commerceforai 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,526 @@
+const env = (k) => typeof process !== "undefined" ? process.env?.[k] : undefined;
+/**
+ * ```ts
+ * const commerce = new Commerce(process.env.COMMERCEFORAI_API_KEY);
+ * const { data, error } = await commerce.checkouts.create({ items: [{ variant_id, quantity: 1 }], success_url });
+ * ```
+ */
+export class Commerce {
+    products;
+    variants;
+    inventory;
+    checkouts;
+    orders;
+    events;
+    webhooks;
+    store;
+    returns;
+    emails;
+    collections;
+    customers;
+    discounts;
+    reports;
+    printify;
+    files;
+    key;
+    baseUrl;
+    maxRetries;
+    fetchImpl;
+    constructor(apiKey, opts = {}) {
+        const key = apiKey ?? env("COMMERCEFORAI_API_KEY");
+        if (!key)
+            throw new Error("Missing API key. Pass it to `new Commerce(key)` or set COMMERCEFORAI_API_KEY.");
+        this.key = key;
+        this.baseUrl = (opts.baseUrl ?? env("COMMERCEFORAI_BASE_URL") ?? "https://api.commerceforai.com").replace(/\/$/, "");
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+        this.products = new Products(this);
+        this.variants = new Variants(this);
+        this.inventory = new InventoryResource(this);
+        this.checkouts = new Checkouts(this);
+        this.orders = new Orders(this);
+        this.events = new Events(this);
+        this.webhooks = new Webhooks(this);
+        this.store = new StoreResource(this);
+        this.returns = new Returns(this);
+        this.emails = new Emails(this);
+        this.collections = new Collections(this);
+        this.customers = new Customers(this);
+        this.discounts = new Discounts(this);
+        this.reports = new Reports(this);
+        this.printify = new PrintifyResource(this);
+        this.files = new Files(this);
+    }
+    /** @internal */
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(opts.query ?? {}))
+            if (v !== undefined)
+                url.searchParams.set(k, String(v));
+        const headers = {
+            authorization: `Bearer ${this.key}`,
+            "user-agent": "commerceforai-node/0.1.0",
+        };
+        if (opts.body !== undefined)
+            headers["content-type"] = "application/json";
+        if (method === "POST")
+            headers["idempotency-key"] = opts.idempotencyKey ?? crypto.randomUUID();
+        let lastError = { type: "network_error", message: "Request failed" };
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            if (attempt > 0)
+                await new Promise((r) => setTimeout(r, 250 * 2 ** (attempt - 1)));
+            let res;
+            try {
+                res = await this.fetchImpl(url, {
+                    method, headers, body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                });
+            }
+            catch (e) {
+                lastError = { type: "network_error", message: e instanceof Error ? e.message : String(e) };
+                continue;
+            }
+            const json = await res.json().catch(() => null);
+            if (res.ok)
+                return { data: json, error: null };
+            lastError = json?.error ?? { type: "internal_error", message: `HTTP ${res.status}` };
+            if (res.status !== 429 && res.status < 500)
+                break;
+        }
+        return { data: null, error: lastError };
+    }
+}
+class Resource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+}
+class Products extends Resource {
+    /**
+     * Create up to 100 products in one request. Each succeeds or fails on its own; retry only the failures.
+     * Returns { created, failed, results: [{ index, product } | { index, error }] }.
+     */
+    createMany(products) {
+        return this.client.request("POST", "/v1/products/bulk", { body: { products } });
+    }
+    /** Create a product. Use `price` for a single-variant product, or `variants` for sizes/colors. */
+    create(params, opts) {
+        return this.client.request("POST", "/v1/products", { body: params, ...opts });
+    }
+    get(id) {
+        return this.client.request("GET", `/v1/products/${encodeURIComponent(id)}`);
+    }
+    /** `metadata` filters on exact matches, e.g. { collection: "yosemite" }. */
+    /** `q` searches product names and SKUs. */
+    list(params = {}) {
+        const { metadata, ...rest } = params;
+        const query = { ...rest };
+        for (const [k, v] of Object.entries(metadata ?? {}))
+            query[`metadata[${k}]`] = v;
+        return this.client.request("GET", "/v1/products", { query });
+    }
+    update(id, params) {
+        return this.client.request("PATCH", `/v1/products/${encodeURIComponent(id)}`, { body: params });
+    }
+    /** Archive: hides it from sale; existing orders are unaffected. */
+    archive(id) {
+        return this.client.request("DELETE", `/v1/products/${encodeURIComponent(id)}`);
+    }
+    addVariant(productId, params) {
+        return this.client.request("POST", `/v1/products/${encodeURIComponent(productId)}/variants`, { body: params });
+    }
+}
+class Variants extends Resource {
+    update(id, params) {
+        return this.client.request("PATCH", `/v1/variants/${encodeURIComponent(id)}`, { body: params });
+    }
+}
+class InventoryResource extends Resource {
+    /** Tracked variants, lowest stock first. */
+    list(params = {}) {
+        return this.client.request("GET", "/v1/inventory", { query: params });
+    }
+    /** Add/remove units, e.g. `{ adjust: 50 }` after a restock or `{ adjust: -1 }` for damage. */
+    adjust(variantId, adjust, reason) {
+        return this.client.request("POST", `/v1/variants/${encodeURIComponent(variantId)}/inventory`, { body: { adjust, reason } });
+    }
+    /** Set the absolute on-hand count, e.g. after a stock count. */
+    set(variantId, onHand, reason) {
+        return this.client.request("POST", `/v1/variants/${encodeURIComponent(variantId)}/inventory`, { body: { set: onHand, reason } });
+    }
+}
+class Checkouts extends Resource {
+    /** Reserve stock and create a Stripe-hosted checkout. Redirect the customer to `data.url`. */
+    create(params, opts) {
+        return this.client.request("POST", "/v1/checkouts", { body: params, ...opts });
+    }
+    get(id) {
+        return this.client.request("GET", `/v1/checkouts/${encodeURIComponent(id)}`);
+    }
+}
+class Orders extends Resource {
+    /** `q` matches an order number, customer email or name. */
+    list(params = {}) {
+        const status = Array.isArray(params.status) ? params.status.join(",") : params.status;
+        return this.client.request("GET", "/v1/orders", { query: { ...params, status } });
+    }
+    /** Accepts an order id (`ord_...`) or order number (`1001`). */
+    get(idOrNumber) {
+        return this.client.request("GET", `/v1/orders/${encodeURIComponent(String(idOrNumber))}`);
+    }
+    update(id, params) {
+        return this.client.request("PATCH", `/v1/orders/${encodeURIComponent(String(id))}`, { body: params });
+    }
+    /** Mark shipped. Calling again updates tracking. */
+    fulfill(id, params = {}) {
+        return this.client.request("POST", `/v1/orders/${encodeURIComponent(String(id))}/fulfill`, { body: params });
+    }
+    /**
+     * Get live label rates from your EasyPost/Shippo account, cheapest first.
+     * Parcel weight defaults to the sum of variant `weight_oz`. Pass `return_id` for return-label rates.
+     */
+    shippingRates(id, params = {}) {
+        return this.client.request("POST", `/v1/orders/${encodeURIComponent(String(id))}/shipping-rates`, { body: params });
+    }
+    /** Buy a label for a rate. Outbound labels also mark the order fulfilled with tracking (and email the customer). */
+    buyLabel(id, rateId, opts = {}) {
+        return this.client.request("POST", `/v1/orders/${encodeURIComponent(String(id))}/labels`, { body: { rate_id: rateId, ...opts } });
+    }
+    /** Send a paid order to the print-on-demand provider now (e.g. after fixing a missing print file). */
+    submitFulfillment(id, params = {}) {
+        return this.client.request("POST", `/v1/orders/${encodeURIComponent(String(id))}/submit-fulfillment`, { body: params });
+    }
+    labels(id) {
+        return this.client.request("GET", `/v1/orders/${encodeURIComponent(String(id))}/labels`);
+    }
+    /** Refund through Stripe. Omit `amount` for a full refund; `restock` returns items to inventory. */
+    refund(id, params = {}) {
+        return this.client.request("POST", `/v1/orders/${encodeURIComponent(String(id))}/refund`, { body: params });
+    }
+}
+class Collections extends Resource {
+    /** Group products, e.g. { name: "Mugs", product_ids: [...] }. The handle defaults from the name. */
+    create(params) {
+        return this.client.request("POST", "/v1/collections", { body: params });
+    }
+    list() { return this.client.request("GET", "/v1/collections"); }
+    /** By id or handle. */
+    get(idOrHandle) { return this.client.request("GET", `/v1/collections/${encodeURIComponent(idOrHandle)}`); }
+    /** Passing product_ids replaces the membership (in that order). */
+    update(idOrHandle, params) {
+        return this.client.request("PATCH", `/v1/collections/${encodeURIComponent(idOrHandle)}`, { body: params });
+    }
+    addProducts(idOrHandle, productIds) {
+        return this.client.request("POST", `/v1/collections/${encodeURIComponent(idOrHandle)}/products`, { body: { product_ids: productIds } });
+    }
+    removeProduct(idOrHandle, productId) {
+        return this.client.request("DELETE", `/v1/collections/${encodeURIComponent(idOrHandle)}/products/${encodeURIComponent(productId)}`);
+    }
+    delete(idOrHandle) {
+        return this.client.request("DELETE", `/v1/collections/${encodeURIComponent(idOrHandle)}`);
+    }
+}
+class Customers extends Resource {
+    /** Everyone who has paid, matched by email. Search by email or name; sort by recent (default), spent or orders. */
+    list(params = {}) {
+        return this.client.request("GET", "/v1/customers", { query: params });
+    }
+    /** Totals, last address and full order history for one email. */
+    get(email) { return this.client.request("GET", `/v1/customers/${encodeURIComponent(email)}`); }
+}
+class Discounts extends Resource {
+    /** e.g. { code: "SUMMER20", kind: "percent", value: 20 } or { code: "FIVEOFF", kind: "amount", value: 500 }. */
+    create(params) { return this.client.request("POST", "/v1/discounts", { body: params }); }
+    list() { return this.client.request("GET", "/v1/discounts"); }
+    /** By id or code. */
+    get(idOrCode) { return this.client.request("GET", `/v1/discounts/${encodeURIComponent(idOrCode)}`); }
+    update(idOrCode, params) {
+        return this.client.request("PATCH", `/v1/discounts/${encodeURIComponent(idOrCode)}`, { body: params });
+    }
+    delete(idOrCode) { return this.client.request("DELETE", `/v1/discounts/${encodeURIComponent(idOrCode)}`); }
+}
+class Reports extends Resource {
+    /** Sales over the last `days` (default 30, max 366): totals vs the previous period, a time series and top products. */
+    sales(params = {}) { return this.client.request("GET", "/v1/reports/sales", { query: params }); }
+}
+/**
+ * Printify, through the shop the store connected (your agent never needs the Printify token).
+ * Find a blueprint → a print provider → its variants, then create the product in Printify.
+ */
+class PrintifyResource extends Resource {
+    /** Search Printify's catalog, e.g. blueprints({ q: "heavy cotton tee" }). */
+    blueprints(params = {}) {
+        return this.client.request("GET", "/v1/fulfillment/printify/blueprints", { query: params });
+    }
+    providers(blueprintId) {
+        return this.client.request("GET", `/v1/fulfillment/printify/blueprints/${blueprintId}/providers`);
+    }
+    /** Variant ids per size/color, the option values, and the print placements ("front", "back"…). */
+    variants(blueprintId, providerId) {
+        return this.client.request("GET", `/v1/fulfillment/printify/blueprints/${blueprintId}/providers/${providerId}/variants`);
+    }
+    /**
+     * Create a CommerceForAI product in your Printify shop (artwork uploaded, variants priced, mockups made) and map
+     * its variants so paid orders go to production. Variants are matched by option values; pass fixed_options for
+     * options yours don't have (e.g. { color: "Black" }), or variant_map to map explicitly.
+     */
+    createProduct(productId, params) {
+        return this.client.request("POST", `/v1/products/${encodeURIComponent(productId)}/printify`, { body: params });
+    }
+}
+/**
+ * Image hosting (product photos, logos, print files): PNG, JPEG or WebP up to 25 MB, 5 GB per store.
+ * Photo metadata is removed; the same image is stored once; URLs never change.
+ */
+class Files extends Resource {
+    /**
+     * Upload bytes (Blob, File, Buffer, Uint8Array) or copy from a link.
+     * ```ts
+     * await commerce.files.upload(readFileSync("art/half-dome.png"), { filename: "half-dome.png" });
+     * await commerce.files.upload({ url: "https://example.com/photo.jpg" });
+     * ```
+     */
+    upload(input, opts = {}) {
+        if (input && typeof input === "object" && "url" in input && typeof input.url === "string")
+            return this.client.request("POST", "/v1/files", { body: { url: input.url } });
+        const bytes = input instanceof Blob ? input : new Blob([input]);
+        return bytes.arrayBuffer().then((buf) => this.client.request("POST", "/v1/files", {
+            body: { data: base64(new Uint8Array(buf)), filename: opts.filename ?? (input instanceof File ? input.name : undefined) },
+        }));
+    }
+    list(params = {}) {
+        return this.client.request("GET", "/v1/files", { query: params });
+    }
+    delete(id) { return this.client.request("DELETE", `/v1/files/${encodeURIComponent(id)}`); }
+    /**
+     * Copy products' outside images (and print files) onto the CDN so a moved or deleted source can't break the store.
+     */
+    copyProductImages(productId) {
+        return this.client.request("POST", `/v1/products/${encodeURIComponent(productId)}/copy-images`);
+    }
+    /** The same for every product with outside images, up to `limit` (≤50) per call. Repeat until `remaining` is 0. */
+    copyAllProductImages(opts = {}) {
+        return this.client.request("POST", "/v1/products/copy-images", { body: opts });
+    }
+}
+function base64(bytes) {
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(bytes).toString("base64");
+    let s = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(s);
+}
+class Returns extends Resource {
+    /** Open a return for items on a shipped order. */
+    create(orderId, params) {
+        return this.client.request("POST", `/v1/orders/${encodeURIComponent(String(orderId))}/returns`, { body: params });
+    }
+    list(params = {}) {
+        return this.client.request("GET", "/v1/returns", { query: { ...params, order_id: params.order_id?.toString() } });
+    }
+    get(id) {
+        return this.client.request("GET", `/v1/returns/${encodeURIComponent(id)}`);
+    }
+    /** Approve. `return_label: "cheapest"` buys a prepaid return label and includes it in the customer email. */
+    approve(id, params = {}) {
+        return this.client.request("POST", `/v1/returns/${encodeURIComponent(id)}/approve`, { body: params });
+    }
+    reject(id, params = {}) {
+        return this.client.request("POST", `/v1/returns/${encodeURIComponent(id)}/reject`, { body: params });
+    }
+    /** Items arrived: restock (default true) and refund their value (default true; shipping not included). */
+    receive(id, params = {}) {
+        return this.client.request("POST", `/v1/returns/${encodeURIComponent(id)}/receive`, { body: params });
+    }
+}
+class Emails extends Resource {
+    /** Log of customer emails sent (or queued) for your store. */
+    list(params = {}) {
+        return this.client.request("GET", "/v1/emails", { query: { order_id: params.order_id?.toString() } });
+    }
+    /** Render a customer email with your branding and sample data. Templates: order_confirmation, order_shipped, order_refunded, return_approved, checkout_recovery. */
+    preview(template) {
+        return this.client.request("GET", `/v1/emails/preview/${template}`);
+    }
+    /** Send previews to the store owner (or the signed-in member): one template, or "all". */
+    sendTest(params = {}) {
+        return this.client.request("POST", "/v1/emails/test", { body: params });
+    }
+}
+class Events extends Resource {
+    /** Poll events in order. Pass the last id you processed as `after`. `type` accepts wildcards like `order.*`. */
+    list(params = {}) {
+        return this.client.request("GET", "/v1/events", { query: params });
+    }
+}
+class StoreResource extends Resource {
+    get() {
+        return this.client.request("GET", "/v1/store");
+    }
+    /**
+     * Note on `tax_enabled`: Stripe only collects tax in jurisdictions where you have an active
+     * tax registration in Stripe Tax. Turning this on without registrations collects $0 tax.
+     */
+    /**
+     * Preview a sync from this store's other version (test or live) into this store. Nothing changes.
+     * Syncs cover products, prices, images, collections, discounts and shipping/email settings; never orders, keys, Stripe, site URLs or stock counts.
+     */
+    syncPreview() { return this.client.request("GET", "/v1/store/sync"); }
+    /** Apply a sync into this store. Into a live store, pass the `plan_id` from syncPreview(). */
+    sync(params = {}) {
+        return this.client.request("POST", "/v1/store/sync", { body: params });
+    }
+    update(params) {
+        return this.client.request("PATCH", "/v1/store", { body: params });
+    }
+    /**
+     * Would OpenAI's ChatGPT shopping accept this store's product feed? Per-item errors (rejected) and
+     * warnings (weaker listings), plus where the feed lives (JSON and the jsonl.gz upload format).
+     */
+    checkFeed() {
+        return this.client.request("GET", "/v1/feeds/openai/check");
+    }
+    /** Sell in ChatGPT: readiness steps, suggested answers for OpenAI's merchant application, and status. */
+    chatgpt() {
+        return this.client.request("GET", "/v1/channels/chatgpt");
+    }
+    /** Record the application's progress (after the owner submits it) or the product category to apply with. */
+    updateChatgpt(params) {
+        return this.client.request("PATCH", "/v1/channels/chatgpt", { body: params });
+    }
+    /** Everything between this store and real orders, each with the exact fix. Start here when setting up. */
+    setupStatus() {
+        return this.client.request("GET", "/v1/setup_status");
+    }
+    /**
+     * Test stores only: run a purchase end to end without a browser. Stock is reserved and committed, the
+     * order is created and paid, events and your webhooks fire; `fulfill: true` also marks it shipped.
+     * Never charges a card, reaches Printify/Printful, emails anyone, or counts toward usage.
+     */
+    simulateOrder(params) {
+        return this.client.request("POST", "/v1/simulate/order", { body: params });
+    }
+    /**
+     * A one-time link (valid 7 days) to hand to a person when the store is ready for real orders. Opening it
+     * signs them in, claims the store if it's an unclaimed sandbox, creates a live copy (products, prices,
+     * inventory, settings and connections), and takes them to Connect Stripe. Test stores only.
+     */
+    goLiveLink() {
+        return this.client.request("POST", "/v1/go_live_links", { body: {} });
+    }
+    /**
+     * Shipping every checkout offers unless it passes its own rates: up to 5 flat rates (cents), the
+     * countries you ship to, and an optional free-shipping threshold on the item subtotal (cents).
+     */
+    configureCheckoutShipping(params) {
+        return this.client.request("PUT", "/v1/store/checkout-shipping", { body: params });
+    }
+    /** Connect your EasyPost or Shippo account for label purchasing. */
+    configureShipping(params) {
+        return this.client.request("PUT", "/v1/store/shipping", { body: params });
+    }
+    /**
+     * Connect Printful or Printify (call once per provider; both can be connected — each variant routes to the
+     * provider it's mapped to). Paid orders with mapped variants are sent automatically — held for your
+     * approval in the provider's dashboard unless `auto_confirm: true`. Shipments mark orders fulfilled.
+     */
+    configureFulfillment(params) {
+        return this.client.request("PUT", "/v1/store/fulfillment", { body: params });
+    }
+    /**
+     * Import products from Shopify: pass Shopify's product export CSV (Products → Export) as `csv`, or
+     * `shop` (your-store.myshopify.com) + a custom app `access_token` (read_products, read_inventory).
+     * Safe to re-run: products match by Shopify id or SKU and existing prices and stock are kept.
+     */
+    importFromShopify(params) {
+        return this.client.request("POST", "/v1/import/shopify", { body: params });
+    }
+    /**
+     * Import the products already set up in a connected Printify shop or Printful store (both when omitted).
+     * Runs in the background and happens automatically on connect; safe to re-run. Progress: `store.get()` → fulfillment[].catalog_import.
+     */
+    importCatalog(params = {}) {
+        return this.client.request("POST", "/v1/catalog/import", { body: params });
+    }
+    /** Disconnect one provider, or all when omitted. */
+    disableFulfillment(provider) {
+        return this.client.request("DELETE", "/v1/store/fulfillment", { query: { provider } });
+    }
+    /** Send customer emails (confirmation, shipped, refunded, return approved) from your domain via Resend. */
+    configureEmails(params) {
+        return this.client.request("PUT", "/v1/store/emails", { body: params });
+    }
+    disableEmails() {
+        return this.client.request("DELETE", "/v1/store/emails");
+    }
+    /**
+     * Publish product feeds for AI shopping surfaces (OpenAI/ACP JSON, Google Merchant XML) and,
+     * with `agent_access: true`, a public API third-party shopping agents can use to create checkout links.
+     */
+    configureStorefront(params) {
+        return this.client.request("PUT", "/v1/store/storefront", { body: params });
+    }
+}
+class Webhooks extends Resource {
+    create(params) {
+        return this.client.request("POST", "/v1/webhook-endpoints", { body: params });
+    }
+    list() {
+        return this.client.request("GET", "/v1/webhook-endpoints");
+    }
+    remove(id) {
+        return this.client.request("DELETE", `/v1/webhook-endpoints/${encodeURIComponent(id)}`);
+    }
+    /** Verify a webhook we sent you. Throws if the signature is invalid or too old. */
+    verify(args) {
+        return verifyWebhook(args);
+    }
+}
+/**
+ * Verify a CommerceForAI webhook (Standard Webhooks format). Works in Node 18+, Bun, Deno and edge runtimes.
+ * Pass the raw request body string, not parsed JSON.
+ */
+export async function verifyWebhook({ payload, headers, secret, toleranceSeconds = 300, }) {
+    const get = (k) => headers instanceof Headers ? headers.get(k) ?? undefined : headers[k] ?? headers[k.toLowerCase()];
+    const msgId = get("webhook-id");
+    const ts = get("webhook-timestamp");
+    const sigHeader = get("webhook-signature");
+    if (!msgId || !ts || !sigHeader)
+        throw new Error("Missing webhook-id, webhook-timestamp or webhook-signature header");
+    const now = Math.floor(Date.now() / 1000);
+    if (!/^\d+$/.test(ts) || Math.abs(now - Number(ts)) > toleranceSeconds)
+        throw new Error("Webhook timestamp outside tolerance");
+    const keyBytes = base64ToBytes(secret.replace(/^whsec_/, ""));
+    const key = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${msgId}.${ts}.${payload}`)));
+    const expected = bytesToBase64(mac);
+    const ok = sigHeader.split(" ").some((part) => {
+        const [ver, sig] = part.split(",");
+        return ver === "v1" && sig !== undefined && timingSafeEqual(sig, expected);
+    });
+    if (!ok)
+        throw new Error("Invalid webhook signature");
+    return JSON.parse(payload);
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+function base64ToBytes(b64) {
+    const bin = atob(b64);
+    return Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
+}
+function bytesToBase64(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin);
+}
+export default Commerce;
+export { createCheckoutHandler } from "./checkout-handler.js";
+export * from "./cart-core.js";

package/dist/react.d.ts

@@ -0,0 +1,85 @@
+import * as React from "react";
+import { type CartLine, type CatalogProduct } from "./cart-core.js";
+export * from "./cart-core.js";
+type Listener = () => void;
+/** A tiny external store: one per storage key, shared by every hook on the page. */
+declare function createCartStore(key: string): {
+    get: () => CartLine[];
+    set(next: CartLine[]): void;
+    subscribe(l: Listener): () => void;
+};
+type CartStore = ReturnType<typeof createCartStore>;
+export interface CartProviderProps {
+    children?: React.ReactNode;
+    /** localStorage key (default "cfa_cart"). Use one per store if a site sells for several. */
+    storageKey?: string;
+    /** Your server route that creates the checkout (default "/api/checkout"). */
+    checkoutEndpoint?: string;
+}
+export declare function CartProvider({ children, storageKey, checkoutEndpoint }: CartProviderProps): React.FunctionComponentElement<React.ProviderProps<{
+    store: CartStore;
+    endpoint: string;
+} | null>>;
+export type CheckoutResult = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    error: {
+        type: string;
+        message: string;
+        variant_id?: string;
+        available?: number;
+    };
+};
+/**
+ * The cart. Pass the catalog (`products`) to get names, current prices, a subtotal and stock checks;
+ * without it you still get lines and a count.
+ */
+export declare function useCart(products?: CatalogProduct[]): {
+    /** Raw lines (ids + quantities). */
+    items: CartLine[];
+    /** Lines joined to the catalog (when `products` is passed). */
+    lines: import("./cart-core.js").ResolvedLine[];
+    missing: CartLine[];
+    count: number;
+    subtotal: number;
+    currency: string;
+    ready: boolean;
+    add: (variantId: string, quantity?: number, properties?: Record<string, string>) => void;
+    setQuantity: (index: number, quantity: number) => void;
+    remove: (index: number) => void;
+    clear: () => void;
+    fix: () => void;
+    checkout: (opts?: {
+        discount_code?: string;
+        redirect?: boolean;
+    }) => Promise<CheckoutResult>;
+    /** True while creating the checkout / redirecting. */
+    pending: boolean;
+    /** The last checkout error (e.g. out_of_stock with variant_id and available). */
+    error: {
+        type: string;
+        message: string;
+        variant_id?: string;
+        available?: number;
+    } | null;
+};
+/** Selected options → variant, with which choices are still buyable. */
+export declare function useVariantPicker(product: CatalogProduct, initial?: Record<string, string>): {
+    selected: Record<string, string>;
+    select: (name: string, value: string) => void;
+    options: {
+        name: string;
+        values: import("./cart-core.js").OptionChoice[];
+    }[];
+    variant: import("./cart-core.js").CatalogVariant | null;
+    inStock: boolean;
+    available: number | null;
+};
+/**
+ * Empty the cart after a successful payment. Call on your success page; it clears only when the URL
+ * has the `cfa_checkout` parameter that `createCheckoutHandler` adds to the success URL.
+ */
+export declare function useClearCartOnSuccess(param?: string): void;
+export declare const formatMoney: (cents: number, currency?: string, locale?: string) => string;