App Worker SDK

@lombokapp/app-worker-sdk is the backend-side SDK that Lombok app workers use at runtime. A worker is the code that actually runs when one of your app’s tasks fires or when an HTTP request is routed to your app. The SDK gives that code:

• a platform client (IAppPlatformService) for talking back to Lombok — emitting events, reading/writing files via signed URLs, triggering tasks, reporting progress, minting user tokens, managing triggers, and running container jobs
• database access to the app’s own Postgres database, including a Drizzle-compatible client with automatic credential rotation
• handler types (TaskHandler, RequestHandler) that define the shape of the functions you export from a worker
• small helpers for file hashing and for verifying app-issued JWTs

The platform client communicates with Lombok over a Socket.IO connection using a single APP_API request/ack channel. You normally don’t construct any of this yourself — the worker runtime builds the client and database access for you and passes them into your handler. This page documents the surface so you know what those objects can do.

Package

@lombokapp/app-worker-sdk

Entry points

Import	Contents
@lombokapp/app-worker-sdk	Main surface: platform client, DB client, handler types, helpers
@lombokapp/app-worker-sdk/drizzle	Re-export of drizzle-orm and drizzle-orm/node-postgres
@lombokapp/app-worker-sdk/drizzle-pg-core	Re-export of drizzle-orm/pg-core

The main entry re-exports the platform/DB client, file-hashing utilities, AppTaskError, and token verification helpers.

Where this fits

Your app manifest declares what can run — its triggers, tasks, and runtime workers. The App Worker SDK is the code-level surface those workers use once execution actually happens.

A worker module exports one or both of:

• handleTask — a TaskHandler
• handleRequest — a RequestHandler

The runtime injects a serverClient, a dbClient, and a createDb factory into every handler call.

Handlers

TaskHandler

type TaskHandler = (
  task: TaskDTO,
  ctx: {
    serverClient: IAppPlatformService
    dbClient: LombokAppPgClient
    createDb: CreateDbFn
  },
) => Promise<undefined> | undefined

Receives the full TaskDTO for the task being run plus the runtime context. Return to mark the task complete; throw to fail it. Throw an AppTaskError to attach a structured code/details payload or to request a requeue with a delay.

RequestHandler

type RequestHandler = (
  request: Request,
  ctx: {
    serverClient: IAppPlatformService
    dbClient: LombokAppPgClient
    createDb: CreateDbFn
    actor: WorkerApiActor | undefined
  },
) => Promise<Response> | Response

Receives a standard web Request and returns a standard Response. In addition to the shared runtime context, request handlers get an actor describing who made the call.

Platform client — IAppPlatformService

The platform client is the worker’s connection back to Lombok. You receive it as serverClient in every handler. It is created by buildAppClient.

Response shape

Every platform method returns a promise of a discriminated result object:

{ result: <method-specific payload> }
{ error: { code: string | number; message: string; details?: Record<string, unknown> } }

Methods do not reject on platform-level errors — they resolve with an error object instead.

Per-call options

Every method takes an optional final argument:

interface PlatformApiExecuteOptions {
  timeoutMs?: number
}

Method groups

Events & logging

Method	Purpose
emitEvent(params)	Emit an app event
saveLogEntry(entry)	Persist an app log entry

Storage & metadata

Method	Purpose
getContentSignedUrls(requests)	Signed URLs for content objects
getMetadataSignedUrls(requests)	Signed URLs for metadata blobs
getAppStorageSignedUrls(requests)	Signed URLs in app-private storage
updateContentMetadata(updates)	Write metadata entries for content objects

Tasks

Method	Purpose
getAppTask({ taskId, targetUserId? })	Fetch a task as a TaskDTO
triggerAppTask(params)	Enqueue a task
reportTaskProgress({ taskId, progressReport })	Report task progress

App settings

Method	Purpose
getAppCustomSettings({ userId })	Read per-user custom settings
patchAppCustomSettings({ userId, values })	Merge-update per-user custom settings

