phase-2: identity, from the landing hook to the profile screen

Flows A1 to A6 and E3 end to end. A visitor types a RUC on the landing page,
sees their real filing dates, registers, verifies a six digit code, grants
consent, completes a three step setup and lands on the first run screen, with
the profile, consent and audit rows to show for it.

API: public RUC lookup behind a token bucket (10/min/IP), the full /me surface
(profile, dependents, consents, notification prefs, data export, account
deletion), an append-only audit module that exports an insert and nothing else,
and a PII module that is the only thing allowed near those tables.

Deletion and consent revocation both freeze the account and drop every session,
reusing better-auth's ban flag rather than adding a second notion of disabled.
Nothing is destroyed yet: the purge is a job for phase 4. deadlineDigit is
always derived server side, never accepted from the client.

Web: landing with the RUC hook, registration, OTP verification, consent, the
setup wizard, the profile screen with "Tus datos", and legal pages that ship as
marked placeholders per COPY.md section 13. Money, Skeleton, Switch and
EmptyState components added.

The seed is now complete for identity: Maria at 4123456-1, filing digit 6 and
day 19, with a dependant, consents and prefs; Carlos as an IVA-only company.

Two real defects found by building the screens and fixed with tests:
the OTP boxes dropped a digit because the handler fired effects inside a
setState updater that React 19 invokes twice, and the switch knob rendered
outside its track because translate-x-5.5 does not resolve.

232 vitest tests, 26 Playwright tests across mobile and desktop, coverage still
100% on the rules, typecheck and lint clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

packages/contracts/src/client.ts

@@ -1,5 +1,17 @@
 import type { z } from 'zod';
