@shopbb/helium 0.1.0

package/src/createStorefrontClient.ts

@@ -0,0 +1,164 @@
+/**
+ * createStorefrontClient
+ *
+ * A thin GraphQL client wrapper around fetch(), with caching.
+ *
+ * 行为对齐 Shopify Hydrogen 的 storefront client：
+ *   - query() 可缓存（CacheLong / CacheShort / etc.）
+ *   - mutate() 不缓存
+ *   - 自动注入 X-Storefront-Access-Token header
+ *   - GraphQL errors 非空时抛出
+ *
+ * 内部缓存策略：
+ *   - 用 caches.default 或传入的 cache 对象（Cache API）
+ *   - cache key = SHA256(query + variables + storeId)
+ *   - 命中 / SWR / MISS 模式区分
+ */
+
+import type {
+  StorefrontClient,
+  StorefrontClientOptions,
+  QueryOptions,
+  MutateOptions,
+  CacheStrategy,
+} from './types';
+import { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
+
+export function createStorefrontClient(options: StorefrontClientOptions): StorefrontClient {
+  const {
+    apiUrl,
+    publicAccessToken,
+    privateAccessToken,
+    storeId,
+    cache,
+    waitUntil,
+  } = options;
+
+  const headers = (): Record<string, string> => ({
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    'X-Storefront-Access-Token': privateAccessToken || publicAccessToken,
+    'X-Store-Id': storeId,
+  });
+
+  /**
+   * Compute a stable cache key for a query + variables.
+   */
+  async function cacheKeyFor(query: string, variables: any): Promise<Request> {
+    const payload = JSON.stringify({ q: query, v: variables ?? {}, s: storeId });
+    const hashBuf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(payload));
+    const hashHex = Array.from(new Uint8Array(hashBuf))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+    return new Request(`https://helium-cache.invalid/${storeId}/${hashHex}`, { method: 'GET' });
+  }
+
+  async function executeGraphQL<TData>(
+    query: string,
+    variables: any | undefined,
+  ): Promise<TData> {
+    const body = JSON.stringify({ query, variables });
+    const res = await fetch(apiUrl, {
+      method: 'POST',
+      headers: headers(),
+      body,
+    });
+    if (!res.ok) {
+      throw new Error(`Storefront API HTTP ${res.status}: ${await res.text()}`);
+    }
+    const json: any = await res.json();
+    if (json.errors && json.errors.length > 0) {
+      const messages = json.errors.map((e: any) => e.message).join('; ');
+      throw new Error(`Storefront GraphQL errors: ${messages}`);
+    }
+    return json.data as TData;
+  }
+
+  async function query<TData = any>(q: string, opts: QueryOptions = {}): Promise<TData> {
+    const cacheStrategy: CacheStrategy = opts.cache ?? CacheNone();
+
+    // No caching → direct call
+    if (cacheStrategy.mode === 'NONE' || !cache) {
+      return executeGraphQL<TData>(q, opts.variables);
+    }
+
+    const key = await cacheKeyFor(q, opts.variables);
+    const cached = await cache.match(key);
+    const now = Date.now();
+
+    if (cached) {
+      const ttl = Number(cached.headers.get('helium-ttl') ?? '0');
+      const cachedAt = Number(cached.headers.get('helium-cached-at') ?? '0');
+      const age = (now - cachedAt) / 1000;
+
+      if (age < ttl) {
+        // Fresh
+        return (await cached.json()) as TData;
+      }
+      // Stale, return stale-while-revalidate if configured
+      const swr = cacheStrategy.staleWhileRevalidate ?? 0;
+      if (age < ttl + swr) {
+        // Trigger background revalidation
+        if (waitUntil) {
+          waitUntil(refreshCache(q, opts.variables, key, cacheStrategy));
+        }
+        return (await cached.json()) as TData;
+      }
+      // Expired
+    }
+
+    const data = await executeGraphQL<TData>(q, opts.variables);
+    // Async write to cache
+    if (waitUntil) {
+      waitUntil(writeCache(key, data, cacheStrategy));
+    } else {
+      // Best-effort sync
+      await writeCache(key, data, cacheStrategy);
+    }
+    return data;
+  }
+
+  async function refreshCache(
+    q: string,
+    variables: any,
+    key: Request,
+    strategy: CacheStrategy,
+  ): Promise<void> {
+    try {
+      const data = await executeGraphQL(q, variables);
+      await writeCache(key, data, strategy);
+    } catch (e) {
+      // Swallow errors during background refresh
+      console.error('[helium] cache refresh failed', e);
+    }
+  }
+
+  async function writeCache(key: Request, data: any, strategy: CacheStrategy): Promise<void> {
+    if (!cache) return;
+    const ttl = strategy.maxAge;
+    const swr = strategy.staleWhileRevalidate ?? 0;
+    const totalAge = ttl + swr;
+    const resp = new Response(JSON.stringify(data), {
+      headers: {
+        'Content-Type': 'application/json',
+        'Cache-Control': `public, max-age=${totalAge}`,
+        'helium-ttl': String(ttl),
+        'helium-cached-at': String(Date.now()),
+      },
+    });
+    await cache.put(key, resp);
+  }
+
+  async function mutate<TData = any>(m: string, opts: MutateOptions = {}): Promise<TData> {
+    return executeGraphQL<TData>(m, opts.variables);
+  }
+
+  return {
+    query,
+    mutate,
+    CacheNone,
+    CacheShort,
+    CacheLong,
+    CacheCustom,
+  };
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * @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 type { CartSetIdOptions } from './cart-id';
+export { CacheNone, CacheShort, CacheLong, CacheCustom } from './cache';
+
+// Re-export all types
+export type {
+  CacheStrategy,
+  StorefrontClient,
+  StorefrontClientOptions,
+  QueryOptions,
+  MutateOptions,
+  CartHandler,
+  CartHandlerOptions,
+  CartLineInput,
+  CartLineUpdateInput,
+  CartUserError,
+  CartResult,
+  CartIdGetter,
+  CartIdSetter,
+  HeliumContext,
+  HeliumContextOptions,
+} from './types';

package/src/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Helium shared types.
+ *
+ * 这些类型在 storefront client / cart handler / context 之间共享。
+ * 对应 shopbb Storefront API GraphQL schema 的核心类型。
+ */
+
+// ============================================================
+// Cache
+// ============================================================
+
+export interface CacheStrategy {
+  mode: 'NONE' | 'PUBLIC';
+  /** CDN/edge cache TTL in seconds */
+  maxAge: number;
+  /** SWR window in seconds */
+  staleWhileRevalidate?: number;
+}
+
+// ============================================================
+// Storefront Client
+// ============================================================
+
+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;
+}
+
+// ============================================================
+// Cart
+// ============================================================
+
+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>>;
+}
+
+// ============================================================
+// Helium Context
+// ============================================================
+
+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;
+}