@gigadrive/sdk 0.8.6 → 0.9.1

package/dist/index.d.mts

@@ -937,9 +937,16 @@ interface StorageUploadSession {
 interface CreateUploadSessionInput {
     /** The object key/path the file will be stored at (e.g. `"images/photo.jpg"`). 1–1024 characters. */
     key: string;
-    /** File size in bytes. Required. */
+    /**
+     * File size in bytes: an integer, `0` or greater. `0` stores an empty object
+     * during the create call (see {@link CreateUploadSessionResponse}).
+     */
     contentLength: number;
-    /** Lowercase hex SHA-256 checksum (64 chars) of the content. Required for server-side verification. */
+    /**
+     * Lowercase hex SHA-256 checksum (64 chars) of the content. Required for
+     * server-side verification. For an empty file this must be the digest of
+     * empty input, `e3b0c442…b855`.
+     */
     checksumSha256: string;
     /** MIME content type of the file (e.g. `"image/jpeg"`). */
     contentType?: string;
@@ -952,13 +959,24 @@ interface CreateUploadSessionInput {
 interface ListStorageUploadSessionsQuery extends ListQuery, StorageEnvironmentOptions {
 }
 /**
- * Response from creating an upload session. Contains both the session metadata
- * and the resumable upload instructions (signed URL + headers).
+ * Response from creating an upload session. Contains the session metadata and
+ * either the resumable upload instructions (signed URL + headers) or, for an
+ * empty file, the object the API already stored.
+ *
+ * | Field     | `contentLength` 0                          | `contentLength` > 0             |
+ * | --------- | ------------------------------------------ | ------------------------------- |
+ * | `session` | `state: "completed"`, `uploadedAt` set     | `state: "ready"`                |
+ * | `upload`  | `null`                                     | Signed URL, method and headers  |
+ * | `object`  | The stored object                          | `null`                          |
  */
 interface CreateUploadSessionResponse {
     /** The created upload session. */
     session: StorageUploadSession;
-    /** Resumable upload instructions — use these to send the file data. */
+    /**
+     * Resumable upload instructions — use these to send the file data. `null`
+     * when `contentLength` was 0: the empty object already exists and there is
+     * nothing to send.
+     */
     upload: {
         /** The HTTP method for the byte upload (resumable upload protocol). */
         method: 'PATCH';
@@ -968,7 +986,18 @@ interface CreateUploadSessionResponse {
         headers: Record<string, string>;
         /** The URL where the object will be accessible after upload (CDN URL for public buckets). */
         publicObjectUrl: string;
-    };
+    } | null;
+    /**
+     * The stored object when the upload finished during the create call, which
+     * happens only for an empty file. `null` while bytes are still expected.
+     */
+    object: StorageObject | null;
+    /**
+     * Canonical object URL for the key, returned for every size (the same value
+     * as `upload.publicObjectUrl` when an upload instruction is returned). Older
+     * API deployments omit it.
+     */
+    publicObjectUrl?: string;
 }
 /** A byte source for uploading directly to a known signed URL. */
 interface UploadByteSource {
@@ -1012,6 +1041,8 @@ declare class StorageUploadSessionsResource extends BaseResource {
      * @param bucketRef - Canonical bucket name or deprecated UUID fallback.
      * @param data - Object key, content length, SHA-256 checksum, and optional content type / extra checksums.
      * @returns The session and resumable upload instructions (URL, method, headers).
+     *   For `contentLength: 0` the session is already `completed`, `upload` is
+     *   `null` and `object` holds the stored empty object.
      */
     create(bucketRef: StorageBucketReference, data: CreateUploadSessionInput, options?: StorageEnvironmentOptions): Promise<CreateUploadSessionResponse>;
     /** @deprecated Prefer the context-bound overload through `client.storage`. */
@@ -1127,7 +1158,10 @@ interface UploadFileResult {
     session: StorageUploadSession;
     /** The public/CDN URL of the uploaded object. */
     url: string;
-    /** The finalized storage object — present only when `waitForCompletion` was set. */
+    /**
+     * The finalized storage object — present when `waitForCompletion` was set,
+     * and always for an empty file, which the API stores during session creation.
+     */
     object?: StorageObject;
 }
 /** Options for {@link ApplicationStorageResource.uploadBatch | uploadBatch()}. */
@@ -1196,6 +1230,10 @@ declare class ApplicationStorageResource {
      * Node filesystem `path`, or a Node readable `stream` (with `contentLength`
      * and `checksumSha256`). The content type is inferred from `key` when omitted.
      *
+     * Empty (zero-byte) files are supported for every input kind. The API stores
+     * them during session creation, so no bytes are transferred, `onProgress` is
+     * not called, `waitForCompletion` does not poll, and `object` is always set.
+     *
      * @param input - What and where to upload, plus optional transfer options.
      * @returns The upload session and public object URL (and the finalized object when `waitForCompletion` is set).
      * @throws {@link UploadError} if the byte upload fails.
@@ -1563,14 +1601,381 @@ declare class ApplicationRequestsResource extends BaseResource {
     get(applicationId: string, requestId: string): Promise<NetworkRequest>;
 }
 
-/** A `*.gigadrive.app` hostname assigned to an application or deployment. */
+/**
+ * Base error class for all Gigadrive SDK errors. Every error thrown by the SDK
+ * extends this class, so you can catch all SDK errors with a single check.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.organizations.list();
+ * } catch (err) {
+ *   if (err instanceof GigadriveError) {
+ *     console.error('SDK error:', err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class GigadriveError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when authentication fails. This includes missing or invalid credentials,
+ * expired tokens, failed token refresh attempts, and failed token exchanges.
+ *
+ * Common causes:
+ * - No credentials provided and no environment variables set
+ * - Invalid `clientId`/`clientSecret` pair
+ * - Expired or revoked refresh token
+ * - API returned 401 even after an automatic token refresh retry
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const client = new GigadriveClient(); // no credentials
+ * } catch (err) {
+ *   if (err instanceof AuthenticationError) {
+ *     console.error('Auth failed:', err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class AuthenticationError extends GigadriveError {
+    constructor(message: string);
+}
+/**
+ * Thrown when an SDK operation requires local configuration that could not be
+ * resolved before making an API request.
+ *
+ * Storage operations use this error when neither an explicit application ID,
+ * `GigadriveClientConfig.applicationId`, nor the workload-provided
+ * `GIGADRIVE_APPLICATION_ID` environment variable is available.
+ */
+declare class ConfigurationError extends GigadriveError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Gigadrive API returns a non-2xx HTTP response.
+ *
+ * Contains the HTTP {@link status} code and an optional machine-readable
+ * {@link code} parsed from the response body.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.deployments.get('non-existent-id');
+ * } catch (err) {
+ *   if (err instanceof ApiError) {
+ *     console.error(`API error ${err.status}: ${err.message}`);
+ *     // err.code may contain a machine-readable error code
+ *   }
+ * }
+ * ```
+ */
+declare class ApiError extends GigadriveError {
+    /** The HTTP status code of the failed response (e.g. 404, 500). */
+    readonly status: number;
+    /** An optional machine-readable error code from the API response body. */
+    readonly code: string | undefined;
+    /**
+     * An optional finer-grained reason next to {@link code}, for example `daily_add_limit` with
+     * `quota_exceeded`, or `other_organization` with `domain_in_use`.
+     */
+    readonly reason: string | undefined;
+    constructor(message: string, status: number, code?: string, reason?: string);
+}
+/**
+ * Thrown when a file upload fails. The original cause (e.g. a network error or a
+ * transport-level error from the resumable upload) is preserved on
+ * {@link cause} for inspection.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.storage.upload({ bucket: 'assets', key, data });
+ * } catch (err) {
+ *   if (err instanceof UploadError) {
+ *     console.error('Upload failed:', err.message, err.cause);
+ *   }
+ * }
+ * ```
+ */
+declare class UploadError extends GigadriveError {
+    /** The underlying error that caused the upload to fail, if any. */
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown when an upload cannot complete because its session (and the short-lived
+ * upload URL it was issued with) expired. Create a new upload to retry.
+ *
+ * The upload URL is only valid until `session.expiresAt`; very large uploads on
+ * slow connections can exceed that window.
+ */
+declare class UploadSessionExpiredError extends UploadError {
+    constructor(message?: string, cause?: unknown);
+}
+
+/** Lifecycle state of a custom domain. Only `active` and `degraded` serve traffic. */
+type CustomDomainState = 'pending_ownership' | 'pending_dns' | 'issuing_certificate' | 'active' | 'degraded' | 'failed' | 'suspended' | 'removing';
+/** A DNS record to publish for a custom domain. */
+interface RequiredDnsRecord {
+    /** `ownership` proves control of the domain; `routing` sends traffic to Gigadrive Network. */
+    purpose: 'ownership' | 'routing';
+    /** `ALIAS` stands for the apex record your DNS provider offers (ALIAS, ANAME or CNAME flattening). */
+    type: 'TXT' | 'CNAME' | 'ALIAS';
+    /** Fully qualified record name. */
+    name: string;
+    /** Record name relative to the registrable domain, as DNS dashboards expect it (`@` for the apex). */
+    host: string;
+    /** Record value to publish. */
+    value: string;
+    /** Whether the last check found the record. */
+    status: 'ok' | 'pending' | 'mismatch';
+}
+/** What a custom domain serves. */
+interface CustomDomainTarget {
+    type: 'production' | 'branch' | 'redirect';
+    branchId: string | null;
+    redirectTo: string | null;
+    redirectStatusCode: 301 | 302 | 307 | 308 | null;
+    redirectPreservePath: boolean;
+}
+/** A problem that keeps a domain from working, with a stable code and guidance. */
+interface DomainProblem {
+    /** Stable code, for example `dns_record_missing` or `cert_blocked_caa`. */
+    code: string;
+    /** What is wrong and how to fix it. */
+    message: string;
+}
+/** A hostname attached to an application. */
+interface CustomDomain {
+    id: string;
+    applicationId: string;
+    /** Hostname in ASCII (punycode) form, lowercased. */
+    hostname: string;
+    /** Hostname for display, with international characters. */
+    unicodeHostname: string;
+    /** Registrable domain of the hostname. */
+    apex: string;
+    /** Whether the hostname is the registrable domain itself (needs an ALIAS record). */
+    isApex: boolean;
+    state: CustomDomainState;
+    suspendedReason: 'claimed' | 'admin' | 'plan_limit' | null;
+    target: CustomDomainTarget;
+    /** Whether this is the application's primary URL. */
+    primary: boolean;
+    /** The domain whose verification authorizes this hostname. */
+    ownership: {
+        name: string | null;
+        verified: boolean;
+    };
+    /** DNS records to publish, in the order to add them. */
+    requiredRecords: RequiredDnsRecord[];
+    /** Why the domain is not working yet, or `null`. */
+    error: DomainProblem | null;
+    certificate: {
+        status: 'none' | 'pending' | 'issued' | 'failed' | 'blocked_caa';
+        expiresAt: string | null;
+    };
+    /** What the last DNS check saw, or `null` before the first check. */
+    dns: {
+        checkedAt: string | null;
+        cname: string[];
+        a: string[];
+        aaaa: string[];
+        nameservers: string[];
+        pointsToEdge: boolean;
+    } | null;
+    /** When Gigadrive Network checks the domain next, or `null`. */
+    nextCheckAt: string | null;
+    activatedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a custom domain should serve. */
+type CustomDomainTargetInput = {
+    type: 'production';
+} | {
+    type: 'branch';
+    branchId: string;
+} | {
+    type: 'redirect';
+    /** Hostname to redirect to. */
+    to: string;
+    /** Defaults to `308`. */
+    statusCode?: 301 | 302 | 307 | 308;
+    /** Keep the path and query string. Defaults to `true`. */
+    preservePath?: boolean;
+};
+/** Input for {@link ApplicationDomainsResource.add}. */
+interface AddCustomDomainInput {
+    /** Hostname such as `shop.example.com` or `example.com`. Normalized by the API. */
+    hostname: string;
+    /** Defaults to production. Redirects are available on paid plans. */
+    target?: CustomDomainTargetInput;
+}
+/** Input for {@link ApplicationDomainsResource.update}. */
+interface UpdateCustomDomainInput {
+    target?: CustomDomainTargetInput;
+    /** Make this the application's primary URL. */
+    primary?: boolean;
+}
+/** A domain an organization claimed or verified. */
+interface DomainOwnership {
+    id: string;
+    organizationId: string;
+    name: string;
+    unicodeName: string;
+    status: 'pending' | 'verified';
+    verificationMethod: 'txt' | 'nameservers' | 'domain_connect' | 'legacy_fqdn_txt' | null;
+    /** The TXT record that proves control of the domain. */
+    record: {
+        type: 'TXT';
+        name: string;
+        host: string;
+        value: string;
+    };
+    error: DomainProblem | null;
+    verifiedAt: string | null;
+    nextCheckAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Options for {@link ApplicationDomainsResource.waitUntilActive}. */
+interface WaitUntilActiveOptions {
+    /** Give up after this long. Defaults to 10 minutes. */
+    timeoutMs?: number;
+    /** Time between checks. Defaults to 5 seconds. */
+    intervalMs?: number;
+    /** Stops waiting when aborted. */
+    signal?: AbortSignal;
+    /** Called with the domain whenever its state changes. */
+    onState?: (domain: CustomDomain) => void;
+}
+/** Why {@link ApplicationDomainsResource.waitUntilActive} stopped without an active domain. */
+type DomainNotActiveReason = 'timeout' | 'failed' | 'suspended' | 'removing';
+/**
+ * Thrown by {@link ApplicationDomainsResource.waitUntilActive} when the domain did not become active
+ * in time, stopped in a state that needs you to act (`failed` or `suspended`), or was removed.
+ */
+declare class DomainNotActiveError extends GigadriveError {
+    /** The domain as of the last successful check. */
+    readonly domain: CustomDomain;
+    /** `timeout` when the wait ran out, `removing` when the domain was removed, otherwise the state that ended it. */
+    readonly reason: DomainNotActiveReason;
+    constructor(domain: CustomDomain, reason: DomainNotActiveReason);
+}
+/**
+ * Custom domains attached to an application. Accessed via `client.applications.domains`.
+ *
+ * Adding a domain returns the DNS records to publish. Gigadrive Network then verifies ownership,
+ * checks DNS, issues the certificate and starts serving on its own; poll {@link get} or use
+ * {@link waitUntilActive}.
+ */
+declare class ApplicationDomainsResource extends BaseResource {
+    /**
+     * List the custom domains of an application.
+     *
+     * @example
+     * ```ts
+     * const { items } = await client.applications.domains.list('app-id');
+     * for (const domain of items) console.log(domain.hostname, domain.state);
+     * ```
+     */
+    list(applicationId: string, query?: ListQuery): Promise<Paginated<CustomDomain>>;
+    /**
+     * Attach a hostname to an application.
+     *
+     * @returns The new domain, including the `requiredRecords` to publish at your DNS provider.
+     *
+     * @example
+     * ```ts
+     * const domain = await client.applications.domains.add('app-id', { hostname: 'shop.example.com' });
+     * for (const record of domain.requiredRecords) console.log(record.type, record.host, record.value);
+     * ```
+     */
+    add(applicationId: string, data: AddCustomDomainInput): Promise<CustomDomain>;
+    /** Get one custom domain with its current state. */
+    get(applicationId: string, domainId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<CustomDomain>;
+    /**
+     * Change what a domain serves, or make it the primary domain.
+     *
+     * @example
+     * ```ts
+     * await client.applications.domains.update('app-id', 'domain-id', {
+     *   target: { type: 'redirect', to: 'www.example.com' },
+     * });
+     * ```
+     */
+    update(applicationId: string, domainId: string, data: UpdateCustomDomainInput): Promise<CustomDomain>;
+    /** Check the domain now instead of waiting for the next scheduled check. Rate limited. */
+    refresh(applicationId: string, domainId: string): Promise<CustomDomain>;
+    /** Stop serving the domain and remove it. */
+    remove(applicationId: string, domainId: string): Promise<void>;
+    /**
+     * Move a hostname another organization attached to this application. Verify the domain for your
+     * organization first and keep its TXT record published: the claim checks the record again.
+     */
+    claim(applicationId: string, hostname: string): Promise<CustomDomain>;
+    /**
+     * Poll a domain until it serves traffic.
+     *
+     * Rate limits, server errors and network failures do not end the wait; the next poll retries until
+     * the timeout. Aborting the signal or reaching the timeout also cancels a request in flight.
+     *
+     * @returns The domain once it is `active` (or `degraded`, which also serves).
+     * @throws {DomainNotActiveError} When it fails, is suspended or removed, or the timeout runs out.
+     *
+     * @example
+     * ```ts
+     * const domain = await client.applications.domains.add('app-id', { hostname: 'shop.example.com' });
+     * await client.applications.domains.waitUntilActive('app-id', domain.id, {
+     *   onState: (current) => console.log(current.state),
+     * });
+     * ```
+     */
+    waitUntilActive(applicationId: string, domainId: string, options?: WaitUntilActiveOptions): Promise<CustomDomain>;
+}
+/**
+ * Domains an organization verified. Accessed via `client.organizations.domains`.
+ *
+ * A verified domain lets every application of the organization attach hostnames at or below it
+ * without another TXT record.
+ */
+declare class OrganizationDomainsResource extends BaseResource {
+    /** List the organization's claimed and verified domains. */
+    list(organizationId: string, query?: ListQuery): Promise<Paginated<DomainOwnership>>;
+    /**
+     * Claim a domain for verification.
+     *
+     * @returns The claim, including the TXT `record` to publish.
+     *
+     * @example
+     * ```ts
+     * const claim = await client.organizations.domains.add('org-id', 'example.com');
+     * console.log(claim.record.host, claim.record.value);
+     * ```
+     */
+    add(organizationId: string, name: string): Promise<DomainOwnership>;
+    /** Get one claimed or verified domain. */
+    get(organizationId: string, domainId: string): Promise<DomainOwnership>;
+    /** Check the TXT record now. Rate limited. */
+    verify(organizationId: string, domainId: string): Promise<DomainOwnership>;
+    /** Remove a domain. Refused while custom domains still rely on it. */
+    remove(organizationId: string, domainId: string): Promise<void>;
+}
+
+/** A hostname routing to an application or deployment: a `*.gigadrive.app` name or an active custom domain. */
 interface Hostname {
     /** Unique identifier (UUID). */
     id: string;
     /** The fully-qualified hostname (e.g. `"my-app.gigadrive.app"`). */
     hostname: string;
-    /** The kind of hostname: `"DEPLOYMENT"`, `"BRANCH"`, or `"APP"`. */
-    type: 'DEPLOYMENT' | 'BRANCH' | 'APP';
+    /** The kind of hostname: `"DEPLOYMENT"`, `"BRANCH"`, `"APP"`, or `"CUSTOM"` (an active custom domain). */
+    type: 'DEPLOYMENT' | 'BRANCH' | 'APP' | 'CUSTOM';
     /** Whether this hostname currently routes traffic. */
     active: boolean;
     /** The deployment this hostname points to, if any. */
@@ -2148,6 +2553,16 @@ declare class OrganizationsResource extends BaseResource {
      * ```
      */
     readonly products: OrganizationProductsResource;
+    /**
+     * Domains the organization verified. A verified domain lets every application attach hostnames
+     * below it without another TXT record.
+     *
+     * @example
+     * ```ts
+     * const claim = await client.organizations.domains.add('org-id', 'example.com');
+     * ```
+     */
+    readonly domains: OrganizationDomainsResource;
     constructor(...args: ConstructorParameters<typeof BaseResource>);
     /**
      * List organizations the authenticated actor has access to.
@@ -2300,6 +2715,16 @@ declare class ApplicationsResource extends BaseResource {
      * ```
      */
     readonly requests: ApplicationRequestsResource;
+    /**
+     * Custom domains attached to the application.
+     *
+     * @example
+     * ```ts
+     * const domain = await client.applications.domains.add('app-id', { hostname: 'shop.example.com' });
+     * await client.applications.domains.waitUntilActive('app-id', domain.id);
+     * ```
+     */
+    readonly domains: ApplicationDomainsResource;
     constructor(httpClient: ConstructorParameters<typeof BaseResource>[0], defaultApplicationId?: string);
     /**
      * List applications the authenticated actor has access to.
@@ -2714,6 +3139,654 @@ declare class ImageOptimizationResource extends BaseResource {
     purge(deploymentId: string, source?: string): Promise<ImageCachePurgeResult>;
 }
 
+/**
+ * Byte, base64 and duration helpers shared by the queue client, the push
+ * handler and the Workflow adapter. Runtime-neutral: Web APIs only.
+ *
+ * @internal
+ */
+/**
+ * A duration as seconds, or a string such as `'500ms'`, `'30s'`, `'10m'`,
+ * `'12h'` or `'7d'`.
+ */
+type QueueDuration = number | `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`;
+/**
+ * Converts a {@link QueueDuration} to whole seconds, rounding up so a
+ * sub-second delay never becomes "now".
+ *
+ * @throws {Error} When the value is negative, not finite, or not a recognised duration string.
+ */
+declare const durationToSeconds: (value: QueueDuration) => number;
+
+/** Headers the platform sets on a push delivery. */
+declare const QUEUE_DELIVERY_HEADERS: {
+    readonly name: "x-gigadrive-queue-name";
+    readonly messageId: "x-gigadrive-queue-message-id";
+    readonly attempt: "x-gigadrive-queue-attempt";
+    readonly createdAt: "x-gigadrive-queue-created-at";
+    readonly expiresAt: "x-gigadrive-queue-expires-at";
+    readonly deadline: "x-gigadrive-queue-deadline";
+    readonly groupKey: "x-gigadrive-queue-group-key";
+    readonly deduplicationKey: "x-gigadrive-queue-deduplication-key";
+    readonly deploymentId: "x-gigadrive-queue-deployment-id";
+    readonly deploymentFallback: "x-gigadrive-queue-deployment-fallback";
+    readonly signature: "x-gigadrive-queue-signature";
+};
+/** Headers a push consumer sets on its response to steer redelivery. */
+declare const QUEUE_RESPONSE_HEADERS: {
+    /** On a 2xx: deliver again after this many seconds without spending an attempt. */
+    readonly retryAfter: "x-gigadrive-queue-retry-after";
+    /** `dead-letter`: stop retrying now, whatever the status. */
+    readonly action: "x-gigadrive-queue-action";
+    /**
+     * Reason recorded on the message. Read only together with `action:
+     * dead-letter`; for any other failure the platform records `HTTP <status>`
+     * and the first 512 bytes of the response body.
+     */
+    readonly error: "x-gigadrive-queue-error";
+};
+/** Serializes payloads to message bodies and back. */
+interface QueueCodec<T> {
+    encode(payload: T): {
+        body: string;
+        encoding: 'utf8' | 'base64';
+        contentType: string;
+    };
+    decode(body: Uint8Array, contentType: string): T;
+}
+/**
+ * The default codec. `Uint8Array` and `ArrayBuffer` payloads travel as raw
+ * bytes (`application/octet-stream`); everything else as JSON. On the way
+ * back, JSON content types are parsed, `text/*` becomes a string and
+ * anything else a `Uint8Array`.
+ */
+declare const defaultQueueCodec: QueueCodec<unknown>;
+/** Options for a {@link Queue} handle. */
+interface QueueOptions<T> extends QueueScopeOptions {
+    /** Body serialization. Defaults to {@link defaultQueueCodec}. */
+    codec?: QueueCodec<T>;
+    /**
+     * Validates every decoded payload before your handler sees it, for example
+     * a Zod schema's `parse`. A payload that fails is dead-lettered, since
+     * retrying cannot fix it.
+     */
+    validate?: (payload: unknown) => T;
+    /** Create a pull queue with default settings on the first send to a new name. Default `true`. */
+    autoCreate?: boolean;
+    /** Push signing secret. Defaults to `GIGADRIVE_QUEUE_SIGNING_SECRET`, which deployments receive. */
+    signingSecret?: string;
+    /**
+     * Accept push deliveries without a valid signature. Only for local
+     * development: anyone who can reach the endpoint could then inject messages.
+     */
+    allowUnsigned?: boolean;
+}
+/** Options for one send. */
+interface QueueSendOptions {
+    /** Deliver after this delay, such as `'10m'` or `90` seconds. Up to one year. */
+    delay?: QueueDuration;
+    /** Deliver at this time, up to one year ahead. Wins over {@link delay}. */
+    at?: Date | string | number;
+    /** Messages with the same key are delivered one at a time, in send order. */
+    groupKey?: string;
+    /** A repeat of this key within the queue's deduplication window is dropped and returns the first id. */
+    deduplicationKey?: string;
+    /** Deliver to this deployment instead of the environment's current one. */
+    deploymentId?: string;
+    /** Extra headers sent with push deliveries. */
+    headers?: Record<string, string>;
+}
+/** A message that was accepted. */
+interface QueueSent {
+    messageId: string;
+    /** `true` when the deduplication key matched an earlier message, whose id this is. */
+    deduplicated: boolean;
+    /** When the message becomes deliverable. */
+    deliverAt: Date;
+}
+/** Per-message outcome of {@link Queue.sendBatch}, in input order. */
+type QueueBatchSent = (QueueSent & {
+    error?: undefined;
+}) | {
+    messageId: null;
+    error: ApiError;
+};
+/** What a handler knows about the message it is processing. */
+interface QueueMessageMeta {
+    messageId: string;
+    queue: string;
+    /** 1 on the first delivery. Deferrals with {@link RetryLaterError} do not count. */
+    attempt: number;
+    createdAt: Date | null;
+    groupKey: string | null;
+    deduplicationKey: string | null;
+    /** Push: the deployment serving this delivery. Pull: the deployment the message was pinned to, if any. */
+    deploymentId: string | null;
+    /** Message headers, as sent. */
+    headers: Record<string, string>;
+}
+/** A leased message from {@link Queue.receive}. Settle it before its lease ends. */
+interface ReceivedQueueMessage<T> extends QueueMessageMeta {
+    payload: T;
+    receipt: string;
+    leaseExpiresAt: Date | null;
+    /** Deletes the message: processing succeeded. */
+    ack(): Promise<void>;
+    /** Releases the message for another attempt, after backoff or `delay`. */
+    retry(options?: {
+        delay?: QueueDuration;
+        error?: string;
+    }): Promise<void>;
+    /** Releases the message for later without spending an attempt. */
+    defer(delay: QueueDuration): Promise<void>;
+    /** Moves the message to the dead-letter list now. */
+    deadLetter(reason?: string): Promise<void>;
+    /** Extends the lease to `duration` from now. */
+    extendLease(duration: QueueDuration): Promise<void>;
+}
+/** A function that processes one message. Throw to retry. */
+type QueueMessageHandler<T> = (payload: T, meta: QueueMessageMeta) => unknown;
+/**
+ * A typed handle on one queue: send messages, receive and process them, or
+ * serve them as a push consumer.
+ *
+ * Get one with the top-level {@link queue} function (zero-config inside a
+ * deployment) or with `client.queues.queue(name)`.
+ *
+ * @typeParam T - The payload type.
+ */
+declare class Queue<T = unknown> {
+    /** The queue name. */
+    readonly name: string;
+    private readonly resource;
+    private readonly options;
+    private readonly codec;
+    constructor(
+    /** The queue name. */
+    name: string, resource: () => QueuesResource, options?: QueueOptions<T>);
+    private get scope();
+    private toMessage;
+    private decode;
+    /**
+     * Sends one message.
+     *
+     * @example
+     * ```ts
+     * await emails.send({ to: 'jane@example.com' });
+     * await emails.send({ to: 'jane@example.com' }, { delay: '10m' });
+     * await emails.send(reminder, { at: new Date('2027-01-01T09:00:00Z'), deduplicationKey: `reminder:${id}` });
+     * ```
+     *
+     * @throws {@link ApiError} when the message is refused, for example with
+     *   `code: 'backlog_full'` when your organization's queued storage is full.
+     *   Its `status` is 429 when sending again later may succeed and 400 when it
+     *   will not, so retry logic that keys on the status stays correct.
+     */
+    send(payload: T, options?: QueueSendOptions): Promise<QueueSent>;
+    /**
+     * Sends many messages, 100 per request. Results come back in input order;
+     * a refused message does not fail the rest; its error carries status 429
+     * when it may be sent again later and 400 when it may not. Chunks are split by count only:
+     * a request whose message bodies exceed 4 MiB in total is refused whole.
+     */
+    sendBatch(messages: readonly ({
+        payload: T;
+    } & QueueSendOptions)[]): Promise<QueueBatchSent[]>;
+    /** Deletes a message that has not been processed yet, such as a scheduled send. */
+    cancel(messageId: string): Promise<void>;
+    /**
+     * Leases messages from a pull queue. Waits up to `wait` (at most 20
+     * seconds) for the first message, then returns what is available.
+     */
+    receive(options?: {
+        maxMessages?: number;
+        wait?: QueueDuration;
+        visibilityTimeout?: QueueDuration;
+        signal?: AbortSignal;
+    }): Promise<ReceivedQueueMessage<T>[]>;
+    private toReceived;
+    /**
+     * Receives and processes messages until `signal` aborts, or until the queue
+     * is empty with `stopWhenEmpty`. A handler that returns acknowledges the
+     * message; {@link RetryLaterError} defers it, {@link NonRetryableError}
+     * dead-letters it, and any other error retries it with backoff.
+     *
+     * @example
+     * ```ts
+     * const controller = new AbortController();
+     * await jobs.consume(async (job) => processJob(job), { maxMessages: 10, signal: controller.signal });
+     * ```
+     */
+    consume(handler: QueueMessageHandler<T>, options?: {
+        maxMessages?: number;
+        wait?: QueueDuration;
+        visibilityTimeout?: QueueDuration;
+        signal?: AbortSignal;
+        stopWhenEmpty?: boolean;
+        /** Called when settling a message fails; the message is then redelivered after its lease. */
+        onError?: (error: unknown) => void;
+    }): Promise<void>;
+    /**
+     * Builds a push consumer: a `(request: Request) => Promise<Response>`
+     * function for the queue's consumer path, such as a Next.js route handler.
+     *
+     * It verifies the delivery signature, decodes the payload and calls
+     * `handler`. Returning acknowledges the message. Throw
+     * {@link RetryLaterError} to defer it without spending an attempt,
+     * {@link NonRetryableError} to dead-letter it, or anything else to retry
+     * with backoff.
+     *
+     * @example
+     * ```ts
+     * // app/api/queues/emails/route.ts
+     * export const POST = emails.handler(async (email, { attempt }) => {
+     *   await sendEmail(email);
+     * });
+     * ```
+     */
+    handler(handler: QueueMessageHandler<T>): (request: Request) => Promise<Response>;
+    /** Creates the queue, or applies `settings` to it. Use it to make a push queue from code. */
+    ensure(settings?: QueueSettings): Promise<QueueInfo>;
+    /** The queue's settings and live depth. */
+    info(): Promise<QueueInfo>;
+    /** Stops deliveries until {@link resume}. Sends are still accepted. */
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    /** Deletes every message, or only the dead letters. */
+    purge(scope?: 'all' | 'dead'): Promise<number>;
+    /** Moves dead letters back for another round of attempts. */
+    redrive(messageIds?: string[]): Promise<number>;
+    /**
+     * Creates or updates a cron schedule that sends `payload` into this queue.
+     *
+     * @example
+     * ```ts
+     * await digests.schedule('weekday-digest', { cron: '0 8 * * MON-FRI', timezone: 'Europe/Berlin', payload: { kind: 'digest' } });
+     * ```
+     */
+    schedule(name: string, schedule: {
+        cron: string;
+        timezone?: string;
+        payload?: T;
+        headers?: Record<string, string>;
+        enabled?: boolean;
+    }): Promise<QueueSchedule>;
+    /** Deletes a schedule. */
+    unschedule(name: string): Promise<void>;
+}
+
+/** Live depth and lifetime counters of a queue. */
+interface QueueStats {
+    /** Messages ready for delivery now. */
+    ready: number;
+    /** Messages delayed or scheduled for later. */
+    scheduled: number;
+    /** Messages held behind an earlier message of the same ordering group. */
+    waiting: number;
+    /** Messages being delivered or leased by a consumer. */
+    inflight: number;
+    /** Messages in the dead-letter list. */
+    dead: number;
+    /** Bytes held by the queue, dead letters included. */
+    bytes: number;
+    sent: number;
+    acknowledged: number;
+    failed: number;
+    deadLettered: number;
+    /** ISO 8601 time the oldest ready message became deliverable. */
+    oldestReadyAt: string | null;
+    /** ISO 8601 time of the next scheduled delivery. */
+    nextScheduledAt: string | null;
+}
+/** A queue in one application environment. */
+interface QueueInfo {
+    id: string;
+    name: string;
+    applicationId: string;
+    environmentId: string;
+    /** `push` queues POST each message to {@link consumerPath}; `pull` queues are drained with receive. */
+    mode: 'push' | 'pull';
+    consumerPath: string | null;
+    visibilityTimeoutSeconds: number;
+    retentionSeconds: number;
+    maxAttempts: number;
+    retryBackoffMinSeconds: number;
+    retryBackoffMaxSeconds: number;
+    deduplicationWindowSeconds: number;
+    concurrency: number | null;
+    rateLimit: {
+        count: number;
+        periodSeconds: number;
+    } | null;
+    deadLetter: boolean;
+    paused: boolean;
+    pausedAt: string | null;
+    /** How the queue was created: `config`, `api` or `auto` (first send). */
+    source: string;
+    createdAt: string;
+    updatedAt: string;
+    /** Present on list and get responses. */
+    stats?: QueueStats;
+}
+/** Settings accepted when creating or updating a queue. Omitted settings keep their current value or default. */
+interface QueueSettings {
+    /** Deployment-relative path that receives push deliveries. `null` makes the queue a pull queue. */
+    consumerPath?: string | null;
+    /** Push delivery timeout and default pull lease, 1 to 43,200 seconds. Default 60. */
+    visibilityTimeoutSeconds?: number;
+    /** How long an undelivered message is kept, 60 to 1,209,600 seconds. Default four days. */
+    retentionSeconds?: number;
+    /** Deliveries before a message is dead-lettered, 1 to 100. Default 10. */
+    maxAttempts?: number;
+    /** First retry delay. Default 5 seconds. */
+    retryBackoffMinSeconds?: number;
+    /** Longest retry delay. Default 900 seconds. */
+    retryBackoffMaxSeconds?: number;
+    /** How long a deduplication key is remembered, up to seven days. Default one day. */
+    deduplicationWindowSeconds?: number;
+    /** Most push deliveries in flight at once, 1 to 1,000. `null` restores the default of 100. */
+    concurrency?: number | null;
+    /** Most deliveries started per period. `null` removes the limit. */
+    rateLimit?: {
+        count: number;
+        periodSeconds: number;
+    } | null;
+    /** Keep exhausted messages in the dead-letter list. Default `true`. */
+    deadLetter?: boolean;
+}
+/** Scopes a call to an application and environment. */
+interface QueueScopeOptions {
+    /** Application UUID. Defaults to the client's application, `GIGADRIVE_APPLICATION_ID` in a deployment. */
+    applicationId?: string;
+    /** Environment slug or UUID. Deployed workloads omit it: their credential selects the environment. */
+    environment?: string;
+}
+/** One message on the wire. Exactly one of `json` or `body` is sent. */
+interface QueueMessageInput {
+    /** Any JSON value, sent with content type `application/json`. */
+    json?: unknown;
+    /** A string body, or base64 when {@link encoding} is `base64`. */
+    body?: string;
+    encoding?: 'utf8' | 'base64';
+    contentType?: string;
+    /**
+     * Headers forwarded with push deliveries, up to 32. Reserved and refused:
+     * `host`, `content-length`, `content-type`, `connection`,
+     * `transfer-encoding`, `te`, `upgrade`, `keep-alive`, `proxy-*`,
+     * `authorization`, `cookie`, `x-gigadrive-*`, `x-nebula-*`,
+     * `x-substrate-*`, `x-vercel-*`, `x-forwarded-*`, `x-bunny-*`,
+     * `x-real-ip`, `true-client-ip` and `forwarded`.
+     */
+    headers?: Record<string, string>;
+    /** Deliver after this many seconds, up to one year. */
+    delaySeconds?: number;
+    /** ISO 8601 time to deliver at, up to one year ahead. Wins over {@link delaySeconds}. */
+    deliverAt?: string;
+    /** Messages with the same key are delivered one at a time, in send order. */
+    groupKey?: string;
+    /** A repeat of this key within the deduplication window is dropped and returns the first message's id. */
+    deduplicationKey?: string;
+    /** Deliver to this deployment instead of the environment's current one. */
+    deploymentId?: string;
+}
+/** Outcome of one sent message. */
+type QueueSendResult = {
+    messageId: string;
+    /** `true` when the deduplication key matched an earlier message, whose id is returned. */
+    deduplicated: boolean;
+    /** ISO 8601 time the message becomes deliverable. */
+    deliverAt: string;
+    error?: undefined;
+} | {
+    messageId: null;
+    error: string;
+    /** Machine-readable reason, such as `backlog_full`. */
+    code: string;
+    /** Sending again later may succeed. */
+    retryable: boolean;
+};
+/** A stored message, as listed, fetched or received. */
+interface QueueMessageRecord {
+    id: string;
+    state: 'ready' | 'scheduled' | 'waiting' | 'inflight' | 'dead';
+    /** UTF-8 text or base64, per {@link encoding}. Listings cut it to a preview; see {@link bodyTruncated}. */
+    body: string;
+    encoding: 'utf8' | 'base64';
+    bodyTruncated: boolean;
+    contentType: string;
+    headers: Record<string, string>;
+    /** Deliveries made so far. */
+    attempts: number;
+    sizeBytes: number;
+    groupKey: string | null;
+    deduplicationKey: string | null;
+    deploymentId: string | null;
+    /** What sent the message, such as `schedule:daily-digest`. `null` for API sends. */
+    source: string | null;
+    lastError: string | null;
+    createdAt: string;
+    deliverAt: string;
+    expiresAt: string;
+    leaseExpiresAt: string | null;
+    lastDeliveredAt: string | null;
+    deadAt: string | null;
+    /** Lease token, present on received messages. Pass it to ack, nack and extend. */
+    receipt?: string;
+}
+/** A recurring send into a queue. */
+interface QueueSchedule {
+    id: string;
+    name: string;
+    /** Five-field cron expression or macro such as `@hourly`. */
+    cron: string;
+    /** IANA time zone the expression is evaluated in. */
+    timezone: string;
+    body: string;
+    contentType: string;
+    headers: Record<string, string>;
+    enabled: boolean;
+    nextRunAt: string | null;
+    lastRunAt: string | null;
+    lastMessageId: string | null;
+    lastError: string | null;
+    /** `config` for schedules declared in `gigadrive.yaml`, else `api`. */
+    source: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Fields of a schedule. Use `json` for a JSON body or `body` for text. */
+interface QueueScheduleInput {
+    cron?: string;
+    timezone?: string;
+    json?: unknown;
+    body?: string;
+    contentType?: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+}
+/** One message's outcome in a batch acknowledgement. */
+type QueueAckResult = {
+    messageId: string;
+    acknowledged: true;
+} | {
+    messageId: string;
+    acknowledged: false;
+    code: 'message_not_found' | 'receipt_mismatch';
+};
+/** Outcome of a nack. */
+type QueueNackResult = {
+    status: 'retrying';
+    deliverAt: string;
+} | {
+    status: 'dead' | 'dropped';
+};
+/**
+ * Network Queues over REST: create and manage queues and schedules, send,
+ * receive and acknowledge messages.
+ *
+ * For typed sending and consuming, prefer {@link QueuesResource.queue}, which
+ * returns a {@link Queue} handle bound to one queue name.
+ */
+declare class QueuesResource extends BaseResource {
+    private readonly defaultApplicationId?;
+    constructor(httpClient: HttpClient, defaultApplicationId?: string | undefined);
+    /**
+     * Returns a typed handle for one queue. Nothing is sent until you call a
+     * method on it, and the queue does not need to exist: the first send
+     * creates a pull queue with default settings.
+     *
+     * @typeParam T - The payload type sent and received through this queue.
+     * @param name - Queue name, unique in the environment and case-sensitive.
+     * @param options - Scope, codec and default send options.
+     */
+    queue<T = unknown>(name: string, options?: QueueOptions<T>): Queue<T>;
+    private base;
+    private path;
+    /** Lists the environment's queues with their live depth. */
+    list(options?: QueueScopeOptions): Promise<{
+        items: QueueInfo[];
+        total: number;
+    }>;
+    /** Fetches one queue with its live depth. */
+    get(name: string, options?: QueueScopeOptions): Promise<QueueInfo>;
+    /**
+     * Creates a queue. Fails with `queue_exists` when the name is taken; use
+     * {@link ensure} for create-or-update.
+     */
+    create(name: string, settings?: QueueSettings, options?: QueueScopeOptions): Promise<QueueInfo>;
+    /** Creates the queue, or applies `settings` to the existing one. */
+    ensure(name: string, settings?: QueueSettings, options?: QueueScopeOptions): Promise<QueueInfo & {
+        created: boolean;
+    }>;
+    /** Changes a queue's settings. Messages already queued keep flowing. */
+    update(name: string, settings: QueueSettings, options?: QueueScopeOptions): Promise<QueueInfo>;
+    /** Deletes a queue, its messages and its schedules. */
+    delete(name: string, options?: QueueScopeOptions): Promise<{
+        purgedMessages: number;
+    }>;
+    /** Stops deliveries. Sends are still accepted and wait until you resume. */
+    pause(name: string, options?: QueueScopeOptions): Promise<QueueInfo>;
+    /** Restarts deliveries after {@link pause}. */
+    resume(name: string, options?: QueueScopeOptions): Promise<QueueInfo>;
+    /** Deletes every message, or only the dead letters. */
+    purge(name: string, scope?: 'all' | 'dead', options?: QueueScopeOptions): Promise<{
+        purgedMessages: number;
+    }>;
+    /** Moves dead letters back to the queue with fresh attempts: all of them, or the given ids. */
+    redrive(name: string, messageIds?: string[], options?: QueueScopeOptions): Promise<{
+        redrivenMessages: number;
+    }>;
+    /**
+     * Sends one message.
+     *
+     * @param autoCreate - Create a pull queue with default settings when the name is new. Default `true`.
+     */
+    send(name: string, message: QueueMessageInput, options?: QueueScopeOptions & {
+        autoCreate?: boolean;
+    }): Promise<QueueSendResult>;
+    /**
+     * Sends up to 100 messages in one request. Results come back in input
+     * order; one rejected message does not fail the others.
+     */
+    sendBatch(name: string, messages: QueueMessageInput[], options?: QueueScopeOptions & {
+        autoCreate?: boolean;
+    }): Promise<QueueSendResult[]>;
+    /** Lists messages in one state without leasing them. Bodies are cut to a preview. */
+    listMessages(name: string, query?: {
+        state?: 'ready' | 'scheduled' | 'inflight' | 'dead';
+        offset?: number;
+        limit?: number;
+    }, options?: QueueScopeOptions): Promise<{
+        items: QueueMessageRecord[];
+        total: number;
+    }>;
+    /** Fetches one message without leasing it. */
+    getMessage(name: string, messageId: string, options?: QueueScopeOptions): Promise<QueueMessageRecord>;
+    /**
+     * Cancels a message that has not been delivered yet, such as a scheduled
+     * send you no longer want. A message being delivered or dead-lettered
+     * answers 400 `invalid_request`; settle it from its consumer, or purge or
+     * redrive dead letters.
+     */
+    deleteMessage(name: string, messageId: string, options?: QueueScopeOptions): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Leases up to `maxMessages` messages from a pull queue, waiting up to
+     * `waitSeconds` (at most 20) for the first one. Each must be acknowledged
+     * with its receipt before the lease ends, or it is delivered again.
+     */
+    receive(name: string, request?: {
+        maxMessages?: number;
+        waitSeconds?: number;
+        visibilityTimeoutSeconds?: number;
+    }, options?: QueueScopeOptions & {
+        signal?: AbortSignal;
+    }): Promise<QueueMessageRecord[]>;
+    /** Acknowledges a received message, deleting it. */
+    ack(name: string, messageId: string, receipt: string, options?: QueueScopeOptions): Promise<{
+        acknowledged: boolean;
+    }>;
+    /**
+     * Acknowledges up to 100 received messages in one request. Each settles on
+     * its own: `results` reports, in order, which were acknowledged and why any
+     * were not (`message_not_found`, `receipt_mismatch`). A batch counts one
+     * operation per started ten acknowledged messages.
+     */
+    ackBatch(name: string, messages: {
+        messageId: string;
+        receipt: string;
+    }[], options?: QueueScopeOptions): Promise<{
+        results: QueueAckResult[];
+    }>;
+    /**
+     * Releases a received message: retry with backoff (or after `delaySeconds`),
+     * or dead-letter it now with `deadLetter: true`. `countAttempt: false`
+     * reschedules without spending an attempt.
+     */
+    nack(name: string, messageId: string, request: {
+        receipt: string;
+        delaySeconds?: number;
+        deadLetter?: boolean;
+        countAttempt?: boolean;
+        error?: string;
+    }, options?: QueueScopeOptions): Promise<QueueNackResult>;
+    /** Extends a received message's lease to `visibilityTimeoutSeconds` from now. */
+    extend(name: string, messageId: string, receipt: string, visibilityTimeoutSeconds: number, options?: QueueScopeOptions): Promise<{
+        leaseExpiresAt: string;
+    }>;
+    /** Lists a queue's schedules. */
+    listSchedules(name: string, options?: QueueScopeOptions): Promise<{
+        items: QueueSchedule[];
+        total: number;
+    }>;
+    /**
+     * Creates a schedule that sends a message into the queue on a cron.
+     *
+     * @example
+     * ```ts
+     * await client.queues.createSchedule('emails', 'daily-digest', {
+     *   cron: '0 8 * * MON-FRI',
+     *   timezone: 'Europe/Berlin',
+     *   json: { kind: 'digest' },
+     * });
+     * ```
+     */
+    createSchedule(name: string, schedule: string, input: QueueScheduleInput & {
+        cron: string;
+    }, options?: QueueScopeOptions): Promise<QueueSchedule>;
+    /** Changes a schedule. Its next run is recomputed when the cron or time zone changes. */
+    updateSchedule(name: string, schedule: string, input: QueueScheduleInput, options?: QueueScopeOptions): Promise<QueueSchedule>;
+    /** Deletes a schedule. Messages it already sent stay queued. */
+    deleteSchedule(name: string, schedule: string, options?: QueueScopeOptions): Promise<{
+        deleted: boolean;
+    }>;
+    /** Sends the schedule's message now, outside its cron. */
+    triggerSchedule(name: string, schedule: string, options?: QueueScopeOptions): Promise<{
+        messageId: string;
+    }>;
+}
+
 /** Input for minting a routing-only sticky session URL. */
 interface CreateStickySessionUrlInput {
     /** Opaque application key shared by callers that must reach the same instance. */
@@ -2919,137 +3992,227 @@ declare class GigadriveClient {
     readonly stickySessions: StickySessionsResource;
     /** Managed image optimization inspection and cache purge operations. */
     readonly imageOptimization: ImageOptimizationResource;
+    /**
+     * Network Queues: manage queues and schedules, send, receive and
+     * acknowledge messages. `client.queues.queue<T>(name)` returns a typed
+     * handle bound to one queue.
+     */
+    readonly queues: QueuesResource;
     constructor(config?: GigadriveClientConfig);
 }
 
 /**
- * Base error class for all Gigadrive SDK errors. Every error thrown by the SDK
- * extends this class, so you can catch all SDK errors with a single check.
+ * Lazily iterate every item across all pages of a cursor-paginated endpoint.
+ * Pass a function that fetches one page for a given cursor; iteration stops when
+ * the API stops returning a `nextCursor`.
+ *
+ * @typeParam T - The item type.
+ * @param fetchPage - Fetches a single page for the given cursor (`undefined` for the first page).
  *
  * @example
  * ```ts
- * try {
- *   await client.organizations.list();
- * } catch (err) {
- *   if (err instanceof GigadriveError) {
- *     console.error('SDK error:', err.message);
- *   }
+ * for await (const object of paginate((cursor) =>
+ *   client.applications.storage.objects.list('app-id', 'bucket-id', { cursor }),
+ * )) {
+ *   console.log(object.key);
  * }
  * ```
  */
-declare class GigadriveError extends Error {
-    constructor(message: string);
-}
+declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Paginated<T>>): AsyncGenerator<T>;
+
 /**
- * Thrown when authentication fails. This includes missing or invalid credentials,
- * expired tokens, failed token refresh attempts, and failed token exchanges.
+ * Returns a typed handle for a Gigadrive Network queue.
  *
- * Common causes:
- * - No credentials provided and no environment variables set
- * - Invalid `clientId`/`clientSecret` pair
- * - Expired or revoked refresh token
- * - API returned 401 even after an automatic token refresh retry
+ * Inside a deployment this needs no configuration: the platform injects the
+ * credentials and the queue signing secret. Elsewhere, set
+ * `GIGADRIVE_CLIENT_ID`, `GIGADRIVE_CLIENT_SECRET` and
+ * `GIGADRIVE_APPLICATION_ID`, pass `environment`, or use
+ * `client.queues.queue(name)` on a client you configure.
+ *
+ * @typeParam T - The payload type sent and received through this queue.
+ * @param name - Queue name, unique in the environment and case-sensitive.
  *
  * @example
  * ```ts
- * try {
- *   const client = new GigadriveClient(); // no credentials
- * } catch (err) {
- *   if (err instanceof AuthenticationError) {
- *     console.error('Auth failed:', err.message);
- *   }
- * }
+ * import { queue } from '@gigadrive/sdk';
+ *
+ * export const emails = queue<{ to: string }>('emails');
+ *
+ * await emails.send({ to: 'jane@example.com' }, { delay: '10m' });
+ *
+ * // app/api/queues/emails/route.ts
+ * export const POST = emails.handler(async (email) => sendWelcomeEmail(email.to));
  * ```
  */
-declare class AuthenticationError extends GigadriveError {
-    constructor(message: string);
-}
+declare function queue<T = unknown>(name: string, options?: QueueOptions<T> & {
+    client?: GigadriveClient;
+}): Queue<T>;
+
 /**
- * Thrown when an SDK operation requires local configuration that could not be
- * resolved before making an API request.
+ * Throw from a queue handler to have the message delivered again later
+ * without spending one of its attempts. Use it for "not yet" outcomes, such
+ * as waiting on a dependency or backing off a rate-limited API.
  *
- * Storage operations use this error when neither an explicit application ID,
- * `GigadriveClientConfig.applicationId`, nor the workload-provided
- * `GIGADRIVE_APPLICATION_ID` environment variable is available.
+ * @example
+ * ```ts
+ * export const POST = emails.handler(async (email) => {
+ *   if (await provider.isThrottled()) throw new RetryLaterError('30s');
+ *   await provider.send(email);
+ * });
+ * ```
  */
-declare class ConfigurationError extends GigadriveError {
+declare class RetryLaterError extends GigadriveError {
+    /** Seconds until the next delivery. */
+    readonly delaySeconds: number;
+    constructor(delay: QueueDuration, message?: string);
+}
+/**
+ * Throw from a queue handler when retrying cannot help, such as a payload
+ * that fails validation. The message moves to the dead-letter list straight
+ * away (or is dropped when the queue keeps no dead letters), with this
+ * error's message recorded as the reason.
+ */
+declare class NonRetryableError extends GigadriveError {
     constructor(message: string);
 }
+
+/** Header carrying the delivery signature: `t=<unix ms>,v1=<hex HMAC-SHA256>`. */
+declare const QUEUE_SIGNATURE_HEADER = "x-gigadrive-queue-signature";
+/** How far a delivery's signing time may drift from the receiver's clock. */
+declare const QUEUE_SIGNATURE_TOLERANCE_MS: number;
+/** The environment variable the platform injects with the environment's queue signing secret. */
+declare const QUEUE_SIGNING_SECRET_ENV = "GIGADRIVE_QUEUE_SIGNING_SECRET";
+/** What a delivery signature covers. */
+interface QueueSignatureInput {
+    /** The environment's signing secret, `GIGADRIVE_QUEUE_SIGNING_SECRET` in a deployment. */
+    secret: string;
+    /** Queue name from `x-gigadrive-queue-name`. */
+    queue: string;
+    /** Message id from `x-gigadrive-queue-message-id`. */
+    messageId: string;
+    /** Delivery attempt from `x-gigadrive-queue-attempt`. */
+    attempt: number;
+    /** The raw request body, exactly as received. */
+    body: Uint8Array | string;
+}
 /**
- * Thrown when the Gigadrive API returns a non-2xx HTTP response.
+ * Computes the `x-gigadrive-queue-signature` header value for a delivery.
  *
- * Contains the HTTP {@link status} code and an optional machine-readable
- * {@link code} parsed from the response body.
+ * Gigadrive Network signs every push delivery this way. Use it to build
+ * signed requests when you unit-test a queue handler.
+ *
+ * @param input - Secret and delivery fields to sign.
+ * @param timestamp - Signing time in Unix milliseconds. Defaults to now.
+ * @returns The header value, `t=<ms>,v1=<hex>`.
  *
  * @example
  * ```ts
- * try {
- *   await client.deployments.get('non-existent-id');
- * } catch (err) {
- *   if (err instanceof ApiError) {
- *     console.error(`API error ${err.status}: ${err.message}`);
- *     // err.code may contain a machine-readable error code
- *   }
- * }
+ * const signature = await signQueueDelivery({ secret, queue: 'emails', messageId, attempt: 1, body });
+ * await handler(new Request(url, { method: 'POST', body, headers: { 'x-gigadrive-queue-signature': signature, ... } }));
  * ```
  */
-declare class ApiError extends GigadriveError {
-    /** The HTTP status code of the failed response (e.g. 404, 500). */
-    readonly status: number;
-    /** An optional machine-readable error code from the API response body. */
-    readonly code: string | undefined;
-    constructor(message: string, status: number, code?: string);
-}
+declare function signQueueDelivery(input: QueueSignatureInput, timestamp?: number): Promise<string>;
 /**
- * Thrown when a file upload fails. The original cause (e.g. a network error or a
- * transport-level error from the resumable upload) is preserved on
- * {@link cause} for inspection.
+ * Verifies a push delivery's `x-gigadrive-queue-signature` header.
  *
- * @example
- * ```ts
- * try {
- *   await client.storage.upload({ bucket: 'assets', key, data });
- * } catch (err) {
- *   if (err instanceof UploadError) {
- *     console.error('Upload failed:', err.message, err.cause);
- *   }
- * }
- * ```
+ * Rejects a missing or malformed header, a signature made with another
+ * secret or over different fields, and one signed more than five minutes
+ * away from `now`. {@link Queue.handler} calls this for you.
+ *
+ * @param header - The header value, or `null` when absent.
+ * @param input - Secret and the delivery fields the signature must cover.
+ * @param now - The receiver's clock in Unix milliseconds. Defaults to now.
+ * @returns `true` only for a valid, fresh signature.
  */
-declare class UploadError extends GigadriveError {
-    /** The underlying error that caused the upload to fail, if any. */
-    readonly cause: unknown;
-    constructor(message: string, cause?: unknown);
+declare function verifyQueueSignature(header: string | null | undefined, input: QueueSignatureInput, now?: number): Promise<boolean>;
+
+/** Where the Workflow SDK serves its queue handler. */
+declare const WORKFLOW_CONSUMER_PATH = "/.well-known/workflow/v1/flow";
+/** Carries the Workflow SDK's queue name, which Gigadrive queue names cannot always hold. */
+declare const WORKFLOW_QUEUE_NAME_HEADER = "x-workflow-queue-name";
+/** Options of a Workflow SDK queue send, as the Workflow runtime passes them. */
+interface WorkflowQueueSendOptions {
+    deploymentId?: string;
+    idempotencyKey?: string;
+    headers?: Record<string, string>;
+    delaySeconds?: number;
+    specVersion?: number;
+    region?: string;
+}
+/** What the Workflow runtime's handler learns about a delivery. */
+interface WorkflowQueueHandlerMeta<TMessageId extends string> {
+    attempt: number;
+    queueName: string;
+    messageId: TMessageId;
+    requestId?: string;
 }
 /**
- * Thrown when an upload cannot complete because its session (and the short-lived
- * upload URL it was issued with) expired. Create a new upload to retry.
- *
- * The upload URL is only valid until `session.expiresAt`; very large uploads on
- * slow connections can exceed that window.
+ * The queue half of a Workflow SDK World, backed by Gigadrive Network
+ * queues. It matches the World `Queue` interface of `@workflow/world`.
  */
-declare class UploadSessionExpiredError extends UploadError {
-    constructor(message?: string, cause?: unknown);
+interface WorkflowQueue<TMessageId extends string = string> {
+    getDeploymentId(): Promise<string>;
+    queue(queueName: string, message: unknown, opts?: WorkflowQueueSendOptions): Promise<{
+        messageId: TMessageId | null;
+    }>;
+    queueBatch(queueName: string, messages: readonly {
+        message: unknown;
+        opts?: WorkflowQueueSendOptions;
+    }[]): Promise<({
+        messageId: TMessageId | null;
+        error?: undefined;
+    } | {
+        messageId: null;
+        error: string;
+        retryable: boolean;
+    })[]>;
+    createQueueHandler(queueNamePrefix: string, handler: (message: unknown, meta: WorkflowQueueHandlerMeta<TMessageId>) => Promise<unknown>): (request: Request) => Promise<Response>;
+}
+/** Options for {@link createWorkflowQueue}. */
+interface WorkflowQueueOptions extends QueueScopeOptions {
+    /** Client for API calls. Defaults to a zero-config client, which works inside a deployment. */
+    client?: GigadriveClient;
+    /** Path of the Workflow handler on your deployment. Default `/.well-known/workflow/v1/flow`. */
+    consumerPath?: string;
+    /** Deployment id the Workflow runtime stamps on runs. Defaults to `GIGADRIVE_DEPLOYMENT_ID`. */
+    deploymentId?: string;
+    /**
+     * Settings for the backing queue. Without them the queue is created once
+     * with 100 attempts (the Workflow runtime gives up earlier on its own) and a
+     * 900 second delivery timeout, and later changes made in the console are
+     * kept. With them, every cold start applies them, so declare them here or
+     * in the console, not both.
+     */
+    queueSettings?: Omit<QueueSettings, 'consumerPath'>;
+    /** Push signing secret. Defaults to `GIGADRIVE_QUEUE_SIGNING_SECRET`. */
+    signingSecret?: string;
+    /** Accept unsigned deliveries. Local development only. */
+    allowUnsigned?: boolean;
 }
-
 /**
- * Lazily iterate every item across all pages of a cursor-paginated endpoint.
- * Pass a function that fetches one page for a given cursor; iteration stops when
- * the API stops returning a `nextCursor`.
+ * Runs the [Workflow SDK](https://workflow-sdk.dev) on Gigadrive Network
+ * queues: returns the World `Queue` implementation (`getDeploymentId`,
+ * `queue`, `queueBatch`, `createQueueHandler`).
  *
- * @typeParam T - The item type.
- * @param fetchPage - Fetches a single page for the given cursor (`undefined` for the first page).
+ * Every Workflow queue with the same prefix shares one push queue named
+ * after the prefix (such as `__wkf_workflow_`), created on first use and
+ * delivering to `/.well-known/workflow/v1/flow`. Sleeps and step timeouts
+ * reschedule the message without spending attempts, every message is pinned
+ * to the deployment that sent it (or the one the runtime names), and
+ * idempotency keys become deduplication keys.
+ *
+ * @typeParam TMessageId - Pass the World's `MessageId` type so the result
+ *   satisfies `@workflow/world`'s branded message ids.
  *
  * @example
  * ```ts
- * for await (const object of paginate((cursor) =>
- *   client.applications.storage.objects.list('app-id', 'bucket-id', { cursor }),
- * )) {
- *   console.log(object.key);
- * }
+ * import type { MessageId, World } from '@workflow/world';
+ * import { createWorkflowQueue } from '@gigadrive/sdk';
+ *
+ * export const world: World = { ...createWorkflowQueue<MessageId>(), ...storage, ...streamer };
  * ```
  */
-declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Paginated<T>>): AsyncGenerator<T>;
+declare function createWorkflowQueue<TMessageId extends string = string>(options?: WorkflowQueueOptions): WorkflowQueue<TMessageId>;
 
 /**
  * Server-Sent Events (SSE) parsing for streamed API responses (e.g. streamed
@@ -3068,4 +4231,4 @@ declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<
  */
 declare function parseSSEStream<T = unknown>(response: Response): AsyncGenerator<T>;
 
-export { AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, ConfigurationError, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStickySessionUrlInput, type CreateStickySessionUrlResult, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, type EmptyStorageTrashResult, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ImageCacheInspection, type ImageCachePurgeResult, ImageOptimizationResource, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageBucketsQuery, type ListStorageObjectsQuery, type ListStorageTrashQuery, type ListStorageUploadSessionsQuery, type ManagedImageUrlOptions, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, type Organization, OrganizationAiGatewayResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, type QueryValue, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, StickySessionsResource, type StorageBucket, type StorageBucketReference, StorageBucketsResource, type StorageEnvironmentOptions, type StorageObject, type StorageObjectAccess, type StorageObjectAccessOptions, type StorageObjectList, StorageObjectsResource, type StorageTrashList, StorageTrashResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type TrashedStorageObject, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, type WaitForCompletionOptions, createManagedImageUrl, paginate, parseSSEStream };
+export { type AddCustomDomainInput, AiGatewayAudioResource, type AiGatewayBudget, type AiGatewayBudgetInput, AiGatewayBudgetsResource, AiGatewayPoliciesResource, type AiGatewayPolicy, type AiGatewayPolicyInput, type AiGatewayProviderAttempt, type AiGatewayRequestEvent, type AiGatewayRequestsQuery, AiGatewayResource, type AiGatewayUsageBreakdown, type AiGatewayUsageQuery, AiGatewayUsageResource, type AiGatewayUsageSummary, AiGatewayVideosResource, type AiModel, type AiModelCapabilities, type AiModelRoutingProvider, ApiError, type ApiKey, ApiKeysResource, type Application, ApplicationDomainsResource, ApplicationEnvVarsResource, type ApplicationHostnameList, ApplicationRequestsResource, ApplicationStorageResource, ApplicationsResource, AuthenticationError, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionContentPart, type ChatCompletionMessage, type ChatCompletionRequest, type ChatCompletionResponse, type ChatCompletionUsage, ConfigurationError, type CreateApiKeyInput, type CreateApiKeyResult, type CreateDeploymentInput, type CreateEnvVarInput, type CreateOrganizationInput, type CreateStickySessionUrlInput, type CreateStickySessionUrlResult, type CreateStorageBucketInput, type CreateUploadSessionInput, type CreateUploadSessionResponse, type CustomDomain, type CustomDomainState, type CustomDomainTarget, type CustomDomainTargetInput, type Deployment, type DeploymentLog, type DeploymentLogPage, type DeploymentLogType, type DeploymentStatus, DeploymentsResource, DomainNotActiveError, type DomainOwnership, type DomainProblem, type EmptyStorageTrashResult, type EnvVar, type GatewayRequestOptions, type GatewayResult, GigadriveClient, type GigadriveClientConfig, GigadriveError, type Hostname, type HostnameAvailability, type ImageCacheInspection, type ImageCachePurgeResult, ImageOptimizationResource, type ListApiKeysQuery, type ListApplicationsQuery, type ListDeploymentLogsQuery, type ListDeploymentsQuery, type ListQuery, type ListRequestsQuery, type ListStorageBucketsQuery, type ListStorageObjectsQuery, type ListStorageTrashQuery, type ListStorageUploadSessionsQuery, type ManagedImageUrlOptions, type NetworkRequest, type NetworkRequestApplicationRef, type NetworkRequestAssetRef, type NetworkRequestBucketRef, type NetworkRequestDeploymentRef, type NetworkRequestDetails, type NetworkRequestFunctionRef, type NetworkRequestMetrics, type NetworkRequestObjectRef, type NetworkRequestSummary, type NetworkResponseDetails, type NodeReadableLike, NonRetryableError, type Organization, OrganizationAiGatewayResource, OrganizationDomainsResource, OrganizationEnvVarsResource, type OrganizationMember, OrganizationMembersResource, type OrganizationMembershipRole, type OrganizationProductAccess, type OrganizationProductEntitlement, type OrganizationProductEntitlementCheck, type OrganizationProductSubscription, OrganizationProductsResource, OrganizationsResource, type Paginated, type PresignedUrlResult, type ProductAccessMode, type ProductAccessResolutionSource, type ProductDefaultAccessPolicy, type ProductDefinition, type ProductEntitlementStatus, type ProductPlan, type ProductSubscriptionStatus, type ProviderRouting, type PullEnvVarsQuery, type PullEnvVarsResult, QUEUE_DELIVERY_HEADERS, QUEUE_RESPONSE_HEADERS, QUEUE_SIGNATURE_HEADER, QUEUE_SIGNATURE_TOLERANCE_MS, QUEUE_SIGNING_SECRET_ENV, type QueryValue, Queue, type QueueAckResult, type QueueBatchSent, type QueueCodec, type QueueDuration, type QueueInfo, type QueueMessageHandler, type QueueMessageInput, type QueueMessageMeta, type QueueMessageRecord, type QueueNackResult, type QueueOptions, type QueueSchedule, type QueueScheduleInput, type QueueScopeOptions, type QueueSendOptions, type QueueSendResult, type QueueSent, type QueueSettings, type QueueSignatureInput, type QueueStats, QueuesResource, type ReceivedQueueMessage, type RequiredDnsRecord, type ResolvedEnvVar, type ResponsesRequest, type ResponsesResponse, RetryLaterError, type RunUploadOptions, type SetProductionHostnameResult, type SpeechRequest, type StartUploadResult, StickySessionsResource, type StorageBucket, type StorageBucketReference, StorageBucketsResource, type StorageEnvironmentOptions, type StorageObject, type StorageObjectAccess, type StorageObjectAccessOptions, type StorageObjectList, StorageObjectsResource, type StorageTrashList, StorageTrashResource, type StorageUploadSession, StorageUploadSessionsResource, type TranscriptionRequest, type TranscriptionResponse, type TrashedStorageObject, type UpdateCustomDomainInput, type UpdateEnvVarInput, type UploadBatchItemResult, type UploadBatchOptions, type UploadByteSource, type UploadData, UploadError, type UploadFileInput, type UploadFileResult, type UploadPart, UploadSessionExpiredError, type UploadUrlStorage, type VideoGenerationRequest, type VideoGenerationResponse, type VideoModelList, WORKFLOW_CONSUMER_PATH, WORKFLOW_QUEUE_NAME_HEADER, type WaitForCompletionOptions, type WaitUntilActiveOptions, type WorkflowQueue, type WorkflowQueueHandlerMeta, type WorkflowQueueOptions, type WorkflowQueueSendOptions, createManagedImageUrl, createWorkflowQueue, defaultQueueCodec, durationToSeconds, paginate, parseSSEStream, queue, signQueueDelivery, verifyQueueSignature };