@swell/apps-sdk 1.0.189 → 2.0.0-alpha.0

package/dist/backend.js

@@ -0,0 +1,152 @@
+import { parseSwellHeaders, requireString, validateUrl } from './context.js';
+import { SwellError } from './error.js';
+import { validateWorkflowParams } from './workflow.js';
+import { USER_AGENT } from './version.js';
+// Matches JSON bodies: undefined values are omitted and Dates become ISO strings.
+function queryParts(query, prefix = '') {
+    return Object.entries(query).flatMap(([key, value]) => {
+        const name = prefix ? `${prefix}[${key}]` : key;
+        if (value === undefined)
+            return [];
+        // A bare key decodes to native null on the server; `key=null` would be the string "null".
+        if (value === null)
+            return [encodeURIComponent(name)];
+        if (value instanceof Date)
+            value = value.toISOString();
+        return typeof value === 'object' ? queryParts(value, name)
+            : [`${encodeURIComponent(name)}=${encodeURIComponent(value)}`];
+    });
+}
+/** Per-request backend client. Use explicit credentials outside trusted platform ingress. */
+export class SwellBackendAPI {
+    #baseUrl;
+    #authorization;
+    #appId;
+    #requestId;
+    get userAgent() { return USER_AGENT; }
+    workflows = {
+        /** Creates a workflow instance. Optional params must be JSON-safe and at most 128 KiB of UTF-8 JSON; invalid params reject. */
+        create: async (name, params) => {
+            const data = { workflow_name: name };
+            if (params !== undefined)
+                data.params = validateWorkflowParams(params);
+            return this.post('/:workflows/instances', data);
+        },
+    };
+    functions = {
+        /**
+         * Invokes an app's private function from server code and resolves to its response payload,
+         * without the envelope's status or headers.
+         * `appId` is the app identifier from `Swell-App-Id` (`parseSwellHeaders(headers).appId`).
+         * `method` (default `post`) selects the function's handler. GET data reaches the function
+         * as query parameters, so its values must be flat strings, numbers or booleans.
+         * Throws `SwellError` when the function reports a non-2xx status or an error.
+         * Callers authorize the operation first; no caller headers are forwarded.
+         */
+        call: async (appId, name, data, { method = 'post' } = {}) => {
+            requireString(appId, 'appId');
+            requireString(name, 'function name');
+            if (!['get', 'post', 'put', 'delete'].includes(method))
+                throw new Error(`Invalid function method: ${method}`);
+            if (method === 'get' && data && Object.values(data).some(value => !['string', 'number', 'boolean'].includes(typeof value))) {
+                throw new Error('GET function data must contain only string, number or boolean values');
+            }
+            const result = await this.put(`/:functions/${encodeURIComponent(`app.${appId}.${name}`)}`, { $call: { data: data ?? {}, method } });
+            if (!result || typeof result !== 'object')
+                throw new SwellError(`Function not found: ${name}`, { status: 404 });
+            const { status, error, code, response } = result;
+            if (error !== undefined || (typeof status === 'number' && (status < 200 || status > 299))) {
+                const message = typeof error === 'string' ? error : typeof response?.error === 'string' ? response.error : `Function ${name} failed`;
+                const failure = new SwellError(message, { status, code });
+                failure.body = response ?? result;
+                throw failure;
+            }
+            return response;
+        },
+    };
+    constructor(options) {
+        if (options.headers && ['storeId', 'apiHost', 'accessToken', 'secretKey', 'appId', 'requestId'].some(key => key in options)) {
+            throw new Error('headers and explicit backend credentials are mutually exclusive');
+        }
+        const config = options.headers ? parseSwellHeaders(options.headers) : options;
+        const secretKey = 'secretKey' in config ? config.secretKey : undefined;
+        requireString(config.storeId, 'storeId');
+        if ((config.accessToken !== undefined) === (secretKey !== undefined))
+            throw new Error('Provide exactly one accessToken or secretKey');
+        const credential = config.accessToken ?? secretKey;
+        requireString(credential, 'accessToken or secretKey');
+        this.#baseUrl = validateUrl(config.apiHost, 'apiHost');
+        const bytes = new TextEncoder().encode(`${config.storeId}:${credential}`);
+        this.#authorization = `Basic ${btoa(Array.from(bytes, byte => String.fromCharCode(byte)).join(''))}`;
+        this.#appId = config.appId;
+        this.#requestId = config.requestId;
+    }
+    async #makeRequest(method, path, data) {
+        // Paths stay on the configured host: '' means '/', spaces are encoded, dot segments are
+        // normalized by URL parsing, fragments/backslashes/control characters are rejected.
+        if (typeof path !== 'string' || /^[a-z][a-z\d+.-]*:/i.test(path) || path.startsWith('//') || /[\\#\x00-\x1f\x7f]/.test(path)) {
+            throw new Error('Backend endpoint must be a path on the configured API host');
+        }
+        const endpointUrl = path.replace(/^\//, '').replaceAll(' ', '%20');
+        const headers = {
+            Authorization: this.#authorization, 'User-Agent': this.userAgent, 'Content-Type': 'application/json',
+            ...(this.#requestId ? { 'Swell-Request-ID': this.#requestId } : {}),
+        };
+        const init = { method, headers, redirect: 'manual' };
+        let query = '';
+        if (data) {
+            try {
+                if (method !== 'GET')
+                    init.body = JSON.stringify(data);
+                else {
+                    const params = queryParts(data).join('&');
+                    if (params)
+                        query = `${path.includes('?') ? '&' : '?'}${params}`;
+                }
+            }
+            catch {
+                throw new Error(`Error serializing data: ${data}`);
+            }
+        }
+        const response = await fetch(`${this.#baseUrl}/${endpointUrl}${query}`, init);
+        const text = await response.text();
+        let result;
+        try {
+            result = JSON.parse(text);
+        }
+        catch {
+            result = text.trim();
+        }
+        if (!response.ok)
+            throw new SwellError(result, { status: response.status, method, endpointUrl });
+        if (method !== 'GET' && result?.errors)
+            throw new SwellError(result.errors, { status: 400, method, endpointUrl });
+        return result;
+    }
+    get(path, query) { return this.#makeRequest('GET', path, query); }
+    put(path, data) { return this.#makeRequest('PUT', path, data); }
+    post(path, data) { return this.#makeRequest('POST', path, data); }
+    delete(path, data) { return this.#makeRequest('DELETE', path, data); }
+    /** Reads installed-app settings; defaults to the configured app ID and rejects when neither ID is supplied. */
+    async settings(appId = this.#appId) {
+        requireString(appId, 'appId for settings()');
+        return this.get(`/settings/${encodeURIComponent(appId)}`);
+    }
+    /** Atomic operations returning results in operation order; only conflicts and throttling retry, and only when requested. */
+    async transaction(ops, options = {}) {
+        const cfg = { limit: 3, base: 100, max: 5000, jitter: true, ...(options.retry === true ? {} : options.retry) };
+        let attempt = 0;
+        while (true) {
+            try {
+                return await this.post('/:transaction', ops);
+            }
+            catch (error) {
+                if (!options.retry || !(error instanceof SwellError) || !error.isRetryable || attempt >= cfg.limit)
+                    throw error;
+                const delay = Math.min(cfg.base * 2 ** attempt, cfg.max);
+                await new Promise(resolve => setTimeout(resolve, cfg.jitter ? delay * (0.5 + Math.random() * 0.5) : delay));
+                attempt++;
+            }
+        }
+    }
+}

package/dist/browser-refusal.d.cts

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

package/dist/browser-refusal.d.ts

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

package/dist/browser-refusal.js

@@ -0,0 +1,2 @@
+throw new Error('@swell/apps-sdk is server-only; import swell-js in browser code');
+export {};

package/dist/context.d.cts

@@ -0,0 +1,21 @@
+import type { PublicConfig } from 'swell-js';
+export type HeaderReader = Pick<Headers, 'get'>;
+export interface SwellContext {
+    storeId?: string;
+    appId?: string;
+    environmentId?: string;
+    storefrontId?: string;
+    accessToken?: string;
+    publicKey?: string;
+    apiHost?: string;
+    adminUrl?: string;
+    vaultUrl?: string;
+    requestId?: string;
+    isLocalDev: boolean;
+}
+/** Parses trusted ingress headers; does not verify their signature. */
+export declare function parseSwellHeaders(headers: HeaderReader): SwellContext;
+export declare function requireString(value: unknown, field: string): asserts value is string;
+export declare function validateUrl(value: unknown, field: string): string;
+/** Projects only public configuration. Deliver it with Cache-Control: private, no-store. */
+export declare function getStorefrontConfig(headers: HeaderReader): PublicConfig;

package/dist/context.d.ts

@@ -0,0 +1,21 @@
+import type { PublicConfig } from 'swell-js';
+export type HeaderReader = Pick<Headers, 'get'>;
+export interface SwellContext {
+    storeId?: string;
+    appId?: string;
+    environmentId?: string;
+    storefrontId?: string;
+    accessToken?: string;
+    publicKey?: string;
+    apiHost?: string;
+    adminUrl?: string;
+    vaultUrl?: string;
+    requestId?: string;
+    isLocalDev: boolean;
+}
+/** Parses trusted ingress headers; does not verify their signature. */
+export declare function parseSwellHeaders(headers: HeaderReader): SwellContext;
+export declare function requireString(value: unknown, field: string): asserts value is string;
+export declare function validateUrl(value: unknown, field: string): string;
+/** Projects only public configuration. Deliver it with Cache-Control: private, no-store. */
+export declare function getStorefrontConfig(headers: HeaderReader): PublicConfig;

package/dist/context.js

@@ -0,0 +1,42 @@
+/** Parses trusted ingress headers; does not verify their signature. */
+export function parseSwellHeaders(headers) {
+    const read = (name) => headers.get(`Swell-${name}`) ?? undefined;
+    return {
+        storeId: read('Store-Id'), appId: read('App-Id'),
+        environmentId: read('Environment-Id'), storefrontId: read('Storefront-Id'),
+        accessToken: read('Access-Token'), publicKey: read('Public-Key'),
+        apiHost: read('API-Host'), adminUrl: read('Admin-Url'),
+        vaultUrl: read('Vault-Url'), requestId: read('Request-ID'),
+        isLocalDev: read('Local-Dev') === 'true',
+    };
+}
+export function requireString(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`Missing or invalid ${field}`);
+}
+export function validateUrl(value, field) {
+    requireString(value, field);
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid ${field}: expected an absolute HTTP(S) URL`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error(`Invalid ${field}: expected an HTTP(S) URL without credentials, query or fragment`);
+    }
+    return url.href.replace(/\/$/, '');
+}
+/** Projects only public configuration. Deliver it with Cache-Control: private, no-store. */
+export function getStorefrontConfig(headers) {
+    const context = parseSwellHeaders(headers);
+    requireString(context.storeId, 'storeId');
+    requireString(context.publicKey, 'publicKey');
+    return {
+        storeId: context.storeId, publicKey: context.publicKey,
+        url: validateUrl(context.adminUrl, 'adminUrl'),
+        vaultUrl: context.vaultUrl === undefined ? 'https://vault.schema.io' : validateUrl(context.vaultUrl, 'vaultUrl'),
+        ...(context.storefrontId ? { headers: { 'Swell-Storefront-Id': context.storefrontId } } : {}),
+    };
+}

package/dist/error.d.cts

@@ -0,0 +1,23 @@
+export interface SwellErrorOptions {
+    status?: number;
+    method?: string;
+    endpointUrl?: string;
+    code?: string;
+    retry?: boolean;
+}
+/**
+ * Backend or function error; ordinary operations never retry automatically.
+ * Machine-readable contract: `status`, optional `code` and optional `body`.
+ * Ordinary backend errors retain structured responses in `body`; string errors have no body.
+ * HTTP-200 non-GET validation failures retain the `errors` field map. Function invocation
+ * failures retain the response payload or, if nullish, the invocation envelope.
+ * `message` is for humans and may change.
+ */
+export declare class SwellError extends Error {
+    status: number;
+    body?: any;
+    code?: string;
+    retry?: boolean;
+    constructor(message: any, options?: SwellErrorOptions);
+    get isRetryable(): boolean;
+}

package/dist/error.d.ts

@@ -0,0 +1,23 @@
+export interface SwellErrorOptions {
+    status?: number;
+    method?: string;
+    endpointUrl?: string;
+    code?: string;
+    retry?: boolean;
+}
+/**
+ * Backend or function error; ordinary operations never retry automatically.
+ * Machine-readable contract: `status`, optional `code` and optional `body`.
+ * Ordinary backend errors retain structured responses in `body`; string errors have no body.
+ * HTTP-200 non-GET validation failures retain the `errors` field map. Function invocation
+ * failures retain the response payload or, if nullish, the invocation envelope.
+ * `message` is for humans and may change.
+ */
+export declare class SwellError extends Error {
+    status: number;
+    body?: any;
+    code?: string;
+    retry?: boolean;
+    constructor(message: any, options?: SwellErrorOptions);
+    get isRetryable(): boolean;
+}

package/dist/error.js

@@ -0,0 +1,30 @@
+/**
+ * Backend or function error; ordinary operations never retry automatically.
+ * Machine-readable contract: `status`, optional `code` and optional `body`.
+ * Ordinary backend errors retain structured responses in `body`; string errors have no body.
+ * HTTP-200 non-GET validation failures retain the `errors` field map. Function invocation
+ * failures retain the response payload or, if nullish, the invocation envelope.
+ * `message` is for humans and may change.
+ */
+export class SwellError extends Error {
+    status;
+    body;
+    code;
+    retry;
+    constructor(message, options = {}) {
+        const body = typeof message === 'string' ? undefined : message;
+        let formatted = typeof message === 'string' ? message
+            : typeof body?.error?.message === 'string' ? body.error.message : JSON.stringify(message, null, 2);
+        if (options.method && options.endpointUrl)
+            formatted = `${options.method} /${options.endpointUrl}\n${formatted}`;
+        super(formatted);
+        this.name = 'SwellError';
+        this.status = options.status || 500;
+        this.body = body;
+        this.code = options.code || body?.error?.code;
+        this.retry = options.retry;
+    }
+    get isRetryable() {
+        return this.code === 'transaction_conflict' || this.code === 'transaction_throttled';
+    }
+}

package/dist/guard.d.cts

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

package/dist/guard.d.ts

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

package/dist/guard.js

@@ -0,0 +1,4 @@
+if (typeof document !== 'undefined') {
+    throw new Error('@swell/apps-sdk is server-only; import swell-js in browser code');
+}
+export {};

package/dist/index.d.cts

@@ -0,0 +1,9 @@
+import './guard.cjs';
+export { parseSwellHeaders, getStorefrontConfig } from './context.cjs';
+export type { HeaderReader, SwellContext } from './context.cjs';
+export { SwellBackendAPI } from './backend.cjs';
+export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.cjs';
+export { SwellError } from './error.cjs';
+export type { SwellErrorOptions } from './error.cjs';
+export { requireStaff } from './staff.cjs';
+export type { StaffIdentity, StaffOptions } from './staff.cjs';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import './guard.js';
+export { parseSwellHeaders, getStorefrontConfig } from './context.js';
+export type { HeaderReader, SwellContext } from './context.js';
+export { SwellBackendAPI } from './backend.js';
+export type { BackendOptions, SwellCollection, SwellData, TransactionOperation, TransactionOptions } from './backend.js';
+export { SwellError } from './error.js';
+export type { SwellErrorOptions } from './error.js';
+export { requireStaff } from './staff.js';
+export type { StaffIdentity, StaffOptions } from './staff.js';