@decocms/apps-wake 7.72.0 → 8.1.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-wake",
-  "version": "7.72.0",
+  "version": "8.1.0-next.0",
   "type": "module",
   "description": "Deco commerce app: Wake Commerce integration",
   "repository": {
@@ -17,6 +17,8 @@
     ".": "./src/index.ts",
     "./mod": "./src/mod.ts",
     "./client": "./src/client.ts",
+    "./storefront": "./src/storefront.ts",
+    "./storefront/types": "./src/storefrontTypes.ts",
     "./commerceLoaders": "./src/commerceLoaders.ts",
     "./loaders/*": "./src/loaders/*.ts",
     "./actions/*": "./src/actions/*.ts",
@@ -37,9 +39,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.72.0",
-    "@decocms/apps-commerce": "7.72.0",
-    "@decocms/tanstack": "7.72.0"
+    "@decocms/blocks": "8.1.0-next.0",
+    "@decocms/apps-commerce": "8.1.0-next.0",
+    "@decocms/tanstack": "8.1.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/__tests__/wakeClient.test.ts

@@ -0,0 +1,136 @@
+// @vitest-environment node
+/**
+ * The v8 Wake client (/next/upstream-clients): every request goes through the
+ * instrumented fetch as provider "wake", named by its operation, and errors
+ * never carry bodies or tokens.
+ */
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const instrumented = vi.hoisted(() => ({
+  providers: [] as string[],
+  operations: [] as (string | undefined)[],
+}));
+
+vi.mock("@decocms/blocks/fetch", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@decocms/blocks/fetch")>();
+  return {
+    createInstrumentedFetch: (options: Parameters<typeof real.createInstrumentedFetch>[0]) => {
+      instrumented.providers.push(options.provider);
+      const request = real.createInstrumentedFetch(options);
+      return (input: string | URL | Request, init?: RequestInit & { operation?: string }) => {
+        instrumented.operations.push(init?.operation);
+        return request(input, init);
+      };
+    },
+  };
+});
+
+import { GetProduct } from "../storefront";
+import { createWakeClient, WakeError } from "../wakeClient";
+
+/** The error a call rejects with (fails the test if it resolves). */
+const failure = (call: Promise<unknown>): Promise<Error> =>
+  call.then(
+    () => {
+      throw new Error("expected the call to fail");
+    },
+    (error: Error) => error,
+  );
+
+function upstream(body: unknown, status = 200) {
+  return vi.fn(
+    async (_input: string | URL | Request, _init?: RequestInit) =>
+      new Response(JSON.stringify(body), { status }),
+  );
+}
+
+beforeEach(() => {
+  instrumented.providers.length = 0;
+  instrumented.operations.length = 0;
+});
+
+describe("createWakeClient", () => {
+  it("runs a storefront operation through the instrumented fetch, labeled by its name", async () => {
+    const fetch = upstream({ data: { product: { productId: 1 } } });
+    const wake = createWakeClient({ storefrontToken: "tok" }, { fetch });
+
+    const data = await wake.graphql<{ product: { productId: number } }>(
+      GetProduct,
+      { productId: 1 },
+      {
+        headers: {
+          "x-forwarded-for": "203.0.113.7",
+          "TCS-Access-Token": "spoofed",
+          "Content-Type": "text/plain",
+        },
+      },
+    );
+
+    expect(data).toEqual({ product: { productId: 1 } });
+    expect(instrumented.providers).toEqual(["wake"]);
+    expect(instrumented.operations).toEqual(["GetProduct"]);
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(String(url)).toBe("https://storefront-api.fbits.net/graphql");
+    const headers = new Headers(init?.headers);
+    // Per-call headers can't override the token or the content type, whatever their case.
+    expect(headers.get("tcs-access-token")).toBe("tok");
+    expect(headers.get("content-type")).toBe("application/json");
+    expect(headers.get("x-forwarded-for")).toBe("203.0.113.7");
+    const body = JSON.parse(String(init?.body));
+    expect(body.variables).toEqual({ productId: 1 });
+    expect(body.query).toContain("fragment"); // fragments are sent with the document
+  });
+
+  it("throws a WakeError without the body on HTTP and GraphQL failures", async () => {
+    const failing = createWakeClient(
+      { storefrontToken: "tok" },
+      { fetch: upstream({ secret: "x" }, 502) },
+    );
+    const httpError = await failure(failing.graphql("query Shop { shop { name } }"));
+    expect(httpError).toBeInstanceOf(WakeError);
+    expect(httpError.message).toBe("wake Shop failed with HTTP 502");
+
+    const erroring = createWakeClient(
+      { storefrontToken: "tok" },
+      { fetch: upstream({ errors: [{ message: "customer jane@example.com not found" }] }) },
+    );
+    const gqlError = await failure(erroring.graphql("query Shop { shop { name } }"));
+    expect(gqlError.message).toBe("wake Shop returned 1 GraphQL error(s)");
+    expect(gqlError.message).not.toContain("jane");
+    expect(gqlError.message).not.toContain("tok");
+  });
+
+  it("reads the signed-in shopper from the checkout, or null when signed out", async () => {
+    const fetch = upstream({ CustomerAccessToken: "cat", Email: "a@example.com" });
+    const wake = createWakeClient(
+      { storefrontToken: "tok", checkoutUrl: "https://checkout.example.com" },
+      { fetch },
+    );
+    expect(await wake.getLogin("fbits-login=abc")).toMatchObject({ CustomerAccessToken: "cat" });
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(String(url)).toBe("https://checkout.example.com/api/Login/Get");
+    expect(new Headers(init?.headers).get("cookie")).toBe("fbits-login=abc");
+    expect(instrumented.operations).toEqual(["getLogin"]);
+
+    const signedOut = createWakeClient(
+      { storefrontToken: "tok", checkoutUrl: "https://checkout.example.com" },
+      { fetch: upstream({}, 401) },
+    );
+    expect(await signedOut.getLogin("")).toBeNull();
+  });
+
+  it("throws on a rate limit instead of reporting the shopper as signed out", async () => {
+    const limited = createWakeClient(
+      { storefrontToken: "tok", checkoutUrl: "https://checkout.example.com" },
+      { fetch: upstream({}, 429) },
+    );
+    const error = await failure(limited.getLogin("fbits-login=abc"));
+    expect(error).toBeInstanceOf(WakeError);
+    expect(error.message).toBe("wake getLogin failed with HTTP 429");
+  });
+
+  it("requires checkoutUrl for getLogin", async () => {
+    const wake = createWakeClient({ storefrontToken: "tok" }, { fetch: upstream({}) });
+    await expect(wake.getLogin("")).rejects.toThrow(/set checkoutUrl/);
+  });
+});

