@doswiftly/storefront-sdk 4.0.0

package/src/core/client/create-client.ts

@@ -0,0 +1,129 @@
+/**
+ * createStorefrontClient — transport factory (Hydrogen pattern).
+ *
+ * Creates a framework-agnostic GraphQL client with:
+ * - Middleware pipeline (composable, lazy)
+ * - Request deduplication (same-tick queries)
+ * - TypedDocumentString support (Saleor/client-preset)
+ * - Plain string queries (for custom operations)
+ * - Debug mode
+ *
+ * 0 runtime dependencies.
+ */
+
+import type {
+  StorefrontClientConfig,
+  StorefrontClient,
+  Middleware,
+  CacheStrategy,
+  TypedDocumentString,
+  ExecuteFn,
+} from './types';
+import { createExecute } from './execute';
+import { compose } from './compose';
+import { dedupe } from './dedupe';
+import { hashQuery } from './hash';
+import { getOperationName } from './operation-name';
+
+export function createStorefrontClient(config: StorefrontClientConfig): StorefrontClient {
+  const {
+    apiUrl,
+    shopSlug,
+    defaultHeaders = {},
+    middleware: initialMiddleware = [],
+    fetch: customFetch = globalThis.fetch,
+    debug = false,
+  } = config;
+
+  const endpoint = `${apiUrl.replace(/\/$/, '')}/storefront/graphql`;
+
+  // Mutable middleware list — use() adds to it, invalidates compiled pipeline
+  const middlewares: Middleware[] = [...initialMiddleware];
+  let compiledPipeline: ExecuteFn | null = null;
+
+  // Create the innermost execute function (native fetch)
+  const innerExecute = createExecute({ endpoint, fetch: customFetch, debug });
+
+  /**
+   * Get or build the compiled middleware pipeline (lazy).
+   * Rebuilt on first call and after use() is called.
+   */
+  function getPipeline(): ExecuteFn {
+    if (!compiledPipeline) {
+      compiledPipeline = middlewares.length > 0
+        ? compose(middlewares, innerExecute)
+        : innerExecute;
+    }
+    return compiledPipeline;
+  }
+
+  /**
+   * Resolve query string from TypedDocumentString or plain string.
+   */
+  function resolveQuery(document: TypedDocumentString | string): string {
+    return typeof document === 'string' ? document : document.toString();
+  }
+
+  /**
+   * Core request execution — shared by query() and mutate().
+   */
+  async function request<T>(
+    document: TypedDocumentString<T, unknown> | string,
+    variables?: Record<string, unknown>,
+    isMutation: boolean = false,
+    cache?: CacheStrategy,
+  ): Promise<T> {
+    const query = resolveQuery(document);
+    const operationName = getOperationName(query);
+    const pipeline = getPipeline();
+
+    const headers: Record<string, string> = {
+      'X-Shop-Slug': shopSlug,
+      ...defaultHeaders,
+    };
+
+    if (operationName !== 'anonymous') {
+      headers['X-Operation-Name'] = operationName;
+    }
+
+    const graphqlRequest = {
+      query,
+      variables,
+      operationName,
+      headers,
+      isMutation,
+      cache,
+    };
+
+    // Dedupe queries (not mutations) in the same tick
+    const executeFn = () => pipeline(graphqlRequest);
+
+    const response = isMutation
+      ? await executeFn()
+      : await dedupe(hashQuery(query, variables), executeFn);
+
+    return response.data as T;
+  }
+
+  return {
+    query<T, V>(
+      document: TypedDocumentString<T, V> | string,
+      variables?: V,
+      cache?: CacheStrategy,
+    ): Promise<T> {
+      return request<T>(document as TypedDocumentString<T, unknown>, variables as Record<string, unknown>, false, cache);
+    },
+
+    mutate<T, V>(
+      document: TypedDocumentString<T, V> | string,
+      variables?: V,
+    ): Promise<T> {
+      return request<T>(document as TypedDocumentString<T, unknown>, variables as Record<string, unknown>, true);
+    },
+
+    use(middleware: Middleware): void {
+      middlewares.push(middleware);
+      compiledPipeline = null; // Invalidate — rebuild on next request
+    },
+  };
+}

package/src/core/client/dedupe.ts

@@ -0,0 +1,19 @@
+/**
+ * Request deduplication — identical queries in the same tick share one fetch.
+ *
+ * Key = hashQuery(query, variables). Only applies to queries, not mutations.
+ */
+
+const pending = new Map<string, Promise<unknown>>();
+
+export function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const existing = pending.get(key);
+  if (existing) return existing as Promise<T>;
+
+  const promise = fn().finally(() => {
+    pending.delete(key);
+  });
+
+  pending.set(key, promise);
+  return promise;
+}

package/src/core/client/execute.ts

