@giveitsmaller/sdk 0.20.0 → 0.22.0

package/dist/merge.js

@@ -128,14 +128,14 @@ export class MergeBuilder {
         });
         // 5. Fetch downloads + project.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Merge workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`Merge workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`, created.workflowId);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
         // TDqmkWpX: the maxWait deadline also covers the downloads fetch itself —
         // re-check AFTER the call so a slow getWorkflowDownloads cannot return a
         // success past the advertised whole-run deadline.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Merge workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+            throw new GislTimeoutError(`Merge workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
         }
         // p0SuJEeK — project ONLY the merge job's output. getWorkflowDownloads
         // returns a download group per terminal job, which now INCLUDES the

package/dist/sse.js

@@ -105,7 +105,55 @@ export async function* parseSseStream(response, opts = {}) {
                     continue;
                 }
                 if (line.startsWith(':')) {
-                    // Comment line (keep-alive), skip
+                    // Comment line (keep-alive), skip.
+                    //
+                    // ⚠️ DO NOT "FIX" THIS INTO SURFACING COMMENT FRAMES WITHOUT READING
+                    // THIS. Dropping them is CORRECT per the SSE spec — a comment carries
+                    // no event — but it is also LOAD-BEARING FOR A CONSUMER, and that
+                    // consumer is in another repo.
+                    //
+                    // The frontend does NOT close its SSE reader on the terminal event:
+                    // `workflow_completed` patches status and breaks WITHOUT aborting.
+                    // What actually closes the stream is an IDLE WATCHDOG at 20s. That
+                    // watchdog only fires because heartbeats are never yielded here, so
+                    // they never re-arm it — roughly 20s after the last real event the
+                    // reader closes and the PHP worker is released.
+                    //
+                    // HEARTBEAT ~16s vs IDLE TIMEOUT 20s: a FOUR-SECOND MARGIN that holds
+                    // only while the heartbeats are invisible. Surfacing comment frames —
+                    // a completely reasonable change, since EventSource semantics treat
+                    // keep-alive comments as liveness signals that legitimately reset
+                    // timeouts — would CONTINUOUSLY re-arm the watchdog. The stream would
+                    // never go idle, and every completed job left on screen would hold a
+                    // PHP worker for the full 570s. That is worker exhaustion from
+                    // ordinary users leaving tabs open.
+                    //
+                    // A ONE-LINE CHANGE HERE SILENTLY CONVERTS THE FRONTEND FROM BOUNDED
+                    // TO UNBOUNDED, and nothing on either side would flag it.
+                    //
+                    // ⚠️ THIS NOTE IS PERMANENT. DO NOT DELETE IT WHEN THE FRONTEND
+                    // ADDS AN EXPLICIT CLOSE-ON-TERMINAL. That fix removes the TERMINAL
+                    // case and does NOT remove the dependency, because closing finished
+                    // streams was never the watchdog's job — that was a side effect
+                    // nobody knew about until 2026-08-12.
+                    //
+                    // THE WATCHDOG'S ACTUAL JOB IS DETECTING A STREAM THAT HAS GONE
+                    // SILENT WHILE THE WORKFLOW IS STILL RUNNING, and resuming the
+                    // fallback poll. That case survives every fix in flight, and it is
+                    // not exotic: a long operation between progress events produces it
+                    // exactly — heartbeats flowing, no data frames, job still running.
+                    //
+                    // If this parser surfaced comment frames, heartbeats at ~16s would
+                    // re-arm the 20s watchdog FOREVER and STALL DETECTION WOULD NEVER
+                    // FIRE AT ALL, on a stream that is genuinely stuck. The UI would go
+                    // on believing a dead job is fine. That is worse than the worker
+                    // leak: a leak is bounded by 570s, a missed stall is not bounded at
+                    // all.
+                    //
+                    // The PHP SDK does the same thing at GislClient.php (`$line[0] === ':'`),
+                    // verified 2026-08-12 — the two languages agree on this axis, and
+                    // they must stay agreed: this property governs whether a stuck
+                    // stream is EVER detected, so a divergence here is not cosmetic.
                     continue;
                 }
                 const colonIndex = line.indexOf(':');

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { OperationType, OperationsSchemaResponse, OperationCapability, OutputProperties, ImageEncodeCapabilities, CallbackEventType, SseEventType, SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, MultipartInitiateRequestMetadataHint, UploadProbeResponse } from '@giveitsmaller/contracts/openapi';
-import type { JobInputV2RoleEnum } from '@giveitsmaller/contracts/openapi';
+import type { JobInputV2RoleEnum, NotifyConfig } from '@giveitsmaller/contracts/openapi';
 export interface GislClientConfig {
     baseUrl: string;
     apiKey?: string;
@@ -188,6 +188,14 @@ export interface WorkflowCreatePayload {
     export?: ExternalDestinationPayload;
     delivery?: DeliveryPayload;
     processing?: WorkflowProcessingPayload;
+    /**
+     * Per-job completion notification (contracts v2.164.0, `notify.email`).
+     * Opaque passthrough wire shape — the ergonomic `notifyEmail` surface
+     * (SubmitOptions/RunOptions + builder convenience) is a separate follow-up
+     * (card y6jsQCpb); this field only acknowledges the wire key so a
+     * hand-built payload can carry it. Mirrors `export`/`delivery`/`processing`.
+     */
+    notify?: NotifyConfig;
 }
 /**
  * Single source of truth for WorkflowCreatePayload's top-level wire keys.
@@ -196,7 +204,7 @@ export interface WorkflowCreatePayload {
  * only via deep imports and should not be treated as public API.
  * @internal
  */
-export declare const WORKFLOW_CREATE_PAYLOAD_KEYS: readonly ["jobs", "source", "operations", "workflow_edges", "callback_url", "callback_events", "export", "delivery", "processing"];
+export declare const WORKFLOW_CREATE_PAYLOAD_KEYS: readonly ["jobs", "source", "operations", "workflow_edges", "callback_url", "callback_events", "export", "delivery", "processing", "notify"];
 export interface GetSchemaOptions {
     /** Filter the schema to operations that accept this MIME type (e.g. `image/jpeg`). */
     mimeType?: string;
@@ -322,7 +330,7 @@ export interface ReadCapabilityOptions {
 export interface WaitOptions {
     /** Poll interval in milliseconds (default: 2000) */
     intervalMs?: number;
-    /** Maximum wait time in milliseconds (default: 300000 = 5 min) */
+    /** Maximum wait time in milliseconds (default: 600000 = 10 min) */
     timeoutMs?: number;
     /** Called after each poll with current status */
     onPoll?: (status: string) => void;

package/dist/types.js

@@ -50,4 +50,5 @@ export const WORKFLOW_CREATE_PAYLOAD_KEYS = Object.freeze([
     'export',
     'delivery',
     'processing',
+    'notify',
 ]);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.53.0"
+    "@giveitsmaller/contracts": "^0.65.0"
   },
   "devDependencies": {
     "@types/node": "^22",

package/dist/ergonomic/presets/document_pdf_compress.d.ts

@@ -1,12 +0,0 @@
-import { PdfProfile, OptimizeFor } from '../../generated/sdk_spec/enums.js';
-export interface DocumentPdfCompressPresetOptionsInput {
-    readonly profile?: PdfProfile;
-    readonly grayscale?: boolean;
-}
-export declare class DocumentPdfCompressPresetOptions {
-    readonly profile?: PdfProfile;
-    readonly grayscale?: boolean;
-    private constructor();
-    static from(input: DocumentPdfCompressPresetOptionsInput): DocumentPdfCompressPresetOptions;
-    static shippedDefaultsFor(level: OptimizeFor): DocumentPdfCompressPresetOptions;
-}

package/dist/ergonomic/presets/document_pdf_compress.js

@@ -1,33 +0,0 @@
-// T4a — DocumentPdfCompressPresetOptions leaf DTO.
-//
-// Field set (2): profile, grayscale — the worker-honored stable PDF controls
-// (contracts v2.96.0 Acrobat-PDF realignment Lw1LseYr). The earlier
-// {profile, colorspace, flattenForms} set was retired: colorspace + flatten_forms
-// are `planned` (not read by the worker) so presets never emit them, and
-// `image_dpi` + `pages` are per-call knobs, not preset cells.
-import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
-import { translateEnum } from './_translate.js';
-export class DocumentPdfCompressPresetOptions {
-    profile;
-    grayscale;
-    constructor(input) {
-        if (input.profile !== undefined)
-            this.profile = input.profile;
-        if (input.grayscale !== undefined)
-            this.grayscale = input.grayscale;
-        Object.freeze(this);
-    }
-    static from(input) {
-        return new DocumentPdfCompressPresetOptions(input);
-    }
-    static shippedDefaultsFor(level) {
-        const cell = f3ShippedDefaultsFor('document_pdf_compress', level);
-        const input = {};
-        const mut = input;
-        if ('profile' in cell)
-            mut.profile = translateEnum('PdfProfile', cell.profile);
-        if ('grayscale' in cell)
-            mut.grayscale = cell.grayscale;
-        return new DocumentPdfCompressPresetOptions(input);
-    }
-}