@giveitsmaller/sdk 0.6.0 → 0.8.0

package/dist/generated/sdk_spec/presets.js

@@ -0,0 +1,157 @@
+// CODE GENERATED — DO NOT EDIT.
+// Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
+// Regenerate with: scripts/generate.py.
+export const PRESETS = Object.freeze({
+    "image_compress": Object.freeze({
+        Size: Object.freeze({
+            "mode": "Lossy",
+            "quality": 65,
+            "metadata": "All",
+            "iccProfile": "Strip",
+            "autoOrient": true,
+            "progressive": true,
+            "outputFormat": "Smallest",
+        }),
+        Balanced: Object.freeze({
+            "mode": "Auto",
+            "quality": 80,
+            "metadata": "Sensitive",
+            "iccProfile": "Preserve",
+            "autoOrient": true,
+            "progressive": true,
+            "outputFormat": "Auto",
+        }),
+        Quality: Object.freeze({
+            "mode": "Lossless",
+            "metadata": "None",
+            "iccProfile": "Preserve",
+            "autoOrient": true,
+            "progressive": true,
+            "outputFormat": "Original",
+        }),
+    }),
+    "audio_compress": Object.freeze({
+        Size: Object.freeze({
+            "bitrate": "_96",
+            "sampleRate": "_44100",
+            "normalize": true,
+        }),
+        Balanced: Object.freeze({
+            "bitrate": "_192",
+            "sampleRate": "_44100",
+            "normalize": true,
+        }),
+        Quality: Object.freeze({
+            "bitrate": "_320",
+            "sampleRate": "_48000",
+            "normalize": false,
+        }),
+    }),
+    "video_compress": Object.freeze({
+        Size: Object.freeze({
+            "codec": "H265",
+            "crf": 30,
+            "preset": "Slow",
+            "faststart": true,
+            "audioCodec": "Aac",
+            "audioBitrate": "_96",
+        }),
+        Balanced: Object.freeze({
+            "codec": "H264",
+            "crf": 23,
+            "preset": "Medium",
+            "faststart": true,
+            "audioCodec": "Aac",
+            "audioBitrate": "_128",
+        }),
+        Quality: Object.freeze({
+            "codec": "H264",
+            "crf": 18,
+            "preset": "Slow",
+            "faststart": true,
+            "audioCodec": "Aac",
+            "audioBitrate": "_192",
+        }),
+    }),
+    "document_pdf_compress": Object.freeze({
+        Size: Object.freeze({
+            "profile": "Max",
+            "colorspace": "Grayscale",
+            "flattenForms": false,
+        }),
+        Balanced: Object.freeze({
+            "profile": "Web",
+            "colorspace": "Unchanged",
+            "flattenForms": false,
+        }),
+        Quality: Object.freeze({
+            "profile": "Archive",
+            "colorspace": "Unchanged",
+            "flattenForms": false,
+        }),
+    }),
+    "document_office_compress": Object.freeze({
+        Size: Object.freeze({
+            "imageQuality": 60,
+            "stripMacros": true,
+            "stripHiddenData": true,
+            "stripUnusedFonts": true,
+        }),
+        Balanced: Object.freeze({
+            "imageQuality": 80,
+            "stripMacros": true,
+            "stripHiddenData": false,
+            "stripUnusedFonts": false,
+        }),
+        Quality: Object.freeze({
+            "imageQuality": 92,
+            "stripMacros": false,
+            "stripHiddenData": false,
+            "stripUnusedFonts": false,
+        }),
+    }),
+    "document_odf_compress": Object.freeze({
+        Size: Object.freeze({
+            "imageQuality": 60,
+            "stripMetadata": true,
+            "stripUnusedStyles": true,
+        }),
+        Balanced: Object.freeze({
+            "imageQuality": 80,
+            "stripMetadata": true,
+            "stripUnusedStyles": false,
+        }),
+        Quality: Object.freeze({
+            "imageQuality": 92,
+            "stripMetadata": false,
+            "stripUnusedStyles": false,
+        }),
+    }),
+    "document_epub_compress": Object.freeze({
+        Size: Object.freeze({
+            "imageQuality": 60,
+            "fontSubsetting": true,
+            "stripUnusedCss": true,
+        }),
+        Balanced: Object.freeze({
+            "imageQuality": 80,
+            "fontSubsetting": true,
+            "stripUnusedCss": false,
+        }),
+        Quality: Object.freeze({
+            "imageQuality": 92,
+            "fontSubsetting": false,
+            "stripUnusedCss": false,
+        }),
+    }),
+});
+/** Lookup the shipped preset cell for (mediaOp, level). Throws on unknown keys. */
+export function shippedDefaultsFor(mediaOp, level) {
+    const group = PRESETS[mediaOp];
+    if (!group)
+        throw new Error(`Unknown preset mediaOp: ${mediaOp}`);
+    const cell = group[level];
+    if (!cell)
+        throw new Error(`Unknown preset level for ${mediaOp}: ${level}`);
+    return cell;
+}

