@doany-ai/sdk 0.2.7 → 0.2.9-alpha.0

package/dist/client.js

@@ -7,6 +7,8 @@ import { confirmAppUserConnection, createConnectorsModule, createUserConnectorsM
 import { getAccessToken } from "./utils/auth-utils.js";
 import { createFunctionsModule } from "./modules/functions.js";
 import { createPaymentsModule } from "./modules/payments.js";
+import { createCatalogModule } from "./modules/catalog.js";
+import { createOrdersModule } from "./modules/orders.js";
 import { createAgentsModule } from "./modules/agents.js";
 import { createAiGatewayModule } from "./modules/ai-gateway.js";
 import { createAppLogsModule } from "./modules/app-logs.js";
@@ -140,6 +142,8 @@ export function createClient(config) {
         }),
         integrations: createIntegrationsModule(axiosClient, appId),
         payments: createPaymentsModule(axiosClient, appId),
+        catalog: createCatalogModule(axiosClient, appId),
+        orders: createOrdersModule(axiosClient, appId),
         connectors: createUserConnectorsModule(axiosClient, appId),
         auth: userAuthModule,
         functions: createFunctionsModule(functionsAxiosClient, appId, {
@@ -202,6 +206,9 @@ export function createClient(config) {
             return {
                 getCheckoutSession: full.getCheckoutSession.bind(full),
                 getSubscription: full.getSubscription.bind(full),
+                // Reading the products is not a decision for any browser, and a
+                // fulfilment function often needs what it just sold.
+                products: full.products,
             };
         })(),
         functions: createFunctionsModule(serviceRoleFunctionsAxiosClient, appId, {
@@ -457,6 +464,21 @@ export function createClientFromRequest(request) {
     if (runIdHeader) {
         additionalHeaders["X-Run-Id"] = runIdHeader.slice(0, 128);
     }
+    // Workflow diagnostics are separate from Annie's X-Run-Id attribution.
+    // The function proxy owns these headers; neither their presence nor their
+    // contents grant permissions or change billing. Match its bounded format.
+    if (serviceRoleToken) {
+        for (const name of [
+            "X-Doany-Workflow-Id",
+            "X-Doany-Workflow-Run-Id",
+            "X-Doany-Workflow-Step-Id",
+        ]) {
+            const value = request.headers.get(name);
+            if (value && /^[A-Za-z0-9_.:/-]{1,128}$/.test(value)) {
+                additionalHeaders[name] = value;
+            }
+        }
+    }
     return createClient({
         serverUrl: serverUrlHeader || "https://api.doany.ai",
         appId,

package/dist/client.types.d.ts

@@ -5,6 +5,8 @@ import type { SsoModule } from "./modules/sso.types.js";
 import type { ConnectorsModule, UserConnectorsModule } from "./modules/connectors.types.js";
 import type { FunctionsModule } from "./modules/functions.types.js";
 import type { PaymentsModule } from "./modules/payments.types.js";
+import type { CatalogModule } from "./modules/catalog.types.js";
+import type { OrdersModule } from "./modules/orders.types.js";
 import type { AgentsModule } from "./modules/agents.types.js";
 import type { AiGatewayModule } from "./modules/ai-gateway.types.js";
 import type { AppLogsModule } from "./modules/app-logs.types.js";
@@ -101,6 +103,10 @@ export interface DoanyClient {
     integrations: IntegrationsModule;
     /** {@link PaymentsModule | Payments module} for taking card payments through Stripe. */
     payments: PaymentsModule;
+    /** {@link CatalogModule | Catalog module} for reading what the business offers. */
+    catalog: CatalogModule;
+    /** {@link OrdersModule | Orders module} for placing and reading orders. */
+    orders: OrdersModule;
     /** Cleanup function to disconnect WebSocket connections. Call when you're done with the client. */
     cleanup: () => void;
     /**
@@ -150,10 +156,11 @@ export interface DoanyClient {
          * service-role caller, so the ordinary client cannot resolve a mode and
          * the read fails whatever the function forwards.
          *
-         * Only the reads are here. There is no service-role checkout — opening one
-         * is a decision that belongs to the browser that is actually there.
+         * Only the reads are here — the two above and the products. There
+         * is no service-role checkout: opening one is a decision that belongs to
+         * the browser that is actually there.
          */
-        payments: Pick<PaymentsModule, "getCheckoutSession" | "getSubscription">;
+        payments: Pick<PaymentsModule, "getCheckoutSession" | "getSubscription" | "products">;
         /** {@link SsoModule | SSO module} for generating SSO tokens.
          * @internal
          */

package/dist/index.d.ts

@@ -11,7 +11,9 @@ export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./mod
 export type { AgentsModule, AgentName, AgentNameRegistry, AgentConversation, AgentMessage, AgentMessageReasoning, AgentMessageToolCall, AgentMessageUsage, AgentMessageCustomContext, AgentMessageMetadata, CreateConversationParams, } from "./modules/agents.types.js";
 export type { AiGatewayModule, AiGatewayConnection, } from "./modules/ai-gateway.types.js";
 export type { AppLogsModule } from "./modules/app-logs.types.js";
-export type { PaymentsModule, CheckoutLineItem, CreateCheckoutParams, CreateCheckoutResult, CreateEmbeddedCheckoutResult, CheckoutSession, SubscriptionState, BillingPortalParams, } from "./modules/payments.types.js";
+export type { PaymentsModule, ProductsModule, Product, ProductQuery, ProductSort, CheckoutLineItem, CreateCheckoutParams, CreateCheckoutResult, CreateEmbeddedCheckoutResult, CheckoutSession, SubscriptionState, BillingPortalParams, } from "./modules/payments.types.js";
+export type { CatalogModule, CatalogItem, CatalogVariant, CatalogListParams, } from "./modules/catalog.types.js";
+export type { OrdersModule, Order, OrderItem, OrderBuyer, OrderSummary, OrderStatus, FulfillmentStatus, CreateOrderParams, CreateOrderOptions, CreateOrderResult, OrderListParams, OrderAccessOptions, } from "./modules/orders.types.js";
 export type { SsoModule, SsoAccessTokenResponse } from "./modules/sso.types.js";
 export type { ConnectorsModule, UserConnectorsModule, ConnectorApiRequest, ConnectorApiResponse, ConnectorProxyRawResponse, } from "./modules/connectors.types.js";
 export type { CustomIntegrationsModule, CustomIntegrationCallParams, CustomIntegrationCallResponse, } from "./modules/custom-integrations.types.js";

package/dist/modules/catalog.d.ts

@@ -0,0 +1,8 @@
+import { AxiosInstance } from "axios";
+import { CatalogModule } from "./catalog.types";
+/**
+ * Creates the catalog module for the Doany SDK.
+ *
+ * @internal
+ */
+export declare function createCatalogModule(axios: AxiosInstance, appId: string): CatalogModule;

package/dist/modules/catalog.js

@@ -0,0 +1,29 @@
+/**
+ * Creates the catalog module for the Doany SDK.
+ *
+ * @internal
+ */
+export function createCatalogModule(axios, appId) {
+    const baseURL = `/apps/${appId}/catalog/items`;
+    return {
+        async list(params = {}) {
+            const query = {};
+            if (params.category)
+                query.category = params.category;
+            if (params.purchasable)
+                query.purchasable = "true";
+            if (params.limit)
+                query.limit = params.limit;
+            if (params.skip)
+                query.skip = params.skip;
+            if (params.sort)
+                query.sort = params.sort;
+            const data = await axios.get(baseURL, { params: query });
+            return data;
+        },
+        async get(itemId) {
+            const data = await axios.get(`${baseURL}/${encodeURIComponent(itemId)}`);
+            return data;
+        },
+    };
+}

package/dist/modules/catalog.types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * One way an item is sold: a name, a price and, for services, a duration.
+ */
+export interface CatalogVariant {
+    id: string;
+    name: string;
+    /** In the currency's smallest unit (cents). `null` when no price is set; `0` is free. */
+    price_amount: number | null;
+    /** Three upper-case letters, e.g. `"USD"`. `null` exactly when `price_amount` is. */
+    currency: string | null;
+    duration_minutes: number | null;
+    /** The variant to preselect. */
+    is_default: boolean;
+    sort_order: number;
+}
+/**
+ * Something the business offers, with the variants it is sold in.
+ */
+export interface CatalogItem {
+    id: string;
+    name: string;
+    description: string | null;
+    category: string | null;
+    image_url: string | null;
+    direct_purchase_enabled: boolean;
+    /**
+     * Whether it can be ordered right now with `doany.orders.create`. An item
+     * that is shown but not purchasable is for display only.
+     */
+    purchasable: boolean;
+    sort_order: number;
+    /** In display order. */
+    variants: CatalogVariant[];
+}
+export interface CatalogListParams {
+    category?: string;
+    /** Only items that can be ordered right now. */
+    purchasable?: boolean;
+    limit?: number;
+    skip?: number;
+    /** A field name, `-` in front for descending: `sort_order` (default), `name`, `category`, `created_at`. */
+    sort?: string;
+}
+/**
+ * What the business offers. Read-only: the catalog is managed by the business
+ * owner in Doany, not from the site.
+ */
+export interface CatalogModule {
+    /**
+     * The published items.
+     *
+     * @example
+     * ```typescript
+     * const items = await doany.catalog.list({ purchasable: true });
+     * ```
+     */
+    list(params?: CatalogListParams): Promise<CatalogItem[]>;
+    /**
+     * One published item. Rejects with status 404 when there is no such item or
+     * it is not published.
+     */
+    get(itemId: string): Promise<CatalogItem>;
+}

package/dist/modules/catalog.types.js

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

package/dist/modules/orders.d.ts

@@ -0,0 +1,21 @@
+import { AxiosInstance } from "axios";
+import { OrdersModule } from "./orders.types";
+/** @internal Tests start from a page that has placed nothing. */
+export declare function resetOrderAttempts(): void;
+/**
+ * Creates the orders module for the Doany SDK.
+ *
+ * Two things are handled here so that page code does not have to:
+ *
+ * - **Retries do not double-order.** The backend requires an `Idempotency-Key`.
+ *   Identical calls that overlap are one request (a double click), and a key
+ *   is kept for an identical order for as long as its outcome is unknown (it
+ *   failed without an answer), so a retry after a dropped connection lands on
+ *   the same order — also after a page reload, for 15 minutes. Once the
+ *   server has answered, the next identical order is a new one.
+ * - **A guest can reopen their order.** The order's access token is kept for
+ *   the browser session and sent with `get` / `cancel` for that order.
+ *
+ * @internal
+ */
+export declare function createOrdersModule(axios: AxiosInstance, appId: string): OrdersModule;

package/dist/modules/orders.js

@@ -0,0 +1,330 @@
+// Shared by every client the page creates: two clients placing the same order
+// at once are still one attempt, and neither may release a key the other is
+// still waiting on. Entries are named by app, actor and request.
+const inFlight = new Map();
+const memory = new Map();
+/** @internal Tests start from a page that has placed nothing. */
+export function resetOrderAttempts() {
+    inFlight.clear();
+    memory.clear();
+}
+function newKey() {
+    const c = globalThis.crypto;
+    if (c === null || c === void 0 ? void 0 : c.randomUUID)
+        return `order-${c.randomUUID()}`;
+    let out = "order-";
+    for (let i = 0; i < 32; i++)
+        out += Math.floor(Math.random() * 16).toString(16);
+    return out;
+}
+/**
+ * How long an order whose outcome is unknown keeps its key across page loads.
+ * Long enough to cover "the request failed, reload, try again"; short enough
+ * that ordering the same things again later is a new order.
+ */
+const ATTEMPT_TTL_MS = 15 * 60 * 1000;
+/** cyrb53: a short, stable name for a payload, so the payload itself (the buyer's
+ * details) is not what gets written as a storage key. A collision would only
+ * reuse a key for a different payload, which the backend refuses with 409. */
+function nameOf(text) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/** Who the backend will take this request to be from: it keeps idempotency
+ * keys per signed-in account and per guest, so an unresolved attempt belongs
+ * to whoever made it and nobody else may reuse or clear it. */
+function actorOf(axios) {
+    var _a, _b, _c;
+    const header = (_c = (_b = (_a = axios.defaults) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b.common) === null || _c === void 0 ? void 0 : _c["Authorization"];
+    if (typeof header !== "string" || !header.startsWith("Bearer "))
+        return "guest";
+    try {
+        const payload = header.split(".")[1].replace(/-/g, "+").replace(/_/g, "/");
+        const sub = JSON.parse(atob(payload)).sub;
+        if (typeof sub === "string" && sub)
+            return `user:${sub}`;
+    }
+    catch (_d) {
+        /* not a JWT we can read */
+    }
+    return `token:${nameOf(header)}`;
+}
+/**
+ * The request exactly as it will be sent, in one canonical form: keys sorted,
+ * `quantity` filled in with its default, `variant_id` lower-cased.
+ *
+ * The retry key is looked up by THIS, and this is what goes over the wire, so
+ * "same key" always means "the very same request". Anything looser breaks in
+ * one of two ways: write the same order with the keys in another order and it
+ * would get a second key (a duplicate order), or fold two requests the backend
+ * tells apart — a stray space, a blank optional field — into one and the
+ * refusal of one would release the key of the other. So whatever is
+ * normalised here is normalised in the request itself, never only in the key.
+ */
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const item = value[key];
+            if (item !== undefined)
+                out[key] = canonical(item);
+        }
+        return out;
+    }
+    return value;
+}
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** A valid name or email in the one form the backend stores it in, so editing
+ * a stray space or a capital between a failed attempt and its retry is still
+ * the same order. Anything blank or invalid is left exactly as typed: the
+ * backend refuses it, and a refused request must stay its own request. */
+function tidyBuyer(buyer) {
+    if (!buyer || typeof buyer !== "object")
+        return buyer;
+    const out = { ...buyer };
+    // `email: null` and no email are the same thing to the backend.
+    for (const optional of ["email", "phone"]) {
+        if (out[optional] === null)
+            delete out[optional];
+    }
+    if (typeof out.name === "string" && out.name.trim())
+        out.name = out.name.trim();
+    if (typeof out.email === "string" && EMAIL.test(out.email.trim())) {
+        out.email = out.email.trim().toLowerCase();
+    }
+    return out;
+}
+function wireOf(params) {
+    const items = Array.isArray(params === null || params === void 0 ? void 0 : params.items)
+        ? params.items.map((item) => item && typeof item === "object"
+            ? {
+                ...item,
+                variant_id: typeof item.variant_id === "string" ? item.variant_id.toLowerCase() : item.variant_id,
+                // Only a quantity that was left out: null or anything else odd
+                // goes to the backend as it is and is refused there.
+                quantity: item.quantity === undefined ? 1 : item.quantity,
+            }
+            : item)
+        : params === null || params === void 0 ? void 0 : params.items;
+    return canonical({ ...params, items, buyer: tidyBuyer(params === null || params === void 0 ? void 0 : params.buyer) });
+}
+function session() {
+    try {
+        return typeof window !== "undefined" ? window.sessionStorage : null;
+    }
+    catch (_a) {
+        return null; // storage can be blocked (private mode, sandboxed iframe)
+    }
+}
+/**
+ * Creates the orders module for the Doany SDK.
+ *
+ * Two things are handled here so that page code does not have to:
+ *
+ * - **Retries do not double-order.** The backend requires an `Idempotency-Key`.
+ *   Identical calls that overlap are one request (a double click), and a key
+ *   is kept for an identical order for as long as its outcome is unknown (it
+ *   failed without an answer), so a retry after a dropped connection lands on
+ *   the same order — also after a page reload, for 15 minutes. Once the
+ *   server has answered, the next identical order is a new one.
+ * - **A guest can reopen their order.** The order's access token is kept for
+ *   the browser session and sent with `get` / `cancel` for that order.
+ *
+ * @internal
+ */
+export function createOrdersModule(axios, appId) {
+    const baseURL = `/apps/${appId}/orders`;
+    // Keys of orders whose outcome is unknown. In memory, and mirrored to
+    // sessionStorage so that reloading the page after a failed request — the
+    // usual way people recover — still retries with the same key.
+    const fresh = (at) => typeof at === "number" && Date.now() - at < ATTEMPT_TTL_MS;
+    const attemptKey = (fingerprint) => `doany_order_attempt_${appId}_${nameOf(fingerprint)}`;
+    const undecided = {
+        get(fingerprint) {
+            var _a, _b;
+            // The window applies wherever the key is held: a tab left open is not a
+            // reason to answer a new order with an old one.
+            const held = memory.get(fingerprint);
+            if (held && fresh(held.at))
+                return held.key;
+            memory.delete(fingerprint);
+            try {
+                const raw = (_a = session()) === null || _a === void 0 ? void 0 : _a.getItem(attemptKey(fingerprint));
+                if (!raw)
+                    return undefined;
+                const saved = JSON.parse(raw);
+                if (saved.key && fresh(saved.at))
+                    return saved.key;
+                (_b = session()) === null || _b === void 0 ? void 0 : _b.removeItem(attemptKey(fingerprint));
+            }
+            catch (_c) {
+                /* unreadable storage is the same as nothing stored */
+            }
+            return undefined;
+        },
+        set(fingerprint, key) {
+            var _a;
+            const entry = { key, at: Date.now() };
+            memory.set(fingerprint, entry);
+            try {
+                (_a = session()) === null || _a === void 0 ? void 0 : _a.setItem(attemptKey(fingerprint), JSON.stringify(entry));
+            }
+            catch (_b) {
+                /* best effort */
+            }
+        },
+        delete(fingerprint) {
+            var _a;
+            memory.delete(fingerprint);
+            try {
+                (_a = session()) === null || _a === void 0 ? void 0 : _a.removeItem(attemptKey(fingerprint));
+            }
+            catch (_b) {
+                /* best effort */
+            }
+        },
+    };
+    // A kept token belongs to whoever placed the order. It is stored under that
+    // actor and looked up under the current one — plus `guest`, so an order placed
+    // before signing in can still be opened after. What it never does is follow
+    // the tab to another account, or stay usable once its account signed out.
+    const tokenKey = (actor, orderId) => { var _a, _b; return `doany_order_token_${appId}_${nameOf(`${(_b = (_a = axios.defaults) === null || _a === void 0 ? void 0 : _a.baseURL) !== null && _b !== void 0 ? _b : ""}|${actor}`)}_${orderId}`; };
+    function remember(actor, orderId, token) {
+        var _a;
+        if (!token)
+            return;
+        try {
+            (_a = session()) === null || _a === void 0 ? void 0 : _a.setItem(tokenKey(actor, orderId), token);
+        }
+        catch (_b) {
+            /* best effort */
+        }
+    }
+    function accessHeaders(orderId, options) {
+        var _a, _b;
+        let token = options === null || options === void 0 ? void 0 : options.accessToken;
+        if (!token) {
+            try {
+                const store = session();
+                token =
+                    (_b = (_a = store === null || store === void 0 ? void 0 : store.getItem(tokenKey(actorOf(axios), orderId))) !== null && _a !== void 0 ? _a : store === null || store === void 0 ? void 0 : store.getItem(tokenKey("guest", orderId))) !== null && _b !== void 0 ? _b : undefined;
+            }
+            catch (_c) {
+                token = undefined;
+            }
+        }
+        return token ? { "X-Doany-Access-Token": token } : {};
+    }
+    return {
+        create(params, options) {
+            var _a, _b, _c, _d, _e;
+            // Read once, before anything is awaited: the request goes out as this
+            // actor, and its token must be kept for this actor even if the page has
+            // signed in as someone else by the time the answer arrives.
+            const actor = actorOf(axios);
+            const wire = wireOf(params);
+            const fingerprint = JSON.stringify([(_b = (_a = axios.defaults) === null || _a === void 0 ? void 0 : _a.baseURL) !== null && _b !== void 0 ? _b : "", appId, actor, wire]);
+            const flight = `${(_c = options === null || options === void 0 ? void 0 : options.idempotencyKey) !== null && _c !== void 0 ? _c : ""}\u0000${fingerprint}`;
+            // A second identical call while the first is still out is the same
+            // attempt (a double click): it gets the first one's answer, not a
+            // request of its own.
+            const running = inFlight.get(flight);
+            if (running)
+                return running;
+            const key = (_e = (_d = options === null || options === void 0 ? void 0 : options.idempotencyKey) !== null && _d !== void 0 ? _d : undecided.get(fingerprint)) !== null && _e !== void 0 ? _e : newKey();
+            // Written on every attempt, not only the first: the window runs from the
+            // LAST time this key went out, or a retry late in it would leave the next
+            // one without the key of an order that may just have been placed.
+            if (!(options === null || options === void 0 ? void 0 : options.idempotencyKey))
+                undecided.set(fingerprint, key);
+            // Only the attempt that put a key there may take it away: a page-keyed
+            // attempt for the same things must not release the automatic one's key.
+            const settle = () => {
+                if (!(options === null || options === void 0 ? void 0 : options.idempotencyKey) && undecided.get(fingerprint) === key) {
+                    undecided.delete(fingerprint);
+                }
+            };
+            const attempt = (async () => {
+                var _a;
+                try {
+                    const data = (await axios.request({
+                        method: "POST",
+                        url: baseURL,
+                        data: wire,
+                        headers: { "Idempotency-Key": key },
+                    }));
+                    // A 2xx that does not carry an order (a proxy's page, a mismatched
+                    // deployment) decides nothing: the key stays for the retry.
+                    if (typeof ((_a = data === null || data === void 0 ? void 0 : data.order) === null || _a === void 0 ? void 0 : _a.id) !== "string") {
+                        throw new Error("The order service answered without an order");
+                    }
+                    settle();
+                    remember(actor, data.order.id, data.access_token);
+                    return data;
+                }
+                catch (error) {
+                    // A 4xx is a decision (refused, invalid) — except 408 and 429, and
+                    // 401, which the rest of the client also treats as "try again"
+                    // (client.ts): a proxy can time out AFTER passing the request on.
+                    // Everything else may have placed the order, so the same key goes
+                    // out again next time; keeping a key too long costs nothing.
+                    const status = error === null || error === void 0 ? void 0 : error.status;
+                    if (typeof status === "number" &&
+                        status >= 400 &&
+                        status < 500 &&
+                        ![401, 408, 429].includes(status)) {
+                        settle();
+                    }
+                    else if (!(options === null || options === void 0 ? void 0 : options.idempotencyKey)) {
+                        // Still undecided: the window runs from now, however long the
+                        // request itself was out.
+                        undecided.set(fingerprint, key);
+                    }
+                    throw error;
+                }
+                finally {
+                    inFlight.delete(flight);
+                }
+            })();
+            inFlight.set(flight, attempt);
+            return attempt;
+        },
+        async list(params = {}) {
+            const query = {};
+            if (params.status)
+                query.status = params.status;
+            if (params.limit)
+                query.limit = params.limit;
+            if (params.skip)
+                query.skip = params.skip;
+            if (params.sort)
+                query.sort = params.sort;
+            const data = await axios.get(baseURL, { params: query });
+            return data;
+        },
+        async get(orderId, options) {
+            const data = await axios.get(`${baseURL}/${encodeURIComponent(orderId)}`, {
+                headers: accessHeaders(orderId, options),
+            });
+            return data;
+        },
+        async cancel(orderId, options) {
+            const data = await axios.request({
+                method: "POST",
+                url: `${baseURL}/${encodeURIComponent(orderId)}/cancel`,
+                headers: accessHeaders(orderId, options),
+            });
+            return data;
+        },
+    };
+}

package/dist/modules/orders.types.d.ts

@@ -0,0 +1,125 @@
+export type OrderStatus = "open" | "completed" | "canceled";
+export type FulfillmentStatus = "pending" | "in_progress" | "completed" | "canceled";
+/** A line of an order. Names, price and duration are as they were when it was placed. */
+export interface OrderItem {
+    id: string;
+    variant_id: string;
+    item_name: string;
+    variant_name: string;
+    duration_minutes: number | null;
+    unit_amount: number;
+    quantity: number;
+    line_amount: number;
+    fulfillment_mode: "manual" | "calendar";
+    fulfillment_status: FulfillmentStatus | null;
+    fulfilled_at: string | null;
+}
+export interface OrderBuyer {
+    name: string;
+    email: string | null;
+    phone: string | null;
+}
+export interface Order {
+    id: string;
+    /** The number to show the customer. */
+    order_number: string;
+    status: OrderStatus;
+    currency: string;
+    /** In the currency's smallest unit (cents). */
+    total_amount: number;
+    buyer: OrderBuyer;
+    items: OrderItem[];
+    payment: {
+        /** `false` for a free order, which is `completed` as soon as it is placed. */
+        required: boolean;
+        amount_received: number;
+        amount_refunded: number;
+    };
+    created_at: string;
+    completed_at: string | null;
+    canceled_at: string | null;
+}
+export interface OrderSummary {
+    id: string;
+    order_number: string;
+    status: OrderStatus;
+    currency: string;
+    total_amount: number;
+    buyer: {
+        name: string;
+    };
+    created_at: string;
+}
+export interface CreateOrderParams {
+    /** What is being bought. Prices are not sent: the order takes them from the catalog. */
+    items: Array<{
+        variant_id: string;
+        quantity?: number;
+    }>;
+    /** Who it is for. `email` or `phone` is required; `phone` in E.164 form (`+14155550123`). */
+    buyer: {
+        name: string;
+        email?: string;
+        phone?: string;
+    };
+}
+export interface CreateOrderOptions {
+    /**
+     * Identifies this attempt, so that a retry does not place a second order.
+     * Optional: the SDK reuses one key for an identical order that is still in
+     * flight or failed without an answer.
+     */
+    idempotencyKey?: string;
+}
+export interface CreateOrderResult {
+    order: Order;
+    /**
+     * Lets someone who is not signed in open this order again. The SDK keeps it
+     * for the rest of the browser session, so `orders.get` and `orders.cancel`
+     * work without passing it; put it in a link (after `#`) to reach the order
+     * from elsewhere.
+     */
+    access_token?: string;
+    /** `false` when the order is free and already completed. */
+    payment_required: boolean;
+}
+export interface OrderListParams {
+    status?: OrderStatus;
+    limit?: number;
+    skip?: number;
+    /** `created_at` (default, newest first), `total_amount`, `order_number`, `status`; `-` in front for descending. */
+    sort?: string;
+}
+export interface OrderAccessOptions {
+    /** The order's `access_token`, when it came from a link rather than from this browser session. */
+    accessToken?: string;
+}
+/**
+ * Orders placed on the site.
+ */
+export interface OrdersModule {
+    /**
+     * Places an order for catalog variants. Works signed in or not.
+     *
+     * Rejects with status 409 and `code` `NOT_PURCHASABLE` (with `data.variant_id`)
+     * when something in it cannot be bought, or `MIXED_CURRENCY`.
+     *
+     * @example
+     * ```typescript
+     * const { order, payment_required } = await doany.orders.create({
+     *   items: [{ variant_id: variant.id, quantity: 1 }],
+     *   buyer: { name, email },
+     * });
+     * ```
+     */
+    create(params: CreateOrderParams, options?: CreateOrderOptions): Promise<CreateOrderResult>;
+    /** The signed-in customer's orders, newest first. Rejects with status 401 when nobody is signed in. */
+    list(params?: OrderListParams): Promise<OrderSummary[]>;
+    /**
+     * One order. Available to the signed-in customer who placed it, or to anyone
+     * holding its access token; otherwise rejects with status 404.
+     */
+    get(orderId: string, options?: OrderAccessOptions): Promise<Order>;
+    /** Cancels an order that is still `open`. Rejects with status 409 (`INVALID_STATE`) otherwise. */
+    cancel(orderId: string, options?: OrderAccessOptions): Promise<Order>;
+}

package/dist/modules/orders.types.js

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

package/dist/modules/payments.d.ts

@@ -1,5 +1,16 @@
 import { AxiosInstance } from "axios";
-import { PaymentsModule } from "./payments.types";
+import { PaymentsModule, ProductsModule } from "./payments.types";
+/**
+ * The product reads.
+ *
+ * Parameters go over the wire exactly as an entity's do (`sort`, `limit`,
+ * `skip`, `q` as JSON), because the point of this module is that code written
+ * against `entities.Product` moves over by renaming it — same arguments, same
+ * records back.
+ *
+ * @internal
+ */
+export declare function createProductsModule(axios: AxiosInstance, appId: string): ProductsModule;
 /**
  * Creates the payments module for the Doany SDK.
  *

package/dist/modules/payments.js

@@ -1,3 +1,42 @@
+/**
+ * The product reads.
+ *
+ * Parameters go over the wire exactly as an entity's do (`sort`, `limit`,
+ * `skip`, `q` as JSON), because the point of this module is that code written
+ * against `entities.Product` moves over by renaming it — same arguments, same
+ * records back.
+ *
+ * @internal
+ */
+export function createProductsModule(axios, appId) {
+    const baseURL = `/apps/${appId}/payments/products`;
+    function params(sort, limit, skip) {
+        const out = {};
+        if (sort)
+            out.sort = sort;
+        if (limit)
+            out.limit = limit;
+        if (skip)
+            out.skip = skip;
+        return out;
+    }
+    return {
+        async list(sort, limit, skip) {
+            const data = await axios.get(baseURL, { params: params(sort, limit, skip) });
+            return data;
+        },
+        async filter(query, sort, limit, skip) {
+            const data = await axios.get(baseURL, {
+                params: { q: JSON.stringify(query), ...params(sort, limit, skip) },
+            });
+            return data;
+        },
+        async get(id) {
+            const data = await axios.get(`${baseURL}/${encodeURIComponent(id)}`);
+            return data;
+        },
+    };
+}
 /**
  * Creates the payments module for the Doany SDK.
  *
@@ -21,6 +60,7 @@ export function createPaymentsModule(axios, appId) {
     // Axios's declared return type does not reflect that, so the results below
     // are cast through `unknown`.
     return {
+        products: createProductsModule(axios, appId),
         createCheckoutSession,
         async getSubscription(subscriptionId) {
             const data = await axios.request({

package/dist/modules/payments.types.d.ts

@@ -1,13 +1,15 @@
 /**
  * One thing being sold in a checkout.
  *
- * A line item names a record in your own app data — doany keeps your catalog
+ * A line item names a record in your own app data — doany keeps your products
  * there rather than as objects inside Stripe, which is why switching from test
  * to real payments needs no migration.
  */
 export type CheckoutLineItem = {
     /**
-     * The `id` of a record in this app's `Product` entity.
+     * The `id` of one of this app's products — a record from
+     * {@linkcode ProductsModule | doany.payments.products}, or from the `Product`
+     * entity on an app whose products predate it.
      *
      * The price, name and currency all come from that record — you cannot pass
      * a price. This endpoint is reachable by anyone (a shop has to sell to
@@ -65,7 +67,7 @@ export type CreateCheckoutResult = {
     /** `test` in the preview, `live` on a published site that has gone live. */
     mode: "test" | "live";
     /**
-     * What the customer is about to agree to, decided by the catalog.
+     * What the customer is about to agree to, decided by the product.
      *
      * `subscription` when the products carry a `recurring_interval`, `payment`
      * otherwise. Say the right word on the button: "Subscribe" over a one-off
@@ -203,17 +205,98 @@ export type CheckoutSession = {
      */
     access_token?: string;
 };
+/**
+ * One of this app's products, as {@linkcode ProductsModule} returns it.
+ *
+ * The same shape an entity record has: the platform's fields and the system
+ * fields by their entity names, and every field of the app's own (`slug`,
+ * `category`, `image_url`, …) at the top level beside them.
+ */
+export type Product = {
+    id: string;
+    name: string;
+    description: string | null;
+    /** Minor units — 2400 is 24.00. `null` for something shown but not sold. */
+    price_cents: number | null;
+    /** Lowercase ISO code, or `null` for the checkout's default. */
+    currency: string | null;
+    /** Present => a subscription billed this often. `null` => a one-off. */
+    recurring_interval: "week" | "month" | "year" | null;
+    /** `false` is off sale: still readable, cannot be bought. */
+    is_available: boolean;
+    created_date: string;
+    updated_date: string;
+    created_by: string | null;
+    created_by_id: string | null;
+    is_sample: boolean;
+    /**
+     * Only ever on {@linkcode ProductsModule.get}: the product was removed from
+     * the store. Kept readable because past orders and subscriptions name it.
+     */
+    is_deleted?: true;
+    /**
+     * The app's own fields. `any`, as on an entity record, so code that read
+     * `product.slug.toLowerCase()` off `entities.Product` still type-checks.
+     */
+    [field: string]: any;
+};
+/**
+ * A field to order by, `-` first for descending: `"price_cents"`,
+ * `"-created_date"`, or one of the app's own fields.
+ */
+export type ProductSort = string;
+/**
+ * Equality only — `{ slug: "starter" }`, `{ is_available: true }`. Several
+ * fields must all match. `{ field: null }` also matches a product that does not
+ * have the field. Operators (`$gt`, `$in`, …) are refused.
+ */
+export type ProductQuery = Record<string, string | number | boolean | null>;
+/**
+ * Read this app's products. Read-only: products are added and priced by
+ * the app owner in the Payments panel, or by asking Annie.
+ *
+ * Same methods, arguments and results as an entity's reads, so code written
+ * against `entities.Product` moves over by renaming it. Records come back in
+ * the order they were created when no `sort` is given.
+ */
+export interface ProductsModule {
+    /**
+     * @example
+     * ```typescript
+     * const products = await doany.payments.products.list();
+     * const newest = await doany.payments.products.list('-created_date', 20);
+     * ```
+     */
+    list(sort?: ProductSort, limit?: number, skip?: number): Promise<Product[]>;
+    /**
+     * @example
+     * ```typescript
+     * const [plan] = await doany.payments.products.filter({ slug: 'pro' });
+     * const onSale = await doany.payments.products.filter(
+     *   { is_available: true }, 'price_cents', 10,
+     * );
+     * ```
+     */
+    filter(query: ProductQuery, sort?: ProductSort, limit?: number, skip?: number): Promise<Product[]>;
+    /**
+     * One product by id. A removed product is still returned, with
+     * `is_deleted: true`; an id that was never a product is a 404.
+     */
+    get(id: string): Promise<Product>;
+}
 /**
  * Take card payments on your site.
  *
  * Money goes to the app owner's own Stripe account — doany never holds it and
  * takes no cut. Stripe's usual per-transaction fee applies.
  *
- * ## Prices live in your data, not in your code
+ * ## Prices live with the product, not in your code
  *
- * Sellable things are records in this app's `Product` entity, with the price in
- * an integer `price_cents` field. A checkout names the product; the server
- * looks up what it costs.
+ * Sellable things are this app's products, read with
+ * {@linkcode PaymentsModule.products}, with the price in an integer
+ * `price_cents` field. A checkout names the product; the server looks up what
+ * it costs. (An app whose products predate this keeps them in a `Product`
+ * entity; checkout reads whichever one the app uses.)
  *
  * ## Test and real payments
  *
@@ -229,12 +312,14 @@ export type CheckoutSession = {
  * The same code covers both. There is no key to configure and no mode to set.
  */
 export interface PaymentsModule {
+    /** This app's products. See {@linkcode ProductsModule}. */
+    products: ProductsModule;
     /**
      * Opens a Stripe checkout and returns the URL to send the customer to.
      *
      * @example Sell one item
      * ```typescript
-     * // The price comes from the Product record, not from this call.
+     * // The price comes from the product, not from this call.
      * const { url } = await doany.payments.createCheckoutSession({
      *   line_items: [{ product_id: product.id, quantity: 1 }],
      *   success_path: '/thanks',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doany-ai/sdk",
-  "version": "0.2.7",
+  "version": "0.2.9-alpha.0",
   "description": "JavaScript SDK for the doany app platform (API-compatible fork of @base44/sdk)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",