@stardeck-customer-apps/testing 0.13.0 → 0.15.0

package/SKILL.md

@@ -295,6 +295,32 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
   - `allowNetwork` — permit non-Stardeck outbound fetches (off by default).
 - `app.reset()` — wipe + re-apply schema + re-seed + clear inbox/sessions.
   Call in `beforeEach`.
+- `app.reset({ mode: "data" })` — available in testing SDK **0.14.0+**. Faster
+  opt-in for stable schemas: truncate ordinary tables in `public`, restart their
+  owned serial/identity sequences, re-run the data-only seed, and clear the same
+  simulator/user/session state as the default. It preserves tables and other
+  schema objects instead of rebuilding them. The default remains full schema
+  reset; `app.reset({ mode: "schema" })` explicitly selects that default.
+
+  ```ts
+  // Only after verifying this suite keeps its schema fixed and uses a data-only seed:
+  beforeEach(() => app.reset({ mode: "data" }));
+  ```
+
+  Keep `app.reset()` for tests that change schema or depend on INSERTs in the
+  schema script. Also keep full reset for independent sequences, materialized
+  views, partitioned/foreign tables, temporary tables, and custom triggers or
+  cross-schema dependencies. Data mode does not restore those states or detect
+  eligibility; inspect both the tests and seed before opting in. All required
+  baseline rows must come from the data-only seed callback, not schema SQL.
+  Data mode refuses foreign keys requiring a cross-schema cascade. Database and
+  seed errors reject the reset; fix them before running the next test.
+
+  Do not use `it.concurrent` or `test.concurrent` with a shared test app: user,
+  database, and simulator state are shared within the file. Keep file isolation
+  enabled and let Vitest parallelize files. This option does not change workers
+  or the platform's test-run deadline.
+
 - `app.asUser(partial?)` — sign in a test user; `getSession()` in app code
   resolves to it. `app.signOut()` clears.
 - `app.issueSession(partial?)` — mint access/refresh tokens for cookie-based
