@stackshift-cloud/sdk 1.3.0 → 1.4.0

package/dist/s2-upload.js

@@ -0,0 +1,49 @@
+import { ChunkedUploadController, putBlob } from './upload-controller.js';
+/** Bind these callbacks to authenticated application-server routes. Never put permanent S3 credentials in a browser. */
+export class S2Uploader {
+    controller;
+    constructor(backend, store) {
+        this.controller = new ChunkedUploadController({
+            create: (file, request) => backend.create({ ...request, size: file.size }),
+            resume: (context) => backend.resume(context),
+            uploadPart: async (session, partNumber, chunk, checksumSHA256, callbacks) => {
+                const signed = await backend.signPart(session, { partNumber, size: chunk.size, checksumSHA256 });
+                await putBlob(signed.url, chunk, callbacks, signed.headers);
+            },
+            complete: (session) => backend.complete(session),
+            cancel: (session) => backend.cancel(session),
+        }, store);
+    }
+    upload(file, request, options = {}) {
+        if (file.size === 0)
+            return Promise.reject(new Error('Use a single presigned PUT for an empty object'));
+        return this.controller.upload(file, request, { ...options, requireMatchingFile: true });
+    }
+    cancel(resumeKey) { return this.controller.cancel(resumeKey); }
+}
+/** Use an account-specific namespace, and clear it on logout. Stored sessions contain temporary upload capabilities. */
+export function createS2ResumeStore(storage, namespace) {
+    if (!namespace.trim())
+        throw new Error('An account-specific upload namespace is required');
+    const key = (value) => `stackshift:s2:${encodeURIComponent(namespace)}:${encodeURIComponent(value)}`;
+    return {
+        async get(value) {
+            const raw = storage.getItem(key(value));
+            if (raw === null)
+                return undefined;
+            let record;
+            try {
+                record = JSON.parse(raw);
+            }
+            catch {
+                throw new Error('Saved upload state is unreadable; clear it before starting again');
+            }
+            if (!record || record.key !== value || typeof record.fingerprint !== 'string' || !record.session?.id) {
+                throw new Error('Saved upload state is invalid; clear it before starting again');
+            }
+            return record;
+        },
+        async set(record) { storage.setItem(key(record.key), JSON.stringify(record)); },
+        async delete(value) { storage.removeItem(key(value)); },
+    };
+}

package/dist/s2.d.ts

@@ -0,0 +1,34 @@
+import type { StackShift } from './client.js';
+import type { S2UploadBackend } from './s2-upload.js';
+import type { ChunkUploadSession, UploadedPart } from './upload-controller.js';
+export interface S2Object {
+    id: string;
+    version_id: string;
+    bucket_id: string;
+    key: string;
+    size: number;
+    etag: string;
+    checksum_sha256: string;
+    content_type: string;
+}
+/** Server-side adapter. Authorize the application's user and destination before forwarding browser requests. */
+export declare class S2UploadsClient implements S2UploadBackend<S2Object> {
+    private readonly client;
+    private readonly path;
+    constructor(client: StackShift, bucketID: string);
+    create(input: {
+        key: string;
+        size: number;
+        mimeType: string;
+    }): Promise<ChunkUploadSession>;
+    resume(context: string): Promise<ChunkUploadSession>;
+    signPart(session: ChunkUploadSession, part: UploadedPart): Promise<{
+        url: string;
+        headers: {
+            [k: string]: string;
+        };
+    }>;
+    complete(session: ChunkUploadSession): Promise<S2Object>;
+    cancel(session: ChunkUploadSession): Promise<void>;
+    private action;
+}

package/dist/s2.js

