@usequeek/app-sdk 0.4.0

package/dist/client.js

@@ -0,0 +1,269 @@
+import { randomUUID } from "node:crypto";
+/** Path of the public Merchant API below the store host. */
+export const MERCHANT_API_PATH = "/api/v1/merchant";
+/** Hosts a handoff `api_base` may point at without extra configuration. */
+export const DEFAULT_API_HOSTS = ["api.usequeek.com"];
+/** Thrown at client construction when `apiBase` fails validation — before any fetch. */
+export class InvalidApiBaseError extends Error {
+    code = "invalid_api_base";
+    constructor(message) {
+        super(message);
+        this.name = "InvalidApiBaseError";
+    }
+}
+const ENV_HOSTS_VAR = "QUEEK_API_HOSTS";
+const ENV_DEV_HOSTS_VAR = "QUEEK_DEV_API_HOSTS";
+const HOSTNAME_RE = /^(?=.{1,253}$)[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/i;
+function parseHostList(raw, varName) {
+    return raw.split(",").map((entry) => {
+        const host = entry.trim().toLowerCase();
+        if (!HOSTNAME_RE.test(host)) {
+            throw new InvalidApiBaseError(`Invalid ${varName} entry ${JSON.stringify(entry)}: must be a bare hostname (no scheme, port or path).`);
+        }
+        return host;
+    });
+}
+/**
+ * Extra allowed `apiBase` hosts for test/local backends, from
+ * `QUEEK_API_HOSTS` (comma-separated bare hostnames). Parsed strictly: any
+ * entry that is not a bare hostname throws — nothing is silently skipped.
+ */
+export function apiHostsFromEnv(env = process.env) {
+    const raw = env[ENV_HOSTS_VAR];
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    return parseHostList(raw, ENV_HOSTS_VAR);
+}
+/**
+ * DEV-ONLY extra allowed hosts (e.g. an HTTPS tunnel to a local backend),
+ * from `QUEEK_DEV_API_HOSTS`. REFUSED when NODE_ENV=production: a dev
+ * tunnel host must never be allowlisted in production, even by accident.
+ * Throws at client construction, before any fetch.
+ */
+export function devApiHostsFromEnv(env = process.env) {
+    const raw = env[ENV_DEV_HOSTS_VAR];
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    if ((env.NODE_ENV ?? "") === "production") {
+        throw new InvalidApiBaseError(`${ENV_DEV_HOSTS_VAR} is set but NODE_ENV=production: dev tunnel hosts are refused in production.`);
+    }
+    return parseHostList(raw, ENV_DEV_HOSTS_VAR);
+}
+/**
+ * Validate the handoff `apiBase` and normalize it to the full merchant base.
+ * Throws `InvalidApiBaseError` on: unparseable URL, non-https scheme,
+ * embedded credentials, an explicit port on a DEFAULT host (production
+ * hosts are 443 — ports ride only on dev/test hosts), or a host outside
+ * `DEFAULT_API_HOSTS + allowedApiHosts + QUEEK_API_HOSTS +
+ * QUEEK_DEV_API_HOSTS`.
+ */
+export function resolveApiBase(raw, allowedApiHosts = []) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new InvalidApiBaseError(`Invalid api_base ${JSON.stringify(raw)}: not a URL.`);
+    }
+    if (url.protocol !== "https:") {
+        throw new InvalidApiBaseError(`Invalid api_base ${JSON.stringify(raw)}: https only.`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new InvalidApiBaseError("Invalid api_base: embedded credentials are never allowed.");
+    }
+    const host = url.hostname.toLowerCase();
+    if (DEFAULT_API_HOSTS.includes(host) && url.port !== "") {
+        throw new InvalidApiBaseError(`Invalid api_base ${JSON.stringify(raw)}: the production host takes no port (443).`);
+    }
+    const allowlist = new Set([
+        ...DEFAULT_API_HOSTS,
+        ...allowedApiHosts.map((h) => h.toLowerCase()),
+        ...apiHostsFromEnv(),
+        ...devApiHostsFromEnv(),
+    ]);
+    if (!allowlist.has(host)) {
+        throw new InvalidApiBaseError(`Invalid api_base host ${JSON.stringify(host)}: not on the allowlist (add test hosts via ${ENV_HOSTS_VAR}).`);
+    }
+    const path = url.pathname.replace(/\/+$/, "");
+    const merchantPath = path.endsWith(MERCHANT_API_PATH) ? path : `${path}${MERCHANT_API_PATH}`;
+    return `https://${host}${url.port !== "" ? `:${url.port}` : ""}${merchantPath}`;
+}
+const WRITE_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+export function newIdempotencyKey() {
+    return randomUUID();
+}
+function parseRetryAfterMs(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    const seconds = Number(trimmed);
+    if (Number.isFinite(seconds) && trimmed !== "") {
+        return Math.max(0, seconds * 1000);
+    }
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return null;
+}
+export class QueekApiError extends Error {
+    status;
+    code;
+    field;
+    errors;
+    docUrl;
+    requestId;
+    /** Set on 429s (and only there): how long to wait before retrying. */
+    retryAfterMs;
+    constructor(details) {
+        super(details.message);
+        this.name = "QueekApiError";
+        this.status = details.status;
+        this.code = details.code;
+        this.field = details.field;
+        this.errors = details.errors;
+        this.docUrl = details.docUrl;
+        this.requestId = details.requestId;
+        this.retryAfterMs = details.retryAfterMs;
+    }
+    get isRateLimited() {
+        return this.status === 429;
+    }
+    get isAuthFailure() {
+        return this.status === 401 || this.status === 403;
+    }
+}
+/**
+ * Build a `QueekApiError` from a status + parsed body + headers. Shared
+ * with the installation-token mint path (`tokens.ts`), so the merchant and
+ * app-credential endpoints parse errors identically.
+ */
+export function queekApiErrorFromResponse(status, body, headers) {
+    const record = (typeof body === "object" && body !== null ? body : {});
+    const envelope = (typeof record.error === "object" && record.error !== null ? record.error : {});
+    const firstString = (...candidates) => {
+        for (const candidate of candidates) {
+            if (typeof candidate === "string" && candidate.trim() !== "")
+                return candidate;
+        }
+        return undefined;
+    };
+    const code = firstString(envelope.code, record.error_code) ?? (status === 429 ? "too_many_requests" : "server_error");
+    const message = firstString(envelope.message, record.message) ?? `Queek API error ${status}`;
+    const details = {
+        status,
+        code,
+        message,
+        field: firstString(envelope.field),
+        errors: (envelope.errors ?? record.errors),
+        docUrl: firstString(envelope.doc_url),
+        requestId: firstString(envelope.request_id, record.request_id, headers.get("x-request-id")),
+    };
+    if (details.errors === undefined)
+        delete details.errors;
+    if (details.field === undefined)
+        delete details.field;
+    if (details.docUrl === undefined)
+        delete details.docUrl;
+    if (details.requestId === undefined)
+        delete details.requestId;
+    if (status === 429) {
+        const retryAfterMs = parseRetryAfterMs(headers.get("retry-after"));
+        if (retryAfterMs !== null)
+            details.retryAfterMs = retryAfterMs;
+    }
+    return new QueekApiError(details);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryable(error) {
+    return error instanceof QueekApiError && (error.isRateLimited || error.code === "network_error");
+}
+function retryDelayMs(error, attempt, baseDelayMs, maxDelayMs) {
+    if (error.isRateLimited && error.retryAfterMs !== undefined)
+        return error.retryAfterMs;
+    return Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+}
+export function createQueekClient(clientOptions) {
+    const base = resolveApiBase(clientOptions.apiBase, clientOptions.allowedApiHosts ?? []);
+    const fetchImpl = clientOptions.fetchImpl ?? fetch;
+    const userAgent = clientOptions.userAgent ?? "queek-app/1.0";
+    async function request(method, path, options = {}) {
+        const upper = method.toUpperCase();
+        const url = new URL(`${base}${path.startsWith("/") ? path : `/${path}`}`);
+        if (options.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        const headers = new Headers();
+        headers.set("X-Client-Key", clientOptions.apiKey);
+        headers.set("Accept", "application/json");
+        headers.set("User-Agent", userAgent);
+        headers.set("X-Request-Id", options.requestId ?? randomUUID());
+        let body;
+        if (options.body !== undefined) {
+            headers.set("Content-Type", "application/json");
+            body = JSON.stringify(options.body);
+        }
+        if (WRITE_METHODS.has(upper)) {
+            headers.set("Idempotency-Key", options.idempotencyKey ?? newIdempotencyKey());
+        }
+        let response;
+        try {
+            response = await fetchImpl(url.toString(), { method: upper, headers, body, signal: options.signal });
+        }
+        catch (cause) {
+            throw new QueekApiError({
+                status: 0,
+                code: "network_error",
+                message: cause instanceof Error ? `Could not reach Queek: ${cause.message}` : "Could not reach Queek.",
+            });
+        }
+        const text = await response.text();
+        const parsed = text === "" ? null : tryParseJson(text);
+        if (!response.ok) {
+            throw queekApiErrorFromResponse(response.status, parsed, response.headers);
+        }
+        return parsed;
+    }
+    async function requestWithRetry(method, path, options = {}) {
+        const maxAttempts = Math.max(1, Math.floor(options.maxAttempts ?? 3));
+        const baseDelayMs = options.baseDelayMs ?? 250;
+        const maxDelayMs = options.maxDelayMs ?? 5000;
+        const sleep = options.sleep ?? defaultSleep;
+        // One key for every attempt: Queek replays same-key+same-body writes
+        // instead of duplicating them, so retrying a write is safe.
+        const idempotencyKey = options.idempotencyKey ?? (WRITE_METHODS.has(method.toUpperCase()) ? newIdempotencyKey() : undefined);
+        let lastError;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                return await request(method, path, { ...options, idempotencyKey });
+            }
+            catch (error) {
+                lastError = error;
+                const retryable = error instanceof QueekApiError && isRetryable(error);
+                if (!retryable || attempt === maxAttempts - 1)
+                    throw error;
+                await sleep(retryDelayMs(error, attempt, baseDelayMs, maxDelayMs));
+            }
+        }
+        throw lastError;
+    }
+    return {
+        getStore: (signal) => request("GET", "/store", { signal }),
+        request,
+        requestWithRetry,
+    };
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text.slice(0, 500) };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8CzC,4DAA4D;AAC5D,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,kBAAkB,CAAC,CAAC;AAEtD,wFAAwF;AACxF,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,kBAAkB,CAAC;IAEnC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,aAAa,GAAG,iBAAiB,CAAC;AACxC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAChD,MAAM,WAAW,GACf,2FAA2F,CAAC;AAE9F,SAAS,aAAa,CAAC,GAAW,EAAE,OAAe;IACjD,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAClC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACxC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,mBAAmB,CAC3B,WAAW,OAAO,UAAU,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,sDAAsD,CACxG,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAG,GAAG,CAAC,aAAa,CAAC,CAAC;IAC/B,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACtD,OAAO,aAAa,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACrE,MAAM,GAAG,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IACtD,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,KAAK,YAAY,EAAE,CAAC;QAC1C,MAAM,IAAI,mBAAmB,CAC3B,GAAG,iBAAiB,8EAA8E,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,aAAa,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW,EAAE,kBAA4B,EAAE;IACxE,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,mBAAmB,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,mBAAmB,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,mBAAmB,CAAC,2DAA2D,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACxC,IAAI,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACxD,MAAM,IAAI,mBAAmB,CAC3B,oBAAoB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,4CAA4C,CACpF,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;QACxB,GAAG,iBAAiB;QACpB,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9C,GAAG,eAAe,EAAE;QACpB,GAAG,kBAAkB,EAAE;KACxB,CAAC,CAAC;IACH,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,mBAAmB,CAC3B,yBAAyB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,8CAA8C,aAAa,IAAI,CAC7G,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,iBAAiB,EAAE,CAAC;IAC7F,OAAO,WAAW,IAAI,GAAG,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,YAAY,EAAE,CAAC;AAClF,CAAC;AAsBD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAElE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAoB;IAC7C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC;IACrC,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAaD,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,MAAM,CAAS;IACf,IAAI,CAAS;IACb,KAAK,CAAU;IACf,MAAM,CAAW;IACjB,MAAM,CAAU;IAChB,SAAS,CAAU;IAC5B,sEAAsE;IAC7D,YAAY,CAAU;IAE/B,YAAY,OAA0B;QACpC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC3C,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IAC7B,CAAC;IAED,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IACpD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAc,EAAE,IAAa,EAAE,OAAgB;IACvF,MAAM,MAAM,GAAG,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;IAClG,MAAM,QAAQ,GAAG,CAAC,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAG9F,CAAC;IACF,MAAM,WAAW,GAAG,CAAC,GAAG,UAAqB,EAAsB,EAAE;QACnE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE;gBAAE,OAAO,SAAS,CAAC;QACjF,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IACF,MAAM,IAAI,GACR,WAAW,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IAC3G,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,mBAAmB,MAAM,EAAE,CAAC;IAC7F,MAAM,OAAO,GAAsB;QACjC,MAAM;QACN,IAAI;QACJ,OAAO;QACP,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC;QAClC,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAY;QACrD,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC;QACrC,SAAS,EAAE,WAAW,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;KAC5F,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC;IACxD,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC;IACtD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC;IACxD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,SAAS,CAAC;IAC9D,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,MAAM,YAAY,GAAG,iBAAiB,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;QACnE,IAAI,YAAY,KAAK,IAAI;YAAE,OAAO,CAAC,YAAY,GAAG,YAAY,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC;AA2BD,SAAS,YAAY,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,YAAY,aAAa,IAAI,CAAC,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC;AACnG,CAAC;AAED,SAAS,YAAY,CACnB,KAAoB,EACpB,OAAe,EACf,WAAmB,EACnB,UAAkB;IAElB,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,YAAY,CAAC;IACvF,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,aAAiC;IACjE,MAAM,IAAI,GAAG,cAAc,CAAC,aAAa,CAAC,OAAO,EAAE,aAAa,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IACxF,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,IAAI,KAAK,CAAC;IACnD,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,IAAI,eAAe,CAAC;IAE7D,KAAK,UAAU,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,UAA0B,EAAE;QAClF,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1E,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzD,IAAI,KAAK,KAAK,SAAS;oBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QACrC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,SAAS,IAAI,UAAU,EAAE,CAAC,CAAC;QAC/D,IAAI,IAAwB,CAAC;QAC7B,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;YAChD,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,OAAO,CAAC,cAAc,IAAI,iBAAiB,EAAE,CAAC,CAAC;QAChF,CAAC;QAED,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACvG,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,aAAa,CAAC;gBACtB,MAAM,EAAE,CAAC;gBACT,IAAI,EAAE,eAAe;gBACrB,OAAO,EACL,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,wBAAwB;aAChG,CAAC,CAAC;QACL,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,MAAM,MAAM,GAAY,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAChE,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,yBAAyB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,MAAW,CAAC;IACrB,CAAC;IAED,KAAK,UAAU,gBAAgB,CAC7B,MAAc,EACd,IAAY,EACZ,UAAyC,EAAE;QAE3C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC;QACtE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC;QAC/C,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;QAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;QAC5C,qEAAqE;QACrE,4DAA4D;QAC5D,MAAM,cAAc,GAClB,OAAO,CAAC,cAAc,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACxG,IAAI,SAAkB,CAAC;QACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;YACvD,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS,GAAG,KAAK,CAAC;gBAClB,MAAM,SAAS,GAAG,KAAK,YAAY,aAAa,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC;gBACvE,IAAI,CAAC,SAAS,IAAI,OAAO,KAAK,WAAW,GAAG,CAAC;oBAAE,MAAM,KAAK,CAAC;gBAC3D,MAAM,KAAK,CAAC,YAAY,CAAC,KAAsB,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;QACD,MAAM,SAAS,CAAC;IAClB,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,CAAC,MAAoB,EAAE,EAAE,CAAC,OAAO,CAAe,KAAK,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC;QACtF,OAAO;QACP,gBAAgB;KACjB,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/collected.d.ts

