@xeonr/upload-pool-sdk 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# @xeonr/upload-pool-sdk
+
+Self-hosted worker SDK for the upl.im content type pipeline. Implement a handler per content type URN; the SDK handles SSE connection, job acceptance, presigned thumbnail upload, and metadata callbacks.
+
+## Install
+
+```sh
+npm install @xeonr/upload-pool-sdk
+```
+
+Requires Node 20+.
+
+## Usage
+
+```ts
+import { createPool, NonRetryableError } from "@xeonr/upload-pool-sdk";
+
+await createPool({
+  token: process.env.UPL_POOL_TOKEN!,         // tpq_... from the pool's creation response
+  endpoint: process.env.UPL_API_URL!,
+  concurrency: 4,
+  handlers: {
+    "my-integration:invoice": async (ctx) => {
+      const buf = await ctx.downloadBuffer();
+      const thumb = await renderInvoiceThumbnail(buf);
+
+      await ctx.uploadMeta({ type: "THUMBNAIL_LIGHT", data: thumb });
+      await ctx.setMetadata({ thumbnailGenerationVersion: 3 });
+    },
+  },
+  onError(err, ctx) {
+    console.error(`job ${ctx?.jobId} (${ctx?.contentType.urn}) failed:`, err);
+  },
+}).start();
+```
+
+The SDK advertises the URNs you register handlers for as `?capabilities=...` on the SSE connect URL, so the pipeline only dispatches matching jobs to this worker process.
+
+## Concepts
+
+### Pool token
+
+The opaque `tpq_…` token authenticates the SSE connection. Mint one via the integration admin UI; the token is shown once at creation. Store it as a deployment secret.
+
+### Per-job update token
+
+Embedded in every job envelope as `updateToken`. It's the existing 24h JWT scoped to the upload (`subject = uploadId`, `audience = internal-uploads-endpoint`) and authenticates the four `InternalUploadsService` callbacks the SDK makes on your behalf — `RequestMetaUpload`, `ConfirmMetaUpload`, `UpdateUpload`, `GetProcessingContext`. You never see it directly; the SDK uses it internally.
+
+### Handler contract
+
+Handlers are keyed by content type URN (e.g. `default:image`, `my-integration:invoice`). On dispatch, the SDK:
+
+1. Calls `AcceptJob` to clear the pipeline's accept-timeout.
+2. Invokes your handler with a `ctx` providing source download + thumbnail upload + metadata callbacks.
+3. On clean resolve, calls `CompleteJob`. On throw, calls `ReportError` with `retry=true`.
+4. Throw `NonRetryableError` to signal permanent failure (the pipeline won't requeue).
+
+## API
+
+### `createPool(config: PoolConfig): Pool`
+
+See [`src/types.ts`](./src/types.ts) for the full `PoolConfig`, `JobContext`, and `UploadMetaOpts` types.
+
+| `ctx` method        | What it does                                                  |
+|---------------------|---------------------------------------------------------------|
+| `download()`        | Stream the source file from the presigned URL.                |
+| `downloadBuffer()`  | Buffer the entire source file in memory.                      |
+| `downloadToFile()`  | Stream to a local path on disk.                               |
+| `uploadMeta()`      | RequestMetaUpload → S3 PUT → ConfirmMetaUpload (atomic).      |
+| `setMetadata()`     | Write upload-row metadata (dimensions, duration, page count). |
+| `setDescription()`  | Write AI description + tags via UpdateUpload.                 |
+
+## Reference example
+
+See [`examples/noop-worker.ts`](./examples/noop-worker.ts) — a 35-line worker that echoes source bytes back as both thumbnail variants. Useful for integration testing.
+
+## Build
+
+```sh
+npm run build           # tsc → dist/
+npm run build:check     # type-check only
+npm run test            # vitest
+```

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Throw NonRetryableError from a JobHandler to signal the pipeline that
+ * the job has failed permanently and should NOT be requeued. The SDK
+ * calls IntegrationQueueService.ReportError with retry=false.
+ *
+ * Use this for: malformed input, permission errors, content-type-specific
+ * unsupported variants. Plain Error throws are retried (the default).
+ */
+export declare class NonRetryableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI1D"}

package/dist/errors.js

@@ -0,0 +1,15 @@
+/**
+ * Throw NonRetryableError from a JobHandler to signal the pipeline that
+ * the job has failed permanently and should NOT be requeued. The SDK
+ * calls IntegrationQueueService.ReportError with retry=false.
+ *
+ * Use this for: malformed input, permission errors, content-type-specific
+ * unsupported variants. Plain Error throws are retried (the default).
+ */
+export class NonRetryableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "NonRetryableError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3C,YAAY,OAAe,EAAE,OAA6B;QACzD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACjC,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @xeonr/upload-pool-sdk — self-hosted worker SDK for the upl.im content
+ * type pipeline.
+ *
+ * Minimum viable worker:
+ *
+ *   import { createPool } from "@xeonr/upload-pool-sdk";
+ *
+ *   await createPool({
+ *     token: process.env.UPL_POOL_TOKEN!,
+ *     endpoint: process.env.UPL_API_URL!,
+ *     handlers: {
+ *       "my-integration:invoice": async (ctx) => {
+ *         const buf = await ctx.downloadBuffer();
+ *         const thumb = await renderInvoiceThumbnail(buf);
+ *         await ctx.uploadMeta({ type: "THUMBNAIL_LIGHT", data: thumb });
+ *       },
+ *     },
+ *   }).start();
+ */
+import { Pool } from "./pool.js";
+import type { PoolConfig } from "./types.js";
+export { Pool } from "./pool.js";
+export { NonRetryableError } from "./errors.js";
+export type { PoolConfig, JobContext, JobHandler, UploadMetaOpts, UploadMetadataPartial, UploadMetadataProto, FolderContext, PoolLifecycleEvents, PresignedUploadRequest, MetaUploadHandle, } from "./types.js";
+export declare function createPool(config: PoolConfig): Pool;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAEnD"}

package/dist/index.js

@@ -0,0 +1,27 @@
+/**
+ * @xeonr/upload-pool-sdk — self-hosted worker SDK for the upl.im content
+ * type pipeline.
+ *
+ * Minimum viable worker:
+ *
+ *   import { createPool } from "@xeonr/upload-pool-sdk";
+ *
+ *   await createPool({
+ *     token: process.env.UPL_POOL_TOKEN!,
+ *     endpoint: process.env.UPL_API_URL!,
+ *     handlers: {
+ *       "my-integration:invoice": async (ctx) => {
+ *         const buf = await ctx.downloadBuffer();
+ *         const thumb = await renderInvoiceThumbnail(buf);
+ *         await ctx.uploadMeta({ type: "THUMBNAIL_LIGHT", data: thumb });
+ *       },
+ *     },
+ *   }).start();
+ */
+import { Pool } from "./pool.js";
+export { Pool } from "./pool.js";
+export { NonRetryableError } from "./errors.js";
+export function createPool(config) {
+    return new Pool(config);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAchD,MAAM,UAAU,UAAU,CAAC,MAAkB;IAC5C,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC"}

package/dist/job-context.d.ts

@@ -0,0 +1,18 @@
+import type { RpcClients } from "./rpc-clients.js";
+import type { FolderContext, JobContext } from "./types.js";
+export interface JobEnvelope {
+    jobId: string;
+    uploadId: string;
+    sourceUrl: string;
+    filename: string;
+    mimeType: string;
+    updateToken: string;
+    contentTypeContext: {
+        urn: string;
+        contentTypeId: string;
+        config?: string;
+    };
+    folderContext?: FolderContext;
+}
+export declare function createJobContext(envelope: JobEnvelope, rpc: RpcClients): JobContext;
+//# sourceMappingURL=job-context.d.ts.map

package/dist/job-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-context.d.ts","sourceRoot":"","sources":["../src/job-context.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EACX,aAAa,EACb,UAAU,EAKV,MAAM,YAAY,CAAC;AAYpB,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,aAAa,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,UAAU,GACb,UAAU,CA6KZ"}

package/dist/job-context.js

@@ -0,0 +1,176 @@
+/**
+ * JobContext implementation. Wraps the four InternalUploadsService RPCs
+ * + the source download with ergonomic helpers handlers actually want.
+ *
+ * All mutations are scoped to a single upload by the per-job update_token
+ * embedded in the job envelope.
+ */
+import { writeFile } from "node:fs/promises";
+import { create } from "@bufbuild/protobuf";
+import { ConfirmMetaUploadRequestSchema, InternalUpdateUploadRequestSchema, InternalUpdateUploadRequest_AiMetadataSchema, MetaTypeSchema, MetaUploadType, RequestMetaUploadRequestSchema, } from "./protocol/uplim/api/v1/uploads_pb.js";
+import { UploadMetadataSchema } from "./protocol/uplim/api/v1/metadata_pb.js";
+const META_TYPE_MAP = {
+    THUMBNAIL_LIGHT: MetaUploadType.MetaUploadType_THUMBNAIL_LIGHT,
+    THUMBNAIL_DARK: MetaUploadType.MetaUploadType_THUMBNAIL_DARK,
+    VIDEO_TIMELINE: MetaUploadType.MetaUploadType_VIDEO_TIMELINE_N,
+    ARCHIVE_FILE: MetaUploadType.MetaUploadType_ARCHIVE_FILE,
+    IMAGE_COMPAT: MetaUploadType.MetaUploadType_IMAGE_COMPAT,
+    AI_CONTENT: MetaUploadType.MetaUploadType_AI_CONTENT,
+    RENDERER_CONFIG: MetaUploadType.MetaUploadType_RENDERER_CONFIG,
+};
+export function createJobContext(envelope, rpc) {
+    const ctx = {
+        jobId: envelope.jobId,
+        uploadId: envelope.uploadId,
+        filename: envelope.filename,
+        mimeType: envelope.mimeType,
+        contentType: {
+            urn: envelope.contentTypeContext.urn,
+            id: envelope.contentTypeContext.contentTypeId,
+            config: envelope.contentTypeContext.config
+                ? Buffer.from(envelope.contentTypeContext.config, "base64")
+                : new Uint8Array(),
+        },
+        folderContext: envelope.folderContext,
+        sourceUrl: envelope.sourceUrl,
+        async download() {
+            const resp = await fetch(envelope.sourceUrl);
+            if (!resp.ok || !resp.body) {
+                throw new Error(`source download failed: ${resp.status} ${resp.statusText}`);
+            }
+            return resp.body;
+        },
+        async downloadBuffer() {
+            const resp = await fetch(envelope.sourceUrl);
+            if (!resp.ok) {
+                throw new Error(`source download failed: ${resp.status} ${resp.statusText}`);
+            }
+            const buf = await resp.arrayBuffer();
+            return new Uint8Array(buf);
+        },
+        async downloadToFile(path) {
+            const data = await ctx.downloadBuffer();
+            await writeFile(path, data);
+        },
+        async uploadMeta(opts) {
+            const protoType = META_TYPE_MAP[opts.type];
+            const metaType = create(MetaTypeSchema, {
+                type: protoType,
+                n: opts.instance,
+                filename: opts.filename,
+            });
+            // 1. RequestMetaUpload → presigned URL.
+            const requested = await rpc.internalUploads.requestMetaUpload(create(RequestMetaUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                metaType: [metaType],
+            }));
+            const meta = requested.metaUploads[0];
+            if (!meta) {
+                throw new Error("RequestMetaUpload returned no meta_uploads");
+            }
+            // 2. S3 PUT.
+            const contentType = opts.contentType ?? inferContentType(opts.type);
+            const body = opts.data instanceof Uint8Array
+                ? opts.data
+                : opts.data;
+            const putResp = await fetch(meta.uploadUrl, {
+                method: "PUT",
+                body: body,
+                headers: { "Content-Type": contentType },
+                duplex: "half",
+            });
+            if (!putResp.ok) {
+                throw new Error(`meta upload PUT failed: ${putResp.status} ${putResp.statusText}`);
+            }
+            // 3. ConfirmMetaUpload.
+            await rpc.internalUploads.confirmMetaUpload(create(ConfirmMetaUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                metadataId: [meta.metadataId],
+            }));
+        },
+        async setMetadata(metadata) {
+            // Distinguish a pre-built proto from a partial: protos carry the
+            // @bufbuild/protobuf $typeName brand.
+            const isProto = metadata.$typeName !== undefined;
+            let protoMetadata;
+            let thumbnailVersion;
+            if (isProto) {
+                protoMetadata = metadata;
+            }
+            else {
+                const partial = metadata;
+                protoMetadata = create(UploadMetadataSchema, {});
+                // Server-side proto has typed sub-messages; the SDK's
+                // UploadMetadataPartial is intentionally loose so workers can
+                // populate just what they computed. Cast into the proto via
+                // the JSON path — fields that don't map are ignored.
+                Object.assign(protoMetadata, partial);
+                thumbnailVersion = partial.thumbnailGenerationVersion;
+            }
+            await rpc.internalUploads.updateUpload(create(InternalUpdateUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                metadata: protoMetadata,
+                thumbnailGenerationVersion: thumbnailVersion,
+            }));
+        },
+        async markHasThumbnail(version) {
+            await rpc.internalUploads.updateUpload(create(InternalUpdateUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                hasThumbnail: true,
+                thumbnailGenerationVersion: version,
+            }));
+        },
+        async setDescription(text, tags) {
+            await rpc.internalUploads.updateUpload(create(InternalUpdateUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                aiMetadata: create(InternalUpdateUploadRequest_AiMetadataSchema, {
+                    description: text,
+                    generatedTags: tags ?? [],
+                }),
+            }));
+        },
+        async withPresignedUploads(opts, callback) {
+            const metaTypes = opts.map((opt) => create(MetaTypeSchema, {
+                type: META_TYPE_MAP[opt.type],
+                n: opt.instance,
+                filename: opt.filename,
+            }));
+            const requested = await rpc.internalUploads.requestMetaUpload(create(RequestMetaUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                metaType: metaTypes,
+            }));
+            if (requested.metaUploads.length !== opts.length) {
+                throw new Error(`RequestMetaUpload returned ${requested.metaUploads.length} URLs, expected ${opts.length}`);
+            }
+            const handles = requested.metaUploads.map((m) => ({
+                uploadUrl: m.uploadUrl,
+                downloadUrl: m.downloadUrl,
+                metadataId: m.metadataId,
+            }));
+            const result = await callback(handles);
+            // Confirm only after the callback resolves cleanly — on throw,
+            // the rows stay unfinalised and will be cleaned up by the next
+            // confirm sweep or expire naturally.
+            await rpc.internalUploads.confirmMetaUpload(create(ConfirmMetaUploadRequestSchema, {
+                updateToken: envelope.updateToken,
+                metadataId: requested.metaUploads.map((m) => m.metadataId),
+            }));
+            return result;
+        },
+    };
+    return ctx;
+}
+function inferContentType(metaType) {
+    switch (metaType) {
+        case "THUMBNAIL_LIGHT":
+        case "THUMBNAIL_DARK":
+        case "VIDEO_TIMELINE":
+        case "IMAGE_COMPAT":
+            return "image/png";
+        case "ARCHIVE_FILE":
+        case "AI_CONTENT":
+        case "RENDERER_CONFIG":
+            return "application/octet-stream";
+    }
+}
+//# sourceMappingURL=job-context.js.map

