@shopbb/helium 0.5.10 → 0.6.1

package/dist/csp/csp.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * createContentSecurityPolicy + NonceProvider + <Script> + useNonce()
+ *
+ * 对齐 Hydrogen 的 CSP 工具集：服务端生成一次性 nonce（base64 random），通过
+ * Content-Security-Policy 头要求所有 inline script 带这个 nonce 才能执行；
+ * React 组件 <Script nonce> 自动注入 nonce 属性。
+ *
+ * 服务端：
+ *   const { nonce, header, NonceProvider } = createContentSecurityPolicy();
+ *   response.headers.set('Content-Security-Policy', header);
+ *   return ReactDOMServer.renderToReadableStream(
+ *     <NonceProvider value={nonce}><App /></NonceProvider>
+ *   );
+ *
+ * 客户端 / 组件内：
+ *   const nonce = useNonce();
+ *   <script nonce={nonce} dangerouslySetInnerHTML={...} />
+ *   // 或者用 <Script>
+ *   <Script>{`window.foo=1`}</Script>
+ */
+import * as React from 'react';
+// ============================================================
+// Nonce context
+// ============================================================
+const NonceContext = React.createContext(null);
+export function NonceProvider({ value, children }) {
+    return _jsx(NonceContext.Provider, { value: value, children: children });
+}
+export function useNonce() {
+    const nonce = React.useContext(NonceContext);
+    return nonce || undefined;
+}
+export function Script(props) {
+    const nonce = useNonce();
+    return _jsx("script", { nonce: nonce, ...props });
+}
+function randomNonce() {
+    // Workers / 浏览器 / Node 都有 crypto.getRandomValues
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        const bytes = new Uint8Array(16);
+        crypto.getRandomValues(bytes);
+        let bin = '';
+        for (const b of bytes)
+            bin += String.fromCharCode(b);
+        return btoa(bin).replace(/[+/=]/g, '');
+    }
+    // fallback
+    return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2);
+}
+export function createContentSecurityPolicy(options = {}) {
+    const nonce = randomNonce();
+    const dirs = [];
+    dirs.push(`default-src ${(options.defaultSrc || ["'self'"]).join(' ')}`);
+    dirs.push(`script-src 'self' 'nonce-${nonce}' 'strict-dynamic' ${(options.scriptSrc || []).join(' ')}`.trim());
+    dirs.push(`style-src 'self' 'unsafe-inline' ${(options.styleSrc || []).join(' ')}`.trim());
+    dirs.push(`img-src 'self' data: blob: ${(options.imgSrc || []).join(' ')}`.trim());
+    if (options.connectSrc?.length)
+        dirs.push(`connect-src 'self' ${options.connectSrc.join(' ')}`);
+    if (options.fontSrc?.length)
+        dirs.push(`font-src 'self' ${options.fontSrc.join(' ')}`);
+    if (options.frameSrc?.length)
+        dirs.push(`frame-src ${options.frameSrc.join(' ')}`);
+    dirs.push(`base-uri 'self'`);
+    dirs.push(`form-action 'self'`);
+    return {
+        nonce,
+        header: dirs.join('; '),
+        headerName: options.reportOnly ? 'Content-Security-Policy-Report-Only' : 'Content-Security-Policy',
+        NonceProvider,
+    };
+}
+//# sourceMappingURL=csp.js.map

package/dist/csp/csp.js.map

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

package/dist/customer/createCustomerAccountClient.d.ts

