@xeonr/upload-pool-sdk 1.0.0 → 1.2.0

package/dist/rpc-clients.js

@@ -1,24 +1,70 @@
 /**
  * ConnectRPC clients for the two services the SDK talks to:
- *   - InternalUploadsService — per-upload callbacks (UpdateUpload,
- *     RequestMetaUpload, ConfirmMetaUpload, GetProcessingContext).
- *     Auth: the per-job update_token from the job envelope, passed
- *     as the in-band `updateToken` field on each request.
- *   - IntegrationQueueService — accept / complete / report-error.
- *     Auth: the pool token, passed as `queueToken` on each request.
+ *   - InternalUploadsService (`apiEndpoint`) — per-upload callbacks
+ *     (UpdateUpload, RequestMetaUpload, ConfirmMetaUpload,
+ *     GetProcessingContext). Auth: the per-job `update_token` from the
+ *     job envelope, passed as the in-band `updateToken` field on each
+ *     request.
+ *   - IntegrationQueueService (`pipelineEndpoint`) — accept / complete /
+ *     report-error. Auth: the pool token, passed as `queueToken` on each
+ *     request.
+ *
+ * The two services live on different processes (Go uploads-api vs Node
+ * pipeline-api) so we keep them on separate transports and don't try to
+ * share a baseUrl.
+ *
+ * Each request is wrapped in a logging interceptor that emits one
+ * `rpc.request` line on dispatch and one of `rpc.response` /
+ * `rpc.error` on completion. Latency and connect-error codes are
+ * captured so failed RPCs are diagnosable from worker logs alone.
  */
 import { createConnectTransport } from "@connectrpc/connect-node";
-import { createClient } from "@connectrpc/connect";
+import { createClient, ConnectError, Code, } from "@connectrpc/connect";
 import { InternalUploadsService } from "./protocol/uplim/api/v1/uploads_pb.js";
 import { IntegrationQueueService } from "./protocol/uplim/workflow/v1/integration_queue_pb.js";
