@giveitsmaller/sdk 0.15.0 → 0.16.0

package/dist/_audit.js

@@ -130,6 +130,9 @@ export function _runAudit() {
     accept();
     // FF3a / u0hBt6fl — homogeneous fan-out builder surface.
     accept();
+    // FF4a / Z7zTr789 — multi-input watermark recipe surface.
+    accept();
+    accept();
     accept();
     accept();
     accept();

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, UploadResponse, UploadProbeResponse, WorkflowCancelResponse, WorkflowCreateResponse, WorkflowResumeResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
-import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
+import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, ReadCapabilityOptions, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
 export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
 export interface ValidationDetail {
@@ -133,8 +133,13 @@ export declare class GislClient {
     createWorkflow(payload: WorkflowCreatePayload): Promise<WorkflowCreateResponse>;
     /**
      * Get current workflow status.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    getWorkflowStatus(workflowId: string): Promise<WorkflowStatusResponse>;
+    getWorkflowStatus(workflowId: string, opts?: ReadCapabilityOptions): Promise<WorkflowStatusResponse>;
     /**
      * Poll until the workflow reaches a terminal status.
      */
@@ -176,13 +181,24 @@ export declare class GislClient {
     resumeWorkflow(workflowId: string): Promise<WorkflowResumeResponse>;
     /**
      * Get download URLs for a completed workflow.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    getWorkflowDownloads(workflowId: string): Promise<WorkflowDownloadResponse>;
+    getWorkflowDownloads(workflowId: string, opts?: ReadCapabilityOptions): Promise<WorkflowDownloadResponse>;
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     streamEvents(workflowId: string, opts?: {
         signal?: AbortSignal;
+        capability?: string;
     }): Promise<AsyncGenerator<GislSseEvent>>;
     /**
      * Get metadata for an uploaded file.

package/dist/client.js

@@ -56,6 +56,17 @@ const S3_MAX_MULTIPART_PARTS = 10_000;
 const RECOMMENDED_CHUNK_SIZE_MAX_BYTES = 104_857_600; // 100 MiB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
+// Anonymous-read capability header. An anonymous (null-owner) workflow create
+// returns a one-time `cap` token (WorkflowCreateResponse.cap); the session-less
+// caller passes it back on status/downloads/events reads via this header so the
+// server can authorize the read. A wrong/missing cap on a null-owner workflow
+// returns 404 (no existence oracle), per contracts ticket YQt88cq2.
+const WORKFLOW_CAPABILITY_HEADER = 'X-Workflow-Capability';
+// Build the capability header set for a workflow read. Empty when no token is
+// supplied (authenticated reads — the session authorizes those).
+function workflowCapabilityHeaders(capability) {
+    return capability ? { [WORKFLOW_CAPABILITY_HEADER]: capability } : {};
+}
 // Statuses that waitForWorkflow() returns immediately on. Per ticket I24,
 // `cancelled` and `expired` are terminal (a workflow cannot leave either
 // state). `paused_insufficient_credits` is a soft-pause: not terminal, but
@@ -1599,10 +1610,16 @@ export class GislClient {
     }
     /**
      * Get current workflow status.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    async getWorkflowStatus(workflowId) {
+    async getWorkflowStatus(workflowId, opts = {}) {
         return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
             deserialize: WorkflowStatusResponseFromJSON,
+            headers: workflowCapabilityHeaders(opts.capability),
         });
     }
     /**
@@ -1613,7 +1630,9 @@ export class GislClient {
         const timeoutMs = options?.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
         const deadline = Date.now() + timeoutMs;
         while (true) {
-            const status = await this.getWorkflowStatus(workflowId);
+            const status = await this.getWorkflowStatus(workflowId, {
+                capability: options?.capability,
+            });
             options?.onPoll?.(status.status);
             if (TERMINAL_STATUSES.has(status.status)) {
                 return status;
@@ -1669,14 +1688,25 @@ export class GislClient {
     }
     /**
      * Get download URLs for a completed workflow.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    async getWorkflowDownloads(workflowId) {
+    async getWorkflowDownloads(workflowId, opts = {}) {
         return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/downloads`, {
             deserialize: WorkflowDownloadResponseFromJSON,
+            headers: workflowCapabilityHeaders(opts.capability),
         });
     }
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     async streamEvents(workflowId, opts = {}) {
         const eventsPath = `/api/workflows/${encodeURIComponent(workflowId)}/events`;
@@ -1702,6 +1732,7 @@ export class GislClient {
             response = await this.request('GET', eventsPath, {
                 rawResponse: true,
                 signal: controller.signal,
+                headers: workflowCapabilityHeaders(opts.capability),
             });
         }
         catch (err) {

package/dist/ergonomic/preset_resolver.d.ts

@@ -2,13 +2,14 @@ import type { ResolvedOptions } from '../builder.js';
 import type { OptimizeFor } from '../generated/sdk_spec/enums.js';
 import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/index.js';
 /**
- * Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value.
- * Must track the contracts `sdk-spec/version.yaml` `presetVersion` (mirrored in
- * the generated `sdk_spec/version.ts`). 1.0 → 1.2 on the contracts v2.71.0
- * (video_compress `audioBitrate` dropped) + v2.73.0 (image Size/Balanced
- * `outputFormat` Smallest/Auto → Original — VcPeRWdD facade self-422 guard) cuts.
+ * The preset matrix version emitted on every resolve. Re-exported from the
+ * GENERATED `sdk_spec/version.ts` (source of truth: contracts
+ * `sdk-spec/version.yaml` `presetVersion`) so it can NEVER drift from the
+ * generated preset cells — a regen that bumps the cells bumps this by
+ * construction. Previously a hand-typed literal that the v2.73.0 regen had to
+ * bump manually (yREs0srv).
  */
-export declare const PRESET_VERSION = "1.2";
+export declare const PRESET_VERSION: "1.2";
 /**
  * Inputs to {@link resolveCompressOptions}. `media` selects which leaf
  * DTO drives sdkDefault + clientDefault lookups + invalid-combo

package/dist/ergonomic/preset_resolver.js

@@ -36,15 +36,17 @@
 // to the wire; conversely if `crf` is explicit, `encoding_mode='crf'`.
 import { sha256Hex } from '../sha256.js';
 import { GislConfigError } from '../errors.js';
+import { PRESET_VERSION as GENERATED_PRESET_VERSION } from '../generated/sdk_spec/version.js';
 import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, } from './presets/index.js';
 /**
- * Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value.
- * Must track the contracts `sdk-spec/version.yaml` `presetVersion` (mirrored in
- * the generated `sdk_spec/version.ts`). 1.0 → 1.2 on the contracts v2.71.0
- * (video_compress `audioBitrate` dropped) + v2.73.0 (image Size/Balanced
- * `outputFormat` Smallest/Auto → Original — VcPeRWdD facade self-422 guard) cuts.
+ * The preset matrix version emitted on every resolve. Re-exported from the
+ * GENERATED `sdk_spec/version.ts` (source of truth: contracts
+ * `sdk-spec/version.yaml` `presetVersion`) so it can NEVER drift from the
+ * generated preset cells — a regen that bumps the cells bumps this by
+ * construction. Previously a hand-typed literal that the v2.73.0 regen had to
+ * bump manually (yREs0srv).
  */
-export const PRESET_VERSION = '1.2';
+export const PRESET_VERSION = GENERATED_PRESET_VERSION;
 // ---------------------------------------------------------------------------
 // Wire-field alias map (declarative — NOT generic toSnakeCase).
 // ---------------------------------------------------------------------------

package/dist/file-first.d.ts

@@ -249,6 +249,19 @@ export declare function isMergeStatus(finalStatus: WorkflowStatusResponse): bool
  * @internal Exported for the file-first `Handle`; not part of the public API.
  */
 export declare function isArchiveStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * True when a terminal status describes a fluent `file(...).watermark(overlay)`
+ * — at least one job ref `watermark` and every OTHER job ref is `src_{i}` (the
+ * ids the {@link WatermarkedRecipe} lowering assigns: `src_0` base, `src_1`
+ * overlay). Lets {@link Handle.wait}/{@link Handle.result} AND
+ * {@link WatermarkedRecipe.run} project ONLY the watermark output — filtering
+ * the `src_*` passthrough plumbing — even after a `client.workflow(id)` reattach.
+ * Mutually exclusive with {@link isFanoutStatus} / {@link isMergeStatus} /
+ * {@link isArchiveStatus}.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export declare function isWatermarkStatus(finalStatus: WorkflowStatusResponse): boolean;
 /**
  * The primary file a {@link Recipe} operates on — the "subject" of the
  * file-first surface. A discriminated union over the ways a caller names an
@@ -355,6 +368,19 @@ export declare class Recipe {
      * `options` carries any additional per-op watermark options.
      */
     textWatermark(text: string, options?: Record<string, unknown>): Recipe;
+    /**
+     * Composite an image OVERLAY onto this file (a multi-input op). `overlay` is a
+     * secondary file-NODE (a {@link Recipe} — e.g. `client.file('logo.png')`),
+     * itself optionally processed first. Routes by THIS file's effective media:
+     * image base → `image_watermark` (stable), video base → `video_watermark`
+     * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
+     * throw locally BEFORE any upload (the planned-op gate). `options` carries the
+     * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
+     * `overlay_width`). Returns a {@link WatermarkedRecipe} (chain post-watermark
+     * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
+     * {@link textWatermark} (single-input text overlay).
+     */
+    watermark(overlay: Recipe, options?: Record<string, unknown>): WatermarkedRecipe;
     /**
      * Lower this recipe to a workflow-create payload against a resolved upload
      * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
@@ -380,6 +406,13 @@ export declare class Recipe {
      * @internal
      */
     get recipeSteps(): readonly RecipeStep[];
+    /**
+     * The primary input this recipe operates on. Read by {@link WatermarkedRecipe}
+     * to lift an overlay Recipe's input (for upload + media inference + src-job
+     * lowering) without making the ctor field public.
+     * @internal
+     */
+    get recipeInput(): FileInput;
     /**
      * Execute the recipe end-to-end: upload the input (when required), create
      * the workflow, await a terminal state (SSE with poll fallback), then
@@ -433,9 +466,57 @@ export declare class Recipe {
     private withStep;
     private lowerStep;
     private lowerCompressOptions;
+    /** Media of the original input (no chain context) — used by the probe gate. */
+    private inputMedia;
+    /**
+     * The media class a `compress` step at `uptoIndex` actually operates on. With no
+     * chain context (`uptoIndex` undefined) this is the original input's media. With
+     * context, FOLD the preceding `convert` steps: each `convert(output_format)` changes
+     * the media the next step sees (56N4chXY / N8eESzQN — a chain like
+     * `mp3 -> convert(flac) -> compress` must resolve against flac, not mp3). Reuses the
+     * synthetic-filename detection precedent from {@link MergedRecipe} (`merged.<ext>`).
+     */
     private compressMediaHint;
+    /**
+     * Whether the media a `compress` step at `uptoIndex` operates on is lossless audio.
+     * Determined by the most recent preceding `convert` target (`flac`/`wav` -> lossless)
+     * when there is one, else by the original input. Lossless is unaffected by the
+     * video/ogg guard (ogg is never lossless either way).
+     */
     private compressAudioLossless;
 }
+/**
+ * The single SDK-side source of truth for which `(wire op, base mime)`
+ * combinations the file-first `watermark()` verb may emit, and their
+ * availability. The generated typed metadata sidecar does NOT carry the
+ * supported-mime allowlist (`MimeGroupMetadata` has no `mimes` field and
+ * `per_mime_availability` is empty for these ops), so this hand table is the
+ * gate's source — PINNED to the generated `availability.json` by a conformance
+ * test (mirrors the wire-key-conformance pattern): a contract regen that
+ * changes the supported mimes or availability of `image_watermark` /
+ * `video_watermark` fails that test. The gate reads ONLY this table.
+ * @internal
+ */
+export declare const WATERMARK_CAPABILITY: {
+    readonly image_watermark: {
+        readonly image: {
+            readonly mimes: readonly ["image/jpeg", "image/png", "image/webp"];
+            readonly availability: "stable";
+        };
+        readonly image_gif: {
+            readonly mimes: readonly ["image/gif"];
+            readonly availability: "planned";
+        };
+    };
+    readonly video_watermark: {
+        readonly video: {
+            readonly mimes: readonly ["video/mp4", "video/webm"];
+            readonly availability: "beta";
+        };
+    };
+};
+/** Wire op types the file-first `watermark()` verb can route to. */
+export type WatermarkWireOp = 'image_watermark' | 'video_watermark';
 /**
  * The homogeneous fan-out builder value (FF3a). `client.files([a, b, c])`
  * returns a `FilesRecipe`; the op-chain methods (`compress`, `convert`,
@@ -776,4 +857,95 @@ export declare class ArchivedRecipe {
      */
     private wireArchiveOptions;
 }
+/**
+ * The single-output recipe you're in AFTER `file(base).watermark(overlay, …)`
+ * (FF4a). Composites an image OVERLAY onto the base (image_watermark for image
+ * bases, video_watermark for video bases — routed at lowering by the base's
+ * effective media). A multi-input op: base + overlay each enter via their own
+ * `passthrough` source job (`src_0` base, `src_1` overlay; their own preceding
+ * steps lower into those jobs), and the `watermark` job consumes them via
+ * `job_output` inputs tagged `role: base` / `role: overlay`. Post-watermark
+ * `compress`/`convert`/`thumbnail` chain onto the watermark output. Mirrors
+ * {@link MergedRecipe}. `textWatermark` is intentionally NOT a post-verb here.
+ */
+export declare class WatermarkedRecipe {
+    private readonly baseInput;
+    private readonly baseSteps;
+    private readonly overlay;
+    private readonly watermarkOptions;
+    private readonly postSteps;
+    private readonly presetDefaults?;
+    private readonly scopedPresetDefaults?;
+    private readonly client?;
+    constructor(baseInput: FileInput, baseSteps: readonly RecipeStep[], overlay: Recipe, watermarkOptions: Readonly<Record<string, unknown>>, postSteps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
+    /** Reduce the watermarked output's size. See {@link Recipe.compress}. */
+    compress(optimize?: OptimizeFor, options?: Record<string, unknown>): WatermarkedRecipe;
+    /** Change the watermarked output's format. See {@link Recipe.convert}. */
+    convert(format: string, options?: Record<string, unknown>): WatermarkedRecipe;
+    /** Thumbnail the watermarked output. Omitted dimensions are dropped from the wire options. */
+    thumbnail(options?: {
+        width?: number;
+        height?: number;
+    } & Record<string, unknown>): WatermarkedRecipe;
+    /**
+     * Lower to the watermark DAG: a `src_0` passthrough/base-steps job + a `src_1`
+     * passthrough/overlay-steps job + one `watermark` job whose `inputs[]` consume
+     * them via `job_output` (role base/overlay) and whose `operations[]` is
+     * `[image_watermark|video_watermark, ...post-watermark ops]`. `fileIds` is
+     * `[baseId, overlayId]` (upload order). Throws pre-lowering if the base media
+     * is undetectable/unsupported (the planned-op gate).
+     *
+     * @internal Consumed by {@link run}/{@link submit} (after upload) + the parity harness.
+     */
+    toWorkflowPayload(fileIds: readonly string[], callbackUrl?: string): WorkflowCreatePayload;
+    /** The number of post-watermark ops chained so far (introspection / tests). */
+    get stepCount(): number;
+    /**
+     * Execute end-to-end: upload base + overlay, create the watermark workflow,
+     * await terminal (SSE with poll fallback), then resolve ONLY the watermark
+     * output into a {@link RunResult}. Requires a client bound at construction.
+     * Mirrors {@link MergedRecipe.run}.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<RunResult>;
+    /**
+     * Fire-and-forget: upload base + overlay + create the watermark workflow
+     * (wiring `webhook` into `callback_url` when given), return a client-bound
+     * {@link Handle}. Does NOT wait for terminal status. Mirrors {@link MergedRecipe.submit}.
+     */
+    submit(webhook?: string, options?: {
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<Handle>;
+    /** Base + overlay inputs, in upload/lowering order (`[base, overlay]`). */
+    private inputsInOrder;
+    /**
+     * Validate the watermark BEFORE any upload: the base must route to a shippable
+     * wire op (throws for undetectable/unsupported/planned bases), and the overlay
+     * must be an image. Shared by {@link run}/{@link submit}. Mirrors
+     * {@link MergedRecipe.validatePreUpload}.
+     */
+    private validatePreUpload;
+    /**
+     * Upload base + overlay (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise) then create ONE watermark workflow. Validates pre-upload.
+     * Shared first half of {@link run} + {@link submit}; mirrors
+     * {@link MergedRecipe._uploadAllAndCreate}.
+     */
+    private _uploadAllAndCreate;
+    /**
+     * Lower the post-watermark chain over a synthetic input whose extension
+     * matches the watermark OUTPUT media (image→png, video→mp4) so
+     * `compress(optimize)` resolves the correct preset — mirrors
+     * {@link MergedRecipe.lowerPostSteps}.
+     */
+    private lowerPostSteps;
+    private withStep;
+}
 export {};