@koolbase/core 10.0.0

package/dist/esm/auth-errors.d.ts

@@ -0,0 +1,117 @@
+import { KoolbaseError } from './errors.js';
+/**
+ * Base error type for all Koolbase auth errors. Catchable via
+ * `instanceof KoolbaseAuthError` to handle any auth-related failure
+ * generically; subclasses let you handle specific cases.
+ */
+export declare class KoolbaseAuthError extends KoolbaseError {
+    constructor(message: string, code?: string);
+}
+export declare class InvalidCredentialsError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class EmailAlreadyInUseError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class UserDisabledError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class WeakPasswordError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class SessionExpiredError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the access token references a session that has been revoked
+ * centrally — either by the user (sessions endpoint) or an administrator.
+ * Distinct from {@link SessionExpiredError} which indicates the access
+ * token TTL elapsed without a successful refresh.
+ *
+ * Forward-compatible: matches multiple server message patterns so it stays
+ * accurate as the server's revocation signaling evolves.
+ */
+export declare class TokenRevokedError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the account is temporarily locked due to too many failed
+ * login attempts. The server uses progressive 5/10/20-attempt lockouts;
+ * if an unlock email was issued (level 2+), the user can clear the lock
+ * by passing that token to {@link KoolbaseAuth.unlock}.
+ *
+ * [lockedUntil] is currently null — the server returns a generic 429 but
+ * does not yet include the unlock timestamp in the response body. Field
+ * is forward-compatible for when the server adds it.
+ */
+export declare class AccountLockedError extends KoolbaseAuthError {
+    lockedUntil?: Date;
+    constructor(lockedUntil?: Date);
+}
+/**
+ * Thrown when the unlock token from a brute-force unlock email is
+ * invalid, expired, or already consumed. Unlock tokens are one-shot.
+ */
+export declare class UnlockTokenInvalidError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the server rate-limits a non-phone authentication endpoint
+ * (HTTP 429 without the "account temporarily locked" marker). Phone OTP
+ * endpoints throw {@link OtpRateLimitError} instead — they hit a
+ * separate server-side rate-limiter.
+ */
+export declare class RateLimitError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * Generic network error. The SDK does NOT throw this directly — fetch
+ * failures (DNS, no connection, timeout) propagate as native TypeErrors.
+ * This class exists for consumer code that wants to construct or
+ * `instanceof`-check a typed network error from their own retry logic.
+ */
+export declare class NetworkError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class InvalidPhoneNumberError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpExpiredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpInvalidError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpMaxAttemptsError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpRateLimitError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class PhoneAlreadyLinkedError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class SmsConfigMissingError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class AppleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class InvalidAppleTokenError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class AppleEmailRequiredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OAuthEmailConflictError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class InvalidGoogleTokenError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class GoogleEmailRequiredError extends KoolbaseAuthError {
+    constructor();
+}

package/dist/esm/auth-errors.js

