@umxr/bagsy 0.0.0-stage → 0.1.0

package/dist/client-2LxFO18p.d.ts

@@ -0,0 +1,309 @@
+import { B as BagsyOptions, c as components, L as ListRef, P as PageOptions, b as ProductRef, I as ItemOptions, V as VariantRef, S as SavedLookup, O as Owner } from './types-C1ZgQf5w.js';
+
+/**
+ * The Bagsy client. Every method is a thin wrapper over a standalone function
+ * in `operations` — use those directly if you want only what you import.
+ */
+declare function createBagsy(options: BagsyOptions): {
+    lists: {
+        /** The owner's lists, default first. */
+        list: () => Promise<{
+            id: string;
+            name: string;
+            isDefault: boolean;
+            visibility: "private" | "shared";
+            itemCount: number;
+            shareToken?: string | null;
+            createdAt: string;
+            updatedAt: string;
+            items?: components["schemas"]["ItemPage"];
+        }[]>;
+        get: (listId?: ListRef, opts?: {
+            includeItems?: boolean;
+        }) => Promise<{
+            id: string;
+            name: string;
+            isDefault: boolean;
+            visibility: "private" | "shared";
+            itemCount: number;
+            shareToken?: string | null;
+            createdAt: string;
+            updatedAt: string;
+            items?: components["schemas"]["ItemPage"];
+        }>;
+        create: (name: string) => Promise<{
+            id: string;
+            name: string;
+            isDefault: boolean;
+            visibility: "private" | "shared";
+            itemCount: number;
+            shareToken?: string | null;
+            createdAt: string;
+            updatedAt: string;
+            items?: components["schemas"]["ItemPage"];
+        }>;
+        rename: (listId: ListRef, name: string) => Promise<{
+            id: string;
+            name: string;
+            isDefault: boolean;
+            visibility: "private" | "shared";
+            itemCount: number;
+            shareToken?: string | null;
+            createdAt: string;
+            updatedAt: string;
+            items?: components["schemas"]["ItemPage"];
+        }>;
+        delete: (listId: ListRef) => Promise<void>;
+        /** The list's share token, created on first share. `rotate: true` issues a new one. */
+        share: (listId?: ListRef, opts?: {
+            rotate?: boolean;
+        }) => Promise<string>;
+        unshare: (listId?: ListRef) => Promise<void>;
+    };
+    items: {
+        list: (listId?: ListRef, page?: PageOptions) => Promise<{
+            data: components["schemas"]["Item"][];
+            pageInfo: {
+                hasNextPage: boolean;
+                endCursor?: string | null;
+            };
+        }>;
+        /** Every item in a list, fetched page by page. */
+        iterate: (listId?: ListRef, opts?: {
+            limit?: number;
+        }) => AsyncGenerator<{
+            id: string;
+            listId: string;
+            productId: components["schemas"]["ProductGid"];
+            variantId?: components["schemas"]["VariantGid"] | null;
+            quantity: number;
+            note?: string | null;
+            addedAt: string;
+        }, any, any>;
+        /** Save a product. Saving it again returns the existing item. */
+        add: (product: ProductRef, opts?: ItemOptions & {
+            quantity?: number;
+            note?: string;
+        }) => Promise<{
+            id: string;
+            listId: string;
+            productId: components["schemas"]["ProductGid"];
+            variantId?: components["schemas"]["VariantGid"] | null;
+            quantity: number;
+            note?: string | null;
+            addedAt: string;
+        }>;
+        /** Save if unsaved, unsave if saved. Built for heart buttons. */
+        toggle: (product: ProductRef, opts?: ItemOptions) => Promise<{
+            saved: boolean;
+        }>;
+        update: (itemId: string, patch: {
+            variantId?: VariantRef | null;
+            quantity?: number;
+            note?: string | null;
+        }, opts?: {
+            listId?: ListRef;
+        }) => Promise<{
+            id: string;
+            listId: string;
+            productId: components["schemas"]["ProductGid"];
+            variantId?: components["schemas"]["VariantGid"] | null;
+            quantity: number;
+            note?: string | null;
+            addedAt: string;
+        }>;
+        remove: (itemId: string, opts?: {
+            listId?: ListRef;
+        }) => Promise<void>;
+        /** Unsave by product, without knowing the item id. No-op if not saved. */
+        removeProduct: (product: ProductRef, opts?: ItemOptions) => Promise<void>;
+    };
+    /**
+     * Saved state for a set of products across all of the owner's lists.
+     * Accepts any number of products; batches of 100 are fetched in parallel.
+     */
+    saved: (products: Iterable<ProductRef>) => Promise<SavedLookup>;
+    identity: {
+        /** Fold a guest's lists into the logged-in customer's. Safe to retry. */
+        merge: (visitorId?: string) => Promise<{
+            mergedItems: number;
+            lists: components["schemas"]["List"][];
+        }>;
+    };
+    shared: {
+        /** Public, read-only view of a shared list. */
+        get: (shareToken: string, page?: PageOptions) => Promise<{
+            list: {
+                name: string;
+                itemCount: number;
+            };
+            items: components["schemas"]["ItemPage"];
+        }>;
+    };
+    insights: {
+        /** Most-saved products. Server key only. */
+        topProducts: (query?: {
+            since?: Date | string;
+            limit?: number;
+        }) => Promise<{
+            productId: components["schemas"]["ProductGid"];
+            saves: number;
+        }[]>;
+    };
+    /**
+     * A copy of this client acting for a specific shopper. In Hydrogen, call
+     * once per request with the customer from your Customer Account session.
+     */
+    as(owner: Owner): {
+        lists: {
+            /** The owner's lists, default first. */
+            list: () => Promise<{
+                id: string;
+                name: string;
+                isDefault: boolean;
+                visibility: "private" | "shared";
+                itemCount: number;
+                shareToken?: string | null;
+                createdAt: string;
+                updatedAt: string;
+                items?: components["schemas"]["ItemPage"];
+            }[]>;
+            get: (listId?: ListRef, opts?: {
+                includeItems?: boolean;
+            }) => Promise<{
+                id: string;
+                name: string;
+                isDefault: boolean;
+                visibility: "private" | "shared";
+                itemCount: number;
+                shareToken?: string | null;
+                createdAt: string;
+                updatedAt: string;
+                items?: components["schemas"]["ItemPage"];
+            }>;
+            create: (name: string) => Promise<{
+                id: string;
+                name: string;
+                isDefault: boolean;
+                visibility: "private" | "shared";
+                itemCount: number;
+                shareToken?: string | null;
+                createdAt: string;
+                updatedAt: string;
+                items?: components["schemas"]["ItemPage"];
+            }>;
+            rename: (listId: ListRef, name: string) => Promise<{
+                id: string;
+                name: string;
+                isDefault: boolean;
+                visibility: "private" | "shared";
+                itemCount: number;
+                shareToken?: string | null;
+                createdAt: string;
+                updatedAt: string;
+                items?: components["schemas"]["ItemPage"];
+            }>;
+            delete: (listId: ListRef) => Promise<void>;
+            /** The list's share token, created on first share. `rotate: true` issues a new one. */
+            share: (listId?: ListRef, opts?: {
+                rotate?: boolean;
+            }) => Promise<string>;
+            unshare: (listId?: ListRef) => Promise<void>;
+        };
+        items: {
+            list: (listId?: ListRef, page?: PageOptions) => Promise<{
+                data: components["schemas"]["Item"][];
+                pageInfo: {
+                    hasNextPage: boolean;
+                    endCursor?: string | null;
+                };
+            }>;
+            /** Every item in a list, fetched page by page. */
+            iterate: (listId?: ListRef, opts?: {
+                limit?: number;
+            }) => AsyncGenerator<{
+                id: string;
+                listId: string;
+                productId: components["schemas"]["ProductGid"];
+                variantId?: components["schemas"]["VariantGid"] | null;
+                quantity: number;
+                note?: string | null;
+                addedAt: string;
+            }, any, any>;
+            /** Save a product. Saving it again returns the existing item. */
+            add: (product: ProductRef, opts?: ItemOptions & {
+                quantity?: number;
+                note?: string;
+            }) => Promise<{
+                id: string;
+                listId: string;
+                productId: components["schemas"]["ProductGid"];
+                variantId?: components["schemas"]["VariantGid"] | null;
+                quantity: number;
+                note?: string | null;
+                addedAt: string;
+            }>;
+            /** Save if unsaved, unsave if saved. Built for heart buttons. */
+            toggle: (product: ProductRef, opts?: ItemOptions) => Promise<{
+                saved: boolean;
+            }>;
+            update: (itemId: string, patch: {
+                variantId?: VariantRef | null;
+                quantity?: number;
+                note?: string | null;
+            }, opts?: {
+                listId?: ListRef;
+            }) => Promise<{
+                id: string;
+                listId: string;
+                productId: components["schemas"]["ProductGid"];
+                variantId?: components["schemas"]["VariantGid"] | null;
+                quantity: number;
+                note?: string | null;
+                addedAt: string;
+            }>;
+            remove: (itemId: string, opts?: {
+                listId?: ListRef;
+            }) => Promise<void>;
+            /** Unsave by product, without knowing the item id. No-op if not saved. */
+            removeProduct: (product: ProductRef, opts?: ItemOptions) => Promise<void>;
+        };
+        /**
+         * Saved state for a set of products across all of the owner's lists.
+         * Accepts any number of products; batches of 100 are fetched in parallel.
+         */
+        saved: (products: Iterable<ProductRef>) => Promise<SavedLookup>;
+        identity: {
+            /** Fold a guest's lists into the logged-in customer's. Safe to retry. */
+            merge: (visitorId?: string) => Promise<{
+                mergedItems: number;
+                lists: components["schemas"]["List"][];
+            }>;
+        };
+        shared: {
+            /** Public, read-only view of a shared list. */
+            get: (shareToken: string, page?: PageOptions) => Promise<{
+                list: {
+                    name: string;
+                    itemCount: number;
+                };
+                items: components["schemas"]["ItemPage"];
+            }>;
+        };
+        insights: {
+            /** Most-saved products. Server key only. */
+            topProducts: (query?: {
+                since?: Date | string;
+                limit?: number;
+            }) => Promise<{
+                productId: components["schemas"]["ProductGid"];
+                saves: number;
+            }[]>;
+        };
+        as(owner: Owner): /*elided*/ any;
+    };
+};
+type Bagsy = ReturnType<typeof createBagsy>;
+
+export { createBagsy as c };
+export type { Bagsy as B };