@@ -0,0 +1,103 @@
+import type { QueekClient } from "./client.js";
+import type { components } from "./merchant-schema.js";
+/**
+ * Installation-bound app writes (S3a): the setup notice, merchant alerts,
+ * collected definitions and record submits. Every helper takes a
+ * `QueekClient` built from the installation's own key — the backend
+ * resolves the installation from that key, never from the body — and
+ * returns the decoded `data` payload of the success envelope.
+ *
+ * Contracts: config/vendor_api_keys.php (Apps group + Forms proof path)
+ * at queek_backend@c1fa1c31; request shapes below are the generated
+ * `components` schemas from the same backend's merchant export.
+ */
+type Schemas = components["schemas"];
+export interface SuccessEnvelope<T> {
+    status: "success";
+    message: string;
+    data: T;
+}
+/** PUT app/setup — full-body write, so callers send the whole sheet every time. */
+export type SetupNoticeStatus = "incomplete" | "complete";
+export interface SetupNoticeItem {
+    key: string;
+    label: string;
+    value: string;
+    sensitive: boolean;
+    copyable: boolean;
+    instructions?: string;
+}
+export interface SetupNotice {
+    status: SetupNoticeStatus;
+    items: SetupNoticeItem[];
+}
+export type SetupNoticeBody = Schemas["UpdateAppSetupNoticeRequest"];
+export declare function setSetupNotice(client: QueekClient, notice: SetupNotice, options?: {
+    idempotencyKey?: string;
+}): Promise<unknown>;
+/** POST app/alerts — pages the merchant through the bell (in-app only). */
+export type AlertSeverity = "info" | "warning" | "error";
+export interface MerchantAlert {
+    severity: AlertSeverity;
+    title: string;
+    message: string;
+    dedupe_key?: string;
+    meta?: string[];
+}
+export type AlertBody = Schemas["SendAppAlertRequest"];
+export declare function sendAlert(client: QueekClient, alert: MerchantAlert, options?: {
+    idempotencyKey?: string;
+}): Promise<unknown>;
+/** Collected definitions owned by the calling installation. */
+export type CollectedField = Schemas["CollectedDefinitionRequest"]["fields"][number];
+export interface CollectedDefinitionCreate {
+    /** Must start with the installation's `app_{slug}_{p_id}_` prefix (403 otherwise). */
+    type: string;
+    name: string;
+    description?: string;
+    display_field: string;
+    fields: CollectedField[];
+}
+export interface CollectedDefinitionUpdate {
+    name?: string;
+    description?: string;
+    display_field?: string;
+    fields?: CollectedField[];
+}
+/**
+ * A collected definition as the Merchant API returns it: the generated
+ * MetaobjectDefinitionResource (typed since bf7329af) with the create
+ * endpoint's field vocabulary for `fields` (the generated `unknown[]`
+ * carries no field shape).
+ */
+export type CollectedDefinition = Omit<Schemas["MetaobjectDefinitionResource"], "fields"> & {
+    fields: CollectedField[];
+};
+export declare const collectedDefinitions: {
+    /** GET collected-definitions — only the calling installation's own types. */
+    list(client: QueekClient): Promise<CollectedDefinition[]>;
+    /** POST collected-definitions — class forced collected, stamped to the installation. */
+    create(client: QueekClient, definition: CollectedDefinitionCreate, options?: {
+        idempotencyKey?: string;
+    }): Promise<CollectedDefinition>;
+    /** PATCH collected-definitions/{p_id} — the type itself is immutable. */
+    update(client: QueekClient, pId: number, patch: CollectedDefinitionUpdate, options?: {
+        idempotencyKey?: string;
+    }): Promise<CollectedDefinition>;
+};
+/**
+ * POST records — one record under the installation's own type.
+ *
+ * `values` is a `{field_key: value}` object (spec-correct since
+ * bf7329af: object + additionalProperties; the writer validates pairs). A
+ * fresh Idempotency-Key is generated per call unless the caller passes
+ * one — no two submits ever share a key.
+ */
+export declare function createRecord(client: QueekClient, submit: {
+    definition: string;
+    values: Record<string, unknown>;
+}, options?: {
+    idempotencyKey?: string;
+}): Promise<unknown>;
+export {};
+//# sourceMappingURL=collected.d.ts.map