@@ -0,0 +1,222 @@
+import { KoolbaseError } from './errors.js';
+/**
+ * Base error type for all Koolbase auth errors. Catchable via
+ * `instanceof KoolbaseAuthError` to handle any auth-related failure
+ * generically; subclasses let you handle specific cases.
+ */
+export class KoolbaseAuthError extends KoolbaseError {
+    constructor(message, code) {
+        super(message, code);
+        this.name = 'KoolbaseAuthError';
+        Object.setPrototypeOf(this, KoolbaseAuthError.prototype);
+    }
+}
+// ─── Credentials / Registration ────────────────────────────────────────────
+export class InvalidCredentialsError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid email or password', 'invalid_credentials');
+        this.name = 'InvalidCredentialsError';
+        Object.setPrototypeOf(this, InvalidCredentialsError.prototype);
+    }
+}
+export class EmailAlreadyInUseError extends KoolbaseAuthError {
+    constructor() {
+        super('Email is already in use', 'email_taken');
+        this.name = 'EmailAlreadyInUseError';
+        Object.setPrototypeOf(this, EmailAlreadyInUseError.prototype);
+    }
+}
+export class UserDisabledError extends KoolbaseAuthError {
+    constructor() {
+        super('This account has been disabled', 'user_disabled');
+        this.name = 'UserDisabledError';
+        Object.setPrototypeOf(this, UserDisabledError.prototype);
+    }
+}
+export class WeakPasswordError extends KoolbaseAuthError {
+    constructor() {
+        super('Password must be at least 8 characters', 'weak_password');
+        this.name = 'WeakPasswordError';
+        Object.setPrototypeOf(this, WeakPasswordError.prototype);
+    }
+}
+// ─── Session lifecycle ─────────────────────────────────────────────────────
+export class SessionExpiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Session expired, please log in again', 'session_expired');
+        this.name = 'SessionExpiredError';
+        Object.setPrototypeOf(this, SessionExpiredError.prototype);
+    }
+}
+/**
+ * Thrown when the access token references a session that has been revoked
+ * centrally — either by the user (sessions endpoint) or an administrator.
+ * Distinct from {@link SessionExpiredError} which indicates the access
+ * token TTL elapsed without a successful refresh.
+ *
+ * Forward-compatible: matches multiple server message patterns so it stays
+ * accurate as the server's revocation signaling evolves.
+ */
+export class TokenRevokedError extends KoolbaseAuthError {
+    constructor() {
+        super('Session has been revoked, please log in again', 'token_revoked');
+        this.name = 'TokenRevokedError';
+        Object.setPrototypeOf(this, TokenRevokedError.prototype);
+    }
+}
+// ─── Brute-force protection ────────────────────────────────────────────────
+/**
+ * Thrown when the account is temporarily locked due to too many failed
+ * login attempts. The server uses progressive 5/10/20-attempt lockouts;
+ * if an unlock email was issued (level 2+), the user can clear the lock
+ * by passing that token to {@link KoolbaseAuth.unlock}.
+ *
+ * [lockedUntil] is currently null — the server returns a generic 429 but
+ * does not yet include the unlock timestamp in the response body. Field
+ * is forward-compatible for when the server adds it.
+ */
+export class AccountLockedError extends KoolbaseAuthError {
+    constructor(lockedUntil) {
+        super('Account temporarily locked due to too many failed attempts', 'account_locked');
+        this.lockedUntil = lockedUntil;
+        this.name = 'AccountLockedError';
+        Object.setPrototypeOf(this, AccountLockedError.prototype);
+    }
+}
+/**
+ * Thrown when the unlock token from a brute-force unlock email is
+ * invalid, expired, or already consumed. Unlock tokens are one-shot.
+ */
+export class UnlockTokenInvalidError extends KoolbaseAuthError {
+    constructor() {
+        super('Unlock link is invalid or has expired', 'unlock_token_invalid');
+        this.name = 'UnlockTokenInvalidError';
+        Object.setPrototypeOf(this, UnlockTokenInvalidError.prototype);
+    }
+}
+/**
+ * Thrown when the server rate-limits a non-phone authentication endpoint
+ * (HTTP 429 without the "account temporarily locked" marker). Phone OTP
+ * endpoints throw {@link OtpRateLimitError} instead — they hit a
+ * separate server-side rate-limiter.
+ */
+export class RateLimitError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Too many requests, please wait before trying again', 'rate_limit');
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+// ─── Network ───────────────────────────────────────────────────────────────
+/**
+ * Generic network error. The SDK does NOT throw this directly — fetch
+ * failures (DNS, no connection, timeout) propagate as native TypeErrors.
+ * This class exists for consumer code that wants to construct or
+ * `instanceof`-check a typed network error from their own retry logic.
+ */
+export class NetworkError extends KoolbaseAuthError {
+    constructor() {
+        super('Network error, please check your connection', 'network_error');
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+// ─── Phone OTP (unchanged from earlier releases) ───────────────────────────
+export class InvalidPhoneNumberError extends KoolbaseAuthError {
+    constructor() {
+        super('Phone number must be in E.164 format (e.g. +233XXXXXXXXX)', 'invalid_phone');
+        this.name = 'InvalidPhoneNumberError';
+        Object.setPrototypeOf(this, InvalidPhoneNumberError.prototype);
+    }
+}
+export class OtpExpiredError extends KoolbaseAuthError {
+    constructor() {
+        super('OTP has expired, please request a new code', 'otp_expired');
+        this.name = 'OtpExpiredError';
+        Object.setPrototypeOf(this, OtpExpiredError.prototype);
+    }
+}
+export class OtpInvalidError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid OTP code', 'otp_invalid');
+        this.name = 'OtpInvalidError';
+        Object.setPrototypeOf(this, OtpInvalidError.prototype);
+    }
+}
+export class OtpMaxAttemptsError extends KoolbaseAuthError {
+    constructor() {
+        super('Too many incorrect attempts, please request a new code', 'otp_max_attempts');
+        this.name = 'OtpMaxAttemptsError';
+        Object.setPrototypeOf(this, OtpMaxAttemptsError.prototype);
+    }
+}
+export class OtpRateLimitError extends KoolbaseAuthError {
+    constructor() {
+        super('Too many OTP requests, please wait before trying again', 'otp_rate_limit');
+        this.name = 'OtpRateLimitError';
+        Object.setPrototypeOf(this, OtpRateLimitError.prototype);
+    }
+}
+export class PhoneAlreadyLinkedError extends KoolbaseAuthError {
+    constructor() {
+        super('Phone number is already associated with another account', 'phone_taken');
+        this.name = 'PhoneAlreadyLinkedError';
+        Object.setPrototypeOf(this, PhoneAlreadyLinkedError.prototype);
+    }
+}
+export class SmsConfigMissingError extends KoolbaseAuthError {
+    constructor() {
+        super('SMS provider not configured for this project', 'sms_config_missing');
+        this.name = 'SmsConfigMissingError';
+        Object.setPrototypeOf(this, SmsConfigMissingError.prototype);
+    }
+}
+export class AppleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor() {
+        super('Apple Sign-In is not configured for this environment', 'apple_not_configured');
+        this.name = 'AppleSignInNotConfiguredError';
+        Object.setPrototypeOf(this, AppleSignInNotConfiguredError.prototype);
+    }
+}
+export class InvalidAppleTokenError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid Apple identity token', 'invalid_apple_token');
+        this.name = 'InvalidAppleTokenError';
+        Object.setPrototypeOf(this, InvalidAppleTokenError.prototype);
+    }
+}
+export class AppleEmailRequiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Apple did not return email for this sign-in. Revoke this app in iOS Settings → Apple ID and retry.', 'apple_email_required');
+        this.name = 'AppleEmailRequiredError';
+        Object.setPrototypeOf(this, AppleEmailRequiredError.prototype);
+    }
+}
+export class OAuthEmailConflictError extends KoolbaseAuthError {
+    constructor() {
+        super('Email is already in use by another account. Sign in with your existing method and link Apple from settings.', 'oauth_email_conflict');
+        this.name = 'OAuthEmailConflictError';
+        Object.setPrototypeOf(this, OAuthEmailConflictError.prototype);
+    }
+}
+export class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor() {
+        super('Google Sign-In is not configured for this environment', 'google_not_configured');
+        this.name = 'GoogleSignInNotConfiguredError';
+        Object.setPrototypeOf(this, GoogleSignInNotConfiguredError.prototype);
+    }
+}
+export class InvalidGoogleTokenError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid Google identity token', 'invalid_google_token');
+        this.name = 'InvalidGoogleTokenError';
+        Object.setPrototypeOf(this, InvalidGoogleTokenError.prototype);
+    }
+}
+export class GoogleEmailRequiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Google did not return email for this sign-in. Ensure the email scope is requested in the native flow.', 'google_email_required');
+        this.name = 'GoogleEmailRequiredError';
+        Object.setPrototypeOf(this, GoogleEmailRequiredError.prototype);
+    }
+}