@@ -0,0 +1,31 @@
+/** Server-side adapter. Authorize the application's user and destination before forwarding browser requests. */
+export class S2UploadsClient {
+    client;
+    path;
+    constructor(client, bucketID) {
+        this.client = client;
+        if (!bucketID)
+            throw new Error('A bucket ID is required');
+        this.path = `/buckets/${encodeURIComponent(bucketID)}/uploads`;
+    }
+    create(input) {
+        return this.client.request(this.path, { method: 'POST', body: input });
+    }
+    resume(context) {
+        return this.action('resume', context);
+    }
+    async signPart(session, part) {
+        const result = await this.action('sign-part', session.uploadToken, part);
+        const headers = Object.fromEntries(Object.entries(result.headers ?? {}).map(([name, values]) => [name, values.join(', ')]));
+        return { url: result.url, headers };
+    }
+    complete(session) {
+        return this.action('complete', session.uploadToken);
+    }
+    async cancel(session) {
+        await this.action('cancel', session.uploadToken);
+    }
+    action(action, token, part) {
+        return this.client.request(`${this.path}/actions`, { method: 'POST', body: { action, token, part } });
+    }
+}

package/dist/support-action-manifest.d.ts

@@ -0,0 +1,3 @@
+import type { SupportActionDescriptor } from './support-action-types.js';
+/** Validate action declarations locally; server registration and destination checks remain authoritative. */
+export declare function validateSupportActionCatalog(version: string, actions: SupportActionDescriptor[]): void;

package/dist/support-action-manifest.js

@@ -0,0 +1,40 @@
+import { actionCheck } from './support-actions.js';
+const reserved = new Set(['customer', 'customer_id', 'external_customer_id', 'external_id', 'contact_id', 'workspace_id', 'environment_id', 'inbox_id', 'conversation_id', 'installation_id', 'tenant_id', 'user_id', 'organization_id', 'authorization', 'scope', 'identity', 'credentials', 'secret', 'token']);
+function endpoint(value) {
+    if (!value || value.length > 2048)
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' && !!url.hostname && !url.username && !url.password && !url.search && !url.hash && !value.includes('?') && !value.includes('#');
+    }
+    catch {
+        return false;
+    }
+}
+function fields(schema, input) {
+    actionCheck(schema && typeof schema === 'object' && !Array.isArray(schema) && Object.keys(schema).length <= 32, 'invalid_catalog');
+    for (const [name, field] of Object.entries(schema)) {
+        actionCheck(/^[a-z][a-z0-9_]{0,63}$/.test(name) && (!input || (!reserved.has(name) && !/^(customer_|tenant_|auth_)/.test(name))), 'invalid_catalog');
+        actionCheck(field && typeof field.required === 'boolean' && Object.keys(field).every(k => ['type', 'required', 'max_length', 'minimum', 'maximum', 'enum'].includes(k)), 'invalid_catalog');
+        if (field.type === 'string')
+            actionCheck(Number.isInteger(field.max_length) && field.max_length >= 1 && field.max_length <= 16000 && field.minimum === undefined && field.maximum === undefined && (!field.enum || (Array.isArray(field.enum) && field.enum.length <= 64 && new Set(field.enum).size === field.enum.length && field.enum.every(v => typeof v === 'string' && [...v].length <= field.max_length))), 'invalid_catalog');
+        else if (field.type === 'number' || field.type === 'integer')
+            actionCheck(!field.max_length && !field.enum?.length && [field.minimum, field.maximum].every(n => n === undefined || (Number.isFinite(n) && (field.type !== 'integer' || Number.isSafeInteger(n)))) && (field.minimum === undefined || field.maximum === undefined || field.minimum <= field.maximum), 'invalid_catalog');
+        else
+            actionCheck(field.type === 'boolean' && !field.max_length && !field.enum?.length && field.minimum === undefined && field.maximum === undefined, 'invalid_catalog');
+    }
+}
+/** Validate action declarations locally; server registration and destination checks remain authoritative. */
+export function validateSupportActionCatalog(version, actions) {
+    actionCheck(typeof version === 'string' && version.length <= 32 && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(version) && Array.isArray(actions) && actions.length >= 1 && actions.length <= 32, 'invalid_catalog');
+    const names = new Set();
+    for (const action of actions) {
+        actionCheck(/^[a-z][a-z0-9_.]{0,79}$/.test(action.name) && !names.has(action.name) && action.version === version && action.identity_required === true && ['read', 'bounded_write', 'customer_change', 'financial', 'security'].includes(action.risk) && typeof action.idempotency_supported === 'boolean' && typeof action.safe_retry === 'boolean' && Number.isInteger(action.timeout_seconds) && action.timeout_seconds >= 1 && action.timeout_seconds <= 30 && endpoint(action.endpoint), 'invalid_catalog');
+        actionCheck((action.risk === 'read' || (action.idempotency_supported && endpoint(action.reconciliation_endpoint) && !!action.verification_operation)) && (!action.safe_retry || action.idempotency_supported) && (!action.reconciliation_endpoint || endpoint(action.reconciliation_endpoint)), 'invalid_catalog');
+        fields(action.input, true);
+        fields(action.output, false);
+        names.add(action.name);
+    }
+    for (const action of actions)
+        actionCheck(!action.verification_operation || actions.some(a => a.name === action.verification_operation && a.risk === 'read'), 'invalid_catalog');
+}