package/dist/collected.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collected.d.ts","sourceRoot":"","sources":["../src/collected.ts"],"names":[],"mappings":"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"}

package/dist/collected.js

@@ -0,0 +1,59 @@
+export async function setSetupNotice(client, notice, options = {}) {
+    const body = {
+        status: notice.status,
+        items: notice.items.map((item) => ({
+            ...item,
+            instructions: item.instructions ?? null,
+        })),
+    };
+    const response = await client.request("PUT", "/app/setup", {
+        body,
+        idempotencyKey: options.idempotencyKey,
+    });
+    return response.data;
+}
+export async function sendAlert(client, alert, options = {}) {
+    const body = {
+        ...alert,
+        dedupe_key: alert.dedupe_key ?? null,
+        meta: alert.meta ?? null,
+    };
+    const response = await client.request("POST", "/app/alerts", {
+        body,
+        idempotencyKey: options.idempotencyKey,
+    });
+    return response.data;
+}
+export const collectedDefinitions = {
+    /** GET collected-definitions — only the calling installation's own types. */
+    async list(client) {
+        const response = await client.request("GET", "/collected-definitions");
+        return response.data;
+    },
+    /** POST collected-definitions — class forced collected, stamped to the installation. */
+    async create(client, definition, options = {}) {
+        const response = await client.request("POST", "/collected-definitions", { body: definition, idempotencyKey: options.idempotencyKey });
+        return response.data;
+    },
+    /** PATCH collected-definitions/{p_id} — the type itself is immutable. */
+    async update(client, pId, patch, options = {}) {
+        const response = await client.request("PATCH", `/collected-definitions/${pId}`, { body: patch, idempotencyKey: options.idempotencyKey });
+        return response.data;
+    },
+};
+/**
+ * POST records — one record under the installation's own type.
+ *
+ * `values` is a `{field_key: value}` object (spec-correct since
+ * bf7329af: object + additionalProperties; the writer validates pairs). A
+ * fresh Idempotency-Key is generated per call unless the caller passes
+ * one — no two submits ever share a key.
+ */
+export async function createRecord(client, submit, options = {}) {
+    const response = await client.request("POST", "/records", {
+        body: submit,
+        idempotencyKey: options.idempotencyKey,
+    });
+    return response.data;
+}
+//# sourceMappingURL=collected.js.map

