@decocms/blocks 7.0.0

package/src/sdk/invoke.ts

@@ -0,0 +1,260 @@
+/**
+ * Typed invoke proxies for client-side RPC to deco loaders/actions.
+ *
+ * Two flavors:
+ *
+ * 1. `createInvokeProxy<T>()` — flat keys (e.g. `invoke["vtex/loaders/productList.ts"](props)`)
+ * 2. `createAppInvoke<T>()` — nested keys (e.g. `invoke.vtex.actions.checkout.addItemsToCart(props)`)
+ *
+ * Both POST to `/deco/invoke/{key}` under the hood.
+ *
+ * @example
+ * ```ts
+ * // Flat proxy (legacy):
+ * const invoke = createInvokeProxy<Loaders>();
+ * await invoke["vtex/loaders/productList.ts"]({ query: "shoes" });
+ *
+ * // Nested proxy (recommended):
+ * const invoke = createAppInvoke();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * ```
+ */
+
+export type InvokeProxy<TLoaders extends Record<string, (props: any) => Promise<any>>> = {
+  [K in keyof TLoaders]: TLoaders[K] extends (props: infer P) => Promise<infer R>
+    ? (props: P) => Promise<R>
+    : never;
+};
+
+/**
+ * Creates a proxy that turns loader key access into fetch calls to `/deco/invoke/:key`.
+ */
+export function createInvokeProxy<TLoaders extends Record<string, (props: any) => Promise<any>>>(
+  basePath = "/deco/invoke",
+): InvokeProxy<TLoaders> {
+  return new Proxy({} as InvokeProxy<TLoaders>, {
+    get(_target, prop: string) {
+      return async (props: unknown) => {
+        const url = `${basePath}/${encodeURIComponent(prop)}`;
+        const response = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(props ?? {}),
+        });
+
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({ error: response.statusText }));
+          throw new Error(
+            `Invoke ${prop} failed (${response.status}): ${(error as any).error || response.statusText}`,
+          );
+        }
+
+        return response.json();
+      };
+    },
+  });
+}
+
+/**
+ * Batch invoke multiple loaders in a single request.
+ *
+ * @example
+ * ```ts
+ * const results = await batchInvoke("/deco/invoke", {
+ *   products: { __resolveType: "vtex/loaders/productList.ts", query: "shoes" },
+ *   details: { __resolveType: "vtex/loaders/productDetailsPage.ts", slug: "shoe-1" },
+ * });
+ * ```
+ */
+export async function batchInvoke<T extends Record<string, unknown>>(
+  basePath: string,
+  payloads: T,
+): Promise<{ [K in keyof T]: unknown }> {
+  const response = await fetch(basePath, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payloads),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Batch invoke failed (${response.status})`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Helper to create TanStack Query `queryOptions` for an invoke call.
+ * The storefront must have `@tanstack/react-query` installed.
+ *
+ * @example
+ * ```ts
+ * import { useQuery } from "@tanstack/react-query";
+ * import { invokeQueryOptions } from "@decocms/start/sdk/invoke";
+ *
+ * const options = invokeQueryOptions(
+ *   "vtex/loaders/productList.ts",
+ *   { query: "shoes" },
+ *   { staleTime: 60_000 }
+ * );
+ *
+ * // In a component:
+ * const { data } = useQuery(options);
+ *
+ * // In a route loader:
+ * queryClient.ensureQueryData(options);
+ * ```
+ */
+export function invokeQueryOptions<TResult = unknown>(
+  key: string,
+  props: unknown,
+  options?: { staleTime?: number; gcTime?: number; basePath?: string },
+) {
+  const basePath = options?.basePath ?? "/deco/invoke";
+
+  return {
+    queryKey: ["deco-invoke", key, props] as const,
+    queryFn: async (): Promise<TResult> => {
+      const url = `${basePath}/${encodeURIComponent(key)}`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(props ?? {}),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Invoke ${key} failed (${response.status})`);
+      }
+
+      return response.json();
+    },
+    staleTime: options?.staleTime,
+    gcTime: options?.gcTime,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Nested invoke proxy — createAppInvoke
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts flat slash-separated keys into a nested object type.
+ *
+ * @example
+ * ```ts
+ * type Map = {
+ *   "vtex/actions/checkout/addItemsToCart": (props: CartInput) => Promise<OrderForm>;
+ *   "vtex/loaders/catalog/getProduct": (props: { slug: string }) => Promise<Product>;
+ * };
+ * type Nested = NestedFromFlat<Map>;
+ * // { vtex: { actions: { checkout: { addItemsToCart: (props: CartInput) => Promise<OrderForm> } } } }
+ * ```
+ */
+type SplitFirst<S extends string> = S extends `${infer Head}/${infer Tail}`
+  ? [Head, Tail]
+  : [S, never];
+
+type BuildNested<Key extends string, Value> =
+  SplitFirst<Key> extends [infer H extends string, infer T]
+    ? T extends string
+      ? { [K in H]: BuildNested<T, Value> }
+      : { [K in H]: Value }
+    : never;
+
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void
+  ? I
+  : never;
+
+type DeepMerge<T> = T extends object ? { [K in keyof T]: DeepMerge<T[K]> } : T;
+
+export type NestedFromFlat<T extends Record<string, any>> = DeepMerge<
+  UnionToIntersection<{ [K in keyof T & string]: BuildNested<K, T[K]> }[keyof T & string]>
+>;
+
+/**
+ * Creates a typed nested invoke proxy.
+ *
+ * Each property access accumulates path segments. When called as a function,
+ * the segments are joined with "/" and POSTed to `/deco/invoke/{key}`.
+ * If the primary key returns 404, a `.ts` suffix variant is tried.
+ *
+ * @example
+ * ```ts
+ * import { createAppInvoke } from "@decocms/start/sdk/invoke";
+ *
+ * // Untyped (any):
+ * const invoke = createAppInvoke();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ *
+ * // Typed (with handler map):
+ * type Handlers = {
+ *   "vtex/actions/checkout/addItemsToCart": (props: CartInput) => Promise<OrderForm>;
+ * };
+ * const invoke = createAppInvoke<Handlers>();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * ```
+ */
+export function createAppInvoke(basePath?: string): any;
+export function createAppInvoke<T extends Record<string, any>>(
+  basePath?: string,
+): NestedFromFlat<T>;
+export function createAppInvoke(basePath = "/deco/invoke"): any {
+  function buildProxy(path: string[]): any {
+    return new Proxy(
+      Object.assign(async (props: any) => {
+        const key = path.join("/");
+        for (const k of [key, `${key}.ts`]) {
+          const response = await fetch(`${basePath}/${k}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(props ?? {}),
+          });
+          if (response.status === 404) {
+            await response.body?.cancel();
+            continue;
+          }
+          if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(
+              `invoke(${k}) failed (${response.status}): ${(error as any).error || response.statusText}`,
+            );
+          }
+          return response.json();
+        }
+        throw new Error(`invoke(${key}) failed: handler not found`);
+      }, {}),
+      {
+        get(_target: any, prop: string | symbol) {
+          if (typeof prop === "symbol") return undefined;
+          if (prop === "then" || prop === "catch" || prop === "finally") {
+            return undefined;
+          }
+          return buildProxy([...path, prop]);
+        },
+      },
+    );
+  }
+
+  return buildProxy([]);
+}
+
+/**
+ * Default nested invoke proxy bound to `/deco/invoke`.
+ *
+ * Replaces site-level `~/runtime.ts` shims that wrap the same `createAppInvoke`
+ * call. Importing this singleton means no per-site boilerplate.
+ *
+ * @example
+ * ```ts
+ * import { invoke } from "@decocms/start/sdk/invoke";
+ *
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * await invoke.site.loaders.Wishlist.getWishlist({});
+ * ```
+ *
+ * For a custom `basePath` or typed handlers, call `createAppInvoke()` directly:
+ * ```ts
+ * const invoke = createAppInvoke<Handlers>("/my/invoke");
+ * ```
+ */
+export const invoke = createAppInvoke();

package/src/sdk/logger.test.ts

@@ -0,0 +1,432 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  _getLoggerAttributeFloorForTests,
+  configureLogger,
+  defaultLoggerAdapter,
+  getLoggerAdapter,
+  getLogLevel,
+  type LoggerAdapter,
+  logger,
+  serializeError,
+  setLoggerAttributeFloor,
+  setLogLevel,
+} from "./logger";
+
+describe("defaultLoggerAdapter", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("debug"); // permissive default for the rest of the suite
+  });
+
+  it("emits one JSON line per call", () => {
+    defaultLoggerAdapter.log("info", "hello", { foo: 1 });
+    expect(logSpy).toHaveBeenCalledOnce();
+    const arg = logSpy.mock.calls[0]?.[0] as string;
+    const parsed = JSON.parse(arg);
+    expect(parsed).toMatchObject({ level: "info", msg: "hello", foo: 1 });
+    expect(typeof parsed.timestamp).toBe("string");
+  });
+
+  it("routes by level so CF Logs colorises correctly", () => {
+    defaultLoggerAdapter.log("error", "boom");
+    defaultLoggerAdapter.log("warn", "careful");
+    defaultLoggerAdapter.log("debug", "details");
+    expect(errorSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(debugSpy).toHaveBeenCalledOnce();
+  });
+
+  it("never throws on circular refs (last-resort fallback)", () => {
+    const circ: any = { name: "x" };
+    circ.self = circ;
+    expect(() => defaultLoggerAdapter.log("info", "circ", { circ })).not.toThrow();
+    expect(logSpy).toHaveBeenCalledOnce();
+  });
+
+  it("does not let attrs override level/msg/timestamp keys", () => {
+    defaultLoggerAdapter.log("info", "real-msg", {
+      level: "tampered",
+      msg: "tampered",
+      timestamp: "tampered",
+    });
+    const parsed = JSON.parse(logSpy.mock.calls[0]?.[0] as string);
+    expect(parsed.level).toBe("info");
+    expect(parsed.msg).toBe("real-msg");
+    expect(parsed.timestamp).not.toBe("tampered");
+  });
+});
+
+describe("level filtering", () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("drops calls below the active min level", () => {
+    setLogLevel("warn");
+    expect(getLogLevel()).toBe("warn");
+    logger.debug("d");
+    logger.info("i");
+    logger.warn("w");
+    logger.error("e");
+    expect(debugSpy).not.toHaveBeenCalled();
+    expect(logSpy).not.toHaveBeenCalled(); // info routes to console.log
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(errorSpy).toHaveBeenCalledOnce();
+  });
+});
+
+describe("configureLogger", () => {
+  afterEach(() => {
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("dispatches to the configured adapter", () => {
+    const calls: Array<[string, string, unknown]> = [];
+    const test: LoggerAdapter = {
+      log(level, msg, attrs) {
+        calls.push([level, msg, attrs]);
+      },
+    };
+    configureLogger(test);
+    expect(getLoggerAdapter()).toBe(test);
+
+    logger.info("hello", { x: 1 });
+    expect(calls).toEqual([["info", "hello", { x: 1 }]]);
+  });
+
+  it("falls back to default adapter if active adapter throws", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const broken: LoggerAdapter = {
+      log() {
+        throw new Error("nope");
+      },
+    };
+    configureLogger(broken);
+    expect(() => logger.info("survives", { x: 1 })).not.toThrow();
+    // Default adapter was invoked as the fallback
+    expect(logSpy).toHaveBeenCalledOnce();
+    logSpy.mockRestore();
+  });
+});
+
+describe("setLoggerAttributeFloor", () => {
+  afterEach(() => {
+    setLoggerAttributeFloor({});
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("starts empty so the floor is a no-op out of the box", () => {
+    expect(_getLoggerAttributeFloorForTests()).toEqual({});
+  });
+
+  it("merges floor attrs into every log call", () => {
+    setLoggerAttributeFloor({
+      "deco.runtime.version": "4.4.0",
+      "deployment.environment": "production",
+    });
+    const calls: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_level, _msg, attrs) {
+        calls.push(attrs);
+      },
+    });
+
+    logger.info("ping", { route: "/" });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual({
+      "deco.runtime.version": "4.4.0",
+      "deployment.environment": "production",
+      route: "/",
+    });
+  });
+
+  it("lets caller attrs override the floor on key collision", () => {
+    setLoggerAttributeFloor({ "deployment.environment": "production" });
+    const calls: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_level, _msg, attrs) {
+        calls.push(attrs);
+      },
+    });
+
+    logger.warn("override", { "deployment.environment": "staging" });
+
+    expect(calls[0]?.["deployment.environment"]).toBe("staging");
+  });
+
+  it("applies the floor even when the caller passes no attrs", () => {
+    setLoggerAttributeFloor({ tenant: "lebiscuit" });
+    const calls: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_level, _msg, attrs) {
+        calls.push(attrs);
+      },
+    });
+
+    logger.info("no-attrs");
+
+    expect(calls[0]).toEqual({ tenant: "lebiscuit" });
+  });
+
+  it("clearing the floor restores the no-op fast path", () => {
+    setLoggerAttributeFloor({ tenant: "lebiscuit" });
+    setLoggerAttributeFloor({});
+    const calls: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_level, _msg, attrs) {
+        calls.push(attrs);
+      },
+    });
+
+    logger.info("clean", { x: 1 });
+
+    expect(calls[0]).toEqual({ x: 1 });
+  });
+});
+
+describe("serializeError", () => {
+  it("flattens an Error into a JSON-safe shape with stack", () => {
+    const err = new Error("boom");
+    const out = serializeError(err);
+    expect(out).toEqual({ name: "Error", message: "boom", stack: err.stack });
+  });
+
+  it("preserves subclass name (TypeError, RangeError, custom)", () => {
+    expect(serializeError(new TypeError("bad type")).name).toBe("TypeError");
+    class MyErr extends Error {
+      override name = "MyErr";
+    }
+    expect(serializeError(new MyErr("custom")).name).toBe("MyErr");
+  });
+
+  it("survives JSON.stringify round-trip", () => {
+    const err = new Error("round-trip");
+    const out = serializeError(err);
+    expect(() => JSON.parse(JSON.stringify(out))).not.toThrow();
+    expect(JSON.parse(JSON.stringify(out)).message).toBe("round-trip");
+  });
+
+  it("captures plain objects as JSON in message, marking them as NonError", () => {
+    const out = serializeError({ code: 500, body: "vtex down" });
+    expect(out.name).toBe("NonError");
+    expect(out.message).toBe('{"code":500,"body":"vtex down"}');
+    expect(out.stack).toBeUndefined();
+  });
+
+  it("falls back to String() when an object has circular refs", () => {
+    const circ: Record<string, unknown> = { a: 1 };
+    circ.self = circ;
+    const out = serializeError(circ);
+    expect(out.name).toBe("NonError");
+    expect(typeof out.message).toBe("string");
+    expect(out.stack).toBeUndefined();
+  });
+
+  it("handles primitives (string, number, null, undefined)", () => {
+    expect(serializeError("just a string")).toEqual({
+      name: "NonError",
+      message: "just a string",
+    });
+    expect(serializeError(42)).toEqual({ name: "NonError", message: "42" });
+    expect(serializeError(null)).toEqual({ name: "NonError", message: "null" });
+    expect(serializeError(undefined)).toEqual({
+      name: "NonError",
+      message: "undefined",
+    });
+  });
+});
+
+describe("request.id stamping (Phase 1, D-9)", () => {
+  afterEach(() => {
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("stamps request.id from RequestContext on every log line emitted inside a request scope", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const reqWithId = new Request("https://example.com/", {
+      headers: { "x-request-id": "client-supplied-uuid" },
+    });
+    await RequestContext.run(reqWithId, async () => {
+      logger.info("inside-scope", { custom: "yes" });
+    });
+    // Outside the scope, no request.id is stamped — the fast path stays
+    // fast (no allocation, no key) when RequestContext.requestId is null.
+    logger.info("outside-scope", { custom: "no" });
+
+    expect(seen[0]).toMatchObject({
+      "request.id": "client-supplied-uuid",
+      custom: "yes",
+    });
+    expect(seen[1]).toEqual({ custom: "no" });
+    expect(seen[1]).not.toHaveProperty("request.id");
+  });
+
+  it("prefers caller-supplied request.id over the auto-generated one", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const req = new Request("https://example.com/", {
+      headers: { "x-request-id": "from-headers" },
+    });
+
+    await RequestContext.run(req, async () => {
+      // Caller can still override by passing the key directly in attrs.
+      logger.info("override", { "request.id": "explicit-from-caller" });
+    });
+
+    expect(seen[0]?.["request.id"]).toBe("explicit-from-caller");
+  });
+
+  it("falls back to cf-ray when x-request-id is absent", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const req = new Request("https://example.com/", {
+      headers: { "cf-ray": "8a1b2c3d4e5f6a7b" },
+    });
+
+    await RequestContext.run(req, async () => {
+      logger.info("cf-ray-stamped");
+    });
+
+    expect(seen[0]?.["request.id"]).toBe("8a1b2c3d4e5f6a7b");
+  });
+
+  it("generates a fresh UUID when neither header is set", async () => {
+    const { RequestContext } = await import("./requestContext");
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    const req = new Request("https://example.com/");
+
+    await RequestContext.run(req, async () => {
+      logger.info("uuid-stamped");
+    });
+
+    const stamped = seen[0]?.["request.id"];
+    expect(typeof stamped).toBe("string");
+    expect((stamped as string).length).toBeGreaterThan(8);
+  });
+});
+
+describe("trace correlation", () => {
+  afterEach(() => {
+    configureLogger(defaultLoggerAdapter);
+    setLogLevel("info");
+  });
+
+  it("includes trace_id/span_id when emitted inside withTracing", async () => {
+    const { configureTracer, setObservabilitySpanStore, withTracing } = await import(
+      "./observability"
+    );
+
+    let current: unknown = null;
+    setObservabilitySpanStore({
+      get: () => current as never,
+      run<R>(value: never, fn: () => R): R {
+        const prev = current;
+        current = value;
+        try {
+          const result = fn();
+          if (result instanceof Promise) {
+            return result.finally(() => {
+              current = prev;
+            }) as unknown as R;
+          }
+          current = prev;
+          return result;
+        } catch (err) {
+          current = prev;
+          throw err;
+        }
+      },
+    });
+    configureTracer({
+      startSpan: () => ({
+        end: () => {},
+        spanContext: () => ({
+          traceId: "deadbeefdeadbeefdeadbeefdeadbeef",
+          spanId: "1234567890abcdef",
+          traceFlags: 1,
+        }),
+      }),
+    });
+
+    const seen: Array<Record<string, unknown> | undefined> = [];
+    configureLogger({
+      log(_l, _m, attrs) {
+        seen.push(attrs);
+      },
+    });
+
+    await withTracing("t", async () => {
+      logger.info("inside-span", { custom: "yes" });
+    });
+    logger.info("outside-span", { custom: "no" });
+
+    expect(seen[0]).toMatchObject({
+      trace_id: "deadbeefdeadbeefdeadbeefdeadbeef",
+      span_id: "1234567890abcdef",
+      custom: "yes",
+    });
+    expect(seen[1]).toEqual({ custom: "no" });
+
+    setObservabilitySpanStore(undefined);
+  });
+});