commerceforai 0.0.0-stage → 0.1.0

package/dist/react.js

@@ -0,0 +1,162 @@
+/**
+ * `commerceforai/react`: cart and variant-picker hooks that draw nothing, so they fit any design.
+ *
+ * ```tsx
+ * <CartProvider>…</CartProvider>                    // once, near the root (a client component)
+ * const cart = useCart(products);                     // lines, count, subtotal, add, setQuantity, checkout
+ * const picker = useVariantPicker(product);           // options, select, variant, inStock
+ * ```
+ *
+ * The cart lives in localStorage (synced across tabs). Checkout posts the lines to your own server
+ * endpoint (see `createCheckoutHandler` in `commerceforai`), which holds the API key and creates the
+ * Stripe checkout. Prices are never sent from the browser.
+ */
+"use client";
+import * as React from "react";
+import { addLine, initialSelection, parseLines, pickVariant, removeLine, resolveCart, setLineQuantity, } from "./cart-core.js";
+export * from "./cart-core.js";
+const EMPTY = [];
+/** A tiny external store: one per storage key, shared by every hook on the page. */
+function createCartStore(key) {
+    let lines = EMPTY;
+    let loaded = false;
+    const listeners = new Set();
+    const read = () => {
+        try {
+            return parseLines(JSON.parse(globalThis.localStorage?.getItem(key) ?? "[]"));
+        }
+        catch {
+            return EMPTY;
+        }
+    };
+    const load = () => { if (!loaded && typeof window !== "undefined") {
+        lines = read();
+        loaded = true;
+    } };
+    const emit = () => listeners.forEach((l) => l());
+    return {
+        get: () => { load(); return lines; },
+        set(next) {
+            load();
+            lines = next;
+            try {
+                globalThis.localStorage?.setItem(key, JSON.stringify(next));
+            }
+            catch { /* private mode: in-memory only */ }
+            emit();
+        },
+        subscribe(l) {
+            listeners.add(l);
+            const onStorage = (e) => { if (e.key === key) {
+                lines = read();
+                emit();
+            } };
+            if (typeof window !== "undefined")
+                window.addEventListener("storage", onStorage);
+            return () => { listeners.delete(l); if (typeof window !== "undefined")
+                window.removeEventListener("storage", onStorage); };
+        },
+    };
+}
+const stores = new Map();
+const storeFor = (key) => { let s = stores.get(key); if (!s) {
+    s = createCartStore(key);
+    stores.set(key, s);
+} return s; };
+const CartContext = React.createContext(null);
+export function CartProvider({ children, storageKey = "cfa_cart", checkoutEndpoint = "/api/checkout" }) {
+    const value = React.useMemo(() => ({ store: storeFor(storageKey), endpoint: checkoutEndpoint }), [storageKey, checkoutEndpoint]);
+    return React.createElement(CartContext.Provider, { value }, children);
+}
+/**
+ * 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 function useCart(products) {
+    const ctx = React.useContext(CartContext);
+    const store = ctx?.store ?? storeFor("cfa_cart");
+    const endpoint = ctx?.endpoint ?? "/api/checkout";
+    const lines = React.useSyncExternalStore(store.subscribe, store.get, () => EMPTY);
+    const [pending, setPending] = React.useState(false);
+    const [error, setError] = React.useState(null);
+    const resolved = React.useMemo(() => (products ? resolveCart(lines, products) : null), [lines, products]);
+    const add = React.useCallback((variantId, quantity = 1, properties) => store.set(addLine(store.get(), variantId, quantity, properties)), [store]);
+    const setQuantity = React.useCallback((index, quantity) => store.set(setLineQuantity(store.get(), index, quantity)), [store]);
+    const remove = React.useCallback((index) => store.set(removeLine(store.get(), index)), [store]);
+    const clear = React.useCallback(() => store.set([]), [store]);
+    /** Drop lines whose product is gone, and cap quantities at what's in stock. Needs `products`. */
+    const fix = React.useCallback(() => {
+        if (!products)
+            return;
+        const r = resolveCart(store.get(), products);
+        store.set(r.lines.map((l) => ({ variant_id: l.variant_id, quantity: l.available === null ? l.quantity : Math.min(l.quantity, l.available), ...(l.properties ? { properties: l.properties } : {}) })).filter((l) => l.quantity > 0));
+    }, [products, store]);
+    /** Create the checkout on your server and go to Stripe. Resolves with an error instead of throwing. */
+    const checkout = React.useCallback(async (opts = {}) => {
+        const items = store.get();
+        if (!items.length)
+            return { ok: false, error: { type: "invalid_request", message: "Your cart is empty." } };
+        setPending(true);
+        setError(null);
+        try {
+            const res = await fetch(endpoint, {
+                method: "POST", headers: { "content-type": "application/json" },
+                body: JSON.stringify({ items, ...(opts.discount_code ? { discount_code: opts.discount_code } : {}) }),
+            });
+            const body = await res.json().catch(() => null);
+            if (!res.ok || !body?.url) {
+                const err = body?.error ?? { type: "api_error", message: "Checkout isn't available right now. Please try again." };
+                setError(err);
+                setPending(false);
+                return { ok: false, error: err };
+            }
+            if (opts.redirect !== false)
+                window.location.assign(body.url);
+            else
+                setPending(false);
+            return { ok: true, url: body.url };
+        }
+        catch {
+            const err = { type: "network_error", message: "Couldn't reach checkout. Check your connection and try again." };
+            setError(err);
+            setPending(false);
+            return { ok: false, error: err };
+        }
+    }, [endpoint, store]);
+    return {
+        /** Raw lines (ids + quantities). */
+        items: lines,
+        /** Lines joined to the catalog (when `products` is passed). */
+        lines: resolved?.lines ?? [],
+        missing: resolved?.missing ?? [],
+        count: lines.reduce((n, l) => n + l.quantity, 0),
+        subtotal: resolved?.subtotal ?? 0,
+        currency: resolved?.currency ?? "usd",
+        ready: resolved ? resolved.ready : lines.length > 0,
+        add, setQuantity, remove, clear, fix, checkout,
+        /** True while creating the checkout / redirecting. */
+        pending,
+        /** The last checkout error (e.g. out_of_stock with variant_id and available). */
+        error,
+    };
+}
+/** Selected options → variant, with which choices are still buyable. */
+export function useVariantPicker(product, initial) {
+    const [selected, setSelected] = React.useState(() => initial ?? initialSelection(product));
+    React.useEffect(() => { setSelected(initial ?? initialSelection(product)); }, [product.id]); // eslint-disable-line react-hooks/exhaustive-deps
+    const picked = React.useMemo(() => pickVariant(product, selected), [product, selected]);
+    const select = React.useCallback((name, value) => setSelected((s) => ({ ...s, [name]: value })), []);
+    return { ...picked, selected, select };
+}
+/**
+ * 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 function useClearCartOnSuccess(param = "cfa_checkout") {
+    const { clear } = useCart();
+    React.useEffect(() => {
+        if (typeof window !== "undefined" && new URLSearchParams(window.location.search).has(param))
+            clear();
+    }, [clear, param]);
+}
+export const formatMoney = (cents, currency = "usd", locale = "en-US") => new Intl.NumberFormat(locale, { style: "currency", currency: currency.toUpperCase() }).format(cents / 100);

package/dist/types.d.ts

@@ -0,0 +1,530 @@
+/** All amounts are integers in the currency's minor unit (cents for USD). */
+export type Money = number;
+export interface Inventory {
+    tracked: boolean;
+    /** Units physically in stock (null when not tracked). */
+    on_hand: number | null;
+    /** Units held by open checkouts. */
+    reserved: number;
+    /** on_hand − reserved: what can be sold right now (null = unlimited). */
+    available: number | null;
+}
+export interface Variant {
+    object: "variant";
+    id: string;
+    product_id: string;
+    name: string;
+    sku: string | null;
+    options: Record<string, string>;
+    price: Money;
+    currency: string;
+    weight_oz: number | null;
+    /** Print-on-demand mapping (null = you ship it yourself). */
+    fulfillment: VariantFulfillment | null;
+    inventory: Inventory;
+    active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface Product {
+    object: "product";
+    id: string;
+    name: string;
+    description: string | null;
+    images: string[];
+    metadata: Record<string, string>;
+    active: boolean;
+    /** Default artwork for all variants (a variant's or checkout line's own print_files win). */
+    print_files: PrintFile[] | null;
+    variants: Variant[];
+    created_at: string;
+    updated_at: string;
+}
+export interface VariantInput {
+    name?: string;
+    sku?: string;
+    price: Money;
+    options?: Record<string, string>;
+    /** Units on hand. Omit or `null` for unlimited (not tracked). */
+    inventory?: number | null;
+    /** Shipping weight in ounces, used to price labels. */
+    weight_oz?: number;
+    /** Map to a Printful catalog variant to have paid orders printed and shipped by Printful. */
+    fulfillment?: VariantFulfillment;
+}
+export interface PrintFile {
+    /** Provider placement, e.g. "front", "back", or Printful "embroidery_chest_left". */
+    placement: string;
+    /** Public https URL of the artwork (PNG recommended). */
+    url: string;
+    /** Provider file options, e.g. Printful [{ id: "thread_colors", value: ["#FFFFFF"] }]. */
+    options?: {
+        id: string;
+        value: unknown;
+    }[];
+}
+/** Print-on-demand mapping: set exactly one of `printful_variant_id`, `printful_sync_variant_id` or `printify`. */
+export interface VariantFulfillment {
+    /** Printful catalog variant id (product + color + size), e.g. 4012. */
+    printful_variant_id?: number;
+    /** A product already set up in your Printful store (sync variant id): no print files needed. */
+    printful_sync_variant_id?: number;
+    /** Printful item options, e.g. [{ id: "thread_colors_chest_left", value: ["#000000"] }] for embroidery. */
+    printful_options?: {
+        id: string;
+        value: unknown;
+    }[];
+    /**
+     * Printify: for per-order artwork give catalog `blueprint_id` + `print_provider_id` + `variant_id`;
+     * to print an existing Printify product give `product_id` + `variant_id`.
+     */
+    printify?: {
+        variant_id: number;
+        blueprint_id?: number;
+        print_provider_id?: number;
+        product_id?: string;
+    };
+    /** Default artwork; a checkout line's own print_files override it. */
+    print_files?: PrintFile[];
+}
+export type ProductCreateParams = {
+    name: string;
+    /** Default artwork for every variant — artwork is usually per design, not per size. */
+    print_files?: PrintFile[];
+    description?: string;
+    images?: string[];
+    metadata?: Record<string, string>;
+} & ({
+    variants: VariantInput[];
+    price?: never;
+    inventory?: never;
+    sku?: never;
+} | {
+    price: Money;
+    inventory?: number | null;
+    sku?: string;
+    weight_oz?: number;
+    variants?: never;
+});
+export interface ProductUpdateParams {
+    name?: string;
+    print_files?: PrintFile[] | null;
+    description?: string | null;
+    images?: string[];
+    metadata?: Record<string, string>;
+    active?: boolean;
+}
+export interface VariantUpdateParams {
+    name?: string;
+    sku?: string | null;
+    price?: Money;
+    options?: Record<string, string>;
+    active?: boolean;
+    weight_oz?: number | null;
+    fulfillment?: VariantFulfillment | null;
+}
+export interface CheckoutItem {
+    variant_id: string;
+    product_id: string;
+    product_name: string;
+    variant_name: string;
+    sku: string | null;
+    quantity: number;
+    unit_price: Money;
+    properties?: Record<string, string>;
+    print_files?: PrintFile[];
+}
+export interface Checkout {
+    object: "checkout";
+    id: string;
+    status: "pending" | "open" | "completed" | "expired" | "failed";
+    /** Stripe-hosted payment page. Redirect the customer here. */
+    url: string | null;
+    items: CheckoutItem[];
+    currency: string;
+    customer_email: string | null;
+    metadata: Record<string, string>;
+    order_id: string | null;
+    expires_at: string;
+    created_at: string;
+}
+export interface CheckoutLine {
+    variant_id: string;
+    quantity: number;
+    /** Custom data for this line, e.g. { parks: "Zion, Arches", name: "Riley" }. Up to 20 keys × 500 chars. Shown on Stripe's page. */
+    properties?: Record<string, string>;
+    /** Per-order artwork for print-on-demand (https URLs). */
+    print_files?: PrintFile[];
+}
+export interface CheckoutCreateParams {
+    items: CheckoutLine[];
+    /** Where Stripe sends the customer after paying. Supports `{CHECKOUT_SESSION_ID}`. */
+    success_url?: string;
+    cancel_url?: string;
+    customer_email?: string;
+    /** Default true. */
+    collect_shipping_address?: boolean;
+    /** ISO country codes. Default ["US"]. */
+    shipping_countries?: string[];
+    shipping_rates?: {
+        name: string;
+        amount: Money;
+        min_days?: number;
+        max_days?: number;
+    }[];
+    /** How long stock is held, 30–1440. Default 30. */
+    expires_in_minutes?: number;
+    metadata?: Record<string, string>;
+    /** Apply a discount code up front. Without it, shoppers can enter any live code on Stripe's page. */
+    discount_code?: string;
+}
+export type OrderStatus = "pending_payment" | "paid" | "fulfilled" | "cancelled" | "refunded";
+export interface Address {
+    name?: string | null;
+    line1?: string | null;
+    line2?: string | null;
+    city?: string | null;
+    state?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+}
+export interface Order {
+    object: "order";
+    id: string;
+    /** Human-friendly, per-store sequential number (e.g. 1001). */
+    number: number;
+    status: OrderStatus;
+    email: string | null;
+    customer_name: string | null;
+    shipping_address: Address | null;
+    items: CheckoutItem[];
+    currency: string;
+    subtotal: Money;
+    shipping: Money;
+    tax: Money;
+    total: Money;
+    /** Taken off by a discount code. */
+    discount: Money;
+    discount_code: string | null;
+    refunded: Money;
+    fulfillment: {
+        carrier: string | null;
+        tracking_number: string | null;
+        tracking_url: string | null;
+        fulfilled_at: string;
+        /** Present when the order shipped in several packages (e.g. Printful + Printify). */
+        shipments?: {
+            provider?: string;
+            carrier: string;
+            tracking_number: string;
+            tracking_url: string | null;
+        }[];
+    } | null;
+    /** One entry per print-on-demand provider this order was routed to. */
+    fulfillment_provider_orders: {
+        provider: "printful" | "printify";
+        id?: string;
+        status: string;
+        dashboard_url?: string | null;
+        error?: string;
+        shipments?: {
+            carrier: string;
+            tracking_number: string;
+            tracking_url: string | null;
+        }[];
+    }[];
+    note: string | null;
+    metadata: Record<string, string>;
+    checkout_id: string;
+    stripe_payment_intent_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Store {
+    object: "store";
+    id: string;
+    name: string;
+    currency: string;
+    mode: "test" | "live";
+    tax_enabled: boolean;
+    default_success_url: string | null;
+    default_cancel_url: string | null;
+    stripe_webhook_url: string | null;
+    stripe_webhook_configured: boolean;
+    shipping: {
+        provider: "easypost" | "shippo";
+        ship_from: Address;
+        default_parcel: Dimensions | null;
+    } | null;
+    emails: {
+        provider: "resend";
+        from: string;
+        reply_to: string | null;
+        events: string[] | null;
+    } | null;
+    storefront: StorefrontConfig | null;
+    agent_access: boolean;
+    /** Shipping every checkout offers unless it passes its own rates. */
+    checkout_shipping: {
+        countries: string[];
+        rates: {
+            name: string;
+            amount: Money;
+            min_days?: number;
+            max_days?: number;
+        }[];
+        free_over: Money | null;
+    } | null;
+    /** Connected print-on-demand providers; each variant routes to the one it's mapped to. */
+    fulfillment: {
+        provider: "printful" | "printify";
+        auto_confirm: boolean;
+        printful_store_id?: string | null;
+        printify_shop_id?: string | null;
+    }[];
+    feeds: {
+        acp: string;
+        google: string;
+        agent: string | null;
+    } | null;
+}
+export interface Dimensions {
+    length: number;
+    width: number;
+    height: number;
+}
+export interface Parcel extends Partial<Dimensions> {
+    weight_oz?: number;
+}
+export interface ShipFromAddress {
+    name?: string;
+    company?: string;
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postal_code: string;
+    country: string;
+    phone?: string;
+    email?: string;
+}
+export interface StorefrontConfig {
+    /** Your product page URL with `{handle}` or `{id}`, e.g. "https://acme.com/products/{handle}". */
+    product_url_template: string;
+    brand?: string;
+    seller_url?: string;
+    privacy_policy_url?: string;
+    terms_url?: string;
+    return_policy_url?: string;
+    return_window_days?: number;
+}
+export interface ShippingRate {
+    object: "shipping_rate";
+    id: string;
+    carrier: string;
+    service: string;
+    amount: Money;
+    currency: string;
+    est_days: number | null;
+    return_id: string | null;
+}
+export interface Label {
+    object: "label";
+    id: string;
+    order_id: string;
+    return_id: string | null;
+    provider: "easypost" | "shippo";
+    carrier: string;
+    service: string;
+    cost: Money;
+    currency: string;
+    tracking_number: string | null;
+    tracking_url: string | null;
+    /** PDF/PNG to print. */
+    label_url: string;
+    created_at: string;
+}
+export interface Return {
+    object: "return";
+    id: string;
+    /** Per-store sequential number, shown to customers as R1, R2, ... */
+    number: number;
+    status: "requested" | "approved" | "rejected" | "completed";
+    order_id: string;
+    order_number: number | null;
+    email: string | null;
+    currency: string | null;
+    items: {
+        variant_id: string;
+        product_name: string;
+        variant_name: string;
+        quantity: number;
+        unit_price: Money;
+    }[];
+    reason: string | null;
+    note: string | null;
+    refund_amount: Money | null;
+    restocked: boolean;
+    label: Label | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Email {
+    object: "email";
+    id: string;
+    order_id: string | null;
+    template: "order_confirmation" | "order_shipped" | "order_refunded" | "return_approved";
+    to: string;
+    subject: string;
+    status: "pending" | "sent" | "failed";
+    attempts: number;
+    last_error: string | null;
+    created_at: string;
+}
+export type EventType = "order.created" | "order.paid" | "order.fulfilled" | "order.updated" | "order.cancelled" | "order.refunded" | "checkout.expired" | "checkout.abandoned" | "label.created" | "order.shipment_created" | "fulfillment.submitted" | "fulfillment.failed" | "fulfillment.canceled" | "fulfillment.on_hold" | "return.requested" | "return.approved" | "return.rejected" | "return.completed" | "inventory.updated" | "product.created" | "product.updated";
+export interface Event<T = unknown> {
+    id: string;
+    object: "event";
+    type: EventType;
+    created_at: string;
+    data: T;
+}
+export interface WebhookEndpoint {
+    object: "webhook_endpoint";
+    id: string;
+    url: string;
+    events: string[];
+    /** Only returned when the endpoint is created. */
+    secret?: string;
+    created_at?: string;
+}
+export interface List<T> {
+    object: "list";
+    data: T[];
+    has_more: boolean;
+}
+export interface ErrorResponse {
+    type: "invalid_request" | "authentication_error" | "not_found" | "conflict" | "out_of_stock" | "stripe_error" | "idempotency_error" | "internal_error" | "network_error";
+    message: string;
+    param?: string;
+    [k: string]: unknown;
+}
+export type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: ErrorResponse;
+};
+export interface Collection {
+    object: "collection";
+    id: string;
+    name: string;
+    /** URL-safe, unique per store. Use it anywhere an id is accepted. */
+    handle: string;
+    description: string | null;
+    image: string | null;
+    position: number;
+    product_count: number;
+    /** In display order. */
+    product_ids: string[];
+    created_at: string;
+    updated_at: string;
+}
+export interface CollectionParams {
+    name?: string;
+    handle?: string;
+    description?: string | null;
+    image?: string | null;
+    position?: number;
+    product_ids?: string[];
+}
+export interface Customer {
+    object: "customer";
+    email: string;
+    name: string | null;
+    /** Paid orders (simulated ones never count). */
+    orders: number;
+    /** After refunds. */
+    total_spent: Money;
+    currency: string;
+    first_order_at: string;
+    last_order_at: string;
+}
+export interface CustomerDetail extends Customer {
+    last_shipping_address: Address | null;
+    order_history: Order[];
+}
+export interface SalesReport {
+    object: "sales_report";
+    days: number;
+    interval: "day" | "week" | "month";
+    currency: string;
+    totals: {
+        orders: number;
+        gross: Money;
+        net: Money;
+        refunds: Money;
+        discounts: Money;
+        average_order: Money;
+        customers: number;
+        returning_customers: number;
+    };
+    previous: {
+        orders: number;
+        gross: Money;
+        net: Money;
+        refunds: Money;
+        discounts: Money;
+        change_pct: {
+            orders: number | null;
+            gross: number | null;
+            net: number | null;
+        };
+    };
+    series: {
+        period: string;
+        orders: number;
+        gross: Money;
+        discounts: Money;
+        shipping: Money;
+        tax: Money;
+        refunds: Money;
+        net: Money;
+    }[];
+    top_products: {
+        product_id: string;
+        name: string;
+        units: number;
+        revenue: Money;
+    }[];
+}
+export interface Discount {
+    object: "discount";
+    id: string;
+    /** Uppercase; what shoppers type. */
+    code: string;
+    kind: "percent" | "amount";
+    /** 1–100 for percent; cents for amount. */
+    value: number;
+    currency: string;
+    description: string;
+    min_subtotal: Money | null;
+    max_redemptions: number | null;
+    times_used: number;
+    starts_at: string | null;
+    ends_at: string | null;
+    active: boolean;
+    status: "live" | "scheduled" | "expired" | "used_up" | "off";
+    created_at: string;
+}
+export interface DiscountParams {
+    code: string;
+    kind: "percent" | "amount";
+    value: number;
+    min_subtotal?: Money | null;
+    max_redemptions?: number | null;
+    starts_at?: string | null;
+    ends_at?: string | null;
+    active?: boolean;
+}

package/dist/types.js

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