@decocms/start 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/src/sdk/index.ts

@@ -11,12 +11,12 @@ export {
   type CacheProfileName,
   type CacheProfileOverrides,
   type CacheTimingWindow,
-  type EdgeCacheConfig,
-  type LoaderCacheOptions,
   cacheHeaders,
   detectCacheProfile,
+  type EdgeCacheConfig,
   edgeCacheConfig,
   getCacheProfile,
+  type LoaderCacheOptions,
   loaderCacheOptions,
   registerCachePattern,
   routeCacheDefaults,
@@ -24,15 +24,26 @@ export {
 } from "./cacheHeaders";
 export { clx } from "./clx";
 export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie } from "./cookie";
+export { forwardResponseCookies, getRequestCookieHeader } from "./cookiePassthrough";
 export { buildCSPHeaderValue, type CSPOptions, setCSPHeaders } from "./csp";
+export { djb2, djb2Hex } from "./djb2";
 export { isDevMode } from "./env";
+export { buildHtmlShell, type HtmlShellOptions } from "./htmlShell";
 export {
   createInstrumentedFetch,
   type FetchInstrumentationOptions,
   type FetchMetrics,
   instrumentFetch,
 } from "./instrumentedFetch";
-export { batchInvoke, createInvokeProxy, type InvokeProxy, invokeQueryOptions } from "./invoke";
+export {
+  batchInvoke,
+  createAppInvoke,
+  createInvokeProxy,
+  type InvokeProxy,
+  invoke,
+  invokeQueryOptions,
+  type NestedFromFlat,
+} from "./invoke";
 export { createCacheControlCollector, mergeCacheControl } from "./mergeCacheControl";
 export {
   getProductionOrigins,
@@ -59,8 +70,6 @@ export {
   registerTrackingParams,
   stripTrackingParams,
 } from "./urlUtils";
-export { djb2, djb2Hex } from "./djb2";
-export { buildHtmlShell, type HtmlShellOptions } from "./htmlShell";
 export {
   checkDesktop,
   checkMobile,
@@ -74,9 +83,14 @@ export {
 } from "./useDevice";
 export { useHydrated } from "./useHydrated";
 export { useId } from "./useId";
-export { inlineScript, usePartialSection, useScript, useScriptAsDataURI, useSection } from "./useScript";
+export {
+  inlineScript,
+  usePartialSection,
+  useScript,
+  useScriptAsDataURI,
+  useSection,
+} from "./useScript";
 export { createDecoWorkerEntry, type DecoWorkerEntryOptions } from "./workerEntry";
-export { forwardResponseCookies, getRequestCookieHeader } from "./cookiePassthrough";
 export {
   isWrappedError,
   unwrapError,

package/src/sdk/invoke.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createAppInvoke, invoke } from "./invoke";
+
+describe("createAppInvoke", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("collects nested property access into slash-separated key", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+
+    const proxy = createAppInvoke();
+    const result = await proxy.vtex.actions.checkout.addItemsToCart({ qty: 1 });
+
+    expect(result).toEqual({ ok: true });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("/deco/invoke/vtex/actions/checkout/addItemsToCart");
+    expect(init.method).toBe("POST");
+    expect(init.headers).toEqual({ "Content-Type": "application/json" });
+    expect(JSON.parse(init.body)).toEqual({ qty: 1 });
+  });
+
+  it("falls back to .ts suffix when first key returns 404", async () => {
+    fetchMock
+      .mockResolvedValueOnce(new Response(null, { status: 404 }))
+      .mockResolvedValueOnce(new Response(JSON.stringify({ via: "ts" }), { status: 200 }));
+
+    const proxy = createAppInvoke();
+    const result = await proxy.site.loaders.Wishlist({});
+
+    expect(result).toEqual({ via: "ts" });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(fetchMock.mock.calls[0][0]).toBe("/deco/invoke/site/loaders/Wishlist");
+    expect(fetchMock.mock.calls[1][0]).toBe("/deco/invoke/site/loaders/Wishlist.ts");
+  });
+
+  it("throws 'handler not found' when both key and .ts variant 404", async () => {
+    fetchMock.mockResolvedValue(new Response(null, { status: 404 }));
+
+    const proxy = createAppInvoke();
+    await expect(proxy.unknown({})).rejects.toThrow(/invoke\(unknown\) failed: handler not found/);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("throws with status and error body on non-OK non-404 response", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ error: "boom" }), { status: 500 }));
+
+    const proxy = createAppInvoke();
+    await expect(proxy.broken({})).rejects.toThrow(/invoke\(broken\) failed \(500\): boom/);
+  });
+
+  it("defaults to empty object body when called with no props", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+
+    const proxy = createAppInvoke();
+    await proxy.foo.bar();
+
+    const init = fetchMock.mock.calls[0][1];
+    expect(JSON.parse(init.body)).toEqual({});
+  });
+
+  it("traps `then`, `catch`, `finally` to avoid being awaited as a thenable", () => {
+    const proxy = createAppInvoke();
+    expect(proxy.then).toBeUndefined();
+    expect(proxy.catch).toBeUndefined();
+    expect(proxy.finally).toBeUndefined();
+    // And on a deeper path:
+    expect(proxy.foo.bar.then).toBeUndefined();
+  });
+
+  it("returns undefined for symbol property access (no spurious sub-proxy)", () => {
+    const proxy = createAppInvoke();
+    expect(proxy[Symbol.toPrimitive]).toBeUndefined();
+    expect(proxy[Symbol.iterator]).toBeUndefined();
+  });
+
+  it("respects custom basePath", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({}), { status: 200 }));
+
+    const proxy = createAppInvoke("/custom/invoke");
+    await proxy.foo.bar({});
+
+    expect(fetchMock.mock.calls[0][0]).toBe("/custom/invoke/foo/bar");
+  });
+});
+
+describe("default invoke singleton", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("is a usable nested proxy bound to /deco/invoke", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+
+    await (invoke as any).site.loaders.example({ x: 1 });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock.mock.calls[0][0]).toBe("/deco/invoke/site/loaders/example");
+  });
+});

package/src/sdk/invoke.ts

@@ -154,29 +154,21 @@ 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 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
+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;
+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]
-  >
+  UnionToIntersection<{ [K in keyof T & string]: BuildNested<K, T[K]> }[keyof T & string]>
 >;
 
 /**
@@ -203,10 +195,10 @@ export type NestedFromFlat<T extends Record<string, any>> = DeepMerge<
  * ```
  */
 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 {
+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) => {
@@ -217,7 +209,10 @@ export function createAppInvoke(
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(props ?? {}),
           });
-          if (response.status === 404) { await response.body?.cancel(); continue; }
+          if (response.status === 404) {
+            await response.body?.cancel();
+            continue;
+          }
           if (!response.ok) {
             const error = await response.json().catch(() => ({ error: response.statusText }));
             throw new Error(
@@ -242,3 +237,24 @@ export function createAppInvoke(
 
   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();