package/dist/support-action-receiver.d.ts

@@ -0,0 +1,20 @@
+import type { SupportActionReceipt, SupportActionRequest, SupportActionVerification } from './support-action-types.js';
+export interface SupportActionClaim {
+    state: 'acquired' | 'completed' | 'running' | 'unknown' | 'conflict';
+    fence?: string;
+    response?: Uint8Array;
+}
+export interface SupportActionDurableStore {
+    claim(namespace: 'delivery' | 'execution', key: string, digest: string): Promise<SupportActionClaim>;
+    complete(namespace: 'delivery' | 'execution', key: string, fence: string, response: Uint8Array, unknown?: boolean): Promise<void>;
+}
+export type SupportActionHandler = (request: SupportActionRequest) => Promise<Pick<SupportActionReceipt, 'state' | 'result' | 'error_code'>>;
+export declare function receiveSupportAction(raw: Uint8Array, headers: Record<string, string>, options: {
+    verification: SupportActionVerification;
+    store: SupportActionDurableStore;
+    execute: SupportActionHandler;
+    reconcile: SupportActionHandler;
+}): Promise<{
+    body: Uint8Array<ArrayBufferLike>;
+    headers: Record<string, string>;
+}>;

package/dist/support-action-receiver.js

@@ -0,0 +1,37 @@
+import { ACTION_RECEIPT_CONTEXT, actionCheck, actionHeaders, encodeSupportActionReceipt, signSupportAction, validateSupportActionFields, verifySupportAction } from './support-actions.js';
+export async function receiveSupportAction(raw, headers, options) {
+    const verification = { ...options.verification, now: options.verification.now ?? Math.floor(Date.now() / 1000) };
+    const request = await verifySupportAction(raw, headers, verification);
+    const delivery = actionHeaders(headers)['x-stackshift-delivery-id'];
+    const digest = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', new Uint8Array(raw))), b => b.toString(16).padStart(2, '0')).join('');
+    const deliveryKey = `${request.installation_id}:${delivery}`;
+    const deliveryClaim = await options.store.claim('delivery', deliveryKey, digest);
+    actionCheck(deliveryClaim.state === 'acquired' && deliveryClaim.fence, 'delivery_replay');
+    const key = [request.installation_id, request.action.name, request.action.version, request.request_id, request.mode].join(':');
+    const claim = await options.store.claim('execution', key, digest);
+    actionCheck(claim.state !== 'conflict', 'idempotency_conflict');
+    let response;
+    if ((claim.state === 'completed' || claim.state === 'unknown') && claim.response)
+        response = claim.response;
+    else if (claim.state === 'running' || claim.state === 'unknown')
+        response = encodeSupportActionReceipt(request.request_id, claim.state === 'unknown' ? 'unknown' : 'accepted', {}, claim.state === 'unknown' ? 'execution_unknown' : 'execution_in_progress');
+    else {
+        actionCheck(claim.state === 'acquired' && claim.fence, 'invalid_store_claim');
+        let state = 'unknown';
+        try {
+            const result = await (request.mode === 'reconcile' ? options.reconcile : options.execute)(request);
+            state = result.state;
+            const action = verification.actions.find(a => a.name === request.action.name && a.version === request.action.version);
+            if (state === 'succeeded')
+                validateSupportActionFields(result.result, action.output);
+            response = encodeSupportActionReceipt(request.request_id, state, result.result, result.error_code);
+        }
+        catch {
+            state = 'unknown';
+            response = encodeSupportActionReceipt(request.request_id, state, {}, 'handler_outcome_unknown');
+        }
+        await options.store.complete('execution', key, claim.fence, response, state === 'unknown');
+    }
+    await options.store.complete('delivery', deliveryKey, deliveryClaim.fence, response);
+    return { body: response, headers: await signSupportAction(response, ACTION_RECEIPT_CONTEXT, verification.keyID, verification.secret, verification.now, delivery) };
+}