@@ -425,6 +451,14 @@ cursor, limit })`; `list()` intentionally keeps its previous array shape.
   display, test print, `getCapabilities()`) — captured in `app.edge`; seed
   devices/peripherals for pairing pickers via `app.edge.seedDevices()` /
   `seedPeripherals()`.
+- `createStarlensClient().extract()` from the starlens SDK — there is no model in
+  tests: register what Starlens answers with `app.starlens.mock({ output, issues })`
+  (a successful extraction; each issue path comes back `null` in `output`, as in
+  production) or `app.starlens.reject("not a receipt")` (the 422 the SDK maps to
+  `UnsupportedDocumentError`). An unregistered call fails with a descriptive 502 so a
+  test never passes on an invented extraction. `app.starlens.calls` records each
+  request's version, input names/media types (never bytes), schema and
+  instructions — assert your `.describe()` aliases reached the wire there.
 
 ### Receipt layout and printer capabilities
 

package/dist/index.d.mts

@@ -462,6 +462,44 @@ interface TestEdge {
     clear(): void;
     get count(): number;
 }
+/** One Starlens request the app made, as the simulator saw it (names only, never bytes). */
+interface CapturedStarlensCall {
+    version: string;
+    inputs: {
+        name: string;
+        mediaType: string | null;
+        source: "url" | "data";
+    }[];
+    schema: Record<string, unknown>;
+    instructions?: string;
+}
+/**
+ * What the simulated Starlens answers next. `{ output, issues }` is returned as a
+ * successful extraction with every issue path nulled in `output`, exactly as the control
+ * plane does; `{ reject }` becomes the 422 `unsupported_document` refusal the SDK maps to
+ * `UnsupportedDocumentError`.
+ */
+type StarlensReply = {
+    output: unknown;
+    issues?: {
+        path: string;
+        reason: string;
+    }[];
+} | {
+    reject: string;
+};
+interface TestStarlens {
+    /** Queue the reply for the next `extract()` call. */
+    mock(reply: StarlensReply): void;
+    /** Queue a refusal for the next `extract()` call. */
+    reject(reason: string): void;
+    /** Reply used whenever the queue is empty (null = fail with a descriptive 502). */
+    mockDefault(reply: StarlensReply | null): void;
+    get calls(): CapturedStarlensCall[];
+    latestCall(): CapturedStarlensCall | undefined;
+    clear(): void;
+    get count(): number;
+}
 interface TestAppOptions {
     /** Data stores exposed through the production-shaped STARDECK_DATA_STORES manifest. */
     dataStores?: TestDataStoreInput[];
@@ -506,6 +544,8 @@ interface TestApp {
     messages: TestMessages;
     /** Captured edge print/display ops and peripheral bindings from edge-sdk. */
     edge: TestEdge;
+    /** Scripted replies and captured calls for the Starlens SDK. */
+    starlens: TestStarlens;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**
@@ -520,8 +560,15 @@ interface TestApp {
      * control-plane verify endpoint resolves these tokens back to the user.
      */
     issueSession(user?: Partial<TestUser>): SessionTokens;
-    /** Drop all tables, re-apply the schema, re-run the seed, clear inbox/user. */
-    reset(): Promise<void>;
+    /**
+     * Rebuild the schema (default), re-run the seed, and clear simulator/user state.
+     * `mode: "data"` instead truncates ordinary public tables and restarts owned
+     * sequences. Use only with a stable schema and data-only seed; it does not
+     * restore DDL changes, schema-script data, or independent sequences.
+     */
+    reset(options?: {
+        mode: "schema" | "data";
+    }): Promise<void>;
     /** Tear down the app and restore global fetch. */
     close(): Promise<void>;
 }
@@ -564,4 +611,4 @@ declare const TEST_ENV_DEFAULTS: {
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DATA_STORE_TEST_URL, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PaymentSimulatorFailure, type PaymentSimulatorOperation, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, TestDataStoreInput, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedStarlensCall, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DATA_STORE_TEST_URL, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PaymentSimulatorFailure, type PaymentSimulatorOperation, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, type StarlensReply, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, TestDataStoreInput, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStarlens, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.d.ts

@@ -462,6 +462,44 @@ interface TestEdge {
     clear(): void;
     get count(): number;
 }
+/** One Starlens request the app made, as the simulator saw it (names only, never bytes). */
+interface CapturedStarlensCall {
+    version: string;
+    inputs: {
+        name: string;
+        mediaType: string | null;
+        source: "url" | "data";
+    }[];
+    schema: Record<string, unknown>;
+    instructions?: string;
+}
+/**
+ * What the simulated Starlens answers next. `{ output, issues }` is returned as a
+ * successful extraction with every issue path nulled in `output`, exactly as the control
+ * plane does; `{ reject }` becomes the 422 `unsupported_document` refusal the SDK maps to
+ * `UnsupportedDocumentError`.
+ */
+type StarlensReply = {
+    output: unknown;
+    issues?: {
+        path: string;
+        reason: string;
+    }[];
+} | {
+    reject: string;
+};
+interface TestStarlens {
+    /** Queue the reply for the next `extract()` call. */
+    mock(reply: StarlensReply): void;
+    /** Queue a refusal for the next `extract()` call. */
+    reject(reason: string): void;
+    /** Reply used whenever the queue is empty (null = fail with a descriptive 502). */
+    mockDefault(reply: StarlensReply | null): void;
+    get calls(): CapturedStarlensCall[];
+    latestCall(): CapturedStarlensCall | undefined;
+    clear(): void;
+    get count(): number;
+}
 interface TestAppOptions {
     /** Data stores exposed through the production-shaped STARDECK_DATA_STORES manifest. */
     dataStores?: TestDataStoreInput[];
@@ -506,6 +544,8 @@ interface TestApp {
     messages: TestMessages;
     /** Captured edge print/display ops and peripheral bindings from edge-sdk. */
     edge: TestEdge;
+    /** Scripted replies and captured calls for the Starlens SDK. */
+    starlens: TestStarlens;
     /** Convenience for raw SQL: `app.query("SELECT ...", [param])`. */
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**
@@ -520,8 +560,15 @@ interface TestApp {
      * control-plane verify endpoint resolves these tokens back to the user.
      */
     issueSession(user?: Partial<TestUser>): SessionTokens;
-    /** Drop all tables, re-apply the schema, re-run the seed, clear inbox/user. */
-    reset(): Promise<void>;
+    /**
+     * Rebuild the schema (default), re-run the seed, and clear simulator/user state.
+     * `mode: "data"` instead truncates ordinary public tables and restarts owned
+     * sequences. Use only with a stable schema and data-only seed; it does not
+     * restore DDL changes, schema-script data, or independent sequences.
+     */
+    reset(options?: {
+        mode: "schema" | "data";
+    }): Promise<void>;
     /** Tear down the app and restore global fetch. */
     close(): Promise<void>;
 }
@@ -564,4 +611,4 @@ declare const TEST_ENV_DEFAULTS: {
 /** Default location of the DDL snapshot written by `generate-types`. */
 declare const DEFAULT_SCHEMA_PATH = "./src/generated/data-store-schema.sql";
 
-export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DATA_STORE_TEST_URL, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PaymentSimulatorFailure, type PaymentSimulatorOperation, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, TestDataStoreInput, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };
+export { type BindingInfo, CONTROL_PLANE_TEST_URL, type CallRouteOptions, type CapturedCheckout, type CapturedDisplay, type CapturedEmail, type CapturedIdentity, type CapturedIdentityLink, type CapturedMessage, type CapturedPrint, type CapturedStarlensCall, type CapturedTestPrint, type CapturedUpload, DATA_STORE_TEST_HOST, DATA_STORE_TEST_URL, DEFAULT_SCHEMA_PATH, type DeviceInfo, type PaymentSimulatorFailure, type PaymentSimulatorOperation, type PeripheralInfo, STORAGE_TEST_HOST, STORAGE_TEST_URL, type SessionTokens, type SimBoltCharge, type SimBoltConnection, type SimBoltIntentRecord, type SimBoltIntentStatus, type StarlensReply, TEST_ENV_DEFAULTS, type TestApp, type TestAppOptions, TestDataStoreInput, type TestDirectory, type TestEdge, type TestInbox, type TestMessages, type TestPayments, type TestStarlens, type TestStorage, type TestUser, WORKFLOW_NAME_PREFIX, callRoute, createTestApp, describeWorkflow, parseWorkflowName };

package/dist/index.js

@@ -73,6 +73,19 @@ async function applySchema(db, schemaSql) {
 async function dropAllTables(db) {
   await db.exec(`DROP SCHEMA public CASCADE; CREATE SCHEMA public;`);
 }
+async function listPublicTables(db) {
+  const { rows } = await db.query(`
+    SELECT format('%I.%I', n.nspname, c.relname) AS name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'public' AND c.relkind = 'r'
+    ORDER BY c.relname
+  `);
+  return rows.map(({ name }) => name);
+}
+async function truncateAllTables(db) {
+  const tables = await listPublicTables(db);
+  if (tables.length) await db.exec(`TRUNCATE TABLE ${tables.join(", ")} RESTART IDENTITY`);
+}
 var identityParsers = null;
 function getIdentityParsers() {
   if (!identityParsers) {
@@ -131,6 +144,9 @@ var state = globalSingleton("state", () => ({
   edgeBindings: /* @__PURE__ */ new Map(),
   edgeCapabilities: null,
   edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
+  starlensCalls: [],
+  starlensReplies: [],
+  starlensDefaultReply: null,
   allowNetwork: false
 }));
 function requireDb() {
@@ -2540,6 +2556,104 @@ function createEdge() {
   };
 }
 
+// src/simulator/starlens.ts
+function starlensFailure(error, status, code) {
+  return json({ success: false, error, code }, status);
+}
+function nullFlagged(output, issues) {
+  const copy = JSON.parse(JSON.stringify(output ?? null));
+  for (const { path } of issues) {
+    const keys = path.replace(/^output\./, "").replace(/\[(\d+)\]/g, ".$1").split(".");
+    const last = keys.pop();
+    const parent = keys.reduce(
+      (o, k) => o != null && typeof o === "object" ? o[k] : void 0,
+      copy
+    );
+    if (parent != null && typeof parent === "object" && Object.prototype.hasOwnProperty.call(parent, last)) {
+      parent[last] = null;
+    }
+  }
+  return copy;
+}
+async function handleStarlensExtract(request, signedDeploymentId) {
+  const body = await readJsonBody(request);
+  if (signedDeploymentId !== null && body.deploymentId !== signedDeploymentId) {
+    return starlensFailure("Deployment ID mismatch", 401, "AUTHENTICATION_ERROR");
+  }
+  const inputs = Array.isArray(body.inputs) ? body.inputs : [];
+  if (inputs.length === 0) {
+    return starlensFailure(
+      "Validation failed \u2014 inputs: at least one input",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const schema = body.schema;
+  if (!schema || schema.type !== "object" || typeof schema.properties !== "object") {
+    return starlensFailure(
+      "Validation failed \u2014 schema.properties is required",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const call = {
+    version: typeof body.version === "string" ? body.version : "latest",
+    inputs: inputs.map((i) => ({
+      name: typeof i.filename === "string" ? i.filename : typeof i.url === "string" ? i.url : "upload",
+      mediaType: typeof i.mediaType === "string" ? i.mediaType : null,
+      source: typeof i.url === "string" ? "url" : "data"
+    })),
+    schema,
+    instructions: typeof body.instructions === "string" ? body.instructions : void 0
+  };
+  state.starlensCalls.push(call);
+  const reply = state.starlensReplies.shift() ?? state.starlensDefaultReply;
+  if (!reply) {
+    return starlensFailure(
+      "[stardeck-testing] No Starlens reply registered. Call app.starlens.mock({ output, issues }) or app.starlens.reject(reason) before the request.",
+      502,
+      "model_failed"
+    );
+  }
+  if ("reject" in reply) {
+    return starlensFailure(reply.reject, 422, "unsupported_document");
+  }
+  const issues = reply.issues ?? [];
+  return success({
+    version: call.version === "latest" ? "v1" : call.version,
+    output: nullFlagged(reply.output, issues),
+    issues,
+    usage: { inputTokens: 0, outputTokens: 0, cost: 0 }
+  });
+}
+function createStarlens() {
+  return {
+    mock(reply) {
+      state.starlensReplies.push(reply);
+    },
+    reject(reason) {
+      state.starlensReplies.push({ reject: reason });
+    },
+    mockDefault(reply) {
+      state.starlensDefaultReply = reply;
+    },
+    get calls() {
+      return state.starlensCalls;
+    },
+    latestCall() {
+      return state.starlensCalls[state.starlensCalls.length - 1];
+    },
+    clear() {
+      state.starlensCalls = [];
+      state.starlensReplies = [];
+      state.starlensDefaultReply = null;
+    },
+    get count() {
+      return state.starlensCalls.length;
+    }
+  };
+}
+
 // src/simulator/router.ts
 var fetchHolder = globalSingleton("fetch-holder", () => ({
   originalFetch: null
@@ -2561,7 +2675,8 @@ function requiresDeploymentHmac(request, url) {
     /^\/api\/deployments\/[^/]+\/integrations\/(slack|line|facebook)(\/.*)?$/
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
-  return !!(dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const isStarlens = url.pathname === "/api/starlens/extract";
+  return !!(isStarlens || dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -2591,6 +2706,7 @@ async function handleSimulatedRequest(request, url) {
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStorageHost = url.hostname === STORAGE_TEST_HOST;
+  let signedDeploymentId = null;
   if (requiresDeploymentHmac(request, url)) {
     const authHeader = request.headers.get("X-Stardeck-Auth");
     if (!authHeader) {
@@ -2602,6 +2718,7 @@ async function handleSimulatedRequest(request, url) {
     if (!authPayload || pathDeploymentId !== null && authPayload.deploymentId !== pathDeploymentId) {
       return failure("Invalid authentication", 401);
     }
+    signedDeploymentId = authPayload.deploymentId;
   }
   if (isStorageHost) {
     return handleStorageRequest(request, url);
@@ -2622,6 +2739,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (url.pathname === "/api/starlens/extract" && request.method === "POST") {
+    return handleStarlensExtract(request, signedDeploymentId);
+  }
   if (dataStoreMatch) {
     const subPath = dataStoreMatch[1] ?? "";
     const db = requireDb();
@@ -2643,7 +2763,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, 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, starlens extract, auth verify/refresh, Neon /sql.`,
     404
   );
 }