-export function createRpcClients(endpoint) {
-    const transport = createConnectTransport({
-        baseUrl: endpoint,
+function loggingInterceptor(logger, target) {
+    return (next) => async (req) => {
+        const startedAt = Date.now();
+        const method = `${req.service.typeName}/${req.method.name}`;
+        logger.debug("rpc.request", { method, target });
+        try {
+            const res = await next(req);
+            logger.debug("rpc.response", {
+                method,
+                target,
+                durationMs: Date.now() - startedAt,
+            });
+            return res;
+        }
+        catch (err) {
+            const code = err instanceof ConnectError ? Code[err.code] : undefined;
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error("rpc.error", {
+                method,
+                target,
+                code,
+                message,
+                durationMs: Date.now() - startedAt,
+            });
+            throw err;
+        }
+    };
+}
+export function createRpcClients(config) {
+    const rpcLogger = config.logger.child({ component: "rpc" });
+    const apiTransport = createConnectTransport({
+        baseUrl: config.apiEndpoint,
+        httpVersion: "1.1",
+        interceptors: [loggingInterceptor(rpcLogger, "api")],
+    });
+    const pipelineTransport = createConnectTransport({
+        baseUrl: config.pipelineEndpoint,
         httpVersion: "1.1",
+        interceptors: [loggingInterceptor(rpcLogger, "pipeline")],
     });
     return {
-        internalUploads: createClient(InternalUploadsService, transport),
-        integrationQueue: createClient(IntegrationQueueService, transport),
+        internalUploads: createClient(InternalUploadsService, apiTransport),
+        integrationQueue: createClient(IntegrationQueueService, pipelineTransport),
     };
 }
 //# sourceMappingURL=rpc-clients.js.map

package/dist/rpc-clients.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-clients.js","sourceRoot":"","sources":["../src/rpc-clients.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAe,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sDAAsD,CAAC;AAO/F,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAChD,MAAM,SAAS,GAAG,sBAAsB,CAAC;QACxC,OAAO,EAAE,QAAQ;QACjB,WAAW,EAAE,KAAK;KAClB,CAAC,CAAC;IACH,OAAO;QACN,eAAe,EAAE,YAAY,CAAC,sBAAsB,EAAE,SAAS,CAAC;QAChE,gBAAgB,EAAE,YAAY,CAAC,uBAAuB,EAAE,SAAS,CAAC;KAClE,CAAC;AACH,CAAC"}
+{"version":3,"file":"rpc-clients.js","sourceRoot":"","sources":["../src/rpc-clients.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACN,YAAY,EAGZ,YAAY,EACZ,IAAI,GACJ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,sDAAsD,CAAC;AAQ/F,SAAS,kBAAkB,CAAC,MAAc,EAAE,MAAc;IACzD,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC5D,MAAM,CAAC,KAAK,CAAC,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5B,MAAM,CAAC,KAAK,CAAC,cAAc,EAAE;gBAC5B,MAAM;gBACN,MAAM;gBACN,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aAClC,CAAC,CAAC;YACH,OAAO,GAAG,CAAC;QACZ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,MAAM,IAAI,GACT,GAAG,YAAY,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1D,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE;gBACzB,MAAM;gBACN,MAAM;gBACN,IAAI;gBACJ,OAAO;gBACP,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;aAClC,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACX,CAAC;IACF,CAAC,CAAC;AACH,CAAC;AAQD,MAAM,UAAU,gBAAgB,CAAC,MAAwB;IACxD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;IAE5D,MAAM,YAAY,GAAG,sBAAsB,CAAC;QAC3C,OAAO,EAAE,MAAM,CAAC,WAAW;QAC3B,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC,kBAAkB,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;KACpD,CAAC,CAAC;IACH,MAAM,iBAAiB,GAAG,sBAAsB,CAAC;QAChD,OAAO,EAAE,MAAM,CAAC,gBAAgB;QAChC,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC,kBAAkB,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;KACzD,CAAC,CAAC;IACH,OAAO;QACN,eAAe,EAAE,YAAY,CAAC,sBAAsB,EAAE,YAAY,CAAC;QACnE,gBAAgB,EAAE,YAAY,CAAC,uBAAuB,EAAE,iBAAiB,CAAC;KAC1E,CAAC;AACH,CAAC"}

package/dist/sse-client.d.ts

@@ -1,8 +1,10 @@
+import type { Logger } from "./logger.js";
 export interface SseClientConfig {
     endpoint: string;
     token: string;
     workerId: string;
     capabilities: string[];
+    logger: Logger;
     onConnected: () => void;
     onDisconnected: (reason: string) => void;
     onJobDispatch: (payload: unknown) => void;
@@ -12,6 +14,8 @@ export declare class SseClient {
     private es;
     private stopped;
     private reconnectDelay;
+    private connectAttempt;
+    private connectedAt;
     constructor(config: SseClientConfig);
     start(): void;
     stop(): void;

package/dist/sse-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse-client.d.ts","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAKD,qBAAa,SAAS;IAKT,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAwB;gBAEjB,MAAM,EAAE,eAAe;IAEpD,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI;IAQZ,OAAO,CAAC,OAAO;CAuCf"}
+{"version":3,"file":"sse-client.d.ts","sourceRoot":"","sources":["../src/sse-client.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C;AAKD,qBAAa,SAAS;IAOT,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,OAAO,CAAC,EAAE,CAA4B;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,WAAW,CAAuB;gBAEb,MAAM,EAAE,eAAe;IAEpD,KAAK,IAAI,IAAI;IAKb,IAAI,IAAI,IAAI;IASZ,OAAO,CAAC,OAAO;CA6Ff"}

package/dist/sse-client.js

@@ -5,6 +5,11 @@
  *
  * Reconnect strategy: exponential backoff (1s, 2s, 4s, 8s, capped at 30s).
  * On `job:dispatch` events the SDK invokes the registered onJob callback.
+ *
+ * All lifecycle transitions emit structured logs via the injected
+ * `Logger` so connection failures are visible in the worker's k8s logs
+ * (otherwise a worker that can't connect at all looks identical to one
+ * that's idle).
  */
 import { EventSource } from "eventsource";
 const RECONNECT_INITIAL_MS = 1_000;
@@ -14,6 +19,8 @@ export class SseClient {
     es = null;
     stopped = false;
     reconnectDelay = RECONNECT_INITIAL_MS;
+    connectAttempt = 0;
+    connectedAt = null;
     constructor(config) {
         this.config = config;
     }
@@ -27,35 +34,82 @@ export class SseClient {
             this.es.close();
             this.es = null;
         }
+        this.config.logger.info("sse.stopped");
     }
     connect() {
         if (this.stopped)
             return;
+        this.connectAttempt++;
         const url = new URL(`${this.config.endpoint}/queue/connect`);
         url.searchParams.set("queueToken", this.config.token);
         url.searchParams.set("workerId", this.config.workerId);
         if (this.config.capabilities.length > 0) {
             url.searchParams.set("capabilities", this.config.capabilities.join(","));
         }
+        // Strip the token from the logged URL — the queueToken param is the
+        // pool secret, no reason to bake it into telemetry.
+        const loggedUrl = new URL(url.toString());
+        loggedUrl.searchParams.set("queueToken", "[redacted]");
+        this.config.logger.info("sse.connect.start", {
+            url: loggedUrl.toString(),
+            attempt: this.connectAttempt,
+            capabilities: this.config.capabilities,
+        });
         this.es = new EventSource(url.toString());
+        this.es.addEventListener("open", () => {
+            this.config.logger.debug("sse.open");
+        });
         this.es.addEventListener("connected", () => {
             this.reconnectDelay = RECONNECT_INITIAL_MS;
+            this.connectedAt = Date.now();
+            this.config.logger.info("sse.connect.opened", {
+                attempt: this.connectAttempt,
+            });
             this.config.onConnected();
         });
         this.es.addEventListener("job:dispatch", (event) => {
             try {
                 const data = JSON.parse(event.data);
+                this.config.logger.debug("sse.event.job_dispatch", {
+                    jobId: data.jobId,
+                });
                 this.config.onJobDispatch(data);
             }
             catch (err) {
-                this.config.onDisconnected(`bad job payload: ${err.message}`);
+                const reason = `bad job payload: ${err.message}`;
+                this.config.logger.error("sse.event.parse_error", {
+                    err,
+                    rawData: event.data,
+                });
+                this.config.onDisconnected(reason);
             }
         });
-        // heartbeat events are no-ops — receipt alone keeps the connection alive.
-        this.es.onerror = () => {
+        // heartbeat events are no-ops at the dispatch layer — receipt alone
+        // keeps the connection alive. We log at debug so noisy keep-alive
+        // traffic doesn't drown the info stream.
+        this.es.addEventListener("heartbeat", () => {
+            this.config.logger.debug("sse.event.heartbeat");
+        });
+        this.es.onerror = (err) => {
             if (this.stopped)
                 return;
-            this.config.onDisconnected("sse error");
+            const errMessage = err?.message ??
+                err?.type ??
+                "unknown";
+            const status = err?.status ??
+                err?.code;
+            const wasConnected = this.connectedAt !== null;
+            const uptimeMs = wasConnected ? Date.now() - this.connectedAt : null;
+            this.config.logger.warn("sse.disconnected", {
+                message: errMessage,
+                status,
+                wasConnected,
+                uptimeMs,
+                attempt: this.connectAttempt,
+                nextReconnectMs: this.reconnectDelay,
+            });
+            this.config.onDisconnected(`sse error: ${errMessage}`);
+            this.connectedAt = null;
             if (this.es) {
                 this.es.close();
                 this.es = null;

package/dist/sse-client.js.map

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

package/dist/types.d.ts

@@ -16,16 +16,47 @@
 export interface PoolConfig {
     /** Pool token, prefixed with "tpq_". From the pool's creation response. */
     token: string;
-    /** API endpoint base URL, e.g. "https://api.upl.im". */
-    endpoint: string;
+    /**
+     * Public uploads-api base URL, e.g. "https://uploads-api.xeonr.dev".
+     * Hosts `InternalUploadsService` (RequestMetaUpload, ConfirmMetaUpload,
+     * UpdateUpload, GetProcessingContext).
+     *
+     * Use the public https URL even when running inside the same k8s cluster
+     * as the API — keeps third-party workers and first-party workers on a
+     * single code path (TLS, normal ingress, no service-mesh assumptions).
+     */
+    apiEndpoint: string;
+    /**
+     * Public pipeline-api base URL, e.g. "https://uploads-pipeline-api.xeonr.dev".
+     * Hosts the SSE `/queue/connect` endpoint and `IntegrationQueueService`
+     * (AcceptJob, CompleteJob, ReportError).
+     *
+     * Distinct from `apiEndpoint` because the pipeline runs as a separate
+     * Node service; conflating the two would silently route worker traffic
+     * to the wrong process.
+     */
+    pipelineEndpoint: string;
     /** Optional worker identifier. Defaults to hostname + random suffix. */
     workerId?: string;
     /** Handlers keyed by content type URN (e.g. "default:image"). */
     handlers: Record<string, JobHandler>;
     /** Fallback handler if URN has no specific entry in `handlers`. Optional. */
     onUnhandled?: JobHandler;
-    /** Lifecycle / error hook. Defaults to console-based logging. */
+    /**
+     * Lifecycle / error hook. Receives every handler exception alongside
+     * the job context. The SDK also logs every failure via `logger` —
+     * `onError` is for hooks that need to fan out to external systems
+     * (sentry, pagerduty). Optional.
+     */
     onError?: (err: Error, ctx?: JobContext) => void;
+    /**
+     * Structured logger. Defaults to a JSON-line logger that writes to
+     * stdout (`info`/`debug`) and stderr (`warn`/`error`), honoring
+     * `UPL_LOG_LEVEL`. Pass `noopLogger` from this package for silence,
+     * or supply your own implementing the `Logger` interface to bridge
+     * to pino/winston.
+     */
+    logger?: import("./logger.js").Logger;
     /** Max concurrent in-flight jobs. Defaults to 1. */
     concurrency?: number;
 }

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeonr/upload-pool-sdk",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "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.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -8,7 +8,8 @@
  *
  *   await createPool({
  *     token: process.env.UPL_POOL_TOKEN!,
- *     endpoint: process.env.UPL_API_URL!,
+ *     apiEndpoint: process.env.UPL_API_URL!,
+ *     pipelineEndpoint: process.env.UPL_PIPELINE_API_URL!,
  *     handlers: {
  *       "my-integration:invoice": async (ctx) => {
  *         const buf = await ctx.downloadBuffer();
@@ -23,6 +24,8 @@ import type { PoolConfig } from "./types.js";
 
 export { Pool } from "./pool.js";
 export { NonRetryableError } from "./errors.js";
+export { JsonLogger, noopLogger } from "./logger.js";
+export type { Logger, LogLevel } from "./logger.js";
 export type {
 	PoolConfig,
 	JobContext,

package/src/job-context.ts

@@ -17,6 +17,7 @@ import {
 } from "./protocol/uplim/api/v1/uploads_pb.js";
 import { UploadMetadataSchema } from "./protocol/uplim/api/v1/metadata_pb.js";
 import type { RpcClients } from "./rpc-clients.js";
+import type { Logger } from "./logger.js";
 import type {
 	FolderContext,
 	JobContext,
@@ -54,6 +55,7 @@ export interface JobEnvelope {
 export function createJobContext(
 	envelope: JobEnvelope,
 	rpc: RpcClients,
+	logger: Logger,
 ): JobContext {
 	const ctx: JobContext = {
 		jobId: envelope.jobId,
@@ -71,28 +73,45 @@ export function createJobContext(
 		sourceUrl: envelope.sourceUrl,
 
 		async download() {
+			logger.debug("source.download.start");
 			const resp = await fetch(envelope.sourceUrl);
 			if (!resp.ok || !resp.body) {
+				logger.error("source.download.failed", {
+					status: resp.status,
+					statusText: resp.statusText,
+				});
 				throw new Error(`source download failed: ${resp.status} ${resp.statusText}`);
 			}
 			return resp.body;
 		},
 
 		async downloadBuffer() {
+			logger.debug("source.download.start", { mode: "buffer" });
 			const resp = await fetch(envelope.sourceUrl);
 			if (!resp.ok) {
+				logger.error("source.download.failed", {
+					status: resp.status,
+					statusText: resp.statusText,
+				});
 				throw new Error(`source download failed: ${resp.status} ${resp.statusText}`);
 			}
 			const buf = await resp.arrayBuffer();
+			logger.debug("source.download.complete", { sizeBytes: buf.byteLength });
 			return new Uint8Array(buf);
 		},
 
 		async downloadToFile(path: string) {
 			const data = await ctx.downloadBuffer();
 			await writeFile(path, data);
+			logger.debug("source.download.to_file", { path, sizeBytes: data.byteLength });
 		},
 
 		async uploadMeta(opts: UploadMetaOpts) {
+			logger.debug("meta.upload.start", {
+				type: opts.type,
+				instance: opts.instance,
+				filename: opts.filename,
+			});
 			const protoType = META_TYPE_MAP[opts.type];
 			const metaType = create(MetaTypeSchema, {
 				type: protoType,
@@ -135,6 +154,10 @@ export function createJobContext(
 					metadataId: [meta.metadataId],
 				}),
 			);
+			logger.info("meta.upload.complete", {
+				type: opts.type,
+				metadataId: meta.metadataId,
+			});
 		},
 
 		async setMetadata(metadata: UploadMetadataPartial | UploadMetadataProto) {
@@ -163,6 +186,7 @@ export function createJobContext(
 					thumbnailGenerationVersion: thumbnailVersion,
 				}),
 			);
+			logger.debug("metadata.set", { thumbnailVersion });
 		},
 
 		async markHasThumbnail(version: number) {
@@ -173,6 +197,7 @@ export function createJobContext(
 					thumbnailGenerationVersion: version,
 				}),
 			);
+			logger.info("thumbnail.marked", { version });
 		},
 
 		async setDescription(text: string, tags?: string[]) {
@@ -185,12 +210,20 @@ export function createJobContext(
 					}),
 				}),
 			);
+			logger.info("description.set", {
+				length: text.length,
+				tags: tags?.length ?? 0,
+			});
 		},
 
 		async withPresignedUploads<T>(
 			opts: PresignedUploadRequest[],
 			callback: (handles: import("./types.js").MetaUploadHandle[]) => Promise<T>,
 		): Promise<T> {
+			logger.debug("presigned.upload.request", {
+				count: opts.length,
+				types: opts.map((o) => o.type),
+			});
 			const metaTypes = opts.map((opt) => create(MetaTypeSchema, {
 				type: META_TYPE_MAP[opt.type],
 				n: opt.instance,
@@ -222,6 +255,7 @@ export function createJobContext(
 					metadataId: requested.metaUploads.map((m) => m.metadataId),
 				}),
 			);
+			logger.info("presigned.upload.complete", { count: handles.length });
 			return result;
 		},
 	};

package/src/logger.ts

@@ -0,0 +1,159 @@
+/**
+ * Logging interface for the SDK. Customers can plug in their own
+ * logger (pino, winston, console) by passing `logger` to createPool;
+ * by default we emit structured JSON lines to stdout/stderr so logs
+ * are grep-friendly in k8s.
+ *
+ * The shape mirrors the pipeline-api's logger contract for consistency
+ * across the upl.im stack.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+	debug(event: string, context?: Record<string, unknown>): void;
+	info(event: string, context?: Record<string, unknown>): void;
+	warn(event: string, context?: Record<string, unknown>): void;
+	error(event: string, context?: Record<string, unknown>): void;
+	/**
+	 * Return a derived logger that merges these context fields into every
+	 * subsequent log call. Used by Pool.handleDispatch to attach jobId /
+	 * uploadId / urn to every line emitted during the job.
+	 */
+	child(context: Record<string, unknown>): Logger;
+}
+
+const SENSITIVE_KEYS = new Set([
+	"token",
+	"queueToken",
+	"queue_token",
+	"workerToken",
+	"worker_token",
+	"updateToken",
+	"update_token",
+	"authorization",
+	"Authorization",
+]);
+
+/**
+ * Redact obvious secrets so a careless `logger.info("rpc.request", { headers })`
+ * doesn't leak the pool token to log aggregators. Best-effort; not a
+ * substitute for thinking about what you're logging.
+ */
+function redact(value: unknown): unknown {
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const out: Record<string, unknown> = {};
+		for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+			if (SENSITIVE_KEYS.has(k)) {
+				out[k] = typeof v === "string" && v.length > 8
+					? `${v.slice(0, 4)}…(${v.length - 4} redacted)`
+					: "[redacted]";
+			} else if (v && typeof v === "object") {
+				out[k] = redact(v);
+			} else {
+				out[k] = v;
+			}
+		}
+		return out;
+	}
+	if (Array.isArray(value)) return value.map(redact);
+	return value;
+}
+
+function serializeError(err: unknown): Record<string, unknown> {
+	if (err instanceof Error) {
+		return {
+			name: err.name,
+			message: err.message,
+			stack: err.stack,
+			...(err as unknown as Record<string, unknown>),
+		};
+	}
+	return { value: String(err) };
+}
+
+/**
+ * Default JSON logger. Emits one line per call. `error` and `warn` go to
+ * stderr; `info` and `debug` go to stdout. Honors `UPL_LOG_LEVEL` env var
+ * (`debug` | `info` | `warn` | `error`) to filter out noise in prod.
+ */
+export class JsonLogger implements Logger {
+	private readonly base: Record<string, unknown>;
+	private readonly minLevel: LogLevel;
+
+	constructor(base: Record<string, unknown> = {}, minLevel?: LogLevel) {
+		this.base = base;
+		this.minLevel = minLevel ?? (process.env.UPL_LOG_LEVEL as LogLevel) ?? "info";
+	}
+
+	child(context: Record<string, unknown>): Logger {
+		return new JsonLogger({ ...this.base, ...context }, this.minLevel);
+	}
+
+	debug(event: string, context?: Record<string, unknown>): void {
+		this.emit("debug", event, context);
+	}
+	info(event: string, context?: Record<string, unknown>): void {
+		this.emit("info", event, context);
+	}
+	warn(event: string, context?: Record<string, unknown>): void {
+		this.emit("warn", event, context);
+	}
+	error(event: string, context?: Record<string, unknown>): void {
+		this.emit("error", event, context);
+	}
+
+	private shouldEmit(level: LogLevel): boolean {
+		const order: Record<LogLevel, number> = {
+			debug: 10,
+			info: 20,
+			warn: 30,
+			error: 40,
+		};
+		return order[level] >= order[this.minLevel];
+	}
+
+	private emit(
+		level: LogLevel,
+		event: string,
+		context?: Record<string, unknown>,
+	): void {
+		if (!this.shouldEmit(level)) return;
+
+		const merged: Record<string, unknown> = {
+			...this.base,
+			...(context ? (redact(context) as Record<string, unknown>) : {}),
+		};
+		if (merged.err !== undefined) {
+			merged.err = serializeError(merged.err);
+		}
+		if (merged.error !== undefined && merged.error instanceof Error) {
+			merged.error = serializeError(merged.error);
+		}
+
+		const line = JSON.stringify({
+			ts: new Date().toISOString(),
+			level,
+			logger: "@xeonr/upload-pool-sdk",
+			event,
+			...merged,
+		});
+
+		// eslint-disable-next-line no-console
+		(level === "error" || level === "warn" ? console.error : console.log)(line);
+	}
+}
+
+/**
+ * No-op logger for tests or callers who want silence. createPool ignores
+ * this if `logger` is unset and uses JsonLogger by default.
+ */
+export const noopLogger: Logger = {
+	debug() {},
+	info() {},
+	warn() {},
+	error() {},
+	child() {
+		return noopLogger;
+	},
+};