@giveitsmaller/sdk 0.20.0 → 0.22.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -2,6 +2,8 @@
 
 TypeScript / Node.js SDK for the [GISL](https://giveitsmaller.com) (Give It Smaller) file compression and processing API.
 
+> **Read-only mirror.** This repository is automatically published from Give It Smaller's private monorepo on each release. Do **not** open issues or pull requests here — they are not monitored. Licensed under [Apache-2.0](./LICENSE).
+
 ## Install
 
 ```bash
@@ -44,9 +46,7 @@ for (const artifact of many.artifacts) console.log(artifact.url);
 > `client.compress(path, { ... }).run()` form (and `thumbnail` / `convert`) is
 > available, and the raw wire client — `client.createWorkflow({ jobs: [...] })`
 > with `uploadSource` / `OperationType` for hand-built job DAGs — is the advanced
-> escape hatch. File-first is the recommended direction the
-> [examples](https://github.com/AntonioCS/giveitsmaller-sdks/tree/main/docs/typescript/examples)
-> build on.
+> escape hatch. File-first is the recommended direction to build on.
 
 > **Reusing an upload id across clients?** An upload created by an
 > authenticated caller is owned by that caller. If you persist a `fileId` and
@@ -56,18 +56,59 @@ for (const artifact of many.artifacts) console.log(artifact.url);
 > only under the same auth that created it; the upload-then-create flow above is
 > consistent by construction. Anonymous-intake uploads are unaffected.
 
-## Full documentation
+## Known limitation — browser SSE is restricted to one origin
+
+**Applies to the browser build only** (`@giveitsmaller/sdk/browser`), and **only to live progress
+streaming** — `streamEvents()`, and the `run({ useSSE: true })` default that uses it.
+
+Live progress is served from a **separate host** to the rest of the API, and that host allows
+**exactly one browser origin**: the Give It Smaller web app. So from a browser on any other origin:
+
+| what you are doing | works? |
+|---|---|
+| Uploads, workflow create, status, downloads | **Yes** — these stay on the main API host, which allows a **list** of origins (per environment) |
+| `streamEvents()` / SSE progress | **No** — blocked at the CORS preflight |
+
+**Affected consumers:** third-party sites embedding the SDK, embedded/iframe use, and **local
+development against staging** — which is the one most likely to bite first, because it looks like a
+bug in your code.
+
+⚠️ **Local dev against staging is the sharp edge, and the reason is worth stating:** the two hosts
+have *different* CORS policies, for a platform reason rather than an oversight. The main API host
+allows a **list** of origins — and the **staging** list includes the usual localhost dev ports — so a
+browser on `localhost` works against staging today. The stream host allows exactly **one** origin,
+because it is a different API product with no native CORS configuration and nowhere to put a second
+value. So everything keeps working right up until live progress, and then fails with a CORS error —
+which reads like a mistake in your own application rather than a platform limitation.
+
+**Production allows only the production web app on both hosts**, and always has.
+
+**Workaround:** pass `useSSE: false` to `run()`. The SDK falls back to polling, which goes to the
+main API host and is unaffected. Everything else about the call is identical.
+
+**Why it cannot simply be widened:** the stream is cookie-credentialed, and the CORS specification
+forbids combining `Access-Control-Allow-Credentials: true` with `Access-Control-Allow-Origin: *`.
+The header also accepts exactly one origin — a comma-separated list is not valid. Supporting more
+origins requires the server to validate and echo the request's `Origin`, which is planned but not
+shipped.
+
+**On authentication:** prefer an API key (`bearerAuth`) or the anonymous capability token on the
+stream host. Cookie/session auth is accepted by the endpoint but a *credentialed cross-origin*
+request additionally needs the browser to opt in and the server to answer with matching credential
+headers — cookie domain scope alone is not sufficient, and this path is not verified.
+
+**Node consumers are unaffected** — CORS is a browser mechanism. The PHP SDK is unaffected for the
+same reason.
+
+> ⚠️ This limitation is invisible to automated testing: our own app's origin is allowed, so every
+> test and canary we run passes while a consumer on another origin fails. It is written here because
+> nothing else would tell you.
 
-Docs are published in the [giveitsmaller-sdks](https://github.com/AntonioCS/giveitsmaller-sdks) repository — they are **not** shipped in the npm tarball (only `dist/` is published).
+## Documentation
 
-- **Getting started & concepts** — [`docs/typescript/index.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/index.md)
-- **Client reference** (all `GislClient` methods + operation option list) — [`docs/typescript/client.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/client.md)
-- **Types & authoring primitives** (config, payloads, job factories) — [`docs/typescript/types.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/types.md)
-- **SSE / live progress** — [`docs/typescript/sse.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/sse.md)
-- **Webhooks** — [`docs/typescript/webhook.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/webhook.md)
-- **Errors & retry guidance** — [`docs/typescript/errors.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/errors.md)
-- **Troubleshooting** — [`docs/typescript/troubleshooting.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/troubleshooting.md)
-- **Examples** — compress, thumbnail, convert, merge, archive, watermark, output — [`docs/typescript/examples/`](https://github.com/AntonioCS/giveitsmaller-sdks/tree/main/docs/typescript/examples)
+Full documentation — getting started and concepts, the `GislClient` reference and operation
+options, authoring primitives, SSE/live progress, webhooks, error/retry guidance, troubleshooting,
+and per-operation examples — lives at [giveitsmaller.com](https://giveitsmaller.com).
 
 ## Contributing: the committed `dist/`
 
@@ -92,4 +133,4 @@ the `file:` gap.
 
 ## License
 
-MIT — see the [LICENSE](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/LICENSE) file.
+Apache-2.0 — see the [LICENSE](./LICENSE) file.

package/dist/_audit.js

@@ -56,6 +56,8 @@ export function _runAudit() {
     accept();
     accept();
     accept();
+    accept();
+    accept();
     // SDK-3 (Wb6ebOMM) public-API surface for the 3 resume-support endpoints.
     accept();
     accept();
@@ -120,10 +122,6 @@ export function _runAudit() {
     accept();
     accept();
     accept();
-    accept();
-    accept();
-    accept();
-    accept();
     // T4b / 27rE1fZn — preset resolver public types.
     accept();
     accept();

package/dist/builder.d.ts

@@ -21,13 +21,13 @@
  *   `status` values pass through verbatim from `SseOperationProgressDataStatusEnum`.
  *   The wire does NOT carry a `phase` field — see karen reality-check 2026-05-23.
  * - `.run()` requires `maxWait` (no default). The underlying `waitForWorkflow`
- *   has a 300s default for the poll fallback path; the ergonomic layer makes
+ *   has a 600s default for the poll fallback path; the ergonomic layer makes
  *   it MANDATORY in the type so callers consciously choose a deadline.
  */
 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';
+import type { PresetDefaults, DetectedMedia } from './ergonomic/presets/index.js';
 /**
  * Best-effort detection of the compress-operation media from the
  * builder's input. T4b only resolves presets for compress; the wire's
@@ -40,7 +40,7 @@ import type { PresetDefaults, PresetMedia } from './ergonomic/presets/index.js';
  *
  * @internal — exported for tests + the preset resolver.
  */
-export declare function _detectCompressMedia(input: string | Blob): PresetMedia | undefined;
+export declare function _detectCompressMedia(input: string | Blob): DetectedMedia | undefined;
 /**
  * Best-effort classification of whether an audio input is LOSSLESS
  * (flac/wav) vs lossy. The worker rejects `bitrate` on lossless audio
@@ -236,7 +236,7 @@ export interface RunOptions {
     /**
      * Wall-clock deadline for the entire run (upload + create + wait + downloads).
      * MANDATORY — the SDK does NOT supply a default because the underlying
-     * `waitForWorkflow` poll path has a 300s default that would otherwise
+     * `waitForWorkflow` poll path has a 600s default that would otherwise
      * leak silently. Pass `'2h'` / `'30m'` / `'120s'` as a string suffix or
      * a number of milliseconds.
      */

package/dist/builder.js

@@ -21,12 +21,12 @@
  *   `status` values pass through verbatim from `SseOperationProgressDataStatusEnum`.
  *   The wire does NOT carry a `phase` field — see karen reality-check 2026-05-23.
  * - `.run()` requires `maxWait` (no default). The underlying `waitForWorkflow`
- *   has a 300s default for the poll fallback path; the ergonomic layer makes
+ *   has a 600s default for the poll fallback path; the ergonomic layer makes
  *   it MANDATORY in the type so callers consciously choose a deadline.
  */
 import { SseEventType, SseOperationProgressDataFromJSON, } from '@giveitsmaller/contracts/openapi';
 import { uploadSource } from './types.js';
-import { GislTimeoutError, GislNetworkError, SseEndedWithoutTerminal } from './errors.js';
+import { GislTimeoutError, GislFanOutTimeoutError, GislNetworkError, SseEndedWithoutTerminal } 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).
@@ -64,10 +64,10 @@ export function _detectCompressMedia(input) {
             return 'audio';
         if (mime.startsWith('video/'))
             return 'video';
-        if (mime === 'application/pdf')
-            return 'document_pdf';
         if (mime === 'application/epub+zip')
             return 'document_epub';
+        if (mime === 'application/pdf')
+            return 'document_pdf';
         if (mime === 'application/vnd.oasis.opendocument.text' ||
             mime === 'application/vnd.oasis.opendocument.spreadsheet' ||
             mime === 'application/vnd.oasis.opendocument.presentation') {
@@ -93,10 +93,10 @@ export function _detectCompressMedia(input) {
         return 'audio';
     if (['mp4', 'mov', 'mkv', 'webm', 'avi', 'wmv', 'flv', 'm4v'].includes(ext))
         return 'video';
-    if (ext === 'pdf')
-        return 'document_pdf';
     if (ext === 'epub')
         return 'document_epub';
+    if (ext === 'pdf')
+        return 'document_pdf';
     if (['odt', 'ods', 'odp'].includes(ext))
         return 'document_odf';
     if (['doc', 'docx', 'xls', 'xlsx', 'ppt', 'pptx'].includes(ext))
@@ -316,14 +316,14 @@ export class OperationBuilder {
         // the deadline before issuing the downloads request rather than letting
         // a slow getWorkflowDownloads silently exceed it.
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+            throw new GislTimeoutError(`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 — a
         // slow getWorkflowDownloads must not return a success after the advertised
         // whole-run deadline. Re-check AFTER the call (the check above is BEFORE).
         if (Date.now() >= deadline) {
-            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`, created.workflowId);
         }
         return _projectResult(finalStatus, downloads.downloads, resolved.wireOptions, resolved.resolvedOptions);
     }
@@ -446,13 +446,38 @@ export class MapEachBuilder {
             _checkAborted(options.signal);
             const remaining = deadline - Date.now();
             if (remaining <= 0) {
-                throw new GislTimeoutError(`maxWait elapsed during fan-out (after ${collectedArtifacts.length} child runs)`);
+                // Clean timeout BETWEEN children (no child in flight): the parent + the
+                // children completed so far are recoverable — carry their ids so the
+                // caller polls them and re-runs ONLY the never-created children (4G4FaA9X).
+                throw new GislFanOutTimeoutError(`maxWait elapsed during fan-out (after ${collectedChildResults.length} child runs)`, {
+                    completedWorkflowIds: collectedChildResults.map((r) => r.workflowId),
+                    parentWorkflowId: parentResult.workflowId,
+                });
             }
             const childBuilder = this.fn(art);
-            const childResult = await childBuilder.run({
-                ...options,
-                maxWait: remaining,
-            });
+            let childResult;
+            try {
+                childResult = await childBuilder.run({
+                    ...options,
+                    maxWait: remaining,
+                });
+            }
+            catch (err) {
+                // A CHILD's own deadline elapsed mid-run — the COMMON fan-out timeout
+                // path. Re-throw as a fan-out timeout so the parent + already-completed
+                // children + this in-flight child are ALL recoverable, instead of losing
+                // them behind the child's bare GislTimeoutError (4G4FaA9X). Other errors
+                // (config / API / item failure) propagate unchanged.
+                if (err instanceof GislTimeoutError) {
+                    throw new GislFanOutTimeoutError(`maxWait elapsed during fan-out while a child was running (${collectedChildResults.length} completed)`, {
+                        completedWorkflowIds: collectedChildResults.map((r) => r.workflowId),
+                        parentWorkflowId: parentResult.workflowId,
+                        workflowId: err.workflowId,
+                        cause: err,
+                    });
+                }
+                throw err;
+            }
             collectedChildResults.push(childResult);
             for (const childArt of childResult.artifacts)
                 collectedArtifacts.push(childArt);
@@ -531,7 +556,7 @@ class _OnProgressThrew {
 export async function _consumeSseToTerminal(client, args) {
     const remainingMs = args.deadline - Date.now();
     if (remainingMs <= 0) {
-        throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+        throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
     }
     const sseAbort = new AbortController();
     // Compose caller's signal + a SDK-internal one so we can tear down on terminal.
@@ -560,7 +585,7 @@ export async function _consumeSseToTerminal(client, args) {
             // If streamEvents rejected because the deadline-armed sseAbort fired
             // before/during connect, surface as timeout (not raw AbortError).
             if (deadlineExpired && err instanceof DOMException && err.name === 'AbortError') {
-                throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+                throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
             }
             // TDqmkWpX: a genuine connect-phase TRANSPORT failure surfaces as a raw
             // `TypeError` from `fetch` (DNS/TCP/TLS) — wrap it as a typed
@@ -577,7 +602,7 @@ export async function _consumeSseToTerminal(client, args) {
         try {
             for await (const event of events) {
                 if (deadlineExpired) {
-                    throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+                    throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
                 }
                 if (args.onProgress !== undefined && event.event === SseEventType.operation_progress) {
                     // Codex r1 high d6485d3e35f9 — `streamEvents` yields raw snake_case
@@ -620,13 +645,13 @@ export async function _consumeSseToTerminal(client, args) {
                 }
                 if (Date.now() >= args.deadline) {
                     sseAbort.abort();
-                    throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+                    throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
                 }
             }
             // Stream ended cleanly without terminal. If the deadline timer fired
             // mid-stream and triggered the abort, surface that as the timeout.
             if (deadlineExpired) {
-                throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+                throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
             }
             // Otherwise it was a clean server-side close — fall back to poll. TDqmkWpX:
             // a sealed marker (not a bare Error) so callers poll ONLY on this + a typed
@@ -646,7 +671,7 @@ export async function _consumeSseToTerminal(client, args) {
             if (deadlineExpired &&
                 innerErr instanceof DOMException &&
                 innerErr.name === 'AbortError') {
-                throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+                throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
             }
             // A genuine mid-stream TRANSPORT failure (reader disconnect) surfaces as a
             // raw `TypeError` from the iterator — wrap as GislNetworkError so callers
@@ -686,7 +711,7 @@ export async function _pollToTerminal(client, args) {
     while (true) {
         _checkAborted(args.signal);
         if (Date.now() >= args.deadline) {
-            throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+            throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
         }
         const status = await client.getWorkflowStatus(args.workflowId);
         if (TERMINAL_STATUS.has(status.status)) {
@@ -697,10 +722,10 @@ export async function _pollToTerminal(client, args) {
         // pre-fetch check firing. Without this, a small `pollIntervalMs` against
         // a slow API can busy-spin past the deadline arbitrarily.
         if (Date.now() >= args.deadline) {
-            throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+            throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
         }
         if (Date.now() + intervalMs >= args.deadline) {
-            throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`);
+            throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
         }
         await sleep(intervalMs, args.signal);
     }

package/dist/client.d.ts

@@ -265,15 +265,18 @@ export declare class GislClient {
      * via that cookie when the client is configured with
      * `useSessionCookie: true`.
      *
-     * Failure modes per ticket FX6mbTJD:
-     * - **401** `invalid_credentials` (collapsed with unverified
-     *   accounts for anti-enumeration) → `GislAuthError`.
-     * - **403** account-state failures (`account_locked`,
-     *   `account_disabled`, `account_deleted`,
-     *   `account_deletion_expired`) → `GislAuthError`.
+     * Failure modes per ticket FX6mbTJD (login narrowed at contracts
+     * v2.166.0 authsec — no 403 account-state branch on login):
+     * - **401** `invalid_credentials` (wrong password, unverified, OR
+     *   unknown account — all collapsed for anti-enumeration) →
+     *   `GislAuthError`.
      * - **429** infrastructure rate-limit → `GislApiError` with
      *   the `Retry-After` header echoed on the response.
      *
+     * The account-status error types (`account_locked` / `account_disabled`
+     * / `account_deleted` / `account_deletion_expired`) still exist but are
+     * emitted on the API-key path + live-session enforcement, not on login.
+     *
      * Node session persistence (cookie-jar across processes) is out of
      * scope — this method only touches the request side.
      */