@nymbalhq/sdk 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,372 @@
+import { Customer, CartItem, Address, PaymentIntent, OrderStatus, CheckoutPayment, VariantOption, ProductSortKey, Facet, Order, Cart, CustomerAddress, ReviewsResult, ReviewResult } from '@nymbalhq/types';
+export { ProductSortKey, ReviewResult as ReviewSubmitResult, ReviewsResult as ReviewsListResult } 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;
+}
+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;
+    results: DenormalisedProduct[];
+    total: number;
+    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;
+    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;
+}
+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 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;
+}
+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 {
+    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?: {
+            limit?: number;
+            cursor?: string;
+        }): Promise<ProductListResult>;
+    };
+    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>;
+        getOrder(orderNumber: string): Promise<Order>;
+    };
+    reviews: {
+        getForProduct(productId: string, params?: {
+            limit?: number;
+            cursor?: string;
+        }): Promise<ReviewsResult>;
+        submit(review: {
+            productId: string;
+            rating: number;
+            title: string;
+            body: string;
+        }): Promise<ReviewResult>;
+    };
+}
+
+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;
+    search(query: string): 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 TokenManagerOptions {
+    storage?: 'memory' | 'localStorage';
+    storageKey?: string;
+}
+interface TokenManager {
+    getAccessToken(): string | null;
+    setTokens(accessToken: string, expiresIn: number): void;
+    clear(): void;
+    scheduleRefresh(refreshFn: () => Promise<{
+        accessToken: string;
+        expiresIn: number;
+    }>): void;
+    destroy(): void;
+}
+declare function createTokenManager(options?: TokenManagerOptions): TokenManager;
+
+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>;
+    destroy(): void;
+}
+declare function createAuthStore(adapter: CommerceAdapter, tokenManager: TokenManager): AuthStore;
+
+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>;
+        get(orderNumber: string): Promise<Order>;
+    };
+}
+interface NymbalClient {
+    cart: CartStore;
+    product: ProductStore;
+    productList: ProductListStore;
+    search: SearchStore;
+    checkout: CheckoutStore;
+    auth: AuthStore;
+    customer: CustomerAccount;
+    adapter: CommerceAdapter;
+    destroy(): void;
+}
+declare function createNymbalClient(options: NymbalClientOptions): NymbalClient;
+
+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>;
+
+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>;
+}
+declare class FetchClient {
+    private readonly baseUrl;
+    private readonly credentials;
+    private readonly getAccessToken;
+    private readonly getCartToken;
+    private readonly onUnauthorized;
+    private handlingUnauthorized;
+    /** The token `GET /api/csrf` answered: the API's `nymbal.csrf` cookie, which this origin may not be able to read. */
+    private csrfToken;
+    constructor(options: FetchClientOptions);
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+    /** Like `request`, keeping the envelope's `meta` (pagination cursors live there). */
+    requestWithMeta<T>(method: string, path: string, body?: unknown): Promise<{
+        data: T;
+        meta: Record<string, unknown>;
+    }>;
+    private csrf;
+    private fetchCsrfToken;
+    private isCsrfRejection;
+    private doFetch;
+    private parseResponse;
+}
+
+declare function createNymbalApiAdapter(fetchClient: FetchClient): CommerceAdapter;
+
+export { type AuthResult, type AuthState, type AuthStore, type CartState, type CartStore, type CheckoutDetails, type CheckoutResult, type CheckoutState, type CheckoutStep, type CheckoutStore, type CommerceAdapter, type CustomerAccount, type DenormalisedProduct, type DenormalisedVariant, FetchClient, type FetchClientOptions, type Listener, type NewAddress, NymbalApiError, type NymbalClient, type NymbalClientOptions, type OrderPage, type ProductListParams, type ProductListResult, type ProductListState, type ProductListStore, type ProductState, type ProductStore, type RegisterParams, type SearchState, type SearchStore, type ShippingMethod, type Store, type TokenManager, type TokenManagerOptions, createAuthStore, createCartStore, createCheckoutStore, createNymbalApiAdapter, createNymbalClient, createProductListStore, createProductStore, createSearchStore, createStore, createTokenManager };