@giveitsmaller/sdk 0.18.0 → 0.20.0

package/dist/retry-metadata.js

@@ -0,0 +1,86 @@
+// Shared HTTP retry-metadata helpers. Extracted here so `errors.ts` can consume
+// them WITHOUT importing `client.ts`: `client.ts` already imports `errors.ts`, so
+// pulling the module-private `parseRetryAfterMs` back out of `client.ts` would
+// form a `client → errors → client` circular import. The millisecond parser is
+// MOVED here verbatim; `client.ts` re-imports it so the retry-loop timing stays
+// byte-identical.
+/**
+ * Whether an HTTP status is retryable per the API-error taxonomy: request
+ * timeout (408), rate-limit (429), or any 5xx (500–599). BOUNDED at 599 — a
+ * non-standard 6xx-and-up status is NOT classified retryable.
+ *
+ * Now value-identical to the S3-PUT retry predicate (`isRetryableStatus`) in
+ * `client.ts` (both are `408 || 429 || 500-599` after qz7MjNTy), but kept
+ * DELIBERATELY SEPARATE: they guard different retry paths (S3-PUT chunk uploads
+ * vs the API-error taxonomy) and may diverge again, so they must NOT be merged.
+ */
+export function isApiRetryableStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
+}
+// Parse an HTTP `Retry-After` header into milliseconds. Accepts the two RFC
+// 9110 forms: delta-seconds (e.g. "5") or an HTTP-date. Returns `undefined`
+// for an absent / unparseable / negative value (caller falls back to its own
+// backoff). A past HTTP-date clamps to 0.
+export function parseRetryAfterMs(headerValue) {
+    if (headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (trimmed === '')
+        return undefined;
+    let ms;
+    if (/^\d+$/.test(trimmed)) {
+        ms = Number(trimmed) * 1000;
+    }
+    else {
+        const when = Date.parse(trimmed);
+        if (Number.isNaN(when))
+            return undefined;
+        ms = when - Date.now();
+    }
+    // A non-positive Retry-After (e.g. "0" or a past HTTP-date) must NOT short-
+    // circuit the backoff to zero — treat it as absent so the caller falls back
+    // to jitter and the loop can't busy-poll until timeout.
+    return ms > 0 ? ms : undefined;
+}
+/**
+ * The server-suggested back-off delay in WHOLE seconds, parsed from the
+ * `Retry-After` response header. Derived from {@link parseRetryAfterMs}
+ * (`Math.floor(ms / 1000)`) so the semantics mirror the retry-loop parser:
+ * absent / malformed / zero / past all collapse to `undefined`, as does a
+ * sub-second future HTTP-date (floors to zero → treated as absent).
+ */
+export function retryAfterSecondsFromHeaders(headers) {
+    const ms = parseRetryAfterMs(headers?.['retry-after']);
+    if (ms === undefined)
+        return undefined;
+    const seconds = Math.floor(ms / 1000);
+    return seconds > 0 ? seconds : undefined;
+}
+// Parse a non-negative integer response header. Returns `undefined` for an
+// absent value or anything that isn't a bare run of decimal digits (so a
+// float, sign, or units suffix is rejected rather than silently truncated).
+function parseIntHeader(headerValue) {
+    if (headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    return Number(trimmed);
+}
+/**
+ * A rate-limit snapshot parsed from the `x-ratelimit-*` response headers.
+ * Present ONLY when `x-ratelimit-limit`, `x-ratelimit-remaining`, and
+ * `x-ratelimit-reset` all parse as non-negative integers; otherwise
+ * `undefined` (a partial set is not a usable snapshot).
+ */
+export function rateLimitFromHeaders(headers) {
+    if (headers === undefined)
+        return undefined;
+    const limit = parseIntHeader(headers['x-ratelimit-limit']);
+    const remaining = parseIntHeader(headers['x-ratelimit-remaining']);
+    const resetSeconds = parseIntHeader(headers['x-ratelimit-reset']);
+    if (limit === undefined || remaining === undefined || resetSeconds === undefined) {
+        return undefined;
+    }
+    return { limit, remaining, resetSeconds };
+}

package/dist/sse.d.ts

@@ -1,4 +1,4 @@
-import type { GislSseEvent } from './types.js';
+import type { GislSseEvent, GislSseParseFailure } from './types.js';
 /**
  * Parse an SSE stream from a fetch Response into an AsyncIterable of typed events.
  *
@@ -27,4 +27,5 @@ import type { GislSseEvent } from './types.js';
  */
 export declare function parseSseStream(response: Response, opts?: {
     signal?: AbortSignal;
+    onParseError?: (diagnostic: GislSseParseFailure) => void;
 }): AsyncGenerator<GislSseEvent>;

package/dist/sse.js

@@ -76,15 +76,27 @@ export async function* parseSseStream(response, opts = {}) {
                     // Empty line = end of event
                     if (dataLines.length > 0) {
                         const rawData = dataLines.join('\n');
+                        const frameEvent = eventType || 'message';
                         let parsed;
                         try {
                             parsed = JSON.parse(rawData);
                         }
-                        catch {
-                            parsed = rawData;
+                        catch (err) {
+                            // TYNjcjpo — a malformed-JSON frame is SKIPPED (not yielded as a
+                            // raw string) so the stream stays resilient, but the failure is
+                            // surfaced via the optional onParseError diagnostic rather than
+                            // silently lost. Identical to the PHP `flushSseFrame` drop-path.
+                            opts.onParseError?.({
+                                raw: rawData,
+                                event: frameEvent,
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                            eventType = '';
+                            dataLines = [];
+                            continue;
                         }
                         yield {
-                            event: eventType || 'message',
+                            event: frameEvent,
                             data: parsed,
                         };
                     }
@@ -124,15 +136,23 @@ export async function* parseSseStream(response, opts = {}) {
         // not be yielded once the consumer has abandoned the stream.
         if (!aborted && dataLines.length > 0) {
             const rawData = dataLines.join('\n');
+            const frameEvent = eventType || 'message';
             let parsed;
             try {
                 parsed = JSON.parse(rawData);
             }
-            catch {
-                parsed = rawData;
+            catch (err) {
+                // TYNjcjpo — trailing-flush malformed frame: skip + diagnostic (same as
+                // the in-loop path above).
+                opts.onParseError?.({
+                    raw: rawData,
+                    event: frameEvent,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return;
             }
             yield {
-                event: eventType || 'message',
+                event: frameEvent,
                 data: parsed,
             };
         }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { OperationType, OperationsSchemaResponse, CallbackEventType, SseEventType, SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, MultipartInitiateRequestMetadataHint, UploadProbeResponse } from '@giveitsmaller/contracts/openapi';
+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';
 export interface GislClientConfig {
     baseUrl: string;
@@ -227,6 +227,32 @@ export type GetSchemaResult = {
     etag?: string;
     lastModified?: string;
 };
+/**
+ * Typed projection of the operation-capability surface returned by
+ * {@link ErgonomicClient.capabilities} (qUhxfDA5). Bundles the three v2.124
+ * capability fields of `OperationsSchemaResponse` — previously typed but with
+ * no ergonomic consumer — so a caller can read them without dropping to
+ * `getSchema()` and its not-modified union.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\CapabilitiesSnapshot` value object.
+ */
+export interface CapabilitiesSnapshot {
+    /**
+     * Tier-scoped operation-capability matrix, keyed by operation type
+     * (`compress`, `convert`, …). Empty when the server omits the field.
+     */
+    readonly operations: Record<string, OperationCapability>;
+    /**
+     * Output-format property table (`hasAudioTrack` / `isAnimated`), keyed by
+     * `output_format`. Tier-invariant. Empty when the server omits the field.
+     */
+    readonly outputProperties: Record<string, OutputProperties>;
+    /**
+     * Pre-flight image-encode capability matrix (`webpQualitySupported`,
+     * `backgroundFlatten`). Tier-invariant. `undefined` when the server omits it.
+     */
+    readonly imageEncode?: ImageEncodeCapabilities;
+}
 export interface CreditsUsageOptions {
     /**
      * Page size. Server defaults to 20 and rejects values outside `[1, 100]`
@@ -373,6 +399,22 @@ export type GislSseEvent = {
     event: string;
     data: unknown;
 };
+/**
+ * A typed, non-throwing diagnostic surfaced when an SSE frame's `data:` body fails
+ * to JSON-parse (TYNjcjpo). The malformed frame is SKIPPED from the event stream —
+ * a long-running consumer must not break on one garbled server frame — but the
+ * failure is observable via the `onParseError` callback on `streamEvents` /
+ * `parseSseStream` rather than silently lost. Mirrors the PHP `GislSseParseFailure`
+ * value object; the shape is identical across the two SDKs (cross-SDK parity).
+ */
+export interface GislSseParseFailure {
+    /** The joined `data:` line(s) that failed to parse. */
+    readonly raw: string;
+    /** The frame's event type (or `'message'` when the frame had no `event:` field). */
+    readonly event: string;
+    /** The parse error message (e.g. the `JSON.parse` `SyntaxError` text). */
+    readonly error: string;
+}
 export interface UploadOptions {
     /** Called with bytes uploaded so far (only for multipart) */
     onProgress?: (uploadedBytes: number, totalBytes: number) => void;

package/package.json

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