package/dist/element.d.ts

@@ -0,0 +1,170 @@
+import { components } from './index.js';
+import { Transport } from './index.js';
+
+/**
+ * `<bagsy-button product-id="123">` — a save/unsave toggle.
+ *
+ * Attributes: `product-id` (required, numeric or GID), `variant-id` (save a
+ * specific variant), `variant-source` (follow the selected variant in the
+ * product form on the page), `label` / `label-saved` (text, also used as the
+ * accessible name), `icon-only`. Reflects `saved` for styling.
+ * Default look: `@umxr/bagsy/styles.css`. Style with `--bagsy-accent`,
+ * `--bagsy-color`, `--bagsy-background`, `--bagsy-border`, `--bagsy-radius`,
+ * `--bagsy-padding`, or `bagsy-button::part(button | icon | label)`.
+ * Put your own markup inside to replace the default icon and label.
+ */
+declare class BagsyButton extends HTMLElement {
+    static observedAttributes: string[];
+    private button;
+    private label;
+    private unwatch?;
+    private busy;
+    private onVariantChange;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Follow the selected variant in the product form, preferring this section's form. */
+    private syncVariant;
+    attributeChangedCallback(name: string, previous: string | null, next: string | null): void;
+    get productId(): string;
+    get variantId(): string | undefined;
+    private subscribe;
+    private render;
+    private onClick;
+}
+
+/**
+ * `<bagsy-count>` — how many items are in the shopper's wishlist, e.g. for a
+ * header link. Renders plain text so it inherits theme styles. Add
+ * `hide-empty` to hide it at zero.
+ */
+declare class BagsyCount extends HTMLElement {
+    private onCount;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private render;
+}
+
+type Image = {
+    url: string;
+    altText: string | null;
+    width: number | null;
+    height: number | null;
+} | null;
+type Money = {
+    amount: string;
+    currencyCode: string;
+};
+/** One card: a saved product, or a saved variant of one. */
+interface Card {
+    productId: string;
+    variantId?: string;
+    title: string;
+    variantTitle?: string;
+    handle: string;
+    available: boolean;
+    image: Image;
+    price: Money;
+}
+/**
+ * `<bagsy-wishlist>`: the shopper's saved products as a grid of cards, or a
+ * shared list when the URL has `?bagsy_share=<token>`.
+ *
+ * Product data comes live from the store's Storefront API (tokenless, same
+ * origin), so titles, prices and availability match the shopper's market.
+ * Attributes: `country`, `language`, `share` (show share controls),
+ * `empty-text`, `remove-label`, `save-label`, `saved-label`, `sold-out-label`,
+ * `share-label`, `unshare-label`, `copied-label`, `unshared-label`,
+ * `shared-heading`, `shared-missing-text`. Renders light DOM with
+ * `bagsy-wishlist__*` classes, styled by `@umxr/bagsy/styles.css`.
+ */
+declare class BagsyWishlist extends HTMLElement {
+    private shared;
+    private onChange;
+    private text;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private loadOwn;
+    private loadShared;
+    /** Saved items → live cards, in saved order. Deleted or unpublished products drop out. */
+    cards(items: {
+        productId: string;
+        variantId?: string | null;
+    }[]): Promise<Card[]>;
+    private shareControls;
+    private actionButton;
+    private message;
+    private renderEmpty;
+    private grid;
+}
+
+interface BagsyConfig {
+    /** Shopify `routes.root_url`, e.g. `/` or `/en-gb`. */
+    root?: string;
+    /** Whether Shopify has a logged-in customer for this page. */
+    customer?: boolean;
+    /** Override the proxy base URL entirely (tests, custom setups). */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+interface ChangeDetail {
+    productId: string;
+    variantId?: string;
+    saved: boolean;
+}
+type Listener = () => void;
+/**
+ * One per page: a single client, one batched `/saved` lookup for every button
+ * on the page, optimistic toggles, and the guest → customer merge on login.
+ */
+declare class BagsyStore extends EventTarget {
+    private config;
+    /** Use with any `@umxr/bagsy` operation, e.g. `listLists(Bagsy.transport)`. */
+    readonly transport: Transport;
+    private saved;
+    private pending;
+    private flush?;
+    private listeners;
+    /** Resolves once any pending guest merge has finished. */
+    readonly ready: Promise<void>;
+    count?: number;
+    /** Storefront root without a trailing slash: '' or '/en-gb'. */
+    readonly root: string;
+    constructor(config?: BagsyConfig);
+    /** Fold the pre-login guest list into the customer's, once. */
+    private mergeGuestIfNeeded;
+    /** Subscribe to a product's saved state; triggers a (batched) lookup. */
+    watch(productId: string, listener: Listener): () => void;
+    isSaved(productId: string, variantId?: string): boolean | undefined;
+    /** Optimistic: listeners see the new state immediately and revert on failure. */
+    toggle(productId: string, variantId?: string): Promise<boolean>;
+    /** Items in the default list, newest first. */
+    items(): AsyncGenerator<{
+        id: string;
+        listId: string;
+        productId: components["schemas"]["ProductGid"];
+        variantId?: components["schemas"]["VariantGid"] | null;
+        quantity: number;
+        note?: string | null;
+        addedAt: string;
+    }, void, any>;
+    private countRequest?;
+    /** Load the count once per page; later calls share the first request. */
+    ensureCount(): Promise<number>;
+    /** Number of items in the default list, for header badges. */
+    loadCount(): Promise<number>;
+    private adjustCount;
+    private queue;
+    private notify;
+    private emit;
+}
+/** The page's store, configured from the app embed's JSON on first use. */
+declare function getStore(): BagsyStore;
+/** Replace the page store (tests, or custom setups before elements connect). */
+declare function setStore(store: BagsyStore | undefined): void;
+
+/** Register the elements. Safe to call more than once. */
+declare function define(): void;
+
+export { BagsyButton, BagsyCount, BagsyStore, BagsyWishlist, define, getStore, setStore };
+export type { BagsyConfig, ChangeDetail };