@mosano-product-framework/sdk 0.2.0

package/dist/identity/types.d.ts

@@ -0,0 +1,690 @@
+import type { MPFRole } from '../auth/claims-types.js';
+/**
+ * Roles accepted when WRITING a membership (inviting a member, updating a
+ * role).
+ *
+ * Closed on purpose, and only here: on a request, autocomplete earns its keep
+ * and an unknown role is a client bug worth catching at compile time.
+ *
+ * On RESPONSES the role is {@link MPFRole} (= `string`) instead. Roles are
+ * database rows (`identity.tenant_membership_valid_roles`), so closing the union
+ * on server output means a newly seeded role forces an SDK release — and it is
+ * exactly how the fictional `'viewer'` role ended up in these types in five
+ * places while the DB actually seeds `guest`.
+ */
+export type MPFTenantRoleInput = 'owner' | 'admin' | 'member' | 'guest';
+/**
+ * Request body for user registration
+ */
+export interface CreateUserRequest {
+    /** User's email address */
+    email: string;
+    /** User's password (minimum 8 characters) */
+    password: string;
+    /** User's display name */
+    display_name?: string;
+    /** User's first name */
+    first_name?: string;
+    /** User's last name */
+    last_name?: string;
+}
+/**
+ * Request body for user login
+ */
+export interface LoginRequest {
+    /** User's email address */
+    email: string;
+    /** User's password */
+    password: string;
+}
+/**
+ * Request body for profile update
+ */
+export interface UpdateProfileRequest {
+    /** User's display name */
+    display_name?: string;
+    /** User's first name */
+    first_name?: string;
+    /** User's last name */
+    last_name?: string;
+    /** Custom user metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request body for adding an email
+ */
+export interface AddEmailRequest {
+    /** Email address to add */
+    email: string;
+}
+/**
+ * Request body for adding a phone number
+ */
+export interface AddPhoneRequest {
+    /** Phone number in E.164 format */
+    phone_number: string;
+}
+/**
+ * Request body for verifying email or phone
+ */
+export interface VerifyContactRequest {
+    /** 6-digit verification code */
+    code: string;
+}
+/**
+ * Request body for sending password recovery code
+ */
+export interface SendRecoveryCodeRequest {
+    /** User's email address */
+    email: string;
+}
+/**
+ * Request body for verifying recovery code
+ */
+export interface VerifyRecoveryCodeRequest {
+    /** User's email address */
+    email: string;
+    /** 6-digit verification code */
+    verification_code: string;
+}
+/**
+ * Request body for password reset
+ */
+export interface ResetPasswordRequest {
+    /** Recovery token obtained from verification step */
+    recovery_token: string;
+    /** New password to set (minimum 8 characters) */
+    new_password: string;
+}
+/**
+ * Request body for authenticated password update
+ */
+export interface UpdatePasswordRequest {
+    /** Current password for verification */
+    current_password: string;
+    /** New password to set (minimum 8 characters) */
+    new_password: string;
+}
+/**
+ * Request body for session renewal
+ */
+export interface RenewSessionRequest {
+    /** The refresh token from the current session */
+    refresh_token: string;
+}
+/**
+ * Request body for session revocation
+ */
+export interface RevokeSessionRequest {
+    /** The refresh token of the session to revoke */
+    refresh_token: string;
+}
+/**
+ * Request body for tenant creation
+ */
+export interface CreateTenantRequest {
+    /** Name of the tenant organization */
+    name: string;
+    /** URL-friendly slug (auto-generated from name if omitted) */
+    slug?: string;
+    /** Optional description of the tenant */
+    description?: string;
+}
+/**
+ * Request body for inviting a member
+ */
+export interface InviteMemberRequest {
+    /** Email address of the person to invite */
+    email: string;
+    /** Role to assign to the invited member */
+    role: MPFTenantRoleInput;
+    /**
+     * Optional override for the configured accept URL template. The literal
+     * "{token}" is replaced with the invitation token.
+     */
+    accept_url_template?: string;
+}
+/**
+ * Result of POST /tenants/{id}/members/invite.
+ */
+export interface InvitationResponse {
+    invitation_id: string;
+    invite_token: string;
+    /** Copyable URL the invitee can use; safe fallback if email delivery fails. */
+    accept_url: string;
+    email: string;
+    role: string;
+    expires_at: string;
+    /** True when no existing user matches the invited email. */
+    is_new_user: boolean;
+    /** True when the invitation email was successfully dispatched. */
+    email_sent: boolean;
+    /** Legacy field. Always empty in the new invitation flow. */
+    membership_id?: string;
+}
+/**
+ * Public, pre-auth view of an invitation. Email is intentionally omitted.
+ */
+export interface InvitationPreviewResponse {
+    tenant_id: string;
+    tenant_name: string;
+    tenant_slug?: string;
+    role: string;
+    inviter_display_name?: string;
+    expires_at: string;
+    /** True when the invitee has no verified account yet. */
+    requires_signup: boolean;
+}
+/**
+ * Result of POST /invitations/{token}/accept.
+ */
+export interface AcceptInvitationResponse {
+    invitation_id: string;
+    tenant_id: string;
+    role: string;
+    membership_id: string;
+    accepted_at: string;
+}
+/**
+ * Request body for updating member role
+ */
+export interface UpdateMemberRoleRequest {
+    /** New role for the member */
+    role: MPFTenantRoleInput;
+}
+/**
+ * Request body for verifying a TOTP code
+ */
+export interface VerifyTOTPRequest {
+    /** 6-digit TOTP code from authenticator app */
+    code: string;
+}
+/**
+ * Request body for disabling TOTP
+ */
+export interface DisableTOTPRequest {
+    /** 6-digit TOTP code to confirm disable */
+    code: string;
+}
+/**
+ * Request body for deleting a passkey (optional, required when user has TOTP 2FA enabled)
+ */
+export interface DeletePasskeyRequest {
+    /** 6-digit TOTP code from authenticator app */
+    totp_code?: string;
+}
+/** WebAuthn credential descriptor as serialized by the API */
+export interface WebAuthnCredentialDescriptor {
+    type: string;
+    id: string;
+    transports?: string[];
+}
+/** WebAuthn creation options as serialized by the API (base64url strings, not ArrayBuffers) */
+export interface WebAuthnCreationOptions {
+    rp: {
+        id: string;
+        name: string;
+    };
+    user: {
+        id: string;
+        name: string;
+        displayName: string;
+    };
+    challenge: string;
+    pubKeyCredParams: Array<{
+        type: string;
+        alg: number;
+    }>;
+    timeout?: number;
+    excludeCredentials?: WebAuthnCredentialDescriptor[];
+    authenticatorSelection?: {
+        authenticatorAttachment?: string;
+        residentKey?: string;
+        requireResidentKey?: boolean;
+        userVerification?: string;
+    };
+    attestation?: string;
+    hints?: string[];
+    extensions?: Record<string, unknown>;
+}
+/** WebAuthn request options as serialized by the API (base64url strings, not ArrayBuffers) */
+export interface WebAuthnRequestOptions {
+    challenge: string;
+    rpId?: string;
+    timeout?: number;
+    allowCredentials?: WebAuthnCredentialDescriptor[];
+    userVerification?: string;
+    hints?: string[];
+    extensions?: Record<string, unknown>;
+}
+/** Encoded credential sent back to the server after navigator.credentials.create/get */
+export interface WebAuthnEncodedCredential {
+    id: string;
+    rawId: string;
+    type: string;
+    response: {
+        clientDataJSON: string;
+        attestationObject?: string;
+        authenticatorData?: string;
+        signature?: string;
+        userHandle?: string | null;
+    };
+}
+/**
+ * Request body for completing passkey registration
+ */
+export interface FinishPasskeyRegistrationRequest {
+    /** Raw WebAuthn credential from navigator.credentials.create() */
+    credential: WebAuthnEncodedCredential;
+    /** Optional human-readable name for the passkey */
+    name?: string;
+}
+/**
+ * Request body for completing passkey login
+ */
+export interface FinishPasskeyLoginRequest {
+    /** Raw WebAuthn credential from navigator.credentials.get() */
+    credential: WebAuthnEncodedCredential;
+    /** Session key returned from begin login */
+    session_key: string;
+}
+/**
+ * Request body for Google OAuth callback
+ */
+export interface GoogleOAuthCallbackRequest {
+    /** Authorization code from Google */
+    code: string;
+    /** Redirect URI used in the initial auth request */
+    redirect_uri: string;
+    /**
+     * The `state` returned by `getGoogleOAuthURL`, round-tripped through the
+     * redirect.
+     *
+     * **Required, and required for a reason.** It is the CSRF defence for this
+     * flow: the server validates it before exchanging the code, so a callback
+     * carrying an attacker's `code` but not the victim's `state` is rejected.
+     * Without it, an attacker can sign a victim into the attacker's own account —
+     * confirmed exploitable, not hypothetical.
+     *
+     * Persist it across the redirect with `createOAuthStateStore()` (web storage:
+     * a full-page redirect discards anything held in memory).
+     */
+    state: string;
+}
+/**
+ * Response containing access and refresh tokens
+ */
+export interface AccessDataResponse {
+    /** JWT access token for API authentication */
+    access_token: string;
+    /** Refresh token for session renewal */
+    refresh_token: string;
+}
+/**
+ * User profile information
+ */
+export interface UserProfileResponse {
+    /** User's unique identifier */
+    id: string;
+    /** User's display name */
+    display_name?: string;
+    /** User's first name */
+    first_name?: string;
+    /** User's last name */
+    last_name?: string;
+    /** User's avatar URL */
+    avatar_url?: string;
+    /** User's email addresses */
+    emails: EmailResponse[];
+    /** User's phone numbers */
+    phones: PhoneResponse[];
+}
+/**
+ * Email address information
+ */
+export interface EmailResponse {
+    /** Email's unique identifier */
+    id: string;
+    /** Email address */
+    email: string;
+    /** Whether this is the primary email */
+    is_primary: boolean;
+    /** When the email was verified (ISO 8601), undefined if not verified */
+    verified_at?: string;
+}
+/**
+ * Phone number information
+ */
+export interface PhoneResponse {
+    /** Phone's unique identifier */
+    id: string;
+    /** Phone number in E.164 format */
+    phone_number: string;
+    /** Whether this is the primary phone */
+    is_primary: boolean;
+    /** When the phone was verified (ISO 8601), undefined if not verified */
+    verified_at?: string;
+}
+/**
+ * Session client information
+ */
+export interface SessionClientInfo {
+    /** Client name */
+    name?: string;
+    /** Client user agent string */
+    user_agent?: string;
+    /** Client IP address */
+    ip_address?: string;
+    /** When the client was last seen (ISO 8601) */
+    last_seen_at?: string;
+}
+/**
+ * Session information
+ */
+export interface SessionResponse {
+    /** Session's unique identifier */
+    id: string;
+    /** Client ID associated with the session */
+    client_id: string;
+    /** Client information */
+    client?: SessionClientInfo;
+    /** When the session expires (ISO 8601) */
+    expires_at: string;
+    /** When the session was created (ISO 8601) */
+    created_at: string;
+    /** Whether this is the current session */
+    is_current: boolean;
+}
+/**
+ * OAuth client information
+ */
+export interface ClientResponse {
+    /** Client's unique identifier */
+    id: string;
+    /** Client name */
+    name?: string;
+    /** Client user agent string */
+    user_agent?: string;
+    /** Client IP address */
+    ip_address?: string;
+    /** When the client was last seen (ISO 8601) */
+    last_seen_at?: string;
+}
+/**
+ * Tenant information
+ */
+export interface TenantResponse {
+    /** Tenant's unique identifier */
+    id: string;
+    /** Tenant name */
+    name: string;
+    /** Tenant description */
+    description?: string;
+    /** Tenant slug (URL-friendly identifier) */
+    slug?: string;
+    /** When the tenant was created (ISO 8601) */
+    created_at: string;
+}
+/**
+ * Tenant membership information
+ */
+export interface MembershipResponse {
+    /** Membership unique identifier */
+    id: string;
+    /** User's unique identifier */
+    user_id: string;
+    /** Member's role in the tenant */
+    role: MPFRole;
+    /** When the member was invited (ISO 8601) */
+    invited_at?: string;
+    /** When the invitation was accepted (ISO 8601) */
+    accepted_at?: string;
+    /** Member's display name */
+    display_name?: string;
+    /** Member's email address */
+    email?: string;
+}
+/**
+ * Response containing recovery token
+ */
+export interface RecoveryTokenResponse {
+    /** Token to use for password reset */
+    recovery_token: string;
+}
+/**
+ * Simple success response
+ */
+export interface SuccessResponse {
+    /** Indicates if the operation was successful */
+    success: boolean;
+}
+/**
+ * Error response from the API
+ */
+export interface ErrorResponse {
+    /** Human-readable error message */
+    error: string;
+    /** Machine-readable error code */
+    code?: string;
+    /** Additional error details (validation errors, etc.) */
+    details?: unknown;
+}
+/**
+ * Validation error detail for a specific field
+ */
+export interface ValidationErrorDetail {
+    /** Name of the field with validation error */
+    field: string;
+    /** Validation error message */
+    message: string;
+}
+/**
+ * Service health status response
+ */
+export interface HealthResponse {
+    /** Health status */
+    status: string;
+    /** Service name */
+    service: string;
+    /** Current server timestamp (ISO 8601) */
+    timestamp: string;
+}
+/**
+ * Response from TOTP setup containing secret and backup codes
+ */
+export interface TOTPSetupResponse {
+    /** TOTP secret key for manual entry */
+    secret: string;
+    /** otpauth:// URL for QR code generation */
+    qr_url: string;
+    /** One-time backup codes for account recovery */
+    backup_codes: string[];
+}
+/**
+ * Response from begin passkey registration
+ */
+export interface BeginPasskeyRegistrationResponse {
+    /** WebAuthn PublicKeyCredentialCreationOptions */
+    options: WebAuthnCreationOptions;
+}
+/**
+ * Response from begin passkey login
+ */
+export interface BeginPasskeyLoginResponse {
+    /** WebAuthn PublicKeyCredentialRequestOptions */
+    options: WebAuthnRequestOptions;
+    /** Session key to pass back in finish login */
+    session_key: string;
+}
+/**
+ * Passkey credential information
+ */
+export interface PasskeyResponse {
+    /** Passkey's unique identifier */
+    id: string;
+    /** Human-readable name for the passkey */
+    name?: string;
+    /** When the passkey was registered (ISO 8601) */
+    created_at: string;
+    /** When the passkey was last used (ISO 8601) */
+    last_used_at?: string;
+}
+/**
+ * A pending invitation for the current user
+ */
+export interface PendingInvitationResponse {
+    /** Invitation/membership ID */
+    id: string;
+    /** Tenant ID the invitation is for */
+    tenant_id: string;
+    /** Tenant name */
+    tenant_name: string;
+    /** Tenant slug */
+    tenant_slug?: string;
+    /** Role assigned in the invitation */
+    role: MPFRole;
+    /** User ID of the person who sent the invitation */
+    invited_by: string;
+    /** When the invitation was sent (ISO 8601) */
+    invited_at: string;
+    /** Invitation token for accepting */
+    token: string;
+}
+/**
+ * A pending invitation issued by the authenticated caller, returned by
+ * GET /tenants/{id}/invitations.
+ */
+export interface IssuedInvitationResponse {
+    /** Invitation ID */
+    id: string;
+    /** Tenant the invitation was issued for */
+    tenant_id: string;
+    /** Email the invitation was sent to */
+    email: string;
+    /** Role the invitee will receive on accept */
+    role: MPFRole;
+    /** User ID of the inviter (always the authenticated caller) */
+    invited_by: string;
+    /** When the invitation was sent (ISO 8601) */
+    invited_at: string;
+    /** Expiration time (ISO 8601) */
+    expires_at: string;
+    /** Raw token. Most callers should use accept_url instead. */
+    token: string;
+    /**
+     * Copyable URL the invitee can paste into a browser. Empty if the server
+     * has no accept-URL template configured.
+     */
+    accept_url: string;
+    /** Display name of the invitee, if they already have an account */
+    display_name?: string;
+}
+/**
+ * Response containing Google OAuth authorization URL
+ */
+export interface GoogleOAuthURLResponse {
+    /** Full Google OAuth authorization URL to redirect user to */
+    url: string;
+    /**
+     * Single-use CSRF state minted and recorded by the server.
+     *
+     * Persist this before redirecting and send it back on
+     * `handleGoogleOAuthCallback`. Dropping it makes the callback trivially
+     * forgeable — see {@link GoogleOAuthCallbackRequest.state}.
+     */
+    state: string;
+}
+/**
+ * Wrapper response for email list
+ */
+export interface EmailsResponse {
+    emails: EmailResponse[];
+}
+/**
+ * Wrapper response for phone list
+ */
+export interface PhonesResponse {
+    phones: PhoneResponse[];
+}
+/**
+ * Wrapper response for session list
+ */
+export interface SessionsResponse {
+    sessions: SessionResponse[];
+}
+/**
+ * Wrapper response for passkey list
+ */
+export interface PasskeysResponse {
+    passkeys: PasskeyResponse[];
+}
+/**
+ * Wrapper response for client list
+ */
+export interface ClientsResponse {
+    clients: ClientResponse[];
+}
+/**
+ * Wrapper response for member list
+ */
+export interface MembersResponse {
+    members: MembershipResponse[];
+}
+/**
+ * Wrapper response for pending-invitations-issued-by-caller list
+ */
+export interface IssuedInvitationsResponse {
+    invitations: IssuedInvitationResponse[];
+}
+/**
+ * Returned when MFA verification is needed to complete login
+ */
+export interface MFARequiredResponse {
+    /** Always true for this response type */
+    mfa_required: true;
+    /** Short-lived JWT ticket for MFA verification */
+    mfa_ticket: string;
+    /** Available MFA methods (e.g., ["totp"]) */
+    mfa_methods: string[];
+}
+/**
+ * Returned when MFA setup is enforced and user hasn't set up TOTP yet
+ */
+export interface MFASetupRequiredResponse {
+    /** Always true for this response type */
+    mfa_setup_required: true;
+    /** Short-lived JWT ticket for MFA setup verification */
+    mfa_ticket: string;
+    /** TOTP setup data including secret and QR code */
+    totp_setup: TOTPSetupResponse;
+}
+/**
+ * Union type for all possible login responses
+ */
+export type LoginResponse = AccessDataResponse | MFARequiredResponse | MFASetupRequiredResponse;
+/**
+ * Type guard to check if login response requires MFA verification
+ */
+export declare function isMFARequired(response: LoginResponse): response is MFARequiredResponse;
+/**
+ * Type guard to check if login response requires MFA setup
+ */
+export declare function isMFASetupRequired(response: LoginResponse): response is MFASetupRequiredResponse;
+/**
+ * Request body for verifying MFA during login
+ */
+export interface MFAVerifyRequest {
+    /** MFA ticket from login response */
+    mfa_ticket: string;
+    /** 6-digit TOTP code from authenticator app */
+    totp_code: string;
+}
+/**
+ * Request body for verifying MFA setup during first-time enrollment
+ */
+export interface MFASetupVerifyRequest {
+    /** MFA ticket from login response */
+    mfa_ticket: string;
+    /** 6-digit TOTP code to verify setup */
+    code: string;
+}