@shopbb/helium 0.1.0

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @shopbb/helium
+ *
+ * shopbb's storefront framework. Hydrogen-equivalent for the shopbb platform.
+ *
+ * Public API:
+ *
+ *   - createHeliumContext       Top-level factory
+ *   - createStorefrontClient    GraphQL client (used by createHeliumContext)
+ *   - createCartHandler         Cart operations (used by createHeliumContext)
+ *   - cartGetIdDefault          Default cart ID getter (reads cookie)
+ *   - cartSetIdDefault          Default cart ID setter (writes Set-Cookie)
+ *   - CacheNone / CacheShort / CacheLong / CacheCustom
+ */
+export { createHeliumContext } from './createHeliumContext';
+export { createStorefrontClient } from './createStorefrontClient';
+export { createCartHandler, DEFAULT_CART_FRAGMENT } from './createCartHandler';
+export { cartGetIdDefault, cartSetIdDefault } from './cart-id';
+export { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Helium shared types.
+ *
+ * 这些类型在 storefront client / cart handler / context 之间共享。
+ * 对应 shopbb Storefront API GraphQL schema 的核心类型。
+ */
+export interface CacheStrategy {
+    mode: 'NONE' | 'PUBLIC';
+    /** CDN/edge cache TTL in seconds */
+    maxAge: number;
+    /** SWR window in seconds */
+    staleWhileRevalidate?: number;
+}
+export interface StorefrontClientOptions {
+    /** GraphQL endpoint URL */
+    apiUrl: string;
+    /** Public Storefront API access token */
+    publicAccessToken: string;
+    /** Private Storefront API access token (preferred when available) */
+    privateAccessToken?: string;
+    /** Store ID */
+    storeId: string;
+    /** Original request, used to forward identifying headers if needed */
+    request?: Request;
+    /** Cache instance (e.g. caches.default or caches.open(...)) */
+    cache?: Cache;
+    /** waitUntil from ExecutionContext for SWR */
+    waitUntil?: (promise: Promise<any>) => void;
+}
+export interface QueryOptions {
+    variables?: Record<string, any>;
+    cache?: CacheStrategy;
+}
+export interface MutateOptions {
+    variables?: Record<string, any>;
+}
+export interface StorefrontClient {
+    query<TData = any>(query: string, options?: QueryOptions): Promise<TData>;
+    mutate<TData = any>(mutation: string, options?: MutateOptions): Promise<TData>;
+    CacheNone(): CacheStrategy;
+    CacheShort(): CacheStrategy;
+    CacheLong(): CacheStrategy;
+    CacheCustom(seconds: number): CacheStrategy;
+}
+export type CartIdGetter = () => string | null;
+export type CartIdSetter = (cartId: string, responseHeaders: Headers) => void;
+export interface CartHandlerOptions {
+    storefront: StorefrontClient;
+    getCartId: CartIdGetter;
+    /** setCartId 会写入 responseHeaders（注入 Set-Cookie） */
+    setCartId: CartIdSetter;
+    responseHeaders: Headers;
+}
+export interface CartLineInput {
+    merchandiseId: string;
+    quantity: number;
+}
+export interface CartLineUpdateInput {
+    id: string;
+    quantity: number;
+}
+export interface CartUserError {
+    field?: string[] | null;
+    message: string;
+    code?: string | null;
+}
+export interface CartResult<TCart = any> {
+    cart: TCart | null;
+    userErrors: CartUserError[];
+}
+export interface CartHandler<TCart = any> {
+    get(): Promise<TCart | null>;
+    getCartId(): string | null;
+    setCartId(cartId: string): void;
+    create(input?: {
+        lines?: CartLineInput[];
+    }): Promise<CartResult<TCart>>;
+    addLines(lines: CartLineInput[]): Promise<CartResult<TCart>>;
+    updateLines(lines: CartLineUpdateInput[]): Promise<CartResult<TCart>>;
+    removeLines(lineIds: string[]): Promise<CartResult<TCart>>;
+}
+export interface HeliumContextOptions {
+    request: Request;
+    env: Record<string, any>;
+    executionContext: ExecutionContext;
+    storefront: Omit<StorefrontClientOptions, 'request' | 'cache' | 'waitUntil'> & {
+        request?: Request;
+        cache?: Cache;
+        waitUntil?: (p: Promise<any>) => void;
+    };
+    cart?: {
+        getId: CartIdGetter;
+        setId: (cartId: string, headers: Headers) => void;
+        /** Optional custom GraphQL fragment for the Cart return type */
+        cartFragment?: string;
+    };
+}
+export interface HeliumContext {
+    env: Record<string, any>;
+    request: Request;
+    storefront: StorefrontClient;
+    cart: CartHandler;
+    /** Headers that should be merged into the outgoing response (e.g. Set-Cookie) */
+    responseHeaders: Headers;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Helium shared types.
+ *
+ * 这些类型在 storefront client / cart handler / context 之间共享。
+ * 对应 shopbb Storefront API GraphQL schema 的核心类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@shopbb/helium",
+  "version": "0.1.0",
+  "description": "shopbb storefront framework — GraphQL client, cart handler, and cache helpers for Cloudflare Workers",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "shopbb",
+    "storefront",
+    "ecommerce",
+    "cloudflare",
+    "workers",
+    "graphql"
+  ],
+  "repository": "https://github.com/shopbb/shopbb",
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20240117.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cache.ts

@@ -0,0 +1,31 @@
+/**
+ * Cache strategies.
+ *
+ * Use with storefront.query({ cache: CacheLong() }).
+ *
+ * Mirrors Shopify Hydrogen's cache strategies API.
+ */
+
+import type { CacheStrategy } from './types';
+
+export function CacheNone(): CacheStrategy {
+  return { mode: 'NONE', maxAge: 0 };
+}
+
+export function CacheShort(): CacheStrategy {
+  return { mode: 'PUBLIC', maxAge: 60, staleWhileRevalidate: 600 };
+}
+
+export function CacheLong(): CacheStrategy {
+  return { mode: 'PUBLIC', maxAge: 3600, staleWhileRevalidate: 82800 };
+}
+
+/**
+ * Custom cache TTL in seconds.
+ */
+export function CacheCustom(seconds: number): CacheStrategy {
+  return {
+    mode: seconds > 0 ? 'PUBLIC' : 'NONE',
+    maxAge: Math.max(0, seconds),
+  };
+}

package/src/cart-id.ts

@@ -0,0 +1,63 @@
+/**
+ * Cart ID helpers.
+ *
+ * Cookie name: "cart"
+ * - cartGetIdDefault: parse "cart=<id>" from request cookie
+ * - cartSetIdDefault: returns a function that appends Set-Cookie to response headers
+ *
+ * 命名/行为对齐 Shopify Hydrogen (`cartGetIdDefault` / `cartSetIdDefault`).
+ */
+
+import type { CartIdGetter, CartIdSetter } from './types';
+
+export interface CartSetIdOptions {
+  /** Cookie path (default '/') */
+  path?: string;
+  /** Cookie max-age in seconds (default 1 year) */
+  maxage?: number;
+  /** SameSite policy (default 'Lax') */
+  sameSite?: 'Lax' | 'Strict' | 'None';
+  /** Secure flag (default true) */
+  secure?: boolean;
+  /** HttpOnly flag (default true) */
+  httpOnly?: boolean;
+  /** Optional domain */
+  domain?: string;
+}
+
+const COOKIE_NAME = 'cart';
+
+/**
+ * Returns a getter that reads `cart=<id>` from request cookies.
+ */
+export function cartGetIdDefault(requestHeaders: Headers): CartIdGetter {
+  return () => {
+    const cookie = requestHeaders.get('cookie') || '';
+    const match = cookie.match(/(?:^|; )cart=([^;]+)/);
+    return match ? decodeURIComponent(match[1]) : null;
+  };
+}
+
+/**
+ * Returns a setter that appends `Set-Cookie: cart=<id>; ...` to response headers.
+ */
+export function cartSetIdDefault(options: CartSetIdOptions = {}): CartIdSetter {
+  const path = options.path ?? '/';
+  const maxage = options.maxage ?? 60 * 60 * 24 * 365;
+  const sameSite = options.sameSite ?? 'Lax';
+  const secure = options.secure !== false;
+  const httpOnly = options.httpOnly !== false;
+  const domainPart = options.domain ? `; Domain=${options.domain}` : '';
+
+  return (cartId: string, headers: Headers) => {
+    const cookie =
+      `${COOKIE_NAME}=${encodeURIComponent(cartId)}` +
+      `; Path=${path}` +
+      `; Max-Age=${maxage}` +
+      `; SameSite=${sameSite}` +
+      (secure ? '; Secure' : '') +
+      (httpOnly ? '; HttpOnly' : '') +
+      domainPart;
+    headers.append('Set-Cookie', cookie);
+  };
+}

package/src/createCartHandler.ts

@@ -0,0 +1,189 @@
+/**
+ * createCartHandler
+ *
+ * High-level cart API that wraps the storefront GraphQL mutations.
+ * Behavior aligned with Shopify Hydrogen:
+ *   - get(): returns null if no cart cookie or cart doesn't exist
+ *   - addLines(): if no cart exists, calls cartCreate first
+ *   - All mutations: auto setCookie when a new cart is created
+ *
+ * The handler operates on Cart GIDs internally; callers pass merchandiseIds
+ * (ProductVariant GIDs) and line IDs (cart line IDs).
+ */
+
+import type {
+  CartHandler,
+  CartHandlerOptions,
+  CartLineInput,
+  CartLineUpdateInput,
+  CartResult,
+} from './types';
+
+/** Default cart return fragment. Can be overridden by caller. */
+export const DEFAULT_CART_FRAGMENT = /* GraphQL */ `
+  fragment CartReturn on Cart {
+    id
+    createdAt
+    updatedAt
+    totalQuantity
+    cost {
+      subtotalAmount { amount currencyCode }
+      totalAmount { amount currencyCode }
+    }
+    lines(first: 50) {
+      nodes {
+        id
+        quantity
+        cost {
+          totalAmount { amount currencyCode }
+          amountPerQuantity { amount currencyCode }
+        }
+        merchandise {
+          ... on ProductVariant {
+            id
+            title
+            sku
+            availableForSale
+            price { amount currencyCode }
+            image { url altText }
+            product { id handle title }
+          }
+        }
+      }
+    }
+    checkoutUrl
+  }
+`;
+
+export function createCartHandler(options: CartHandlerOptions): CartHandler {
+  const { storefront, getCartId, setCartId: rawSetId, responseHeaders } = options;
+
+  // Set the cart ID (delegate to options.setCartId, which writes Set-Cookie)
+  function setCartId(cartId: string): void {
+    rawSetId(cartId, responseHeaders);
+  }
+
+  // ----- GraphQL operations -----
+
+  const CART_QUERY = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    query Cart($id: ID!) {
+      cart(id: $id) { ...CartReturn }
+    }
+  `;
+
+  const CART_CREATE = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartCreate($input: CartInput) {
+      cartCreate(input: $input) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
+  const CART_LINES_ADD = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
+      cartLinesAdd(cartId: $cartId, lines: $lines) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
+  const CART_LINES_UPDATE = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartLinesUpdate($cartId: ID!, $lines: [CartLineUpdateInput!]!) {
+      cartLinesUpdate(cartId: $cartId, lines: $lines) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
+  const CART_LINES_REMOVE = /* GraphQL */ `
+    ${DEFAULT_CART_FRAGMENT}
+    mutation CartLinesRemove($cartId: ID!, $lineIds: [ID!]!) {
+      cartLinesRemove(cartId: $cartId, lineIds: $lineIds) {
+        cart { ...CartReturn }
+        userErrors { field message code }
+      }
+    }
+  `;
+
+  // ----- Handler methods -----
+
+  async function get(): Promise<any | null> {
+    const cartId = getCartId();
+    if (!cartId) return null;
+    const data = await storefront.query<{ cart: any }>(CART_QUERY, {
+      variables: { id: cartId },
+      cache: storefront.CacheNone(),
+    });
+    return data.cart ?? null;
+  }
+
+  async function create(input?: { lines?: CartLineInput[] }): Promise<CartResult> {
+    const data = await storefront.mutate<{ cartCreate: { cart: any; userErrors: any[] } }>(
+      CART_CREATE,
+      { variables: { input: input ?? {} } },
+    );
+    const result = data.cartCreate;
+    if (result.cart) setCartId(result.cart.id);
+    return { cart: result.cart, userErrors: result.userErrors };
+  }
+
+  async function addLines(lines: CartLineInput[]): Promise<CartResult> {
+    const cartId = getCartId();
+    if (!cartId) {
+      // No existing cart → create with these lines
+      return create({ lines });
+    }
+    const data = await storefront.mutate<{ cartLinesAdd: { cart: any; userErrors: any[] } }>(
+      CART_LINES_ADD,
+      { variables: { cartId, lines } },
+    );
+    return { cart: data.cartLinesAdd.cart, userErrors: data.cartLinesAdd.userErrors };
+  }
+
+  async function updateLines(lines: CartLineUpdateInput[]): Promise<CartResult> {
+    const cartId = getCartId();
+    if (!cartId) {
+      return {
+        cart: null,
+        userErrors: [{ message: 'No cart exists', code: 'NO_CART' }],
+      };
+    }
+    const data = await storefront.mutate<{ cartLinesUpdate: { cart: any; userErrors: any[] } }>(
+      CART_LINES_UPDATE,
+      { variables: { cartId, lines } },
+    );
+    return { cart: data.cartLinesUpdate.cart, userErrors: data.cartLinesUpdate.userErrors };
+  }
+
+  async function removeLines(lineIds: string[]): Promise<CartResult> {
+    const cartId = getCartId();
+    if (!cartId) {
+      return {
+        cart: null,
+        userErrors: [{ message: 'No cart exists', code: 'NO_CART' }],
+      };
+    }
+    const data = await storefront.mutate<{ cartLinesRemove: { cart: any; userErrors: any[] } }>(
+      CART_LINES_REMOVE,
+      { variables: { cartId, lineIds } },
+    );
+    return { cart: data.cartLinesRemove.cart, userErrors: data.cartLinesRemove.userErrors };
+  }
+
+  return {
+    get,
+    getCartId,
+    setCartId,
+    create,
+    addLines,
+    updateLines,
+    removeLines,
+  };
+}

package/src/createHeliumContext.ts

@@ -0,0 +1,72 @@
+/**
+ * createHeliumContext
+ *
+ * Entry-point factory that assembles a storefront client and a cart handler
+ * into a single context object that loaders/actions can consume.
+ *
+ * Usage:
+ *   const context = createHeliumContext({ request, env, executionContext,
+ *     storefront: { apiUrl, publicAccessToken, storeId },
+ *     cart: { getId: cartGetIdDefault(request.headers),
+ *             setId: cartSetIdDefault({ maxage: ... }) }
+ *   });
+ *
+ *   // Then:
+ *   const data = await context.storefront.query(QUERY);
+ *   const result = await context.cart.addLines([...]);
+ *
+ *   // When responding:
+ *   return new Response(html, { headers: context.responseHeaders });
+ */
+
+import type { HeliumContext, HeliumContextOptions } from './types';
+import { createStorefrontClient } from './createStorefrontClient';
+import { createCartHandler } from './createCartHandler';
+
+export function createHeliumContext(options: HeliumContextOptions): HeliumContext {
+  const { request, env, executionContext, storefront: storefrontOpts, cart: cartOpts } = options;
+
+  // Mutable headers that will be merged into the eventual response
+  // (used for Set-Cookie when cart cookie needs to be written).
+  const responseHeaders = new Headers();
+
+  // 1. Build storefront client
+  const storefront = createStorefrontClient({
+    apiUrl: storefrontOpts.apiUrl,
+    publicAccessToken: storefrontOpts.publicAccessToken,
+    privateAccessToken: storefrontOpts.privateAccessToken,
+    storeId: storefrontOpts.storeId,
+    request,
+    cache: storefrontOpts.cache,
+    waitUntil:
+      storefrontOpts.waitUntil ??
+      executionContext.waitUntil.bind(executionContext),
+  });
+
+  // 2. Build cart handler (if cart options provided)
+  let cart;
+  if (cartOpts) {
+    cart = createCartHandler({
+      storefront,
+      getCartId: cartOpts.getId,
+      setCartId: cartOpts.setId,
+      responseHeaders,
+    });
+  } else {
+    // No cart options provided → no-op cart handler
+    cart = createCartHandler({
+      storefront,
+      getCartId: () => null,
+      setCartId: () => {},
+      responseHeaders,
+    });
+  }
+
+  return {
+    env,
+    request,
+    storefront,
+    cart,
+    responseHeaders,
+  };
+}