@shopbb/helium 0.5.10 → 0.6.1

package/src/sitemap/sitemap.ts

@@ -0,0 +1,121 @@
+/**
+ * getSitemap + getSitemapIndex — 对齐 Hydrogen
+ *
+ * 生成 XML sitemap，让搜索引擎能爬到商品 / 集合 / 页面。
+ *
+ * 用法（服务端 GET /sitemap.xml）：
+ *
+ *   const xml = await getSitemap({
+ *     storefront,
+ *     request,
+ *     types: ['products', 'collections', 'pages'],
+ *     getLink: ({ type, baseUrl, handle }) => `${baseUrl}/${type}/${handle}`,
+ *   });
+ *   return new Response(xml, { headers: { 'Content-Type': 'application/xml' } });
+ *
+ * 大店铺：一个 sitemap 装不下时分多个：
+ *
+ *   // GET /sitemap.xml
+ *   const indexXml = await getSitemapIndex({
+ *     baseUrl: 'https://shop',
+ *     sitemaps: ['products-1.xml', 'collections.xml'],
+ *   });
+ */
+
+export interface SitemapResource {
+  url: string;
+  lastmod?: string;
+  changefreq?: 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never' | 'always' | 'hourly';
+  priority?: number;
+}
+
+export interface GetSitemapOptions {
+  storefront: { query: (q: string, opts?: any) => Promise<any> };
+  request: Request;
+  /** 拉哪些类型 */
+  types: Array<'products' | 'collections' | 'pages' | 'articles' | 'blogs'>;
+  /** 每页最多多少（GraphQL connection pageSize），默认 250 */
+  pageSize?: number;
+  /** 自定义 link 构造：({type, baseUrl, handle}) => url。默认 baseUrl + /type + /handle */
+  getLink?: (args: { type: string; baseUrl: string; handle: string }) => string;
+  /** 强制 base URL（不传则从 request 推导） */
+  baseUrl?: string;
+}
+
+const Q_PRODUCTS = `query SitemapProducts($first:Int!,$after:String){products(first:$first,after:$after){edges{cursor node{handle updatedAt}} pageInfo{hasNextPage endCursor}}}`;
+const Q_COLLECTIONS = `query SitemapCollections($first:Int!,$after:String){collections(first:$first,after:$after){edges{cursor node{handle updatedAt}} pageInfo{hasNextPage endCursor}}}`;
+
+function escapeXml(s: string): string {
+  return s.replace(/[<>&'"]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;' }[c]!));
+}
+
+function urlEntry(r: SitemapResource): string {
+  const parts: string[] = [`<url>`, `  <loc>${escapeXml(r.url)}</loc>`];
+  if (r.lastmod) parts.push(`  <lastmod>${r.lastmod}</lastmod>`);
+  if (r.changefreq) parts.push(`  <changefreq>${r.changefreq}</changefreq>`);
+  if (r.priority != null) parts.push(`  <priority>${r.priority}</priority>`);
+  parts.push('</url>');
+  return parts.join('\n');
+}
+
+export async function getSitemap(options: GetSitemapOptions): Promise<string> {
+  const { storefront, request, types, pageSize = 250, getLink, baseUrl: baseUrlOverride } = options;
+  const url = new URL(request.url);
+  const baseUrl = (baseUrlOverride || `${url.protocol}//${url.host}`).replace(/\/$/, '');
+
+  const linker = getLink || (({ type, baseUrl, handle }) => `${baseUrl}/${type}/${handle}`);
+
+  const entries: SitemapResource[] = [];
+
+  for (const type of types) {
+    let cursor: string | null = null;
+    let hasNext = true;
+    const query = type === 'products' ? Q_PRODUCTS : type === 'collections' ? Q_COLLECTIONS : null;
+    if (!query) continue;
+    while (hasNext) {
+      const data: any = await storefront.query(query, { variables: { first: pageSize, after: cursor } });
+      const conn = (data as any)[type];
+      if (!conn) break;
+      for (const e of conn.edges) {
+        const node = e.node;
+        entries.push({
+          url: linker({ type, baseUrl, handle: node.handle }),
+          lastmod: node.updatedAt,
+          changefreq: 'daily',
+        });
+      }
+      hasNext = conn.pageInfo.hasNextPage;
+      cursor = conn.pageInfo.endCursor;
+      // safety break — 单次请求最多 50 page
+      if (entries.length > pageSize * 50) break;
+    }
+  }
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">`,
+    ...entries.map(urlEntry),
+    `</urlset>`,
+  ].join('\n');
+}
+
+export interface GetSitemapIndexOptions {
+  baseUrl: string;
+  sitemaps: string[];  // 子 sitemap 路径或完整 URL
+  lastmod?: string;
+}
+
+export function getSitemapIndex(options: GetSitemapIndexOptions): string {
+  const { baseUrl, sitemaps, lastmod } = options;
+  const base = baseUrl.replace(/\/$/, '');
+  const items = sitemaps.map((s) => {
+    const loc = /^https?:\/\//.test(s) ? s : `${base}/${s.replace(/^\//, '')}`;
+    return `<sitemap><loc>${escapeXml(loc)}</loc>${lastmod ? `<lastmod>${lastmod}</lastmod>` : ''}</sitemap>`;
+  });
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">`,
+    ...items,
+    `</sitemapindex>`,
+  ].join('\n');
+}

