@trymellon/js 1.1.3

package/dist/index.d.cts

@@ -0,0 +1,421 @@
+type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+declare const ok: <T>(value: T) => Result<T, never>;
+declare const err: <E>(error: E) => Result<never, 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);
+}
+declare function createError(code: TryMellonErrorCode, message?: string, details?: unknown): TryMellonError;
+declare function isTryMellonError(error: unknown): error is TryMellonError;
+declare function createNotSupportedError(): TryMellonError;
+declare function createUserCancelledError(): TryMellonError;
+declare function createNetworkError(cause?: Error): TryMellonError;
+declare function createTimeoutError(): TryMellonError;
+declare function createInvalidArgumentError(field: string, reason: string): TryMellonError;
+declare function mapWebAuthnError(error: unknown): TryMellonError;
+
+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>>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+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 OnboardingStartResult = {
+    session_id: string;
+    onboarding_url: string;
+    expires_in: number;
+};
+type OnboardingStatusResult = {
+    status: 'pending_passkey' | 'pending_data' | 'completed';
+    onboarding_url: string;
+    expires_in: number;
+};
+type OnboardingRegisterResult = {
+    session_id: string;
+    status: 'pending_passkey';
+    onboarding_url: string;
+};
+type OnboardingRegisterPasskeyOptions = {
+    session_id: string;
+    credential: {
+        id: string;
+        rawId: string;
+        response: {
+            clientDataJSON: string;
+            attestationObject: string;
+        };
+        type: 'public-key';
+    };
+    tenant_id?: string;
+    challenge: string;
+};
+type OnboardingRegisterPasskeyResult = {
+    session_id: string;
+    status: 'pending_data' | 'completed';
+    user_id: string;
+    tenant_id: string;
+};
+type OnboardingCompleteOptions = {
+    session_id: string;
+    company_name?: string;
+};
+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>>;
+        };
+    };
+}
+
+declare class ConsoleLogger implements 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;
+}
+
+export { type AuthenticateOptions, type AuthenticateResult, type ClientStatus, ConsoleLogger, type EmailFallbackStartOptions, type EmailFallbackVerifyOptions, type EmailFallbackVerifyResult, type EventHandler, type EventPayload, type LogLevel, type Logger, type OnboardingCompleteOptions, type OnboardingCompleteResult, type OnboardingRegisterPasskeyOptions, type OnboardingRegisterPasskeyResult, type OnboardingRegisterResult, type OnboardingStartOptions, type OnboardingStartResult, type OnboardingStatusResult, type RegisterOptions, type RegisterResult, type Result, type SessionValidateResponse, TryMellon, type TryMellonConfig, TryMellonError, type TryMellonErrorCode, type TryMellonEvent, createError, createInvalidArgumentError, createNetworkError, createNotSupportedError, createTimeoutError, createUserCancelledError, err, isTryMellonError, mapWebAuthnError, ok };