@stardeck-customer-apps/testing 0.15.0 → 0.17.0

package/SKILL.md

@@ -341,6 +341,64 @@ 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. Completion attaches
+  the claimant's login to the profile (moving it off any profile it was on), but
+  does not 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. Bearer links are on by default, like the platform;
+  `.enableBearerLinks(false)` models a project whose admin turned them off. A bearer claim is raised against a
+  profile with no contact at all, so it takes no `kind`/`externalId`/`deliver`
+  (sending one is refused, not ignored) and `completeClaim` connects whoever
+  completes it — unless another login already holds that profile, which comes
+  back `refused` / `owned_elsewhere`. That refusal is the one a leaked bearer
+  link runs into, so test it. A profile that holds an email or phone is refused
+  at `create` with a 409 (send an `invite`); one that gains a contact before
+  the link is used completes as `refused` / `protected`, and a link still
+  outstanding when `.enableBearerLinks(false)` runs completes as `refused` /
+  `expired`. People seeded with only a `dashboard_user` link (team members) are
+  left out of `identities.list()` and `search()`, as on the platform.
+  `search({ attributes })` matches profile attributes exactly and by JSON type
+  (`5` never matches `"5"`) and rejects nested, array, `null` or more than 10
+  keys (or a `__proto__` key) with a `ValidationError` whose message matches the
+  platform's, like the platform.
+
+  ```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");
+  ```
+
+  ```ts
+  // A name on a card, no email or phone: the link IS the authorisation.
+  const bearer = await integrations.identities.claims.create({
+    flow: "bearer",
+    identityId: walkIn.id,
+  });
+  expect(app.identities.completeClaim(bearer.claimId, { clerkUserId: "user_2" }).state).toBe(
+    "completed"
+  );
+  ```
+
 - `app.payments` — checkouts created through payments-sdk:
   `.checkouts`, `.latest()`, `.setProducts()`, `.markPaid(id)`,
   `.setSessionStatus(id, status)`, `.setPaymentLinkStatus(id, status)`,
@@ -409,12 +467,20 @@ 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
-  `profile` object (not a merge), like the control plane. Inspect via
+  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. A person with a
+  seeded `dashboard_user` link is a team member: changing their `displayName`
+  or `profile.email` is refused with a 409 `ValidationError`, and a new
+  `profile` without `email` keeps the current one, as on the platform. 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.

package/dist/index.d.mts

@@ -105,6 +105,33 @@ 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" | "bearer";
+    /** The profile the claim connects the customer to. */
+    identityId: string;
+    /** The recorded contact this claim was raised against. Null for `bearer` only. */
+    kind: "email" | "phone" | null;
+    externalId: string | null;
+    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 +153,49 @@ 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: set the project's bearer-link opt-in. It is on by default,
+     * like the platform; pass `false` to model an org that switched it off, and
+     * `claims.create({ flow: "bearer" })` is then refused with 403.
+     */
+    enableBearerLinks(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;
 }

package/dist/index.d.ts

@@ -105,6 +105,33 @@ 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" | "bearer";
+    /** The profile the claim connects the customer to. */
+    identityId: string;
+    /** The recorded contact this claim was raised against. Null for `bearer` only. */
+    kind: "email" | "phone" | null;
+    externalId: string | null;
+    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 +153,49 @@ 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: set the project's bearer-link opt-in. It is on by default,
+     * like the platform; pass `false` to model an org that switched it off, and
+     * `claims.create({ flow: "bearer" })` is then refused with 403.
+     */
+    enableBearerLinks(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;
 }