@usethrottle/auth 0.11.0 → 0.12.1

package/dist/client-7LVKfuXO.d.ts

@@ -0,0 +1,319 @@
+interface Customer {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    firstName?: string | null;
+    lastName?: string | null;
+    phone?: string | null;
+    company?: string | null;
+    acceptsMarketing?: boolean;
+}
+interface Session {
+    accessToken: string;
+    expiresAt: string;
+    refreshToken: string;
+    customer: Customer;
+}
+/**
+ * Defined here rather than in `storage.ts` so `ThrottleAuthConfig` can name it
+ * without importing a module that does not exist until Task 2. `storage.ts`
+ * imports and re-exports it.
+ */
+interface AuthStorage {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+interface ThrottleAuthConfig {
+    publishableKey: string;
+    baseUrl?: string;
+    storage?: AuthStorage;
+    /** Called when a route needs a step-up proof. Return the buyer's password, or null to cancel. */
+    onStepUpRequired?: () => Promise<string | null>;
+}
+interface ProfilePatch {
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    company?: string | null;
+    acceptsMarketing?: boolean;
+}
+interface AddressInput {
+    label?: string;
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    stateProvince?: string;
+    postalCode?: string;
+    countryCode: string;
+    phone?: string;
+    isDefault?: boolean;
+}
+interface Address {
+    id: string;
+    label: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    company: string | null;
+    addressLine1: string;
+    addressLine2: string | null;
+    city: string;
+    stateProvince: string | null;
+    postalCode: string | null;
+    countryCode: string;
+    phone: string | null;
+    isDefault: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface PaymentMethod {
+    id: string;
+    methodType: string;
+    cardBrand: string | null;
+    cardLastFour: string | null;
+    cardExpMonth: number | null;
+    cardExpYear: number | null;
+    isDefault: boolean;
+    createdAt: string;
+}
+interface Order {
+    id: string;
+    orderNumber: string;
+    status: string;
+    type: string;
+    paymentStatus: string;
+    currency: string;
+    subtotal: number;
+    taxTotal: number;
+    discountTotal: number;
+    shippingTotal: number;
+    total: number;
+    buyerVatNumber: string | null;
+    taxReverseCharge: boolean;
+    billingAddress: unknown | null;
+    shippingAddress: unknown | null;
+    discountCode: string | null;
+    /** Set only when the order is linked to exactly one subscription. Read `subscriptionIds`. */
+    subscriptionId: string | null;
+    /** Every subscription this order created, in line order. One cart can hold several. */
+    subscriptionIds: string[];
+    /**
+     * The invoice raised for this order, when one exists. Resolved on the
+     * detail read only — the list would need a lookup per row.
+     */
+    invoiceId?: string | null;
+    cancelledAt: string | null;
+    completedAt: string | null;
+    closedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface OrderLineItem {
+    id: string;
+    name: string;
+    description: string | null;
+    quantity: number;
+    /** Integer minor units, like every other amount on the wire. */
+    unitPrice: number;
+    subtotal: number;
+    taxAmount: number;
+    discountAmount: number;
+    total: number;
+    imageUrl: string | null;
+    /** The subscription this line created, or null for a one-time line. */
+    subscriptionId: string | null;
+    /**
+     * The catalog SKU the line was bought as, or null. Carried so "order
+     * again" can re-add the line; never display it. Sent by APIs with the
+     * Storefront Part 8 change (absent from older ones, read as null); optional
+     * in the type so 0.11-shaped implementations still compile.
+     */
+    referenceId?: string | null;
+}
+/** The buyer's newest open (or idle-abandoned) cart in one currency. */
+interface OpenCart {
+    cartId: string;
+    sessionId: string;
+    sessionExpiresAt: string;
+    currency: string;
+    status: 'open' | 'abandoned';
+}
+/**
+ * What `getOrder` returns. Deliberately NOT folded into `Order`: the list route
+ * does not load line items, so a required `lineItems` on `Order` would be a
+ * promise the list response cannot keep.
+ */
+interface OrderDetail extends Order {
+    lineItems: OrderLineItem[];
+}
+interface InvoiceLineItem {
+    name: string;
+    description: string | null;
+    quantity: number;
+    unitPrice: number;
+    taxAmount: number;
+    discountAmount: number;
+    total: number;
+}
+interface Invoice {
+    id: string;
+    number: string;
+    status: string;
+    currency: string;
+    subtotal: number;
+    taxTotal: number;
+    shippingTotal: number;
+    discountTotal: number;
+    total: number;
+    amountRefunded: number;
+    issuedAt: string;
+    dueAt: string | null;
+    periodStart: string | null;
+    periodEnd: string | null;
+    createdAt: string;
+    updatedAt: string;
+    /** What this invoice billed: 'order' | 'net30' | 'subscription'. */
+    sourceType: string | null;
+    /** Frozen at issue — the lines actually billed, not the order's lines today. */
+    lineItems: InvoiceLineItem[];
+    /**
+     * Set when the invoice bills less than the order: the order total its lines
+     * add up to. `total` is then the amount due (Net-N invoice) or the amount
+     * paid (a deposit receipt). Null when the invoice bills the whole order.
+     */
+    orderTotal: number | null;
+    /** Net-N invoices: paid on the order before this invoice (e.g. a deposit). */
+    amountPaid: number | null;
+    /** Net-N invoices: waived by a comp. */
+    compWaived: number | null;
+    /** Deposit receipts: the balance still due, billed on the Net-N invoice. */
+    balanceDue: number | null;
+    /** Resolved on the detail read only; null on list rows and when the hop fails. */
+    orderId: string | null;
+    orderNumber: string | null;
+    subscriptionId: string | null;
+}
+interface Subscription {
+    id: string;
+    status: string;
+    planReference: string;
+    planName: string | null;
+    interval: string;
+    intervalUnit: string | null;
+    intervalCount: number | null;
+    totalPayments: number | null;
+    paymentsMade: number;
+    completedAt: string | null;
+    /** Installment plans only: every payment in order; dueAt is an estimate. */
+    paymentSchedule?: Array<{
+        index: number;
+        amount: number;
+        discount: number;
+        net: number;
+        intervalUnit: string | null;
+        intervalCount: number | null;
+        status: 'paid' | 'due' | 'upcoming';
+        dueAt: string | null;
+    }> | null;
+    /** Installment plans only: the sum of every payment's net amount. */
+    scheduleTotal?: number | null;
+    /** Installment plans only: what the next payment will charge; null once complete. */
+    nextPaymentAmount?: number | null;
+    amount: number;
+    quantity: number;
+    currency: string;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    trialEnd: string | null;
+    cancelledAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    pendingPlanReference: string | null;
+    pendingPlanName: string | null;
+    pendingInterval: string | null;
+    pendingQuantity: number | null;
+    pausedAt: string | null;
+    lastPaymentAt: string | null;
+    /** `shipment` = a physical subscription: every renewal ships a box to `shippingAddress`. */
+    deliveryMethod?: 'access_grant' | 'shipment';
+    /** Where a physical subscription ships; null when nothing ships. */
+    shippingAddress?: SubscriptionShippingAddress | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Where a physical subscription's box goes. */
+interface SubscriptionShippingAddress {
+    firstName?: string;
+    lastName?: string;
+    company?: string;
+    addressLine1: string;
+    addressLine2?: string;
+    city: string;
+    stateProvince?: string;
+    postalCode?: string;
+    countryCode: string;
+    phone?: string;
+}
+
+type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
+interface AuthSnapshot {
+    status: AuthStatus;
+    customer: Customer | null;
+    /**
+     * False here does NOT only mean "we emailed them and they have not clicked".
+     * While it is false the API may also be withholding pre-existing account
+     * data behind the claim cutoff — empty order lists and a 403 on `PATCH /me`
+     * are expected, not broken. See the plan header.
+     */
+    emailVerified: boolean;
+}
+
+interface DeviceSession {
+    id: string;
+    userAgent: string | null;
+    ipPrefix: string | null;
+    createdAt: string;
+    lastUsedAt: string;
+    current: boolean;
+}
+interface ThrottleAuth {
+    register(email: string, password: string): Promise<{
+        status: 'active' | 'pending';
+    }>;
+    signIn(email: string, password: string): Promise<void>;
+    signOut(): Promise<void>;
+    signOutEverywhere(): Promise<void>;
+    restore(): Promise<void>;
+    getSnapshot(): AuthSnapshot;
+    /**
+     * The current access token, refreshed first when it is about to expire
+     * (single-flight, shared with every other caller), or null when signed out.
+     * Rejects when a refresh fails without ending the session (a 5xx, a 429 or
+     * a network error); the buyer stays signed in. `@usethrottle/catalog`
+     * treats a rejection as signed out for that request.
+     * Pass it to `@usethrottle/catalog`'s `customerToken`.
+     */
+    getAccessToken(): Promise<string | null>;
+    subscribe(fn: (s: AuthSnapshot) => void): () => void;
+    stepUp(password: string): Promise<void>;
+    call<T = any>(method: string, path: string, body?: unknown): Promise<T>;
+    verifyEmail(token: string): Promise<void>;
+    resendVerification(): Promise<void>;
+    forgotPassword(email: string): Promise<void>;
+    resetPassword(token: string, password: string): Promise<void>;
+    changePassword(password: string): Promise<void>;
+    listSessions(): Promise<DeviceSession[]>;
+    revokeSession(id: string): Promise<void>;
+    /**
+     * Resolves once any sign-in or registration claim in flight has settled.
+     * `createThrottleAuth` always supplies it (it resolves at once there);
+     * `ThrottleProvider` supplies one that tracks its cart claim. Optional so a
+     * hand-made `ThrottleAuth` written against 0.11 still compiles.
+     */
+    whenClaimSettled?(): Promise<void>;
+}
+declare function createThrottleAuth(config: ThrottleAuthConfig): ThrottleAuth & Required<Pick<ThrottleAuth, 'whenClaimSettled'>>;
+
+export { type Address as A, type Customer as C, type DeviceSession as D, type Invoice as I, type OpenCart as O, type PaymentMethod as P, type Session as S, type ThrottleAuth as T, type AddressInput as a, type AuthSnapshot as b, type AuthStatus as c, type AuthStorage as d, type Order as e, type OrderDetail as f, type ProfilePatch as g, type Subscription as h, type SubscriptionShippingAddress as i, type ThrottleAuthConfig as j, createThrottleAuth as k };

package/dist/hooks-DkpLrEiC.d.ts

@@ -0,0 +1,148 @@
+import { C as Customer, g as ProfilePatch, A as Address, a as AddressInput, P as PaymentMethod, e as Order, f as OrderDetail, I as Invoice, h as Subscription, i as SubscriptionShippingAddress, O as OpenCart, T as ThrottleAuth } from './client-7LVKfuXO.js';
+
+interface Page {
+    cursor?: string;
+    limit?: number;
+}
+/** What the payment widget needs to render a card form. Passed through from
+ *  the processor — `buyerExternalIdentifier` in particular must reach the
+ *  widget unchanged, because the session token pins it and the processor
+ *  refuses a mismatch by rendering nothing at all. */
+interface CardSetupSession {
+    embedToken: string;
+    checkoutSessionId: string;
+    amount: number;
+    currency: string;
+    merchantAccountId?: string;
+    environment?: string;
+    buyerExternalIdentifier: string;
+    country: string;
+    /** A ready-made page that hosts the card form, if you would rather redirect
+     *  or iframe than embed the widget yourself. */
+    hostedUrl: string;
+    embedUrl: string;
+}
+interface ThrottleAccount {
+    getProfile(): Promise<Customer>;
+    updateProfile(patch: ProfilePatch): Promise<Customer>;
+    listAddresses(): Promise<Address[]>;
+    createAddress(input: AddressInput): Promise<Address>;
+    updateAddress(id: string, patch: Partial<AddressInput>): Promise<Address>;
+    deleteAddress(id: string): Promise<void>;
+    listPaymentMethods(): Promise<PaymentMethod[]>;
+    setDefaultPaymentMethod(id: string): Promise<PaymentMethod>;
+    deletePaymentMethod(id: string): Promise<void>;
+    /** Opens a processor-hosted session the buyer types their card into. The
+     *  returned values are handed straight to the payment widget. */
+    startCardSetup(): Promise<CardSetupSession>;
+    /** Records the card the widget just vaulted, identified by the transaction
+     *  the widget returns. Safe to call twice with the same id. */
+    confirmCardSetup(transactionId: string): Promise<PaymentMethod>;
+    listOrders(page?: Page): Promise<Order[]>;
+    getOrder(id: string): Promise<OrderDetail>;
+    listInvoices(page?: Page): Promise<Invoice[]>;
+    getInvoice(id: string): Promise<Invoice>;
+    /** A 600-second signed URL. Fetch it on click — it expires. */
+    getInvoicePdfUrl(id: string): Promise<{
+        url: string;
+    }>;
+    listSubscriptions(page?: Page): Promise<Subscription[]>;
+    getSubscription(id: string): Promise<Subscription>;
+    /**
+     * Voids an unpaid order. Refused once money has been captured — that is a
+     * return, not a cancellation, and only the merchant may move money back.
+     */
+    cancelOrder(id: string, opts?: {
+        reason?: string;
+    }): Promise<Order>;
+    /** Opens an RMA the merchant approves. Changes no order state by itself. */
+    requestOrderReturn(id: string, input: {
+        items: Array<{
+            lineItemId: string;
+            quantity: number;
+        }>;
+        reason?: string;
+    }): Promise<{
+        id: string;
+        status: string;
+    }>;
+    cancelSubscription(id: string, opts?: {
+        atPeriodEnd?: boolean;
+    }): Promise<Subscription>;
+    pauseSubscription(id: string): Promise<Subscription>;
+    resumeSubscription(id: string): Promise<Subscription>;
+    /**
+     * Where a physical subscription's box goes, from the next renewal. Needs a
+     * fresh sign-in (step-up), like cancelling. A subscription that ships
+     * nothing answers `subscription_not_physical`.
+     */
+    updateSubscriptionShippingAddress(id: string, address: SubscriptionShippingAddress): Promise<Subscription>;
+    claimCart(cartId: string): Promise<{
+        cartId: string;
+        customerId: string;
+    }>;
+    /**
+     * The buyer's newest open or idle-abandoned cart in `currency` (see `status`), or null. Answers null as well
+     * when the API predates the route (404). Always present on the account that
+     * `createAccount` and `ThrottleProvider` build; optional here so a hand-made
+     * `ThrottleAccount` written against 0.11 still compiles.
+     */
+    getOpenCart?(input: {
+        currency: string;
+    }): Promise<OpenCart | null>;
+}
+declare function createAccount(auth: ThrottleAuth): ThrottleAccount & Required<Pick<ThrottleAccount, 'getOpenCart'>>;
+
+declare class ThrottleAuthError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly retryAfter?: number;
+    readonly details?: unknown;
+    constructor(args: {
+        code: string;
+        message: string;
+        statusCode: number;
+        retryAfter?: number;
+        details?: unknown;
+    });
+}
+
+interface Resource<T> {
+    data: T;
+    isLoading: boolean;
+    error: ThrottleAuthError | null;
+    refetch(): Promise<void>;
+}
+declare function useCustomer(): Resource<Customer | null> & {
+    update(patch: ProfilePatch): Promise<void>;
+};
+declare function useAddresses(): Resource<Address[]> & {
+    create(input: AddressInput): Promise<void>;
+    update(id: string, patch: Partial<AddressInput>): Promise<void>;
+    remove(id: string): Promise<void>;
+};
+declare function useSavedCards(): Resource<PaymentMethod[]> & {
+    setDefault(id: string): Promise<void>;
+    remove(id: string): Promise<void>;
+};
+declare function useOrders(page?: Page): Resource<Order[]>;
+declare function useInvoices(page?: Page): Resource<Invoice[]>;
+declare function useSubscriptions(page?: Page): Resource<Subscription[]> & {
+    cancel(id: string, opts?: {
+        atPeriodEnd?: boolean;
+    }): Promise<void>;
+    pause(id: string): Promise<void>;
+    resume(id: string): Promise<void>;
+    /** Where a physical subscription ships, from the next renewal (step-up). */
+    updateShippingAddress(id: string, address: SubscriptionShippingAddress): Promise<void>;
+};
+/**
+ * Single-resource reads for the detail views. A `null` id means "nothing
+ * selected" and must not call the API — `useResource` still runs, so the
+ * loader resolves to null rather than being skipped, which keeps the
+ * loading/error shape identical whether or not an id is present.
+ */
+declare function useOrder(id: string | null): Resource<OrderDetail | null>;
+declare function useInvoice(id: string | null): Resource<Invoice | null>;
+
+export { type Page as P, type Resource as R, type ThrottleAccount as T, ThrottleAuthError as a, useCustomer as b, createAccount as c, useInvoice as d, useInvoices as e, useOrder as f, useOrders as g, useSavedCards as h, useSubscriptions as i, useAddresses as u };

package/dist/index.cjs

@@ -373,7 +373,10 @@ function createThrottleAuth(config) {
       const current = mine.find((s) => s.current);
       await call("DELETE", `/me/sessions/${encodeURIComponent(id)}`);
       if (current?.id === id) await forget();
-    }
+    },
+    // The core never claims a cart; `ThrottleProvider` overrides this with one
+    // that tracks its sign-in claim.
+    whenClaimSettled: () => Promise.resolve()
   };
 }
 
@@ -420,7 +423,18 @@ function createAccount(auth) {
     pauseSubscription: (id) => call("POST", `/me/subscriptions/${seg(id)}/pause`),
     resumeSubscription: (id) => call("POST", `/me/subscriptions/${seg(id)}/resume`),
     updateSubscriptionShippingAddress: (id, address) => call("PATCH", `/me/subscriptions/${seg(id)}/shipping-address`, address),
-    claimCart: (cartId) => call("POST", `/me/carts/${seg(cartId)}/claim`)
+    claimCart: (cartId) => call("POST", `/me/carts/${seg(cartId)}/claim`),
+    async getOpenCart({ currency }) {
+      if (typeof currency !== "string" || !/^[A-Za-z]{3}$/.test(currency)) {
+        throw new TypeError("getOpenCart: currency must be a 3-letter ISO code");
+      }
+      try {
+        return await call("GET", `/me/cart?currency=${currency.toUpperCase()}`);
+      } catch (err) {
+        if (err instanceof ThrottleAuthError && err.statusCode === 404) return null;
+        throw err;
+      }
+    }
   };
 }
 // Annotate the CommonJS export names for ESM import in node: