@tiledev/sdk-shopify 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apptile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+# @apptile/sdk-shopify
+
+Type-safe Shopify Storefront API client. Zero deps beyond `fetch`.
+
+Works in any JavaScript runtime — Node, browsers, React Native, Cloudflare Workers, Deno, Bun.
+
+Optional React helpers (provider + hooks) ship under a subpath so you only pay for `react` if you use them.
+
+```bash
+npm i @apptile/sdk-shopify
+```
+
+## Pure SDK (framework-agnostic)
+
+```ts
+import { shopify } from '@apptile/sdk-shopify';
+
+await shopify.init({
+  storeDomain: 'my-store.myshopify.com',
+  storefrontAccessToken: '...',
+  apiVersion: '2024-10',
+});
+
+const { nodes: products } = await shopify.products.list({ first: 20 });
+const cart = await shopify.cart.create({ lines: [{ merchandiseId: 'gid://…', quantity: 1 }] });
+```
+
+## Surface
+
+| API | Methods |
+|---|---|
+| `shopify.products`    | `list`, `byHandle`, `byId`, `search`, `recommended` |
+| `shopify.collections` | `list`, `byHandle`, `products` |
+| `shopify.cart`        | `create`, `get`, `addLines`, `updateLines`, `removeLines`, `applyDiscountCodes`, `setBuyerIdentity`, `updateNote` |
+| `shopify.customer`    | `signup`, `login`, `logout`, `profile`, `updateProfile`, `recoverPassword`, `orders`, `orderById` |
+| `shopify.blogs`       | `list`, `byHandle`, `articles`, `articleByHandle` |
+| `shopify.wishlist`    | `init`, `add`, `remove`, `toggle`, `has`, `list`, `count`, `clear`, `refresh`, `onChange` |
+| `shopify.alerts`      | `message`, `setMessages`, `patchMessages`, `setPolicy` — see [Alerts & Toasts](#alerts--toasts) |
+
+### Cart note
+
+The shopper's order note — the free-text box on the cart, which the merchant reads beside the order. Distinct from cart *attributes*: attributes are the app's own bookkeeping, the note is content the shopper wrote.
+
+```ts
+const cart = await shopify.cart.updateNote(cartId, 'Leave at the back door');
+cart.note;                                           // 'Leave at the back door'
+(await shopify.cart.updateNote(cartId, null)).note;  // null — cleared
+```
+
+`cart.note` is `string | null` and never `''`. Shopify reports "no note" as an empty string, normalized here so there is one falsy value to test rather than two. Passing `null` clears it — on the wire that is `''`, because Shopify's `note` argument is `String!` and declaring the variable nullable is rejected outright.
+
+`cart.create()` takes no note; set it in a follow-up call once the cart exists.
+
+From React:
+
+```tsx
+const { cart, updateNote } = useCart();
+<TextInput
+  defaultValue={cart?.note ?? ''}
+  onBlur={e => updateNote(e.nativeEvent.text || null)}
+/>
+```
+
+The hook's `updateNote` is **not** debounced — a note is typed and then committed, so write it on blur or a Save, not per keystroke. It is serialized against the line writes (a note landing mid-`addLine` would be applied to a cart the provider is about to replace, and would vanish), no-ops when there is no cart yet, and emits no alert event.
+
+### Wishlist — local-storage backed
+
+Stores a lightweight snapshot per product to whatever storage you give it (browser: `localStorage` by default; RN: pass AsyncStorage; server: pass any in-memory shim). Hydrates the full `Product` via a batched Storefront `nodes(ids:)` query on init and on demand, chunking arbitrarily large lists.
+
+Deleted products (Storefront returns `null`) are pruned automatically. Pass `refresh({ keepDeleted: true })` to keep them with `product: null` for a "no longer available" UI.
+
+```ts
+await shopify.wishlist.init();          // rehydrates from storage, background-refreshes from API
+await shopify.wishlist.add(product);
+shopify.wishlist.has(product.id);       // O(1)
+await shopify.wishlist.toggle(product);
+shopify.wishlist.onChange(items => …);  // subscribe
+```
+
+## Optional React helper
+
+```ts
+import { ShopifyProvider, useShopify, useCart, useWishlist } from '@apptile/sdk-shopify/react';
+```
+
+Wrap your app once — one provider gives you SDK readiness + cart state + wishlist state:
+
+```tsx
+<ShopifyProvider config={{ storeDomain, storefrontAccessToken }}>
+  <App />
+</ShopifyProvider>
+```
+
+Storage is passed at the provider:
+
+```tsx
+// Web: defaults to window.localStorage — nothing to configure
+<ShopifyProvider config={...}>...</ShopifyProvider>
+
+// React Native / Node / anywhere without localStorage:
+import AsyncStorage from '@react-native-async-storage/async-storage';
+<ShopifyProvider config={...} storage={AsyncStorage}>...</ShopifyProvider>
+```
+
+Then read from the context:
+
+```tsx
+const { ready, error, cart, wishlist, customer, checkout } = useShopify();
+const { addLine, itemCount, cart } = useCart();
+const { items, count, toggle, has } = useWishlist();
+const { loggedIn, login, logout } = useCustomer();
+```
+
+`react` is an **optional** peer dep — install it only if you use the `/react` subpath.
+
+## Alerts & Toasts
+
+The editor's Settings panel configures the copy for 13 shopper-facing alerts. The
+SDK never renders anything — it resolves the right string and hands it to you on
+an event, so a screen can toast without keeping its own copy table or mapping
+Shopify error shapes to sentences.
+
+```tsx
+<ShopifyProvider
+  config={{ storeDomain, storefrontAccessToken }}
+  cartPolicy={{ maxLineItems: 25 }}
+  messages={{ 'cart.added': 'Added to bag' }}   // ← what the Settings panel writes
+  translate={(key, fallback) => i18n.t(key, fallback)}
+  onEvent={(e) => toast.show(e.message, { type: e.severity })}
+>
+```
+
+Every event carries the resolved copy, so that one-liner is the whole integration:
+
+| Event | Message key | Panel group |
+| --- | --- | --- |
+| `cart:add` | `cart.added` | Cart |
+| `cart:remove` | `cart.removed` | Cart |
+| `cart:limitExceeded` | `cart.limitExceeded` | Cart |
+| `cart:outOfStock` | `cart.outOfStock` | Checkout |
+| `wishlist:add` / `wishlist:remove` | `wishlist.added` / `wishlist.removed` | Wishlist |
+| `auth:loginSuccess` / `auth:loginFailed` | `auth.loginSuccess` / `auth.loginFailed` | Login |
+| `auth:logout` / `auth:recoverSent` | `auth.loggedOut` / `auth.resetLinkSent` | Login |
+| `checkout:orderPlaced` / `checkout:paymentFailed` | `checkout.orderPlaced` / `checkout.paymentFailed` | Checkout |
+
+`cart:update` and `cart:buyerIdentity` are state signals and carry no message.
+`wishlist.empty` has no event — read it directly for a placeholder:
+
+```tsx
+const message = useShopifyMessage();
+{count === 0 && <Text>{message('wishlist.empty')}</Text>}
+```
+
+Resolution order per key: `messages` prop → `config.messages` → `translate(key)`
+→ built-in default. A cleared panel field (empty string) falls through rather than
+rendering blank. `translate` is called with the i18n key where one exists
+(`cart.added` → `toast.added_to_cart`), otherwise the message key itself.
+
+### Cart line limit
+
+`cartPolicy.maxLineItems` is the panel's "Cart Line Item Maximum Limit". It counts
+**distinct lines, not units** — quantity 30 of one variant is one line — and is
+checked before the mutation, so a refusal costs no round trip:
+
+```tsx
+const result = await cart.addLine({ merchandiseId, quantity: 1 });
+if (!result.ok && result.reason === 'limit') { /* result.message is ready to show */ }
+```
+
+`reason` is `'guard'` (a `cartGuard` veto), `'limit'`, or `'no-cart'`. An
+unsellable line still throws — `cart:outOfStock` fires on the way out.
+
+> **Breaking from 0.1.x:** `addLine` used to return `boolean`. An object is always
+> truthy, so `if (await addLine(...))` no longer detects a refusal — read `.ok`.
+
+### Customer session
+
+`useCustomer()` owns the token so the Login alerts have somewhere to originate. It
+persists to the same storage as the cart and restores on mount; an expired token
+is dropped silently, because reopening the app is not a failed login.
+
+```tsx
+const { loggedIn, customer, login, logout, recoverPassword, restoring } = useCustomer();
+// `login` resolves false on bad credentials (and emits auth:loginFailed).
+// Anything else — network, store down — throws.
+```
+
+### Checkout
+
+Checkout is Shopify-hosted, so the SDK cannot see the outcome. Report it from the
+webview and the configured copy comes back on the event:
+
+```tsx
+const { reportOrderPlaced, reportPaymentFailed } = useCheckout();
+// reportOrderPlaced also resets the cart — the old one is spent.
+```
+
+> A `checkout.observe(url)` helper that classifies the return URL itself is the
+> next piece of work; this is the seam it will emit through.
+
+## Tile Credit
+
+Customer wallet + gift-card mint + one-shot apply to a Shopify cart.
+
+```ts
+import {shopify, centsToMoney} from '@apptile/sdk-shopify';
+
+// Configure once per signed-in customer (rebuild on logout / new customer).
+shopify.tileCredit.configure({
+  baseUrl: 'https://tile-credit-1097788179850.us-central1.run.app',
+  customerAccessToken,     // shcat_… or classic Storefront customer token
+  shopDomain: 'yourshop.myshopify.com',
+});
+
+const client = shopify.tileCredit.client()!;
+const wallet = await client.getWallet();
+console.log('balance:', centsToMoney(wallet.balanceCents));
+
+// Redeem 15.00 AND apply the minted gift card to the current cart in one call.
+const {redeemed, cart} = await shopify.tileCredit.redeemAndApplyToCart({
+  cartId,
+  amountCents: 1500,
+});
+```
+
+React hook:
+
+```tsx
+import {useTileCredit} from '@apptile/sdk-shopify/react';
+
+function WalletScreen() {
+  const {wallet, config, redeemAndApply, refresh, loading, error} = useTileCredit({
+    baseUrl: TILE_CREDIT_URL,
+    customerAccessToken: session.token,
+    shopDomain: SHOP_DOMAIN,
+  });
+  // …
+}
+```
+
+Full integration guide (idempotency, error taxonomy, recovery playbook)
+lives in the mobile app repo alongside the wallet screen — this SDK ships
+the client + types only. Every method rejects with a `TileCreditError`
+(`.code`: `'unauthorized' | 'insufficient_balance' | 'shopify_upstream'
+| 'network' | …`). Branch on `.code`, not `.message`.
+
+## Types
+
+```ts
+import type {
+  Product, ProductVariant, ProductOption,
+  Cart, CartLine, CartLineInput, CartLineUpdateInput,
+  Collection, Customer, Order, Blog, Article,
+  WishlistItem, WishlistStorageAdapter,
+  ShopifyConfig, ShopifyIntegration,
+  ShopifyError,
+  // Tile Credit
+  TileCreditConfig, TileCreditAPI,
+  TileCreditWallet, TileCreditLedgerEntry, TileCreditLedgerPage,
+  TileCreditIssuedGiftCard, TileCreditPublicConfig,
+  TileCreditRedeemInput, TileCreditRedeemResult,
+  TileCreditError, TileCreditErrorCode,
+  AppliedGiftCard,
+} from '@apptile/sdk-shopify';
+```
+
+## License
+
+MIT

package/dist/blogs.d.ts

@@ -0,0 +1,3 @@
+import type { ShopifyBlogsAPI } from './types';
+export declare const blogs: ShopifyBlogsAPI;
+//# sourceMappingURL=blogs.d.ts.map

package/dist/blogs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blogs.d.ts","sourceRoot":"","sources":["../src/blogs.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAMV,eAAe,EAChB,MAAM,SAAS,CAAC;AAsCjB,eAAO,MAAM,KAAK,EAAE,eA0CnB,CAAC"}

package/dist/blogs.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blogs = void 0;
+const client_1 = require("./client");
+const queries_1 = require("./queries");
+function normalizeArticle(a) {
+    var _a, _b, _c, _d, _e, _f;
+    return {
+        id: a.id,
+        handle: a.handle,
+        title: a.title,
+        content: a.content,
+        contentHtml: a.contentHtml,
+        excerpt: (_a = a.excerpt) !== null && _a !== void 0 ? _a : null,
+        excerptHtml: (_b = a.excerptHtml) !== null && _b !== void 0 ? _b : null,
+        publishedAt: a.publishedAt,
+        tags: (_c = a.tags) !== null && _c !== void 0 ? _c : [],
+        image: (_d = a.image) !== null && _d !== void 0 ? _d : null,
+        author: a.authorV2
+            ? {
+                name: a.authorV2.name,
+                email: (_e = a.authorV2.email) !== null && _e !== void 0 ? _e : null,
+                bio: (_f = a.authorV2.bio) !== null && _f !== void 0 ? _f : null,
+            }
+            : null,
+        blog: a.blog,
+    };
+}
+exports.blogs = {
+    async list(opts) {
+        var _a, _b;
+        const data = await (0, client_1.request)(queries_1.BLOGS_LIST_QUERY, {
+            first: (_a = opts === null || opts === void 0 ? void 0 : opts.first) !== null && _a !== void 0 ? _a : 20,
+            after: opts === null || opts === void 0 ? void 0 : opts.after,
+            query: opts === null || opts === void 0 ? void 0 : opts.query,
+            sortKey: opts === null || opts === void 0 ? void 0 : opts.sortKey,
+            reverse: (_b = opts === null || opts === void 0 ? void 0 : opts.reverse) !== null && _b !== void 0 ? _b : false,
+        });
+        return data.blogs;
+    },
+    async byHandle(handle) {
+        const data = await (0, client_1.request)(queries_1.BLOG_BY_HANDLE_QUERY, { handle });
+        return data.blog;
+    },
+    async articles(blogHandle, opts) {
+        var _a, _b;
+        const data = await (0, client_1.request)(queries_1.BLOG_ARTICLES_QUERY, {
+            handle: blogHandle,
+            first: (_a = opts === null || opts === void 0 ? void 0 : opts.first) !== null && _a !== void 0 ? _a : 20,
+            after: opts === null || opts === void 0 ? void 0 : opts.after,
+            sortKey: opts === null || opts === void 0 ? void 0 : opts.sortKey,
+            reverse: (_b = opts === null || opts === void 0 ? void 0 : opts.reverse) !== null && _b !== void 0 ? _b : false,
+        });
+        if (!data.blog) {
+            return { nodes: [], pageInfo: { hasNextPage: false, hasPreviousPage: false, startCursor: null, endCursor: null } };
+        }
+        return {
+            nodes: data.blog.articles.nodes.map(normalizeArticle),
+            pageInfo: data.blog.articles.pageInfo,
+        };
+    },
+    async articleByHandle(blogHandle, articleHandle) {
+        const data = await (0, client_1.request)(queries_1.BLOG_ARTICLE_BY_HANDLE_QUERY, {
+            blogHandle,
+            articleHandle,
+        });
+        if (!data.blog || !data.blog.articleByHandle)
+            return null;
+        return normalizeArticle(data.blog.articleByHandle);
+    },
+};
+//# sourceMappingURL=blogs.js.map

package/dist/blogs.js.map

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

package/dist/cart.d.ts

@@ -0,0 +1,3 @@
+import type { ShopifyCartAPI } from './types';
+export declare const cart: ShopifyCartAPI;
+//# sourceMappingURL=cart.d.ts.map

package/dist/cart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../src/cart.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAIV,cAAc,EAEf,MAAM,SAAS,CAAC;AAiCjB,eAAO,MAAM,IAAI,EAAE,cAyElB,CAAC"}

package/dist/cart.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cart = void 0;
+const client_1 = require("./client");
+const queries_1 = require("./queries");
+function normalize(c) {
+    var _a, _b, _c, _d;
+    return {
+        id: c.id,
+        checkoutUrl: c.checkoutUrl,
+        totalQuantity: c.totalQuantity,
+        lines: ((_b = (_a = c.lines) === null || _a === void 0 ? void 0 : _a.nodes) !== null && _b !== void 0 ? _b : []).map((line) => {
+            var _a, _b, _c;
+            return ({
+                id: line.id,
+                quantity: line.quantity,
+                attributes: (_a = line.attributes) !== null && _a !== void 0 ? _a : [],
+                merchandise: line.merchandise,
+                product: (_c = (_b = line.merchandise) === null || _b === void 0 ? void 0 : _b.product) !== null && _c !== void 0 ? _c : null,
+                cost: line.cost,
+            });
+        }),
+        cost: c.cost,
+        discountCodes: (_c = c.discountCodes) !== null && _c !== void 0 ? _c : [],
+        appliedGiftCards: (_d = c.appliedGiftCards) !== null && _d !== void 0 ? _d : [],
+        createdAt: c.createdAt,
+        updatedAt: c.updatedAt,
+    };
+}
+exports.cart = {
+    async create(input) {
+        const payload = {
+            lines: input === null || input === void 0 ? void 0 : input.lines,
+            discountCodes: input === null || input === void 0 ? void 0 : input.discountCodes,
+        };
+        const data = await (0, client_1.request)(queries_1.CART_CREATE_MUTATION, { input: payload });
+        (0, client_1.assertNoUserErrors)('cartCreate', data.cartCreate.userErrors);
+        return normalize(data.cartCreate.cart);
+    },
+    async get(cartId) {
+        const data = await (0, client_1.request)(queries_1.CART_GET_QUERY, { id: cartId });
+        return data.cart ? normalize(data.cart) : null;
+    },
+    async addLines(cartId, lines) {
+        const data = await (0, client_1.request)(queries_1.CART_LINES_ADD_MUTATION, { cartId, lines });
+        (0, client_1.assertNoUserErrors)('cartLinesAdd', data.cartLinesAdd.userErrors);
+        return normalize(data.cartLinesAdd.cart);
+    },
+    async updateLines(cartId, lines) {
+        const data = await (0, client_1.request)(queries_1.CART_LINES_UPDATE_MUTATION, { cartId, lines });
+        (0, client_1.assertNoUserErrors)('cartLinesUpdate', data.cartLinesUpdate.userErrors);
+        return normalize(data.cartLinesUpdate.cart);
+    },
+    async removeLines(cartId, lineIds) {
+        const data = await (0, client_1.request)(queries_1.CART_LINES_REMOVE_MUTATION, { cartId, lineIds });
+        (0, client_1.assertNoUserErrors)('cartLinesRemove', data.cartLinesRemove.userErrors);
+        return normalize(data.cartLinesRemove.cart);
+    },
+    async applyDiscountCodes(cartId, codes) {
+        const data = await (0, client_1.request)(queries_1.CART_DISCOUNT_CODES_UPDATE_MUTATION, {
+            cartId,
+            discountCodes: codes,
+        });
+        (0, client_1.assertNoUserErrors)('cartDiscountCodesUpdate', data.cartDiscountCodesUpdate.userErrors);
+        return normalize(data.cartDiscountCodesUpdate.cart);
+    },
+    async setBuyerIdentity(cartId, identity) {
+        const data = await (0, client_1.request)(queries_1.CART_BUYER_IDENTITY_UPDATE_MUTATION, {
+            cartId,
+            buyerIdentity: {
+                email: identity.email,
+                countryCode: identity.countryCode,
+                customerAccessToken: identity.customerAccessToken,
+            },
+        });
+        (0, client_1.assertNoUserErrors)('cartBuyerIdentityUpdate', data.cartBuyerIdentityUpdate.userErrors);
+        return normalize(data.cartBuyerIdentityUpdate.cart);
+    },
+    async applyGiftCardCodes(cartId, codes) {
+        const data = await (0, client_1.request)(queries_1.CART_GIFT_CARD_CODES_UPDATE_MUTATION, {
+            cartId,
+            giftCardCodes: codes,
+        });
+        (0, client_1.assertNoUserErrors)('cartGiftCardCodesUpdate', data.cartGiftCardCodesUpdate.userErrors);
+        return normalize(data.cartGiftCardCodesUpdate.cart);
+    },
+    async removeGiftCardCodes(cartId, appliedGiftCardIds) {
+        const data = await (0, client_1.request)(queries_1.CART_GIFT_CARD_CODES_REMOVE_MUTATION, {
+            cartId,
+            appliedGiftCardIds,
+        });
+        (0, client_1.assertNoUserErrors)('cartGiftCardCodesRemove', data.cartGiftCardCodesRemove.userErrors);
+        return normalize(data.cartGiftCardCodesRemove.cart);
+    },
+};
+//# sourceMappingURL=cart.js.map

package/dist/cart.js.map

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

package/dist/cartPolicy.d.ts

@@ -0,0 +1,15 @@
+import type { Cart, CartLineInput, CartPolicy } from './types';
+export declare function setCartPolicy(policy?: CartPolicy | null): void;
+export declare function getCartPolicy(): CartPolicy;
+/** Normalised limit, or `null` for "no limit" — including a garbage config
+ *  value, which must not silently block every add. */
+export declare function maxLineItems(): number | null;
+/** How many distinct lines the cart would hold once `inputs` are added. */
+export declare function projectedLineCount(cart: Cart | null, inputs: CartLineInput[]): number;
+/**
+ * True when adding `inputs` would push the cart past `maxLineItems`. Checked
+ * before the mutation so a refusal costs no round trip — and so the shopper
+ * sees the configured message instead of a Shopify error.
+ */
+export declare function wouldExceedLineLimit(cart: Cart | null, inputs: CartLineInput[]): boolean;
+//# sourceMappingURL=cartPolicy.d.ts.map

package/dist/cartPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cartPolicy.d.ts","sourceRoot":"","sources":["../src/cartPolicy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAQ/D,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI,CAE9D;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C;AAED;sDACsD;AACtD,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAI5C;AAqBD,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAarF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAIxF"}

package/dist/cartPolicy.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setCartPolicy = setCartPolicy;
+exports.getCartPolicy = getCartPolicy;
+exports.maxLineItems = maxLineItems;
+exports.projectedLineCount = projectedLineCount;
+exports.wouldExceedLineLimit = wouldExceedLineLimit;
+const state = { policy: {} };
+function setCartPolicy(policy) {
+    state.policy = policy ? { ...policy } : {};
+}
+function getCartPolicy() {
+    return { ...state.policy };
+}
+/** Normalised limit, or `null` for "no limit" — including a garbage config
+ *  value, which must not silently block every add. */
+function maxLineItems() {
+    const max = state.policy.maxLineItems;
+    if (typeof max !== 'number' || !Number.isFinite(max) || max <= 0)
+        return null;
+    return Math.floor(max);
+}
+/**
+ * The line an input would land on, if the cart already holds one.
+ *
+ * Shopify merges an add into an existing line only when the merchandise AND the
+ * line attributes match, so a per-add attribute opens a new line. Selling plans
+ * split lines too, but `CartLine` carries no `sellingPlanAllocation` today, so a
+ * subscription add can look like a merge into the one-off line — which counts
+ * one line low and makes the limit slightly lenient rather than falsely
+ * blocking a shopper.
+ */
+function mergesInto(cart, input) {
+    var _a;
+    const attrs = (_a = input.attributes) !== null && _a !== void 0 ? _a : [];
+    return cart.lines.some((line) => {
+        var _a;
+        if (((_a = line.merchandise) === null || _a === void 0 ? void 0 : _a.id) !== input.merchandiseId)
+            return false;
+        if (attrs.length !== line.attributes.length)
+            return false;
+        return attrs.every((a) => line.attributes.some((b) => b.key === a.key && b.value === a.value));
+    });
+}
+/** How many distinct lines the cart would hold once `inputs` are added. */
+function projectedLineCount(cart, inputs) {
+    var _a, _b;
+    let count = (_a = cart === null || cart === void 0 ? void 0 : cart.lines.length) !== null && _a !== void 0 ? _a : 0;
+    // Two inputs for the same new variant open one line between them, so track
+    // what this batch has already accounted for.
+    const opened = new Set();
+    for (const input of inputs) {
+        if (cart && mergesInto(cart, input))
+            continue;
+        const key = `${input.merchandiseId}|${JSON.stringify((_b = input.attributes) !== null && _b !== void 0 ? _b : [])}`;
+        if (opened.has(key))
+            continue;
+        opened.add(key);
+        count += 1;
+    }
+    return count;
+}
+/**
+ * True when adding `inputs` would push the cart past `maxLineItems`. Checked
+ * before the mutation so a refusal costs no round trip — and so the shopper
+ * sees the configured message instead of a Shopify error.
+ */
+function wouldExceedLineLimit(cart, inputs) {
+    const max = maxLineItems();
+    if (max === null)
+        return false;
+    return projectedLineCount(cart, inputs) > max;
+}
+//# sourceMappingURL=cartPolicy.js.map

package/dist/cartPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cartPolicy.js","sourceRoot":"","sources":["../src/cartPolicy.ts"],"names":[],"mappings":";;AAeA,sCAEC;AAED,sCAEC;AAID,oCAIC;AAsBD,gDAaC;AAOD,oDAIC;AA9DD,MAAM,KAAK,GAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAE1C,SAAgB,aAAa,CAAC,MAA0B;IACtD,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED,SAAgB,aAAa;IAC3B,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED;sDACsD;AACtD,SAAgB,YAAY;IAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,YAAY,CAAC;IACtC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9E,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,UAAU,CAAC,IAAU,EAAE,KAAoB;;IAClD,MAAM,KAAK,GAAG,MAAA,KAAK,CAAC,UAAU,mCAAI,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;;QAC9B,IAAI,CAAA,MAAA,IAAI,CAAC,WAAW,0CAAE,EAAE,MAAK,KAAK,CAAC,aAAa;YAAE,OAAO,KAAK,CAAC;QAC/D,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1D,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACjG,CAAC,CAAC,CAAC;AACL,CAAC;AAED,2EAA2E;AAC3E,SAAgB,kBAAkB,CAAC,IAAiB,EAAE,MAAuB;;IAC3E,IAAI,KAAK,GAAG,MAAA,IAAI,aAAJ,IAAI,uBAAJ,IAAI,CAAE,KAAK,CAAC,MAAM,mCAAI,CAAC,CAAC;IACpC,2EAA2E;IAC3E,6CAA6C;IAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,IAAI,IAAI,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC;YAAE,SAAS;QAC9C,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,aAAa,IAAI,IAAI,CAAC,SAAS,CAAC,MAAA,KAAK,CAAC,UAAU,mCAAI,EAAE,CAAC,EAAE,CAAC;QAC/E,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChB,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB,CAAC,IAAiB,EAAE,MAAuB;IAC7E,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,GAAG,CAAC;AAChD,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import { ShopifyConfig, UserError } from './types';
+export declare function setShopInfo(info: {
+    moneyFormat?: string | null;
+    currencyCode?: string | null;
+}): void;
+/** Null until the shop query resolves. */
+export declare function getMoneyFormat(): string | null;
+export declare function getCurrencyCode(): string | null;
+export declare function setConfig(config: ShopifyConfig): void;
+export declare function getConfig(): ShopifyConfig;
+export declare function isConfigured(): boolean;
+export declare function request<T>(operation: string, variables?: Record<string, unknown>): Promise<T>;
+/** Throws if a Shopify mutation payload contains userErrors. */
+export declare function assertNoUserErrors(label: string, errors: UserError[] | null | undefined): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgB,SAAS,EAAE,MAAM,SAAS,CAAC;AAWjE,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAGrG;AAED,0CAA0C;AAC1C,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAE/C;AAID,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAIrD;AAED,wBAAgB,SAAS,IAAI,aAAa,CAGzC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AA4DD,wBAAsB,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAgCnG;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAO9F"}