-import { ProfileDto } from './dto';
+import {
+  type ConsentInput,
+  DataExportDto,
+  type DeleteAccountInput,
+  DependentDto,
+  type DependentInput,
+  LookupDto,
+  NotificationPrefsDto,
+  type NotificationPrefsInput,
+  OkDto,
+  ProfileDto,
+  type ProfileInput,
+} from './dto';
 import { ApiError, ErrorEnvelope } from './errors';
 
 export interface ApiClientOptions {
@@ -60,8 +72,48 @@ export function createApiClient(options: ApiClientOptions = {}) {
 
   return {
     request,
+
+    // Public
+    lookupRuc: (numberOrRuc: string, signal?: AbortSignal) =>
+      request('GET', `/lookup/ruc/${encodeURIComponent(numberOrRuc)}`, {
+        schema: LookupDto,
+        ...(signal ? { signal } : {}),
+      }),
+
+    // Profile
     getProfile: (signal?: AbortSignal) =>
       request('GET', '/me/profile', { schema: ProfileDto, ...(signal ? { signal } : {}) }),
+    putProfile: (body: ProfileInput) => request('PUT', '/me/profile', { schema: ProfileDto, body }),
+
+    // Dependents
+    listDependents: (signal?: AbortSignal) =>
+      request('GET', '/me/dependents', {
+        schema: DependentDto.array(),
+        ...(signal ? { signal } : {}),
+      }),
+    createDependent: (body: DependentInput) =>
+      request('POST', '/me/dependents', { schema: DependentDto, body }),
+    deleteDependent: (id: string) =>
+      request('DELETE', `/me/dependents/${encodeURIComponent(id)}`, { schema: OkDto }),
+
+    // Consent and account
+    postConsent: (body: ConsentInput) => request('POST', '/me/consents', { schema: OkDto, body }),
+    getDataExport: (signal?: AbortSignal) =>
+      request('GET', '/me/data-export', {
+        schema: DataExportDto,
+        ...(signal ? { signal } : {}),
+      }),
+    deleteAccount: (body: DeleteAccountInput) =>
+      request('DELETE', '/me/account', { schema: OkDto, body }),
+
+    // Notifications
+    getNotificationPrefs: (signal?: AbortSignal) =>
+      request('GET', '/me/notification-prefs', {
+        schema: NotificationPrefsDto,
+        ...(signal ? { signal } : {}),
+      }),
+    patchNotificationPrefs: (body: NotificationPrefsInput) =>
+      request('PATCH', '/me/notification-prefs', { schema: NotificationPrefsDto, body }),
   };
 }
 

packages/contracts/src/dto.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { DocType, LocaleCode, ObligationCode, TaxpayerKind } from './enums';
+import { DocType, IrpCategory, LocaleCode, ObligationCode, TaxpayerKind } from './enums';
 
 /**
  * DTO schemas are added as their phase lands. Field names come from CONTRACTS.md
@@ -28,6 +28,90 @@ export const ProfileDto = z.object({
 });
 export type ProfileDto = z.infer<typeof ProfileDto>;
 
+/** `PUT /me/profile` body: the profile minus deadlineDigit, which is derived. */
+export const ProfileInput = ProfileDto.omit({ deadlineDigit: true }).extend({
+  fullName: z.string().trim().min(1).max(200),
+  irpGrossEstimate: z.number().int().min(0).max(1_000_000_000_000).nullable(),
+  autoConfirmDays: z.number().int().min(0).max(90),
+});
+export type ProfileInput = z.infer<typeof ProfileInput>;
+
+export const Relationship = z.enum(['conyuge', 'hijo', 'padre', 'otro']);
+export type Relationship = z.infer<typeof Relationship>;
+
+export const DependentDto = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  relationship: Relationship,
+  active: z.boolean(),
+});
+export type DependentDto = z.infer<typeof DependentDto>;
+
+export const DependentInput = z.object({
+  displayName: z.string().trim().min(1).max(120),
+  relationship: Relationship,
+  docNumber: z.string().trim().max(20).nullable().optional(),
+});
+export type DependentInput = z.infer<typeof DependentInput>;
+
+export const ConsentKind = z.enum(['data_processing', 'notifications']);
+export type ConsentKind = z.infer<typeof ConsentKind>;
+
+export const ConsentDto = z.object({
+  kind: ConsentKind,
+  granted: z.boolean(),
+  grantedAt: z.string(),
+  revokedAt: z.string().nullable(),
+  textVersion: z.string(),
+});
+export type ConsentDto = z.infer<typeof ConsentDto>;
+
+export const ConsentInput = z.object({ kind: ConsentKind, granted: z.boolean() });
+export type ConsentInput = z.infer<typeof ConsentInput>;
+
+export const NotificationPrefsDto = z.object({
+  pushEnabled: z.boolean(),
+  emailEnabled: z.boolean(),
+  telegramChatId: z.string().nullable(),
+  digestHour: z.number().int().min(0).max(23),
+});
+export type NotificationPrefsDto = z.infer<typeof NotificationPrefsDto>;
+
+export const NotificationPrefsInput = NotificationPrefsDto.partial();
+export type NotificationPrefsInput = z.infer<typeof NotificationPrefsInput>;
+
+/**
+ * `GET /lookup/ruc/:number`. An unparseable number is a 200 with `valid: false`, not an
+ * error: the landing shows it inline and never dead ends (CONTRACTS.md section 3).
+ */
+export const LookupDto = z.object({
+  valid: z.boolean(),
+  docType: DocType,
+  base: z.string(),
+  dv: z.number().int().nullable(),
+  deadlineDigit: z.number().int().min(0).max(9),
+  deadlineDay: z.number().int().min(1).max(31),
+  nextDeadlines: z.array(z.string()).length(3),
+});
+export type LookupDto = z.infer<typeof LookupDto>;
+
+/** Everything the platform holds about one user, as a downloadable file. */
+export const DataExportDto = z.object({
+  exportedAt: z.string(),
+  account: z.object({ email: z.string(), createdAt: z.string() }),
+  profile: ProfileDto.nullable(),
+  dependents: z.array(DependentDto),
+  consents: z.array(ConsentDto),
+  notificationPrefs: NotificationPrefsDto.nullable(),
+  documents: z.array(z.record(z.string(), z.unknown())),
+  classifications: z.array(z.record(z.string(), z.unknown())),
+  declarations: z.array(z.record(z.string(), z.unknown())),
+});
+export type DataExportDto = z.infer<typeof DataExportDto>;
+
+export const DeleteAccountInput = z.object({ confirmText: z.string() });
+export type DeleteAccountInput = z.infer<typeof DeleteAccountInput>;
+
 export const OkDto = z.object({ ok: z.literal(true) });
 export type OkDto = z.infer<typeof OkDto>;
 
@@ -39,3 +123,6 @@ export const ReadyDto = z.object({
   checks: z.record(z.string(), z.enum(['ok', 'error', 'pending'])),
 });
 export type ReadyDto = z.infer<typeof ReadyDto>;
+
+/** Re-exported so callers get the category vocabulary from one place. */
+export { IrpCategory };

packages/contracts/src/index.ts

@@ -17,6 +17,24 @@ export {
 
 export { ERROR_CODES, ErrorCode, ErrorEnvelope, ApiError, isApiError } from './errors';
 
-export { Obligation, ProfileDto, OkDto, HealthDto, ReadyDto } from './dto';
+export {
+  Obligation,
+  ProfileDto,
+  ProfileInput,
+  Relationship,
+  DependentDto,
+  DependentInput,
+  ConsentKind,
+  ConsentDto,
+  ConsentInput,
+  NotificationPrefsDto,
+  NotificationPrefsInput,
+  LookupDto,
+  DataExportDto,
+  DeleteAccountInput,
+  OkDto,
+  HealthDto,
+  ReadyDto,
+} from './dto';
 
 export { createApiClient, type ApiClient, type ApiClientOptions } from './client';