package/dist/job-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-context.js","sourceRoot":"","sources":["../src/job-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EACN,8BAA8B,EAC9B,iCAAiC,EACjC,4CAA4C,EAC5C,cAAc,EACd,cAAc,EACd,8BAA8B,GAC9B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AAW9E,MAAM,aAAa,GAAmD;IACrE,eAAe,EAAE,cAAc,CAAC,8BAA8B;IAC9D,cAAc,EAAE,cAAc,CAAC,6BAA6B;IAC5D,cAAc,EAAE,cAAc,CAAC,+BAA+B;IAC9D,YAAY,EAAE,cAAc,CAAC,2BAA2B;IACxD,YAAY,EAAE,cAAc,CAAC,2BAA2B;IACxD,UAAU,EAAE,cAAc,CAAC,yBAAyB;IACpD,eAAe,EAAE,cAAc,CAAC,8BAA8B;CAC9D,CAAC;AAiBF,MAAM,UAAU,gBAAgB,CAC/B,QAAqB,EACrB,GAAe;IAEf,MAAM,GAAG,GAAe;QACvB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,WAAW,EAAE;YACZ,GAAG,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG;YACpC,EAAE,EAAE,QAAQ,CAAC,kBAAkB,CAAC,aAAa;YAC7C,MAAM,EAAE,QAAQ,CAAC,kBAAkB,CAAC,MAAM;gBACzC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC;gBAC3D,CAAC,CAAC,IAAI,UAAU,EAAE;SACnB;QACD,aAAa,EAAE,QAAQ,CAAC,aAAa;QACrC,SAAS,EAAE,QAAQ,CAAC,SAAS;QAE7B,KAAK,CAAC,QAAQ;YACb,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAC9E,CAAC;YACD,OAAO,IAAI,CAAC,IAAI,CAAC;QAClB,CAAC;QAED,KAAK,CAAC,cAAc;YACnB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAC9E,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;YACrC,OAAO,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAED,KAAK,CAAC,cAAc,CAAC,IAAY;YAChC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,cAAc,EAAE,CAAC;YACxC,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC7B,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,IAAoB;YACpC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,EAAE;gBACvC,IAAI,EAAE,SAAS;gBACf,CAAC,EAAE,IAAI,CAAC,QAAQ;gBAChB,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACvB,CAAC,CAAC;YAEH,wCAAwC;YACxC,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,iBAAiB,CAC5D,MAAM,CAAC,8BAA8B,EAAE;gBACtC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,QAAQ,EAAE,CAAC,QAAQ,CAAC;aACpB,CAAC,CACF,CAAC;YAEF,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YACtC,IAAI,CAAC,IAAI,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAC/D,CAAC;YAED,aAAa;YACb,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,YAAY,UAAU;gBAC3C,CAAC,CAAC,IAAI,CAAC,IAAI;gBACX,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACb,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE;gBAC3C,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,IAAgB;gBACtB,OAAO,EAAE,EAAE,cAAc,EAAE,WAAW,EAAE;gBACxC,MAAM,EAAE,MAAM;aACuB,CAAC,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,2BAA2B,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;YACpF,CAAC;YAED,wBAAwB;YACxB,MAAM,GAAG,CAAC,eAAe,CAAC,iBAAiB,CAC1C,MAAM,CAAC,8BAA8B,EAAE;gBACtC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,UAAU,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC;aAC7B,CAAC,CACF,CAAC;QACH,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,QAAqD;YACtE,iEAAiE;YACjE,sCAAsC;YACtC,MAAM,OAAO,GAAI,QAAgC,CAAC,SAAS,KAAK,SAAS,CAAC;YAC1E,IAAI,aAAqE,CAAC;YAC1E,IAAI,gBAAoC,CAAC;YACzC,IAAI,OAAO,EAAE,CAAC;gBACb,aAAa,GAAG,QAAkE,CAAC;YACpF,CAAC;iBAAM,CAAC;gBACP,MAAM,OAAO,GAAG,QAAiC,CAAC;gBAClD,aAAa,GAAG,MAAM,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;gBACjD,sDAAsD;gBACtD,8DAA8D;gBAC9D,4DAA4D;gBAC5D,qDAAqD;gBACrD,MAAM,CAAC,MAAM,CAAC,aAAuB,EAAE,OAAO,CAAC,CAAC;gBAChD,gBAAgB,GAAG,OAAO,CAAC,0BAA0B,CAAC;YACvD,CAAC;YAED,MAAM,GAAG,CAAC,eAAe,CAAC,YAAY,CACrC,MAAM,CAAC,iCAAiC,EAAE;gBACzC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,QAAQ,EAAE,aAAa;gBACvB,0BAA0B,EAAE,gBAAgB;aAC5C,CAAC,CACF,CAAC;QACH,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,OAAe;YACrC,MAAM,GAAG,CAAC,eAAe,CAAC,YAAY,CACrC,MAAM,CAAC,iCAAiC,EAAE;gBACzC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,YAAY,EAAE,IAAI;gBAClB,0BAA0B,EAAE,OAAO;aACnC,CAAC,CACF,CAAC;QACH,CAAC;QAED,KAAK,CAAC,cAAc,CAAC,IAAY,EAAE,IAAe;YACjD,MAAM,GAAG,CAAC,eAAe,CAAC,YAAY,CACrC,MAAM,CAAC,iCAAiC,EAAE;gBACzC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,UAAU,EAAE,MAAM,CAAC,4CAA4C,EAAE;oBAChE,WAAW,EAAE,IAAI;oBACjB,aAAa,EAAE,IAAI,IAAI,EAAE;iBACzB,CAAC;aACF,CAAC,CACF,CAAC;QACH,CAAC;QAED,KAAK,CAAC,oBAAoB,CACzB,IAA8B,EAC9B,QAA0E;YAE1E,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,EAAE;gBAC1D,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC;gBAC7B,CAAC,EAAE,GAAG,CAAC,QAAQ;gBACf,QAAQ,EAAE,GAAG,CAAC,QAAQ;aACtB,CAAC,CAAC,CAAC;YACJ,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,eAAe,CAAC,iBAAiB,CAC5D,MAAM,CAAC,8BAA8B,EAAE;gBACtC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,QAAQ,EAAE,SAAS;aACnB,CAAC,CACF,CAAC;YACF,IAAI,SAAS,CAAC,WAAW,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;gBAClD,MAAM,IAAI,KAAK,CACd,8BAA8B,SAAS,CAAC,WAAW,CAAC,MAAM,mBAAmB,IAAI,CAAC,MAAM,EAAE,CAC1F,CAAC;YACH,CAAC;YACD,MAAM,OAAO,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACjD,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;aACxB,CAAC,CAAC,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;YACvC,+DAA+D;YAC/D,+DAA+D;YAC/D,qCAAqC;YACrC,MAAM,GAAG,CAAC,eAAe,CAAC,iBAAiB,CAC1C,MAAM,CAAC,8BAA8B,EAAE;gBACtC,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,UAAU,EAAE,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;aAC1D,CAAC,CACF,CAAC;YACF,OAAO,MAAM,CAAC;QACf,CAAC;KACD,CAAC;IAEF,OAAO,GAAG,CAAC;AACZ,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgC;IACzD,QAAQ,QAAQ,EAAE,CAAC;QAClB,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,gBAAgB,CAAC;QACtB,KAAK,cAAc;YAClB,OAAO,WAAW,CAAC;QACpB,KAAK,cAAc,CAAC;QACpB,KAAK,YAAY,CAAC;QAClB,KAAK,iBAAiB;YACrB,OAAO,0BAA0B,CAAC;IACpC,CAAC;AACF,CAAC"}