package/src/index.ts

@@ -1,3 +1,16 @@
+// v8: the thin Wake client (see /next/upstream-clients). Operations are in
+// `@decocms/apps-wake/storefront`, their types in `.../storefront/types`.
+
+export type { UserAuthenticate } from "./utils/client";
+export {
+  createWakeClient,
+  type WakeClient,
+  type WakeClientConfig,
+  type WakeClientOptions,
+  WakeError,
+} from "./wakeClient";
+
+// v7 (kept for v7 consumers until the v7 modules are dropped)
 // App contract
 
 // Cart actions

package/src/storefront.ts

@@ -0,0 +1,13 @@
+/**
+ * `@decocms/apps-wake/storefront`: Wake's Storefront GraphQL operations, to
+ * pass to `createWakeClient`'s `graphql`. Their generated request and response
+ * types are in `@decocms/apps-wake/storefront/types`:
+ *
+ * ```ts
+ * import { GetProduct } from "@decocms/apps-wake/storefront";
+ * import type { GetProductQuery, GetProductQueryVariables } from "@decocms/apps-wake/storefront/types";
+ *
+ * const data = await wake.graphql<GetProductQuery, GetProductQueryVariables>(GetProduct, { productId: 1 });
+ * ```
+ */
+export * from "./utils/graphql/queries";