@@ -0,0 +1,43 @@
+/**
+ * createCustomerAccountClient — 对齐 Hydrogen createCustomerAccountClient
+ *
+ * 给"买家账号"操作提供 GraphQL client + 简单 token 管理。
+ *
+ * Hydrogen 用 Customer Account API（OAuth + PKCE）；我们 shopbb 用简化的
+ * buyer JWT（service signed token），所以这里**不实现 OAuth login/logout**，
+ * 只提供 GraphQL query/mutate 和 isLoggedIn 检测。商家用 oxygen 提供的
+ * REST `/api/buyer/login` 完成登录，把 token 存进 localStorage。
+ *
+ * 用法（客户端）：
+ *
+ *   const customer = createCustomerAccountClient({
+ *     customerApiUrl: 'https://api.../customer/api/2026-04/graphql',
+ *     getAccessToken: () => localStorage.getItem('shopbb:buyer_token'),
+ *   });
+ *
+ *   const data = await customer.query(`{ customer { id email } }`);
+ *   await customer.mutate(`mutation { customerAddressCreate(...) { ... } }`);
+ *   const loggedIn = await customer.isLoggedIn();
+ *
+ * 与 Hydrogen 区别：
+ *   - getAccessToken 默认从 localStorage / cookie 取（商家可覆盖）
+ *   - 不带 OAuth redirect helper（commerce 简化）
+ *   - login / logout 由商家应用层负责（调 oxygen REST）
+ */
+export interface CustomerAccountClientOptions {
+    /** Customer GraphQL endpoint */
+    customerApiUrl: string;
+    /** Token 取法。不传时从 localStorage 取 'shopbb:buyer_token'。SSR 阶段可传 cookie 解析 */
+    getAccessToken?: () => string | null | Promise<string | null>;
+    /** 自定义 headers（如 store_id） */
+    extraHeaders?: Record<string, string>;
+}
+export interface CustomerAccountClient {
+    query<T = any>(query: string, variables?: Record<string, any>): Promise<T>;
+    mutate<T = any>(mutation: string, variables?: Record<string, any>): Promise<T>;
+    isLoggedIn(): Promise<boolean>;
+    getAccessToken(): Promise<string | null>;
+    getApiUrl(): string;
+}
+export declare function createCustomerAccountClient(options: CustomerAccountClientOptions): CustomerAccountClient;
+//# sourceMappingURL=createCustomerAccountClient.d.ts.map

package/dist/customer/createCustomerAccountClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCustomerAccountClient.d.ts","sourceRoot":"","sources":["../../src/customer/createCustomerAccountClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,4BAA4B;IAC3C,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC9D,8BAA8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/E,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,SAAS,IAAI,MAAM,CAAC;CACrB;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,qBAAqB,CA4CxG"}

package/dist/customer/createCustomerAccountClient.js

