@techfinityedge/koolbase-react-native 1.8.0 → 1.10.0

package/dist/auth.d.ts

@@ -1,29 +1,136 @@
-import { KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, SendOtpParams, VerifyOtpParams } from './types';
+import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, SendOtpParams, SignInWithAppleParams, VerifyOtpParams } from './types';
 export declare class KoolbaseAuth {
     private config;
+    private storage;
     private session;
+    private metadata;
+    private fetchFn;
+    private timeoutMs;
+    private ongoingRefresh;
+    private listeners;
     constructor(config: KoolbaseConfig);
-    private get headers();
-    private get authHeaders();
-    private request;
+    /**
+     * 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;
+    private clearSessionInternal;
+    restoreSession(): Promise<RestoreResult>;
     register(params: RegisterParams): Promise<KoolbaseUser>;
     login(params: LoginParams): Promise<KoolbaseSession>;
-    logout(): Promise<void>;
+    /**
+   * 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>;
+    /**
+     * Parses a /v1/sdk/auth/oauth/apple response. Distinct from
+     * parseSessionResponse because OAuth error semantics differ from
+     * credential auth — status codes map to a separate error set.
+     */
+    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;
-    setSession(session: KoolbaseSession | null): void;
-    oauthLogin({ provider, token, email, name, avatarUrl, }: {
+    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<Record<string, unknown> | null>;
+    }): 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;
+    private parseSessionResponse;
+    private checkResponse;
+    private throwTypedError;
     private parsePhoneResponse;
 }