package/src/storefrontTypes.ts

@@ -0,0 +1,6 @@
+/**
+ * `@decocms/apps-wake/storefront/types`: types generated from Wake's
+ * Storefront GraphQL schema, one `<Operation>Query`/`<Operation>Mutation` and
+ * `...Variables` pair per operation in `@decocms/apps-wake/storefront`.
+ */
+export type * from "./utils/graphql/storefront.graphql.gen";

package/src/utils/gql.ts

@@ -0,0 +1,24 @@
+/**
+ * GraphQL document helpers shared by the v8 client (`../wakeClient.ts`) and
+ * the v7 GraphQL client (`./graphql.ts`). Pure: no I/O, no framework imports.
+ */
+
+/**
+ * Tagged-template helper that composes a GraphQL document string.
+ * Kept identical to the Deno `gql` so `graphql/queries.ts` (which defines
+ * `{ fragments, query }` objects) works verbatim.
+ */
+export function gql(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ""), "");
+}
+
+/** A Wake storefront operation: its document plus the fragments it spreads. */
+export interface QueryDefinition {
+  fragments?: string[];
+  query: string;
+}
+
+export function buildQuery(def: QueryDefinition): string {
+  const fragments = def.fragments?.join("\n") ?? "";
+  return fragments ? `${fragments}\n${def.query}` : def.query;
+}

package/src/utils/graphql/queries.ts