package/dist/generated/sdk_spec/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SDK_SPEC_VERSION: "1.2.0";
+export declare const PRESET_VERSION: "1.0";
+export declare const PRESET_CONFIG_HASH: "sha256:35aeb0b6b86edd9814ace5b75cfeef8a7b1432ecb8e4d5ee8b38d9187a0b45eb";

package/dist/generated/sdk_spec/version.js

@@ -0,0 +1,6 @@
+// CODE GENERATED — DO NOT EDIT.
+// Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
+// Regenerate with: scripts/generate.py.
+export const SDK_SPEC_VERSION = "1.2.0";
+export const PRESET_VERSION = "1.0";
+export const PRESET_CONFIG_HASH = "sha256:35aeb0b6b86edd9814ace5b75cfeef8a7b1432ecb8e4d5ee8b38d9187a0b45eb";

package/dist/gisl.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Ergonomic-layer entrypoint for the GISL SDK. Wraps the low-level
+ * `GislClient` (transport, multipart, SSE, downloads) with credential-chain
+ * resolution + ergonomic factory functions. Designed to feel native to a
+ * developer writing `import { gisl } from '@giveitsmaller/sdk'` and then
+ * `const client = await gisl.create();`.
+ *
+ * Scope of this card (T1, `wVU4xHx3`):
+ * - `gisl.create()` — full functionality. Resolves credentials + endpoint
+ *   via `credentials.ts`, fails early with `GislMissingCredentialsError`
+ *   when no apiKey is found AND the caller hasn't opted into cookie-mode
+ *   or anonymous mode.
+ * - INTERNAL `_gislAnonymous` capability + `ANONYMOUS_ALLOWLIST` constant
+ *   are wired but NOT publicly exported until the free-tier launch decides
+ *   which operations are anonymous-capable (plan §12 open decision). A
+ *   non-empty allowlist + the named export will arrive in a follow-up PR
+ *   the moment user picks; this card avoids shipping a dead `gisl.anonymous()`.
+ */
+import { GislClient } from './client.js';
+import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError } from './errors.js';
+import { type ResolveCredentialsOptions, type ResolveEndpointOptions } from './credentials.js';
+import type { GislClientConfig } from './types.js';
+import { OperationBuilder } from './builder.js';
+import { MergeBuilder, type Asset, type MergeOptions } from './merge.js';
+import { PresetDefaults } from './ergonomic/presets/index.js';
+import { Recipe, type FileInput } from './file-first.js';
+/**
+ * Operations that may be invoked on a `gisl.anonymous()` client without
+ * raising `GislFeatureRequiresAuthError`. Empty until the free-tier launch
+ * decision lands (plan §12). Typed as a `readonly []` tuple (NOT
+ * `readonly string[]`) so the audit-gate compile-time assertion in
+ * `_audit.ts` fires if a future PR widens this without flipping the
+ * parking-decision + adding the public `gisl.anonymous()` export.
+ *
+ * Consumers must not depend on its emptiness today — only `package.json`
+ * `exports` keeps deep-imports blocked; the marker is internal.
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ALLOWLIST: readonly [];
+export interface GislCreateOptions extends ResolveCredentialsOptions, ResolveEndpointOptions, Omit<GislClientConfig, 'baseUrl' | 'apiKey' | 'useSessionCookie'> {
+    /**
+     * Layered ergonomic preset defaults (T4a / VhIj4S7T). Built via
+     * `presetDefaults().<cell>(level, overrides?)…`. The resolver wiring
+     * that consumes this slot lands in T4b — until then, supplying this
+     * field is a no-op at workflow-create time.
+     */
+    readonly presetDefaults?: PresetDefaults;
+}
+/**
+ * Construct an ergonomic-layer client. Resolves the API key + base URL via
+ * the credential chain (see `credentials.ts`) and constructs a low-level
+ * `GislClient`. Throws `GislMissingCredentialsError` synchronously before
+ * any HTTP I/O when no key is found AND neither `useSessionCookie` nor
+ * `allowAnonymous` is set.
+ *
+ * Cookie-mode (`useSessionCookie: true`) explicitly bypasses the missing-
+ * credentials check — browser SPAs that drive auth via `client.login()`
+ * legitimately have no apiKey at construction time.
+ */
+export declare function create(opts?: GislCreateOptions): Promise<ErgonomicClient>;
+/**
+ * The ergonomic-client surface: `GislClient` (verbatim low-level API)
+ * plus three ergonomic op-builder factories. Intersection type — at
+ * runtime the Proxy synthesises the three methods on-demand. `input`
+ * accepts `string | Blob` matching `GislClient.uploadFile` (codex r1
+ * low 89cae59f4f04 — Blob/File uploads were previously rejected by the
+ * ergonomic factory's narrower string-only typing).
+ */
+export type ErgonomicClient = GislClient & {
+    /**
+     * File-first entry point (FF2a). Returns an immutable {@link Recipe} you
+     * call operations on (`.compress()` / `.convert()` / `.thumbnail()` /
+     * `.textWatermark()`), chaining sequentially. A bare string is a filesystem
+     * path; pass a {@link FileInput} (e.g. `fileInput.uploadId(...)`) to reuse a
+     * pre-uploaded file. `key` is RESULT-addressing only — never input wiring.
+     * Execution (`run()`) lands in FF2b.
+     */
+    file(input: string | Blob | FileInput, key?: string): Recipe;
+    compress(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
+    convert(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
+    thumbnail(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
+    /**
+     * Merge ordered-sequence factory (T3). Accepts a variadic list of assets
+     * (strings/Blobs/`handle()`/`asset()`) optionally terminated by a
+     * `MergeOptions` object. Returns a `MergeBuilder`; pin the play order
+     * with `.sequence(...)`.
+     */
+    merge(...args: ReadonlyArray<string | Blob | Asset | MergeOptions>): MergeBuilder;
+    /**
+     * Immutable scoped derive (T4c — `ULAlOP6j`). Returns a new client
+     * with `defaults` layered on top of the parent's scoped defaults.
+     * Use for the "next N jobs" pattern — e.g. an evening batch needing
+     * higher quality without mutating the long-lived parent client.
+     *
+     * Identity: the derived client shares the SAME underlying low-level
+     * transport (baseUrl, apiKey, headers, timeouts, multipart, session
+     * cookie) by reference. Safe for concurrent parent + derived use.
+     *
+     * Merge semantics (codex r2 #5 — scalar leaf): scoped per-cell fields
+     * override the parent's scoped where defined; the parent's
+     * `client.presetDefaults` layer is unaffected and still contributes
+     * fields the scoped layer doesn't set.
+     *
+     * Does NOT re-resolve credentials. The derive never calls the
+     * credential chain or constructor — it composes new closure values
+     * over the existing transport.
+     */
+    withPresetDefaults(defaults: PresetDefaults): ErgonomicClient;
+};
+/**
+ * The `gisl` namespace — primary ergonomic-layer entry point.
+ * Exports `gisl.create()` only for v0.7; `gisl.anonymous()` lands once
+ * the anonymous-capable operation allowlist is non-empty (plan §12).
+ */
+export declare const gisl: {
+    readonly create: typeof create;
+};
+export type { Environment } from './credentials.js';
+/** @internal */
+export declare function _internalAnonymous(opts?: GislCreateOptions): Promise<GislClient>;
+export { GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError };

package/dist/gisl.js

@@ -0,0 +1,283 @@
+/**
+ * Ergonomic-layer entrypoint for the GISL SDK. Wraps the low-level
+ * `GislClient` (transport, multipart, SSE, downloads) with credential-chain
+ * resolution + ergonomic factory functions. Designed to feel native to a
+ * developer writing `import { gisl } from '@giveitsmaller/sdk'` and then
+ * `const client = await gisl.create();`.
+ *
+ * Scope of this card (T1, `wVU4xHx3`):
+ * - `gisl.create()` — full functionality. Resolves credentials + endpoint
+ *   via `credentials.ts`, fails early with `GislMissingCredentialsError`
+ *   when no apiKey is found AND the caller hasn't opted into cookie-mode
+ *   or anonymous mode.
+ * - INTERNAL `_gislAnonymous` capability + `ANONYMOUS_ALLOWLIST` constant
+ *   are wired but NOT publicly exported until the free-tier launch decides
+ *   which operations are anonymous-capable (plan §12 open decision). A
+ *   non-empty allowlist + the named export will arrive in a follow-up PR
+ *   the moment user picks; this card avoids shipping a dead `gisl.anonymous()`.
+ */
+import { GislClient } from './client.js';
+import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError, } from './errors.js';
+import { resolveApiKey, resolveEndpoint, } from './credentials.js';
+import { OperationBuilder } from './builder.js';
+import { MergeBuilder, asset } from './merge.js';
+import { PresetDefaults } from './ergonomic/presets/index.js';
+import { Recipe, fileInput } from './file-first.js';
+// ---------------------------------------------------------------------------
+// Anonymous-capable operation allowlist (internal)
+// ---------------------------------------------------------------------------
+/**
+ * Operations that may be invoked on a `gisl.anonymous()` client without
+ * raising `GislFeatureRequiresAuthError`. Empty until the free-tier launch
+ * decision lands (plan §12). Typed as a `readonly []` tuple (NOT
+ * `readonly string[]`) so the audit-gate compile-time assertion in
+ * `_audit.ts` fires if a future PR widens this without flipping the
+ * parking-decision + adding the public `gisl.anonymous()` export.
+ *
+ * Consumers must not depend on its emptiness today — only `package.json`
+ * `exports` keeps deep-imports blocked; the marker is internal.
+ *
+ * @internal
+ */
+export const ANONYMOUS_ALLOWLIST = [];
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Construct an ergonomic-layer client. Resolves the API key + base URL via
+ * the credential chain (see `credentials.ts`) and constructs a low-level
+ * `GislClient`. Throws `GislMissingCredentialsError` synchronously before
+ * any HTTP I/O when no key is found AND neither `useSessionCookie` nor
+ * `allowAnonymous` is set.
+ *
+ * Cookie-mode (`useSessionCookie: true`) explicitly bypasses the missing-
+ * credentials check — browser SPAs that drive auth via `client.login()`
+ * legitimately have no apiKey at construction time.
+ */
+export async function create(opts = {}) {
+    // Extract presetDefaults BEFORE `_createInternal` destructures and
+    // strips it — the resolver needs the value for every operation call,
+    // not just construction. `_createInternal` still strips the slot
+    // from the low-level `GislClient` config (no leak into transport).
+    const presetDefaults = opts.presetDefaults;
+    return wrapErgonomic(await _createInternal(opts), presetDefaults);
+}
+/**
+ * Compose the ergonomic operation surface (`.compress` / `.convert` /
+ * `.thumbnail`) on top of a `GislClient` via Proxy — matches the
+ * `wrapAnonymous` precedent (no prototype mutation). Layer order is
+ * builder-wrap INSIDE, anonymous-wrap OUTSIDE so the allowlist gate
+ * runs last in `_internalAnonymous` (see `_createInternal`).
+ */
+function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'file') {
+                // File-first entry point — the subject of the file-first surface.
+                // A bare string is a filesystem path, a Blob/File an in-memory input;
+                // pass a `FileInput` (e.g. `fileInput.uploadId(...)`) to reuse a
+                // pre-uploaded file. `key` is RESULT-addressing only. The Proxy's
+                // closure forwards the same preset-defaults references the op builders
+                // get, so a file-first `compress()` resolves presets identically.
+                return (input, key) => {
+                    const resolved = typeof input === 'string'
+                        ? fileInput.path(input)
+                        : input instanceof Blob
+                            ? fileInput.blob(input)
+                            : input;
+                    return new Recipe(resolved, key, [], presetDefaults, scopedPresetDefaults, target);
+                };
+            }
+            if (prop === 'compress' || prop === 'convert' || prop === 'thumbnail') {
+                return (input, options = {}) => {
+                    // T4b — pass client-scope presetDefaults into the builder so
+                    // .run()/.submit() consult the preset resolver. The Proxy's
+                    // closure carries the same reference for every per-call
+                    // builder construction.
+                    // T4c — also forward the scopedPresetDefaults closure (from
+                    // `withPresetDefaults`); `undefined` on root clients.
+                    return new OperationBuilder(target, prop, input, options, presetDefaults, scopedPresetDefaults);
+                };
+            }
+            if (prop === 'withPresetDefaults') {
+                // T4c — immutable scoped derive. Computes mergedScoped =
+                // (parent.scoped === undefined ? new : PresetDefaults.merge(
+                // parent.scoped, new)) and returns a new Proxy wrapping the SAME
+                // underlying GislClient `target` (identity preservation —
+                // baseUrl / apiKey / headers / timeouts / multipart / session-
+                // cookie all by reference). Does NOT re-trigger _createInternal
+                // / resolveApiKey (codex r2 invariant — derives never re-read
+                // env or profile).
+                return (defaults) => {
+                    const mergedScoped = scopedPresetDefaults === undefined
+                        ? defaults
+                        : PresetDefaults.merge(scopedPresetDefaults, defaults);
+                    return wrapErgonomic(target, presetDefaults, mergedScoped);
+                };
+            }
+            if (prop === 'merge') {
+                // merge(...) accepts a mix of:
+                // - Asset objects (handle/path) — declared explicitly
+                // - string | Blob — wrapped via `asset()`
+                // - MergeOptions (always LAST) — sniffed by the absence of asset shape
+                return (...args) => {
+                    let mergeOpts = {};
+                    let last = args.length > 0 ? args[args.length - 1] : undefined;
+                    if (isMergeOptions(last)) {
+                        mergeOpts = last;
+                        args = args.slice(0, -1);
+                    }
+                    const declared = args.map((a) => {
+                        if (typeof a === 'string' || a instanceof Blob)
+                            return asset(a);
+                        // Asset (handle or path).
+                        return a;
+                    });
+                    return new MergeBuilder(target, declared, mergeOpts);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Sniff whether the final argument to `merge(...)` is a `MergeOptions`
+ * object rather than an `Asset`. Heuristic: an `Asset` always has a
+ * `type` field with `'handle'` or `'path'`; a `MergeOptions` does not.
+ */
+function isMergeOptions(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (typeof value.then === 'function')
+        return false;
+    if (value instanceof Blob)
+        return false;
+    const t = value.type;
+    if (t === 'handle' || t === 'path' || t === 'clip')
+        return false;
+    return true;
+}
+/**
+ * Inner factory shared by `create()` and `_internalAnonymous()` — extracted
+ * so the anonymous branch can ENTIRELY skip the credential chain rather
+ * than just suppressing its throw (codex r1 high e9e1c1182d56 — without
+ * this, env-resolved keys would silently attach an Authorization header
+ * to anonymous calls and defeat the parking guarantee).
+ *
+ * @internal
+ */
+async function _createInternal(opts) {
+    const { apiKey: explicitKey, profile, profilePath, useSessionCookie, baseUrl, environment, allowAnonymous, 
+    // T4a slot — stripped from transportConfig so it does not leak
+    // into the low-level `GislClientConfig` spread. The T4b resolver
+    // reads `opts.presetDefaults` directly via its own path.
+    presetDefaults: _presetDefaults, ...transportConfig } = opts;
+    void _presetDefaults;
+    const resolvedBaseUrl = resolveEndpoint({ baseUrl, environment });
+    // Anonymous mode entirely BYPASSES the credential chain. Any env / profile
+    // key that happens to exist on the host MUST NOT leak into the request
+    // (codex r1 high e9e1c1182d56). Cookie-mode also bypasses, since the
+    // caller authenticates via session cookie later.
+    if (allowAnonymous === true) {
+        const config = {
+            baseUrl: resolvedBaseUrl,
+            ...transportConfig,
+        };
+        if (useSessionCookie !== undefined) {
+            config.useSessionCookie = useSessionCookie;
+        }
+        return wrapAnonymous(new GislClient(config));
+    }
+    // Cookie-mode: skip env / profile resolution entirely UNLESS the caller
+    // ALSO passes an explicit `{apiKey}` (the mixed case is legitimate — a
+    // cookie-authenticated SPA may also send a server-issued API key). Codex
+    // r2 medium 913e4d8073f5 — without this, useSessionCookie=true could
+    // silently pick up an ambient GISL_API_KEY or fail on a malformed local
+    // profile, neither of which a cookie-auth caller expects.
+    let resolvedKey;
+    if (useSessionCookie === true && (explicitKey === undefined || explicitKey === '')) {
+        resolvedKey = null;
+    }
+    else {
+        resolvedKey = await resolveApiKey({
+            apiKey: explicitKey,
+            profile,
+            profilePath,
+            useSessionCookie,
+        });
+    }
+    if (resolvedKey === null && useSessionCookie !== true) {
+        throw new GislMissingCredentialsError('No API key found via explicit arg, GISL_API_KEY env, or ~/.gisl/credentials profile. ' +
+            'Pass {apiKey} explicitly, set GISL_API_KEY, populate ~/.gisl/credentials, ' +
+            'or pass {useSessionCookie: true} for browser session-cookie authentication.');
+    }
+    const config = {
+        baseUrl: resolvedBaseUrl,
+        ...transportConfig,
+    };
+    if (resolvedKey !== null) {
+        config.apiKey = resolvedKey;
+    }
+    if (useSessionCookie !== undefined) {
+        config.useSessionCookie = useSessionCookie;
+    }
+    return new GislClient(config);
+}
+/**
+ * Wrap a `GislClient` so calls to non-allowlisted operations throw
+ * `GislFeatureRequiresAuthError` BEFORE any I/O. This is the internal
+ * capability that backs `gisl.anonymous()` once the allowlist is non-empty.
+ *
+ * @internal
+ */
+function wrapAnonymous(client) {
+    // Explicit Set<string> — `ANONYMOUS_ALLOWLIST` is currently typed as the
+    // empty tuple `readonly []` (audit-gate parking-invariant in _audit.ts).
+    // Without this, `new Set(ANONYMOUS_ALLOWLIST)` would infer `Set<never>`.
+    const allowlist = new Set(ANONYMOUS_ALLOWLIST);
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== 'function' || typeof prop !== 'string') {
+                return value;
+            }
+            // Allow base infrastructure methods that don't carry user operations.
+            if (prop.startsWith('_') ||
+                prop === 'login' ||
+                prop === 'logout' ||
+                prop === 'getSchema' ||
+                prop === 'submitContact' ||
+                prop === 'constructor') {
+                return value.bind(target);
+            }
+            // Allowlist gate: throw if the op isn't approved for anonymous use.
+            if (!allowlist.has(prop)) {
+                return () => {
+                    throw new GislFeatureRequiresAuthError(prop, `Operation '${prop}' is not available on an anonymous client. ` +
+                        `Use gisl.create({apiKey}) for authenticated access, or wait for the operation to be added to the anonymous allowlist.`);
+                };
+            }
+            return value.bind(target);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Public `gisl` namespace
+// ---------------------------------------------------------------------------
+/**
+ * The `gisl` namespace — primary ergonomic-layer entry point.
+ * Exports `gisl.create()` only for v0.7; `gisl.anonymous()` lands once
+ * the anonymous-capable operation allowlist is non-empty (plan §12).
+ */
+export const gisl = {
+    create,
+};
+// `_internalAnonymous` is the implementation behind the future public
+// `gisl.anonymous()` export. Kept underscore-prefixed so it does not
+// reach the audit gate as a public symbol.
+/** @internal */
+export async function _internalAnonymous(opts = {}) {
+    return _createInternal({ ...opts, allowAnonymous: true });
+}
+// Re-export error types for callers that want to `instanceof` them.
+export { GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError };

package/dist/http-downloader.d.ts

@@ -0,0 +1,9 @@
+import type { Downloader } from './file-first.js';
+/**
+ * Streams a (typically pre-signed) URL to a local path without buffering the
+ * whole body in memory. Pre-signed download URLs require no SDK auth, so this
+ * issues a plain unauthenticated `fetch`.
+ */
+export declare class HttpDownloader implements Downloader {
+    downloadTo(url: string, destPath: string): Promise<void>;
+}

package/dist/http-downloader.js

@@ -0,0 +1,55 @@
+/**
+ * Node-only streaming {@link Downloader} implementation.
+ *
+ * Lives in its own module so the framework-free `file-first.ts` stays
+ * Node-import-free; the Node `fs`/`stream` imports are isolated here.
+ */
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { GislNetworkError, GislSinkError } from './errors.js';
+/**
+ * Streams a (typically pre-signed) URL to a local path without buffering the
+ * whole body in memory. Pre-signed download URLs require no SDK auth, so this
+ * issues a plain unauthenticated `fetch`.
+ */
+export class HttpDownloader {
+    async downloadTo(url, destPath) {
+        // Source-read failures surface as GislNetworkError to match the PHP
+        // StreamingDownloader (both raise GislNetworkError when the output URL
+        // cannot be fetched); a dest-write failure is GislSinkError(write_failed)
+        // on the RunResult sink side. Parity-critical: the FF1 sink contract tells
+        // callers to narrow with instanceof, so the source-read error type must
+        // match across languages.
+        let res;
+        try {
+            res = await fetch(url);
+        }
+        catch (cause) {
+            // A rejected fetch (DNS, TCP, TLS, mid-flight disconnect) must surface as
+            // GislNetworkError too — not the raw TypeError — so callers can narrow
+            // every download-source failure with `instanceof GislNetworkError`
+            // (codex review medium).
+            throw new GislNetworkError(`Failed to fetch download source: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (!res.ok) {
+            throw new GislNetworkError(`Download failed with status ${res.status}`);
+        }
+        if (res.body === null) {
+            throw new GislNetworkError('Download response had no body');
+        }
+        // `fetch`'s WHATWG ReadableStream and Node's `stream/web` ReadableStream
+        // are structurally the same at runtime but typed in two different lib
+        // declarations; the cast bridges them for `Readable.fromWeb`.
+        try {
+            await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+        }
+        catch {
+            // Destination-write failures (unwritable dir, disk full, …) surface as
+            // GislSinkError(write_failed) to match the PHP StreamingDownloader — a
+            // raw Node ENOENT would otherwise leak through the parity-critical sink
+            // contract. Source-read failures are handled above as GislNetworkError.
+            throw new GislSinkError(`Failed to stream download to destination: ${destPath}`, { reason: 'write_failed' });
+        }
+    }
+}