@smileid/usesmileid 12.0.0 → 12.0.2

package/src/data/model/__tests__/token_payload.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from "vitest";
+import {
+  isTokenConsentComplete,
+  tokenConsentMissingSubfields,
+  parseTokenPayload,
+  bindsRequiredUserDetails,
+  type TokenPayload,
+} from "../token_payload";
+
+// Canonical backend claim — user-detail values are opaque vault
+// references; only key presence is meaningful client-side.
+const FULL_CLAIM = {
+  given_names: "pii_abc",
+  last_name: "pii_def",
+  email: "pii_ghi",
+  phone_number: "pii_jkl",
+  consent: {
+    granted: true,
+    granted_at: "2026-01-01T09:00:00.000Z",
+    notice_language: "EN",
+    notice_privacy_policy_url: "https://partner.test/privacy",
+  },
+} as const;
+
+describe("parseTokenPayload — claim-shape tolerance", () => {
+  it("parses the full canonical claim into presence flags + complete consent", () => {
+    const payload = parseTokenPayload(FULL_CLAIM);
+    expect(payload).toEqual({
+      hasGivenNames: true,
+      hasLastName: true,
+      hasEmail: true,
+      hasPhoneNumber: true,
+      consent: {
+        granted: true,
+        grantedAt: "2026-01-01T09:00:00.000Z",
+        noticeLanguage: "EN",
+        noticePrivacyPolicyUrl: "https://partner.test/privacy",
+      },
+    });
+  });
+
+  it("parses a subset claim — only the present keys flag true", () => {
+    const payload = parseTokenPayload({ email: "pii_x" });
+    expect(payload).toEqual({
+      hasGivenNames: false,
+      hasLastName: false,
+      hasEmail: true,
+      hasPhoneNumber: false,
+    });
+  });
+
+  it("returns undefined for a non-object claim (string / array / number / null)", () => {
+    expect(parseTokenPayload("payload")).toBeUndefined();
+    expect(parseTokenPayload(["pii_x"])).toBeUndefined();
+    expect(parseTokenPayload(42)).toBeUndefined();
+    expect(parseTokenPayload(null)).toBeUndefined();
+    expect(parseTokenPayload(undefined)).toBeUndefined();
+  });
+
+  it("treats an empty string value as not binding the field", () => {
+    const payload = parseTokenPayload({ given_names: "", email: "pii_x" });
+    expect(payload?.hasGivenNames).toBe(false);
+    expect(payload?.hasEmail).toBe(true);
+  });
+
+  it("degrades a wrong-typed identity field to absent without dropping its siblings", () => {
+    const payload = parseTokenPayload({
+      given_names: 42,
+      last_name: ["pii"],
+      email: "pii_x",
+    });
+    expect(payload?.hasGivenNames).toBe(false);
+    expect(payload?.hasLastName).toBe(false);
+    expect(payload?.hasEmail).toBe(true);
+  });
+
+  it("ignores unknown keys and the out-of-scope id/callback fields", () => {
+    const payload = parseTokenPayload({
+      country: "NG",
+      id_type: "NIN",
+      id_number: "pii_id",
+      callback_url: "callback_x",
+      something_new: { nested: true },
+      last_name: "pii_def",
+    });
+    expect(payload).toEqual({
+      hasGivenNames: false,
+      hasLastName: true,
+      hasEmail: false,
+      hasPhoneNumber: false,
+    });
+  });
+
+  it("treats a non-object consent (string / array) as absent", () => {
+    expect(parseTokenPayload({ consent: "granted" })?.consent).toBeUndefined();
+    expect(parseTokenPayload({ consent: [true] })?.consent).toBeUndefined();
+  });
+
+  it("treats an empty consent object as absent", () => {
+    expect(parseTokenPayload({ consent: {} })?.consent).toBeUndefined();
+  });
+
+  it('never trusts granted: false or granted: "yes" as a binding', () => {
+    const deniedConsent = parseTokenPayload({
+      consent: { granted: false, granted_at: "2026-01-01T09:00:00.000Z" },
+    })?.consent;
+    expect(deniedConsent?.granted).toBeUndefined();
+    expect(deniedConsent?.grantedAt).toBe("2026-01-01T09:00:00.000Z");
+
+    const stringGranted = parseTokenPayload({
+      consent: { granted: "yes" },
+    })?.consent;
+    expect(stringGranted).toBeUndefined();
+  });
+
+  it("degrades wrong-typed consent subfields individually", () => {
+    const consent = parseTokenPayload({
+      consent: { granted: true, granted_at: 12345, notice_language: "EN" },
+    })?.consent;
+    expect(consent).toEqual({ granted: true, noticeLanguage: "EN" });
+  });
+
+  it("never throws for arbitrary claim shapes", () => {
+    const inputs: unknown[] = [
+      {},
+      FULL_CLAIM,
+      { consent: { granted: null } },
+      { given_names: { nested: true } },
+      Object.create(null),
+    ];
+    for (const input of inputs) {
+      expect(() => parseTokenPayload(input)).not.toThrow();
+    }
+  });
+});
+
+describe("isTokenConsentComplete", () => {
+  const completeConsent = {
+    granted: true,
+    grantedAt: "2026-01-01T09:00:00.000Z",
+    noticeLanguage: "EN",
+    noticePrivacyPolicyUrl: "https://partner.test/privacy",
+  } as const;
+
+  it("is true only when granted and all three subfields are non-blank", () => {
+    expect(isTokenConsentComplete(completeConsent)).toBe(true);
+  });
+
+  it("is false when any subfield is missing or blank", () => {
+    expect(isTokenConsentComplete(undefined)).toBe(false);
+    const { granted: _granted, ...withoutGranted } = completeConsent;
+    expect(isTokenConsentComplete(withoutGranted)).toBe(false);
+    const { noticeLanguage: _language, ...withoutLanguage } = completeConsent;
+    expect(isTokenConsentComplete(withoutLanguage)).toBe(false);
+    expect(
+      isTokenConsentComplete({ ...completeConsent, grantedAt: "  " }),
+    ).toBe(false);
+    expect(
+      isTokenConsentComplete({
+        ...completeConsent,
+        noticePrivacyPolicyUrl: "",
+      }),
+    ).toBe(false);
+  });
+
+  it("missingSubfields names exactly the absent or blank consent subfields", () => {
+    expect(tokenConsentMissingSubfields(completeConsent)).toEqual([]);
+    const { granted: _granted, ...withoutGranted } = completeConsent;
+    expect(tokenConsentMissingSubfields(withoutGranted)).toEqual(["granted"]);
+    const { noticeLanguage: _language, ...withoutLanguage } = completeConsent;
+    expect(
+      tokenConsentMissingSubfields({ ...withoutLanguage, grantedAt: " " }),
+    ).toEqual(["granted_at", "notice_language"]);
+    expect(tokenConsentMissingSubfields({})).toEqual([
+      "granted",
+      "granted_at",
+      "notice_language",
+      "notice_privacy_policy_url",
+    ]);
+  });
+});
+
+describe("bindsRequiredUserDetails", () => {
+  function payload(overrides: Partial<TokenPayload>): TokenPayload {
+    return {
+      hasGivenNames: false,
+      hasLastName: false,
+      hasEmail: false,
+      hasPhoneNumber: false,
+      ...overrides,
+    };
+  }
+
+  it("requires both names plus at least one contact field", () => {
+    expect(
+      bindsRequiredUserDetails(
+        payload({ hasGivenNames: true, hasLastName: true, hasEmail: true }),
+      ),
+    ).toBe(true);
+    expect(
+      bindsRequiredUserDetails(
+        payload({
+          hasGivenNames: true,
+          hasLastName: true,
+          hasPhoneNumber: true,
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("is false when a name or every contact field is missing", () => {
+    expect(
+      bindsRequiredUserDetails(
+        payload({ hasGivenNames: true, hasLastName: true }),
+      ),
+    ).toBe(false);
+    expect(
+      bindsRequiredUserDetails(
+        payload({ hasGivenNames: true, hasEmail: true }),
+      ),
+    ).toBe(false);
+    expect(bindsRequiredUserDetails(undefined)).toBe(false);
+  });
+});

package/src/data/model/__tests__/user_details_payload.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import type { UserDetails } from "../../../core/models/params";
+import {
+  isUserDetailsPayloadEmpty,
+  userDetailsPayloadFrom,
+  userDetailsPayloadToWire,
+} from "../user_details_payload";
+
+// Pins the `user_details` wire carrier: token-bound fields are stripped,
+// nothing-stripped output matches the legacy `UserDetails` encoding, and an
+// all-stripped payload reads as empty so the part is omitted rather than
+// sent as `{}`.
+describe("UserDetailsPayload", () => {
+  const details: UserDetails = {
+    givenNames: "Ada",
+    lastName: "Lovelace",
+    email: "ada@example.test",
+    phoneNumber: "+2348000000000",
+  };
+
+  it("no token binding keeps every field and matches the UserDetails wire encoding", () => {
+    const payload = userDetailsPayloadFrom(details, undefined);
+
+    expect(payload).toEqual(details);
+    expect(isUserDetailsPayloadEmpty(payload)).toBe(false);
+    expect(userDetailsPayloadToWire(payload)).toEqual({
+      given_names: "Ada",
+      last_name: "Lovelace",
+      email: "ada@example.test",
+      phone_number: "+2348000000000",
+    });
+  });
+
+  it("an empty token payload binding nothing keeps every field", () => {
+    const payload = userDetailsPayloadFrom(details, {
+      hasGivenNames: false,
+      hasLastName: false,
+      hasEmail: false,
+      hasPhoneNumber: false,
+    });
+
+    expect(payload).toEqual(details);
+  });
+
+  it("token-bound fields are dropped individually", () => {
+    const payload = userDetailsPayloadFrom(details, {
+      hasGivenNames: true,
+      hasLastName: true,
+      hasEmail: false,
+      hasPhoneNumber: false,
+    });
+
+    expect(payload.givenNames).toBeUndefined();
+    expect(payload.lastName).toBeUndefined();
+    expect(payload.email).toBe("ada@example.test");
+    expect(payload.phoneNumber).toBe("+2348000000000");
+    expect(Object.keys(userDetailsPayloadToWire(payload)).sort()).toEqual([
+      "email",
+      "phone_number",
+    ]);
+  });
+
+  it("fully bound details read as empty", () => {
+    const payload = userDetailsPayloadFrom(details, {
+      hasGivenNames: true,
+      hasLastName: true,
+      hasEmail: true,
+      hasPhoneNumber: true,
+    });
+
+    expect(isUserDetailsPayloadEmpty(payload)).toBe(true);
+  });
+
+  it("blank contact fields count as empty and are omitted from the wire", () => {
+    const payload = userDetailsPayloadFrom(
+      { givenNames: "Ada", lastName: "Lovelace", email: "  ", phoneNumber: "" },
+      {
+        hasGivenNames: true,
+        hasLastName: true,
+        hasEmail: false,
+        hasPhoneNumber: false,
+      },
+    );
+
+    // Blank contacts encode to nothing, so nothing remains.
+    expect(isUserDetailsPayloadEmpty(payload)).toBe(true);
+    expect(userDetailsPayloadToWire(payload)).toEqual({});
+  });
+
+  it("contact fields are trimmed on the wire", () => {
+    const wire = userDetailsPayloadToWire({
+      givenNames: "Ada",
+      lastName: "Lovelace",
+      email: " ada@example.test ",
+    });
+
+    expect(wire["email"]).toBe("ada@example.test");
+    expect(wire["phone_number"]).toBeUndefined();
+  });
+});

package/src/data/model/job_request.ts

@@ -2,8 +2,8 @@ import type {
   ConsentInformation,
   EnhancedKYCParams,
   BiometricKYCParams,
-  UserDetails,
 } from "../../core/models/params";
+import type { UserDetailsPayload } from "./user_details_payload";
 import { JobType } from "../../core/models/job_type";
 import type { UseSmileIDMetadata } from "../../metadata/use_smile_id_metadata";
 
@@ -12,10 +12,11 @@ import type { UseSmileIDMetadata } from "../../metadata/use_smile_id_metadata";
  * narrows the union and tells the repository which API method to
  * dispatch to.
  *
- * Every variant intersects [BaseJobRequest], which carries the two
+ * Every variant intersects [BaseJobRequest], which carries the
  * fields shared by all submissions: the partner-captured `consent`
- * record and the per-submission `metadata` snapshot. Variants keep a
- * narrowed `jobType` literal so the union still discriminates.
+ * record, the per-submission `metadata` snapshot, and the decoded
+ * token bindings. Variants keep a narrowed `jobType` literal so the
+ * union still discriminates.
  *
  * `metadata` is built at the request-construction site (the flow
  * navigation manager) and travels on the request itself — the API
@@ -23,7 +24,14 @@ import type { UseSmileIDMetadata } from "../../metadata/use_smile_id_metadata";
  * multipart part rather than generating the snapshot at submit time.
  */
 export interface BaseJobRequest {
-  readonly consent: ConsentInformation;
+  /**
+   * Local consent record (captured on the consent screen or
+   * pre-supplied via the builder). Omitted only when no local source
+   * exists AND the token binds complete consent — the API layer then
+   * omits the `consent` multipart part and the server injects the
+   * token's consent.
+   */
+  readonly consent?: ConsentInformation;
   readonly metadata: UseSmileIDMetadata;
 }
 
@@ -31,7 +39,8 @@ export type SmartSelfieEnrollmentRequest = BaseJobRequest & {
   readonly jobType: typeof JobType.smartSelfieEnrollment;
   readonly selfieImage: string;
   readonly livenessImages: readonly string[];
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
   /**
    * Screen-level enhanced-liveness intent marker. The wire path is
    * always `/v3/registration` (and `/v3/authentication` on the auth
@@ -59,7 +68,8 @@ export type SmartSelfieAuthenticationRequest = BaseJobRequest & {
   readonly jobType: typeof JobType.smartSelfieAuthentication;
   readonly selfieImage: string;
   readonly livenessImages: readonly string[];
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
   /**
    * The `user_id` returned by a prior enrollment — the v3
    * `/v3/authentication` endpoint requires it so the server can match
@@ -77,7 +87,8 @@ export type SmartSelfieAuthenticationRequest = BaseJobRequest & {
 export type EnhancedKycRequest = BaseJobRequest & {
   readonly jobType: typeof JobType.enhancedKyc;
   readonly params: EnhancedKYCParams;
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
 };
 
 /**
@@ -90,7 +101,8 @@ export type EnhancedKycRequest = BaseJobRequest & {
 export type BvnRequest = BaseJobRequest & {
   readonly jobType: typeof JobType.bvn;
   readonly params: EnhancedKYCParams;
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
 };
 
 export type BiometricKycRequest = BaseJobRequest & {
@@ -98,7 +110,8 @@ export type BiometricKycRequest = BaseJobRequest & {
   readonly selfieImage: string;
   readonly livenessImages: readonly string[];
   readonly params: BiometricKYCParams;
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
   /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
   readonly expectedLivenessImageCount: number;
 };
@@ -114,7 +127,8 @@ export type DocumentVerificationRequest = BaseJobRequest & {
   readonly country: string;
   /** Optional — the server classifies the document when omitted. */
   readonly idType?: string;
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
   /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
   readonly expectedLivenessImageCount: number;
 };
@@ -135,7 +149,8 @@ export type EnhancedDocumentVerificationRequest = BaseJobRequest & {
   readonly backDocument?: string;
   readonly country: string;
   readonly idType: string;
-  readonly userDetails: UserDetails;
+  /** Omitted when the token binds every required field, or reduced to the unbound remainder. */
+  readonly userDetails?: UserDetailsPayload;
   /** See `SmartSelfieEnrollmentRequest.expectedLivenessImageCount`. */
   readonly expectedLivenessImageCount: number;
 };

package/src/data/model/token_payload.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+
+/**
+ * User-detail and consent bindings delivered via the JWT auth token.
+ *
+ * The backend embeds this object under the top-level `payload` claim
+ * (JWT payload, base64url-decoded middle segment) when the partner
+ * binds user details and/or consent into the token on their backend.
+ * User-detail values in the claim are opaque vault references — only
+ * key PRESENCE is meaningful client-side. Consent subfields are
+ * plaintext. `country` / `id_type` / `id_number` / `callback_url` may
+ * also appear in the claim but are deliberately ignored.
+ *
+ * Every field is optional and every field tolerates a wrong wire type
+ * by degrading to absent — a malformed claim never rejects the token.
+ *
+ * Field names are a deliberate cross-SDK shared contract that
+ * intentionally omits the `UseSmileID` prefix. Internal — not
+ * re-exported from the package entrypoint (`src/index.ts`).
+ */
+
+const tokenConsentClaimSchema = z.object({
+  /** Only a literal `true` counts — `false` or a non-boolean is never trusted as a binding. */
+  granted: z.literal(true).optional().catch(undefined),
+  granted_at: z.string().optional().catch(undefined),
+  notice_language: z.string().optional().catch(undefined),
+  notice_privacy_policy_url: z.string().optional().catch(undefined),
+});
+
+/**
+ * Tolerant wire schema for the `payload` claim. Unknown keys are
+ * stripped; a wrong-typed field degrades to `undefined` (per-field
+ * `.catch`) instead of failing the whole claim.
+ */
+export const tokenPayloadSchema = z.object({
+  given_names: z.string().optional().catch(undefined),
+  last_name: z.string().optional().catch(undefined),
+  email: z.string().optional().catch(undefined),
+  phone_number: z.string().optional().catch(undefined),
+  /** Non-object / array consent values degrade to absent. */
+  consent: tokenConsentClaimSchema.optional().catch(undefined),
+});
+
+/**
+ * Consent subfields bound into the token. Token consent always wins:
+ * a complete binding (see {@link isTokenConsentComplete}) supersedes
+ * every local consent source, and a partial binding is a build-time
+ * validation error naming the missing subfields (see
+ * {@link tokenConsentMissingSubfields}).
+ */
+export type TokenConsent = {
+  /** Present (and `true`) only when the claim carried a literal `granted: true`. */
+  readonly granted?: boolean;
+  /** ISO-8601 timestamp from the claim's `granted_at`. */
+  readonly grantedAt?: string;
+  /** Language code from the claim's `notice_language`. */
+  readonly noticeLanguage?: string;
+  /** URL from the claim's `notice_privacy_policy_url`. */
+  readonly noticePrivacyPolicyUrl?: string;
+};
+
+/**
+ * Presence flags for the identity fields the token binds, parsed from
+ * the `payload` claim. A flag is `true` iff the claim carries the key
+ * with a non-empty string value (the value itself is an opaque vault
+ * reference — the server injects the real value at submission).
+ */
+export type TokenPayload = {
+  readonly hasGivenNames: boolean;
+  readonly hasLastName: boolean;
+  readonly hasEmail: boolean;
+  readonly hasPhoneNumber: boolean;
+  readonly consent?: TokenConsent;
+};
+
+/**
+ * Parse a raw `payload` claim value into a `TokenPayload`, or
+ * `undefined` when the claim is absent or not a JSON object. Mirrors
+ * the `sdk_config` degradation semantics: never throws, tolerates
+ * unknown keys, and degrades wrong-typed fields to absent.
+ */
+export function parseTokenPayload(rawClaim: unknown): TokenPayload | undefined {
+  if (
+    rawClaim === null ||
+    typeof rawClaim !== "object" ||
+    Array.isArray(rawClaim)
+  ) {
+    return undefined;
+  }
+  const parseResult = tokenPayloadSchema.safeParse(rawClaim);
+  if (!parseResult.success) {
+    // Unreachable in practice (every field carries a `.catch`), but
+    // degrade gracefully to preserve the never-throws contract.
+    return undefined;
+  }
+  const claim = parseResult.data;
+  const consent = tokenConsentFromClaim(claim.consent);
+  return {
+    hasGivenNames: isPresent(claim.given_names),
+    hasLastName: isPresent(claim.last_name),
+    hasEmail: isPresent(claim.email),
+    hasPhoneNumber: isPresent(claim.phone_number),
+    ...(consent !== undefined ? { consent } : {}),
+  };
+}
+
+/**
+ * Token consent is COMPLETE when `granted` is `true` and every other
+ * subfield is non-blank. A complete binding — granted with every
+ * notice subfield non-blank — satisfies the consent requirement
+ * without a local source. Token consent always wins, so a partial
+ * binding is a build-time validation error.
+ */
+export function isTokenConsentComplete(
+  consent: TokenConsent | undefined,
+): boolean {
+  return (
+    consent !== undefined && tokenConsentMissingSubfields(consent).length === 0
+  );
+}
+
+/**
+ * Wire-key names of the consent subfields the binding is missing. A
+ * token that carries a consent object must carry all four subfields —
+ * a non-empty list is a build-time validation error naming exactly
+ * what the token must add.
+ */
+export function tokenConsentMissingSubfields(
+  consent: TokenConsent,
+): readonly string[] {
+  const missing: string[] = [];
+  if (consent.granted !== true) missing.push("granted");
+  if (!isNonBlank(consent.grantedAt)) missing.push("granted_at");
+  if (!isNonBlank(consent.noticeLanguage)) missing.push("notice_language");
+  if (!isNonBlank(consent.noticePrivacyPolicyUrl)) {
+    missing.push("notice_privacy_policy_url");
+  }
+  return missing;
+}
+
+/**
+ * Whether the token binds every user-detail field the SDK would
+ * otherwise require from the builder: `given_names` AND `last_name`
+ * AND at least one of `email` / `phone_number`. Only then may
+ * `builder.userDetails` be omitted entirely.
+ */
+export function bindsRequiredUserDetails(
+  payload: TokenPayload | undefined,
+): boolean {
+  if (payload === undefined) return false;
+  return (
+    payload.hasGivenNames &&
+    payload.hasLastName &&
+    (payload.hasEmail || payload.hasPhoneNumber)
+  );
+}
+
+function tokenConsentFromClaim(
+  claim: z.infer<typeof tokenConsentClaimSchema> | undefined,
+): TokenConsent | undefined {
+  if (claim === undefined) return undefined;
+  const consent: TokenConsent = {
+    ...(claim.granted === true ? { granted: true } : {}),
+    ...(claim.granted_at !== undefined ? { grantedAt: claim.granted_at } : {}),
+    ...(claim.notice_language !== undefined
+      ? { noticeLanguage: claim.notice_language }
+      : {}),
+    ...(claim.notice_privacy_policy_url !== undefined
+      ? { noticePrivacyPolicyUrl: claim.notice_privacy_policy_url }
+      : {}),
+  };
+  // An empty consent object binds nothing — treat it as absent.
+  return Object.keys(consent).length > 0 ? consent : undefined;
+}
+
+function isPresent(value: string | undefined): boolean {
+  return value !== undefined && value.length > 0;
+}
+
+function isNonBlank(value: string | undefined): boolean {
+  return value !== undefined && value.trim().length > 0;
+}

package/src/data/model/user_details_payload.ts

@@ -0,0 +1,84 @@
+import type { UserDetails } from "../../core/models/params";
+import type { TokenPayload } from "./token_payload";
+
+/**
+ * Wire carrier for the `user_details` multipart part.
+ *
+ * Unlike `UserDetails` — the partner-facing input model whose names are
+ * required — every field here is optional so the part can carry only the
+ * fields the token does **not** already bind. Token-bound fields are dropped
+ * at assembly (`userDetailsPayloadFrom`): the server injects the bound values
+ * and they take precedence over anything the client sends. When nothing
+ * remains, assembly omits the part entirely (`isUserDetailsPayloadEmpty`).
+ *
+ * Type and helper names are a deliberate cross-SDK shared contract and
+ * intentionally omit the `UseSmileID` prefix (like `TokenPayload`).
+ */
+export type UserDetailsPayload = {
+  readonly givenNames?: string;
+  readonly lastName?: string;
+  readonly email?: string;
+  readonly phoneNumber?: string;
+};
+
+/**
+ * Build the payload from builder-supplied details, dropping every field the
+ * token binds. With no token binding this reproduces `UserDetails`' wire
+ * encoding unchanged.
+ */
+export function userDetailsPayloadFrom(
+  userDetails: UserDetails,
+  droppingFieldsBoundBy: TokenPayload | undefined,
+): UserDetailsPayload {
+  return {
+    ...(droppingFieldsBoundBy?.hasGivenNames
+      ? {}
+      : { givenNames: userDetails.givenNames }),
+    ...(droppingFieldsBoundBy?.hasLastName
+      ? {}
+      : { lastName: userDetails.lastName }),
+    ...(droppingFieldsBoundBy?.hasEmail || userDetails.email === undefined
+      ? {}
+      : { email: userDetails.email }),
+    ...(droppingFieldsBoundBy?.hasPhoneNumber ||
+    userDetails.phoneNumber === undefined
+      ? {}
+      : { phoneNumber: userDetails.phoneNumber }),
+  };
+}
+
+/**
+ * True when `userDetailsPayloadToWire` would produce an empty object — the
+ * caller omits the part instead of sending `{}`. Blank contacts count as
+ * empty, mirroring the wire encoding that trims and drops them.
+ */
+export function isUserDetailsPayloadEmpty(
+  payload: UserDetailsPayload,
+): boolean {
+  return Object.keys(userDetailsPayloadToWire(payload)).length === 0;
+}
+
+/**
+ * Wire shape: snake_case keys. Names are emitted as supplied when non-blank;
+ * contact fields are trimmed and omitted when blank.
+ */
+export function userDetailsPayloadToWire(
+  payload: UserDetailsPayload,
+): Record<string, string> {
+  const wire: Record<string, string> = {};
+  if (payload.givenNames !== undefined && payload.givenNames.trim() !== "") {
+    wire["given_names"] = payload.givenNames;
+  }
+  if (payload.lastName !== undefined && payload.lastName.trim() !== "") {
+    wire["last_name"] = payload.lastName;
+  }
+  const trimmedEmail = payload.email?.trim();
+  if (trimmedEmail) {
+    wire["email"] = trimmedEmail;
+  }
+  const trimmedPhone = payload.phoneNumber?.trim();
+  if (trimmedPhone) {
+    wire["phone_number"] = trimmedPhone;
+  }
+  return wire;
+}