package/dist/collected.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collected.js","sourceRoot":"","sources":["../src/collected.ts"],"names":[],"mappings":"AA0CA,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAmB,EACnB,MAAmB,EACnB,UAAuC,EAAE;IAEzC,MAAM,IAAI,GAAoB;QAC5B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACjC,GAAG,IAAI;YACP,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI;SACxC,CAAC,CAAC;KACJ,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAA2B,KAAK,EAAE,YAAY,EAAE;QACnF,IAAI;QACJ,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,IAAI,CAAC;AACvB,CAAC;AAeD,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAmB,EACnB,KAAoB,EACpB,UAAuC,EAAE;IAEzC,MAAM,IAAI,GAAc;QACtB,GAAG,KAAK;QACR,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,IAAI;KACzB,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAA2B,MAAM,EAAE,aAAa,EAAE;QACrF,IAAI;QACJ,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,IAAI,CAAC;AACvB,CAAC;AA+BD,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,6EAA6E;IAC7E,KAAK,CAAC,IAAI,CAAC,MAAmB;QAC5B,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CACnC,KAAK,EACL,wBAAwB,CACzB,CAAC;QACF,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,MAAM,CACV,MAAmB,EACnB,UAAqC,EACrC,UAAuC,EAAE;QAEzC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CACnC,MAAM,EACN,wBAAwB,EACxB,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAC7D,CAAC;QACF,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,MAAM,CACV,MAAmB,EACnB,GAAW,EACX,KAAgC,EAChC,UAAuC,EAAE;QAEzC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CACnC,OAAO,EACP,0BAA0B,GAAG,EAAE,EAC/B,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CACxD,CAAC;QACF,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAmB,EACnB,MAA+D,EAC/D,UAAuC,EAAE;IAEzC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAA2B,MAAM,EAAE,UAAU,EAAE;QAClF,IAAI,EAAE,MAAM;QACZ,cAAc,EAAE,OAAO,CAAC,cAAc;KACvC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC,IAAI,CAAC;AACvB,CAAC"}

