@smileid/usesmileid 12.0.1 → 12.0.2

package/src/core/exception/__tests__/builder_validation_exceptions.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import { DuplicateScreenTypeException } from "../duplicate_screen_type_exception";
+import { InvalidMissingCaptureTypeException } from "../invalid_missing_capture_type_exception";
 import { InvalidSelfieCaptureConfigException } from "../invalid_selfie_capture_config_exception";
 import { LivenessFrameCountException } from "../liveness_frame_count_exception";
 import { UseSmileIDErrorCode } from "../use_smile_id_error_code";
@@ -65,3 +66,16 @@ describe("InvalidSelfieCaptureConfigException", () => {
     });
   });
 });
+
+describe("InvalidMissingCaptureTypeException", () => {
+  it("carries the missing-capture-type code and an actionable fix", () => {
+    const exception = new InvalidMissingCaptureTypeException();
+
+    expect(exception).toBeInstanceOf(Error);
+    expect(exception.errorCode).toBe(
+      UseSmileIDErrorCode.Builder.MissingCaptureType,
+    );
+    expect(exception.message).toContain("captureType is missing");
+    expect(exception.suggestedFix).toContain("selfie or document");
+  });
+});

package/src/core/exception/flow_exceptions.test.ts

@@ -36,4 +36,14 @@ describe("ProcessingCancelledException", () => {
     expect(error).toBeInstanceOf(UseSmileIDException);
     expect(error).toBeInstanceOf(Error);
   });
+
+  it("carries an underlying cause when one is supplied", () => {
+    const underlying = new Error("upload aborted");
+    const error = new ProcessingCancelledException({ cause: underlying });
+    expect(error.cause).toBe(underlying);
+  });
+
+  it("leaves cause unset when none is supplied", () => {
+    expect(new ProcessingCancelledException().cause).toBeUndefined();
+  });
 });

package/src/core/exception/flow_exceptions.ts

