@spindlecommerce/storefront-client 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,455 @@
+/** What the Storefront API returns, as this package's documents select it. */
+export type Money = {
+    amount: string;
+    currencyCode: string;
+    formatted: string;
+};
+export type PriceRange = {
+    minVariantPrice: Money | null;
+    maxVariantPrice: Money | null;
+    compareAtMinVariantPrice: Money | null;
+};
+export type ProductOptionValue = {
+    code: string;
+    label: string;
+    swatch: string | null;
+};
+export type ProductOption = {
+    attribute: {
+        code: string;
+        label: string | null;
+    };
+    values: ProductOptionValue[];
+};
+/** A variant as cards need it: what to add, and whether it can be bought. */
+export type VariantSummary = {
+    id: string;
+    isAvailable: boolean;
+    selectedOptions: {
+        attribute: string;
+        value: string;
+    }[];
+};
+/** What product cards and grids show. */
+export type ProductSummary = {
+    id: string;
+    name: string;
+    slug: string;
+    isAvailable: boolean;
+    priceRange: PriceRange | null;
+    /** In position order. A photo of one variant names it. */
+    media: {
+        url: string;
+        alt: string | null;
+        kind: "IMAGE" | "VIDEO";
+        variant: {
+            id: string;
+        } | null;
+    }[];
+    options: ProductOption[];
+    variants: VariantSummary[];
+};
+export type SelectedOption = {
+    attribute: string;
+    value: string;
+    label: string;
+    name: string;
+    swatch: string | null;
+};
+export type ProductVariant = {
+    id: string;
+    sku: string;
+    name: string;
+    isAvailable: boolean;
+    quantityAvailable: number | null;
+    price: Money | null;
+    compareAtPrice: Money | null;
+    selectedOptions: SelectedOption[];
+    media: {
+        url: string;
+        alt: string | null;
+    }[];
+};
+export type CategoryLink = {
+    id: string;
+    name: string;
+    path: string;
+};
+export type Product = Omit<ProductSummary, "media" | "variants"> & {
+    description: string | null;
+    seo: {
+        title: string | null;
+        description: string | null;
+    } | null;
+    categories: CategoryLink[];
+    variants: ProductVariant[];
+    media: {
+        id: string;
+        url: string;
+        alt: string | null;
+        kind: "IMAGE" | "VIDEO";
+        position: number;
+        variant: {
+            id: string;
+        } | null;
+    }[];
+    attributes: {
+        attribute: {
+            code: string;
+            label: string;
+        };
+        value: string | null;
+    }[];
+};
+export type Category = CategoryLink & {
+    slug: string;
+    description: string | null;
+    ancestors: CategoryLink[];
+    children: CategoryLink[];
+};
+export type Connection<N> = {
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+    edges: {
+        node: N | null;
+    }[];
+};
+export type ProductConnection = Connection<ProductSummary> & {
+    totalCount: number;
+};
+export type ProductSort = {
+    field: "NEWEST" | "PRICE" | "NAME";
+    direction: "ASC" | "DESC";
+};
+export type CategoryTreeNode = {
+    path: string;
+    children?: CategoryTreeNode[];
+};
+export type PageLink = {
+    id: string;
+    path: string | null;
+    title: string | null;
+};
+export type PageEntry = {
+    path: string | null;
+    updatedAt: string | null;
+    seo: {
+        noIndex: boolean;
+    } | null;
+};
+export type PageImage = {
+    url: string;
+    alt: string | null;
+    width: number | null;
+    height: number | null;
+};
+/** A component instance as the API delivers it. */
+export type ContentNode = {
+    id: string;
+    component: string;
+    variation: string | null;
+    fields: Record<string, unknown>;
+};
+/** A component tree in the request locale, and what it refers to. */
+export type BuilderPage<Root extends {
+    id: string;
+    component: string;
+} = ContentNode> = {
+    id: string;
+    type: string;
+    path: string | null;
+    title: string | null;
+    isPreview: boolean;
+    publishedAt: string | null;
+    /** Changes with every draft save (in preview) or publish. */
+    updatedAt: string;
+    seo: {
+        title: string | null;
+        description: string | null;
+        noIndex: boolean;
+        image: PageImage | null;
+    };
+    content: Root;
+    references: {
+        products: ProductSummary[];
+        categories: CategoryLink[];
+        pages: PageLink[];
+    };
+};
+export type TemplateKind = "product" | "category";
+/**
+ * A pathless builder page that product or category pages render with. The product or category
+ * supplies its components' data.
+ */
+export type TemplatePage = BuilderPage & {
+    templateFor: "PRODUCT" | "CATEGORY";
+};
+/** A null template renders the storefront's built-in layout. The template places the sections. */
+export type WithTemplate = {
+    template: TemplatePage | null;
+    sections: BuilderPage | null;
+};
+export type Redirect = {
+    location: string;
+    statusCode: number;
+};
+export type RouteResult = ({
+    __typename: "Page";
+} & BuilderPage) | ({
+    __typename: "Product";
+} & Product & WithTemplate) | ({
+    __typename: "Category";
+} & Category & WithTemplate) | ({
+    __typename: "Redirect";
+} & Redirect);
+/** route() without a product's or category's template and sections, which load separately. */
+export type RouteData = Exclude<RouteResult, {
+    __typename: "Product" | "Category";
+}> | ({
+    __typename: "Product";
+} & Product) | ({
+    __typename: "Category";
+} & Category);
+export type Localization = {
+    locale: string;
+    currencyCode: string;
+    channel: {
+        code: string;
+        name: string;
+    };
+};
+export type SiteData<Header extends {
+    id: string;
+    component: string;
+} = ContentNode, Footer extends {
+    id: string;
+    component: string;
+} = ContentNode> = {
+    header: BuilderPage<Header> | null;
+    footer: BuilderPage<Footer> | null;
+    localization: Localization | null;
+};
+export type PreviewSession = {
+    expiresAt: string;
+    adminOrigin: string | null;
+    at: string | null;
+};
+export type CartLine = {
+    id: string;
+    name: string;
+    quantity: number;
+    quantityAvailable: number | null;
+    unitPrice: Money | null;
+    compareAtUnitPrice: Money | null;
+    total: Money | null;
+    issue: {
+        code: string;
+        message: string;
+    } | null;
+    product: {
+        name: string;
+        slug: string;
+        media: {
+            url: string;
+            alt: string | null;
+            kind: string;
+        }[];
+    } | null;
+    variant: {
+        id: string;
+        name: string;
+        selectedOptions: {
+            name: string;
+            label: string;
+        }[];
+        media: {
+            url: string;
+            alt: string | null;
+        }[];
+    } | null;
+};
+export type Cart = {
+    id: string;
+    isOpen: boolean;
+    totalQuantity: number;
+    currencyCode: string;
+    cost: {
+        subtotal: Money | null;
+        total: Money | null;
+        tax: Money | null;
+        shipping: Money | null;
+        discountTotal: Money | null;
+        pricesIncludeTax: boolean;
+    } | null;
+    lines: CartLine[];
+};
+export type Address = {
+    firstName: string | null;
+    lastName: string | null;
+    company: string | null;
+    line1: string | null;
+    line2: string | null;
+    city: string | null;
+    region: string | null;
+    regionCode: string | null;
+    postalCode: string | null;
+    countryCode: string | null;
+    phone: string | null;
+};
+/** An address as cartUpdate takes it. Incomplete addresses are saved as drafts. */
+export type AddressInput = {
+    [Field in Exclude<keyof Address, "countryCode">]?: string | null;
+} & {
+    countryCode: string;
+};
+/** cartUpdate's input. Fields left out stay as they are. */
+export type CartUpdateInput = {
+    email?: string;
+    locale?: string;
+    currencyCode?: string;
+    shippingAddress?: {
+        address: AddressInput;
+    };
+    billingAddress?: {
+        sameAsShipping: true;
+    } | {
+        address: AddressInput;
+    };
+    /** Null goes back to the cheapest rate. */
+    shippingMethodCode?: string | null;
+    paymentMethodCode?: string;
+};
+/** What a cart still needs before it can become an order (Cart.missing). */
+export type CartRequirement = "EMAIL" | "LINES" | "LINE_ISSUES" | "SHIPPING_ADDRESS" | "SHIPPING_METHOD" | "BILLING_ADDRESS" | "PAYMENT_METHOD";
+export type ShippingRate = {
+    code: string;
+    name: string;
+    description: string | null;
+    price: Money | null;
+    minDeliveryDays: number | null;
+    maxDeliveryDays: number | null;
+};
+/**
+ * `provider`: offline, test_gateway, stripe, … `sessionRequired`: needs a payment session before
+ * the order is placed. An older API gives null and false.
+ */
+export type PaymentMethod = {
+    code: string;
+    name: string;
+    instructions: string | null;
+    provider: string | null;
+    sessionRequired: boolean;
+};
+export type Country = {
+    code: string;
+    name: string;
+};
+export type Discount = {
+    name: string;
+    couponCode: string | null;
+    amount: Money | null;
+};
+/** `subtotal`: quantity × unit price, before discounts and any tax added on top. */
+export type CheckoutLine = CartLine & {
+    subtotal: Money | null;
+};
+export type CheckoutCart = {
+    id: string;
+    /** Increments on every change to the cart. */
+    version: number;
+    email: string | null;
+    requiresShipping: boolean;
+    missing: CartRequirement[];
+    /** As far as the shopper filled them in. */
+    shippingAddress: Address | null;
+    /** The cart's own, or else the shipping address. */
+    billingAddress: Address | null;
+    billingSameAsShipping: boolean;
+    shippingMethods: ShippingRate[];
+    /** Before shipping discounts (see `discounts`). The cheapest until the shopper chooses. */
+    selectedShipping: {
+        code: string;
+        name: string;
+        price: Money | null;
+    } | null;
+    paymentMethods: PaymentMethod[];
+    selectedPayment: PaymentMethod | null;
+    coupons: {
+        code: string;
+        applied: boolean;
+        reason: string | null;
+    }[];
+    discounts: Discount[];
+    cost: {
+        subtotal: Money | null;
+        total: Money | null;
+        tax: Money | null;
+        pricesIncludeTax: boolean;
+    } | null;
+    lines: CheckoutLine[];
+};
+/** `path` runs from the argument root, e.g. ["input", "shippingAddress", "address", "postalCode"]. */
+export type FieldError = {
+    path: string[];
+    message: string;
+};
+/** What guestOrder needs to look the order up: its number, email and billing postal code. */
+export type PlacedOrderRef = {
+    number: string;
+    email: string;
+    billingAddress: {
+        postalCode: string | null;
+    } | null;
+};
+export type PlacedOrder = {
+    number: string;
+    email: string;
+    locale: string | null;
+    status: "OPEN" | "COMPLETED" | "CANCELED";
+    paymentStatus: "PENDING" | "AUTHORIZED" | "PAID" | "PARTIALLY_PAID" | "REFUNDED" | "PARTIALLY_REFUNDED" | "VOIDED" | null;
+    placedAt: string | null;
+    currencyCode: string;
+    lines: {
+        id: string;
+        name: string;
+        sku: string;
+        quantity: number;
+        unitPrice: Money | null;
+        subtotal: Money | null;
+        total: Money | null;
+        product: {
+            name: string;
+            slug: string;
+            media: {
+                url: string;
+                alt: string | null;
+                kind: string;
+            }[];
+        } | null;
+        variant: {
+            selectedOptions: {
+                name: string;
+                label: string;
+            }[];
+            media: {
+                url: string;
+                alt: string | null;
+            }[];
+        } | null;
+    }[];
+    totals: {
+        subtotal: Money | null;
+        shipping: Money | null;
+        tax: Money | null;
+        total: Money | null;
+        pricesIncludeTax: boolean;
+        discounts: Discount[] | null;
+    } | null;
+    shippingAddress: Address | null;
+    billingAddress: Address | null;
+    shippingMethod: {
+        name: string;
+    } | null;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+/** What the Storefront API returns, as this package's documents select it. */
+export {};

package/dist/variants.d.ts

@@ -0,0 +1,29 @@
+import type { ProductOption, VariantSummary } from "./types.ts";
+/** Option values by attribute code, e.g. { color: "blue", size: "m" }. */
+export type Selection = Record<string, string>;
+type WithOptions = Pick<VariantSummary, "selectedOptions">;
+type Stocked = WithOptions & Pick<VariantSummary, "isAvailable">;
+export declare const selectionOf: (variant: WithOptions | undefined) => Selection;
+/** The selection names every option of the variant. */
+export declare const matches: (variant: WithOptions, selection: Selection) => boolean;
+/** The variant has the selection's values, and maybe other options. */
+export declare const hasValues: (variant: WithOptions, selection: Selection) => boolean;
+export declare const variantFor: <V extends WithOptions>(variants: V[], selection: Selection) => V | undefined;
+/**
+ * Choosing `value` keeps the other choices when that combination exists; otherwise it moves to one
+ * that does, in stock if there is one.
+ */
+export declare const chooseValue: <V extends Stocked>(variants: V[], selection: Selection, attribute: string, value: string) => {
+    selection: Selection;
+    variant: V | undefined;
+};
+/** Whether choosing `value`, keeping the other choices, gives a variant in stock. */
+export declare const inStock: (variants: Stocked[], selection: Selection, attribute: string, value: string) => boolean;
+/** The attribute's value on the first variant in stock, else on the first variant. */
+export declare const firstValue: (variants: Stocked[], attribute: string) => string | null;
+/** The option's values some variant has along with the selection, each with that variant. */
+export declare const valuesWith: <V extends WithOptions>(variants: V[], option: ProductOption, selection: Selection) => {
+    value: import("./types.ts").ProductOptionValue;
+    variant: V;
+}[];
+export {};

package/dist/variants.js

@@ -0,0 +1,26 @@
+export const selectionOf = (variant) => Object.fromEntries((variant?.selectedOptions ?? []).map((o) => [o.attribute, o.value]));
+/** The selection names every option of the variant. */
+export const matches = (variant, selection) => variant.selectedOptions.every((o) => selection[o.attribute] === o.value);
+/** The variant has the selection's values, and maybe other options. */
+export const hasValues = (variant, selection) => Object.entries(selection).every(([attribute, value]) => variant.selectedOptions.some((o) => o.attribute === attribute && o.value === value));
+export const variantFor = (variants, selection) => variants.find((v) => matches(v, selection));
+/**
+ * Choosing `value` keeps the other choices when that combination exists; otherwise it moves to one
+ * that does, in stock if there is one.
+ */
+export const chooseValue = (variants, selection, attribute, value) => {
+    const wanted = { ...selection, [attribute]: value };
+    const variant = variants.find((v) => matches(v, wanted)) ??
+        variants.find((v) => v.isAvailable && hasValues(v, { [attribute]: value })) ??
+        variants.find((v) => hasValues(v, { [attribute]: value }));
+    return { selection: variant ? selectionOf(variant) : wanted, variant };
+};
+/** Whether choosing `value`, keeping the other choices, gives a variant in stock. */
+export const inStock = (variants, selection, attribute, value) => variants.some((v) => v.isAvailable && matches(v, { ...selection, [attribute]: value }));
+/** The attribute's value on the first variant in stock, else on the first variant. */
+export const firstValue = (variants, attribute) => selectionOf(variants.find((v) => v.isAvailable) ?? variants[0])[attribute] ?? null;
+/** The option's values some variant has along with the selection, each with that variant. */
+export const valuesWith = (variants, option, selection) => option.values.flatMap((value) => {
+    const variant = variantFor(variants, { ...selection, [option.attribute.code]: value.code });
+    return variant ? [{ value, variant }] : [];
+});

package/dist/visual-editing.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Markup for the visual editing bridge (see the header of the API's /visual-editing/bridge.js).
+ * Outside draft mode every helper returns no attributes.
+ *
+ *   data-ecom-document   around each document: the page, the header, the footer
+ *   data-ecom-node       on a component's root element (with data-ecom-component)
+ *   data-ecom-field      on an element showing a field: "<nodeId>.<field>", or for a list item
+ *                        "<nodeId>.<field>.<itemId>[.<subField>]"
+ *   data-ecom-patch      "text" when the element shows the field's text as is, so the bridge can
+ *                        update it as the editor types
+ */
+export type EditAttributes = {
+    [attribute: `data-ecom-${string}`]: string;
+};
+export type Editable = {
+    draft: boolean;
+    document: (id: string) => EditAttributes;
+    node: (node: {
+        id: string;
+        component: string;
+    }) => EditAttributes;
+    field: (nodeId: string, ...path: string[]) => EditAttributes;
+    /** A field whose element shows exactly the field's text. */
+    text: (nodeId: string, ...path: string[]) => EditAttributes;
+};
+export declare const editable: (draft: boolean) => Editable;
+/** The bridge, protocol version 1. */
+export type VisualEditingBridge = {
+    version: number;
+    readonly connected: boolean;
+    init(options: {
+        adminOrigin: string;
+        onRefresh?: () => void | Promise<void>;
+        onPatch?: (patch: {
+            nodeId: string;
+            path: string[];
+            value: unknown;
+        }) => void;
+        navigate?: (path: string) => void;
+    }): VisualEditingBridge;
+    /** Tells the editor a refresh has rendered. */
+    rendered(): void;
+};
+/** Where the platform serves the bridge's script. */
+export declare const visualEditingBridgeUrl: (apiUrl: string) => string;
+/** The bridge, once its script has run in this window. */
+export declare const visualEditingBridge: () => VisualEditingBridge | undefined;

package/dist/visual-editing.js

@@ -0,0 +1,23 @@
+/**
+ * Markup for the visual editing bridge (see the header of the API's /visual-editing/bridge.js).
+ * Outside draft mode every helper returns no attributes.
+ *
+ *   data-ecom-document   around each document: the page, the header, the footer
+ *   data-ecom-node       on a component's root element (with data-ecom-component)
+ *   data-ecom-field      on an element showing a field: "<nodeId>.<field>", or for a list item
+ *                        "<nodeId>.<field>.<itemId>[.<subField>]"
+ *   data-ecom-patch      "text" when the element shows the field's text as is, so the bridge can
+ *                        update it as the editor types
+ */
+const NONE = {};
+export const editable = (draft) => ({
+    draft,
+    document: (id) => (draft ? { "data-ecom-document": id } : NONE),
+    node: (node) => (draft ? { "data-ecom-node": node.id, "data-ecom-component": node.component } : NONE),
+    field: (nodeId, ...path) => (draft ? { "data-ecom-field": [nodeId, ...path].join(".") } : NONE),
+    text: (nodeId, ...path) => (draft ? { "data-ecom-field": [nodeId, ...path].join("."), "data-ecom-patch": "text" } : NONE),
+});
+/** Where the platform serves the bridge's script. */
+export const visualEditingBridgeUrl = (apiUrl) => `${apiUrl.replace(/\/+$/, "")}/visual-editing/bridge.js`;
+/** The bridge, once its script has run in this window. */
+export const visualEditingBridge = () => globalThis.EcomVisualEditing;

package/dist/webhooks.d.ts

@@ -0,0 +1,52 @@
+import type { TemplateKind } from "./types.ts";
+/**
+ * Platform webhooks: `{ id, type, occurredAt, data }`, signed with
+ * `x-spindle-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">`.
+ */
+export type WebhookEvent = {
+    id: string;
+    type: string;
+    occurredAt: string;
+    data: {
+        aggregateType?: string;
+        aggregateId?: string;
+        type?: unknown;
+        path?: unknown;
+        previousPath?: unknown;
+        templateFor?: unknown;
+        sectionsFor?: unknown;
+        [key: string]: unknown;
+    };
+};
+/** Older or newer signatures are refused, so a captured request cannot be replayed. */
+export declare const SIGNATURE_TOLERANCE_SECONDS: number;
+/** Checks the signature over the exact text received. Verify before parsing. */
+export declare const verifyWebhookSignature: (secret: string, body: string, header: string | null, nowSeconds?: number) => Promise<boolean>;
+/** A verified body as an event; null when it is not one. */
+export declare const parseWebhookEvent: (body: string) => WebhookEvent | null;
+/** Content an event changed, for a storefront to expire what shows it. */
+export type ContentChange = {
+    kind: "everything";
+} | {
+    kind: "pages";
+} | {
+    kind: "catalog";
+} | {
+    kind: "path";
+    path: string;
+} | {
+    kind: "templates";
+    for: TemplateKind;
+} | {
+    kind: "sections";
+    for: TemplateKind;
+} | {
+    kind: "singleton";
+    type: string;
+};
+/** `immediate`: expire now (the next visit waits for fresh data) rather than serve stale while refetching. */
+export type ContentChanges = {
+    changes: ContentChange[];
+    immediate: boolean;
+};
+export declare const changesFor: (event: WebhookEvent) => ContentChanges;