package/dist/support-action-sqlite.d.ts

@@ -0,0 +1,17 @@
+import type { SupportActionClaim, SupportActionDurableStore } from './support-action-receiver.js';
+/** Compatible with node:sqlite DatabaseSync; supply a persistent disk database. */
+export interface SupportActionSQLiteDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        run(...values: any[]): {
+            changes: number | bigint;
+        };
+        get(...values: any[]): unknown;
+    };
+}
+export declare class SupportActionSQLiteStore implements SupportActionDurableStore {
+    private readonly database;
+    constructor(database: SupportActionSQLiteDatabase);
+    claim(namespace: 'delivery' | 'execution', key: string, digest: string): Promise<SupportActionClaim>;
+    complete(namespace: 'delivery' | 'execution', key: string, fence: string, response: Uint8Array, unknown?: boolean): Promise<void>;
+}

package/dist/support-action-sqlite.js

@@ -0,0 +1,30 @@
+import { actionCheck } from './support-actions.js';
+export class SupportActionSQLiteStore {
+    database;
+    constructor(database) {
+        this.database = database;
+        database.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=10000;');
+        database.exec(`CREATE TABLE IF NOT EXISTS support_action_claims (
+      namespace TEXT NOT NULL, claim_key TEXT NOT NULL, digest TEXT NOT NULL,
+      state TEXT NOT NULL, fence TEXT NOT NULL, response BLOB,
+      PRIMARY KEY(namespace, claim_key))`);
+    }
+    async claim(namespace, key, digest) {
+        const db = this.database, fence = crypto.randomUUID();
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const inserted = db.prepare('INSERT OR IGNORE INTO support_action_claims VALUES (?, ?, ?, ?, ?, NULL)').run(namespace, key, digest, 'running', fence);
+            const row = db.prepare('SELECT digest,state,fence,response FROM support_action_claims WHERE namespace=? AND claim_key=?').get(namespace, key);
+            db.exec('COMMIT');
+            return { state: inserted.changes ? 'acquired' : row.digest === digest ? row.state : 'conflict', fence: row.fence, ...(row.response ? { response: new Uint8Array(row.response) } : {}) };
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    async complete(namespace, key, fence, response, unknown = false) {
+        const result = this.database.prepare('UPDATE support_action_claims SET state=?,response=? WHERE namespace=? AND claim_key=? AND fence=? AND state=?').run(unknown ? 'unknown' : 'completed', response, namespace, key, fence, 'running');
+        actionCheck(Number(result.changes) === 1, 'fence_lost');
+    }
+}

package/dist/support-action-types.d.ts

@@ -0,0 +1,93 @@
+export interface SupportActionField {
+    type: 'string' | 'number' | 'integer' | 'boolean';
+    required: boolean;
+    max_length?: number;
+    minimum?: number;
+    maximum?: number;
+    enum?: string[];
+}
+export interface SupportActionDescriptor {
+    name: string;
+    version: string;
+    endpoint: string;
+    reconciliation_endpoint?: string;
+    input: Record<string, SupportActionField>;
+    output: Record<string, SupportActionField>;
+    risk: 'read' | 'bounded_write' | 'customer_change' | 'financial' | 'security';
+    identity_required: true;
+    idempotency_supported: boolean;
+    safe_retry: boolean;
+    timeout_seconds: number;
+    verification_operation?: string;
+}
+export interface SupportActionManifest {
+    schema: 'stackshift.support.app/v2';
+    version: string;
+    permissions: string[];
+    event_types: string[];
+    placements: string[];
+    webhook_url: string;
+    description: string;
+    actions: SupportActionDescriptor[];
+}
+export interface SupportActionRequest {
+    schema: 'stackshift.support.action/v1';
+    request_id: string;
+    installation_id: string;
+    installation_revision: number;
+    app_version_id: string;
+    action: {
+        name: string;
+        version: string;
+    };
+    scope: {
+        workspace_id: string;
+        environment_id: string;
+        inbox_id: string;
+        conversation_id: string;
+        contact_id: string;
+    };
+    customer: {
+        external_id: string;
+    };
+    arguments: Record<string, string | number | boolean>;
+    authorization: {
+        grant_id?: string;
+        revision: number;
+        mode: 'automatic' | 'customer' | 'staff';
+    };
+    issued_at: number;
+    expires_at: number;
+    mode: 'execute' | 'reconcile';
+    target_request_id?: string;
+}
+export interface SupportActionReceipt {
+    schema: 'stackshift.support.action-receipt/v1';
+    request_id: string;
+    state: 'accepted' | 'succeeded' | 'failed' | 'unknown';
+    result: Record<string, unknown>;
+    error_code?: string;
+}
+export interface SupportActionVerification {
+    keyID: string;
+    secret: string;
+    installationID: string;
+    actions: SupportActionDescriptor[];
+    expectedCustomerExternalID: string;
+    now?: number;
+    tolerance?: number;
+}
+export interface SupportActionInstallationInput {
+    version_id: string;
+    environment_id: string;
+    inbox_id: string;
+    permissions: string[];
+    action_operations: string[];
+    confirm_consent: true;
+    revision: number;
+}
+export interface SupportActionInstallationCredentials {
+    action_key_id: string;
+    action_secret: string;
+    action_operations: string[];
+}

package/dist/support-action-types.js

@@ -0,0 +1 @@
+export {};

package/dist/support-actions.d.ts

@@ -0,0 +1,19 @@
+import type { SupportActionField, SupportActionReceipt, SupportActionRequest, SupportActionVerification } from './support-action-types.js';
+export declare const ACTION_CONTEXT = "stackshift.support.action/v1";
+export declare const ACTION_RECEIPT_CONTEXT = "stackshift.support.action-receipt/v1";
+export declare class SupportActionError extends Error {
+}
+export declare function actionCheck(ok: unknown, code?: string): asserts ok;
+export declare function signSupportAction(raw: Uint8Array, context: string, keyID: string, secret: string, timestamp: number, deliveryID: string): Promise<Record<string, string>>;
+export declare function actionHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function validateSupportActionFields(value: unknown, fields: Record<string, SupportActionField>): void;
+export declare function verifySupportAction(raw: Uint8Array, headers: Record<string, string>, options: SupportActionVerification): Promise<SupportActionRequest>;
+export declare function encodeSupportActionReceipt(requestID: string, state: SupportActionReceipt['state'], result: Record<string, unknown>, errorCode?: string): Uint8Array<ArrayBuffer>;
+export declare function verifySupportActionReceipt(raw: Uint8Array, headers: Record<string, string>, options: {
+    keyID: string;
+    secret: string;
+    requestID: string;
+    deliveryID: string;
+    now: number;
+    tolerance?: number;
+}): Promise<SupportActionReceipt>;

package/dist/support-actions.js

@@ -0,0 +1,213 @@
+export const ACTION_CONTEXT = 'stackshift.support.action/v1';
+export const ACTION_RECEIPT_CONTEXT = 'stackshift.support.action-receipt/v1';
+export class SupportActionError extends Error {
+}
+const encoder = new TextEncoder();
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function actionCheck(ok, code = 'invalid_request') { if (!ok)
+    throw new SupportActionError(code); }
+function uuid(value) { return typeof value === 'string' && uuidPattern.test(value) && value !== '00000000-0000-0000-0000-000000000000'; }
+function integer(value) { return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0; }
+function object(value, required, optional = []) {
+    actionCheck(value !== null && typeof value === 'object' && !Array.isArray(value));
+    const keys = Object.keys(value);
+    actionCheck(required.every(k => keys.includes(k)) && keys.every(k => required.includes(k) || optional.includes(k)));
+}
+function joined(context, keyID, timestamp, deliveryID, raw) {
+    const prefix = encoder.encode(`${context}\n${keyID}\n${timestamp}\n${deliveryID}\n`);
+    const result = new Uint8Array(prefix.length + raw.length);
+    result.set(prefix);
+    result.set(raw, prefix.length);
+    return result;
+}
+export async function signSupportAction(raw, context, keyID, secret, timestamp, deliveryID) {
+    actionCheck([ACTION_CONTEXT, ACTION_RECEIPT_CONTEXT].includes(context) && /^[A-Za-z0-9_-]{1,128}$/.test(keyID) && uuid(deliveryID) && integer(timestamp) && timestamp > 0 && secret.length >= 32);
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, joined(context, keyID, String(timestamp), deliveryID, raw));
+    return { 'x-stackshift-action-key-id': keyID, 'x-stackshift-timestamp': String(timestamp), 'x-stackshift-delivery-id': deliveryID, 'x-stackshift-action-signature': `v1=${Array.from(new Uint8Array(signature), b => b.toString(16).padStart(2, '0')).join('')}` };
+}
+export function actionHeaders(headers) {
+    const result = Object.create(null);
+    for (const [name, value] of Object.entries(headers)) {
+        const lower = name.toLowerCase();
+        actionCheck(!(lower in result), 'invalid_headers');
+        result[lower] = value;
+    }
+    return result;
+}
+async function verifySignature(raw, headers, context, keyID, secret, now, tolerance, limit) {
+    actionCheck(raw instanceof Uint8Array && raw.length > 0 && raw.length <= limit, 'body_limit');
+    actionCheck(integer(now) && Number.isInteger(tolerance) && tolerance > 0 && tolerance <= 300);
+    const h = actionHeaders(headers), stamp = h['x-stackshift-timestamp'], delivery = h['x-stackshift-delivery-id'];
+    actionCheck(typeof stamp === 'string' && /^[1-9][0-9]{0,15}$/.test(stamp) && integer(Number(stamp)), 'invalid_headers');
+    actionCheck(h['x-stackshift-action-key-id'] === keyID && uuid(delivery) && /^[A-Za-z0-9_-]{1,128}$/.test(keyID) && secret.length >= 32, 'binding_mismatch');
+    actionCheck(Math.abs(now - Number(stamp)) <= tolerance, 'stale_signature');
+    const signature = h['x-stackshift-action-signature'];
+    actionCheck(typeof signature === 'string' && /^v1=[0-9a-f]{64}$/.test(signature), 'invalid_signature');
+    const bytes = Uint8Array.from(signature.slice(3).match(/../g), v => parseInt(v, 16));
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    actionCheck(await crypto.subtle.verify('HMAC', key, bytes, joined(context, keyID, stamp, delivery, raw)), 'invalid_signature');
+    return delivery;
+}
+// Reject duplicate keys before JSON.parse; ordinary JSON.parse silently overwrites them.
+function decode(raw) {
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(raw);
+    }
+    catch {
+        throw new SupportActionError('invalid_request');
+    }
+    let i = 0;
+    function space() { while (/\s/.test(text[i] ?? '') && i < text.length)
+        i++; }
+    function string() { const start = i++; while (i < text.length) {
+        if (text[i++] === '\\') {
+            i++;
+            continue;
+        }
+        if (text[i - 1] === '"')
+            return JSON.parse(text.slice(start, i));
+    } throw new SupportActionError('invalid_request'); }
+    function value(depth) {
+        actionCheck(depth <= 32);
+        space();
+        if (text[i] === '{') {
+            i++;
+            space();
+            const keys = new Set();
+            if (text[i] === '}') {
+                i++;
+                return;
+            }
+            while (i < text.length) {
+                space();
+                actionCheck(text[i] === '"');
+                const key = string();
+                actionCheck(!keys.has(key));
+                keys.add(key);
+                space();
+                actionCheck(text[i++] === ':');
+                value(depth + 1);
+                space();
+                const next = text[i++];
+                if (next === '}')
+                    return;
+                actionCheck(next === ',');
+            }
+        }
+        else if (text[i] === '[') {
+            i++;
+            space();
+            if (text[i] === ']') {
+                i++;
+                return;
+            }
+            ;
+            while (i < text.length) {
+                value(depth + 1);
+                space();
+                const next = text[i++];
+                if (next === ']')
+                    return;
+                actionCheck(next === ',');
+            }
+        }
+        else if (text[i] === '"') {
+            string();
+            return;
+        }
+        else {
+            const start = i;
+            while (i < text.length && !/[\s,\]}]/.test(text[i]))
+                i++;
+            actionCheck(i > start);
+            JSON.parse(text.slice(start, i));
+            return;
+        }
+        throw new SupportActionError('invalid_request');
+    }
+    try {
+        value(0);
+        space();
+        actionCheck(i === text.length);
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SupportActionError('invalid_request');
+    }
+}
+export function validateSupportActionFields(value, fields) {
+    actionCheck(value !== null && typeof value === 'object' && !Array.isArray(value));
+    const data = value;
+    actionCheck(Object.keys(data).every(k => Object.hasOwn(fields, k)));
+    for (const [name, field] of Object.entries(fields)) {
+        if (!Object.hasOwn(data, name)) {
+            actionCheck(!field.required);
+            continue;
+        }
+        const item = data[name];
+        actionCheck((field.type === 'string' && typeof item === 'string') || (field.type === 'boolean' && typeof item === 'boolean') || (field.type === 'integer' && typeof item === 'number' && Number.isSafeInteger(item)) || (field.type === 'number' && typeof item === 'number' && Number.isFinite(item)));
+        if (typeof item === 'string')
+            actionCheck([...item].length <= (field.max_length ?? 16000) && (!field.enum?.length || field.enum.includes(item)));
+        if (typeof item === 'number')
+            actionCheck(item >= (field.minimum ?? -Infinity) && item <= (field.maximum ?? Infinity));
+    }
+}
+export async function verifySupportAction(raw, headers, options) {
+    const now = options.now ?? Math.floor(Date.now() / 1000), tolerance = options.tolerance ?? 300;
+    await verifySignature(raw, headers, ACTION_CONTEXT, options.keyID, options.secret, now, tolerance, 256 * 1024);
+    const body = decode(raw);
+    object(body, ['schema', 'request_id', 'installation_id', 'installation_revision', 'app_version_id', 'action', 'scope', 'customer', 'arguments', 'authorization', 'issued_at', 'expires_at', 'mode'], ['target_request_id']);
+    actionCheck(body.schema === ACTION_CONTEXT && body.installation_id === options.installationID, 'binding_mismatch');
+    actionCheck(['request_id', 'installation_id', 'app_version_id'].every(k => uuid(body[k])) && integer(body.installation_revision) && body.installation_revision > 0);
+    object(body.action, ['name', 'version']);
+    object(body.scope, ['workspace_id', 'environment_id', 'inbox_id', 'conversation_id', 'contact_id']);
+    actionCheck(Object.values(body.scope).every(uuid));
+    object(body.customer, ['external_id']);
+    actionCheck(options.expectedCustomerExternalID.length > 0 && [...options.expectedCustomerExternalID].length <= 256 && body.customer.external_id === options.expectedCustomerExternalID, 'binding_mismatch');
+    object(body.authorization, ['revision', 'mode'], ['grant_id']);
+    const auth = body.authorization;
+    actionCheck(integer(auth.revision) && auth.revision > 0 && ['automatic', 'customer', 'staff'].includes(auth.mode) && (!Object.hasOwn(auth, 'grant_id') || uuid(auth.grant_id)));
+    actionCheck(integer(body.issued_at) && integer(body.expires_at) && body.issued_at <= now + tolerance && body.expires_at > now && body.expires_at > body.issued_at, 'request_expired');
+    const action = options.actions.find(a => a.name === body.action.name && a.version === body.action.version);
+    actionCheck(action, 'action_not_registered');
+    if (body.mode === 'reconcile') {
+        actionCheck(uuid(body.target_request_id) && body.target_request_id !== body.request_id);
+        object(body.arguments, []);
+    }
+    else {
+        actionCheck(body.mode === 'execute' && !Object.hasOwn(body, 'target_request_id'));
+        validateSupportActionFields(body.arguments, action.input);
+    }
+    return body;
+}
+function validateReceipt(body) {
+    object(body, ['schema', 'request_id', 'state', 'result'], ['error_code']);
+    actionCheck(body.schema === ACTION_RECEIPT_CONTEXT && uuid(body.request_id) && ['accepted', 'succeeded', 'failed', 'unknown'].includes(body.state));
+    actionCheck(body.result !== null && typeof body.result === 'object' && !Array.isArray(body.result));
+    actionCheck(body.state === 'succeeded' || Object.keys(body.result).length === 0);
+    actionCheck(!Object.hasOwn(body, 'error_code') || (typeof body.error_code === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(body.error_code)));
+}
+export function encodeSupportActionReceipt(requestID, state, result, errorCode) {
+    const body = { schema: ACTION_RECEIPT_CONTEXT, request_id: requestID, state, result, ...(errorCode !== undefined ? { error_code: errorCode } : {}) };
+    validateReceipt(body);
+    let serialized;
+    try {
+        serialized = JSON.stringify(body, (_key, value) => { actionCheck(value !== undefined && typeof value !== 'function' && typeof value !== 'symbol' && (typeof value !== 'number' || Number.isFinite(value))); return value; });
+    }
+    catch {
+        throw new SupportActionError('invalid_request');
+    }
+    const raw = encoder.encode(serialized);
+    actionCheck(raw.length <= 64 * 1024, 'body_limit');
+    decode(raw);
+    return raw;
+}
+export async function verifySupportActionReceipt(raw, headers, options) {
+    const delivery = await verifySignature(raw, headers, ACTION_RECEIPT_CONTEXT, options.keyID, options.secret, options.now, options.tolerance ?? 300, 64 * 1024);
+    const body = decode(raw);
+    validateReceipt(body);
+    actionCheck(delivery === options.deliveryID && body.request_id === options.requestID, 'binding_mismatch');
+    return body;
+}

