@pplethai/cli 0.6.0 → 0.8.0

package/templates/golden-path/src/read-dataset.ts

@@ -0,0 +1,376 @@
+// A Consumer's read of one Dataset Object Type (ADR-0030). The Builder names
+// the entry and the Object Type. This module adds the services address, the
+// App Key, and — only when the caller passes one — the user token. It builds
+// the filter, sort and limit query, looks an object up by id, and follows
+// `next` when asked.
+//
+// Under `npm run dev`, while `DEV_PERSONA` is not `"none"`, the answer comes
+// from the workspace overlay (ADR-0026, `dev-read-dataset.ts`). That branch
+// is compiled out of the production build. Under vitest the fetch is the one
+// the test injected: this module does not read the overlay, which CI does
+// not have.
+
+import { callService, PLATFORM_ERROR_HEADER, type CallServiceEnv } from "./call-service";
+import { answerOfflineRead } from "./dev-read-dataset";
+
+/** One page of a collection. `next` is null on the last page. */
+export interface DatasetPage<T = Record<string, unknown>> {
+  objects: T[];
+  next: string | null;
+  sweptAt: string | null;
+  snapshot: number | null;
+}
+
+/** A singleton, or one object looked up by id. `object` is null when the sweep held none. */
+export interface DatasetObject<T = Record<string, unknown>> {
+  object: T | null;
+  sweptAt: string | null;
+  snapshot: number | null;
+}
+
+export interface DatasetRange {
+  gt?: string | number | boolean;
+  gte?: string | number | boolean;
+  lt?: string | number | boolean;
+  lte?: string | number | boolean;
+}
+
+/** Equality, a list (`in`), or a range on one indexed field. */
+export type DatasetFilterValue =
+  | string
+  | number
+  | boolean
+  | readonly (string | number | boolean)[]
+  | DatasetRange;
+
+interface ReadDatasetCommon {
+  /** End-user PPLE ID token. Sent as `x-pple-user-token` only when set. */
+  userToken?: string;
+  /**
+   * Test seam. Under vitest this is required: `readDataset` does not fall
+   * back to `globalThis.fetch`. Production omits it.
+   */
+  fetchImpl?: typeof fetch;
+}
+
+export interface ReadDatasetPageOptions extends ReadDatasetCommon {
+  shape?: "collection";
+  id?: undefined;
+  /** Equality, a repeated value (`in`), or `{ gt, gte, lt, lte }`. */
+  filter?: Record<string, DatasetFilterValue>;
+  /** `<index>` or `-<index>`. Omitted sorts by id ascending. */
+  sort?: string;
+  limit?: number;
+  /** Opaque cursor from a previous page. Bound to the filters and the sort. */
+  next?: string;
+  /**
+   * Walk `next` until the last page and return every object. `data.next` is
+   * null. If a later page's `snapshot` differs, the walk starts over so one
+   * result does not mix two sweeps. After three such starts the result is
+   * `{ ok: false, error: null }`.
+   */
+  follow?: boolean;
+}
+
+export interface ReadDatasetSingletonOptions extends ReadDatasetCommon {
+  shape: "singleton";
+  id?: undefined;
+  /** Sent as-is. The platform answers `invalid_query` for any query on a singleton. */
+  filter?: Record<string, DatasetFilterValue>;
+  sort?: string;
+  limit?: number;
+  next?: string;
+}
+
+export interface ReadDatasetLookupOptions extends ReadDatasetCommon {
+  /** Look up this id. A query string as well is `invalid_query`. */
+  id: string;
+  shape?: "collection" | "singleton";
+  filter?: Record<string, DatasetFilterValue>;
+  sort?: string;
+  limit?: number;
+  next?: string;
+}
+
+export type DatasetSuccess<T> = {
+  ok: true;
+  status: number;
+  etag: string | null;
+  data: T;
+};
+
+/**
+ * A platform or dev refusal. `error` is the `x-pple-error` header, including
+ * the dev-only `no_mock`. `platformError` reads the same header and returns
+ * null for `no_mock` and for any code it does not know. Null `error` means
+ * the header was absent.
+ */
+export type DatasetFailure = {
+  ok: false;
+  status: number;
+  error: string | null;
+};
+
+export type DatasetResult<T> = DatasetSuccess<T> | DatasetFailure;
+
+const RANGE_OPS = ["gt", "gte", "lt", "lte"] as const;
+const FOLLOW_ATTEMPTS = 3;
+
+/**
+ * `GET services.<domain>/<provider>/<name>/<objectType>[/<id>]`.
+ *
+ * A collection (the default) is a page. `shape: "singleton"` or `id` is one
+ * object. `follow: true` walks a collection to the end. The App Key is always
+ * `Authorization: Bearer`.
+ */
+export async function readDataset<T extends Record<string, unknown> = Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetLookupOptions,
+): Promise<DatasetResult<DatasetObject<T>>>;
+export async function readDataset<T extends Record<string, unknown> = Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetSingletonOptions,
+): Promise<DatasetResult<DatasetObject<T>>>;
+export async function readDataset<T extends Record<string, unknown> = Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options?: ReadDatasetPageOptions,
+): Promise<DatasetResult<DatasetPage<T>>>;
+export async function readDataset<T extends Record<string, unknown> = Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetPageOptions | ReadDatasetSingletonOptions | ReadDatasetLookupOptions = {},
+): Promise<DatasetResult<DatasetPage<T> | DatasetObject<T>>> {
+  if (!/^[^/\s]+\/[^/\s]+$/.test(entry)) {
+    throw new Error('readDataset entry must be "<provider>/<name>"');
+  }
+  if (objectType === "" || /[/\s?#]/.test(objectType)) {
+    throw new Error("readDataset objectType must be one path segment");
+  }
+  if ("id" in options && options.id === "") {
+    throw new Error("readDataset id must not be empty");
+  }
+
+  if (isPageRequest(options) && options.follow === true) {
+    return followPages(env, entry, objectType, options);
+  }
+  return readOnce(env, entry, objectType, options);
+}
+
+async function followPages<T extends Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetPageOptions,
+): Promise<DatasetResult<DatasetPage<T>>> {
+  let cursor = options.next;
+  for (let attempt = 0; attempt < FOLLOW_ATTEMPTS; attempt++) {
+    const walked = await walkPages<T>(env, entry, objectType, options, cursor);
+    if (walked.outcome !== "moved") return walked.result;
+    cursor = undefined;
+  }
+  // The snapshot kept moving. There is no platform code for that.
+  return { ok: false, status: 200, error: null };
+}
+
+async function walkPages<T extends Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetPageOptions,
+  cursor: string | undefined,
+): Promise<{ outcome: "done"; result: DatasetResult<DatasetPage<T>> } | { outcome: "moved" }> {
+  const first = await readOnce<T>(env, entry, objectType, pageOptions(options, cursor));
+  if (!first.ok) return { outcome: "done", result: first };
+  if (!isPage<T>(first.data)) return { outcome: "done", result: { ok: false, status: first.status, error: null } };
+
+  const objects = [...first.data.objects];
+  let next = first.data.next;
+  const snapshot = first.data.snapshot;
+  let sweptAt = first.data.sweptAt;
+  let etag = first.etag;
+  let status = first.status;
+  const seen = new Set<string>();
+  while (next !== null) {
+    if (seen.has(next)) return { outcome: "done", result: { ok: false, status: 400, error: null } };
+    seen.add(next);
+    const page = await readOnce<T>(env, entry, objectType, pageOptions(options, next));
+    if (!page.ok) return { outcome: "done", result: page };
+    if (!isPage<T>(page.data)) return { outcome: "done", result: { ok: false, status: page.status, error: null } };
+    if (page.data.snapshot !== snapshot) return { outcome: "moved" };
+    objects.push(...page.data.objects);
+    next = page.data.next;
+    sweptAt = page.data.sweptAt;
+    etag = page.etag;
+    status = page.status;
+  }
+  return {
+    outcome: "done",
+    result: { ok: true, status, etag, data: { objects, next: null, sweptAt, snapshot } },
+  };
+}
+
+function pageOptions(options: ReadDatasetPageOptions, next: string | undefined): ReadDatasetPageOptions {
+  const rest: ReadDatasetPageOptions = { ...options, follow: false };
+  if (next === undefined) {
+    delete rest.next;
+    return rest;
+  }
+  return { ...rest, next };
+}
+
+async function readOnce<T extends Record<string, unknown>>(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetPageOptions | ReadDatasetSingletonOptions | ReadDatasetLookupOptions,
+): Promise<DatasetResult<DatasetPage<T> | DatasetObject<T>>> {
+  const response = await load(env, entry, objectType, options);
+  const error = response.headers.get(PLATFORM_ERROR_HEADER);
+  if (error !== null) return { ok: false, status: response.status, error };
+  if (!response.ok) return { ok: false, status: response.status, error: null };
+
+  const body = (await response.json().catch(() => null)) as unknown;
+  const etag = response.headers.get("etag");
+  if (isObjectRequest(options)) {
+    const data = asObject<T>(body);
+    if (!data) return { ok: false, status: response.status, error: null };
+    return { ok: true, status: response.status, etag, data };
+  }
+  const data = asPage<T>(body);
+  if (!data) return { ok: false, status: response.status, error: null };
+  return { ok: true, status: response.status, etag, data };
+}
+
+function load(
+  env: CallServiceEnv,
+  entry: string,
+  objectType: string,
+  options: ReadDatasetPageOptions | ReadDatasetSingletonOptions | ReadDatasetLookupOptions,
+): Promise<Response> {
+  const search = datasetSearch(options);
+  // `import.meta.env.DEV` is false in the production build, so this branch
+  // and `dev-read-dataset.ts` are absent from the deployed Worker. Vitest
+  // keeps the injected fetch even when a Persona is set.
+  if (import.meta.env.DEV && env.DEV_PERSONA !== "none" && !underVitest()) {
+    return Promise.resolve(answerOfflineRead(env, entry, objectType, {
+      id: "id" in options ? options.id : undefined,
+      search,
+      userToken: options.userToken,
+    }));
+  }
+  const id = "id" in options ? options.id : undefined;
+  return callService(env, entry, datasetPath(objectType, id, search), { method: "GET" }, {
+    userToken: options.userToken,
+    fetchImpl: options.fetchImpl,
+  });
+}
+
+function datasetPath(
+  objectType: string,
+  id: string | undefined,
+  search: readonly (readonly [string, string])[],
+): string {
+  const head = id !== undefined
+    ? `${encodeURIComponent(objectType)}/${encodeURIComponent(id)}`
+    : encodeURIComponent(objectType);
+  if (search.length === 0) return head;
+  const params = new URLSearchParams();
+  for (const [key, value] of search) params.append(key, value);
+  return `${head}?${params.toString()}`;
+}
+
+function datasetSearch(
+  options: ReadDatasetPageOptions | ReadDatasetSingletonOptions | ReadDatasetLookupOptions,
+): [string, string][] {
+  const entries: [string, string][] = [];
+  const filter = "filter" in options ? options.filter : undefined;
+  if (filter) {
+    for (const [field, value] of Object.entries(filter)) {
+      if (Array.isArray(value)) {
+        for (const item of value) entries.push([field, String(item)]);
+        continue;
+      }
+      if (isRange(value)) {
+        for (const op of RANGE_OPS) {
+          const bound = value[op];
+          if (bound !== undefined) entries.push([`${field}[${op}]`, String(bound)]);
+        }
+        continue;
+      }
+      entries.push([field, String(value)]);
+    }
+  }
+  if (options.sort !== undefined) entries.push(["sort", options.sort]);
+  if (options.limit !== undefined) entries.push(["limit", String(options.limit)]);
+  if (options.next !== undefined) entries.push(["next", options.next]);
+  return entries;
+}
+
+function isRange(value: DatasetFilterValue): value is DatasetRange {
+  if (typeof value !== "object") return false;
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => key === "gt" || key === "gte" || key === "lt" || key === "lte");
+}
+
+function isPageRequest(
+  options: ReadDatasetPageOptions | ReadDatasetSingletonOptions | ReadDatasetLookupOptions,
+): options is ReadDatasetPageOptions {
+  return !("id" in options && options.id !== undefined) && options.shape !== "singleton";
+}
+
+function isObjectRequest(
+  options: ReadDatasetPageOptions | ReadDatasetSingletonOptions | ReadDatasetLookupOptions,
+): boolean {
+  return ("id" in options && options.id !== undefined) || options.shape === "singleton";
+}
+
+function isPage<T>(data: DatasetPage<T> | DatasetObject<T>): data is DatasetPage<T> {
+  return "objects" in data;
+}
+
+function asPage<T extends Record<string, unknown>>(body: unknown): DatasetPage<T> | null {
+  if (!isRecord(body) || !Array.isArray(body.objects)) return null;
+  if (!body.objects.every((item) => isRecord(item))) return null;
+  if (!(body.next === null || typeof body.next === "string")) return null;
+  const sweptAt = asSweptAt(body.sweptAt);
+  const snapshot = asSnapshot(body.snapshot);
+  if (sweptAt === undefined || snapshot === undefined) return null;
+  return { objects: body.objects as T[], next: body.next, sweptAt, snapshot };
+}
+
+function asObject<T extends Record<string, unknown>>(body: unknown): DatasetObject<T> | null {
+  if (!isRecord(body)) return null;
+  if (!(body.object === null || isRecord(body.object))) return null;
+  const sweptAt = asSweptAt(body.sweptAt);
+  const snapshot = asSnapshot(body.snapshot);
+  if (sweptAt === undefined || snapshot === undefined) return null;
+  return { object: body.object as T | null, sweptAt, snapshot };
+}
+
+function asSweptAt(value: unknown): string | null | undefined {
+  if (value === null) return null;
+  if (typeof value === "string") return value;
+  return undefined;
+}
+
+function asSnapshot(value: unknown): number | null | undefined {
+  if (value === null) return null;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function underVitest(): boolean {
+  const flag = import.meta.env.VITEST;
+  return import.meta.env.MODE === "test" || flag === true || flag === "true";
+}

package/templates/golden-path/src/registry.ts

@@ -0,0 +1,122 @@
+// A Builder Service or Dataset (ADR-0024, ADR-0027). The platform calls
+// `registry[name]` on the Worker default export at `/.pple/registry/<name>/…`.
+// `serviceCall` reads who is calling from the headers the platform set. It
+// returns null for any other request, including public traffic: the wrapper
+// strips `x-pple-*` before app code sees it. Under `npm run dev` the template
+// emulates that path and those headers; that emulation is compiled out of
+// production.
+//
+// The Identity is one header, `x-pple-identity`: base64url (RFC 4648 §5, no
+// padding) of the UTF-8 JSON `{ actor, effective }`. A Thai name is not a
+// reliable raw header value. The header is absent when the entry declares
+// `userToken: none`, and then `identity` is null. The user's token is never
+// one of these headers.
+
+import { IdentitySchema, type Identity } from "../shared/api";
+import type { Env } from "./env";
+
+export const CONSUMER_HEADER = "x-pple-consumer";
+export const ENTRY_HEADER = "x-pple-entry";
+export const IDENTITY_HEADER = "x-pple-identity";
+
+export interface ServiceCall {
+  /** The Consumer, named from its App Key. */
+  consumer: string;
+  /** `<provider>/<name>`. */
+  entry: string;
+  /**
+   * Effective (including `sub`), Actor, and `effective.isDelegated`. Null
+   * when the entry declares `userToken: none`: nothing about the user was
+   * passed.
+   */
+  identity: Identity | null;
+}
+
+/** Fetch-shaped, so a Hono app (which has `.fetch`) plugs straight in. */
+export type RegistryFetch = (
+  request: Request,
+  env: Env,
+  ctx: ExecutionContext,
+) => Response | Promise<Response>;
+
+export type RegistryHandler = RegistryFetch | { fetch: RegistryFetch };
+
+/** What a Dataset page function is called with. `cursor` is null on the first page. */
+export interface PageInput {
+  cursor: string | null;
+}
+
+/**
+ * One page of a collection. `next` is the Provider's own cursor, or null on
+ * the last page. `subs` is the swept audience, and only on the last page.
+ */
+export interface CollectionPage<T = unknown> {
+  objects: T[];
+  next: string | null;
+  subs?: string[];
+}
+
+/** A singleton. `object` is null when the Dataset currently holds none. `subs` sits beside it. */
+export interface SingletonPage<T = unknown> {
+  object: T | null;
+  subs?: string[];
+}
+
+export type CollectionPageFunction<T = unknown> = (
+  input: PageInput,
+  env: Env,
+  ctx: ExecutionContext,
+) => CollectionPage<T> | Promise<CollectionPage<T>>;
+
+export type SingletonPageFunction<T = unknown> = (
+  input: PageInput,
+  env: Env,
+  ctx: ExecutionContext,
+) => SingletonPage<T> | Promise<SingletonPage<T>>;
+
+/** One Object Type's page function. The declared shape says which return to write. */
+export type ObjectTypePageFunction<T = unknown> = CollectionPageFunction<T> | SingletonPageFunction<T>;
+
+/** Page functions for one Dataset, keyed by Object Type name. */
+export type DatasetPages = Record<string, ObjectTypePageFunction>;
+
+/**
+ * Service handlers and Dataset page functions, keyed by the entry name.
+ * A Service value is fetch-shaped. A Dataset value is {@link DatasetPages}.
+ */
+export type RegistryMap = Record<string, RegistryHandler | DatasetPages>;
+
+export interface PpleWorker {
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Response | Promise<Response>;
+  registry?: RegistryMap;
+}
+
+function decodeIdentity(value: string): Identity | null {
+  try {
+    const pad = value.length % 4 === 0 ? "" : "=".repeat(4 - (value.length % 4));
+    const binary = atob(value.replace(/-/g, "+").replace(/_/g, "/") + pad);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    const identity = IdentitySchema.safeParse(parsed);
+    return identity.success ? identity.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Who is calling this Service, or null when the request is not a platform
+ * registry call. Never includes the user's token.
+ */
+export function serviceCall(request: Request): ServiceCall | null {
+  const consumer = (request.headers.get(CONSUMER_HEADER) ?? "").trim();
+  const entry = (request.headers.get(ENTRY_HEADER) ?? "").trim();
+  if (!consumer || !entry) return null;
+  const encoded = request.headers.get(IDENTITY_HEADER);
+  return {
+    consumer,
+    entry,
+    identity: encoded ? decodeIdentity(encoded) : null,
+  };
+}

package/templates/golden-path/src/vite-env.d.ts

@@ -7,8 +7,21 @@ interface ImportMetaEnv {
   readonly DEV: boolean;
   readonly PROD: boolean;
   readonly MODE: string;
+  /** Set by vitest. Absent from `vite dev` and the production build. */
+  readonly VITEST?: boolean | "true";
 }
 
 interface ImportMeta {
   readonly env: ImportMetaEnv;
+  /**
+   * Vite loads the matched files at build time. The offline overlay glob
+   * keeps `.pple/registry` in the fixed base and sits in an
+   * `import.meta.env.DEV` branch, so the production Worker does not contain it.
+   * `?mtime` is the overlay file's write time (`overlay-mtime.mjs`), used as
+   * `sweptAt` by offline `readDataset`.
+   */
+  glob(
+    pattern: string,
+    options: { eager: true; query: string; import: string },
+  ): Record<string, unknown>;
 }

package/templates/golden-path/test/call-service.test.ts

@@ -0,0 +1,178 @@
+// callService (issue #253). The harness is the platform: tests see the URL,
+// the method, and the headers the Builder would observe, and the record
+// keeps no App Key and no user token.
+
+import { describe, expect, it, vi } from "vitest";
+import { callService, platformError } from "../src/call-service";
+import { makeHarness, serviceRefusal } from "./harness";
+
+const env = {
+  DEV_PERSONA: "none",
+  PPLE_SERVICES_URL: "https://services.test",
+  PPLE_APP_KEY: "app-key",
+};
+
+describe("callService", () => {
+  it("sends the App Key and the user token to the entry URL", async () => {
+    let seen: { authorization: string | null; userToken: string | null; method: string } | undefined;
+    const h = makeHarness(
+      {
+        services: (req) => {
+          seen = {
+            authorization: req.headers.get("authorization"),
+            userToken: req.headers.get("x-pple-user-token"),
+            method: req.method,
+          };
+          return Response.json({ ok: true });
+        },
+      },
+      env,
+    );
+
+    const res = await callService(
+      h.testEnv,
+      "platform/legal-identity",
+      "",
+      {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          authorization: "Bearer caller",
+          "x-pple-user-token": "smuggled",
+        },
+      },
+      { userToken: "user-token", fetchImpl: h.fetchImpl },
+    );
+
+    expect(res.status).toBe(200);
+    expect(seen).toEqual({
+      authorization: "Bearer app-key",
+      userToken: "user-token",
+      method: "POST",
+    });
+    expect(h.calls.services).toEqual([
+      {
+        path: "/platform/legal-identity",
+        method: "POST",
+        headers: { accept: "application/json" },
+      },
+    ]);
+  });
+
+  it("omits the user token unless one was given, and joins the path onto the entry", async () => {
+    let userToken: string | null = "unset";
+    const h = makeHarness(
+      {
+        services: (req) => {
+          userToken = req.headers.get("x-pple-user-token");
+          return new Response(null, { status: 204 });
+        },
+      },
+      { ...env, PPLE_SERVICES_URL: "https://services.test/" },
+    );
+
+    await callService(
+      h.testEnv,
+      "shop/orders",
+      "items/1?limit=2",
+      { method: "GET", headers: { "x-pple-user-token": "smuggled" } },
+      { fetchImpl: h.fetchImpl },
+    );
+
+    expect(userToken).toBeNull();
+    expect(h.calls.services).toEqual([
+      { path: "/shop/orders/items/1?limit=2", method: "GET", headers: {} },
+    ]);
+  });
+
+  it("uses the injected fetch under vitest", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () => new Response("from-injected"));
+    const globalFetch = vi.spyOn(globalThis, "fetch");
+    try {
+      const res = await callService(env, "platform/legal-identity", "?dry=1", { method: "POST" }, {
+        userToken: "t",
+        fetchImpl,
+      });
+      expect(await res.text()).toBe("from-injected");
+      expect(fetchImpl).toHaveBeenCalledOnce();
+      expect(String(fetchImpl.mock.calls[0]?.[0])).toBe("https://services.test/platform/legal-identity?dry=1");
+      expect(globalFetch).not.toHaveBeenCalled();
+    } finally {
+      globalFetch.mockRestore();
+    }
+
+    await expect(callService(env, "platform/legal-identity", "")).rejects.toThrow(/injected fetch/);
+  });
+
+  it("keeps the injected fetch when a persona and DEV_REGISTRY_ERROR are set", async () => {
+    const fetchImpl = vi.fn<typeof fetch>(async () => new Response("from-injected"));
+    const res = await callService(
+      { ...env, DEV_PERSONA: "hq-staff", DEV_REGISTRY_ERROR: "not_granted" },
+      "shop/orders",
+      "/items/1",
+      { method: "GET" },
+      { userToken: "t", fetchImpl },
+    );
+    expect(await res.text()).toBe("from-injected");
+    expect(fetchImpl).toHaveBeenCalledOnce();
+    expect(String(fetchImpl.mock.calls[0]?.[0])).toBe("https://services.test/shop/orders/items/1");
+  });
+
+  it("does not call out without the services URL or the App Key", async () => {
+    const fetchImpl = vi.fn<typeof fetch>();
+    await expect(
+      callService({ PPLE_SERVICES_URL: "https://services.test" }, "platform/legal-identity", "", {}, { fetchImpl }),
+    ).rejects.toThrow(/PPLE_APP_KEY/);
+    await expect(
+      callService({ PPLE_APP_KEY: "app-key" }, "platform/legal-identity", "", {}, { fetchImpl }),
+    ).rejects.toThrow(/PPLE_SERVICES_URL/);
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+});
+
+describe("services fake", () => {
+  it("answers as any Provider and refuses with any x-pple-error code", async () => {
+    const codes = [
+      "invalid_app_key",
+      "not_listed",
+      "not_granted",
+      "needs_beta",
+      "user_token_invalid",
+      "identity_unavailable",
+      "provider_unavailable",
+      "provider_timeout",
+      "no_mock",
+      "made_up",
+    ];
+    let next = Response.json({ items: ["a"] });
+    const h = makeHarness({ services: () => next }, env);
+
+    const answered = await callService(h.testEnv, "shop/catalog", "/search", { method: "GET" }, {
+      fetchImpl: h.fetchImpl,
+    });
+    expect(answered.status).toBe(200);
+    expect(await answered.json()).toEqual({ items: ["a"] });
+    expect(platformError(answered)).toBeNull();
+
+    for (const code of codes) {
+      next = serviceRefusal(code, 418);
+      const res = await callService(h.testEnv, "shop/catalog", "", { method: "POST" }, {
+        userToken: "t",
+        fetchImpl: h.fetchImpl,
+      });
+      expect(res.status).toBe(418);
+      expect(res.headers.get("x-pple-error")).toBe(code);
+      expect(await res.json()).toEqual({ error: code });
+      const known = platformError(res);
+      if (code === "no_mock" || code === "made_up") expect(known).toBeNull();
+      else expect(known).toBe(code);
+    }
+
+    expect(h.calls.services[0]).toEqual({ path: "/shop/catalog/search", method: "GET", headers: {} });
+    expect(h.calls.services).toHaveLength(1 + codes.length);
+    for (const call of h.calls.services) {
+      expect(call.headers).not.toHaveProperty("authorization");
+      expect(call.headers).not.toHaveProperty("x-pple-user-token");
+    }
+  });
+});