@stardeck-customer-apps/testing 0.27.0 → 0.28.0

package/SKILL.md

@@ -624,6 +624,24 @@ cursor, limit })`; `list()` intentionally keeps its previous array shape.
   `expect(app.schedules.earliestWake("booking-janitor")!.getTime()).toBeLessThanOrEqual(dueAt.getTime())`.
   `app.schedules.wakesFor(key)` lists them; `reset()` clears them. Run the job's handler
   yourself to test what it does and the `nextRun()` it returns.
+- `getControl` / `getControls` / `setControl` from `@stardeck-customer-apps/controls/server` — the
+  sync (`POST /api/deployments/:id/controls`) and write (`PUT .../controls/:key`) routes are
+  simulated, signature-checked like the others, and served from `app.controls`. Defaults are
+  permissive so existing tests keep passing: `flag.paymentsSetupStep: false`,
+  `plan.locations: { included: 3, max: null, extraMonthly: { amount: 990, currency: "THB" } }`,
+  `plan.multiEntity: true`, `payments.provider: "beam"`, `payments.methods: { card: true, promptPay: true }`.
+  Seed with `createTestApp({ controls: { "plan.multiEntity": false } })`. Then
+  `app.controls.set(key, value)` (the next `getControl` in the same process sees it: the
+  controls cache is dropped on every change and on `reset()`),
+  `app.controls.setUnavailable(key)` (that key reads `{ ok: false }`, like a platform outage),
+  `app.controls.lastUsage()` (the usage the app reported on its latest sync, for example
+  `{ locations: 4 }`), `app.controls.writes()` (each `setControl` the app made:
+  `{ key, value, userToken }`) and `app.controls.refuseNextWrite({ code, message, connectUrl? })`
+  (the next write fails once with that error, for example `PROVIDER_NOT_READY` with a connect
+  link). A write needs the person's session token in `X-Stardeck-User-Token`; without it the
+  simulator answers 401 `UNAUTHENTICATED`. Only `payments.provider` and `payments.methods` are
+  writable (anything else is 400 `NOT_WRITABLE`), and an invalid value is 400 `INVALID_VALUE`.
+  `app.controls.clear()` returns to the seeded values. Test the `ok: false` path of every gate.
 
 ### Receipt layout and printer capabilities
 

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
 import * as next_server from 'next/server';
+import { ControlKey, ControlValue, ControlsUsage, ControlWriteErrorCode } from '@stardeck-customer-apps/controls';
 import { PGlite } from '@electric-sql/pglite';
 import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.mjs';
 export { S as STARDECK_DATA_STORES_ENV, a as TestDataStoreManifestEntry, b as buildTestDataStoreManifest } from './data-store-manifest-Zwgcv0DJ.mjs';
@@ -745,7 +746,40 @@ interface TestSchedules {
     earliestWake(scheduleKey: string): Date | undefined;
     clear(): void;
 }
+interface CapturedControlWrite {
+    key: ControlKey;
+    value: unknown;
+    /** The person's session token the app sent in `X-Stardeck-User-Token`. */
+    userToken: string;
+}
+interface ControlRefusal {
+    code: ControlWriteErrorCode;
+    message: string;
+    connectUrl?: string;
+}
+/** The simulated app-controls sync and write routes (`@stardeck-customer-apps/controls`). */
+interface TestControls {
+    /**
+     * Set a control's value (the app sees it on its next `getControl`, with no
+     * stale cache). Also makes a key that was forced unavailable available again.
+     */
+    set<K extends ControlKey>(key: K, value: ControlValue<K>): void;
+    /** Make the sync report this control as `{ ok: false }`, like a platform outage for one key. */
+    setUnavailable(key: ControlKey): void;
+    /** The usage the app reported on its latest sync, or null if it reported none. */
+    lastUsage(): ControlsUsage | null;
+    /** Writes the app made through `setControl`, oldest first. */
+    writes(): CapturedControlWrite[];
+    /** The next write is refused with this error, then writes succeed again. */
+    refuseNextWrite(refusal: ControlRefusal): void;
+    /** Back to the values the test app was created with; clears writes, usage and refusals. */
+    clear(): void;
+}
 interface TestAppOptions {
+    /** Control values the simulated platform serves; unlisted keys keep the permissive defaults. */
+    controls?: Partial<{
+        [K in ControlKey]: ControlValue<K>;
+    }>;
     /**
      * The LIFF ID the platform forwards to the app for a LINE MINI App shop. It is
      * what `GET /api/auth/me` returns as `liffId` and what makes `useLiff()` start
@@ -799,6 +833,8 @@ interface TestApp {
     starlens: TestStarlens;
     /** Wakes the app asked of its adaptive schedules (`wakeSchedule`). */
     schedules: TestSchedules;
+    /** Platform-owned app controls: flags, plan limits, payment provider and methods. */
+    controls: TestControls;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as _stardeck_customer_apps_payments_sdk from '@stardeck-customer-apps/payments-sdk';
 import * as next_server from 'next/server';
+import { ControlKey, ControlValue, ControlsUsage, ControlWriteErrorCode } from '@stardeck-customer-apps/controls';
 import { PGlite } from '@electric-sql/pglite';
 import { T as TestDataStoreInput } from './data-store-manifest-Zwgcv0DJ.js';
 export { S as STARDECK_DATA_STORES_ENV, a as TestDataStoreManifestEntry, b as buildTestDataStoreManifest } from './data-store-manifest-Zwgcv0DJ.js';
@@ -745,7 +746,40 @@ interface TestSchedules {
     earliestWake(scheduleKey: string): Date | undefined;
     clear(): void;
 }
+interface CapturedControlWrite {
+    key: ControlKey;
+    value: unknown;
+    /** The person's session token the app sent in `X-Stardeck-User-Token`. */
+    userToken: string;
+}
+interface ControlRefusal {
+    code: ControlWriteErrorCode;
+    message: string;
+    connectUrl?: string;
+}
+/** The simulated app-controls sync and write routes (`@stardeck-customer-apps/controls`). */
+interface TestControls {
+    /**
+     * Set a control's value (the app sees it on its next `getControl`, with no
+     * stale cache). Also makes a key that was forced unavailable available again.
+     */
+    set<K extends ControlKey>(key: K, value: ControlValue<K>): void;
+    /** Make the sync report this control as `{ ok: false }`, like a platform outage for one key. */
+    setUnavailable(key: ControlKey): void;
+    /** The usage the app reported on its latest sync, or null if it reported none. */
+    lastUsage(): ControlsUsage | null;
+    /** Writes the app made through `setControl`, oldest first. */
+    writes(): CapturedControlWrite[];
+    /** The next write is refused with this error, then writes succeed again. */
+    refuseNextWrite(refusal: ControlRefusal): void;
+    /** Back to the values the test app was created with; clears writes, usage and refusals. */
+    clear(): void;
+}
 interface TestAppOptions {
+    /** Control values the simulated platform serves; unlisted keys keep the permissive defaults. */
+    controls?: Partial<{
+        [K in ControlKey]: ControlValue<K>;
+    }>;
     /**
      * The LIFF ID the platform forwards to the app for a LINE MINI App shop. It is
      * what `GET /api/auth/me` returns as `liffId` and what makes `useLiff()` start
@@ -799,6 +833,8 @@ interface TestApp {
     starlens: TestStarlens;
     /** Wakes the app asked of its adaptive schedules (`wakeSchedule`). */
     schedules: TestSchedules;
+    /** Platform-owned app controls: flags, plan limits, payment provider and methods. */
+    controls: TestControls;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**

package/dist/index.js

@@ -381,6 +381,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 function requireDb() {
@@ -4024,6 +4032,141 @@ function createEdge() {
   };
 }
 
+// src/simulator/controls.ts
+var CONTROLS_STATE_SYMBOL = /* @__PURE__ */ Symbol.for("stardeck.controls.state");
+var USER_TOKEN_HEADER = "x-stardeck-user-token";
+var DEFAULTS = {
+  "flag.paymentsSetupStep": false,
+  "plan.locations": { included: 3, max: null, extraMonthly: { amount: 990, currency: "THB" } },
+  "plan.multiEntity": true,
+  "payments.provider": "beam",
+  "payments.methods": { card: true, promptPay: true }
+};
+var REFUSAL_STATUS = {
+  NOT_WRITABLE: 400,
+  INVALID_VALUE: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  WRITE_NOT_ALLOWED_HERE: 403,
+  PROVIDER_NOT_READY: 409,
+  UNAVAILABLE: 503
+};
+var controlsModule = null;
+function loadControls() {
+  controlsModule ??= import("@stardeck-customer-apps/controls");
+  return controlsModule;
+}
+function resetControlsClientCache() {
+  const clientState = globalThis[CONTROLS_STATE_SYMBOL];
+  clientState?.reset?.();
+}
+function initControls(seed) {
+  state.controls.seed = { ...seed };
+  restoreControls();
+}
+function restoreControls() {
+  state.controls.values = { ...DEFAULTS, ...state.controls.seed };
+  state.controls.unavailable = /* @__PURE__ */ new Set();
+  state.controls.lastUsage = null;
+  state.controls.writes = [];
+  state.controls.refusal = null;
+  resetControlsClientCache();
+}
+function clearControls() {
+  restoreControls();
+}
+function currentControlsBody() {
+  const controls = {};
+  for (const [key, value] of Object.entries(state.controls.values)) {
+    controls[key] = state.controls.unavailable.has(key) ? { ok: false, reason: "unavailable (simulated)" } : { ok: true, value };
+  }
+  return controls;
+}
+function refusalResponse(refusal) {
+  return json({ error: refusal }, REFUSAL_STATUS[refusal.code]);
+}
+function handleSync(body) {
+  const usage = body.usage;
+  if (typeof usage === "object" && usage !== null) {
+    const locations = usage.locations;
+    state.controls.lastUsage = typeof locations === "number" && Number.isInteger(locations) && locations >= 0 ? { locations } : {};
+  }
+  return json({ controls: currentControlsBody() });
+}
+async function handleWrite(request, key) {
+  const { CONTROLS, isWritableControl } = await loadControls();
+  if (!isWritableControl(key)) {
+    return refusalResponse({
+      code: "NOT_WRITABLE",
+      message: `${key} cannot be changed from the app`
+    });
+  }
+  const userToken = request.headers.get(USER_TOKEN_HEADER);
+  if (!userToken) {
+    return refusalResponse({
+      code: "UNAUTHENTICATED",
+      message: "A signed-in person is required (X-Stardeck-User-Token)"
+    });
+  }
+  const body = await readJsonBody(request);
+  const parsed = CONTROLS[key].schema.safeParse(body.value);
+  if (!parsed.success) {
+    return refusalResponse({
+      code: "INVALID_VALUE",
+      message: parsed.error.issues[0]?.message ?? "Invalid value"
+    });
+  }
+  const refusal = state.controls.refusal;
+  if (refusal) {
+    state.controls.refusal = null;
+    return refusalResponse(refusal);
+  }
+  state.controls.values[key] = parsed.data;
+  state.controls.unavailable.delete(key);
+  state.controls.writes.push({ key, value: parsed.data, userToken });
+  return json({ controls: currentControlsBody() });
+}
+var CONTROLS_PATH = /^\/api\/deployments\/[^/]+\/controls(?:\/([^/]+))?$/;
+async function handleControlsRequest(request, url) {
+  const match = url.pathname.match(CONTROLS_PATH);
+  const key = match?.[1] ? decodeURIComponent(match[1]) : null;
+  if (!key && request.method === "POST") {
+    return handleSync(await readJsonBody(request));
+  }
+  if (key && request.method === "PUT") {
+    return handleWrite(request, key);
+  }
+  return json(
+    {
+      error: { code: "UNAVAILABLE", message: `No simulator for ${request.method} ${url.pathname}` }
+    },
+    404
+  );
+}
+function createControls() {
+  return {
+    set(key, value) {
+      state.controls.values[key] = value;
+      state.controls.unavailable.delete(key);
+      resetControlsClientCache();
+    },
+    setUnavailable(key) {
+      state.controls.unavailable.add(key);
+      resetControlsClientCache();
+    },
+    lastUsage() {
+      return state.controls.lastUsage;
+    },
+    writes() {
+      return state.controls.writes;
+    },
+    refuseNextWrite(refusal) {
+      state.controls.refusal = refusal;
+    },
+    clear: restoreControls
+  };
+}
+
 // src/simulator/schedules.ts
 async function handleScheduleWake(request, scheduleKey) {
   if (request.method !== "POST") return failure(`Method ${request.method} not allowed`, 405);
@@ -4215,8 +4358,10 @@ function requiresDeploymentHmac(request, url) {
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStarlens = url.pathname === "/api/starlens/extract";
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
-  return !!(isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const controlsMatch = url.pathname.match(CONTROLS_PATH2);
+  return !!(controlsMatch || isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
+var CONTROLS_PATH2 = /^\/api\/deployments\/[^/]+\/controls(\/[^/]+)?$/;
 var SCHEDULE_WAKE_PATH = /^\/api\/deployments\/[^/]+\/schedules\/([^/]+)\/wake$/;
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -4284,6 +4429,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (CONTROLS_PATH2.test(url.pathname)) {
+    return handleControlsRequest(request, url);
+  }
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
   if (scheduleWakeMatch) {
     return handleScheduleWake(request, decodeURIComponent(scheduleWakeMatch[1]));
@@ -4312,7 +4460,7 @@ async function handleSimulatedRequest(request, url) {
     }
   }
   return failure(
-    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
+    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, app controls sync/write, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
     404
   );
 }
@@ -4461,6 +4609,7 @@ async function createTestApp(options = {}) {
   const initialLiffId = options.liffId ?? null;
   state.liffId = initialLiffId;
   installFetchRouter();
+  initControls(options.controls);
   const schemaSql = loadSchemaSql(options) ?? "";
   const db = await bootWithSchema(schemaSql);
   state.db = db;
@@ -4492,6 +4641,7 @@ async function createTestApp(options = {}) {
   const edge = createEdge();
   const starlens = createStarlens();
   const schedules = createSchedules();
+  const controls = createControls();
   const app = {
     db,
     inbox,
@@ -4502,6 +4652,7 @@ async function createTestApp(options = {}) {
     edge,
     starlens,
     schedules,
+    controls,
     async query(sql, params = []) {
       const result = await db.query(sql, params);
       return result.rows;
@@ -4551,6 +4702,7 @@ async function createTestApp(options = {}) {
       edge.clear();
       starlens.clear();
       schedules.clear();
+      clearControls();
     },
     async close() {
       state.db = null;
@@ -4567,6 +4719,7 @@ async function createTestApp(options = {}) {
       edge.clear();
       starlens.clear();
       schedules.clear();
+      clearControls();
       uninstallFetchRouter();
       await db.close();
     }

package/dist/index.mjs

@@ -342,6 +342,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 function requireDb() {
@@ -3985,6 +3993,141 @@ function createEdge() {
   };
 }
 
+// src/simulator/controls.ts
+var CONTROLS_STATE_SYMBOL = /* @__PURE__ */ Symbol.for("stardeck.controls.state");
+var USER_TOKEN_HEADER = "x-stardeck-user-token";
+var DEFAULTS = {
+  "flag.paymentsSetupStep": false,
+  "plan.locations": { included: 3, max: null, extraMonthly: { amount: 990, currency: "THB" } },
+  "plan.multiEntity": true,
+  "payments.provider": "beam",
+  "payments.methods": { card: true, promptPay: true }
+};
+var REFUSAL_STATUS = {
+  NOT_WRITABLE: 400,
+  INVALID_VALUE: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  WRITE_NOT_ALLOWED_HERE: 403,
+  PROVIDER_NOT_READY: 409,
+  UNAVAILABLE: 503
+};
+var controlsModule = null;
+function loadControls() {
+  controlsModule ??= import("@stardeck-customer-apps/controls");
+  return controlsModule;
+}
+function resetControlsClientCache() {
+  const clientState = globalThis[CONTROLS_STATE_SYMBOL];
+  clientState?.reset?.();
+}
+function initControls(seed) {
+  state.controls.seed = { ...seed };
+  restoreControls();
+}
+function restoreControls() {
+  state.controls.values = { ...DEFAULTS, ...state.controls.seed };
+  state.controls.unavailable = /* @__PURE__ */ new Set();
+  state.controls.lastUsage = null;
+  state.controls.writes = [];
+  state.controls.refusal = null;
+  resetControlsClientCache();
+}
+function clearControls() {
+  restoreControls();
+}
+function currentControlsBody() {
+  const controls = {};
+  for (const [key, value] of Object.entries(state.controls.values)) {
+    controls[key] = state.controls.unavailable.has(key) ? { ok: false, reason: "unavailable (simulated)" } : { ok: true, value };
+  }
+  return controls;
+}
+function refusalResponse(refusal) {
+  return json({ error: refusal }, REFUSAL_STATUS[refusal.code]);
+}
+function handleSync(body) {
+  const usage = body.usage;
+  if (typeof usage === "object" && usage !== null) {
+    const locations = usage.locations;
+    state.controls.lastUsage = typeof locations === "number" && Number.isInteger(locations) && locations >= 0 ? { locations } : {};
+  }
+  return json({ controls: currentControlsBody() });
+}
+async function handleWrite(request, key) {
+  const { CONTROLS, isWritableControl } = await loadControls();
+  if (!isWritableControl(key)) {
+    return refusalResponse({
+      code: "NOT_WRITABLE",
+      message: `${key} cannot be changed from the app`
+    });
+  }
+  const userToken = request.headers.get(USER_TOKEN_HEADER);
+  if (!userToken) {
+    return refusalResponse({
+      code: "UNAUTHENTICATED",
+      message: "A signed-in person is required (X-Stardeck-User-Token)"
+    });
+  }
+  const body = await readJsonBody(request);
+  const parsed = CONTROLS[key].schema.safeParse(body.value);
+  if (!parsed.success) {
+    return refusalResponse({
+      code: "INVALID_VALUE",
+      message: parsed.error.issues[0]?.message ?? "Invalid value"
+    });
+  }
+  const refusal = state.controls.refusal;
+  if (refusal) {
+    state.controls.refusal = null;
+    return refusalResponse(refusal);
+  }
+  state.controls.values[key] = parsed.data;
+  state.controls.unavailable.delete(key);
+  state.controls.writes.push({ key, value: parsed.data, userToken });
+  return json({ controls: currentControlsBody() });
+}
+var CONTROLS_PATH = /^\/api\/deployments\/[^/]+\/controls(?:\/([^/]+))?$/;
+async function handleControlsRequest(request, url) {
+  const match = url.pathname.match(CONTROLS_PATH);
+  const key = match?.[1] ? decodeURIComponent(match[1]) : null;
+  if (!key && request.method === "POST") {
+    return handleSync(await readJsonBody(request));
+  }
+  if (key && request.method === "PUT") {
+    return handleWrite(request, key);
+  }
+  return json(
+    {
+      error: { code: "UNAVAILABLE", message: `No simulator for ${request.method} ${url.pathname}` }
+    },
+    404
+  );
+}
+function createControls() {
+  return {
+    set(key, value) {
+      state.controls.values[key] = value;
+      state.controls.unavailable.delete(key);
+      resetControlsClientCache();
+    },
+    setUnavailable(key) {
+      state.controls.unavailable.add(key);
+      resetControlsClientCache();
+    },
+    lastUsage() {
+      return state.controls.lastUsage;
+    },
+    writes() {
+      return state.controls.writes;
+    },
+    refuseNextWrite(refusal) {
+      state.controls.refusal = refusal;
+    },
+    clear: restoreControls
+  };
+}
+
 // src/simulator/schedules.ts
 async function handleScheduleWake(request, scheduleKey) {
   if (request.method !== "POST") return failure(`Method ${request.method} not allowed`, 405);
@@ -4176,8 +4319,10 @@ function requiresDeploymentHmac(request, url) {
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStarlens = url.pathname === "/api/starlens/extract";
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
-  return !!(isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const controlsMatch = url.pathname.match(CONTROLS_PATH2);
+  return !!(controlsMatch || isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
+var CONTROLS_PATH2 = /^\/api\/deployments\/[^/]+\/controls(\/[^/]+)?$/;
 var SCHEDULE_WAKE_PATH = /^\/api\/deployments\/[^/]+\/schedules\/([^/]+)\/wake$/;
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -4245,6 +4390,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (CONTROLS_PATH2.test(url.pathname)) {
+    return handleControlsRequest(request, url);
+  }
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
   if (scheduleWakeMatch) {
     return handleScheduleWake(request, decodeURIComponent(scheduleWakeMatch[1]));
@@ -4273,7 +4421,7 @@ async function handleSimulatedRequest(request, url) {
     }
   }
   return failure(
-    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
+    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, app controls sync/write, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
     404
   );
 }
@@ -4422,6 +4570,7 @@ async function createTestApp(options = {}) {
   const initialLiffId = options.liffId ?? null;
   state.liffId = initialLiffId;
   installFetchRouter();
+  initControls(options.controls);
   const schemaSql = loadSchemaSql(options) ?? "";
   const db = await bootWithSchema(schemaSql);
   state.db = db;
@@ -4453,6 +4602,7 @@ async function createTestApp(options = {}) {
   const edge = createEdge();
   const starlens = createStarlens();
   const schedules = createSchedules();
+  const controls = createControls();
   const app = {
     db,
     inbox,
@@ -4463,6 +4613,7 @@ async function createTestApp(options = {}) {
     edge,
     starlens,
     schedules,
+    controls,
     async query(sql, params = []) {
       const result = await db.query(sql, params);
       return result.rows;
@@ -4512,6 +4663,7 @@ async function createTestApp(options = {}) {
       edge.clear();
       starlens.clear();
       schedules.clear();
+      clearControls();
     },
     async close() {
       state.db = null;
@@ -4528,6 +4680,7 @@ async function createTestApp(options = {}) {
       edge.clear();
       starlens.clear();
       schedules.clear();
+      clearControls();
       uninstallFetchRouter();
       await db.close();
     }

package/dist/next/headers-shim.js

@@ -103,6 +103,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 

package/dist/next/headers-shim.mjs

@@ -76,6 +76,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 

package/dist/setup.js

@@ -108,6 +108,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 function requireDb() {
@@ -3010,6 +3018,91 @@ async function handleEdgeRequest(request, subPath) {
   return edgeFailure(`No edge simulator for ${method} .../edge${subPath}`, 404);
 }
 
+// src/simulator/controls.ts
+var USER_TOKEN_HEADER = "x-stardeck-user-token";
+var REFUSAL_STATUS = {
+  NOT_WRITABLE: 400,
+  INVALID_VALUE: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  WRITE_NOT_ALLOWED_HERE: 403,
+  PROVIDER_NOT_READY: 409,
+  UNAVAILABLE: 503
+};
+var controlsModule = null;
+function loadControls() {
+  controlsModule ??= import("@stardeck-customer-apps/controls");
+  return controlsModule;
+}
+function currentControlsBody() {
+  const controls = {};
+  for (const [key, value] of Object.entries(state.controls.values)) {
+    controls[key] = state.controls.unavailable.has(key) ? { ok: false, reason: "unavailable (simulated)" } : { ok: true, value };
+  }
+  return controls;
+}
+function refusalResponse(refusal) {
+  return json({ error: refusal }, REFUSAL_STATUS[refusal.code]);
+}
+function handleSync(body) {
+  const usage = body.usage;
+  if (typeof usage === "object" && usage !== null) {
+    const locations = usage.locations;
+    state.controls.lastUsage = typeof locations === "number" && Number.isInteger(locations) && locations >= 0 ? { locations } : {};
+  }
+  return json({ controls: currentControlsBody() });
+}
+async function handleWrite(request, key) {
+  const { CONTROLS, isWritableControl } = await loadControls();
+  if (!isWritableControl(key)) {
+    return refusalResponse({
+      code: "NOT_WRITABLE",
+      message: `${key} cannot be changed from the app`
+    });
+  }
+  const userToken = request.headers.get(USER_TOKEN_HEADER);
+  if (!userToken) {
+    return refusalResponse({
+      code: "UNAUTHENTICATED",
+      message: "A signed-in person is required (X-Stardeck-User-Token)"
+    });
+  }
+  const body = await readJsonBody(request);
+  const parsed = CONTROLS[key].schema.safeParse(body.value);
+  if (!parsed.success) {
+    return refusalResponse({
+      code: "INVALID_VALUE",
+      message: parsed.error.issues[0]?.message ?? "Invalid value"
+    });
+  }
+  const refusal = state.controls.refusal;
+  if (refusal) {
+    state.controls.refusal = null;
+    return refusalResponse(refusal);
+  }
+  state.controls.values[key] = parsed.data;
+  state.controls.unavailable.delete(key);
+  state.controls.writes.push({ key, value: parsed.data, userToken });
+  return json({ controls: currentControlsBody() });
+}
+var CONTROLS_PATH = /^\/api\/deployments\/[^/]+\/controls(?:\/([^/]+))?$/;
+async function handleControlsRequest(request, url) {
+  const match = url.pathname.match(CONTROLS_PATH);
+  const key = match?.[1] ? decodeURIComponent(match[1]) : null;
+  if (!key && request.method === "POST") {
+    return handleSync(await readJsonBody(request));
+  }
+  if (key && request.method === "PUT") {
+    return handleWrite(request, key);
+  }
+  return json(
+    {
+      error: { code: "UNAVAILABLE", message: `No simulator for ${request.method} ${url.pathname}` }
+    },
+    404
+  );
+}
+
 // src/simulator/schedules.ts
 async function handleScheduleWake(request, scheduleKey) {
   if (request.method !== "POST") return failure(`Method ${request.method} not allowed`, 405);
@@ -3158,8 +3251,10 @@ function requiresDeploymentHmac(request, url) {
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStarlens = url.pathname === "/api/starlens/extract";
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
-  return !!(isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const controlsMatch = url.pathname.match(CONTROLS_PATH2);
+  return !!(controlsMatch || isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
+var CONTROLS_PATH2 = /^\/api\/deployments\/[^/]+\/controls(\/[^/]+)?$/;
 var SCHEDULE_WAKE_PATH = /^\/api\/deployments\/[^/]+\/schedules\/([^/]+)\/wake$/;
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -3227,6 +3322,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (CONTROLS_PATH2.test(url.pathname)) {
+    return handleControlsRequest(request, url);
+  }
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
   if (scheduleWakeMatch) {
     return handleScheduleWake(request, decodeURIComponent(scheduleWakeMatch[1]));
@@ -3255,7 +3353,7 @@ async function handleSimulatedRequest(request, url) {
     }
   }
   return failure(
-    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
+    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, app controls sync/write, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
     404
   );
 }

package/dist/setup.mjs

@@ -84,6 +84,14 @@ var state = globalSingleton("state", () => ({
   starlensCalls: [],
   starlensReplies: [],
   starlensDefaultReply: null,
+  controls: {
+    seed: {},
+    values: {},
+    unavailable: /* @__PURE__ */ new Set(),
+    lastUsage: null,
+    writes: [],
+    refusal: null
+  },
   allowNetwork: false
 }));
 function requireDb() {
@@ -2986,6 +2994,91 @@ async function handleEdgeRequest(request, subPath) {
   return edgeFailure(`No edge simulator for ${method} .../edge${subPath}`, 404);
 }
 
+// src/simulator/controls.ts
+var USER_TOKEN_HEADER = "x-stardeck-user-token";
+var REFUSAL_STATUS = {
+  NOT_WRITABLE: 400,
+  INVALID_VALUE: 400,
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  WRITE_NOT_ALLOWED_HERE: 403,
+  PROVIDER_NOT_READY: 409,
+  UNAVAILABLE: 503
+};
+var controlsModule = null;
+function loadControls() {
+  controlsModule ??= import("@stardeck-customer-apps/controls");
+  return controlsModule;
+}
+function currentControlsBody() {
+  const controls = {};
+  for (const [key, value] of Object.entries(state.controls.values)) {
+    controls[key] = state.controls.unavailable.has(key) ? { ok: false, reason: "unavailable (simulated)" } : { ok: true, value };
+  }
+  return controls;
+}
+function refusalResponse(refusal) {
+  return json({ error: refusal }, REFUSAL_STATUS[refusal.code]);
+}
+function handleSync(body) {
+  const usage = body.usage;
+  if (typeof usage === "object" && usage !== null) {
+    const locations = usage.locations;
+    state.controls.lastUsage = typeof locations === "number" && Number.isInteger(locations) && locations >= 0 ? { locations } : {};
+  }
+  return json({ controls: currentControlsBody() });
+}
+async function handleWrite(request, key) {
+  const { CONTROLS, isWritableControl } = await loadControls();
+  if (!isWritableControl(key)) {
+    return refusalResponse({
+      code: "NOT_WRITABLE",
+      message: `${key} cannot be changed from the app`
+    });
+  }
+  const userToken = request.headers.get(USER_TOKEN_HEADER);
+  if (!userToken) {
+    return refusalResponse({
+      code: "UNAUTHENTICATED",
+      message: "A signed-in person is required (X-Stardeck-User-Token)"
+    });
+  }
+  const body = await readJsonBody(request);
+  const parsed = CONTROLS[key].schema.safeParse(body.value);
+  if (!parsed.success) {
+    return refusalResponse({
+      code: "INVALID_VALUE",
+      message: parsed.error.issues[0]?.message ?? "Invalid value"
+    });
+  }
+  const refusal = state.controls.refusal;
+  if (refusal) {
+    state.controls.refusal = null;
+    return refusalResponse(refusal);
+  }
+  state.controls.values[key] = parsed.data;
+  state.controls.unavailable.delete(key);
+  state.controls.writes.push({ key, value: parsed.data, userToken });
+  return json({ controls: currentControlsBody() });
+}
+var CONTROLS_PATH = /^\/api\/deployments\/[^/]+\/controls(?:\/([^/]+))?$/;
+async function handleControlsRequest(request, url) {
+  const match = url.pathname.match(CONTROLS_PATH);
+  const key = match?.[1] ? decodeURIComponent(match[1]) : null;
+  if (!key && request.method === "POST") {
+    return handleSync(await readJsonBody(request));
+  }
+  if (key && request.method === "PUT") {
+    return handleWrite(request, key);
+  }
+  return json(
+    {
+      error: { code: "UNAVAILABLE", message: `No simulator for ${request.method} ${url.pathname}` }
+    },
+    404
+  );
+}
+
 // src/simulator/schedules.ts
 async function handleScheduleWake(request, scheduleKey) {
   if (request.method !== "POST") return failure(`Method ${request.method} not allowed`, 405);
@@ -3134,8 +3227,10 @@ function requiresDeploymentHmac(request, url) {
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStarlens = url.pathname === "/api/starlens/extract";
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
-  return !!(isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const controlsMatch = url.pathname.match(CONTROLS_PATH2);
+  return !!(controlsMatch || isStarlens || scheduleWakeMatch || dataStoreMatch || isEmail2 || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
+var CONTROLS_PATH2 = /^\/api\/deployments\/[^/]+\/controls(\/[^/]+)?$/;
 var SCHEDULE_WAKE_PATH = /^\/api\/deployments\/[^/]+\/schedules\/([^/]+)\/wake$/;
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -3203,6 +3298,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (CONTROLS_PATH2.test(url.pathname)) {
+    return handleControlsRequest(request, url);
+  }
   const scheduleWakeMatch = url.pathname.match(SCHEDULE_WAKE_PATH);
   if (scheduleWakeMatch) {
     return handleScheduleWake(request, decodeURIComponent(scheduleWakeMatch[1]));
@@ -3231,7 +3329,7 @@ async function handleSimulatedRequest(request, url) {
     }
   }
   return failure(
-    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
+    `[stardeck-testing] No simulator for ${request.method} ${url.pathname}. Supported: data-store query/mutate/schema, email send, identities CRUD, payments store/checkout, storage upload/files, messaging send, edge print/display/bindings, app controls sync/write, starlens extract, schedule wakes, auth verify/refresh, Neon /sql.`,
     404
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Vitest test harness for Stardeck customer apps — in-process Postgres (PGlite) plus a control-plane simulator so the real Stardeck SDKs run unmodified in tests",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -65,6 +65,7 @@
     "@electric-sql/pglite": "^0.3.0"
   },
   "peerDependencies": {
+    "@stardeck-customer-apps/controls": ">=0.1.0",
     "@stardeck-customer-apps/edge-sdk": ">=1.4.0",
     "@stardeck-customer-apps/integrations-sdk": ">=1.16.0",
     "@stardeck-customer-apps/payments-sdk": ">=0.1.0",
@@ -74,6 +75,9 @@
     "@stardeck-customer-apps/starlens": ">=0.1.0"
   },
   "peerDependenciesMeta": {
+    "@stardeck-customer-apps/controls": {
+      "optional": true
+    },
     "@stardeck-customer-apps/integrations-sdk": {
       "optional": true
     },
@@ -95,6 +99,7 @@
   },
   "devDependencies": {
     "@neondatabase/serverless": "^1.0.0",
+    "@stardeck-customer-apps/controls": "*",
     "@stardeck-customer-apps/data-store-sdk": "*",
     "@stardeck-customer-apps/edge-sdk": "*",
     "@stardeck-customer-apps/email-sdk": "*",