@@ -0,0 +1,70 @@
+/**
+ * Native fetch transport — 0 runtime dependencies.
+ *
+ * Sends GraphQL POST request, parses response, returns typed GraphQLResponse.
+ * Error normalization is handled by error middleware, NOT here.
+ */
+
+import type { GraphQLRequest, GraphQLResponse, GraphQLErrorInfo } from './types';
+
+export interface ExecuteConfig {
+  /** GraphQL endpoint URL */
+  endpoint: string;
+  /** Custom fetch implementation */
+  fetch: typeof globalThis.fetch;
+  /** Enable debug logging */
+  debug: boolean;
+}
+
+/**
+ * Create the innermost execute function for the middleware pipeline.
+ */
+export function createExecute(config: ExecuteConfig) {
+  const { endpoint, fetch: fetchFn, debug } = config;
+
+  return async function execute(request: GraphQLRequest): Promise<GraphQLResponse> {
+    const { query, variables, headers, signal, operationName } = request;
+
+    if (debug) {
+      console.log('[StorefrontSDK]', operationName ?? 'request', { variables });
+    }
+
+    const body: Record<string, unknown> = { query };
+    if (variables && Object.keys(variables).length > 0) {
+      body.variables = variables;
+    }
+    if (operationName) {
+      body.operationName = operationName;
+    }
+
+    const response = await fetchFn(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...headers,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+
+    const json = await response.json() as {
+      data?: unknown;
+      errors?: GraphQLErrorInfo[];
+    };
+
+    if (debug) {
+      console.log('[StorefrontSDK]', operationName ?? 'response', {
+        status: response.status,
+        hasErrors: !!json.errors?.length,
+      });
+    }
+
+    return {
+      data: json.data as never,
+      errors: json.errors,
+      status: response.status,
+      headers: response.headers,
+    };
+  };
+}

package/src/core/client/hash.ts

@@ -0,0 +1,21 @@
+/**
+ * Stable query hashing for request deduplication.
+ *
+ * Sorts object keys so `{a:1,b:2}` and `{b:2,a:1}` produce the same hash.
+ */
+
+function stableStringify(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return '[' + value.map(stableStringify).join(',') + ']';
+  }
+  const keys = Object.keys(value as Record<string, unknown>).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + stableStringify((value as Record<string, unknown>)[k])).join(',') + '}';
+}
+
+export function hashQuery(query: string, variables?: Record<string, unknown>): string {
+  const queryPart = query.trim();
+  const varsPart = variables ? stableStringify(variables) : '';
+  return queryPart + '::' + varsPart;
+}

package/src/core/client/operation-name.ts

@@ -0,0 +1,12 @@
+/**
+ * Auto-extract operation name from a GraphQL query string.
+ *
+ * Used for: X-Operation-Name header (debugging), cache tags, logging.
+ */
+
+const OPERATION_RE = /(?:query|mutation|subscription)\s+(\w+)/;
+
+export function getOperationName(query: string): string {
+  const match = query.match(OPERATION_RE);
+  return match?.[1] ?? 'anonymous';
+}

package/src/core/client/types.ts