package/dist/esm/auth.d.ts

@@ -0,0 +1,213 @@
+import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, SendOtpParams, SignInWithAppleParams, VerifyOtpParams } from './types.js';
+import type { SignInWithGoogleParams } from './types.js';
+export declare class KoolbaseAuth {
+    private config;
+    private storage;
+    private session;
+    private metadata;
+    private fetchFn;
+    private timeoutMs;
+    private ongoingRefresh;
+    private listeners;
+    constructor(config: KoolbaseConfig);
+    /**
+     * Subscribe to authentication state changes. The listener fires:
+     * - Immediately on subscribe, with the current user (or null).
+     * - On every successful login, register, refresh, session restoration.
+     * - On logout / explicit setSession(null).
+     * - On linkPhone success (user object updated with phone fields).
+     *
+     * Returns an unsubscribe function. Call it when the consumer no longer
+     * needs updates (e.g. in a React useEffect cleanup).
+     *
+     * Listener errors are swallowed so a buggy listener can't break auth
+     * state propagation to other listeners.
+     *
+     * @example
+     * const unsubscribe = auth.onAuthStateChange((user) => {
+     *   setCurrentUser(user);
+     * });
+     * // later:
+     * unsubscribe();
+     */
+    onAuthStateChange(listener: AuthStateListener): () => void;
+    private fireAuthStateChange;
+    /**
+     * Compose the full header set for an outbound request: base headers,
+     * device metadata, and optionally the Authorization bearer token.
+     * Async because device metadata's first build may read from keychain.
+     */
+    private prepareHeaders;
+    /**
+     * Low-level request helper used by every endpoint. Wires together:
+     * - The injected fetch implementation (config.fetch or global fetch)
+     * - Device metadata + x-api-key + auth header in one place
+     * - AbortController-based timeout (config.authTimeout, default 10s)
+     *
+     * On timeout, fetch rejects with an AbortError; callers see this as a
+     * non-KoolbaseAuthError exception, which restoreSession() treats as
+     * Offline (preserving optimistic state).
+     */
+    private authRequest;
+    /**
+     * Authenticated request wrapper. Refreshes the access token if it's
+     * stale (within 1-min buffer of expiry) before issuing the call, then
+     * delegates to {@link authRequest} with includeAuth=true.
+     */
+    private authedRequest;
+    private setSessionInternal;
+    /**
+     * Discards the stored session without contacting the server.
+     *
+     * For when the session is already known to be unusable — the server rejected
+     * the token, or a build was pointed at a different project and the persisted
+     * session belongs to the old one. Unlike `logout()` there is no server call:
+     * the token has already been refused, and asking for it to be revoked would
+     * only add a round trip that cannot succeed.
+     *
+     * Safe in any state, including with no session at all. The SDK calls this
+     * itself when a request is rejected as unauthenticated, so most apps will not
+     * need to.
+     */
+    clearStoredSession(): Promise<void>;
+    private clearSessionInternal;
+    restoreSession(): Promise<RestoreResult>;
+    register(params: RegisterParams): Promise<KoolbaseUser>;
+    login(params: LoginParams): Promise<KoolbaseSession>;
+    /**
+   * Sign in with Apple using a credential obtained from a native Apple
+   * Sign-In SDK.
+   *
+   * The SDK is library-agnostic — use any native Apple Sign-In package
+   * (`@invertase/react-native-apple-authentication`, etc.) and pass the
+   * resulting `identityToken`, optional `nonce`, and optional `fullName`.
+   *
+   * `fullName` is meaningful only on first sign-in — Apple omits name
+   * data on subsequent sign-ins. The server persists at link time and
+   * ignores on subsequent sign-ins.
+   *
+   * On success the session is persisted via the configured storage and
+   * `onAuthStateChange` fires with the resolved user.
+   *
+   * @throws AppleSignInNotConfiguredError when Apple is not enabled in
+   *   the dashboard OAuth config for this environment (400).
+   * @throws InvalidAppleTokenError when the token signature, audience,
+   *   expiry, replay, or nonce check failed server-side (401).
+   * @throws UserDisabledError when the account flag is set to disabled (403).
+   * @throws AppleEmailRequiredError when Apple did not return email for
+   *   a new-account sign-in (400).
+   * @throws OAuthEmailConflictError when email matches existing user
+   *   but auto-link rule blocked (409).
+   */
+    signInWithApple(params: SignInWithAppleParams): Promise<KoolbaseSession>;
+    /**
+     * Sign in with Google using an idToken from a native Google Sign-In SDK.
+     *
+     * The SDK is library-agnostic — use any native Google Sign-In package
+     * (`@react-native-google-signin/google-signin`, etc.) and pass the
+     * resulting `idToken`. Google embeds the user's name and email in the
+     * idToken itself, so this method does not take a `fullName` parameter
+     * (unlike `signInWithApple`).
+     *
+     * On success the session is persisted via the configured storage and
+     * `onAuthStateChange` fires with the resolved user.
+     *
+     * @throws GoogleSignInNotConfiguredError when Google is not enabled
+     *   in the OAuth config for this environment (400).
+     * @throws InvalidGoogleTokenError when the token signature, audience,
+     *   expiry, replay, or nonce check failed server-side (401).
+     * @throws UserDisabledError when the account flag is set to disabled (403).
+     * @throws GoogleEmailRequiredError when Google did not return email
+     *   for a new-account sign-in (400).
+     * @throws OAuthEmailConflictError when email matches existing user
+     *   but auto-link rule blocked (409).
+     */
+    signInWithGoogle(params: SignInWithGoogleParams): Promise<KoolbaseSession>;
+    /**
+     * Parses a /v1/sdk/auth/oauth/google response. Code-first: the server
+     * emits unified OAuth codes (oauth_not_configured, invalid_oauth_token,
+     * oauth_email_required, oauth_email_conflict) for both providers; the
+     * provider distinction is made here so Google codes map to Google-specific
+     * errors. Status + message logic is retained as a fallback for older servers.
+     */
+    private parseGoogleSessionResponse;
+    /**
+     * Parses a /v1/sdk/auth/oauth/apple response. Code-first; the provider
+     * distinction is made here so the server's unified OAuth codes map to
+     * Apple-specific errors. Status + message logic is retained as a fallback
+     * for older servers.
+     */
+    private parseAppleSessionResponse;
+    refresh(refreshToken?: string): Promise<KoolbaseSession>;
+    private _doRefresh;
+    logout(): Promise<boolean>;
+    forgotPassword(email: string): Promise<void>;
+    resetPassword(token: string, password: string): Promise<void>;
+    unlock(token: string): Promise<void>;
+    get currentUser(): KoolbaseUser | null;
+    get accessToken(): string | null;
+    /**
+     * Currently-valid access token for data-plane requests, refreshing
+     * (via refresh()) if the cached one is near expiry. Returns null when no
+     * session exists or refresh fails — callers then go api-key-only and the
+     * server treats it as having no end-user identity. The db/storage/functions
+     * clients pull from this per request so identity follows the live session.
+     */
+    validAccessToken(): Promise<string | null>;
+    setSession(session: KoolbaseSession | null): Promise<void>;
+    /**
+     * @deprecated v1.9.0: Server endpoint /v1/sdk/auth/oauth not yet
+     * shipped. This method previously routed to /v1/auth/oauth (dashboard
+     * developer OAuth) which never created project-scoped end-user
+     * sessions. Properly implemented in v1.10.0 with provider-specific
+     * server endpoints under /v1/sdk/auth/oauth/{apple,google,github}.
+     * Use email/password sign-in for now.
+     *
+     * @throws Always throws KoolbaseAuthError('not_implemented').
+     */
+    oauthLogin(_params: {
+        provider: string;
+        token: string;
+        email?: string;
+        name?: string;
+        avatarUrl?: string;
+    }): Promise<never>;
+    sendOtp(params: SendOtpParams): Promise<OtpSendResult>;
+    verifyOtp(params: VerifyOtpParams): Promise<PhoneVerifyResult>;
+    linkPhone(params: LinkPhoneParams): Promise<void>;
+    /**
+     * Release resources held by this auth client. Clears the in-memory
+     * listener set. Does not invalidate sessions or clear storage — call
+     * {@link logout} for that.
+     */
+    dispose(): void;
+    private validatePhone;
+    private _ensureValidToken;
+    private mapUser;
+    /**
+     * Parse a session-returning response (login, register, refresh).
+     * Non-2xx is delegated to throwTypedError, which is code-first
+     * (reads body.code) with a status/message fallback. isRefresh only
+     * affects how a bare 401 (no code, older server) is interpreted.
+     */
+    private parseSessionResponse;
+    private checkResponse;
+    /**
+     * Map a non-2xx credential/session response to a typed error.
+     *
+     * Code-first: the server now emits a stable `code` on every error
+     * (contract conformance), so we switch on body.code. The status +
+     * message logic is retained as a fallback for older servers or any
+     * response that arrives without a code. isRefresh only changes how a
+     * bare 401 is interpreted in the fallback path.
+     */
+    private throwTypedError;
+    /**
+     * Parse a phone-auth response. Code-first, with a phone-specific twist:
+     * the server emits the generic `rate_limit` code for the phone endpoints
+     * (they share the default 429), but phone has a dedicated server-side
+     * rate-limiter, so we surface OtpRateLimitError rather than RateLimitError.
+     * Status + message logic is retained as a fallback for older servers.
+     */
+    private parsePhoneResponse;
+}