@apostra/sdk 0.0.0-stage → 0.38.0

package/dist/transport.js

@@ -0,0 +1,600 @@
+import { baseUrl, m2mTokenUrl, operations, version, } from './generated/metadata.js';
+export class ApostraError extends Error {
+    status;
+    error;
+    requestId;
+    code;
+    recovery;
+    retryAfter;
+    retryable;
+    constructor(status, error, requestId) {
+        // Server messages/details are available explicitly. Do not include them in
+        // the default exception string: they can contain reflected request secrets.
+        const code = error.code;
+        const recovery = error.recovery ?? recoveryForStatus(status);
+        const retryAfter = error.retry_after ?? null;
+        super(`Apostra request failed (${status} ${code}${requestId ? `, request ${requestId}` : ''})`);
+        this.status = status;
+        this.error = error;
+        this.requestId = requestId;
+        this.name = 'ApostraError';
+        this.code = code;
+        this.recovery = recovery;
+        this.retryAfter = retryAfter;
+        this.retryable = recovery === 'transient';
+    }
+}
+export class AuthenticationError extends ApostraError {
+}
+export class PermissionError extends ApostraError {
+}
+export class NotFoundError extends ApostraError {
+}
+export class ConflictError extends ApostraError {
+}
+export class RateLimitError extends ApostraError {
+}
+export class ValidationError extends ApostraError {
+}
+/** @deprecated This compatibility export is never thrown by the transport. */
+export class UnsupportedCapabilityError extends Error {
+}
+export class ConnectionError extends Error {
+    code = 'CONNECTION_ERROR';
+    recovery = 'transient';
+    retryAfter = null;
+    retryable = true;
+    requestId = null;
+    constructor(cause) {
+        super('Apostra connection failed', { cause });
+        this.name = 'ConnectionError';
+    }
+}
+export class TimeoutError extends Error {
+    code = 'TIMEOUT';
+    recovery = 'transient';
+    retryAfter = null;
+    retryable = true;
+    requestId = null;
+    constructor(cause) {
+        super('Apostra request timed out', { cause });
+        this.name = 'TimeoutError';
+    }
+}
+export class ProtocolError extends Error {
+    status;
+    requestId;
+    constructor(status, requestId) {
+        super(`Unexpected Apostra response (${status})`);
+        this.status = status;
+        this.requestId = requestId;
+        this.name = 'ProtocolError';
+    }
+}
+/**
+ * The server accepted a write but cannot yet honestly report its completion.
+ *
+ * Callers retain the original operation-specific idempotency key; the SDK
+ * never makes another request or creates a replacement key.
+ */
+export class InFlightReceiptError extends Error {
+    requestId;
+    retryAfterMs;
+    receipt;
+    status = 202;
+    constructor(requestId, retryAfterMs, receipt) {
+        super('Apostra write is still in flight');
+        this.requestId = requestId;
+        this.retryAfterMs = retryAfterMs;
+        this.receipt = receipt;
+        this.name = 'InFlightReceiptError';
+    }
+}
+const account = (value) => {
+    if (value !== undefined && !/^[1-9][0-9]*$/.test(value))
+        throw new TypeError('accountId must be a positive integer string');
+    return value;
+};
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function credentialPart(value, name) {
+    if (!value || /[\r\n]/.test(value))
+        throw new TypeError(`${name} must be a non-empty single-line string`);
+    return value;
+}
+function m2mScope(value) {
+    const scope = Array.isArray(value) ? value.join(' ') : value;
+    if (!scope.trim() || /[\r\n]/.test(scope))
+        throw new TypeError('scope must be a non-empty single-line string');
+    return scope;
+}
+function m2mTimeoutMs(value) {
+    const timeoutMs = value ?? 30_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new TypeError('timeoutMs must be a positive finite number');
+    return timeoutMs;
+}
+/**
+ * Acquire and cache an OAuth client-credentials token for server-side use.
+ *
+ * The returned provider performs one refresh for concurrent callers and refreshes
+ * 60 seconds before expiry. It never persists or logs a client secret or token.
+ */
+export function m2mTokenProvider({ clientId: rawClientId, clientSecret: rawClientSecret, scope: rawScope, fetch: suppliedFetch, timeoutMs: rawTimeoutMs, }) {
+    const clientId = credentialPart(rawClientId, 'clientId');
+    const clientSecret = credentialPart(rawClientSecret, 'clientSecret');
+    const scope = m2mScope(rawScope);
+    const fetcher = suppliedFetch ?? globalThis.fetch;
+    const timeoutMs = m2mTimeoutMs(rawTimeoutMs);
+    let token;
+    let expiresAt = 0;
+    let refreshing;
+    const refresh = async () => {
+        let response;
+        const signal = AbortSignal.timeout(timeoutMs);
+        try {
+            response = await fetcher(m2mTokenUrl, {
+                method: 'POST',
+                headers: {
+                    Accept: 'application/json',
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+                body: new URLSearchParams({
+                    client_id: clientId,
+                    client_secret: clientSecret,
+                    grant_type: 'client_credentials',
+                    scope,
+                }),
+                redirect: 'error',
+                signal,
+            });
+        }
+        catch (cause) {
+            if (signal.aborted)
+                throw new TimeoutError(cause);
+            throw new ConnectionError(cause);
+        }
+        if (!response.ok)
+            throw new Error(`M2M token request failed (${response.status})`);
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            throw new Error('M2M token response is invalid');
+        }
+        if (!record(payload) ||
+            typeof payload.access_token !== 'string' ||
+            !payload.access_token ||
+            /[\r\n]/.test(payload.access_token) ||
+            typeof payload.expires_in !== 'number' ||
+            !Number.isFinite(payload.expires_in) ||
+            payload.expires_in <= 0)
+            throw new Error('M2M token response is invalid');
+        const result = payload;
+        token = result.access_token;
+        expiresAt = Date.now() + Math.max(0, result.expires_in * 1000 - 60_000);
+        return token;
+    };
+    return () => {
+        if (token && Date.now() < expiresAt)
+            return token;
+        refreshing ??= refresh().finally(() => {
+            refreshing = undefined;
+        });
+        return refreshing;
+    };
+}
+function errorModel(value) {
+    return (record(value) &&
+        typeof value.code === 'string' &&
+        typeof value.message === 'string');
+}
+function inFlightReceipt(value) {
+    if (!record(value))
+        return false;
+    const data = value.data;
+    if (!record(data) || !record(data.receipt))
+        return false;
+    const receipt = data.receipt;
+    return (value.error === null &&
+        typeof receipt.id === 'string' &&
+        typeof receipt.operation === 'string' &&
+        typeof receipt.state === 'string' &&
+        ['claimed', 'running', 'uncertain'].includes(receipt.state) &&
+        typeof receipt.stateVersion === 'number' &&
+        Number.isInteger(receipt.stateVersion) &&
+        receipt.stateVersion >= 1 &&
+        typeof receipt.stateChangedAt === 'string' &&
+        typeof receipt.pendingReason === 'string');
+}
+function retryAfterMs(value) {
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const at = Date.parse(value);
+    return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}
+function retryDelayMs(error, attempt) {
+    const jitter = Math.random() * Math.min(10_000, 250 * 2 ** attempt);
+    const retryAfter = error instanceof ApostraError && error.retryAfter !== null
+        ? error.retryAfter * 1000
+        : 0;
+    return Math.max(jitter, retryAfter);
+}
+function retryable(error) {
+    if (error instanceof ConnectionError)
+        return true;
+    if (error instanceof ApostraError)
+        return error.status === 429 || error.status >= 500;
+    return (error instanceof ProtocolError &&
+        (error.status === 429 || error.status >= 500));
+}
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener('abort', abort);
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timer);
+            cleanup();
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+function recoveryForStatus(status) {
+    if (status === 408 || status === 429 || status >= 500)
+        return 'transient';
+    if (status === 400 ||
+        status === 401 ||
+        status === 403 ||
+        status === 404 ||
+        status === 409 ||
+        status === 422)
+        return 'correctable';
+    return 'terminal';
+}
+function typedError(status, error, requestId) {
+    const args = [status, error, requestId];
+    if (status === 401)
+        return new AuthenticationError(...args);
+    if (status === 403)
+        return new PermissionError(...args);
+    if (status === 404)
+        return new NotFoundError(...args);
+    if (status === 409)
+        return new ConflictError(...args);
+    if (status === 429)
+        return new RateLimitError(...args);
+    if (status === 400 || status === 422)
+        return new ValidationError(...args);
+    return new ApostraError(...args);
+}
+export class Transport {
+    #options;
+    #url;
+    #fetch;
+    constructor(options = {}) {
+        const environment = globalThis.process?.env;
+        const hasExplicitCredential = [
+            options.apiKey,
+            options.accessToken,
+            options.tokenProvider,
+        ].some((value) => value !== undefined);
+        const resolvedOptions = {
+            ...options,
+            apiKey: hasExplicitCredential
+                ? options.apiKey
+                : environment?.APOSTRA_API_KEY,
+            accountId: options.accountId ?? environment?.APOSTRA_ACCOUNT_ID,
+            baseUrl: options.baseUrl ?? environment?.APOSTRA_BASE_URL,
+        };
+        if ([
+            resolvedOptions.apiKey,
+            resolvedOptions.accessToken,
+            resolvedOptions.tokenProvider,
+        ].filter((x) => x !== undefined).length !== 1)
+            throw new TypeError('Supply exactly one of apiKey, accessToken or tokenProvider');
+        const maxRetries = resolvedOptions.maxRetries ?? 2;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0)
+            throw new TypeError('maxRetries must be a non-negative integer');
+        account(resolvedOptions.accountId);
+        const url = new URL(resolvedOptions.baseUrl ?? baseUrl);
+        if (url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            (url.protocol !== 'https:' &&
+                !(url.protocol === 'http:' &&
+                    ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))))
+            throw new TypeError('Use an HTTPS base URL (HTTP is allowed only on loopback)');
+        this.#url = url.href.replace(/\/$/, '');
+        this.#options = { ...resolvedOptions, maxRetries };
+        this.#fetch = resolvedOptions.fetch ?? globalThis.fetch;
+    }
+    async request(operation, input, options = {}) {
+        return (await this.perform(operation, input, options)).data;
+    }
+    async requestDetailed(operation, input, options = {}) {
+        return this.perform(operation, input, options);
+    }
+    async perform(operation, input, options) {
+        const meta = operations[operation];
+        const timeout = options.timeoutMs ?? this.#options.timeoutMs ?? 30_000;
+        if (!Number.isFinite(timeout) || timeout <= 0)
+            throw new TypeError('timeoutMs must be positive');
+        const timeoutSignal = AbortSignal.timeout(timeout);
+        const signal = options.signal
+            ? AbortSignal.any([options.signal, timeoutSignal])
+            : timeoutSignal;
+        const deadline = (promise) => abortable(promise, signal).catch((error) => {
+            if (timeoutSignal.aborted)
+                throw new TimeoutError(error);
+            throw error;
+        });
+        const throwIfAborted = () => {
+            try {
+                signal.throwIfAborted();
+            }
+            catch (error) {
+                if (timeoutSignal.aborted)
+                    throw new TimeoutError(error);
+                throw error;
+            }
+        };
+        throwIfAborted();
+        const target = account(options.accountId ?? this.#options.accountId);
+        const token = await deadline(Promise.resolve().then(() => {
+            throwIfAborted();
+            return (this.#options.tokenProvider?.() ??
+                this.#options.apiKey ??
+                this.#options.accessToken);
+        }));
+        throwIfAborted();
+        if (!token || /[\r\n]/.test(token))
+            throw new TypeError('Credential source returned an empty or invalid token');
+        const headers = new Headers({
+            Authorization: `Bearer ${token}`,
+            Accept: meta.binary ? 'text/markdown' : 'application/json',
+            'User-Agent': `apostra-typescript/${version}`,
+        });
+        let requestInput = input;
+        const fields = requestInput;
+        const bodyKeyField = 'bodyKeyField' in meta ? meta.bodyKeyField : undefined;
+        if (target)
+            headers.set('X-SCOPE3-CUSTOMER-ID', target);
+        if (meta.idempotencyKey) {
+            const key = options.idempotencyKey;
+            if (typeof key !== 'string' || !/^[\x21-\x7e]{1,255}$/.test(key))
+                throw new TypeError('idempotencyKey must be a non-empty printable string');
+            headers.set('Idempotency-Key', key);
+            if (bodyKeyField) {
+                const supplied = fields[bodyKeyField];
+                if (supplied !== undefined && supplied !== key)
+                    throw new TypeError(`${bodyKeyField} must match idempotencyKey for ${operation}`);
+                requestInput = { ...fields, [bodyKeyField]: key };
+            }
+        }
+        let path = meta.path;
+        const query = new URLSearchParams();
+        for (const param of meta.parameters) {
+            const value = fields[param.name];
+            if (value === undefined) {
+                if (param.required)
+                    throw new TypeError(`Missing ${param.name}`);
+                continue;
+            }
+            if (param.location === 'path')
+                path = path.replace(`{${param.name}}`, encodeURIComponent(String(value)));
+            else
+                query.set(param.name, String(value));
+        }
+        if (meta.body)
+            headers.set('Content-Type', 'application/json');
+        const url = `${this.#url}${path}${query.size ? `?${query}` : ''}`;
+        const retries = this.#options.maxRetries ?? 2;
+        for (let attempt = 0;; attempt++) {
+            try {
+                let response;
+                try {
+                    response = await deadline(this.#fetch(url, {
+                        method: meta.method,
+                        headers,
+                        body: meta.body ? JSON.stringify(requestInput) : undefined,
+                        signal,
+                        redirect: 'error',
+                    }));
+                }
+                catch (error) {
+                    if (timeoutSignal.aborted)
+                        throw new TimeoutError(error);
+                    if (options.signal?.aborted)
+                        throw error;
+                    throw new ConnectionError(error);
+                }
+                const requestId = response.headers.get('x-request-id');
+                // A 202 is an in-flight/uncertain write receipt, never a completed result.
+                if (response.status === 202) {
+                    let receiptEnvelope;
+                    try {
+                        receiptEnvelope = await deadline(response.json());
+                    }
+                    catch (error) {
+                        throwIfAborted();
+                        if (!(error instanceof SyntaxError))
+                            throw error;
+                        throw new ProtocolError(response.status, requestId);
+                    }
+                    if (!inFlightReceipt(receiptEnvelope))
+                        throw new ProtocolError(response.status, requestId);
+                    throw new InFlightReceiptError(requestId, retryAfterMs(response.headers.get('retry-after')), receiptEnvelope.data.receipt);
+                }
+                if (meta.binary && response.ok)
+                    return {
+                        data: new Uint8Array(await deadline(response.arrayBuffer())),
+                        status: response.status,
+                        headers: response.headers,
+                        requestId,
+                    };
+                let envelope;
+                try {
+                    envelope = await deadline(response.json());
+                }
+                catch (error) {
+                    throwIfAborted();
+                    if (!(error instanceof SyntaxError))
+                        throw error;
+                    throw new ProtocolError(response.status, requestId);
+                }
+                if (!response.ok) {
+                    if (record(envelope) &&
+                        envelope.data === null &&
+                        errorModel(envelope.error))
+                        throw typedError(response.status, envelope.error, requestId);
+                    throw new ProtocolError(response.status, requestId);
+                }
+                if (!record(envelope) ||
+                    envelope.error !== null ||
+                    !('data' in envelope))
+                    throw new ProtocolError(response.status, requestId);
+                return {
+                    data: envelope.data,
+                    status: response.status,
+                    headers: response.headers,
+                    requestId,
+                };
+            }
+            catch (error) {
+                if (attempt >= retries || !retryable(error))
+                    throw error;
+                await deadline(wait(retryDelayMs(error, attempt), signal));
+            }
+        }
+    }
+}
+/** Re-invoke a caller-owned keyed write until an in-flight receipt settles. */
+export async function settle(run, options = {}) {
+    const timeout = options.timeoutMs ?? 30_000;
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        throw new TypeError('timeoutMs must be positive');
+    const timeoutSignal = AbortSignal.timeout(timeout);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, timeoutSignal])
+        : timeoutSignal;
+    while (true) {
+        signal.throwIfAborted();
+        try {
+            return await abortable(run(signal), signal);
+        }
+        catch (error) {
+            if (!(error instanceof InFlightReceiptError))
+                throw error;
+            await wait(error.retryAfterMs ?? 1000, signal);
+        }
+    }
+}
+/** Visit pages while preserving the exact caller-owned query and cursor rules. */
+export async function* paginate(read, next, signal) {
+    let cursor;
+    const seen = new Set();
+    do {
+        signal?.throwIfAborted();
+        const page = await (signal
+            ? abortable(read(cursor, signal), signal)
+            : read(cursor));
+        signal?.throwIfAborted();
+        const nextCursor = next(page) ?? undefined;
+        if (nextCursor && seen.has(nextCursor))
+            throw new ProtocolError(200, null);
+        if (nextCursor)
+            seen.add(nextCursor);
+        yield page;
+        cursor = nextCursor;
+    } while (cursor);
+}
+/** The caller supplies the contract's status predicate and keeps idempotency keys stable. */
+export async function poll(read, complete, options) {
+    const interval = options.intervalMs ?? 1000;
+    if (!Number.isFinite(interval) || interval <= 0)
+        throw new TypeError('intervalMs must be positive');
+    while (true) {
+        options.signal.throwIfAborted();
+        const result = await abortable(read(options.signal), options.signal);
+        options.signal.throwIfAborted();
+        if (complete(result))
+            return result;
+        await new Promise((resolve, reject) => {
+            const cleanup = () => options.signal.removeEventListener('abort', abort);
+            const timer = setTimeout(() => {
+                cleanup();
+                resolve();
+            }, interval);
+            const abort = () => {
+                clearTimeout(timer);
+                cleanup();
+                reject(options.signal.reason);
+            };
+            options.signal.addEventListener('abort', abort, { once: true });
+            if (options.signal.aborted)
+                abort();
+        });
+    }
+}
+function handoffResume(value) {
+    return (record(value) &&
+        value.kind === 'manual' &&
+        value.reason ===
+            'This Page has no durable completion receipt. Read the affected object before continuing; opening or closing the browser is not completion.');
+}
+/** Return an actionable human handoff, or null when no supported URL is present. */
+export function getHandoff(result) {
+    const handoff = result?.humanHandoff;
+    if (!record(handoff) ||
+        handoff.kind !== 'human_action_required' ||
+        typeof handoff.url !== 'string' ||
+        typeof handoff.expiresAt !== 'string' ||
+        !handoffResume(handoff.resume))
+        return null;
+    return {
+        kind: 'human_action_required',
+        url: handoff.url,
+        expiresAt: handoff.expiresAt,
+        resume: handoff.resume,
+    };
+}
+/** Pass only a handoff returned by getHandoff; headless calls simply return its URL. */
+export async function openHandoff(handoff, opener) {
+    const url = typeof handoff === 'string' ? handoff : handoff.url;
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password)
+        throw new TypeError('Expected an HTTPS handoff URL');
+    await opener?.(url);
+    return url;
+}
+function abortable(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener('abort', abort);
+        const abort = () => {
+            cleanup();
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+        if (signal.aborted)
+            abort();
+    });
+}

