@trymellon/js 2.2.1 → 2.3.1

package/dist/{trymellon-P7BPxIry.d.ts → trymellon-CO_2wLZz.d.ts}

@@ -1,4 +1,4 @@
-type TryMellonErrorCode = 'NOT_SUPPORTED' | 'USER_CANCELLED' | 'PASSKEY_NOT_FOUND' | 'SESSION_EXPIRED' | 'NETWORK_FAILURE' | 'INVALID_ARGUMENT' | 'TIMEOUT' | 'ABORTED' | 'ABORT_ERROR' | 'CHALLENGE_MISMATCH' | 'UNKNOWN_ERROR';
+type TryMellonErrorCode = 'NOT_SUPPORTED' | 'USER_CANCELLED' | 'PASSKEY_NOT_FOUND' | 'SESSION_EXPIRED' | 'NETWORK_FAILURE' | 'INVALID_ARGUMENT' | 'TIMEOUT' | 'ABORTED' | 'ABORT_ERROR' | 'CHALLENGE_MISMATCH' | 'TICKET_NOT_FOUND' | 'TICKET_EXPIRED' | 'TICKET_ALREADY_USED' | 'PIN_MISMATCH' | 'PIN_LOCKED' | 'BRIDGE_SESSION_EXPIRED' | 'UNKNOWN_ERROR';
 declare class TryMellonError extends Error {
     readonly code: TryMellonErrorCode;
     readonly details?: unknown;
@@ -26,11 +26,10 @@ interface TelemetrySender {
 type Branded<T, B> = T & {
     __brand: B;
 };
-type AppId = Branded<string, 'AppId'>;
 type ExternalUserId = Branded<string, 'ExternalUserId'>;
 type TryMellonConfig = {
     /** Application identifier (tenant). Required for API requests. */
-    appId: string | AppId;
+    appId: string;
     /** API key for authentication. Required for API requests. */
     publishableKey: string;
     apiBaseUrl?: string;
@@ -61,6 +60,14 @@ type TryMellonConfig = {
      * Set this in Node or when the document origin is not the correct one (e.g. SSR).
      */
     origin?: string;
+    /**
+     * Optional storage for context hash (e.g. sessionStorage). If not set, browser sessionStorage or in-memory fallback is used.
+     * Injected for testability and SSR; must implement getItem/setItem.
+     */
+    contextHashStorage?: {
+        getItem(key: string): string | null;
+        setItem(key: string, value: string): void;
+    };
 };
 interface RegisterOptions {
     /**
@@ -108,19 +115,19 @@ type SuccessEventUserInfo = {
 /** Success payload: token always present (03-eventos-seguridad). Nonce when flow generates it. */
 type SuccessEventPayload = {
     type: 'success';
-    operation: 'register' | 'authenticate';
+    operation: 'register' | 'authenticate' | 'enroll';
     token: string;
     user?: SuccessEventUserInfo;
     nonce?: string;
 };
 type EventPayload = {
     type: 'start';
-    operation: 'register' | 'authenticate';
+    operation: 'register' | 'authenticate' | 'enroll';
     nonce?: string;
 } | SuccessEventPayload | {
     type: 'error';
     error: TryMellonError;
-    operation?: 'register' | 'authenticate';
+    operation?: 'register' | 'authenticate' | 'enroll';
     nonce?: string;
 } | {
     type: 'cancelled';
@@ -143,6 +150,31 @@ type EmailFallbackVerifyResult = {
     /** Set when successUrl was passed and allowed by application allowlist */
     redirectUrl?: string;
 };
+type EnrollOptions = {
+    ticketId: string;
+    signal?: AbortSignal;
+};
+/** Result of finish enrollment; aligns with backend envelope (session_token). */
+type EnrollmentResult = {
+    sessionToken: string;
+};
+/** Backend response for POST /v1/enrollment/register/options. Validators use this shape. */
+type EnrollmentStartResponse = {
+    session_id: string;
+    challenge: RegisterStartResponse['challenge'];
+};
+/** Backend response for POST /v1/enrollment/register. Validators use this shape. */
+type EnrollmentFinishResponse = {
+    credential_id: string;
+    status: string;
+    session_token: string;
+    user: {
+        user_id: string;
+        external_user_id?: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    };
+};
 type RecoveryVerifyResponse = {
     challenge: Record<string, unknown>;
     recovery_session_id: string;
@@ -240,6 +272,62 @@ type CrossDeviceVerifyRegistrationRequest = {
     session_id: string;
     credential: RegisterFinishRequest['credential'];
 };
+/** Response from GET context/:sessionId (auth or registration). Aligns with backend unwrapped result. */
+type BridgeContextResponse = {
+    type: 'auth' | 'registration';
+    options: Record<string, unknown>;
+    application_name?: string;
+};
+/** Response from POST verify/:sessionId (challenge / options for WebAuthn). */
+type BridgeChallengeResponse = {
+    session_id: string;
+    challenge?: string;
+    registration_options?: Record<string, unknown>;
+    authentication_options?: Record<string, unknown>;
+};
+/** Backend result of POST complete (enrollment). Validators use this shape. */
+type BridgeCompleteEnrollmentResult = {
+    credential_id: string;
+    entity_id: string;
+    user_id: string;
+    session_token: string;
+};
+/** Backend result of POST complete (auth). */
+type BridgeCompleteAuthResult = {
+    session_token: string;
+};
+/** Options for bridge flows: PIN callback, optional preset PIN, abort signal. */
+type BridgeOptions = {
+    onPinRequired?: () => Promise<string>;
+    presencePin?: string;
+    signal?: AbortSignal;
+};
+/** Public result of bridge enrollment: sessionToken and optional credential/user/entity ids. */
+type BridgeEnrollmentResult = {
+    sessionToken: string;
+    credentialId?: string;
+    userId?: string;
+    entityId?: string;
+};
+/** Public result of bridge auth: sessionToken only. */
+type BridgeAuthResult = {
+    sessionToken: string;
+};
+/** Union: bridge completion returns enrollment or auth result. */
+type BridgeResult = BridgeEnrollmentResult | BridgeAuthResult;
+/** Status snapshot from GET .../status/:sessionId (polling or SSE event). Terminal: pin_verified | pin_locked | completed. */
+type BridgeStatusSnapshot = {
+    status: 'pending' | 'pin_verified' | 'pin_locked' | 'completed';
+    ts?: string;
+};
+/** Options for complete(): BridgeOptions plus kind and enrollment-only fields. */
+type BridgeCompleteOptions = BridgeOptions & {
+    kind: 'enrollment' | 'auth';
+    /** Required when completing enrollment bridge. */
+    ticketId?: string;
+    /** Required when completing enrollment bridge. */
+    entityId?: string;
+};
 type RegisterStartRequest = {
     external_user_id: string;
 };
@@ -387,10 +475,10 @@ interface AuthenticateResult {
 }
 type SessionValidateResponse = {
     valid: boolean;
-    user_id: string;
-    external_user_id: string;
-    tenant_id: string;
-    app_id: string;
+    userId: string;
+    externalUserId: string;
+    tenantId: string;
+    appId: string;
 };
 type OnboardingStartRequest = {
     user_role: 'maintainer' | 'app_user';
@@ -458,6 +546,8 @@ type OnboardingRegisterResponseWithChallenge = OnboardingRegisterResponse & {
     challenge?: RegisterStartResponse['challenge'];
 };
 
+/** Bridge kind: enrollment-bridge (registration flow) or auth-bridge (auth flow). */
+type BridgeKind = 'enrollment' | 'auth';
 declare class ApiClient {
     private readonly httpClient;
     private readonly baseUrl;
@@ -504,6 +594,49 @@ declare class ApiClient {
     verifyCrossDeviceRegistration(request: CrossDeviceVerifyRegistrationRequest): Promise<Result<void, TryMellonError>>;
     verifyAccountRecoveryOtp(externalUserId: string, otp: string): Promise<Result<RecoveryVerifyResponse, TryMellonError>>;
     completeAccountRecovery(recoverySessionId: string, credential: Record<string, unknown>): Promise<Result<RecoveryCompleteResponse, TryMellonError>>;
+    startEnrollment(ticketId: string, contextHash: string, headers?: Record<string, string>): Promise<Result<EnrollmentStartResponse, TryMellonError>>;
+    finishEnrollment(ticketId: string, body: {
+        credential: unknown;
+        context_hash: string;
+    }, headers?: Record<string, string>): Promise<Result<EnrollmentFinishResponse, TryMellonError>>;
+    private bridgePrefix;
+    getBridgeContext(sessionId: string, kind: BridgeKind, headers?: Record<string, string>): Promise<Result<BridgeContextResponse, TryMellonError>>;
+    verifyBridgePin(sessionId: string, pin: string, kind: BridgeKind, headers?: Record<string, string>): Promise<Result<BridgeChallengeResponse, TryMellonError>>;
+    completeBridgeEnrollment(body: {
+        session_id: string;
+        ticket_id: string;
+        entity_id: string;
+        context_hash: string;
+        registration_response: {
+            id: string;
+            rawId: string;
+            response: {
+                clientDataJSON: string;
+                attestationObject: string;
+            };
+            type: string;
+        };
+    }, headers?: Record<string, string>): Promise<Result<BridgeCompleteEnrollmentResult, TryMellonError>>;
+    completeBridgeAuth(body: {
+        session_id: string;
+        credential: {
+            id: string;
+            rawId: string;
+            response: {
+                authenticatorData: string;
+                clientDataJSON: string;
+                signature: string;
+                userHandle?: string;
+            };
+            type: string;
+        };
+    }, headers?: Record<string, string>): Promise<Result<BridgeCompleteAuthResult, TryMellonError>>;
+    /**
+     * Full URL for GET bridge status (polling or EventSource). Same path as getBridgeStatus.
+     * Used by BridgeManager for SSE when EventSource is available (browser only; Node has no EventSource).
+     */
+    getBridgeStatusUrl(sessionId: string, kind: BridgeKind): string;
+    getBridgeStatus(sessionId: string, kind: BridgeKind, headers?: Record<string, string>): Promise<Result<BridgeStatusSnapshot, TryMellonError>>;
 }
 
 declare class OnboardingManager {
@@ -531,20 +664,35 @@ declare class TryMellon {
     private authService;
     private recoveryService;
     onboarding: OnboardingManager;
-    /**
-     * Creates a new TryMellon instance.
-     * Validates config and returns a Result.
-     * @param config SDK configuration
-     */
+    private readonly enrollmentManager;
+    private readonly bridgeManager;
+    private readonly contextHashStorage;
+    private static validateConfig;
     static create(config: TryMellonConfig): Result<TryMellon, TryMellonError>;
     /**
      * @deprecated Use `TryMellon.create(config)` instead to handle validation errors safely.
      * This constructor will throw errors if configuration is invalid.
      */
     constructor(config: TryMellonConfig);
+    /**
+     * Bridge (KP-BRIDGE-04): complete enrollment or auth from a second device (e.g. mobile scanning desktop QR).
+     * Use kind 'enrollment' for enrollment-bridge sessions, 'auth' for auth-bridge sessions.
+     */
+    get bridge(): {
+        getContext(sessionId: string, kind: 'enrollment' | 'auth'): Promise<Result<BridgeContextResponse, TryMellonError>>;
+        verifyPin(sessionId: string, pin: string, kind: 'enrollment' | 'auth'): Promise<Result<BridgeChallengeResponse, TryMellonError>>;
+        complete(sessionId: string, options?: BridgeCompleteOptions): Promise<Result<BridgeResult, TryMellonError>>;
+        waitForResult(sessionId: string, options?: {
+            useSse?: boolean;
+            kind?: 'enrollment' | 'auth';
+            timeoutMs?: number;
+        }): Promise<Result<BridgeStatusSnapshot, TryMellonError>>;
+    };
     static isSupported(): boolean;
     register(options: RegisterOptions): Promise<Result<RegisterResult, TryMellonError>>;
     authenticate(options: AuthenticateOptions): Promise<Result<AuthenticateResult, TryMellonError>>;
+    enroll(options: EnrollOptions): Promise<Result<EnrollmentResult, TryMellonError>>;
+    getContextHash(): string;
     validateSession(sessionToken: string): Promise<Result<SessionValidateResponse, TryMellonError>>;
     getStatus(): Promise<ClientStatus>;
     on(event: TryMellonEvent, handler: EventHandler): () => void;
@@ -573,4 +721,4 @@ declare class TryMellon {
     };
 }
 
-export { type AuthenticateResult as A, type Result as R, TryMellon as T, type RegisterResult as a, TryMellonError as b, type RegisterOptions as c, type AuthenticateOptions as d, type TryMellonConfig as e };
+export { type AuthenticateResult as A, type EnrollmentResult as E, type Result as R, TryMellon as T, type RegisterResult as a, TryMellonError as b, type RegisterOptions as c, type AuthenticateOptions as d, type EnrollOptions as e };

package/dist/ui/index.d.ts

@@ -7,7 +7,7 @@ declare const INITIAL_UI_STATE: "IDLE";
 /** UI FSM types — presentation layer. No DOM/core deps (types only). Aligned to 01-arquitectura §4. */
 
 /** UI state machine states. */
-type UIState = 'IDLE' | 'EVALUATING_ENV' | 'READY' | 'READY_REGISTER' | 'READY_LOGIN' | 'AUTHENTICATING' | 'SUCCESS' | 'ERROR' | 'FALLBACK' | 'FALLBACK_EMAIL' | 'FALLBACK_QR';
+type UIState = 'IDLE' | 'EVALUATING_ENV' | 'READY' | 'READY_REGISTER' | 'READY_LOGIN' | 'AUTHENTICATING' | 'SUCCESS' | 'ERROR' | 'FALLBACK' | 'FALLBACK_EMAIL' | 'FALLBACK_QR' | 'ENROLLMENT_READY' | 'ENROLLING' | 'ENROLLMENT_SUCCESS' | 'ENROLLMENT_ERROR';
 /** Component mode (mode attribute). */
 type UIMode = 'login' | 'register' | 'auto';
 /** Client status in UI layer (port/adapter map from core). */
@@ -54,6 +54,19 @@ type FSMEvent = {
     type: 'AUTH_FALLBACK_EMAIL';
 } | {
     type: 'AUTH_FALLBACK_QR';
+} | {
+    type: 'ENROLLMENT_READY_SET';
+    payload?: {
+        ticketId?: string;
+    };
+} | {
+    type: 'START_ENROLL';
+} | {
+    type: 'ENROLL_SUCCESS';
+} | {
+    type: 'ENROLL_ERROR';
+} | {
+    type: 'ENROLL_RETRY';
 };
 
 /**
@@ -104,6 +117,8 @@ type ParsedAttributes = {
     buttonLabel?: string | null;
     /** Optional aria-label for the trigger button (default = TRIGGER_ARIA_LABEL). */
     buttonAriaLabel?: string | null;
+    /** When set, WC runs in enrollment mode: emits context-ready and exposes enroll(). */
+    ticketId?: string | null;
 };
 /** Modal display mode: overlay vs inline. */
 type ModalDisplayMode = 'modal' | 'inline';
@@ -158,13 +173,18 @@ type RenderOptions = {
     primaryButtonAriaLabel?: string;
 };
 
+type EnrollOptions = {
+    ticketId: string;
+    signal?: AbortSignal;
+};
+
 /**
  * Port: core event subscription and re-emission on host. Source of truth for modal WC event contract (names, detail types).
  * Contract only; implementation in adapters. No import from ../core.
  */
 
-/** Public auth operation for host (login | register). */
-type AuthOperation = TabKind;
+/** Public auth operation for host (login | register | enroll). */
+type AuthOperation = TabKind | 'enroll';
 /** Optional user info in mellon:success; minimal shape for host without coupling to core. */
 type MellonSuccessUserInfo = {
     userId: string;
@@ -216,10 +236,12 @@ interface CoreWithEvents {
 interface CoreEventsPort {
     subscribe(core: CoreWithEvents, host: HTMLElement): () => void;
 }
-/** Minimal core surface for UI: start auth and subscribe to events. */
+/** Minimal core surface for UI: start auth, enrollment, context hash, and subscribe to events. */
 interface CoreAuthPort extends CoreWithEvents {
     authenticate(options?: CoreAuthOptions): void;
     register(options?: CoreAuthOptions): void;
+    enroll(options?: EnrollOptions): void;
+    getContextHash(): string;
 }
 /** Options when starting auth from UI. */
 interface CoreAuthOptions {
@@ -253,8 +275,13 @@ declare class AuthController {
     consumeCancelledDetailIfAuthenticating(): MellonOperationDetail | null;
     handleAuthSuccess(): void;
     handleAuthError(): void;
+    handleEnrollSuccess(): void;
+    handleEnrollError(): void;
     onStartEvent(detail: MellonOperationDetail | undefined): void;
     startAuthFromClick(core: CoreAuthPort | null, tab: TabKind, options?: CoreAuthOptions): void;
+    startEnrollment(core: CoreAuthPort | null, options: {
+        ticketId: string;
+    }): void;
     runEnvEval(params: Omit<RunEnvEvalParams, 'currentState'>): Promise<UIState | null>;
     reset(): void;
     setStateForRender(state: UIState): void;
@@ -340,6 +367,8 @@ declare abstract class AuthElementBase extends HTMLElement {
 declare class TryMellonAuthElement extends AuthElementBase {
     static get observedAttributes(): string[];
     protected _parsed: ParsedAttributes;
+    /** When set, WC is in enrollment mode: emits context-ready and exposes enroll(). */
+    get ticketId(): string | null;
     private _internalModal;
     /** Element that opened the modal; single source for focus restore on close. */
     private _focusRestoreTarget;
@@ -348,6 +377,12 @@ declare class TryMellonAuthElement extends AuthElementBase {
     /** Re-dispatch modal success on this element so host can listen on <trymellon-auth> (modal is in body, events don't bubble here). */
     private _onInternalModalSuccess;
     private _restoreFocusToTrigger;
+    /** When ticket-id is set and core is attached, emits mellon:context-ready with contextHash (composed: true). */
+    private _emitContextReadyIfEnrollment;
+    /**
+     * Starts enrollment (only when ticket-id is set). No-op if no ticketId or core. Success/error re-dispatched via mellon:success / mellon:error.
+     */
+    enroll(): void;
     connectedCallback(): void;
     private _registerInteractions;
     attributeChangedCallback(name: string, _oldValue: string | null, _newValue: string | null): void;