@@ -0,0 +1,68 @@
+/**
+ * createCustomerAccountClient — 对齐 Hydrogen createCustomerAccountClient
+ *
+ * 给"买家账号"操作提供 GraphQL client + 简单 token 管理。
+ *
+ * Hydrogen 用 Customer Account API（OAuth + PKCE）；我们 shopbb 用简化的
+ * buyer JWT（service signed token），所以这里**不实现 OAuth login/logout**，
+ * 只提供 GraphQL query/mutate 和 isLoggedIn 检测。商家用 oxygen 提供的
+ * REST `/api/buyer/login` 完成登录，把 token 存进 localStorage。
+ *
+ * 用法（客户端）：
+ *
+ *   const customer = createCustomerAccountClient({
+ *     customerApiUrl: 'https://api.../customer/api/2026-04/graphql',
+ *     getAccessToken: () => localStorage.getItem('shopbb:buyer_token'),
+ *   });
+ *
+ *   const data = await customer.query(`{ customer { id email } }`);
+ *   await customer.mutate(`mutation { customerAddressCreate(...) { ... } }`);
+ *   const loggedIn = await customer.isLoggedIn();
+ *
+ * 与 Hydrogen 区别：
+ *   - getAccessToken 默认从 localStorage / cookie 取（商家可覆盖）
+ *   - 不带 OAuth redirect helper（commerce 简化）
+ *   - login / logout 由商家应用层负责（调 oxygen REST）
+ */
+export function createCustomerAccountClient(options) {
+    const { customerApiUrl, getAccessToken: getter, extraHeaders } = options;
+    async function getAccessToken() {
+        if (getter)
+            return await getter();
+        if (typeof localStorage === 'undefined')
+            return null;
+        return localStorage.getItem('shopbb:buyer_token') || localStorage.getItem('shopflare:buyer_token');
+    }
+    async function call(body, variables) {
+        const token = await getAccessToken();
+        if (!token)
+            throw new Error('not authenticated');
+        const headers = {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${token}`,
+            ...(extraHeaders || {}),
+        };
+        const res = await fetch(customerApiUrl, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ query: body, variables }),
+        });
+        const json = await res.json().catch(() => null);
+        if (!res.ok || json?.errors?.length) {
+            throw new Error(json?.errors?.[0]?.message || `Customer API error: HTTP ${res.status}`);
+        }
+        return json.data;
+    }
+    async function isLoggedIn() {
+        const token = await getAccessToken();
+        return !!token;
+    }
+    return {
+        query: (q, v) => call(q, v),
+        mutate: (m, v) => call(m, v),
+        isLoggedIn,
+        getAccessToken,
+        getApiUrl: () => customerApiUrl,
+    };
+}
+//# sourceMappingURL=createCustomerAccountClient.js.map

package/dist/customer/createCustomerAccountClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCustomerAccountClient.js","sourceRoot":"","sources":["../../src/customer/createCustomerAccountClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAmBH,MAAM,UAAU,2BAA2B,CAAC,OAAqC;IAC/E,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC;IAEzE,KAAK,UAAU,cAAc;QAC3B,IAAI,MAAM;YAAE,OAAO,MAAM,MAAM,EAAE,CAAC;QAClC,IAAI,OAAO,YAAY,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC;QACrD,OAAO,YAAY,CAAC,OAAO,CAAC,oBAAoB,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACrG,CAAC;IAED,KAAK,UAAU,IAAI,CACjB,IAAY,EACZ,SAA+B;QAE/B,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;QACjD,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,eAAe,EAAE,UAAU,KAAK,EAAE;YAClC,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC;SACxB,CAAC;QACF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,cAAc,EAAE;YACtC,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;SACjD,CAAC,CAAC;QACH,MAAM,IAAI,GAAQ,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,4BAA4B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,IAAI,CAAC,IAAS,CAAC;IACxB,CAAC;IAED,KAAK,UAAU,UAAU;QACvB,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;QACrC,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IAED,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5B,UAAU;QACV,cAAc;QACd,SAAS,EAAE,GAAG,EAAE,CAAC,cAAc;KAChC,CAAC;AACJ,CAAC"}

package/dist/handleCartFormAction.d.ts

@@ -0,0 +1,39 @@
+/**
+ * handleCartFormAction
+ *
+ * 服务端统一处理 <CartForm> 提交的 helper。对齐 Hydrogen 的"单一 /cart route action"模式：
+ *
+ *   import { CartForm, handleCartFormAction } from '@shopbb/helium';
+ *
+ *   // shopflare server.tsx POST handler
+ *   if (url.pathname === '/cart' && request.method === 'POST') {
+ *     const ctx = createHeliumContext({ ... });
+ *     const response = await handleCartFormAction(request, ctx.cart, {
+ *       responseHeaders: ctx.responseHeaders,
+ *     });
+ *     return response;
+ *   }
+ *
+ * 行为：
+ *   1. 从 request.formData() 调 CartForm.getFormInput 解析出 { action, inputs }
+ *   2. switch(action) 分发到 cartHandler 对应方法
+ *   3. 返回 JSON Response，里面带 { cart, userErrors, errors? } 和 Set-Cookie header
+ *   4. 客户端 fetch 拿到这个 Response，调 CartProvider.applyCart 同步 state
+ *
+ * 也支持 progressive enhancement：JS 没加载时浏览器原生 form POST + 303 redirect 回 referrer。
+ * 通过 query param `?_progressive=1` 或检测 `Accept: text/html` 触发 303 模式。
+ */
+import type { CartHandler, CartResult } from './types';
+export interface HandleCartFormActionOptions {
+    /** 服务端构造的 responseHeaders（Set-Cookie 写在这里） */
+    responseHeaders?: Headers;
+    /** JS 未加载时浏览器原生 form POST → 303 redirect 到这个 URL（默认 Referer 或 /cart） */
+    redirectTo?: string;
+    /**
+     * 自定义 action 处理器（CartForm 支持 `Custom${string}` action）。
+     * 第二个参数是 cartHandler，可以组合调用。
+     */
+    customActions?: Record<string, (inputs: any, cart: CartHandler) => Promise<CartResult>>;
+}
+export declare function handleCartFormAction(request: Request, cart: CartHandler, options?: HandleCartFormActionOptions): Promise<Response>;
+//# sourceMappingURL=handleCartFormAction.d.ts.map

package/dist/handleCartFormAction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleCartFormAction.d.ts","sourceRoot":"","sources":["../src/handleCartFormAction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEvD,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;CACzF;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,QAAQ,CAAC,CA6EnB"}

package/dist/handleCartFormAction.js

@@ -0,0 +1,103 @@
+/**
+ * handleCartFormAction
+ *
+ * 服务端统一处理 <CartForm> 提交的 helper。对齐 Hydrogen 的"单一 /cart route action"模式：
+ *
+ *   import { CartForm, handleCartFormAction } from '@shopbb/helium';
+ *
+ *   // shopflare server.tsx POST handler
+ *   if (url.pathname === '/cart' && request.method === 'POST') {
+ *     const ctx = createHeliumContext({ ... });
+ *     const response = await handleCartFormAction(request, ctx.cart, {
+ *       responseHeaders: ctx.responseHeaders,
+ *     });
+ *     return response;
+ *   }
+ *
+ * 行为：
+ *   1. 从 request.formData() 调 CartForm.getFormInput 解析出 { action, inputs }
+ *   2. switch(action) 分发到 cartHandler 对应方法
+ *   3. 返回 JSON Response，里面带 { cart, userErrors, errors? } 和 Set-Cookie header
+ *   4. 客户端 fetch 拿到这个 Response，调 CartProvider.applyCart 同步 state
+ *
+ * 也支持 progressive enhancement：JS 没加载时浏览器原生 form POST + 303 redirect 回 referrer。
+ * 通过 query param `?_progressive=1` 或检测 `Accept: text/html` 触发 303 模式。
+ */
+import { CartForm } from './components/CartForm';
+export async function handleCartFormAction(request, cart, options = {}) {
+    const { responseHeaders, redirectTo, customActions } = options;
+    let formData;
+    try {
+        formData = await request.formData();
+    }
+    catch (e) {
+        return jsonResponse({ error: 'Invalid form data: ' + (e.message || e), userErrors: [] }, 400, responseHeaders);
+    }
+    let parsed;
+    try {
+        parsed = CartForm.getFormInput(formData);
+    }
+    catch (e) {
+        return jsonResponse({ error: e.message || String(e), userErrors: [] }, 400, responseHeaders);
+    }
+    let result;
+    try {
+        switch (parsed.action) {
+            case 'LinesAdd':
+                result = await cart.addLines(parsed.inputs.lines);
+                break;
+            case 'LinesUpdate':
+                result = await cart.updateLines(parsed.inputs.lines);
+                break;
+            case 'LinesRemove':
+                result = await cart.removeLines(parsed.inputs.lineIds);
+                break;
+            case 'DiscountCodesUpdate':
+                result = await cart.updateDiscountCodes(parsed.inputs.discountCodes || []);
+                break;
+            case 'Create':
+                result = await cart.create(parsed.inputs.input);
+                break;
+            default:
+                // shopbb-extension actions
+                if (parsed.action === 'CustomDiscountSelect') {
+                    result = await cart.selectDiscount(parsed.inputs.claimId);
+                    break;
+                }
+                if (parsed.action === 'CustomDiscountClear') {
+                    result = await cart.clearDiscount();
+                    break;
+                }
+                // 用户自定义
+                if (parsed.action.startsWith('Custom') && customActions && customActions[parsed.action]) {
+                    result = await customActions[parsed.action](parsed.inputs, cart);
+                    break;
+                }
+                return jsonResponse({ error: `Unknown CartForm action: "${parsed.action}"`, userErrors: [] }, 400, responseHeaders);
+        }
+    }
+    catch (e) {
+        return jsonResponse({ error: e.message || String(e), userErrors: [] }, 500, responseHeaders);
+    }
+    // 写入 Set-Cookie（如果 cart id 变化）
+    if (result.cart?.id && responseHeaders) {
+        cart.setCartId(result.cart.id);
+    }
+    // 浏览器原生 form POST（无 JS）→ 303 redirect 回 referrer
+    // 判定：只信 X-Helium-Fetch header（CartForm fetch 显式带）
+    // 没有该 header → 视为原生 form POST，必须用 303 让浏览器跳转（不然显示 raw JSON）
+    const isJsFetch = !!request.headers.get('X-Helium-Fetch');
+    if (!isJsFetch) {
+        const target = redirectTo || request.headers.get('Referer') || '/cart';
+        const headers = new Headers(responseHeaders || {});
+        headers.set('Location', target);
+        return new Response(null, { status: 303, headers });
+    }
+    return jsonResponse({ cart: result.cart, userErrors: result.userErrors }, 200, responseHeaders);
+}
+function jsonResponse(body, status, responseHeaders) {
+    const headers = new Headers(responseHeaders || {});
+    headers.set('Content-Type', 'application/json; charset=utf-8');
+    return new Response(JSON.stringify(body), { status, headers });
+}
+//# sourceMappingURL=handleCartFormAction.js.map

package/dist/handleCartFormAction.js.map

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

package/dist/index.d.ts

@@ -17,6 +17,24 @@ export { createStorefrontClient } from './createStorefrontClient';
 export { createCartHandler, DEFAULT_CART_FRAGMENT } from './createCartHandler';
 export { cartGetIdDefault, cartSetIdDefault } from './cart-id';
 export type { CartSetIdOptions } from './cart-id';
+export { handleCartFormAction } from './handleCartFormAction';
+export type { HandleCartFormActionOptions } from './handleCartFormAction';
 export { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
+export { createWithCache, InMemoryCache } from './cache/withCache';
+export type { WithCache, WithCacheOptions, CacheKey } from './cache/withCache';
+export { storefrontRedirect } from './routing/storefrontRedirect';
+export type { StorefrontRedirectOptions } from './routing/storefrontRedirect';
+export { getSeoMeta } from './seo/getSeoMeta';
+export type { SeoConfig, SeoResult } from './seo/getSeoMeta';
+export { createCustomerAccountClient } from './customer/createCustomerAccountClient';
+export type { CustomerAccountClient, CustomerAccountClientOptions } from './customer/createCustomerAccountClient';
+export { createContentSecurityPolicy, NonceProvider, useNonce, Script } from './csp/csp';
+export type { CspOptions, CspResult, NonceProviderProps, ScriptProps } from './csp/csp';
+export { getSitemap, getSitemapIndex } from './sitemap/sitemap';
+export type { SitemapResource, GetSitemapOptions, GetSitemapIndexOptions, } from './sitemap/sitemap';
+export { flattenConnection } from './utils/flattenConnection';
+export type { Connection } from './utils/flattenConnection';
+export { parseGid } from './utils/parseGid';
+export type { ParsedGid } from './utils/parseGid';
 export type { CacheStrategy, StorefrontClient, StorefrontClientOptions, QueryOptions, MutateOptions, CartHandler, CartHandlerOptions, CartLineInput, CartLineUpdateInput, CartUserError, CartResult, CartIdGetter, CartIdSetter, HeliumContext, HeliumContextOptions, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGxE,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,2BAA2B,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGxE,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,YAAY,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AACrF,YAAY,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AAClH,OAAO,EAAE,2BAA2B,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACzF,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxF,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EACV,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,GAC3D,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -16,5 +16,16 @@ export { createHeliumContext } from './createHeliumContext';
 export { createStorefrontClient } from './createStorefrontClient';
 export { createCartHandler, DEFAULT_CART_FRAGMENT } from './createCartHandler';
 export { cartGetIdDefault, cartSetIdDefault } from './cart-id';
+export { handleCartFormAction } from './handleCartFormAction';
 export { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
+// 服务端工具
+export { createWithCache, InMemoryCache } from './cache/withCache';
+export { storefrontRedirect } from './routing/storefrontRedirect';
+export { getSeoMeta } from './seo/getSeoMeta';
+export { createCustomerAccountClient } from './customer/createCustomerAccountClient';
+export { createContentSecurityPolicy, NonceProvider, useNonce, Script } from './csp/csp';
+export { getSitemap, getSitemapIndex } from './sitemap/sitemap';
+// 工具
+export { flattenConnection } from './utils/flattenConnection';
+export { parseGid } from './utils/parseGid';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAExE,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,2BAA2B,EAAE,MAAM,wCAAwC,CAAC;AAErF,OAAO,EAAE,2BAA2B,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKhE,KAAK;AACL,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/routing/storefrontRedirect.d.ts

@@ -0,0 +1,37 @@
+/**
+ * storefrontRedirect — 对齐 Hydrogen storefrontRedirect
+ *
+ * 商家从老平台搬过来时常有 URL 改写需求，Shopify 在 admin 里维护 redirects 表。
+ * 商家 storefront 收到 404 时，调用 `storefrontRedirect({request, storefront})`
+ * 查 oxygen 的 redirects 表，若有匹配 → 301 / 302 跳到新地址。
+ *
+ * 用法（在 404 catch handler 里）：
+ *
+ *   if (response.status === 404) {
+ *     const redirect = await storefrontRedirect({ request, storefront });
+ *     if (redirect) return redirect;
+ *   }
+ *   return notFound();
+ *
+ * 简化版当前实现：调用 oxygen REST `/api/redirects?path=...`，未来 oxygen 加这条
+ * endpoint。商家可以传 fetcher 自定义查询源。
+ */
+export interface StorefrontRedirectOptions {
+    /** 当前 Request，从 URL 取 path 查 redirect */
+    request: Request;
+    /** oxygen Storefront client（用于 GraphQL urlRedirects 查询）；或自定义 fetcher */
+    storefront?: {
+        query: (q: string, opts?: any) => Promise<any>;
+    };
+    /**
+     * 自定义查询 redirect：传入 path，返回目标 URL（找不到返回 null）。
+     * 优先级高于 storefront query。
+     */
+    resolveRedirect?: (path: string) => Promise<string | null>;
+    /** 重定向状态码：默认 301（永久） */
+    status?: 301 | 302 | 307 | 308;
+    /** 是否仅域内 path（避免 open redirect 攻击）。默认 true */
+    noExternal?: boolean;
+}
+export declare function storefrontRedirect(options: StorefrontRedirectOptions): Promise<Response | null>;
+//# sourceMappingURL=storefrontRedirect.d.ts.map

package/dist/routing/storefrontRedirect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storefrontRedirect.d.ts","sourceRoot":"","sources":["../../src/routing/storefrontRedirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,yBAAyB;IACxC,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,CAAC;IAChE;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D,wBAAwB;IACxB,MAAM,CAAC,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC/B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAUD,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAwC1B"}

package/dist/routing/storefrontRedirect.js

@@ -0,0 +1,64 @@
+/**
+ * storefrontRedirect — 对齐 Hydrogen storefrontRedirect
+ *
+ * 商家从老平台搬过来时常有 URL 改写需求，Shopify 在 admin 里维护 redirects 表。
+ * 商家 storefront 收到 404 时，调用 `storefrontRedirect({request, storefront})`
+ * 查 oxygen 的 redirects 表，若有匹配 → 301 / 302 跳到新地址。
+ *
+ * 用法（在 404 catch handler 里）：
+ *
+ *   if (response.status === 404) {
+ *     const redirect = await storefrontRedirect({ request, storefront });
+ *     if (redirect) return redirect;
+ *   }
+ *   return notFound();
+ *
+ * 简化版当前实现：调用 oxygen REST `/api/redirects?path=...`，未来 oxygen 加这条
+ * endpoint。商家可以传 fetcher 自定义查询源。
+ */
+const URL_REDIRECTS_QUERY = /* GraphQL */ `
+  query UrlRedirects($first: Int!, $query: String) {
+    urlRedirects(first: $first, query: $query) {
+      nodes { path target }
+    }
+  }
+`;
+export async function storefrontRedirect(options) {
+    const { request, storefront, resolveRedirect, status = 301, noExternal = true } = options;
+    const url = new URL(request.url);
+    const path = url.pathname + (url.search || '');
+    let target = null;
+    if (resolveRedirect) {
+        target = await resolveRedirect(path).catch(() => null);
+    }
+    else if (storefront) {
+        try {
+            const data = await storefront.query(URL_REDIRECTS_QUERY, { variables: { first: 1, query: `path:${path}` } });
+            const match = data?.urlRedirects?.nodes?.find((r) => r.path === path);
+            target = match?.target ?? null;
+        }
+        catch {
+            target = null;
+        }
+    }
+    if (!target)
+        return null;
+    if (noExternal) {
+        // 防 open redirect — 只允许相对路径或同域
+        if (target.startsWith('//') || /^https?:\/\//i.test(target)) {
+            try {
+                const t = new URL(target);
+                if (t.host !== url.host)
+                    return null;
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return new Response(null, {
+        status,
+        headers: { Location: target },
+    });
+}
+//# sourceMappingURL=storefrontRedirect.js.map

package/dist/routing/storefrontRedirect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storefrontRedirect.js","sourceRoot":"","sources":["../../src/routing/storefrontRedirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkBH,MAAM,mBAAmB,GAAG,aAAa,CAAC;;;;;;CAMzC,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAkC;IAElC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,GAAG,GAAG,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAC1F,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAE/C,IAAI,MAAM,GAAkB,IAAI,CAAC;IAEjC,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;SAAM,IAAI,UAAU,EAAE,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,IAAI,GAAQ,MAAM,UAAU,CAAC,KAAK,CACtC,mBAAmB,EACnB,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,QAAQ,IAAI,EAAE,EAAE,EAAE,CACnD,CAAC;YACF,MAAM,KAAK,GAAG,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;YAC3E,MAAM,GAAG,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC;QACjC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEzB,IAAI,UAAU,EAAE,CAAC;QACf,+BAA+B;QAC/B,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;gBAC1B,IAAI,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI;oBAAE,OAAO,IAAI,CAAC;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;QACxB,MAAM;QACN,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;KAC9B,CAAC,CAAC;AACL,CAAC"}

package/dist/seo/getSeoMeta.d.ts

@@ -0,0 +1,68 @@
+/**
+ * getSeoMeta + <Seo> — 对齐 Hydrogen 的 SEO 工具
+ *
+ * Hydrogen 通过 Remix `meta` export 返回 SeoConfig；我们这里因不绑 Remix，
+ * 提供一个 `getSeoMeta(config)` 函数返回 HTML `<meta>` 字符串，供 SSR
+ * 服务端拼到 `<head>` 里。也提供 `<Seo data={config} />` 客户端组件
+ * （hydrate 阶段更新 document title / meta），用作 SPA 路由切换。
+ *
+ * 用法（服务端）：
+ *
+ *   const seo = getSeoMeta({
+ *     title: product.title,
+ *     description: product.description,
+ *     image: product.featuredImage?.url,
+ *     url: 'https://shop/products/xxx',
+ *     type: 'product',
+ *   });
+ *   // seo = { title, htmlTags: '<title>...</title><meta ...>' }
+ *   const html = `<head>${seo.htmlTags}...</head>`;
+ */
+export interface SeoConfig {
+    /** Page title — appears in <title> and og:title */
+    title?: string;
+    /** Suffix appended to title with separator " · " — usually shop name */
+    titleTemplate?: string;
+    /** Meta description / og:description */
+    description?: string;
+    /** Canonical URL / og:url */
+    url?: string;
+    /** og:image */
+    image?: string | {
+        url: string;
+        width?: number;
+        height?: number;
+        altText?: string;
+    };
+    /** og:type — "website" | "product" | "article" | ... */
+    type?: 'website' | 'product' | 'article' | string;
+    /** twitter:card — "summary" | "summary_large_image" */
+    twitterCard?: 'summary' | 'summary_large_image' | string;
+    /** Additional og:* fields */
+    og?: Record<string, string>;
+    /** robots — "index,follow" / "noindex" */
+    robots?: string;
+    /** JSON-LD structured data */
+    jsonLd?: Record<string, any> | Array<Record<string, any>>;
+    /** lang — "zh-CN" / "en" */
+    language?: string;
+}
+export interface SeoResult {
+    title: string;
+    description: string;
+    /** 直接拼接到 <head> 的 HTML 字符串 */
+    htmlTags: string;
+    /** 关键 meta，方便商家自己拼 */
+    meta: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+    /** 完整 title（含 template） */
+    fullTitle: string;
+}
+/**
+ * 根据 config 生成 <head> 该有的全部 SEO 标签字符串。
+ */
+export declare function getSeoMeta(config: SeoConfig): SeoResult;
+//# sourceMappingURL=getSeoMeta.d.ts.map

package/dist/seo/getSeoMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSeoMeta.d.ts","sourceRoot":"","sources":["../../src/seo/getSeoMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe;IACf,KAAK,CAAC,EAAE,MAAM,GAAG;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpF,wDAAwD;IACxD,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAClD,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,GAAG,qBAAqB,GAAG,MAAM,CAAC;IACzD,6BAA6B;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1D,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,IAAI,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAQD;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CA0DvD"}