package/dist/webhooks.d.ts

@@ -0,0 +1,24 @@
+export type WebhookSecret = string | {
+    secret: string;
+    acceptsUntil?: number;
+};
+export type WebhookHeaders = {
+    signature: readonly string[];
+    timestamp: readonly string[];
+    deliveryId: readonly string[];
+};
+export type WebhookVerification = {
+    status: 'verified';
+    deliveryId: string;
+    secretId: string;
+    timestamp: number;
+} | {
+    status: 'malformed' | 'unknown_secret' | 'expired_secret' | 'invalid_signature' | 'invalid_clock' | 'stale';
+};
+/** Verify one duplicate-preserving V3 webhook delivery before parsing its body. */
+export declare function verifyWebhook(input: {
+    rawBody: Uint8Array | string;
+    headers: WebhookHeaders;
+    secrets: Readonly<Record<string, WebhookSecret>>;
+    nowUnixSeconds?: number;
+}): WebhookVerification;

package/dist/webhooks.js

@@ -0,0 +1,49 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const webhookSignature = /^v1,kid=([A-Za-z0-9_-]{1,128}),hmac-sha256=([a-f0-9]{64})$/;
+const webhookTimestamp = /^[1-9][0-9]{9,12}$/;
+const webhookDeliveryId = /^[!-~]{1,128}$/;
+const exactlyOne = (values) => Array.isArray(values) && values.length === 1 && typeof values[0] === 'string'
+    ? values[0]
+    : null;
+/** Verify one duplicate-preserving V3 webhook delivery before parsing its body. */
+export function verifyWebhook(input) {
+    const nowUnixSeconds = input.nowUnixSeconds ?? Math.floor(Date.now() / 1000);
+    if (!Number.isSafeInteger(nowUnixSeconds) || nowUnixSeconds < 0)
+        return { status: 'invalid_clock' };
+    const signatureHeader = exactlyOne(input.headers.signature);
+    const timestampHeader = exactlyOne(input.headers.timestamp);
+    const deliveryId = exactlyOne(input.headers.deliveryId);
+    const signature = signatureHeader && webhookSignature.exec(signatureHeader);
+    if (!signature ||
+        !timestampHeader ||
+        !webhookTimestamp.test(timestampHeader) ||
+        !deliveryId ||
+        !webhookDeliveryId.test(deliveryId))
+        return { status: 'malformed' };
+    const timestamp = Number(timestampHeader);
+    if (!Number.isSafeInteger(timestamp))
+        return { status: 'malformed' };
+    const configured = input.secrets[signature[1]];
+    if (!configured)
+        return { status: 'unknown_secret' };
+    const secret = typeof configured === 'string' ? configured : configured.secret;
+    const acceptsUntil = typeof configured === 'string' ? undefined : configured.acceptsUntil;
+    if (!secret ||
+        (acceptsUntil !== undefined &&
+            (!Number.isSafeInteger(acceptsUntil) || nowUnixSeconds > acceptsUntil)))
+        return { status: 'expired_secret' };
+    const body = Buffer.from(input.rawBody);
+    const expected = createHmac('sha256', secret)
+        .update(Buffer.concat([
+        Buffer.from(`v1.${timestampHeader}.${deliveryId}.`),
+        body,
+    ]))
+        .digest();
+    const supplied = Buffer.from(signature[2], 'hex');
+    if (supplied.length !== expected.length ||
+        !timingSafeEqual(supplied, expected))
+        return { status: 'invalid_signature' };
+    if (Math.abs(nowUnixSeconds - timestamp) > 300)
+        return { status: 'stale' };
+    return { status: 'verified', deliveryId, secretId: signature[1], timestamp };
+}