@stackshift-cloud/sdk 1.3.1 → 1.4.1

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

@@ -256,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackshift-cloud/sdk",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Official JavaScript and TypeScript SDK for StackShift.",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,8 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node test/mail.test.mjs && node test/mail-simulation.test.mjs && node test/mail-platform.test.mjs && node test/mail-webhooks.test.mjs && node test/mail-advanced.test.mjs && node test/mail-tracking.test.mjs && node test/mail-subscribers.test.mjs && node test/mail-exports.test.mjs && node test/mail-diagnostics.test.mjs && node test/assets.test.mjs && node test/assets-platform.test.mjs && node test/assets-video.test.mjs && node test/assets-dam.test.mjs && node test/ai-credits.test.mjs && node --test test/s2-upload.test.mjs"
+    "test": "npm run build && node test/mail.test.mjs && node test/mail-simulation.test.mjs && node test/mail-platform.test.mjs && node test/mail-webhooks.test.mjs && node test/mail-advanced.test.mjs && node test/mail-tracking.test.mjs && node test/mail-subscribers.test.mjs && node test/mail-exports.test.mjs && node test/mail-mailboxes.test.mjs && node test/mail-diagnostics.test.mjs && node test/partner.test.mjs && node test/assets.test.mjs && node test/assets-platform.test.mjs && node test/assets-video.test.mjs && node test/assets-dam.test.mjs && node test/ai-credits.test.mjs && node --test test/s2-upload.test.mjs",
+    "test:support-actions": "npm run build && node --test tests/support-actions.test.mjs"
   },
   "devDependencies": {
     "typescript": "^5.4.0"