@printwithsynergy/artwork-pdf 0.2.1 → 0.3.0

package/dist/index.d.ts

@@ -1,11 +1,37 @@
+/**
+ * One stage in a synergy workflow.
+ *
+ * `nodeType` is the dotted node identifier the synergy engine routes
+ * on (e.g. `"artwork.render"`). `config` is node-specific — for
+ * artwork.* nodes it's the `JobSubmitRequest` shape from
+ * `@artworkpdf/document-model`; for other node types it follows that
+ * node's own schema. Synergy validates per-node-type at submit time.
+ */
 export type WorkflowStage = {
     nodeType: string;
     config?: Record<string, unknown>;
 };
+/**
+ * Body shape for `POST /api/v1/workflows`.
+ *
+ * `stages` are executed in declaration order; each stage's output
+ * becomes the next stage's input (synergy handles the threading).
+ * `input` seeds the first stage — typically the source document or
+ * asset reference that flows through the pipeline.
+ */
 export type WorkflowSubmitRequest = {
     stages: WorkflowStage[];
     input: Record<string, unknown>;
 };
+/**
+ * Workflow run state, returned by both submit and poll endpoints.
+ *
+ * `status` is the run-level state machine:
+ * `queued → running → done | failed`. Per-stage progress lives in
+ * `stages[]` — each entry's `status` is opaquely-typed since each
+ * node type defines its own stage state vocabulary; consumers
+ * generally only display it or filter on terminal values.
+ */
 export type WorkflowRun = {
     id: string;
     status: "queued" | "running" | "done" | "failed";
@@ -14,10 +40,44 @@ export type WorkflowRun = {
         status: string;
     }>;
 };
