@decocms/apps-magento 7.72.0 → 8.0.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/apps-magento",
-  "version": "7.72.0",
+  "version": "8.0.0-next.0",
   "type": "module",
   "description": "Deco commerce app: Magento integration",
   "repository": {
@@ -26,9 +26,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.72.0",
-    "@decocms/apps-commerce": "7.72.0",
-    "@decocms/tanstack": "7.72.0"
+    "@decocms/blocks": "8.0.0-next.0",
+    "@decocms/apps-commerce": "8.0.0-next.0",
+    "@decocms/tanstack": "8.0.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/__tests__/magentoClient.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment node
+/**
+ * The v8 Magento client (/next/upstream-clients): every request goes through
+ * the instrumented fetch as provider "magento", named by its operation; the
+ * store's credentials only go to the store; errors never carry bodies.
+ */
+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 { createMagentoClient, MagentoError } from "../magentoClient";
+
+/** 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 }),
+  );
+}
+
+const config = { baseUrl: "https://store.example.com/", apiKey: "key", originHeader: "origin" };
+
+beforeEach(() => {
+  instrumented.providers.length = 0;
+  instrumented.operations.length = 0;
+});
+
+describe("createMagentoClient", () => {
+  it("calls REST with the store credentials, labeled by operation", async () => {
+    const fetch = upstream({ id: 7 });
+    const magento = createMagentoClient(config, { fetch });
+
+    expect(
+      await magento.rest<{ id: number }>("/rest/default/V1/carts/7", { operation: "getCart" }),
+    ).toEqual({ id: 7 });
+    expect(instrumented.providers).toEqual(["magento"]);
+    expect(instrumented.operations).toEqual(["getCart"]);
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(String(url)).toBe("https://store.example.com/rest/default/V1/carts/7");
+    const headers = new Headers(init?.headers);
+    expect(headers.get("authorization")).toBe("Bearer key");
+    expect(headers.get("x-origin-header")).toBe("origin");
+  });
+
+  it("omits the token when a call opts out", async () => {
+    const fetch = upstream({});
+    const magento = createMagentoClient(config, { fetch });
+    await magento.request("/customer/section/load", {
+      operation: "loadSections",
+      authenticated: false,
+    });
+    expect(new Headers(fetch.mock.calls[0]![1]?.headers).get("authorization")).toBeNull();
+  });
+
+  it("refuses URLs on another origin, so the token never leaves the store", async () => {
+    const fetch = upstream({});
+    const magento = createMagentoClient(config, { fetch });
+    await expect(magento.request("https://evil.example/steal", { operation: "x" })).rejects.toThrow(
+      /only paths on the configured store/,
+    );
+    await expect(magento.request("//evil.example/steal", { operation: "x" })).rejects.toThrow(
+      /only paths on the configured store/,
+    );
+    expect(fetch).not.toHaveBeenCalled();
+  });
+
+  it("keeps a customer Authorization header instead of the store's token", async () => {
+    const fetch = upstream({ data: { customer: { email: "a" } }, items: [] });
+    const magento = createMagentoClient(config, { fetch });
+    await magento.graphql("query Customer { customer { email } }", undefined, {
+      operationName: "Customer",
+      headers: { Authorization: "Bearer customer" },
+    });
+    await magento.rest("/rest/default/V1/carts/mine", {
+      operation: "getCart",
+      headers: { Authorization: "Bearer customer" },
+    });
+    for (const [, init] of fetch.mock.calls) {
+      expect(new Headers(init?.headers).get("authorization")).toBe("Bearer customer");
+    }
+  });
+
+  it("sends GraphQL without the store's token unless asked, and keeps the JSON content type", async () => {
+    const fetch = upstream({ data: {} });
+    const magento = createMagentoClient(config, { fetch });
+    await magento.graphql("query Q { a }", undefined, {
+      operationName: "Q",
+      headers: { "Content-Type": "text/plain" },
+    });
+    await magento.graphql("query Q { a }", undefined, { operationName: "Q", authenticated: true });
+    const [first, second] = fetch.mock.calls.map(([, init]) => new Headers(init?.headers));
+    expect(first!.get("authorization")).toBeNull();
+    expect(first!.get("content-type")).toBe("application/json");
+    expect(second!.get("authorization")).toBe("Bearer key");
+  });
+
+  it("returns undefined for a 204 REST response", async () => {
+    const fetch = vi.fn(async () => new Response(null, { status: 204 }));
+    const magento = createMagentoClient(config, { fetch });
+    await expect(
+      magento.rest("/rest/default/V1/carts/mine/items/1", {
+        operation: "removeCartItem",
+        method: "DELETE",
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("sends GraphQL with its operationName, which is the label", async () => {
+    const fetch = upstream({ data: { productStockAlert: { status: true } } });
+    const magento = createMagentoClient(config, { fetch });
+    const data = await magento.graphql<{ productStockAlert: { status: boolean } }>(
+      "mutation ProductStockAlert($sku: String!) { productStockAlert(sku: $sku) { status } }",
+      { sku: "A1" },
+      { operationName: "ProductStockAlert", headers: { Store: "default" } },
+    );
+    expect(data.productStockAlert.status).toBe(true);
+    expect(instrumented.operations).toEqual(["ProductStockAlert"]);
+    const [url, init] = fetch.mock.calls[0]!;
+    expect(String(url)).toBe("https://store.example.com/graphql");
+    expect(new Headers(init?.headers).get("store")).toBe("default");
+    expect(JSON.parse(String(init?.body))).toMatchObject({
+      operationName: "ProductStockAlert",
+      variables: { sku: "A1" },
+    });
+  });
+
+  it("throws a MagentoError without the body", async () => {
+    const magento = createMagentoClient(config, {
+      fetch: upstream({ message: "token key invalid" }, 401),
+    });
+    const error = await failure(magento.rest("/rest/V1/carts/mine", { operation: "getCart" }));
+    expect(error).toBeInstanceOf(MagentoError);
+    expect(error.message).toBe("magento getCart failed with HTTP 401");
+
+    const gql = createMagentoClient(config, {
+      fetch: upstream({ errors: [{ message: "x@example.com" }] }),
+    });
+    const gqlError = await failure(gql.graphql("query Q { a }", undefined, { operationName: "Q" }));
+    expect(gqlError.message).toBe("magento Q returned 1 GraphQL error(s)");
+  });
+});

package/src/index.ts

@@ -1,3 +1,6 @@
+// v8: the thin Magento client (see /next/upstream-clients).
+
+// v7 (kept for v7 consumers until the v7 modules are dropped)
 /**
  * Magento app entry point for @decocms/apps.
  * Re-exports client config + initializer.
@@ -8,6 +11,14 @@
  *   import { magentoFetch } from "@decocms/apps/magento/client"
  */
 export * from "./client";
+export {
+  createMagentoClient,
+  type MagentoClient,
+  type MagentoClientConfig,
+  type MagentoClientOptions,
+  MagentoError,
+  type MagentoRequestInit,
+} from "./magentoClient";
 export type { MagentoCart } from "./types";
 export {
   clearFetchCache,

package/src/magentoClient.ts

@@ -0,0 +1,129 @@
+/**
+ * The Magento client: a thin client for a Magento store's REST and GraphQL
+ * APIs, over the framework's instrumented fetch (provider "magento"). See
+ * /next/upstream-clients.
+ *
+ * Configuration comes in as arguments; the site reads its environment (or a
+ * `secret` block) where it creates the client. Converters, hooks, cart and
+ * session flows, caching and feature toggles belong to the site (platform
+ * templates), not here.
+ */
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+
+export interface MagentoClientConfig {
+  /** The store's origin, e.g. `https://store.example.com`. Every request goes here. */
+  baseUrl: string;
+  /** Integration access token, sent as `Authorization: Bearer` unless a call opts out. */
+  apiKey?: string;
+  /** Optional value sent as `x-origin-header`, for stores behind an origin guard. */
+  originHeader?: string;
+}
+
+export interface MagentoClientOptions {
+  /** The fetch underneath, e.g. a fake in tests. Defaults to `globalThis.fetch`. */
+  fetch?: Parameters<typeof createInstrumentedFetch>[0]["fetch"];
+}
+
+export interface MagentoRequestInit extends RequestInit {
+  /** The operation label, the API's own name for the call (e.g. `getCart`), never a URL. */
+  operation: string;
+  /**
+   * Send the `apiKey` bearer token. Default true for `request`/`rest`, false
+   * for `graphql`. Never replaces an `Authorization` header the call sets
+   * (e.g. a customer token).
+   */
+  authenticated?: boolean;
+}
+
+/** Thrown on a non-2xx response or a GraphQL `errors` payload. Never carries bodies or tokens. */
+export class MagentoError 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
+        ? `magento ${operation} returned ${graphqlErrors} GraphQL error(s)`
+        : `magento ${operation} failed with HTTP ${status}`,
+    );
+    this.name = "MagentoError";
+  }
+}
+
+export type MagentoClient = ReturnType<typeof createMagentoClient>;
+
+export function createMagentoClient(
+  config: MagentoClientConfig,
+  options: MagentoClientOptions = {},
+) {
+  const instrumented = createInstrumentedFetch({ provider: "magento", fetch: options.fetch });
+  const origin = new URL(config.baseUrl).origin;
+
+  /**
+   * A request to a path on the store, e.g. `/rest/default/V1/carts/mine` or
+   * `/customer/section/load`, returning the raw response. Paths only: the
+   * store's credentials never go to another origin.
+   */
+  async function request(path: string, init: MagentoRequestInit): Promise<Response> {
+    const { operation, authenticated = true, ...rest } = init;
+    const url = new URL(path, origin);
+    if (url.origin !== origin) {
+      throw new Error(`magento ${operation}: only paths on the configured store are allowed`);
+    }
+    const headers = new Headers(rest.headers);
+    if (authenticated && config.apiKey && !headers.has("authorization")) {
+      headers.set("authorization", `Bearer ${config.apiKey}`);
+    }
+    if (config.originHeader) headers.set("x-origin-header", config.originHeader);
+    return instrumented(url, { ...rest, headers, operation });
+  }
+
+  return {
+    request,
+
+    /** A REST call (`/rest/<store>/V1/...`) returning its parsed JSON body. */
+    async rest<T>(path: string, init: MagentoRequestInit): Promise<T> {
+      const headers = new Headers(init.headers);
+      if (init.body !== undefined && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+      }
+      const response = await request(path, { ...init, headers });
+      if (!response.ok) throw new MagentoError(init.operation, response.status);
+      if (response.status === 204) return undefined as T;
+      return (await response.json()) as T;
+    },
+
+    /**
+     * A GraphQL operation on `/graphql`. `operationName` is sent with the
+     * request and is the operation label. `headers` adds per-call headers,
+     * such as `Store` or a customer `Authorization` token. Storefront
+     * GraphQL is public, so the `apiKey` is sent only with
+     * `authenticated: true`, and never over a customer token.
+     */
+    async graphql<TData, TVariables = Record<string, unknown>>(
+      query: string,
+      variables: TVariables | undefined,
+      init: { operationName: string; headers?: Record<string, string>; authenticated?: boolean },
+    ): Promise<TData> {
+      const { operationName, ...rest } = init;
+      const headers = new Headers(rest.headers);
+      headers.set("content-type", "application/json");
+      const response = await request("/graphql", {
+        operation: operationName,
+        authenticated: rest.authenticated ?? false,
+        method: "POST",
+        headers,
+        body: JSON.stringify({ query, variables, operationName }),
+      });
+      if (!response.ok) throw new MagentoError(operationName, response.status);
+      const body = (await response.json()) as { data?: TData; errors?: unknown[] };
+      if (body.errors?.length) {
+        throw new MagentoError(operationName, response.status, body.errors.length);
+      }
+      if (body.data === undefined) throw new MagentoError(operationName, response.status);
+      return body.data;
+    },
+  };
+}