@@ -27,16 +27,17 @@ export class ConsentDeniedException extends UseSmileIDGeneralException {
  *
  * Surfaced through `onResult.failure` so partners can distinguish a
  * user-initiated cancellation from a submission error, mirroring the
- * native SDKs' `ProcessingCancelledException`.
+ * native SDKs' `ProcessingCancelledException`. An optional `cause` carries a submission failure that preceded the exit.
  */
 export class ProcessingCancelledException extends UseSmileIDGeneralException {
   readonly errorCode = UseSmileIDErrorCode.General.OperationFailed;
 
-  constructor() {
+  constructor(args: { cause?: unknown } = {}) {
     super({
       message: "Processing was cancelled",
       suggestedFix:
         "The user exited the processing screen before submission completed.",
+      ...(args.cause !== undefined ? { cause: args.cause } : {}),
     });
   }
 }

package/src/core/exception/missing_job_type_exception.ts

@@ -2,9 +2,7 @@ import { UseSmileIDBuilderException } from "./use_smile_id_builder_exception";
 import { UseSmileIDErrorCode } from "./use_smile_id_error_code";
 
 /**
- * The `network { config { } }` block is present but `jobType` was
- * never set — the orchestrator can't pick a submission path without
- * it.
+ * `jobType` was never set, or was set to a value that is not one of the SDK's job types.
  */
 export class MissingJobTypeException extends UseSmileIDBuilderException {
   readonly errorCode = UseSmileIDErrorCode.Builder.MissingJobType;
@@ -12,7 +10,7 @@ export class MissingJobTypeException extends UseSmileIDBuilderException {
   constructor() {
     super({
       message:
-        "jobType is not set — it must be configured explicitly in the network { config { } } block",
+        "jobType is not set to one of the SDK's job types — it must be configured explicitly in the network { config { } } block",
       suggestedFix:
         "Set config.jobType in the network { config { } } block, e.g. config.jobType = JobType.DocumentVerification",
     });

package/src/data/api/__tests__/smile_id_api.test.ts

@@ -39,6 +39,7 @@ import type {
   ConsentInformation,
   UserDetails,
 } from "../../../core/models/params";
+import type { TokenPayload } from "../../model/token_payload";
 import { UseSmileIDMetadata } from "../../../metadata/use_smile_id_metadata";
 
 type RecordedCall = {
@@ -109,7 +110,7 @@ const consent: ConsentInformation = Object.freeze({
 // builds this and it travels on every `JobRequest`; the API
 // serializes `request.metadata` as the `metadata` multipart part.
 const metadata = new UseSmileIDMetadata({
-  sdkVersion: "12.0.1",
+  sdkVersion: "12.0.2",
   sdk: "react-native-expo",
   deviceOs: "",
   deviceModel: "",
@@ -1071,6 +1072,279 @@ describe("SmileIDAPI response-body parse failures", () => {
   });
 });
 
+describe("SmileIDAPI — token-provided user details & consent (wire)", () => {
+  const livenessImages: readonly string[] = [
+    "file:///l1.jpg",
+    "file:///l2.jpg",
+    "file:///l3.jpg",
+    "file:///l4.jpg",
+    "file:///l5.jpg",
+    "file:///l6.jpg",
+    "file:///l7.jpg",
+  ];
+
+  const fullUserDetails: UserDetails = {
+    givenNames: "John",
+    lastName: "Doe",
+    email: "john@example.test",
+    phoneNumber: "+254700000000",
+  };
+
+  function tokenPayload(overrides: Partial<TokenPayload> = {}): TokenPayload {
+    return {
+      hasGivenNames: false,
+      hasLastName: false,
+      hasEmail: false,
+      hasPhoneNumber: false,
+      ...overrides,
+    };
+  }
+
+  const fullBinding = tokenPayload({
+    hasGivenNames: true,
+    hasLastName: true,
+    hasEmail: true,
+    hasPhoneNumber: true,
+  });
+
+  const completeTokenConsent = {
+    granted: true,
+    grantedAt: "2026-01-01T09:00:00.000Z",
+    noticeLanguage: "EN",
+    noticePrivacyPolicyUrl: "https://partner.test/privacy",
+  } as const;
+
+  function enrollmentRequest(
+    overrides: Partial<SmartSelfieEnrollmentRequest> = {},
+  ): SmartSelfieEnrollmentRequest {
+    return {
+      jobType: JobType.smartSelfieEnrollment,
+      selfieImage: "file:///selfie.jpg",
+      livenessImages,
+      consent,
+      metadata,
+      expectedLivenessImageCount: 7,
+      userDetails: fullUserDetails,
+      enhanced: false,
+      ...overrides,
+    };
+  }
+
+  it("a partial user_details payload sends only its remaining fields", async () => {
+    // Assembly already dropped the token-bound names (token always wins);
+    // only email/phone ride the wire.
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(
+      enrollmentRequest({
+        userDetails: {
+          email: "john@example.test",
+          phoneNumber: "+254700000000",
+        },
+      }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    const parsed = JSON.parse(await readJsonPart(parts["user_details"]![0]));
+    expect(parsed).toEqual({
+      email: "john@example.test",
+      phone_number: "+254700000000",
+    });
+  });
+
+  it("omits the user_details part when the request carries no userDetails", async () => {
+    const { api, calls } = makeApi();
+    const { userDetails: _details, ...withoutUserDetails } =
+      enrollmentRequest();
+    await api.smartSelfieEnrollment({
+      ...withoutUserDetails,
+      tokenPayload: fullBinding,
+    });
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_details"]).toBeUndefined();
+  });
+
+  it("an empty user_details payload omits the part entirely", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(enrollmentRequest({ userDetails: {} }));
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["user_details"]).toBeUndefined();
+  });
+
+  it("omits the consent part when the request carries no consent (token-complete path)", async () => {
+    const { api, calls } = makeApi();
+    const { consent: _consent, ...withoutConsent } = enrollmentRequest();
+    await api.smartSelfieEnrollment({
+      ...withoutConsent,
+      tokenPayload: {
+        ...tokenPayload(),
+        consent: completeTokenConsent,
+      },
+    });
+    const parts = partsByName(calls[0]!.body);
+    expect(parts["consent"]).toBeUndefined();
+    // The metadata part is unconditional — it must survive the omission.
+    expect(parts["metadata"]).toBeDefined();
+  });
+
+  it("sends a local consent in full even when the token also binds consent", async () => {
+    // Server merges per-subfield with the token winning; the SDK never
+    // trims a locally captured / preset consent.
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(
+      enrollmentRequest({
+        tokenPayload: {
+          ...tokenPayload(),
+          consent: completeTokenConsent,
+        },
+      }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    const parsed = JSON.parse(await readJsonPart(parts["consent"]![0]));
+    expect(parsed).toEqual({
+      granted: true,
+      granted_at: "2026-04-30T00:00:00.000Z",
+      notice_language: "EN",
+      notice_privacy_policy_url: "https://example.test/p",
+    });
+  });
+
+  it("regression: without a tokenPayload the parts are identical to today", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(enrollmentRequest());
+    const parts = partsByName(calls[0]!.body);
+    const userDetailsParsed = JSON.parse(
+      await readJsonPart(parts["user_details"]![0]),
+    );
+    expect(userDetailsParsed).toEqual({
+      given_names: "John",
+      last_name: "Doe",
+      email: "john@example.test",
+      phone_number: "+254700000000",
+    });
+    const consentParsed = JSON.parse(await readJsonPart(parts["consent"]![0]));
+    expect(consentParsed).toEqual({
+      granted: true,
+      granted_at: "2026-04-30T00:00:00.000Z",
+      notice_language: "EN",
+      notice_privacy_policy_url: "https://example.test/p",
+    });
+  });
+
+  it("keeps the stripped user_details part an untagged text form field", async () => {
+    const { api, calls } = makeApi();
+    await api.smartSelfieEnrollment(
+      enrollmentRequest({
+        tokenPayload: tokenPayload({ hasGivenNames: true }),
+      }),
+    );
+    const parts = partsByName(calls[0]!.body);
+    expectNoJsonContentType(parts["user_details"]![0]);
+  });
+
+  // Every endpoint routes user_details / consent through the same
+  // helpers — pin the omission behavior across all six.
+  const omissionSubmissions: ReadonlyArray<{
+    readonly endpoint: string;
+    readonly submit: (api: SmileIDAPI) => Promise<unknown>;
+  }> = [
+    {
+      endpoint: "/v3/registration",
+      submit: (api) =>
+        api.smartSelfieEnrollment({
+          jobType: JobType.smartSelfieEnrollment,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          enhanced: false,
+          metadata,
+          expectedLivenessImageCount: 7,
+          tokenPayload: { ...fullBinding, consent: completeTokenConsent },
+        }),
+    },
+    {
+      endpoint: "/v3/authentication",
+      submit: (api) =>
+        api.smartSelfieAuthentication({
+          jobType: JobType.smartSelfieAuthentication,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          userId: "user-1",
+          enhanced: false,
+          metadata,
+          expectedLivenessImageCount: 7,
+          tokenPayload: { ...fullBinding, consent: completeTokenConsent },
+        }),
+    },
+    {
+      endpoint: "/v3/enhanced_kyc",
+      submit: (api) =>
+        api.enhancedKyc({
+          jobType: JobType.enhancedKyc,
+          params: { idType: "NATIONAL_ID", idNumber: "1", country: "KE" },
+          metadata,
+          tokenPayload: { ...fullBinding, consent: completeTokenConsent },
+        }),
+    },
+    {
+      endpoint: "/v3/biometric_kyc",
+      submit: (api) =>
+        api.biometricKyc({
+          jobType: JobType.biometricKyc,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          params: {
+            idType: "NATIONAL_ID",
+            idNumber: "1",
+            country: "KE",
+            useEnrolledImage: false,
+          },
+          metadata,
+          expectedLivenessImageCount: 7,
+          tokenPayload: { ...fullBinding, consent: completeTokenConsent },
+        }),
+    },
+    {
+      endpoint: "/v3/document_verification",
+      submit: (api) =>
+        api.documentVerification({
+          jobType: JobType.documentVerification,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          frontDocument: "file:///front.jpg",
+          country: "KE",
+          metadata,
+          expectedLivenessImageCount: 7,
+          tokenPayload: { ...fullBinding, consent: completeTokenConsent },
+        }),
+    },
+    {
+      endpoint: "/v3/enhanced_document_verification",
+      submit: (api) =>
+        api.enhancedDocumentVerification({
+          jobType: JobType.enhancedDocumentVerification,
+          selfieImage: "file:///selfie.jpg",
+          livenessImages,
+          frontDocument: "file:///front.jpg",
+          country: "KE",
+          idType: "NATIONAL_ID",
+          metadata,
+          expectedLivenessImageCount: 7,
+          tokenPayload: { ...fullBinding, consent: completeTokenConsent },
+        }),
+    },
+  ];
+
+  for (const { endpoint, submit } of omissionSubmissions) {
+    it(`${endpoint} omits user_details and consent on the token-complete path`, async () => {
+      const { api, calls } = makeApi();
+      await submit(api);
+      expect(calls[0]!.url).toBe(endpoint);
+      const parts = partsByName(calls[0]!.body);
+      expect(parts["user_details"]).toBeUndefined();
+      expect(parts["consent"]).toBeUndefined();
+      expect(parts["metadata"]).toBeDefined();
+    });
+  }
+});
+
 describe("SmileIDAPI signed job opt-in (request MAC + attestation)", () => {
   // An endpoint missing the opt-in flags ships an unsigned job the
   // server rejects — while the interceptors' own tests stay green.

package/src/data/api/interceptors/__tests__/credential_header_redaction.test.ts

@@ -0,0 +1,144 @@
+import axios, { AxiosHeaders, type InternalAxiosRequestConfig } from "axios";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+import { LogLevel } from "../../../../core/models/network_config";
+import { LoggingConfigBuilder } from "../../../dsl/builder/config_builder";
+import { InterceptorConfigBuilder } from "../../../dsl/builder/interceptor_config_builder";
+import { attachLoggingInterceptor } from "../logging_interceptor";
+
+const CANONICAL_CREDENTIAL_HEADERS: ReadonlyArray<
+  readonly [name: string, value: string]
+> = [
+  ["SmileID-Token", "secret-jwt-value"],
+  ["smileid-partner-id", "secret-partner-002"],
+  ["SmileID-Api-Key", "secret-api-key"],
+  ["smileid-device-nonce", "secret-nonce"],
+  ["Authorization", "Bearer secret-bearer"],
+  ["Cookie", "session=secret-cookie"],
+  ["Set-Cookie", "session=secret-set-cookie"],
+];
+
+function requestHeaders(): AxiosHeaders {
+  const headers = new AxiosHeaders();
+  for (const [name, value] of CANONICAL_CREDENTIAL_HEADERS) {
+    headers.set(name, value);
+  }
+  headers.set("Content-Type", "multipart/form-data");
+  return headers;
+}
+
+function invokeRequestFulfilled(
+  client: ReturnType<typeof axios.create>,
+): InternalAxiosRequestConfig {
+  const handlers = (
+    client.interceptors.request as unknown as {
+      handlers: {
+        fulfilled?: (
+          config: InternalAxiosRequestConfig,
+        ) => InternalAxiosRequestConfig;
+      }[];
+    }
+  ).handlers;
+  const lastHandler = handlers[handlers.length - 1];
+  if (typeof lastHandler?.fulfilled !== "function") {
+    throw new Error("No fulfilled request handler found");
+  }
+  return lastHandler.fulfilled({
+    method: "post",
+    baseURL: "https://testapi.smileidentity.com",
+    url: "/v2/submit-job",
+    headers: requestHeaders(),
+  } as InternalAxiosRequestConfig);
+}
+
+describe("credential headers under the partner-facing logging config", () => {
+  let client: ReturnType<typeof axios.create>;
+  let consoleLogSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    client = axios.create();
+    consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+  });
+
+  function printedOutput(): string {
+    return consoleLogSpy.mock.calls
+      .map((call) => call.map((arg) => JSON.stringify(arg)).join(" "))
+      .join("\n");
+  }
+
+  const configurations: ReadonlyArray<
+    readonly [label: string, attach: (client_: typeof client) => void]
+  > = [
+    [
+      "network { config { logging { } } } at default redactHeaders",
+      (client_) => {
+        const builder = new LoggingConfigBuilder();
+        builder.level = LogLevel.headers;
+        attachLoggingInterceptor(client_, builder.build());
+      },
+    ],
+    [
+      "network { interceptors { logging() } } at default redactHeaders",
+      (client_) => {
+        const interceptors = new InterceptorConfigBuilder();
+        interceptors
+          .logging((l) => {
+            l.level = LogLevel.headers;
+          })
+          .attach(client_);
+      },
+    ],
+  ];
+
+  for (const [label, attach] of configurations) {
+    it(`masks every credential header — ${label}`, () => {
+      attach(client);
+      invokeRequestFulfilled(client);
+
+      const output = printedOutput();
+      expect(output).not.toBe("");
+      for (const [name, value] of CANONICAL_CREDENTIAL_HEADERS) {
+        expect(output, `${name} leaked its value`).not.toContain(value);
+      }
+      expect(output).toContain("multipart/form-data");
+    });
+
+    it(`keeps the header names visible so the audit trail survives — ${label}`, () => {
+      attach(client);
+      invokeRequestFulfilled(client);
+
+      const output = printedOutput().toLowerCase();
+      for (const [name] of CANONICAL_CREDENTIAL_HEADERS) {
+        expect(output, `${name} was dropped entirely`).toContain(
+          name.toLowerCase(),
+        );
+      }
+    });
+  }
+
+  it("does not print headers at the default verbosity", () => {
+    const builder = new LoggingConfigBuilder();
+    attachLoggingInterceptor(client, builder.build());
+    invokeRequestFulfilled(client);
+
+    expect(printedOutput()).not.toContain("headers");
+  });
+
+  it("unions the partner's list with the always-redact set rather than replacing it", () => {
+    const builder = new LoggingConfigBuilder();
+    builder.level = LogLevel.headers;
+    builder.redactHeaders = ["content-type"];
+    attachLoggingInterceptor(client, builder.build());
+    invokeRequestFulfilled(client);
+
+    const output = printedOutput();
+    expect(output).not.toContain("multipart/form-data");
+    for (const [, value] of CANONICAL_CREDENTIAL_HEADERS) {
+      expect(output).not.toContain(value);
+    }
+  });
+});

package/src/data/api/interceptors/smile_auth_interceptor.ts

@@ -26,7 +26,7 @@ import type { TokenHolder } from "../auth/token_holder";
  * by the next outgoing request.
  */
 
-const SDK_VERSION = "12.0.1";
+const SDK_VERSION = "12.0.2"; // x-release-please-version
 
 export type SmileAuthInterceptorOptions = {
   readonly partnerConfig: PartnerConfig;

package/src/data/api/smile_id_api.ts

@@ -4,7 +4,9 @@ import type {
   PartnerConfig,
 } from "../../core/models/network_config";
 import { SmileIDUrls } from "../smile_id_urls";
-import type { ConsentInformation, UserDetails } from "../../core/models/params";
+import type { ConsentInformation } from "../../core/models/params";
+import { userDetailsPayloadToWire } from "../model/user_details_payload";
+import type { UserDetailsPayload } from "../model/user_details_payload";
 import type {
   BiometricKycRequest,
   DocumentVerificationRequest,
@@ -87,11 +89,7 @@ export class SmileIDAPI {
     request: SmartSelfieEnrollmentRequest,
   ): Promise<JobSubmissionResponse> {
     const formData = this._buildSelfieFormData(request);
-    appendJsonPart(
-      formData,
-      "user_details",
-      userDetailsToWire(request.userDetails),
-    );
+    appendUserDetailsPart(formData, request);
     this._appendPartnerConfigParts(formData);
     this._appendConsentAndMetadata(formData, request.consent, request.metadata);
     return this._postMultipart("/v3/registration", formData);
@@ -108,11 +106,7 @@ export class SmileIDAPI {
   ): Promise<JobSubmissionResponse> {
     const formData = this._buildSelfieFormData(request);
     appendStringPart(formData, "user_id", request.userId);
-    appendJsonPart(
-      formData,
-      "user_details",
-      userDetailsToWire(request.userDetails),
-    );
+    appendUserDetailsPart(formData, request);
     this._appendPartnerConfigParts(formData);
     this._appendConsentAndMetadata(formData, request.consent, request.metadata);
     return this._postMultipart("/v3/authentication", formData);
@@ -126,11 +120,7 @@ export class SmileIDAPI {
     // multipart/form-data`.
     const formData = new FormData();
     this._appendIdFields(formData, request.params);
-    appendJsonPart(
-      formData,
-      "user_details",
-      userDetailsToWire(request.userDetails),
-    );
+    appendUserDetailsPart(formData, request);
     if (request.params.bankCode) {
       appendStringPart(formData, "bank_code", request.params.bankCode);
     }
@@ -149,11 +139,7 @@ export class SmileIDAPI {
     const useEnrolled = request.params.useEnrolledImage;
     const formData = this._buildSelfieFormData(request);
     this._appendIdFields(formData, request.params);
-    appendJsonPart(
-      formData,
-      "user_details",
-      userDetailsToWire(request.userDetails),
-    );
+    appendUserDetailsPart(formData, request);
     if (useEnrolled) {
       appendStringPart(formData, "use_enrolled_image", "true");
     }
@@ -194,11 +180,7 @@ export class SmileIDAPI {
     if (request.idType) {
       appendStringPart(formData, "id_type", request.idType);
     }
-    appendJsonPart(
-      formData,
-      "user_details",
-      userDetailsToWire(request.userDetails),
-    );
+    appendUserDetailsPart(formData, request);
     this._appendPartnerConfigParts(formData);
     this._appendConsentAndMetadata(formData, request.consent, request.metadata);
     return this._postMultipart(url, formData);
@@ -306,6 +288,10 @@ export class SmileIDAPI {
    * the part with `Content-Type: application/json` causes the parser
    * to reject the part as "missing or invalid".
    *
+   * `consent` is `undefined` only when the token binds complete
+   * consent and no local source exists — the part is then omitted
+   * entirely and the server injects the token's consent.
+   *
    * The `metadata` snapshot is built by the request-construction site
    * (the flow navigation manager) and travels on the request — this
    * method serializes the snapshot it is handed rather than generating
@@ -313,19 +299,21 @@ export class SmileIDAPI {
    */
   private _appendConsentAndMetadata(
     formData: FormData,
-    consent: ConsentInformation,
+    consent: ConsentInformation | undefined,
     metadata: UseSmileIDMetadata,
   ): void {
     // Transform the JS camelCase shape into the canonical snake_case
     // wire JSON before serialization. The server validates the wire
     // shape exactly — `consent.granted` (snake_case via `granted`
     // already) and `consent.granted_at` are required.
-    appendJsonPart(formData, "consent", {
-      granted: consent.granted,
-      granted_at: consent.grantedAt,
-      notice_language: consent.noticeLanguage,
-      notice_privacy_policy_url: consent.noticePrivacyPolicyUrl,
-    });
+    if (consent !== undefined) {
+      appendJsonPart(formData, "consent", {
+        granted: consent.granted,
+        granted_at: consent.grantedAt,
+        notice_language: consent.noticeLanguage,
+        notice_privacy_policy_url: consent.noticePrivacyPolicyUrl,
+      });
+    }
     appendJsonPart(formData, "metadata", metadata.toEntries());
   }
 
@@ -386,23 +374,22 @@ function mapJobSubmissionResponse(data: unknown): JobSubmissionResponse {
 }
 
 /**
- * Convert `UserDetails` to the snake_case wire shape. Optional fields
- * are trimmed; blank values are omitted.
+ * Append the `user_details` JSON multipart part. The payload arrives
+ * pre-reduced from assembly (token-bound fields already dropped); the
+ * part is omitted entirely when nothing remains — or when `userDetails`
+ * was legitimately omitted because the token binds every required field.
  */
-function userDetailsToWire(details: UserDetails): Record<string, string> {
-  const wire: Record<string, string> = {
-    given_names: details.givenNames,
-    last_name: details.lastName,
-  };
-  const trimmedEmail = details.email?.trim();
-  if (trimmedEmail) {
-    wire["email"] = trimmedEmail;
-  }
-  const trimmedPhone = details.phoneNumber?.trim();
-  if (trimmedPhone) {
-    wire["phone_number"] = trimmedPhone;
-  }
-  return wire;
+function appendUserDetailsPart(
+  formData: FormData,
+  request: {
+    readonly userDetails?: UserDetailsPayload;
+  },
+): void {
+  const details = request.userDetails;
+  if (details === undefined) return;
+  const wire = userDetailsPayloadToWire(details);
+  if (Object.keys(wire).length === 0) return;
+  appendJsonPart(formData, "user_details", wire);
 }
 
 /**