+/**
+ * Minimal HTTP client for the synergy engine's workflow API.
+ *
+ * Two methods cover the artwork-pdf use case: submit a workflow,
+ * poll a workflow run. Both authenticate via the `x-api-key`
+ * header; both throw on non-2xx responses with the HTTP status in
+ * the message (the synergy API returns a JSON error body, but this
+ * skeleton client surfaces only the status code — richer error
+ * shapes can land later without breaking the constructor signature).
+ *
+ * **Response-shape trust:** the 2xx JSON is cast directly to
+ * {@link WorkflowRun} without runtime validation. Downstream code
+ * is type-safe relative to the synergy contract, not relative to
+ * arbitrary network bytes — if the engine ships an incompatible
+ * shape, errors surface at the consumer site, not here. Runtime
+ * validation (zod) is a future follow-up.
+ *
+ * The client is stateless apart from `baseUrl` + `apiKey` and is
+ * safe to reuse across requests; instantiate once per process.
+ */
 export declare class SynergyClient {
     #private;
     constructor(baseUrl: string, apiKey: string);
+    /**
+     * `POST /api/v1/workflows` — submit a new workflow run.
+     * Resolves with the initial {@link WorkflowRun} (typically in
+     * `"queued"` state). Throws `Error("synergy error: <status>")` on
+     * non-2xx.
+     */
     submitWorkflow(req: WorkflowSubmitRequest): Promise<WorkflowRun>;
+    /**
+     * `GET /api/v1/workflows/:id` — poll the current state of a
+     * previously-submitted workflow run.
+     *
+     * No long-polling or SSE in this client; callers poll on their
+     * own cadence. Throws `Error("synergy error: <status>")` on
+     * non-2xx (including 404 for unknown ids).
+     */
     getWorkflow(id: string): Promise<WorkflowRun>;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACjD,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD,CAAC;AAEF,qBAAa,aAAa;;gBAIZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAKrC,cAAc,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAahE,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAOpD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACjD,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAa;;gBAIZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK3C;;;;;OAKG;IACG,cAAc,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAatE;;;;;;;OAOG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAOpD"}

package/dist/index.js

@@ -1,4 +1,41 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// `@printwithsynergy/artwork-pdf` — typed HTTP client for the synergy
+// engine's workflow API, scoped to artworkPDF's node usage.
+//
+// The synergy engine orchestrates multi-stage pipelines across
+// disparate node types (`artwork.render`, `artwork.thumbnail`,
+// `artwork.preview-separations` plus equivalents from sibling
+// nodes). artwork-pdf hosts that want to submit synergy workflows
+// (e.g. the marketing site's "submit-for-print" flow) use this
+// client; it is *not* the in-process pg-boss boundary inside
+// `apps/service` — that boundary lives in `apps/service/src/db/boss.ts`
+// and consumes jobs that synergy enqueued.
+//
+// Public surface:
+// - {@link WorkflowStage} / {@link WorkflowSubmitRequest} /
+//   {@link WorkflowRun} — wire shapes for `/api/v1/workflows`.
+// - {@link SynergyClient} — minimal POST/GET client.
+/**
+ * Minimal HTTP client for the synergy engine's workflow API.
+ *
+ * Two methods cover the artwork-pdf use case: submit a workflow,
+ * poll a workflow run. Both authenticate via the `x-api-key`
+ * header; both throw on non-2xx responses with the HTTP status in
+ * the message (the synergy API returns a JSON error body, but this
+ * skeleton client surfaces only the status code — richer error
+ * shapes can land later without breaking the constructor signature).
+ *
+ * **Response-shape trust:** the 2xx JSON is cast directly to
+ * {@link WorkflowRun} without runtime validation. Downstream code
+ * is type-safe relative to the synergy contract, not relative to
+ * arbitrary network bytes — if the engine ships an incompatible
+ * shape, errors surface at the consumer site, not here. Runtime
+ * validation (zod) is a future follow-up.
+ *
+ * The client is stateless apart from `baseUrl` + `apiKey` and is
+ * safe to reuse across requests; instantiate once per process.
+ */
 export class SynergyClient {
     #baseUrl;
     #apiKey;
@@ -6,6 +43,12 @@ export class SynergyClient {
         this.#baseUrl = baseUrl;
         this.#apiKey = apiKey;
     }
+    /**
+     * `POST /api/v1/workflows` — submit a new workflow run.
+     * Resolves with the initial {@link WorkflowRun} (typically in
+     * `"queued"` state). Throws `Error("synergy error: <status>")` on
+     * non-2xx.
+     */
     async submitWorkflow(req) {
         const res = await fetch(`${this.#baseUrl}/api/v1/workflows`, {
             method: "POST",
@@ -19,6 +62,14 @@ export class SynergyClient {
             throw new Error(`synergy error: ${res.status}`);
         return res.json();
     }
+    /**
+     * `GET /api/v1/workflows/:id` — poll the current state of a
+     * previously-submitted workflow run.
+     *
+     * No long-polling or SSE in this client; callers poll on their
+     * own cadence. Throws `Error("synergy error: <status>")` on
+     * non-2xx (including 404 for unknown ids).
+     */
     async getWorkflow(id) {
         const res = await fetch(`${this.#baseUrl}/api/v1/workflows/${id}`, {
             headers: { "x-api-key": this.#apiKey },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAkB7C,MAAM,OAAO,aAAa;IACf,QAAQ,CAAS;IACjB,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,MAAc;QACzC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,GAA0B;QAC7C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,mBAAmB,EAAE;YAC3D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,OAAO;aAC1B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,CAAC,IAAI,EAA0B,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,EAAU;QAC1B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,qBAAqB,EAAE,EAAE,EAAE;YACjE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE;SACvC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,CAAC,IAAI,EAA0B,CAAC;IAC5C,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,sEAAsE;AACtE,4DAA4D;AAC5D,EAAE;AACF,+DAA+D;AAC/D,+DAA+D;AAC/D,8DAA8D;AAC9D,kEAAkE;AAClE,+DAA+D;AAC/D,6DAA6D;AAC7D,wEAAwE;AACxE,2CAA2C;AAC3C,EAAE;AACF,kBAAkB;AAClB,4DAA4D;AAC5D,+DAA+D;AAC/D,qDAAqD;AA4CrD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,aAAa;IACf,QAAQ,CAAS;IACjB,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,MAAc;QACzC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAC,GAA0B;QAC7C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,mBAAmB,EAAE;YAC3D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,OAAO;aAC1B;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,CAAC,IAAI,EAA0B,CAAC;IAC5C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,WAAW,CAAC,EAAU;QAC1B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,QAAQ,qBAAqB,EAAE,EAAE,EAAE;YACjE,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,OAAO,EAAE;SACvC,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,OAAO,GAAG,CAAC,IAAI,EAA0B,CAAC;IAC5C,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printwithsynergy/artwork-pdf",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Typed client for the artworkPDF synergy node",
   "license": "AGPL-3.0-or-later",
   "type": "module",
@@ -16,7 +16,7 @@
   },
   "devDependencies": {
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^4.1.0"
   },
   "scripts": {
     "build": "tsc",

package/src/index.ts

@@ -1,21 +1,84 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// `@printwithsynergy/artwork-pdf` — typed HTTP client for the synergy
+// engine's workflow API, scoped to artworkPDF's node usage.
+//
+// The synergy engine orchestrates multi-stage pipelines across
+// disparate node types (`artwork.render`, `artwork.thumbnail`,
+// `artwork.preview-separations` plus equivalents from sibling
+// nodes). artwork-pdf hosts that want to submit synergy workflows
+// (e.g. the marketing site's "submit-for-print" flow) use this
+// client; it is *not* the in-process pg-boss boundary inside
+// `apps/service` — that boundary lives in `apps/service/src/db/boss.ts`
+// and consumes jobs that synergy enqueued.
+//
+// Public surface:
+// - {@link WorkflowStage} / {@link WorkflowSubmitRequest} /
+//   {@link WorkflowRun} — wire shapes for `/api/v1/workflows`.
+// - {@link SynergyClient} — minimal POST/GET client.
 
+/**
+ * One stage in a synergy workflow.
+ *
+ * `nodeType` is the dotted node identifier the synergy engine routes
+ * on (e.g. `"artwork.render"`). `config` is node-specific — for
+ * artwork.* nodes it's the `JobSubmitRequest` shape from
+ * `@artworkpdf/document-model`; for other node types it follows that
+ * node's own schema. Synergy validates per-node-type at submit time.
+ */
 export type WorkflowStage = {
   nodeType: string;
   config?: Record<string, unknown>;
 };
 
+/**
+ * Body shape for `POST /api/v1/workflows`.
+ *
+ * `stages` are executed in declaration order; each stage's output
+ * becomes the next stage's input (synergy handles the threading).
+ * `input` seeds the first stage — typically the source document or
+ * asset reference that flows through the pipeline.
+ */
 export type WorkflowSubmitRequest = {
   stages: WorkflowStage[];
   input: Record<string, unknown>;
 };
 
+/**
+ * Workflow run state, returned by both submit and poll endpoints.
+ *
+ * `status` is the run-level state machine:
+ * `queued → running → done | failed`. Per-stage progress lives in
+ * `stages[]` — each entry's `status` is opaquely-typed since each
+ * node type defines its own stage state vocabulary; consumers
+ * generally only display it or filter on terminal values.
+ */
 export type WorkflowRun = {
   id: string;
   status: "queued" | "running" | "done" | "failed";
   stages: Array<{ nodeType: string; status: string }>;
 };
 
+/**
+ * Minimal HTTP client for the synergy engine's workflow API.
+ *
+ * Two methods cover the artwork-pdf use case: submit a workflow,
+ * poll a workflow run. Both authenticate via the `x-api-key`
+ * header; both throw on non-2xx responses with the HTTP status in
+ * the message (the synergy API returns a JSON error body, but this
+ * skeleton client surfaces only the status code — richer error
+ * shapes can land later without breaking the constructor signature).
+ *
+ * **Response-shape trust:** the 2xx JSON is cast directly to
+ * {@link WorkflowRun} without runtime validation. Downstream code
+ * is type-safe relative to the synergy contract, not relative to
+ * arbitrary network bytes — if the engine ships an incompatible
+ * shape, errors surface at the consumer site, not here. Runtime
+ * validation (zod) is a future follow-up.
+ *
+ * The client is stateless apart from `baseUrl` + `apiKey` and is
+ * safe to reuse across requests; instantiate once per process.
+ */
 export class SynergyClient {
   readonly #baseUrl: string;
   readonly #apiKey: string;
@@ -25,6 +88,12 @@ export class SynergyClient {
     this.#apiKey = apiKey;
   }
 
+  /**
+   * `POST /api/v1/workflows` — submit a new workflow run.
+   * Resolves with the initial {@link WorkflowRun} (typically in
+   * `"queued"` state). Throws `Error("synergy error: <status>")` on
+   * non-2xx.
+   */
   async submitWorkflow(req: WorkflowSubmitRequest): Promise<WorkflowRun> {
     const res = await fetch(`${this.#baseUrl}/api/v1/workflows`, {
       method: "POST",
@@ -38,6 +107,14 @@ export class SynergyClient {
     return res.json() as Promise<WorkflowRun>;
   }
 
+  /**
+   * `GET /api/v1/workflows/:id` — poll the current state of a
+   * previously-submitted workflow run.
+   *
+   * No long-polling or SSE in this client; callers poll on their
+   * own cadence. Throws `Error("synergy error: <status>")` on
+   * non-2xx (including 404 for unknown ids).
+   */
   async getWorkflow(id: string): Promise<WorkflowRun> {
     const res = await fetch(`${this.#baseUrl}/api/v1/workflows/${id}`, {
       headers: { "x-api-key": this.#apiKey },