@stardeck-customer-apps/testing 0.5.0 → 0.6.0

package/SKILL.md

@@ -2,8 +2,9 @@
 
 Vitest harness for Stardeck apps. Tests run against an **in-process Postgres
 (PGlite)** and a **simulated control plane**, so the real Stardeck SDKs
-(`data-store-sdk`, `email-sdk`, `project-auth`) execute their production code
-paths with no network, no mocks to write, and full determinism.
+(`data-store-sdk`, `email-sdk`, `project-auth`, and `integrations-sdk`) execute
+their production code paths with no network, no mocks to write, and full
+determinism.
 
 ## Setup (once per project)
 
@@ -53,7 +54,7 @@ beforeEach(() => app.reset());
 afterAll(() => app.close());
 
 describeWorkflow("checkout", () => {
-  it("completes an order, decrements stock, and emails the customer", async () => {
+  it("someone buys a widget and gets a confirmation email", async () => {
     const user = app.asUser({ email: "buyer@example.com" });
 
     const res = await callRoute(checkout, { body: { items: [{ sku: "Widget", qty: 2 }] } });
@@ -102,6 +103,34 @@ const integrations = createIntegrationsClient();
 await integrations.line.push("U123", { type: "text", text: "Your order shipped" });
 expect(app.messages.channel("line").to("U123")[0].body.text).toMatch(/shipped/i);
 
+// Guest/counter identity resolution. `provenance` is selected by this trusted
+// server route; never copy it from a browser form or request body.
+const identity = await integrations.identities.resolveOrCreate({
+  kind: "email",
+  externalId: "guest@example.com",
+  provenance: "guest",
+  displayName: "Guest",
+});
+if (identity.identityId) {
+  const identityId = identity.identityId;
+  const aliases = await integrations.identities.getAliases(identityId);
+  const aliasSet = Object.values(aliases).find((ids) => ids.includes(identityId)) ?? [identityId];
+  expect(aliasSet).toContain(identityId);
+}
+
+// A staff POS route derives `staff` only after checking an authenticated staff
+// session and permission. A guest lookup against a verified link returns the
+// safe conflict branch instead of attributing activity to that customer.
+const staffIdentity = await integrations.identities.resolveOrCreate({
+  kind: "phone",
+  externalId: "+15550100",
+  provenance: "staff",
+});
+if (staffIdentity.identityId) {
+  const page = await integrations.identities.search({ query: "15550100", limit: 10 });
+  expect(page.items.map((item) => item.id)).toContain(staffIdentity.identityId);
+}
+
 // Receipt print + display
 import { createEdgeClient } from "@stardeck-customer-apps/edge-sdk/server";
 
@@ -132,7 +161,11 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
   `.to(addr)`, `.all()`, `.count`, `.clear()`.
 - `app.identities` — the platform-identity directory created through
   integrations-sdk `client.identities`: `.get(id)`, `.links(id)`, `.all()`,
-  `.count`, `.clear()`.
+  `.count`, `.clear()`. The test-only `.seedVerifiedLink(id, { kind,
+externalId })` helper models a trusted platform/channel link, and
+  `.merge(sourceId, canonicalId)` models governed merge redirects. They are
+  setup helpers only; deployed app code cannot create verified links or merge
+  identities through the integrations SDK.
 - `app.payments` — checkouts created through payments-sdk:
   `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
   `.deliverStripeEvent(handler, event)`, `.deliverBeamEvent(handler, event)`,
@@ -153,6 +186,23 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
   ("checkout", "booking", "inventory"). The platform reports these per
   deployment — every critical workflow should have one.
 
+### Naming
+
+The app owner reads these names in the dashboard, under the workflow, without
+ever opening the code. Name the workflow after the business capability, and name
+each test after the thing a person does, in a full sentence:
+
+```ts
+describeWorkflow("checkout", () => {
+  it("someone adds an item to their cart", ...);
+  it("someone pays for their cart with a credit card", ...);
+  it("someone whose card is declined keeps their cart", ...);
+});
+```
+
+Not `it("POST /api/checkout returns 200")` or `it("decrements stock")` — those
+describe the code, and the owner can't tell from them what is or isn't covered.
+
 ## What works out of the box
 
 - `DataStoreClient` (query/insert/update/delete/schema ops) — served by the
@@ -163,9 +213,24 @@ expect(app.edge.latestDisplay()?.action).toBe("show");
   `asUser(...)` user (header fast path) or issued session cookies.
 - `EmailClient.send()` — captured in `app.inbox`, never delivered.
 - `client.identities` from integrations-sdk (create/get/update/list accounts &
-  persons, attach channel links) — served offline by the simulated directory;
-  `update` replaces the `profile` object (not a merge), like the control plane.
-  Inspect via `app.identities`. Merge/archive are dashboard-only — not simulated.
+  persons, attach channel links, guest/staff `resolveOrCreate`, paginated
+  `search`, and batch `getAliases`) — served offline by the simulated directory.
+  `resolveOrCreate` lowercases/trims email, requires E.164 phone values, and
+  always writes an unverified link. A guest lookup of a verified link returns
+  `{ identityId: null, reason: "verified_conflict" }`; staff provenance may
+  resolve either verified or unverified links. `attachLink(..., { verified:
+true })` remains source-compatible but the simulator (like the control plane)
+  ignores that flag and returns `verified: false`. `update` replaces the
+  `profile` object (not a merge), like the control plane. Inspect via
+  `app.identities`; merge/archive are privileged setup operations, with only
+  test-only merge modeling exposed above.
+- `session.user.identityId` is the platform-provisioned cross-app customer key.
+  `session.user.id` is the platform login key; it is not the key for customer
+  data. The simulator round-trips `identityId` through issued sessions while
+  preserving older users that omit it or set it to `null`.
+- For merge-correct reads, request aliases in batches and include every id in
+  the returned canonical set. Page directory UIs through `search({ query,
+cursor, limit })`; `list()` intentionally keeps its previous array shape.
 - `PaymentsServerClient` (Stripe checkout + Beam payment links, product list) —
   captured in `app.payments`; fulfill via `markPaid` (poll) or
   `deliverStripeEvent` / `deliverBeamEvent` (webhook push).

package/dist/index.d.mts

@@ -34,6 +34,8 @@ interface TestUser {
     permissions?: string[];
     organizationId?: string | null;
     projectId?: string | null;
+    /** Cross-app customer ownership key returned by the platform identity resolver. */
+    identityId?: string | null;
 }
 interface CapturedEmail {
     resendId: string;
@@ -103,6 +105,20 @@ interface TestDirectory {
     get(id: string): CapturedIdentity | undefined;
     /** Channel/login links attached to an identity. */
     links(identityId: string): CapturedIdentityLink[];
+    /**
+     * Test setup only: seed a platform-verified link. Deployment SDK writes are
+     * intentionally unverified; this helper models a trusted control-plane or
+     * channel source so guest conflict and adoption tests can be deterministic.
+     */
+    seedVerifiedLink(identityId: string, params: {
+        kind: string;
+        externalId: string;
+    }): CapturedIdentityLink;
+    /**
+     * Test setup only: govern a merge from one identity into an active canonical
+     * identity. The production integrations SDK does not expose merge operations.
+     */
+    merge(sourceIdentityId: string, canonicalIdentityId: string): void;
     clear(): void;
     get count(): number;
 }
@@ -353,6 +369,10 @@ declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
  * "booking", "inventory"). The platform parses the `workflow:` prefix out of
  * test reporter output to show per-workflow pass/fail on deployments — use
  * one block per workflow the app's owner cares about.
+ *
+ * The dashboard lists the workflow's test names beneath it, so title each test
+ * as a sentence about what a person does ("someone pays with a credit card"),
+ * not about the code under it.
  */
 declare function describeWorkflow(name: string, fn: () => void): void;
 declare const WORKFLOW_NAME_PREFIX = "workflow:";

package/dist/index.d.ts

@@ -34,6 +34,8 @@ interface TestUser {
     permissions?: string[];
     organizationId?: string | null;
     projectId?: string | null;
+    /** Cross-app customer ownership key returned by the platform identity resolver. */
+    identityId?: string | null;
 }
 interface CapturedEmail {
     resendId: string;
@@ -103,6 +105,20 @@ interface TestDirectory {
     get(id: string): CapturedIdentity | undefined;
     /** Channel/login links attached to an identity. */
     links(identityId: string): CapturedIdentityLink[];
+    /**
+     * Test setup only: seed a platform-verified link. Deployment SDK writes are
+     * intentionally unverified; this helper models a trusted control-plane or
+     * channel source so guest conflict and adoption tests can be deterministic.
+     */
+    seedVerifiedLink(identityId: string, params: {
+        kind: string;
+        externalId: string;
+    }): CapturedIdentityLink;
+    /**
+     * Test setup only: govern a merge from one identity into an active canonical
+     * identity. The production integrations SDK does not expose merge operations.
+     */
+    merge(sourceIdentityId: string, canonicalIdentityId: string): void;
     clear(): void;
     get count(): number;
 }
@@ -353,6 +369,10 @@ declare function createTestApp(options?: TestAppOptions): Promise<TestApp>;
  * "booking", "inventory"). The platform parses the `workflow:` prefix out of
  * test reporter output to show per-workflow pass/fail on deployments — use
  * one block per workflow the app's owner cares about.
+ *
+ * The dashboard lists the workflow's test names beneath it, so title each test
+ * as a sentence about what a person does ("someone pays with a credit card"),
+ * not about the code under it.
  */
 declare function describeWorkflow(name: string, fn: () => void): void;
 declare const WORKFLOW_NAME_PREFIX = "workflow:";