package/dist/pool.d.ts

@@ -0,0 +1,16 @@
+import type { PoolConfig } from "./types.js";
+export declare class Pool {
+    private readonly config;
+    private readonly rpc;
+    private readonly sse;
+    private inFlight;
+    private readonly workerId;
+    private readonly capabilities;
+    constructor(config: PoolConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private handleDispatch;
+    private resolveHandler;
+    private reportError;
+}
+//# sourceMappingURL=pool.d.ts.map

package/dist/pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAGX,UAAU,EACV,MAAM,YAAY,CAAC;AAEpB,qBAAa,IAAI;IAChB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;gBAE5B,MAAM,EAAE,UAAU;IAwBxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,cAAc;IA+C5B,OAAO,CAAC,cAAc;YAIR,WAAW;CAqBzB"}

package/dist/pool.js

@@ -0,0 +1,111 @@
+/**
+ * Pool: the SDK's top-level lifecycle object. Maintains an SSE connection
+ * to the pool's job stream, dispatches job:dispatch events to the right
+ * handler keyed by content type URN, and orchestrates accept/complete/
+ * report-error against IntegrationQueueService.
+ */
+import { hostname } from "node:os";
+import { randomBytes } from "node:crypto";
+import { create } from "@bufbuild/protobuf";
+import { AcceptJobRequestSchema, CompleteJobRequestSchema, ReportErrorRequestSchema, } from "./protocol/uplim/workflow/v1/integration_queue_pb.js";
+import { createRpcClients } from "./rpc-clients.js";
+import { SseClient } from "./sse-client.js";
+import { createJobContext } from "./job-context.js";
+import { NonRetryableError } from "./errors.js";
+export class Pool {
+    config;
+    rpc;
+    sse;
+    inFlight = 0;
+    workerId;
+    capabilities;
+    constructor(config) {
+        this.config = {
+            concurrency: 1,
+            onError: defaultErrorHandler,
+            ...config,
+        };
+        this.workerId = config.workerId ?? `${hostname()}-${randomBytes(4).toString("hex")}`;
+        this.capabilities = Object.keys(config.handlers);
+        this.rpc = createRpcClients(config.endpoint);
+        this.sse = new SseClient({
+            endpoint: config.endpoint,
+            token: config.token,
+            workerId: this.workerId,
+            capabilities: this.capabilities,
+            onConnected: () => {
+                /* lifecycle: future event emitter hook */
+            },
+            onDisconnected: () => {
+                /* lifecycle: future event emitter hook */
+            },
+            onJobDispatch: (payload) => this.handleDispatch(payload),
+        });
+    }
+    async start() {
+        this.sse.start();
+    }
+    async stop() {
+        this.sse.stop();
+    }
+    async handleDispatch(envelope) {
+        if (this.inFlight >= (this.config.concurrency ?? 1)) {
+            // Pipeline only dispatches to idle workers (zero in-flight), so
+            // this branch is defensive — if it ever fires we silently
+            // drop the dispatch and let the pipeline timeout requeue.
+            return;
+        }
+        this.inFlight++;
+        const handler = this.resolveHandler(envelope.contentTypeContext.urn);
+        const ctx = createJobContext(envelope, this.rpc);
+        try {
+            // AcceptJob — clears the pipeline's accept-timeout.
+            await this.rpc.integrationQueue.acceptJob(create(AcceptJobRequestSchema, {
+                jobId: envelope.jobId,
+                workerId: this.workerId,
+                queueToken: this.config.token,
+            }));
+            if (!handler) {
+                await this.reportError(envelope.jobId, ctx, new NonRetryableError(`no handler for URN ${envelope.contentTypeContext.urn}`));
+                return;
+            }
+            await handler(ctx);
+            await this.rpc.integrationQueue.completeJob(create(CompleteJobRequestSchema, {
+                jobId: envelope.jobId,
+                workerId: this.workerId,
+                queueToken: this.config.token,
+            }));
+        }
+        catch (err) {
+            await this.reportError(envelope.jobId, ctx, err);
+        }
+        finally {
+            this.inFlight--;
+        }
+    }
+    resolveHandler(urn) {
+        return this.config.handlers[urn] ?? this.config.onUnhandled;
+    }
+    async reportError(jobId, ctx, err) {
+        const retry = !(err instanceof NonRetryableError);
+        this.config.onError?.(err, ctx);
+        try {
+            await this.rpc.integrationQueue.reportError(create(ReportErrorRequestSchema, {
+                jobId,
+                workerId: this.workerId,
+                queueToken: this.config.token,
+                error: err.message,
+                retry,
+            }));
+        }
+        catch (rptErr) {
+            this.config.onError?.(rptErr, ctx);
+        }
+    }
+}
+function defaultErrorHandler(err, ctx) {
+    const where = ctx ? `job ${ctx.jobId} (${ctx.contentType.urn})` : "pool";
+    // eslint-disable-next-line no-console
+    console.error(`[@xeonr/upload-pool-sdk] ${where}: ${err.message}`);
+}
+//# sourceMappingURL=pool.js.map

package/dist/pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.js","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"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"}