package/dist/crypto.d.ts

@@ -0,0 +1,6 @@
+export declare function parseStoreKey(raw: string | undefined): Buffer;
+/** Non-secret fingerprint for logs (first 4 bytes, hex). Reveals nothing usable. */
+export declare function storeKeyFingerprint(key: Buffer): string;
+export declare function encryptSecret(plaintext: string, key: Buffer): string;
+export declare function decryptSecret(envelope: string, key: Buffer): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAgBA,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CA8B7D;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CASpE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBnE"}

package/dist/crypto.js

@@ -0,0 +1,76 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+/**
+ * AES-256-GCM envelope encryption for secrets at rest (installation api_key
+ * and webhook_secret). One random 96-bit IV per value; the stored string is
+ * `v1.<base64 iv>.<base64 ciphertext+tag>`.
+ *
+ * The 32-byte data key comes from the environment (`APP_ENCRYPTION_KEY`, base64
+ * or hex of 32 bytes) and is parsed by `parseStoreKey()`. The key itself is
+ * NEVER logged — only its 8-char fingerprint (first bytes, hex) may appear in
+ * logs to prove which key a ciphertext belongs to.
+ */
+const ENVELOPE_VERSION = "v1";
+const IV_BYTES = 12;
+export function parseStoreKey(raw) {
+    if (!raw || raw.trim() === "") {
+        throw new Error("Missing store encryption key: set APP_ENCRYPTION_KEY to base64 or hex of 32 random bytes.");
+    }
+    const value = raw.trim();
+    const candidates = [];
+    // Base64 only when it looks like base64 (length multiple of 4); a raw
+    // 32-char passphrase must NOT be misread as base64.
+    if (/^[A-Za-z0-9+/]+={0,2}$/.test(value) && value.length % 4 === 0) {
+        try {
+            candidates.push(Buffer.from(value, "base64"));
+        }
+        catch {
+            // fall through to hex/utf8
+        }
+    }
+    if (/^[0-9a-fA-F]+$/.test(value)) {
+        try {
+            candidates.push(Buffer.from(value, "hex"));
+        }
+        catch {
+            // fall through
+        }
+    }
+    candidates.push(Buffer.from(value, "utf8"));
+    const key = candidates.find((candidate) => candidate.length === 32);
+    if (!key) {
+        throw new Error("Invalid APP_ENCRYPTION_KEY: must decode to exactly 32 bytes (base64 or hex).");
+    }
+    return key;
+}
+/** Non-secret fingerprint for logs (first 4 bytes, hex). Reveals nothing usable. */
+export function storeKeyFingerprint(key) {
+    return key.subarray(0, 4).toString("hex");
+}
+export function encryptSecret(plaintext, key) {
+    if (key.length !== 32)
+        throw new Error("Encryption key must be 32 bytes.");
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [ENVELOPE_VERSION, iv.toString("base64"), Buffer.concat([ciphertext, tag]).toString("base64")].join(".");
+}
+export function decryptSecret(envelope, key) {
+    if (key.length !== 32)
+        throw new Error("Encryption key must be 32 bytes.");
+    const parts = envelope.split(".");
+    if (parts.length !== 3 || parts[0] !== ENVELOPE_VERSION) {
+        throw new Error("Unrecognized secret envelope (expected v1.<iv>.<ciphertext>).");
+    }
+    const iv = Buffer.from(parts[1], "base64");
+    const raw = Buffer.from(parts[2], "base64");
+    if (iv.length !== IV_BYTES || raw.length < 17) {
+        throw new Error("Corrupt secret envelope.");
+    }
+    const tag = raw.subarray(raw.length - 16);
+    const ciphertext = raw.subarray(0, raw.length - 16);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/frame.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Framed-page handshake client (S4 stage 2): the browser-safe half of the
+ * dashboard bridge. Carries NO secret and performs NO verification — it only
+ * shapes and addresses messages. The dashboard (queek-merchant) enforces
+ * origin+source binding and mints tokens; the app backend verifies them via
+ * `./server` (`verifySessionToken`).
+ *
+ * DOM-free by design (structural minimal types): the app passes its own
+ * window/parent in, so this module needs no DOM lib and stays import-safe
+ * in edge runtimes.
+ */
+export declare const DASHBOARD_SOURCE = "queek-merchant";
+export declare const APP_SOURCE = "queek-app";
+export type AppOutboundMessage = {
+    source: typeof APP_SOURCE;
+    type: "ready";
+} | {
+    source: typeof APP_SOURCE;
+    type: "resize";
+    height: number;
+} | {
+    source: typeof APP_SOURCE;
+    type: "ack";
+};
+export type AppInboundMessage = {
+    source: typeof DASHBOARD_SOURCE;
+    type: "token";
+    token: string;
+} | {
+    source: typeof DASHBOARD_SOURCE;
+    type: "resize-ack";
+};
+export interface EmbedEvent {
+    origin: string;
+    data: unknown;
+}
+export interface EmbedEventTarget {
+    addEventListener(type: "message", listener: (event: EmbedEvent) => void): void;
+    removeEventListener(type: "message", listener: (event: EmbedEvent) => void): void;
+}
+export interface EmbedPostTarget {
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+export interface FrameBridgeOptions {
+    /** Exact dashboard origin (e.g. from the embed query or app config). */
+    dashboardOrigin: string;
+    target?: EmbedEventTarget;
+    onToken?: (token: string) => void;
+    onResizeAck?: () => void;
+}
+/**
+ * Listen for dashboard messages, accepting only the exact dashboard
+ * origin. Returns an unsubscribe function. Never touches any secret.
+ */
+export declare function listenToDashboard(options: FrameBridgeOptions): () => void;
+/** Announce readiness to the exact dashboard origin — never `"*"`. */
+export declare function sendReady(dashboardOrigin: string, target?: EmbedPostTarget): void;
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB,mBAAmB,CAAC;AACjD,eAAO,MAAM,UAAU,cAAc,CAAC;AAEtC,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,OAAO,UAAU,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,OAAO,UAAU,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,OAAO,UAAU,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAE/C,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,OAAO,gBAAgB,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,MAAM,EAAE,OAAO,gBAAgB,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/E,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;CACnF;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAgBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAkBzE;AAED,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAGjF"}