package/dist/types.d.ts

@@ -197,6 +197,18 @@ export interface ProjectListOptions {
     perPage?: number;
 }
 export interface Asset {
+    readiness?: {
+        state: "ready" | "processing" | "blocked" | "unknown";
+        stages: Array<{
+            id: string;
+            status: string;
+        }>;
+        actions: Record<"preview" | "download" | "edit" | "publish", {
+            state: "ready" | "blocked" | "unknown";
+            code: string;
+            message: string;
+        }>;
+    };
     id: string;
     bucket: string;
     key: string;
@@ -244,6 +256,11 @@ export interface AssetAIAnnotation {
     colors: string[];
     raw?: JsonValue;
 }
+export interface AssetManualDescriptionInput {
+    caption?: string;
+    alt_text?: string;
+    tags?: string[];
+}
 export interface AssetModerationResult {
     id: string;
     provider: string;

package/dist/upload-controller.d.ts

@@ -9,6 +9,7 @@ export interface UploadedPart {
     checksumSHA256?: string;
 }
 export interface ChunkUploadSession {
+    completionPending?: boolean;
     id: string;
     uploadToken: string;
     expiresAt: string;
@@ -52,6 +53,7 @@ export interface ChunkedUploadOptions extends ChunkUploadCallbacks {
     concurrency?: number;
     retryAttempts?: number;
     cancelOnAbort?: boolean;
+    requireMatchingFile?: boolean;
 }
 export declare class UploadResumeInvalidError extends Error {
     constructor(message?: string);