@giveitsmaller/sdk 0.7.0 → 0.9.0

package/dist/_audit.js

@@ -121,4 +121,20 @@ export function _runAudit() {
     accept();
     accept();
     accept();
+    // FF1 / 3BIxEnfR — file-first result surface + sink errors.
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    // FF3a / u0hBt6fl — homogeneous fan-out builder surface.
+    accept();
+    accept();
+    accept();
+    accept();
+    // FF5a / Ao8RPVxD — file-first Handle reattach surface.
+    accept();
+    accept();
 }

package/dist/builder.d.ts

@@ -26,6 +26,7 @@
  */
 import type { GislClient } from './client.js';
 import type { OperationDownload, WorkflowStatusResponse, SseOperationProgressDataStatusEnum } from '@giveitsmaller/contracts/openapi';
+import { Handle } from './handle.js';
 import type { PresetDefaults, PresetMedia } from './ergonomic/presets/index.js';
 /**
  * Best-effort detection of the compress-operation media from the
@@ -183,14 +184,6 @@ export interface Result {
      */
     readonly resolvedOptions: ResolvedOptions;
 }
-/**
- * Lighter return value from `.submit({webhook})` — no SSE/poll wait,
- * caller reconciles completion via the webhook.
- */
-export interface Handle {
-    readonly workflowId: string;
-    readonly webhookSecret?: string;
-}
 /**
  * Upload-phase progress event. The byte counter comes from
  * `UploadOptions.onProgress` — there is no `phase` field on the wire.

package/dist/builder.js

@@ -27,6 +27,10 @@
 import { SseEventType, SseOperationProgressDataFromJSON, } from '@giveitsmaller/contracts/openapi';
 import { uploadSource } from './types.js';
 import { GislTimeoutError } from './errors.js';
+// Deferred-usage-only import: `Handle` is constructed inside submit() at call
+// time, not at module load, so the builder.ts <-> handle.ts cycle is safe
+// under ESM (handle.ts imports the await-primitives from this module).
+import { Handle } from './handle.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
 /**
  * Best-effort detection of the compress-operation media from the
@@ -264,11 +268,9 @@ export class OperationBuilder {
             callback_url: options.webhook,
         };
         const created = await this.client.createWorkflow(payload);
-        const handle = {
-            workflowId: created.workflowId,
-            ...(created.webhookSecret != null ? { webhookSecret: created.webhookSecret } : {}),
-        };
-        return handle;
+        // No client passed → the returned Handle's status()/wait()/result()
+        // throw `no_client`; the operation-first submit reconciles via webhook.
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined);
     }
     /**
      * Fan-out chain: run this builder to completion, then for each artifact

package/dist/client.js

@@ -399,10 +399,19 @@ export class GislClient {
                 locale: json.locale,
                 messageParams: json.message_params,
             };
+            // Human-readable text comes from `message` (the I26 localised field).
+            // `error` is the stable, never-localised SCREAMING_SNAKE machine code —
+            // NOT display text. Surfacing `error` as the thrown error's `.message`
+            // regressed consumers that render the human string (x9Lbf6uy). Fall back
+            // to `error` when `message` is absent (deployed contract guarantees
+            // `message` on conforming error envelopes). Machine dispatch keys off
+            // `error_type` (below), unchanged.
+            const status = response.status;
+            const errorMessage = json.message ?? json.error ?? 'Unknown error';
             // Validation-details branch first — preserve existing shape so callers
             // matching on `instanceof GislValidationError` keep working.
             if (isValidationDetails(json.details)) {
-                throw new GislValidationError(response.status, json.error ?? 'Validation error', json.details, path, i18n);
+                throw new GislValidationError(response.status, errorMessage, json.details, path, i18n);
             }
             // Dispatch by (status, error_type) onto the structured envelope shapes
             // emitted by the v2 contracts. Each branch builds the typed payload via
@@ -416,8 +425,6 @@ export class GislClient {
             // fall through to the base `GislApiError` rather than handing the
             // caller silently-corrupted typed metadata.
             const errorType = json.error_type;
-            const status = response.status;
-            const errorMessage = json.error ?? 'Unknown error';
             // Build the typed payload via FromJSON, then validate that all
             // required typed fields are well-formed. FromJSON does not throw on
             // missing required fields — for example `workflow_expired` without
@@ -1740,7 +1747,10 @@ export class GislClient {
             let errorMessage = 'Unknown error';
             try {
                 const errJson = (await response.json());
-                if (errJson.error)
+                // Prefer the human `message`; `error` is the machine code (x9Lbf6uy).
+                if (errJson.message)
+                    errorMessage = errJson.message;
+                else if (errJson.error)
                     errorMessage = errJson.error;
             }
             catch {

package/dist/errors.d.ts

@@ -300,6 +300,18 @@ export declare class GislChainCardinalityMismatchError extends GislConfigError {
 export declare class GislTimeoutError extends GislError {
     constructor(message: string);
 }
+/**
+ * Transport-level failure: the underlying `fetch` (or other transport) could
+ * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a
+ * non-ok status / empty body when fetching a result download. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislNetworkError`. Subclasses `GislError` (not
+ * `GislApiError`) because it carries no contract error envelope. The concrete
+ * file-first {@link Downloader} raises this when the output URL cannot be read
+ * (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export declare class GislNetworkError extends GislError {
+    constructor(message: string);
+}
 export declare class GislAbortError extends GislError {
     constructor(message: string);
 }
@@ -326,3 +338,56 @@ export declare class GislMultipartPartCountError extends GislError {
     readonly maxParts: number;
     constructor(message: string, requiredParts: number, maxParts: number);
 }
+/**
+ * Thrown by the file-first `RunResult.byKey()` (FF1) when no result entry
+ * matches the requested key. A keyless run (no `key:` supplied to `file()`)
+ * is addressable positionally only — `byKey()` always throws.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNoSuchKeyError`.
+ */
+export declare class GislNoSuchKeyError extends GislError {
+    constructor(message: string);
+}
+/**
+ * Thrown by the file-first `Handle.result()` (FF5a) when the workflow has not
+ * yet reached a terminal state. `result()` is the NON-blocking accessor: it
+ * fetches the current status once and, if the workflow is still
+ * `pending`/`in_progress`, throws this rather than waiting. Use `Handle.wait()`
+ * to block until terminal instead.
+ *
+ * Carries the `workflowId` and the current (non-terminal) `state`.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislResultNotReadyError`.
+ */
+export declare class GislResultNotReadyError extends GislError {
+    readonly workflowId: string;
+    readonly state: string;
+    constructor(workflowId: string, state: string);
+}
+/** Machine-readable cause carried by {@link GislSinkError}. */
+export type GislSinkErrorReason = 'not_single_output' | 'downloader_unavailable' | 'partial_failure' | 'duplicate_filename' | 'invalid_directory' | 'write_failed';
+/**
+ * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
+ * FF1) when they cannot deliver. The machine-readable `reason` discriminates
+ * the three cases, mirroring the `reason`-bag convention on
+ * {@link GislConfigError}:
+ *
+ *  - `not_single_output`      — `toFile()` requires exactly one output but the
+ *                               run produced zero or more than one.
+ *  - `downloader_unavailable` — the `RunResult` has no downloader bound (e.g. a
+ *                               browser / no-I/O context).
+ *  - `partial_failure`        — `downloadTo({ failOnPartial: true })` and the
+ *                               run had at least one failed input.
+ *  - `duplicate_filename`     — two outputs share a destination filename in one
+ *                               `downloadTo(dir)`, which would silently overwrite.
+ *  - `write_failed`           — a concrete {@link Downloader} could not open or
+ *                               stream to the destination path.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislSinkError`.
+ */
+export declare class GislSinkError extends GislError {
+    readonly reason: GislSinkErrorReason;
+    constructor(message: string, options: {
+        readonly reason: GislSinkErrorReason;
+    });
+}

