@nymbalhq/sdk 1.4.0 → 1.6.0

package/dist/core-BviXjOsX.d.ts

@@ -0,0 +1,560 @@
+import { Address, Order, VariantOption, ProductRating, CartItem, Facet, ProductSortKey, PaymentIntent, OrderStatus, CheckoutPayment, Customer, StoreCapabilities, ShopperOrder, Cart, CustomerAddress, PublicReviewsResult, ReviewResult, AlertKind } from '@nymbalhq/types';
+
+interface DenormalisedVariant {
+    id: string;
+    sku: string;
+    name: string;
+    priceMinor: number;
+    stock: number;
+    options: VariantOption[];
+}
+interface DenormalisedProduct {
+    id: string;
+    slug: string;
+    name: string;
+    description: string;
+    shortDescription: string;
+    status: string;
+    type: string;
+    media: unknown;
+    variantCount: number;
+    inStock: boolean;
+    priceRange: {
+        minMinor: number;
+        maxMinor: number;
+    } | null;
+    currency: string | null;
+    priceMinor: number | null;
+    variants: DenormalisedVariant[];
+    categoryIds: string[];
+    categories: Array<{
+        id: string;
+        name: string;
+        slug: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+    /** Served by the product routes, not stored: null when the product has no approved review. */
+    rating?: ProductRating | null;
+}
+interface CartState {
+    items: CartItem[];
+    subtotalMinor: number;
+    currency: string;
+    itemCount: number;
+    loading: boolean;
+    error: string | null;
+}
+interface ProductState {
+    product: DenormalisedProduct | null;
+    selectedVariant: DenormalisedVariant | null;
+    loading: boolean;
+    error: string | null;
+}
+interface ProductListState {
+    products: DenormalisedProduct[];
+    facets: Facet[];
+    filters: Record<string, string | string[]>;
+    sort: ProductSortKey;
+    pagination: {
+        cursor: string | null;
+        hasMore: boolean;
+    };
+    loading: boolean;
+    error: string | null;
+}
+interface SearchState {
+    query: string;
+    /** The category slug the search is narrowed to, or null for every category. */
+    category: string | null;
+    /** Every page loaded so far, in rank order. */
+    results: DenormalisedProduct[];
+    /** The API's count of every match, not of the results loaded. */
+    total: number;
+    /** The next page's cursor; null when every match is loaded. */
+    nextCursor: string | null;
+    /** The search's facets: the category facet when search reports `facet` and the query matches. */
+    facets: Facet[];
+    loading: boolean;
+}
+type CheckoutStep = 'contact' | 'shipping' | 'payment' | 'confirmation';
+interface ShippingMethod {
+    carrier: string;
+    service: string;
+    amountMinor: number;
+    currency: string;
+    estimatedDays: number;
+}
+interface CheckoutState {
+    step: CheckoutStep;
+    email: string;
+    shippingAddress: Address | null;
+    billingAddress: Address | null;
+    shippingMethod: ShippingMethod | null;
+    /** What the server said about the payment; `succeeded` only once the order is paid. */
+    paymentStatus: 'idle' | 'processing' | 'requires_action' | 'succeeded' | 'failed';
+    error: string | null;
+    /** The API's code for `error` (`auth.token_invalid`, …), null when the error came from no API answer. */
+    errorCode: string | null;
+    order: {
+        orderId: string;
+        orderNumber: string;
+        paymentIntent: PaymentIntent;
+    } | null;
+    /** The order this cart already became, when the server refused a resubmit and named it. */
+    placedOrderNumber: string | null;
+    /** That order's key, when the refusal carried one. */
+    placedOrderKey: string | null;
+}
+interface AuthState {
+    customer: Customer | null;
+    isAuthenticated: boolean;
+    loading: boolean;
+    error: string | null;
+}
+interface ProductListParams {
+    limit?: number;
+    cursor?: string;
+    category?: string;
+    sort?: ProductSortKey;
+}
+interface ProductListResult {
+    items: DenormalisedProduct[];
+    nextCursor: string | null;
+    facets?: Facet[];
+}
+interface ProductSearchParams {
+    limit?: number;
+    cursor?: string;
+    /** A category slug, as on the listing. */
+    category?: string;
+}
+interface ProductSearchResult {
+    items: DenormalisedProduct[];
+    nextCursor: string | null;
+    total: number;
+    facets: Facet[];
+}
+interface CheckoutDetails {
+    email: string;
+    billingAddress: Address;
+    shippingAddress: Address;
+    notes?: string;
+}
+interface CheckoutResult {
+    orderId: string;
+    orderNumber: string;
+    paymentIntent: PaymentIntent;
+    currency: string;
+    totalMinor: number;
+    orderStatus: OrderStatus;
+    payment: CheckoutPayment;
+    /** Reads the order with no session (`customer.orders.get(n, { key })`); absent from an API that mints none. */
+    orderKey?: string;
+}
+interface RegisterParams {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+}
+interface AuthResult {
+    customer: Customer;
+    accessToken: string;
+    expiresIn: number;
+}
+type NewAddress = Address & {
+    isDefaultBilling?: boolean;
+    isDefaultShipping?: boolean;
+};
+interface OrderPage {
+    items: Order[];
+    nextCursor: string | null;
+}
+
+interface CommerceAdapter {
+    /** What the store can do (GET /api/capabilities); an adapter without it cannot tell the storefront. */
+    capabilities?: {
+        get(): Promise<StoreCapabilities>;
+    };
+    /**
+     * A guest's orders, read with the order's key; an expired key opens the order beside the order's email. An adapter
+     * without it cannot open a guest's order.
+     */
+    orders?: {
+        get(orderNumber: string, options?: {
+            key?: string;
+            email?: string;
+        }): Promise<ShopperOrder>;
+        /** Asks the store to email the order's link to the order's own email; it answers the same whatever matched. */
+        requestLink(request: {
+            orderNumber: string;
+            email: string;
+        }): Promise<void>;
+    };
+    /** The shopper's recently viewed products; an adapter without it shows none. */
+    recentlyViewed?: {
+        record(productId: string): Promise<void>;
+        list(): Promise<{
+            items: DenormalisedProduct[];
+        }>;
+    };
+    cart: {
+        get(): Promise<Cart>;
+        addItem(variantId: string, qty: number): Promise<Cart>;
+        removeItem(variantId: string): Promise<Cart>;
+        updateQuantity(variantId: string, qty: number): Promise<Cart>;
+        clear(): Promise<Cart>;
+    };
+    products: {
+        getBySlug(slug: string): Promise<DenormalisedProduct>;
+        list(params?: ProductListParams): Promise<ProductListResult>;
+        search(query: string, params?: ProductSearchParams): Promise<ProductSearchResult>;
+    };
+    checkout: {
+        create(details: CheckoutDetails): Promise<CheckoutResult>;
+    };
+    customers: {
+        register(params: RegisterParams): Promise<AuthResult>;
+        login(email: string, password: string): Promise<AuthResult>;
+        logout(): Promise<void>;
+        refresh(): Promise<{
+            accessToken: string;
+            expiresIn: number;
+        }>;
+        getProfile(): Promise<Customer>;
+        updateProfile(updates: Partial<Pick<Customer, 'firstName' | 'lastName' | 'phone'>>): Promise<Customer>;
+        listAddresses(): Promise<CustomerAddress[]>;
+        addAddress(address: NewAddress): Promise<CustomerAddress>;
+        removeAddress(id: string): Promise<void>;
+        listOrders(params?: {
+            cursor?: string;
+        }): Promise<OrderPage>;
+        /** `key` is the order's key from its checkout, for a reader with no session. */
+        getOrder(orderNumber: string, options?: {
+            key?: string;
+        }): Promise<ShopperOrder>;
+    };
+    reviews: {
+        getForProduct(productId: string, params?: {
+            limit?: number;
+            cursor?: string;
+        }): Promise<PublicReviewsResult>;
+        submit(review: {
+            productId: string;
+            rating: number;
+            title: string;
+            body: string;
+        }): Promise<ReviewResult>;
+    };
+    alerts: {
+        /**
+         * Asks to be emailed when a variant is back; the store mails a confirmation first. The answer is `pending` whether
+         * or not the address has an account or an alert already.
+         */
+        subscribe(request: {
+            email: string;
+            variantId: string;
+            kind: AlertKind;
+        }): Promise<{
+            status: 'pending';
+        }>;
+    };
+}
+
+/** A refresh: its token for the manager to hold, or nothing when it has set (or cleared) the token itself. */
+type RefreshFn = () => Promise<{
+    accessToken: string;
+    expiresIn: number;
+} | void>;
+interface TokenManagerOptions {
+    storage?: 'memory' | 'localStorage';
+    storageKey?: string;
+}
+interface TokenManager {
+    getAccessToken(): string | null;
+    setTokens(accessToken: string, expiresIn: number): void;
+    clear(): void;
+    scheduleRefresh(refreshFn: RefreshFn): void;
+    destroy(): void;
+}
+declare function createTokenManager(options?: TokenManagerOptions): TokenManager;
+
+interface CartStore {
+    getState(): CartState;
+    subscribe(listener: () => void): () => void;
+    addItem(variantId: string, qty?: number): Promise<void>;
+    removeItem(variantId: string): Promise<void>;
+    updateQuantity(variantId: string, qty: number): Promise<void>;
+    clear(): Promise<void>;
+    load(): Promise<void>;
+    destroy(): void;
+}
+declare function createCartStore(adapter: CommerceAdapter): CartStore;
+
+interface ProductStore {
+    getState(): ProductState;
+    subscribe(listener: () => void): () => void;
+    loadBySlug(slug: string): Promise<void>;
+    selectVariant(variant: DenormalisedVariant | null): void;
+    destroy(): void;
+}
+declare function createProductStore(adapter: CommerceAdapter): ProductStore;
+
+interface ProductListStore {
+    getState(): ProductListState;
+    subscribe(listener: () => void): () => void;
+    load(params?: ProductListParams): Promise<void>;
+    loadMore(): Promise<void>;
+    applyFilter(name: string, value: string | string[]): Promise<void>;
+    removeFilter(name: string): Promise<void>;
+    setSort(sort: ProductSortKey): Promise<void>;
+    destroy(): void;
+}
+declare function createProductListStore(adapter: CommerceAdapter): ProductListStore;
+
+interface SearchStore {
+    getState(): SearchState;
+    subscribe(listener: () => void): () => void;
+    /** Page 1 of `query`, in `options.category` (a slug) when given, otherwise in every category. */
+    search(query: string, options?: {
+        category?: string | null;
+    }): Promise<void>;
+    /** Appends the next page; a no-op when every match is loaded or a page is loading. */
+    loadMore(): Promise<void>;
+    /** Page 1 of the current query in `category` (a slug), or in every category when null. */
+    setCategory(category: string | null): Promise<void>;
+    clearSearch(): void;
+    destroy(): void;
+}
+declare function createSearchStore(adapter: CommerceAdapter): SearchStore;
+
+interface CheckoutStore {
+    getState(): CheckoutState;
+    subscribe(listener: () => void): () => void;
+    setEmail(email: string): void;
+    setShippingAddress(address: Address): void;
+    setBillingAddress(address: Address): void;
+    setShippingMethod(method: ShippingMethod): void;
+    /** Places the order; resolves to the server's result, or null when there is none. */
+    submitPayment(): Promise<CheckoutResult | null>;
+    /** The provider confirmed the payment on the client (Stripe's `confirmCardPayment`). */
+    markConfirmed(): void;
+    reset(): void;
+    destroy(): void;
+}
+/**
+ * `cart`, when given, is loaded again once the server has answered a submit: placing an order changes the cart on the
+ * server (emptied when confirmed, kept while awaiting payment), and whatever renders the cart store must show that.
+ */
+declare function createCheckoutStore(adapter: CommerceAdapter, cart?: CartStore): CheckoutStore;
+
+interface AuthStore {
+    getState(): AuthState;
+    subscribe(listener: () => void): () => void;
+    login(email: string, password: string): Promise<void>;
+    register(params: RegisterParams): Promise<void>;
+    logout(): Promise<void>;
+    refreshToken(): Promise<void>;
+    updateProfile(updates: Partial<Pick<Customer, 'firstName' | 'lastName' | 'phone'>>): Promise<void>;
+    loadProfile(): Promise<void>;
+    /**
+     * Brings a page load's session back: the profile with a token held; with none, one refresh from the refresh cookie
+     * when this browser has signed in (the session hint), then the profile; a guest's sends nothing. Never throws.
+     */
+    restore(): Promise<void>;
+    destroy(): void;
+}
+declare function createAuthStore(adapter: CommerceAdapter, tokenManager: TokenManager, restoreSession?: () => Promise<void>): AuthStore;
+
+type Listener = () => void;
+interface Store<TState> {
+    getState(): TState;
+    setState(partial: Partial<TState> | ((prev: TState) => Partial<TState>)): void;
+    subscribe(listener: Listener): () => void;
+    destroy(): void;
+}
+declare function createStore<TState extends object>(initialState: TState): Store<TState>;
+
+interface NymbalClientOptions {
+    baseUrl: string;
+    adapter?: CommerceAdapter;
+    tokenStorage?: 'memory' | 'localStorage';
+    credentials?: RequestCredentials;
+    getCartToken?: () => string | null;
+}
+/** The signed-in customer's own account; every call sends the session's bearer token. */
+interface CustomerAccount {
+    addresses: {
+        list(): Promise<CustomerAddress[]>;
+        create(address: NewAddress): Promise<CustomerAddress>;
+        remove(id: string): Promise<void>;
+    };
+    orders: {
+        list(opts?: {
+            cursor?: string;
+        }): Promise<OrderPage>;
+        /** `key`, the order's key from its checkout, reads it with no session; without one, only its owner can. */
+        get(orderNumber: string, options?: {
+            key?: string;
+        }): Promise<ShopperOrder>;
+    };
+}
+/**
+ * A guest's orders, opened with the key from the checkout or the order email. Once the key has expired, the read is
+ * refused with `orders.key_expired` and opens with the order's email beside the key; the email travels in a header,
+ * never in a URL.
+ */
+interface GuestOrders {
+    get(orderNumber: string, options?: {
+        key?: string;
+        email?: string;
+    }): Promise<ShopperOrder>;
+    /** Asks the store to email the order's link to the order's own email; it answers the same whatever matched. */
+    requestLink(request: {
+        orderNumber: string;
+        email: string;
+    }): Promise<void>;
+}
+/** The store's capabilities report, read once per client: what it can do does not change while it runs. */
+interface StoreCapabilitiesReader {
+    get(): Promise<StoreCapabilities>;
+}
+/** The shopper's recently viewed products, kept by the store under the signed-in customer or the browser's visitor. */
+interface RecentlyViewed {
+    /** Records a view of the product; the store ignores a product that is not active. */
+    record(productId: string): Promise<void>;
+    /** The shopper's active products, newest first. */
+    list(): Promise<{
+        items: DenormalisedProduct[];
+    }>;
+}
+interface NymbalClient {
+    capabilities: StoreCapabilitiesReader;
+    recentlyViewed: RecentlyViewed;
+    cart: CartStore;
+    product: ProductStore;
+    productList: ProductListStore;
+    search: SearchStore;
+    checkout: CheckoutStore;
+    auth: AuthStore;
+    customer: CustomerAccount;
+    orders: GuestOrders;
+    adapter: CommerceAdapter;
+    destroy(): void;
+}
+/** What `onStoreBuilt` hands its listener: any store, a hand-made client's included, reads and subscribes. */
+type ObservedStore = Pick<Store<unknown>, 'getState' | 'subscribe'>;
+type StoreListener = (store: ObservedStore) => void;
+/**
+ * `auth.restore()`'s refresh without the auth store, for a page that reads no profile: with the session hint and no
+ * token held, the one refresh from the refresh cookie, which every other request the client sends meanwhile waits for.
+ * A guest's sends nothing. An `auth.restore()` called while it is in flight shares it. Never throws.
+ */
+declare function resumeSession(client: NymbalClient): Promise<void>;
+/**
+ * Calls `listener` with each store namespace the client has built, and with each it builds later; returns the
+ * unsubscribe. A client not made by `createNymbalClient` has its stores already: each is reported once, now.
+ */
+declare function onStoreBuilt(client: NymbalClient, listener: StoreListener): () => void;
+declare function createNymbalClient(options: NymbalClientOptions): NymbalClient;
+
+/** What a checkout already knows about the shopper, which a driver may hand its processor with the payment. */
+interface PaymentConfirmContext {
+    email?: string;
+    billing?: Address;
+}
+/** What a payment driver's `confirm` answers: paid now, accepted without a payment yet, or refused with a reason. */
+type PaymentConfirmation = {
+    ok: true;
+    confirmed: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The browser half of a payments adapter, named by the `driver` of GET /api/capabilities' payments client. `mount`
+ * renders whatever the shopper pays with inside `el`; `confirm` completes a payment the API left `requires_action`,
+ * with the shopper's email and billing address when the checkout has them.
+ */
+interface PaymentDriver {
+    mount(el: HTMLElement, options: Record<string, string>): Promise<void> | void;
+    confirm(clientSecret: string, context?: PaymentConfirmContext): Promise<PaymentConfirmation>;
+}
+/** Registers `driver` under `name`, replacing any driver of that name. */
+declare function registerPaymentDriver(name: string, driver: PaymentDriver): void;
+declare function getPaymentDriver(name: string): PaymentDriver | undefined;
+
+/**
+ * Set in `localStorage` while the browser holds a session the refresh cookie can bring back. It holds no token: a page
+ * load with no hint is a guest's, and restores nothing.
+ */
+declare const SESSION_HINT_KEY = "nymbal.auth.session";
+
+declare class NymbalApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, status: number, context?: Record<string, unknown> | undefined);
+}
+interface FetchClientOptions {
+    baseUrl: string;
+    credentials?: RequestCredentials;
+    getAccessToken?: () => string | null;
+    getCartToken?: () => string | null;
+    onUnauthorized?: () => Promise<void>;
+}
+/** Per request: headers sent beside the client's own. */
+interface RequestOptions {
+    headers?: Record<string, string>;
+    /**
+     * The token refresh itself (what `onUnauthorized` sends through this client): its 401 is thrown, never waited on or
+     * sent again, so a refused refresh cannot wait on itself. An unmarked one that is refused is cut off after
+     * 10 s with the original 401.
+     */
+    authRefresh?: boolean;
+    /**
+     * Sent with a customer's bearer, never sent again without one: when the 401's refresh leaves no token, the 401 is
+     * thrown. For a request the API would otherwise answer as a guest (a checkout begin).
+     */
+    keepIdentity?: boolean;
+}
+declare class FetchClient {
+    private readonly baseUrl;
+    private readonly credentials;
+    private readonly getAccessToken;
+    private readonly getCartToken;
+    private readonly onUnauthorized;
+    /** The refresh a refused request started, which every request refused meanwhile waits on rather than its own. */
+    private refreshing;
+    /** The token `GET /api/csrf` answered: the API's `nymbal.csrf` cookie, which this origin may not be able to read. */
+    private csrfToken;
+    /** A session restore's refresh, which every request sent meanwhile waits on so that none goes out as a guest. */
+    private held;
+    constructor(options: FetchClientOptions);
+    /** Starts the session's refresh, or joins the one in flight: a client sends one refresh at a time. */
+    refreshSession(): Promise<void>;
+    /**
+     * As `refreshSession`, and every other request sent until the refresh settles waits for it, at most
+     * `REFRESH_WAIT_MS`. Held from this call on, before any await: a page's first requests go in the same tick.
+     */
+    restoreSession(): Promise<void>;
+    request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /** Like `request`, keeping the envelope's `meta` (pagination cursors live there). */
+    requestWithMeta<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<{
+        data: T;
+        meta: Record<string, unknown>;
+    }>;
+    /** Whether the refresh ended within `REFRESH_WAIT_MS`; a refresh that fails throws here, as it always has. */
+    private waitFor;
+    private refresh;
+    private csrf;
+    private fetchCsrfToken;
+    private isCsrfRejection;
+    private doFetch;
+    private parseResponse;
+}
+
+export { getPaymentDriver as $, FetchClient as F, createAuthStore as M, createCartStore as Q, SESSION_HINT_KEY as S, createCheckoutStore as U, createNymbalClient as V, createProductListStore as W, createProductStore as X, createSearchStore as Y, createStore as Z, createTokenManager as _, registerPaymentDriver as a0, onStoreBuilt as a1, resumeSession as a2, NymbalApiError as m };
+export type { AuthResult as A, SearchState as B, CommerceAdapter as C, DenormalisedProduct as D, SearchStore as E, GuestOrders as G, ShippingMethod as H, Store as I, StoreCapabilitiesReader as J, TokenManagerOptions as K, Listener as L, NewAddress as N, OrderPage as O, PaymentConfirmContext as P, RecentlyViewed as R, TokenManager as T, AuthState as a, AuthStore as b, CartState as c, CartStore as d, CheckoutDetails as e, CheckoutResult as f, CheckoutState as g, CheckoutStep as h, CheckoutStore as i, CustomerAccount as j, DenormalisedVariant as k, FetchClientOptions as l, NymbalClient as n, NymbalClientOptions as o, PaymentConfirmation as p, PaymentDriver as q, ProductListParams as r, ProductListResult as s, ProductListState as t, ProductListStore as u, ProductSearchParams as v, ProductSearchResult as w, ProductState as x, ProductStore as y, RegisterParams as z };

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+export { j as CustomerAccount, G as GuestOrders, m as NymbalApiError, n as NymbalClient, o as NymbalClientOptions, P as PaymentConfirmContext, p as PaymentConfirmation, q as PaymentDriver, R as RecentlyViewed, S as SESSION_HINT_KEY, J as StoreCapabilitiesReader, V as createNymbalClient, $ as getPaymentDriver, a1 as onStoreBuilt, a0 as registerPaymentDriver, a2 as resumeSession } from './core-BviXjOsX.js';
+import '@nymbalhq/types';

package/dist/core.js

@@ -0,0 +1,21 @@
+import {
+  getPaymentDriver,
+  registerPaymentDriver
+} from "./chunk-4GP43MKT.js";
+import {
+  NymbalApiError,
+  SESSION_HINT_KEY,
+  createNymbalClient,
+  onStoreBuilt,
+  resumeSession
+} from "./chunk-2EEZZXZX.js";
+export {
+  NymbalApiError,
+  SESSION_HINT_KEY,
+  createNymbalClient,
+  getPaymentDriver,
+  onStoreBuilt,
+  registerPaymentDriver,
+  resumeSession
+};
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}