package/src/types.ts

@@ -96,10 +96,21 @@ export interface CartHandler<TCart = any> {
   get(): Promise<TCart | null>;
   getCartId(): string | null;
   setCartId(cartId: string): void;
-  create(input?: { lines?: CartLineInput[] }): Promise<CartResult<TCart>>;
+  create(input?: { lines?: CartLineInput[]; discountCodes?: string[] }): Promise<CartResult<TCart>>;
   addLines(lines: CartLineInput[]): Promise<CartResult<TCart>>;
   updateLines(lines: CartLineUpdateInput[]): Promise<CartResult<TCart>>;
   removeLines(lineIds: string[]): Promise<CartResult<TCart>>;
+  /** 替换 cart 上的优惠码列表（对齐 Hydrogen cart.updateDiscountCodes） */
+  updateDiscountCodes(discountCodes: string[]): Promise<CartResult<TCart>>;
+  /**
+   * shopbb-extension：买家从已领的 claim 中选一张（不是输入 code）。
+   * 服务端把 selected_claim_id 写到 cart DO；下次 resolveCart 时优先用该 claim。
+   *
+   * Hydrogen 没这个 API；这是 shopbb W5 的优惠券模型（claim-based）专属能力。
+   */
+  selectDiscount(claimId: string): Promise<CartResult<TCart>>;
+  /** 清掉显式选择，回到"服务端自动选最佳"模式 */
+  clearDiscount(): Promise<CartResult<TCart>>;
 }
 
 // ============================================================

package/src/utils/flattenConnection.ts

@@ -0,0 +1,33 @@
+/**
+ * flattenConnection — 对齐 Hydrogen React 同名工具
+ *
+ * GraphQL Connection 类型常见两种形态：
+ *   { edges: [{node: T}, ...] }
+ *   { nodes: [T, ...] }
+ *
+ * 此函数把两种统一拍平成 T[]，让消费方写法一致。
+ *
+ * 用法：
+ *   const products = flattenConnection(data.products);
+ *   products.forEach(p => ...);
+ */
+
+interface ConnectionWithEdges<T> {
+  edges: Array<{ node: T }>;
+}
+interface ConnectionWithNodes<T> {
+  nodes: T[];
+}
+
+export type Connection<T> = ConnectionWithEdges<T> | ConnectionWithNodes<T> | null | undefined;
+
+export function flattenConnection<T = any>(connection: Connection<T>): T[] {
+  if (!connection) return [];
+  if ('nodes' in connection && Array.isArray(connection.nodes)) {
+    return connection.nodes;
+  }
+  if ('edges' in connection && Array.isArray(connection.edges)) {
+    return connection.edges.map((e) => e.node);
+  }
+  return [];
+}

package/src/utils/parseGid.ts

@@ -0,0 +1,25 @@
+/**
+ * parseGid — 对齐 Hydrogen React 同名工具
+ *
+ * 把 GraphQL global ID 拆成 { id, resource }：
+ *   "gid://shopbb/Product/prod_123" → { id: "prod_123", resource: "Product" }
+ *   "gid://shopify/CartLine/abc"     → { id: "abc", resource: "CartLine" }
+ *
+ * 找不到合法格式 → 返回 { id: gid, resource: null }（保留原值，便于兜底渲染）
+ */
+
+export interface ParsedGid {
+  id: string;
+  resource: string | null;
+  /** 完整原始 gid，便于回填 */
+  raw: string;
+}
+
+const GID_PATTERN = /^gid:\/\/[^/]+\/([^/]+)\/(.+)$/;
+
+export function parseGid(gid: string | null | undefined): ParsedGid {
+  if (!gid) return { id: '', resource: null, raw: '' };
+  const m = gid.match(GID_PATTERN);
+  if (!m) return { id: gid, resource: null, raw: gid };
+  return { id: m[2], resource: m[1], raw: gid };
+}