Tokens

Method	Purpose
mintAppUserToken({ userId, platformAccess?, extra? })	Mint an app-user token pair

Database credentials

Method	Purpose
getLatestDbCredentials()	Current Postgres credentials for the app database

Container jobs & containers

Method	Purpose
executeAppDockerJob(params)	Submit a Docker-backed job and wait
executeAppDockerJobAsync(params)	Submit a Docker-backed job asynchronously
destroyAppDockerContainers(params)	Tear down containers
resolveAppDockerContainer(params)	Resolve a live container
inspectAppDockerContainer(params)	Inspect container state
startAppDockerContainer(params)	Start a stopped container

Bridge tunnels

Method	Purpose
createBridgeTunnel(params)	Open a tunnel to a container command
deleteBridgeTunnel({ sessionId })	Close a tunnel

Triggers

Method	Purpose
registerAppTrigger({ trigger })	Register an event or schedule trigger
unregisterAppTrigger({ triggerId })	Remove a trigger
listAppTriggers({ kind? })	List triggers

Misc

Method	Purpose
getServerBaseUrl()	The platform base URL the client was built with

buildAppClient

function buildAppClient(
  socket: Socket,
  serverBaseUrl: string,
  defaultTimeoutMs?: number,
): IAppPlatformService

Builds an IAppPlatformService over a connected Socket.IO client. Each method serializes its name + data, sends an APP_API message with an acknowledgement, validates the response, and returns the { result } | { error } shape.

AppAPIError

class AppAPIError extends Error {
  errorCode: string | number
  details?: Record<string, unknown>
}

A throwable error carrying a structured errorCode and optional details.

Database access

A Lombok app gets its own Postgres database. The SDK provides a pooled client that fetches credentials from the platform and rotates them automatically when they expire.

LombokAppPgClient

class LombokAppPgClient {
  constructor(server: IAppPlatformService)
  query(text: string, params?: unknown[]): Promise<pg.QueryResult>
  connect(): Promise<pg.PoolClient>
  end(): Promise<void>
}

Key behaviors:

• credentials are fetched lazily on first use via getLatestDbCredentials()
• if a query fails with Postgres auth error 28P01, the client refreshes credentials, rebuilds the pool, and retries once
• connect() hands out a pooled client suitable for transactions

createLombokAppPgDatabase & createDb

function createLombokAppPgDatabase<TDb>(
  server: IAppPlatformService,
  schema: TDb,
): NodePgDatabase<TDb>

type CreateDbFn = <T>(schema: T) => NodePgDatabase<T>

Inside a handler you typically use the pre-bound createDb factory passed in the runtime context rather than constructing the database directly.

Errors

AppTaskError

class AppTaskError extends Error {
  constructor(
    code: string,
    message: string,
    details?: Record<string, unknown>,
    requeueDelayMs?: number,
    cause?: AppTaskError,
  )
}

Structured error to throw from a TaskHandler, including optional requeue delay.

Token verification

verifyAppToken

function verifyAppToken(
  token: string,
  options: { publicKeyPem: string },
): Promise<AppJwtClaims>

Verifies an EdDSA-signed app JWT against the supplied public key. The returned AppJwtClaims is a discriminated union on actorType:

• app
• app_user

Utilities

function hashFileStream(stream: fs.ReadStream): Promise<string>
function hashLocalFile(filepath: string): Promise<string>

Both helpers compute SHA-1 hashes and return hex strings.

TaskDTO shape

The object passed to a TaskHandler and returned by getAppTask. Key fields include:

• id
• taskIdentifier
• ownerId
• invocation
• data
• targetLocation
• progress / progressReports
• result
• success / error
• timestamps
• systemLog / taskLog

See @lombokapp/types for the exact authoritative schema.

Next steps

• App Platform Overview
• Events & Tasks
• Workers
• App Browser SDK
• Core SDK