@trymellon/js 1.1.3

package/dist/trymellon-Ca4kob_K.d.cts

@@ -0,0 +1,364 @@
+type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+
+type TryMellonErrorCode = 'NOT_SUPPORTED' | 'USER_CANCELLED' | 'PASSKEY_NOT_FOUND' | 'SESSION_EXPIRED' | 'NETWORK_FAILURE' | 'INVALID_ARGUMENT' | 'TIMEOUT' | 'ABORTED' | 'UNKNOWN_ERROR';
+declare class TryMellonError extends Error {
+    readonly code: TryMellonErrorCode;
+    readonly details?: unknown;
+    readonly isTryMellonError = true;
+    constructor(code: TryMellonErrorCode, message: string, details?: unknown);
+}
+
+interface HttpClient {
+    get<T>(url: string, headers?: Record<string, string>): Promise<Result<T, TryMellonError>>;
+    post<T>(url: string, body: unknown, headers?: Record<string, string>): Promise<Result<T, TryMellonError>>;
+}
+
+interface Logger {
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+
+type TelemetryEvent = 'register' | 'authenticate';
+type TelemetryPayload = {
+    event: TelemetryEvent;
+    latencyMs: number;
+    ok: true;
+};
+interface TelemetrySender {
+    send(payload: TelemetryPayload): Promise<void>;
+}
+
+type TryMellonConfig = {
+    /** Application identifier (tenant). Required for API requests. */
+    appId: string;
+    /** API key for authentication. Required for API requests. */
+    publishableKey: string;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    /** Optional logger for request/error correlation (e.g. requestId). */
+    logger?: Logger;
+    /** If true, send anonymous telemetry (event + latency) after successful register/authenticate. */
+    enableTelemetry?: boolean;
+    /** Custom telemetry sender; used when enableTelemetry is true. Defaults to TryMellon endpoint. */
+    telemetrySender?: TelemetrySender;
+    /** Endpoint for default telemetry sender when enableTelemetry is true and telemetrySender not set. */
+    telemetryEndpoint?: string;
+};
+type RegisterOptions = {
+    /** User identifier (recommended: camelCase). */
+    externalUserId?: string;
+    /** User identifier (snake_case alias). */
+    external_user_id?: string;
+    authenticatorType?: 'platform' | 'cross-platform';
+    signal?: AbortSignal;
+};
+type RegisterResult = {
+    success: true;
+    credential_id: string;
+    status: string;
+    session_token: string;
+    user: {
+        user_id: string;
+        external_user_id: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    };
+};
+type AuthenticateOptions = {
+    /** User identifier (recommended: camelCase). */
+    externalUserId?: string;
+    /** User identifier (snake_case alias). */
+    external_user_id?: string;
+    hint?: string;
+    signal?: AbortSignal;
+    /** Conditional UI mediation for passkey autofill / conditional UI. */
+    mediation?: 'optional' | 'conditional' | 'required';
+};
+type AuthenticateResult = {
+    authenticated: boolean;
+    session_token: string;
+    user: {
+        user_id: string;
+        external_user_id: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    };
+    signals: {
+        userVerification?: boolean;
+        backupEligible?: boolean;
+        backupStatus?: boolean;
+    };
+};
+type ClientStatus = {
+    isPasskeySupported: boolean;
+    platformAuthenticatorAvailable: boolean;
+    recommendedFlow: 'passkey' | 'fallback';
+};
+type TryMellonEvent = 'start' | 'success' | 'error' | 'cancelled';
+type EventPayload = {
+    type: 'start';
+    operation: 'register' | 'authenticate';
+} | {
+    type: 'success';
+    operation: 'register' | 'authenticate';
+} | {
+    type: 'error';
+    error: TryMellonError;
+} | {
+    type: 'cancelled';
+    operation: 'register' | 'authenticate';
+};
+type EventHandler = (payload: EventPayload) => void;
+type EmailFallbackStartOptions = {
+    userId: string;
+};
+type EmailFallbackVerifyOptions = {
+    userId: string;
+    code: string;
+};
+type EmailFallbackVerifyResult = {
+    sessionToken: string;
+};
+type OnboardingStartOptions = {
+    user_role: 'maintainer' | 'app_user';
+};
+type OnboardingCompleteResult = {
+    session_id: string;
+    status: 'completed';
+    user_id: string;
+    tenant_id: string;
+    session_token: string;
+};
+type RegisterStartRequest = {
+    external_user_id: string;
+};
+type AuthStartRequest = {
+    external_user_id: string;
+};
+type RegisterFinishRequest = {
+    session_id: string;
+    credential: {
+        id: string;
+        rawId: string;
+        response: {
+            clientDataJSON: string;
+            attestationObject: string;
+        };
+        type: 'public-key';
+    };
+};
+type AuthFinishRequest = {
+    session_id: string;
+    credential: {
+        id: string;
+        rawId: string;
+        response: {
+            authenticatorData: string;
+            clientDataJSON: string;
+            signature: string;
+            userHandle?: string;
+        };
+        type: 'public-key';
+    };
+};
+type RegisterStartResponse = {
+    challenge: {
+        rp: {
+            name: string;
+            id: string;
+        };
+        user: {
+            id: string;
+            name: string;
+            displayName: string;
+        };
+        challenge: string;
+        pubKeyCredParams: Array<{
+            type: 'public-key';
+            alg: number;
+        }>;
+        timeout?: number;
+        excludeCredentials?: Array<{
+            id: string;
+            type: 'public-key';
+            transports?: string[];
+        }>;
+        authenticatorSelection?: {
+            userVerification?: 'required' | 'preferred' | 'discouraged';
+            residentKey?: 'required' | 'preferred' | 'discouraged';
+            authenticatorAttachment?: 'platform' | 'cross-platform';
+        };
+    };
+    session_id: string;
+};
+type AuthStartResponse = {
+    challenge: {
+        challenge: string;
+        rpId: string;
+        allowCredentials: Array<{
+            id: string;
+            type: 'public-key';
+            transports?: string[];
+        }>;
+        timeout?: number;
+        userVerification?: 'required' | 'preferred' | 'discouraged';
+    };
+    session_id: string;
+};
+type RegisterFinishResponse = {
+    credential_id: string;
+    status: string;
+    session_token: string;
+    user: {
+        user_id: string;
+        external_user_id: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    };
+};
+type AuthFinishResponse = {
+    authenticated: boolean;
+    user: {
+        user_id: string;
+        external_user_id: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    };
+    signals: {
+        userVerification?: boolean;
+        backupEligible?: boolean;
+        backupStatus?: boolean;
+    };
+    session_token: string;
+};
+type SessionValidateResponse = {
+    valid: boolean;
+    user_id: string;
+    external_user_id: string;
+    tenant_id: string;
+    app_id: string;
+};
+type OnboardingStartRequest = {
+    user_role: 'maintainer' | 'app_user';
+};
+type OnboardingStartResponse = {
+    session_id: string;
+    onboarding_url: string;
+    expires_in: number;
+};
+type OnboardingStatusResponse = {
+    status: 'pending_passkey' | 'pending_data' | 'completed';
+    onboarding_url: string;
+    expires_in: number;
+};
+type OnboardingRegisterResponse = {
+    session_id: string;
+    status: 'pending_passkey';
+    onboarding_url: string;
+};
+type OnboardingRegisterPasskeyRequest = {
+    credential: {
+        id: string;
+        rawId: string;
+        response: {
+            clientDataJSON: string;
+            attestationObject: string;
+        };
+        type: 'public-key';
+    };
+    tenant_id?: string;
+    challenge: string;
+};
+type OnboardingRegisterPasskeyResponse = {
+    session_id: string;
+    status: 'pending_data' | 'completed';
+    user_id: string;
+    tenant_id: string;
+};
+type OnboardingCompleteRequest = {
+    company_name?: string;
+};
+type OnboardingCompleteResponse = {
+    session_id: string;
+    status: 'completed';
+    user_id: string;
+    tenant_id: string;
+    session_token: string;
+};
+
+/** Response may include optional challenge for same-device passkey registration */
+type OnboardingRegisterResponseWithChallenge = OnboardingRegisterResponse & {
+    challenge?: RegisterStartResponse['challenge'];
+};
+
+declare class ApiClient {
+    private readonly httpClient;
+    private readonly baseUrl;
+    private readonly defaultHeaders;
+    constructor(httpClient: HttpClient, baseUrl: string, defaultHeaders?: Record<string, string>);
+    private mergeHeaders;
+    private post;
+    private get;
+    startRegister(request: RegisterStartRequest): Promise<Result<RegisterStartResponse, TryMellonError>>;
+    startAuth(request: AuthStartRequest): Promise<Result<AuthStartResponse, TryMellonError>>;
+    finishRegister(request: RegisterFinishRequest): Promise<Result<RegisterFinishResponse, TryMellonError>>;
+    finishAuth(request: AuthFinishRequest): Promise<Result<AuthFinishResponse, TryMellonError>>;
+    validateSession(sessionToken: string): Promise<Result<SessionValidateResponse, TryMellonError>>;
+    startEmailFallback(userId: string): Promise<Result<void, TryMellonError>>;
+    verifyEmailCode(userId: string, code: string): Promise<Result<{
+        sessionToken: string;
+    }, TryMellonError>>;
+    startOnboarding(request: OnboardingStartRequest): Promise<Result<OnboardingStartResponse, TryMellonError>>;
+    getOnboardingStatus(sessionId: string): Promise<Result<OnboardingStatusResponse, TryMellonError>>;
+    getOnboardingRegister(sessionId: string): Promise<Result<OnboardingRegisterResponseWithChallenge, TryMellonError>>;
+    registerOnboardingPasskey(sessionId: string, request: OnboardingRegisterPasskeyRequest): Promise<Result<OnboardingRegisterPasskeyResponse, TryMellonError>>;
+    completeOnboarding(sessionId: string, request: OnboardingCompleteRequest): Promise<Result<OnboardingCompleteResponse, TryMellonError>>;
+}
+
+declare class OnboardingManager {
+    private readonly apiClient;
+    constructor(apiClient: ApiClient);
+    /**
+     * Executes the full onboarding flow in a single call.
+     * 1. Starts onboarding
+     * 2. Polls for 'pending_passkey' or 'completed' status
+     * 3. If pending_passkey: when API returns challenge, registers passkey (WebAuthn) then completes onboarding
+     * 4. If pending_passkey but API does not return challenge: returns NOT_SUPPORTED with onboarding_url for user to complete elsewhere
+     */
+    startFlow(options: OnboardingStartOptions & {
+        company_name?: string;
+    }): Promise<Result<OnboardingCompleteResult, TryMellonError>>;
+}
+
+declare class TryMellon {
+    private apiClient;
+    private eventEmitter;
+    private telemetrySender;
+    onboarding: OnboardingManager;
+    constructor(config: TryMellonConfig);
+    static isSupported(): boolean;
+    register(options: RegisterOptions): Promise<Result<RegisterResult, TryMellonError>>;
+    authenticate(options: AuthenticateOptions): Promise<Result<AuthenticateResult, TryMellonError>>;
+    validateSession(sessionToken: string): Promise<Result<SessionValidateResponse, TryMellonError>>;
+    getStatus(): Promise<ClientStatus>;
+    on(event: TryMellonEvent, handler: EventHandler): () => void;
+    version(): string;
+    fallback: {
+        email: {
+            start: (options: EmailFallbackStartOptions) => Promise<Result<void, TryMellonError>>;
+            verify: (options: EmailFallbackVerifyOptions) => Promise<Result<EmailFallbackVerifyResult, TryMellonError>>;
+        };
+    };
+}
+
+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 };