@@ -0,0 +1,171 @@
+/**
+ * Core types for Storefront SDK transport layer.
+ *
+ * Framework-agnostic — no React, no Zustand, 0 runtime dependencies.
+ */
+
+// ---------------------------------------------------------------------------
+// TypedDocumentString (Saleor / client-preset pattern)
+// ---------------------------------------------------------------------------
+
+/**
+ * A branded string carrying result & variable types.
+ * Produced by graphql-codegen client-preset with `documentMode: 'string'`.
+ *
+ * SDK also accepts plain strings — TypedDocumentString is purely for DX.
+ */
+export class TypedDocumentString<TResult = unknown, TVariables = unknown> extends String {
+  /** Type-level brand — never used at runtime */
+  __apiType?: (variables: TVariables) => TResult;
+
+  constructor(value: string, public __meta__?: { hash: string }) {
+    super(value);
+  }
+
+  override toString(): string {
+    return this.valueOf();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL request / response
+// ---------------------------------------------------------------------------
+
+export interface GraphQLRequest {
+  /** GraphQL query or mutation string */
+  query: string;
+  /** Operation variables */
+  variables?: Record<string, unknown>;
+  /** Operation name (auto-extracted if omitted) */
+  operationName?: string;
+  /** Request headers (merged: default < middleware < request) */
+  headers: Record<string, string>;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+  /** Whether this is a mutation (affects retry, cache) */
+  isMutation: boolean;
+  /** Cache strategy override */
+  cache?: CacheStrategy;
+}
+
+export interface GraphQLResponse<T = unknown> {
+  /** Parsed response data */
+  data: T;
+  /** GraphQL errors (if any) */
+  errors?: GraphQLErrorInfo[];
+  /** HTTP status code */
+  status: number;
+  /** Raw response headers */
+  headers: Headers;
+}
+
+export interface GraphQLErrorInfo {
+  message: string;
+  locations?: Array<{ line: number; column: number }>;
+  path?: Array<string | number>;
+  extensions?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// User errors (cart mutations, auth mutations, etc.)
+// ---------------------------------------------------------------------------
+
+export interface UserError {
+  message: string;
+  field?: string[];
+  code?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Middleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute function — the innermost (or next) handler in the pipeline.
+ */
+export type ExecuteFn = (request: GraphQLRequest) => Promise<GraphQLResponse>;
+
+/**
+ * Middleware function — receives the request and the next handler.
+ *
+ * Can modify request, modify response, short-circuit, retry, etc.
+ *
+ * @example
+ * ```typescript
+ * const authMiddleware: Middleware = (req, next) => {
+ *   req.headers['Authorization'] = `Bearer ${getToken()}`;
+ *   return next(req);
+ * };
+ * ```
+ */
+export type Middleware = (request: GraphQLRequest, next: ExecuteFn) => Promise<GraphQLResponse>;
+
+// ---------------------------------------------------------------------------
+// Cache strategy
+// ---------------------------------------------------------------------------
+
+export interface CacheOptions {
+  /** Max age in seconds */
+  maxAge: number;
+  /** Stale-while-revalidate in seconds */
+  staleWhileRevalidate?: number;
+  /** Cache mode */
+  mode: 'public' | 'private' | 'no-store';
+  /** Cache tags (for Next.js revalidateTag) */
+  tags?: string[];
+}
+
+export type CacheStrategy = CacheOptions;
+
+// ---------------------------------------------------------------------------
+// Client config
+// ---------------------------------------------------------------------------
+
+export interface StorefrontClientConfig {
+  /** GraphQL API URL (e.g. 'https://api.doswiftly.pl') */
+  apiUrl: string;
+  /** Shop slug for multi-tenant routing */
+  shopSlug: string;
+  /** Default headers for all requests */
+  defaultHeaders?: Record<string, string>;
+  /** Middleware pipeline */
+  middleware?: Middleware[];
+  /** Custom fetch implementation (polyfill, test mocks, edge) */
+  fetch?: typeof globalThis.fetch;
+  /** Enable debug logging (request/response in dev) */
+  debug?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+export interface StorefrontClient {
+  /**
+   * Execute a typed GraphQL query.
+   *
+   * Accepts TypedDocumentString (from codegen) or plain string.
+   */
+  query<T = unknown, V = Record<string, unknown>>(
+    document: TypedDocumentString<T, V> | string,
+    variables?: V,
+    cache?: CacheStrategy,
+  ): Promise<T>;
+
+  /**
+   * Execute a typed GraphQL mutation.
+   *
+   * Mutations are never cached and never retried by retry middleware.
+   */
+  mutate<T = unknown, V = Record<string, unknown>>(
+    document: TypedDocumentString<T, V> | string,
+    variables?: V,
+  ): Promise<T>;
+
+  /**
+   * Add middleware to the pipeline (imperative API).
+   *
+   * Invalidates the compiled pipeline — next request re-composes.
+   */
+  use(middleware: Middleware): void;
+}

package/src/core/errors.ts

@@ -0,0 +1,67 @@
+/**
+ * StorefrontError — unified error class for all SDK errors.
+ *
+ * Normalizes GraphQL errors, network errors, user errors, and timeouts
+ * into a single throwable type with structured data.
+ */
+
+import type { GraphQLErrorInfo, UserError } from './client/types';
+
+export interface StorefrontErrorOptions {
+  /** Error code for programmatic handling */
+  code: string;
+  /** Human-readable message */
+  message: string;
+  /** HTTP status code (0 for network errors) */
+  status?: number;
+  /** GraphQL-level errors from the response */
+  graphqlErrors?: GraphQLErrorInfo[];
+  /** User errors from mutations (field-level validation) */
+  userErrors?: UserError[];
+  /** Original error (if wrapping) */
+  cause?: unknown;
+}
+
+export class StorefrontError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly graphqlErrors: GraphQLErrorInfo[];
+  readonly userErrors: UserError[];
+
+  constructor(options: StorefrontErrorOptions) {
+    super(options.message, { cause: options.cause });
+    this.name = 'StorefrontError';
+    this.code = options.code;
+    this.status = options.status ?? 0;
+    this.graphqlErrors = options.graphqlErrors ?? [];
+    this.userErrors = options.userErrors ?? [];
+  }
+
+  /** True if this error contains user errors (field-level validation) */
+  get hasUserErrors(): boolean {
+    return this.userErrors.length > 0;
+  }
+
+  /** True if this is a network error (no HTTP response) */
+  get isNetworkError(): boolean {
+    return this.code === 'NETWORK_ERROR';
+  }
+
+  /** True if the request timed out */
+  get isTimeout(): boolean {
+    return this.code === 'TIMEOUT';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error codes
+// ---------------------------------------------------------------------------
+
+export const ErrorCodes = {
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  TIMEOUT: 'TIMEOUT',
+  HTTP_ERROR: 'HTTP_ERROR',
+  GRAPHQL_ERROR: 'GRAPHQL_ERROR',
+  USER_ERROR: 'USER_ERROR',
+  NO_DATA: 'NO_DATA',
+} as const;