@@ -2811,6 +2931,7 @@ async function createTestApp(options = {}) {
   const storage = createStorage();
   const messages = createMessages();
   const edge = createEdge();
+  const starlens = createStarlens();
   const app = {
     db,
     inbox,
@@ -2819,6 +2940,7 @@ async function createTestApp(options = {}) {
     storage,
     messages,
     edge,
+    starlens,
     async query(sql, params = []) {
       const result = await db.query(sql, params);
       return result.rows;
@@ -2841,9 +2963,14 @@ async function createTestApp(options = {}) {
       state.refreshSessions.set(tokens.refreshToken, fullUser);
       return tokens;
     },
-    async reset() {
-      await dropAllTables(db);
-      await initialize();
+    async reset(resetOptions) {
+      if (resetOptions?.mode === "data") {
+        await truncateAllTables(db);
+        if (options.seed) await options.seed(db);
+      } else {
+        await dropAllTables(db);
+        await initialize();
+      }
       state.currentUser = null;
       state.sessions.clear();
       state.refreshSessions.clear();
@@ -2855,6 +2982,7 @@ async function createTestApp(options = {}) {
       storage.clear();
       messages.clear();
       edge.clear();
+      starlens.clear();
     },
     async close() {
       state.db = null;
@@ -2869,6 +2997,7 @@ async function createTestApp(options = {}) {
       storage.clear();
       messages.clear();
       edge.clear();
+      starlens.clear();
       uninstallFetchRouter();
       await db.close();
     }

package/dist/index.mjs

@@ -24,6 +24,19 @@ async function applySchema(db, schemaSql) {
 async function dropAllTables(db) {
   await db.exec(`DROP SCHEMA public CASCADE; CREATE SCHEMA public;`);
 }
+async function listPublicTables(db) {
+  const { rows } = await db.query(`
+    SELECT format('%I.%I', n.nspname, c.relname) AS name
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+    WHERE n.nspname = 'public' AND c.relkind = 'r'
+    ORDER BY c.relname
+  `);
+  return rows.map(({ name }) => name);
+}
+async function truncateAllTables(db) {
+  const tables = await listPublicTables(db);
+  if (tables.length) await db.exec(`TRUNCATE TABLE ${tables.join(", ")} RESTART IDENTITY`);
+}
 var identityParsers = null;
 function getIdentityParsers() {
   if (!identityParsers) {
@@ -82,6 +95,9 @@ var state = globalSingleton("state", () => ({
   edgeBindings: /* @__PURE__ */ new Map(),
   edgeCapabilities: null,
   edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
+  starlensCalls: [],
+  starlensReplies: [],
+  starlensDefaultReply: null,
   allowNetwork: false
 }));
 function requireDb() {
@@ -2491,6 +2507,104 @@ function createEdge() {
   };
 }
 
+// src/simulator/starlens.ts
+function starlensFailure(error, status, code) {
+  return json({ success: false, error, code }, status);
+}
+function nullFlagged(output, issues) {
+  const copy = JSON.parse(JSON.stringify(output ?? null));
+  for (const { path } of issues) {
+    const keys = path.replace(/^output\./, "").replace(/\[(\d+)\]/g, ".$1").split(".");
+    const last = keys.pop();
+    const parent = keys.reduce(
+      (o, k) => o != null && typeof o === "object" ? o[k] : void 0,
+      copy
+    );
+    if (parent != null && typeof parent === "object" && Object.prototype.hasOwnProperty.call(parent, last)) {
+      parent[last] = null;
+    }
+  }
+  return copy;
+}
+async function handleStarlensExtract(request, signedDeploymentId) {
+  const body = await readJsonBody(request);
+  if (signedDeploymentId !== null && body.deploymentId !== signedDeploymentId) {
+    return starlensFailure("Deployment ID mismatch", 401, "AUTHENTICATION_ERROR");
+  }
+  const inputs = Array.isArray(body.inputs) ? body.inputs : [];
+  if (inputs.length === 0) {
+    return starlensFailure(
+      "Validation failed \u2014 inputs: at least one input",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const schema = body.schema;
+  if (!schema || schema.type !== "object" || typeof schema.properties !== "object") {
+    return starlensFailure(
+      "Validation failed \u2014 schema.properties is required",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const call = {
+    version: typeof body.version === "string" ? body.version : "latest",
+    inputs: inputs.map((i) => ({
+      name: typeof i.filename === "string" ? i.filename : typeof i.url === "string" ? i.url : "upload",
+      mediaType: typeof i.mediaType === "string" ? i.mediaType : null,
+      source: typeof i.url === "string" ? "url" : "data"
+    })),
+    schema,
+    instructions: typeof body.instructions === "string" ? body.instructions : void 0
+  };
+  state.starlensCalls.push(call);
+  const reply = state.starlensReplies.shift() ?? state.starlensDefaultReply;
+  if (!reply) {
+    return starlensFailure(
+      "[stardeck-testing] No Starlens reply registered. Call app.starlens.mock({ output, issues }) or app.starlens.reject(reason) before the request.",
+      502,
+      "model_failed"
+    );
+  }
+  if ("reject" in reply) {
+    return starlensFailure(reply.reject, 422, "unsupported_document");
+  }
+  const issues = reply.issues ?? [];
+  return success({
+    version: call.version === "latest" ? "v1" : call.version,
+    output: nullFlagged(reply.output, issues),
+    issues,
+    usage: { inputTokens: 0, outputTokens: 0, cost: 0 }
+  });
+}
+function createStarlens() {
+  return {
+    mock(reply) {
+      state.starlensReplies.push(reply);
+    },
+    reject(reason) {
+      state.starlensReplies.push({ reject: reason });
+    },
+    mockDefault(reply) {
+      state.starlensDefaultReply = reply;
+    },
+    get calls() {
+      return state.starlensCalls;
+    },
+    latestCall() {
+      return state.starlensCalls[state.starlensCalls.length - 1];
+    },
+    clear() {
+      state.starlensCalls = [];
+      state.starlensReplies = [];
+      state.starlensDefaultReply = null;
+    },
+    get count() {
+      return state.starlensCalls.length;
+    }
+  };
+}
+
 // src/simulator/router.ts
 var fetchHolder = globalSingleton("fetch-holder", () => ({
   originalFetch: null
@@ -2512,7 +2626,8 @@ function requiresDeploymentHmac(request, url) {
     /^\/api\/deployments\/[^/]+\/integrations\/(slack|line|facebook)(\/.*)?$/
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
-  return !!(dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const isStarlens = url.pathname === "/api/starlens/extract";
+  return !!(isStarlens || dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -2542,6 +2657,7 @@ async function handleSimulatedRequest(request, url) {
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStorageHost = url.hostname === STORAGE_TEST_HOST;
+  let signedDeploymentId = null;
   if (requiresDeploymentHmac(request, url)) {
     const authHeader = request.headers.get("X-Stardeck-Auth");
     if (!authHeader) {
@@ -2553,6 +2669,7 @@ async function handleSimulatedRequest(request, url) {
     if (!authPayload || pathDeploymentId !== null && authPayload.deploymentId !== pathDeploymentId) {
       return failure("Invalid authentication", 401);
     }
+    signedDeploymentId = authPayload.deploymentId;
   }
   if (isStorageHost) {
     return handleStorageRequest(request, url);
@@ -2573,6 +2690,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (url.pathname === "/api/starlens/extract" && request.method === "POST") {
+    return handleStarlensExtract(request, signedDeploymentId);
+  }
   if (dataStoreMatch) {
     const subPath = dataStoreMatch[1] ?? "";
     const db = requireDb();
@@ -2594,7 +2714,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, 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, starlens extract, auth verify/refresh, Neon /sql.`,
     404
   );
 }
@@ -2762,6 +2882,7 @@ async function createTestApp(options = {}) {
   const storage = createStorage();
   const messages = createMessages();
   const edge = createEdge();
+  const starlens = createStarlens();
   const app = {
     db,
     inbox,
@@ -2770,6 +2891,7 @@ async function createTestApp(options = {}) {
     storage,
     messages,
     edge,
+    starlens,
     async query(sql, params = []) {
       const result = await db.query(sql, params);
       return result.rows;
@@ -2792,9 +2914,14 @@ async function createTestApp(options = {}) {
       state.refreshSessions.set(tokens.refreshToken, fullUser);
       return tokens;
     },
-    async reset() {
-      await dropAllTables(db);
-      await initialize();
+    async reset(resetOptions) {
+      if (resetOptions?.mode === "data") {
+        await truncateAllTables(db);
+        if (options.seed) await options.seed(db);
+      } else {
+        await dropAllTables(db);
+        await initialize();
+      }
       state.currentUser = null;
       state.sessions.clear();
       state.refreshSessions.clear();
@@ -2806,6 +2933,7 @@ async function createTestApp(options = {}) {
       storage.clear();
       messages.clear();
       edge.clear();
+      starlens.clear();
     },
     async close() {
       state.db = null;
@@ -2820,6 +2948,7 @@ async function createTestApp(options = {}) {
       storage.clear();
       messages.clear();
       edge.clear();
+      starlens.clear();
       uninstallFetchRouter();
       await db.close();
     }

package/dist/next/headers-shim.js

@@ -74,6 +74,9 @@ var state = globalSingleton("state", () => ({
   edgeBindings: /* @__PURE__ */ new Map(),
   edgeCapabilities: null,
   edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
+  starlensCalls: [],
+  starlensReplies: [],
+  starlensDefaultReply: null,
   allowNetwork: false
 }));
 

package/dist/next/headers-shim.mjs

@@ -47,6 +47,9 @@ var state = globalSingleton("state", () => ({
   edgeBindings: /* @__PURE__ */ new Map(),
   edgeCapabilities: null,
   edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
+  starlensCalls: [],
+  starlensReplies: [],
+  starlensDefaultReply: null,
   allowNetwork: false
 }));
 

package/dist/setup.js

@@ -68,6 +68,9 @@ var state = globalSingleton("state", () => ({
   edgeBindings: /* @__PURE__ */ new Map(),
   edgeCapabilities: null,
   edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
+  starlensCalls: [],
+  starlensReplies: [],
+  starlensDefaultReply: null,
   allowNetwork: false
 }));
 function requireDb() {
@@ -2000,6 +2003,77 @@ async function handleEdgeRequest(request, subPath) {
   return edgeFailure(`No edge simulator for ${method} .../edge${subPath}`, 404);
 }
 
+// src/simulator/starlens.ts
+function starlensFailure(error, status, code) {
+  return json({ success: false, error, code }, status);
+}
+function nullFlagged(output, issues) {
+  const copy = JSON.parse(JSON.stringify(output ?? null));
+  for (const { path } of issues) {
+    const keys = path.replace(/^output\./, "").replace(/\[(\d+)\]/g, ".$1").split(".");
+    const last = keys.pop();
+    const parent = keys.reduce(
+      (o, k) => o != null && typeof o === "object" ? o[k] : void 0,
+      copy
+    );
+    if (parent != null && typeof parent === "object" && Object.prototype.hasOwnProperty.call(parent, last)) {
+      parent[last] = null;
+    }
+  }
+  return copy;
+}
+async function handleStarlensExtract(request, signedDeploymentId) {
+  const body = await readJsonBody(request);
+  if (signedDeploymentId !== null && body.deploymentId !== signedDeploymentId) {
+    return starlensFailure("Deployment ID mismatch", 401, "AUTHENTICATION_ERROR");
+  }
+  const inputs = Array.isArray(body.inputs) ? body.inputs : [];
+  if (inputs.length === 0) {
+    return starlensFailure(
+      "Validation failed \u2014 inputs: at least one input",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const schema = body.schema;
+  if (!schema || schema.type !== "object" || typeof schema.properties !== "object") {
+    return starlensFailure(
+      "Validation failed \u2014 schema.properties is required",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const call = {
+    version: typeof body.version === "string" ? body.version : "latest",
+    inputs: inputs.map((i) => ({
+      name: typeof i.filename === "string" ? i.filename : typeof i.url === "string" ? i.url : "upload",
+      mediaType: typeof i.mediaType === "string" ? i.mediaType : null,
+      source: typeof i.url === "string" ? "url" : "data"
+    })),
+    schema,
+    instructions: typeof body.instructions === "string" ? body.instructions : void 0
+  };
+  state.starlensCalls.push(call);
+  const reply = state.starlensReplies.shift() ?? state.starlensDefaultReply;
+  if (!reply) {
+    return starlensFailure(
+      "[stardeck-testing] No Starlens reply registered. Call app.starlens.mock({ output, issues }) or app.starlens.reject(reason) before the request.",
+      502,
+      "model_failed"
+    );
+  }
+  if ("reject" in reply) {
+    return starlensFailure(reply.reject, 422, "unsupported_document");
+  }
+  const issues = reply.issues ?? [];
+  return success({
+    version: call.version === "latest" ? "v1" : call.version,
+    output: nullFlagged(reply.output, issues),
+    issues,
+    usage: { inputTokens: 0, outputTokens: 0, cost: 0 }
+  });
+}
+
 // src/simulator/router.ts
 var fetchHolder = globalSingleton("fetch-holder", () => ({
   originalFetch: null
@@ -2021,7 +2095,8 @@ function requiresDeploymentHmac(request, url) {
     /^\/api\/deployments\/[^/]+\/integrations\/(slack|line|facebook)(\/.*)?$/
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
-  return !!(dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const isStarlens = url.pathname === "/api/starlens/extract";
+  return !!(isStarlens || dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -2051,6 +2126,7 @@ async function handleSimulatedRequest(request, url) {
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStorageHost = url.hostname === STORAGE_TEST_HOST;
+  let signedDeploymentId = null;
   if (requiresDeploymentHmac(request, url)) {
     const authHeader = request.headers.get("X-Stardeck-Auth");
     if (!authHeader) {
@@ -2062,6 +2138,7 @@ async function handleSimulatedRequest(request, url) {
     if (!authPayload || pathDeploymentId !== null && authPayload.deploymentId !== pathDeploymentId) {
       return failure("Invalid authentication", 401);
     }
+    signedDeploymentId = authPayload.deploymentId;
   }
   if (isStorageHost) {
     return handleStorageRequest(request, url);
@@ -2082,6 +2159,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (url.pathname === "/api/starlens/extract" && request.method === "POST") {
+    return handleStarlensExtract(request, signedDeploymentId);
+  }
   if (dataStoreMatch) {
     const subPath = dataStoreMatch[1] ?? "";
     const db = requireDb();
@@ -2103,7 +2183,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, 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, starlens extract, auth verify/refresh, Neon /sql.`,
     404
   );
 }

package/dist/setup.mjs

@@ -44,6 +44,9 @@ var state = globalSingleton("state", () => ({
   edgeBindings: /* @__PURE__ */ new Map(),
   edgeCapabilities: null,
   edgePeripheralCapabilities: /* @__PURE__ */ new Map(),
+  starlensCalls: [],
+  starlensReplies: [],
+  starlensDefaultReply: null,
   allowNetwork: false
 }));
 function requireDb() {
@@ -1976,6 +1979,77 @@ async function handleEdgeRequest(request, subPath) {
   return edgeFailure(`No edge simulator for ${method} .../edge${subPath}`, 404);
 }
 
+// src/simulator/starlens.ts
+function starlensFailure(error, status, code) {
+  return json({ success: false, error, code }, status);
+}
+function nullFlagged(output, issues) {
+  const copy = JSON.parse(JSON.stringify(output ?? null));
+  for (const { path } of issues) {
+    const keys = path.replace(/^output\./, "").replace(/\[(\d+)\]/g, ".$1").split(".");
+    const last = keys.pop();
+    const parent = keys.reduce(
+      (o, k) => o != null && typeof o === "object" ? o[k] : void 0,
+      copy
+    );
+    if (parent != null && typeof parent === "object" && Object.prototype.hasOwnProperty.call(parent, last)) {
+      parent[last] = null;
+    }
+  }
+  return copy;
+}
+async function handleStarlensExtract(request, signedDeploymentId) {
+  const body = await readJsonBody(request);
+  if (signedDeploymentId !== null && body.deploymentId !== signedDeploymentId) {
+    return starlensFailure("Deployment ID mismatch", 401, "AUTHENTICATION_ERROR");
+  }
+  const inputs = Array.isArray(body.inputs) ? body.inputs : [];
+  if (inputs.length === 0) {
+    return starlensFailure(
+      "Validation failed \u2014 inputs: at least one input",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const schema = body.schema;
+  if (!schema || schema.type !== "object" || typeof schema.properties !== "object") {
+    return starlensFailure(
+      "Validation failed \u2014 schema.properties is required",
+      400,
+      "VALIDATION_ERROR"
+    );
+  }
+  const call = {
+    version: typeof body.version === "string" ? body.version : "latest",
+    inputs: inputs.map((i) => ({
+      name: typeof i.filename === "string" ? i.filename : typeof i.url === "string" ? i.url : "upload",
+      mediaType: typeof i.mediaType === "string" ? i.mediaType : null,
+      source: typeof i.url === "string" ? "url" : "data"
+    })),
+    schema,
+    instructions: typeof body.instructions === "string" ? body.instructions : void 0
+  };
+  state.starlensCalls.push(call);
+  const reply = state.starlensReplies.shift() ?? state.starlensDefaultReply;
+  if (!reply) {
+    return starlensFailure(
+      "[stardeck-testing] No Starlens reply registered. Call app.starlens.mock({ output, issues }) or app.starlens.reject(reason) before the request.",
+      502,
+      "model_failed"
+    );
+  }
+  if ("reject" in reply) {
+    return starlensFailure(reply.reject, 422, "unsupported_document");
+  }
+  const issues = reply.issues ?? [];
+  return success({
+    version: call.version === "latest" ? "v1" : call.version,
+    output: nullFlagged(reply.output, issues),
+    issues,
+    usage: { inputTokens: 0, outputTokens: 0, cost: 0 }
+  });
+}
+
 // src/simulator/router.ts
 var fetchHolder = globalSingleton("fetch-holder", () => ({
   originalFetch: null
@@ -1997,7 +2071,8 @@ function requiresDeploymentHmac(request, url) {
     /^\/api\/deployments\/[^/]+\/integrations\/(slack|line|facebook)(\/.*)?$/
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
-  return !!(dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
+  const isStarlens = url.pathname === "/api/starlens/extract";
+  return !!(isStarlens || dataStoreMatch || isEmail || identitiesMatch || storeMatch || messagingMatch || edgeMatch);
 }
 function deploymentIdFromPath(url) {
   const match = url.pathname.match(/\/api\/deployments\/([^/]+)(?:\/|$)/);
@@ -2027,6 +2102,7 @@ async function handleSimulatedRequest(request, url) {
   );
   const edgeMatch = url.pathname.match(/^\/api\/deployments\/[^/]+\/edge(\/.*)?$/);
   const isStorageHost = url.hostname === STORAGE_TEST_HOST;
+  let signedDeploymentId = null;
   if (requiresDeploymentHmac(request, url)) {
     const authHeader = request.headers.get("X-Stardeck-Auth");
     if (!authHeader) {
@@ -2038,6 +2114,7 @@ async function handleSimulatedRequest(request, url) {
     if (!authPayload || pathDeploymentId !== null && authPayload.deploymentId !== pathDeploymentId) {
       return failure("Invalid authentication", 401);
     }
+    signedDeploymentId = authPayload.deploymentId;
   }
   if (isStorageHost) {
     return handleStorageRequest(request, url);
@@ -2058,6 +2135,9 @@ async function handleSimulatedRequest(request, url) {
   if (edgeMatch) {
     return handleEdgeRequest(request, edgeMatch[1] ?? "");
   }
+  if (url.pathname === "/api/starlens/extract" && request.method === "POST") {
+    return handleStarlensExtract(request, signedDeploymentId);
+  }
   if (dataStoreMatch) {
     const subPath = dataStoreMatch[1] ?? "";
     const db = requireDb();
@@ -2079,7 +2159,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, 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, starlens extract, auth verify/refresh, Neon /sql.`,
     404
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardeck-customer-apps/testing",
-  "version": "0.13.0",
+  "version": "0.15.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",
@@ -70,7 +70,8 @@
     "@stardeck-customer-apps/payments-sdk": ">=0.1.0",
     "@stardeck-customer-apps/storage-sdk": ">=0.1.0",
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
-    "vitest": ">=2.0.0"
+    "vitest": ">=2.0.0",
+    "@stardeck-customer-apps/starlens": ">=0.1.0"
   },
   "peerDependenciesMeta": {
     "@stardeck-customer-apps/integrations-sdk": {
@@ -87,6 +88,9 @@
     },
     "next": {
       "optional": true
+    },
+    "@stardeck-customer-apps/starlens": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -106,6 +110,8 @@
     "tsup": "^8.0.0",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.0.0",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@stardeck-customer-apps/starlens": "*",
+    "zod": "^4.3.5"
   }
 }