@tiledev/sdk-shopify 0.2.5

package/dist/react/ShopifyProvider.d.ts

@@ -0,0 +1,181 @@
+import { ReactNode } from "react";
+import type { AlertMessageKey, AlertMessages, Cart, CartLineAttribute, CartLineGuard, CartLineInput, CartPolicy, CartWriteResult, Customer, MessageResolver, Product, ShopifyConfig, WishlistItem, WishlistStorageAdapter } from "../types";
+interface CartState {
+    cart: Cart | null;
+    loading: boolean;
+    itemCount: number;
+    /** Distinct lines, which is what `maxLineItems` limits — not `itemCount`. */
+    lineCount: number;
+    /** The configured `maxLineItems`, or `null` when unlimited. */
+    maxLineItems: number | null;
+    /**
+     * `ok: false` means nothing was written: a `cartGuard` veto (`reason: 'guard'`) or the
+     * line limit (`reason: 'limit'`, with the configured message). Shopify refusing the
+     * line still throws — an unsellable one emits `cart:outOfStock` on the way out.
+     */
+    addLine: (input: CartLineInput) => Promise<CartWriteResult>;
+    /**
+     * Returns the resulting cart, `null` when nothing landed. One unsellable line fails the whole
+     * `cartLinesAdd`, so a rejected batch is retried line by line and the successes are kept.
+     */
+    addLines: (inputs: CartLineInput[]) => Promise<Cart | null>;
+    /**
+     * `false` when a `cartGuard` cancelled the increase. `attributes` REPLACE the line's set —
+     * Shopify does not merge them — so omit the argument to leave them untouched.
+     */
+    updateLine: (lineId: string, quantity: number, attributes?: CartLineAttribute[]) => Promise<boolean>;
+    removeLine: (lineId: string) => Promise<void>;
+    applyDiscountCodes: (codes: string[]) => Promise<void>;
+    /**
+     * Attributes the order to a buyer and opens checkout signed in. `false` when there is no cart
+     * yet. New customer accounts pass their Customer Account API token straight through.
+     */
+    setBuyerIdentity: (identity: {
+        email?: string;
+        countryCode?: string;
+        customerAccessToken?: string;
+    }) => Promise<boolean>;
+    /** Re-reads the cart and returns it, so a caller need not wait for the re-render. */
+    refresh: () => Promise<Cart | null>;
+    /**
+     * Switches to a cart handed over from elsewhere — another device, a support agent, the web store.
+     * A read and a swap, not a mutation: nothing is written to either cart. Null when that id no
+     * longer resolves, in which case the current cart is left alone.
+     */
+    adopt: (cartId: string) => Promise<Cart | null>;
+    reset: () => Promise<void>;
+}
+interface WishlistState {
+    items: WishlistItem[];
+    count: number;
+    has: (productId: string) => boolean;
+    /** Alias for `has`. */
+    isWishlisted: (productId: string) => boolean;
+    add: (product: Product | string) => Promise<void>;
+    remove: (productId: string) => Promise<void>;
+    toggle: (product: Product | string) => Promise<boolean>;
+    clear: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * The customer session, so the four Login alerts have somewhere to originate.
+ * `shopify.customer.*` stays available for everything else; this owns only what
+ * a session needs — the token, who it belongs to, and the events.
+ */
+interface CustomerState {
+    customer: Customer | null;
+    /** True once a stored token has been exchanged for a profile. */
+    loggedIn: boolean;
+    /** The stored access token, for callers that need it (Tile Credit, checkout). */
+    accessToken: string | null;
+    loading: boolean;
+    /** Restoring a stored token on mount — distinct from "logged out". */
+    restoring: boolean;
+    /** `false` on bad credentials, which emits `auth:loginFailed`. Everything else throws. */
+    login: (email: string, password: string) => Promise<boolean>;
+    signup: (input: {
+        email: string;
+        password: string;
+        firstName?: string;
+        lastName?: string;
+        acceptsMarketing?: boolean;
+    }) => Promise<boolean>;
+    /** Always resolves — Shopify refusing the token delete still ends the local session. */
+    logout: () => Promise<void>;
+    /** Emits `auth:recoverSent`. Shopify does not reveal whether the email exists. */
+    recoverPassword: (email: string) => Promise<void>;
+    /** Re-reads the profile for the stored token. Null if the token no longer resolves. */
+    refresh: () => Promise<Customer | null>;
+}
+/**
+ * Checkout is Shopify-hosted, so the SDK cannot see the outcome itself. The host
+ * webview reports it here and gets the configured copy on the event, rather than
+ * every app hard-coding "Your order has been placed".
+ *
+ * A `checkout.observe(url)` helper that classifies the return URL is the next
+ * piece of work; this is the seam it will emit through.
+ */
+interface CheckoutState {
+    /** Emits `checkout:orderPlaced`, then resets the cart so the next visit starts clean. */
+    reportOrderPlaced: (details?: {
+        orderId?: string;
+        orderNumber?: string | number;
+    }) => Promise<void>;
+    /** Emits `checkout:paymentFailed`. Leaves the cart alone so the shopper can retry. */
+    reportPaymentFailed: (error?: unknown) => void;
+}
+interface ShopifyContextType {
+    ready: boolean;
+    error: string | null;
+    cart: CartState;
+    wishlist: WishlistState;
+    customer: CustomerState;
+    checkout: CheckoutState;
+    /** Resolved alert copy, for labelling UI that isn't a toast — e.g. the
+     *  empty-wishlist placeholder (`wishlist.empty`), which has no event. */
+    message: (key: AlertMessageKey) => string;
+}
+/**
+ * Everything the host may want to tell the shopper about. One event per alert the
+ * editor's Settings panel configures, plus the writes that carry no copy of their own.
+ *
+ * Failures are events too — a "Payment failed" or "Out of stock" toast needs a
+ * signal as much as a success does, and wrapping every call in try/catch to find
+ * out is what this replaces. Errors still throw for callers that want them.
+ */
+export type ShopifyEventType = "cart:add" | "cart:update" | "cart:remove" | "cart:limitExceeded" | "cart:outOfStock" | "cart:buyerIdentity" | "wishlist:add" | "wishlist:remove" | "auth:loginSuccess" | "auth:loginFailed" | "auth:signup" | "auth:logout" | "auth:recoverSent" | "checkout:orderPlaced" | "checkout:paymentFailed";
+export interface ShopifyEvent {
+    type: ShopifyEventType;
+    /** How to present it — a toast tone, not a log level. */
+    severity: "success" | "error" | "info";
+    /**
+     * Resolved copy for this event, already through the Settings panel → i18n →
+     * default chain. Absent for the events that have no configurable message
+     * (`cart:update`, `cart:buyerIdentity`), which are state signals, not alerts.
+     */
+    message?: string;
+    /** Which panel field `message` came from, for hosts that key off it. */
+    messageKey?: AlertMessageKey;
+    /** Present on failures. `ShopifyError.errors` carries the Shopify codes. */
+    error?: unknown;
+}
+export interface ShopifyProviderProps {
+    children: ReactNode;
+    config: ShopifyConfig;
+    /**
+     * Backs the cart id, the customer session and the wishlist. Defaults to
+     * `window.localStorage`; React Native and Node consumers pass an
+     * AsyncStorage-compatible adapter.
+     */
+    storage?: WishlistStorageAdapter;
+    onEvent?: (event: ShopifyEvent) => void;
+    /** Vets cart writes — see `CartLineGuard`. On the provider so no screen can bypass it. */
+    cartGuard?: CartLineGuard;
+    /** See `WishlistInitOptions.keepDeleted`. Recommended for a shopper-facing wishlist. */
+    wishlistKeepDeleted?: boolean;
+    /**
+     * Alert copy, outside `config` so a Live Layer publish can change it without
+     * re-running `init` (which would re-load the shop and re-create the cart).
+     * Merged over `config.messages`; re-applied whenever this object changes.
+     */
+    messages?: AlertMessages;
+    /** i18n resolver for keys `messages` does not set. Same reason as above. */
+    translate?: MessageResolver;
+    /** Cart rules. Live-updatable for the same reason. */
+    cartPolicy?: CartPolicy;
+}
+export declare function ShopifyProvider({ children, config, storage, onEvent, cartGuard, wishlistKeepDeleted, messages, translate, cartPolicy, }: ShopifyProviderProps): import("react").JSX.Element;
+export declare function useShopify(): ShopifyContextType;
+export declare function useCart(): CartState;
+export declare function useWishlist(): WishlistState;
+/** Customer session — the source of the four Login alerts. */
+export declare function useCustomer(): CustomerState;
+/** Reports a hosted-checkout outcome so the two Checkout alerts can fire. */
+export declare function useCheckout(): CheckoutState;
+/**
+ * Resolved alert copy, for UI that isn't a toast — the empty-wishlist
+ * placeholder (`wishlist.empty`) is configurable but has no event.
+ */
+export declare function useShopifyMessage(): (key: AlertMessageKey) => string;
+export type { CartState, WishlistState, CustomerState, CheckoutState };
+//# sourceMappingURL=ShopifyProvider.d.ts.map

package/dist/react/ShopifyProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShopifyProvider.d.ts","sourceRoot":"","sources":["../../src/react/ShopifyProvider.tsx"],"names":[],"mappings":"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"}