@@ -1,4 +1,4 @@
-import { gql } from "../graphql";
+import { gql } from "../gql";
 
 const Checkout = gql`
 fragment Checkout on Checkout {

package/src/utils/graphql.ts

@@ -1,25 +1,9 @@
 import { type FetchFn, withFetchTimeout } from "@decocms/blocks/sdk/fetchTimeout";
 import type { InstrumentedFetchInit } from "@decocms/blocks/sdk/instrumentedFetch";
+import { buildQuery, type QueryDefinition } from "./gql";
 import { extractGraphqlOperationName } from "./graphqlOperationName";
 
-/**
- * Tagged-template helper that composes a GraphQL document string.
- * Kept identical to the Deno `gql` so the ported `graphql/queries.ts`
- * (which defines `{ fragments, query }` objects) works verbatim.
- */
-export function gql(strings: TemplateStringsArray, ...values: unknown[]): string {
-  return strings.reduce((acc, str, i) => acc + str + (values[i] ?? ""), "");
-}
-
-export interface QueryDefinition {
-  fragments?: string[];
-  query: string;
-}
-
-export function buildQuery(def: QueryDefinition): string {
-  const fragments = def.fragments?.join("\n") ?? "";
-  return fragments ? `${fragments}\n${def.query}` : def.query;
-}
+export { buildQuery, gql, type QueryDefinition } from "./gql";
 
 export interface GraphQLClient {
   /**

package/src/wakeClient.ts

@@ -0,0 +1,104 @@
+/**
+ * The Wake client: a thin, typed client for Wake's Storefront GraphQL API and
+ * the one checkout REST call a storefront needs, over the framework's
+ * instrumented fetch (provider "wake"). See /next/upstream-clients.
+ *
+ * Configuration comes in as arguments; the site reads its environment where
+ * it creates the client. Converters, hooks, cart/session flows, caching and
+ * proxying belong to the site (platform templates), not here.
+ */
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+import type { UserAuthenticate } from "./utils/client";
+import { buildQuery, type QueryDefinition } from "./utils/gql";
+import { extractGraphqlOperationName } from "./utils/graphqlOperationName";
+
+const WAKE_STOREFRONT_ENDPOINT = "https://storefront-api.fbits.net/graphql";
+
+export interface WakeClientConfig {
+  /** Wake Storefront API token, sent as `TCS-Access-Token`. */
+  storefrontToken: string;
+  /** Storefront GraphQL endpoint; defaults to Wake's multi-tenant endpoint. */
+  storefrontEndpoint?: string;
+  /** Checkout origin, e.g. `https://checkout.example.com`. Required by `getLogin`. */
+  checkoutUrl?: string;
+}
+
+export interface WakeClientOptions {
+  /** The fetch underneath, e.g. a fake in tests. Defaults to `globalThis.fetch`. */
+  fetch?: Parameters<typeof createInstrumentedFetch>[0]["fetch"];
+}
+
+/** Thrown on a non-2xx response or a GraphQL `errors` payload. Never carries bodies or tokens. */
+export class WakeError extends Error {
+  constructor(
+    readonly operation: string,
+    readonly status: number,
+    /** How many GraphQL errors the response carried (0 for an HTTP failure). */
+    readonly graphqlErrors = 0,
+  ) {
+    super(
+      graphqlErrors > 0
+        ? `wake ${operation} returned ${graphqlErrors} GraphQL error(s)`
+        : `wake ${operation} failed with HTTP ${status}`,
+    );
+    this.name = "WakeError";
+  }
+}
+
+export type WakeClient = ReturnType<typeof createWakeClient>;
+
+export function createWakeClient(config: WakeClientConfig, options: WakeClientOptions = {}) {
+  const request = createInstrumentedFetch({ provider: "wake", fetch: options.fetch });
+  const endpoint = config.storefrontEndpoint || WAKE_STOREFRONT_ENDPOINT;
+  const checkoutUrl = config.checkoutUrl;
+
+  return {
+    /**
+     * Run a Storefront GraphQL operation (see `@decocms/apps-wake/storefront`).
+     * The operation label is the document's operation name. `headers` adds
+     * per-call headers, such as `X-Forwarded-For` or a customer access token;
+     * they never override the token or the content type.
+     */
+    async graphql<TData, TVariables = Record<string, unknown>>(
+      document: string | QueryDefinition,
+      variables?: TVariables,
+      init: { headers?: Record<string, string> } = {},
+    ): Promise<TData> {
+      const query = typeof document === "string" ? document : buildQuery(document);
+      const operation = extractGraphqlOperationName(query) ?? "graphql";
+      const headers = new Headers(init.headers);
+      headers.set("content-type", "application/json");
+      headers.set("tcs-access-token", config.storefrontToken);
+      const response = await request(endpoint, {
+        operation,
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query, variables }),
+      });
+      if (!response.ok) throw new WakeError(operation, response.status);
+      const body = (await response.json()) as { data?: TData; errors?: unknown[] };
+      if (body.errors?.length) throw new WakeError(operation, response.status, body.errors.length);
+      if (body.data === undefined) throw new WakeError(operation, response.status);
+      return body.data;
+    },
+
+    /**
+     * `GET /api/Login/Get` on the checkout: exchanges the shopper's checkout
+     * cookies (the `fbits-login` cookie) for their account, or `null` when
+     * they aren't signed in (401, 403 or 404). Any other failure, such as
+     * a 429, throws a `WakeError`.
+     */
+    async getLogin(cookie: string): Promise<UserAuthenticate | null> {
+      if (!checkoutUrl) throw new Error("wake getLogin: set checkoutUrl");
+      const response = await request(new URL("/api/Login/Get", checkoutUrl), {
+        operation: "getLogin",
+        headers: { cookie },
+      });
+      if (response.status === 401 || response.status === 403 || response.status === 404) {
+        return null; // not signed in
+      }
+      if (!response.ok) throw new WakeError("getLogin", response.status);
+      return (await response.json()) as UserAuthenticate | null;
+    },
+  };
+}