package/dist/errors.js

@@ -320,6 +320,21 @@ export class GislTimeoutError extends GislError {
         this.name = 'GislTimeoutError';
     }
 }
+/**
+ * Transport-level failure: the underlying `fetch` (or other transport) could
+ * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a
+ * non-ok status / empty body when fetching a result download. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislNetworkError`. Subclasses `GislError` (not
+ * `GislApiError`) because it carries no contract error envelope. The concrete
+ * file-first {@link Downloader} raises this when the output URL cannot be read
+ * (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export class GislNetworkError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislNetworkError';
+    }
+}
 export class GislAbortError extends GislError {
     constructor(message) {
         super(message);
@@ -359,3 +374,65 @@ export class GislMultipartPartCountError extends GislError {
         this.maxParts = maxParts;
     }
 }
+/**
+ * Thrown by the file-first `RunResult.byKey()` (FF1) when no result entry
+ * matches the requested key. A keyless run (no `key:` supplied to `file()`)
+ * is addressable positionally only — `byKey()` always throws.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNoSuchKeyError`.
+ */
+export class GislNoSuchKeyError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislNoSuchKeyError';
+    }
+}
+/**
+ * Thrown by the file-first `Handle.result()` (FF5a) when the workflow has not
+ * yet reached a terminal state. `result()` is the NON-blocking accessor: it
+ * fetches the current status once and, if the workflow is still
+ * `pending`/`in_progress`, throws this rather than waiting. Use `Handle.wait()`
+ * to block until terminal instead.
+ *
+ * Carries the `workflowId` and the current (non-terminal) `state`.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislResultNotReadyError`.
+ */
+export class GislResultNotReadyError extends GislError {
+    workflowId;
+    state;
+    constructor(workflowId, state) {
+        super(`Workflow ${workflowId} is not ready (state '${state}'); its result is not available yet. ` +
+            'Call wait() to block until it reaches a terminal state, or poll result() again later.');
+        this.name = 'GislResultNotReadyError';
+        this.workflowId = workflowId;
+        this.state = state;
+    }
+}
+/**
+ * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
+ * FF1) when they cannot deliver. The machine-readable `reason` discriminates
+ * the three cases, mirroring the `reason`-bag convention on
+ * {@link GislConfigError}:
+ *
+ *  - `not_single_output`      — `toFile()` requires exactly one output but the
+ *                               run produced zero or more than one.
+ *  - `downloader_unavailable` — the `RunResult` has no downloader bound (e.g. a
+ *                               browser / no-I/O context).
+ *  - `partial_failure`        — `downloadTo({ failOnPartial: true })` and the
+ *                               run had at least one failed input.
+ *  - `duplicate_filename`     — two outputs share a destination filename in one
+ *                               `downloadTo(dir)`, which would silently overwrite.
+ *  - `write_failed`           — a concrete {@link Downloader} could not open or
+ *                               stream to the destination path.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislSinkError`.
+ */
+export class GislSinkError extends GislError {
+    reason;
+    constructor(message, options) {
+        super(message);
+        this.name = 'GislSinkError';
+        this.reason = options.reason;
+    }
+}