@stardeck-customer-apps/testing 0.14.0 → 0.16.0

package/SKILL.md

@@ -341,6 +341,37 @@ 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.
+- **Profile connections** (`client.identities.claims`) are driven from the same
+  accessor: `.claims()` and `.claim(claimId)` inspect what the app opened;
+  `.enableStaffAssist()` turns on the org opt-in that `assist`/`transfer` claims
+  need (off by default, so an un-opted project gets the real 403);
+  `.completeClaim(claimId, { clerkUserId })` models the customer finishing the
+  platform-hosted flow; `.refuseClaim(claimId, reason)` models reception or the
+  platform turning one down. `completeClaim` flips the claimed contact to
+  `verified`, or records `invalidated` when the contact is no longer on that
+  profile and `refused` / `contact_owned` when someone else already proved it.
+  Completing a finished claim replays the recorded result. It does not attach a
+  login or move history — the platform's merge core is not modelled.
+  `.allowReturnOrigin(origin)` widens the allowed `returnTo` origins (the test
+  app's own origin is allowed by default); a `returnTo` anywhere else is dropped
+  silently, exactly as the platform drops it. `claimUrl` carries a one-time
+  opaque handle, so never assert it contains the claim id, and `deliver: true`
+  comes back as `delivered`. `.suppressClaimDelivery()` models the platform
+  sending nothing (a suppressed quota, a bounced address): `deliver: true` then
+  returns `delivered: false` with the `claimUrl` still valid, so the app's own
+  fallback delivery can be tested.
+
+  ```ts
+  const claim = await integrations.identities.claims.create({
+    flow: "invite",
+    identityId: person.id,
+    kind: "phone",
+    externalId: "+15550100",
+  });
+  app.identities.completeClaim(claim.claimId, { clerkUserId: "user_1" });
+  expect((await integrations.identities.claims.get(claim.claimId)).state).toBe("completed");
+  ```
+
 - `app.payments` — checkouts created through payments-sdk:
   `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
   `.setSessionStatus(id, status)`, `.setPaymentLinkStatus(id, status)`,
@@ -409,11 +440,16 @@ describe the code, and the owner can't tell from them what is or isn't covered.
   A–Z→a–z; Turkish İ is left unchanged), 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` accepts only
-  channel kinds (line/facebook/instagram/email/phone); login keys must be
-  seeded via `app.identities.seedVerifiedLink`. `attachLink(..., { verified:
+  resolve either verified or unverified links. `attachLink` records a contact or
+  channel id (line/facebook/instagram/email/phone); login keys must be seeded
+  via `app.identities.seedVerifiedLink`. `attachLink(..., { verified:
 true })` remains source-compatible but the simulator (like the control plane)
-  ignores that flag and returns `verified: false`. `update` replaces the
+  ignores that flag and returns `verified: false`. An **unverified** email or
+  phone may be recorded on several identities (a household sharing one number);
+  a verified holder makes a further _verified_ attach conflict, but unverified
+  copies still succeed, and `resolveOrCreate` prefers the verified owner and
+  otherwise the earliest unverified holder. Channel and login kinds stay
+  single-owner and 409 on a second holder. `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.
@@ -451,6 +487,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

@@ -105,6 +105,32 @@ interface CapturedIdentityLink {
  * the control plane that `client.identities` talks to in tests. Identities and
  * links created by app code under test land here; assert on them like `inbox`.
  */
+interface CapturedIdentityClaim {
+    claimId: string;
+    flow: "invite" | "assist" | "transfer";
+    /** The profile the claim connects the customer to. */
+    identityId: string;
+    kind: "email" | "phone";
+    externalId: string;
+    returnTo: string | null;
+    /** The app's reference for the staff member, for assist/transfer claims. */
+    staffActorRef: string | null;
+    state: "pending" | "completed" | "expired" | "invalidated" | "refused";
+    refusalReason: string | null;
+    completedIdentityId: string | null;
+    /** Set by completeClaim; models the Clerk account that proved the contact. */
+    claimantClerkUserId: string | null;
+    /**
+     * Hosted claim link. Its path carries a one-time opaque handle, NOT the claim
+     * id — the platform never makes the customer's page derivable from an id an
+     * app already holds.
+     */
+    claimUrl: string;
+    /** Whether the platform sent the link itself (only when `deliver` was asked). */
+    delivered: boolean | null;
+    expiresAt: string;
+    createdAt: string;
+}
 interface TestDirectory {
     /** All identities, oldest first. */
     all(): CapturedIdentity[];
@@ -126,6 +152,43 @@ interface TestDirectory {
      * identity. The production integrations SDK does not expose merge operations.
      */
     merge(sourceIdentityId: string, canonicalIdentityId: string): void;
+    /** Every profile-connection claim the app has opened, oldest first. */
+    claims(): CapturedIdentityClaim[];
+    /** A single claim by id, or undefined. */
+    claim(claimId: string): CapturedIdentityClaim | undefined;
+    /**
+     * Test setup only: turn on the org's staff-assistance opt-in. Without it,
+     * `claims.create` refuses `assist` and `transfer` with 403, like the platform.
+     */
+    enableStaffAssist(enabled?: boolean): void;
+    /**
+     * Test setup only: model the platform failing to send a claim link it was
+     * asked to deliver (a suppressed quota, a bounced address). `deliver: true`
+     * then comes back `delivered: false` with the `claimUrl` still valid, so an
+     * app's own fallback delivery can be tested.
+     */
+    suppressClaimDelivery(enabled?: boolean): void;
+    /**
+     * Test setup only: allow a claim `returnTo` on this origin. The harness app's
+     * own origin is allowed by default; anything else is dropped silently, like
+     * the platform's allowed-origins check.
+     */
+    allowReturnOrigin(origin: string): void;
+    /**
+     * Test setup only: model the customer finishing the platform-hosted claim —
+     * Clerk proof plus their confirmation. Flips the claimed contact to verified,
+     * or records `invalidated` (the contact was removed from that profile) or
+     * `refused` with `contact_owned` (someone else already proved it). Replaying a
+     * finished claim returns the recorded result unchanged.
+     *
+     * It does NOT attach a login link or move history: the platform's merge core
+     * is not modelled here, only the ownership decision the app can observe.
+     */
+    completeClaim(claimId: string, params: {
+        clerkUserId: string;
+    }): CapturedIdentityClaim;
+    /** Test setup only: model reception or the platform refusing a claim. */
+    refuseClaim(claimId: string, reason: string): CapturedIdentityClaim;
     clear(): void;
     get count(): number;
 }
@@ -462,6 +525,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 +607,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[]>;
     /**
@@ -571,4 +674,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

@@ -105,6 +105,32 @@ interface CapturedIdentityLink {
  * the control plane that `client.identities` talks to in tests. Identities and
  * links created by app code under test land here; assert on them like `inbox`.
  */
+interface CapturedIdentityClaim {
+    claimId: string;
+    flow: "invite" | "assist" | "transfer";
+    /** The profile the claim connects the customer to. */
+    identityId: string;
+    kind: "email" | "phone";
+    externalId: string;
+    returnTo: string | null;
+    /** The app's reference for the staff member, for assist/transfer claims. */
+    staffActorRef: string | null;
+    state: "pending" | "completed" | "expired" | "invalidated" | "refused";
+    refusalReason: string | null;
+    completedIdentityId: string | null;
+    /** Set by completeClaim; models the Clerk account that proved the contact. */
+    claimantClerkUserId: string | null;
+    /**
+     * Hosted claim link. Its path carries a one-time opaque handle, NOT the claim
+     * id — the platform never makes the customer's page derivable from an id an
+     * app already holds.
+     */
+    claimUrl: string;
+    /** Whether the platform sent the link itself (only when `deliver` was asked). */
+    delivered: boolean | null;
+    expiresAt: string;
+    createdAt: string;
+}
 interface TestDirectory {
     /** All identities, oldest first. */
     all(): CapturedIdentity[];
@@ -126,6 +152,43 @@ interface TestDirectory {
      * identity. The production integrations SDK does not expose merge operations.
      */
     merge(sourceIdentityId: string, canonicalIdentityId: string): void;
+    /** Every profile-connection claim the app has opened, oldest first. */
+    claims(): CapturedIdentityClaim[];
+    /** A single claim by id, or undefined. */
+    claim(claimId: string): CapturedIdentityClaim | undefined;
+    /**
+     * Test setup only: turn on the org's staff-assistance opt-in. Without it,
+     * `claims.create` refuses `assist` and `transfer` with 403, like the platform.
+     */
+    enableStaffAssist(enabled?: boolean): void;
+    /**
+     * Test setup only: model the platform failing to send a claim link it was
+     * asked to deliver (a suppressed quota, a bounced address). `deliver: true`
+     * then comes back `delivered: false` with the `claimUrl` still valid, so an
+     * app's own fallback delivery can be tested.
+     */
+    suppressClaimDelivery(enabled?: boolean): void;
+    /**
+     * Test setup only: allow a claim `returnTo` on this origin. The harness app's
+     * own origin is allowed by default; anything else is dropped silently, like
+     * the platform's allowed-origins check.
+     */
+    allowReturnOrigin(origin: string): void;
+    /**
+     * Test setup only: model the customer finishing the platform-hosted claim —
+     * Clerk proof plus their confirmation. Flips the claimed contact to verified,
+     * or records `invalidated` (the contact was removed from that profile) or
+     * `refused` with `contact_owned` (someone else already proved it). Replaying a
+     * finished claim returns the recorded result unchanged.
+     *
+     * It does NOT attach a login link or move history: the platform's merge core
+     * is not modelled here, only the ownership decision the app can observe.
+     */
+    completeClaim(claimId: string, params: {
+        clerkUserId: string;
+    }): CapturedIdentityClaim;
+    /** Test setup only: model reception or the platform refusing a claim. */
+    refuseClaim(claimId: string, reason: string): CapturedIdentityClaim;
     clear(): void;
     get count(): number;
 }
@@ -462,6 +525,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 +607,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[]>;
     /**
@@ -571,4 +674,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 };