@koolbase/core 10.3.0 → 11.0.0

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

@@ -64,6 +64,25 @@ export declare class UnlockTokenInvalidError extends KoolbaseAuthError {
 export declare class RateLimitError extends KoolbaseAuthError {
     constructor(message?: string);
 }
+/**
+ * The verification email was refused because one was sent too recently.
+ *
+ * Carries when the next send becomes possible, so an app can show a countdown
+ * rather than a bare refusal — the server sends the timestamp and throwing it
+ * away would waste the only thing that makes this error actionable.
+ */
+export declare class VerificationResendCooldownError extends KoolbaseAuthError {
+    readonly cooldownUntil: Date | null;
+    constructor(cooldownUntil: Date | null, message?: string);
+}
+/**
+ * The day's verification-email allowance is spent. Distinct from the cooldown
+ * because the remedy differs: waiting seconds versus waiting until tomorrow,
+ * and an app should say which.
+ */
+export declare class VerificationResendDailyCapError 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.
@@ -109,6 +128,19 @@ export declare class OAuthEmailConflictError extends KoolbaseAuthError {
 export declare class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
     constructor();
 }
+/**
+ * The server answered a sign-in as though it succeeded, without the tokens a
+ * session needs.
+ *
+ * Distinct from verification_required, which is a legitimate session-less
+ * success the SDK reports through SignUpResult. This is the other case: the
+ * response claims authentication and cannot support it. Inventing a session
+ * from it is what produced a signed-in user whose every request went out as
+ * `Bearer undefined`, so the SDK refuses instead.
+ */
+export declare class MalformedSessionResponseError extends KoolbaseAuthError {
+    constructor(missing: string);
+}
 export declare class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor();
 }

package/dist/cjs/auth-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.GoogleSignInNotConfiguredError = exports.OAuthEmailConflictError = exports.AppleEmailRequiredError = exports.InvalidAppleTokenError = exports.AppleSignInNotConfiguredError = exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.InvalidPhoneNumberError = exports.NetworkError = exports.RateLimitError = exports.UnlockTokenInvalidError = exports.AccountLockedError = exports.TokenRevokedError = exports.SessionExpiredError = exports.WeakPasswordError = exports.UserDisabledError = exports.EmailAlreadyInUseError = exports.InvalidCredentialsError = exports.KoolbaseAuthError = void 0;
+exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.MalformedSessionResponseError = exports.GoogleSignInNotConfiguredError = exports.OAuthEmailConflictError = exports.AppleEmailRequiredError = exports.InvalidAppleTokenError = exports.AppleSignInNotConfiguredError = exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.InvalidPhoneNumberError = exports.NetworkError = exports.VerificationResendDailyCapError = exports.VerificationResendCooldownError = exports.RateLimitError = exports.UnlockTokenInvalidError = exports.AccountLockedError = exports.TokenRevokedError = exports.SessionExpiredError = exports.WeakPasswordError = exports.UserDisabledError = exports.EmailAlreadyInUseError = exports.InvalidCredentialsError = exports.KoolbaseAuthError = void 0;
 const errors_js_1 = require("./errors.js");
 /**
  * Base error type for all Koolbase auth errors. Catchable via
@@ -120,6 +120,35 @@ class RateLimitError extends KoolbaseAuthError {
     }
 }
 exports.RateLimitError = RateLimitError;
+/**
+ * The verification email was refused because one was sent too recently.
+ *
+ * Carries when the next send becomes possible, so an app can show a countdown
+ * rather than a bare refusal — the server sends the timestamp and throwing it
+ * away would waste the only thing that makes this error actionable.
+ */
+class VerificationResendCooldownError extends KoolbaseAuthError {
+    constructor(cooldownUntil, message) {
+        super(message ?? 'Please wait before requesting another verification email', 'resend_cooldown');
+        this.cooldownUntil = cooldownUntil;
+        this.name = 'VerificationResendCooldownError';
+        Object.setPrototypeOf(this, VerificationResendCooldownError.prototype);
+    }
+}
+exports.VerificationResendCooldownError = VerificationResendCooldownError;
+/**
+ * The day's verification-email allowance is spent. Distinct from the cooldown
+ * because the remedy differs: waiting seconds versus waiting until tomorrow,
+ * and an app should say which.
+ */
+class VerificationResendDailyCapError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Daily verification-email limit reached; try again tomorrow', 'resend_daily_cap');
+        this.name = 'VerificationResendDailyCapError';
+        Object.setPrototypeOf(this, VerificationResendDailyCapError.prototype);
+    }
+}
+exports.VerificationResendDailyCapError = VerificationResendDailyCapError;
 // ─── Network ───────────────────────────────────────────────────────────────
 /**
  * Generic network error. The SDK does NOT throw this directly — fetch
@@ -232,6 +261,24 @@ class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
     }
 }
 exports.GoogleSignInNotConfiguredError = GoogleSignInNotConfiguredError;
+/**
+ * The server answered a sign-in as though it succeeded, without the tokens a
+ * session needs.
+ *
+ * Distinct from verification_required, which is a legitimate session-less
+ * success the SDK reports through SignUpResult. This is the other case: the
+ * response claims authentication and cannot support it. Inventing a session
+ * from it is what produced a signed-in user whose every request went out as
+ * `Bearer undefined`, so the SDK refuses instead.
+ */
+class MalformedSessionResponseError extends KoolbaseAuthError {
+    constructor(missing) {
+        super(`The server returned a session without ${missing}. This is a protocol error, not a credential problem.`, 'malformed_session_response');
+        this.name = 'MalformedSessionResponseError';
+        Object.setPrototypeOf(this, MalformedSessionResponseError.prototype);
+    }
+}
+exports.MalformedSessionResponseError = MalformedSessionResponseError;
 class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor() {
         super('Invalid Google identity token', 'invalid_google_token');

package/dist/cjs/auth.d.ts

@@ -1,4 +1,4 @@
-import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, SendOtpParams, SignInWithAppleParams, VerifyOtpParams } from './types.js';
+import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, ResendVerificationResult, SendOtpParams, SignUpResult, SignInWithAppleParams, VerifyOtpParams } from './types.js';
 import type { SignInWithGoogleParams } from './types.js';
 export declare class KoolbaseAuth {
     private config;
@@ -72,7 +72,19 @@ export declare class KoolbaseAuth {
     clearStoredSession(): Promise<void>;
     private clearSessionInternal;
     restoreSession(): Promise<RestoreResult>;
-    register(params: RegisterParams): Promise<KoolbaseUser>;
+    /**
+     * Create an account.
+     *
+     * Two outcomes, and the caller must tell them apart. With
+     * require_verified_contact off, the account is created and signed in.
+     * With it on, the account is created and NO session is issued — the user
+     * verifies their email before their first sign-in. Both are successes.
+     *
+     * Switch on `status` rather than checking the session for null: the point
+     * of the union is that there is no path where an app reads the user and
+     * assumes it is signed in.
+     */
+    register(params: RegisterParams): Promise<SignUpResult>;
     login(params: LoginParams): Promise<KoolbaseSession>;
     /**
    * Sign in with Apple using a credential obtained from a native Apple
@@ -143,6 +155,27 @@ export declare class KoolbaseAuth {
     logout(): Promise<boolean>;
     forgotPassword(email: string): Promise<void>;
     resetPassword(token: string, password: string): Promise<void>;
+    /**
+     * Complete email verification with a token from a verification link.
+     *
+     * The token comes from wherever your verification URL template pointed —
+     * your own page reads it from the query string and passes it here. Throws
+     * if the token is invalid, expired or already used.
+     */
+    verifyEmail(token: string): Promise<void>;
+    /**
+     * Re-send the verification email to the signed-in but unverified user.
+     *
+     * Safe to call when already verified: nothing is sent and
+     * `alreadyVerified` comes back true. The server throttles this — a short
+     * cooldown between sends and a daily cap — and the refusal arrives as
+     * VerificationResendCooldownError carrying when to retry, or
+     * VerificationResendDailyCapError when the day's allowance is spent.
+     *
+     * Requires a session, since the server verifies the caller rather than
+     * taking an email address — otherwise this would be an open mail relay.
+     */
+    resendVerificationEmail(): Promise<ResendVerificationResult>;
     unlock(token: string): Promise<void>;
     get currentUser(): KoolbaseUser | null;
     get accessToken(): string | null;
@@ -191,6 +224,18 @@ export declare class KoolbaseAuth {
      * affects how a bare 401 (no code, older server) is interpreted.
      */
     private parseSessionResponse;
+    /**
+     * A session, or a refusal — never a session-shaped object with nothing in
+     * it.
+     *
+     * This used to read the fields straight off the body, so a response with no
+     * tokens produced a session whose accessToken was undefined. It persisted,
+     * currentUser returned a user, and every authenticated request went out as
+     * `Bearer undefined` and came back 401 — signed in as far as the app could
+     * tell, and unable to do anything. A user object without tokens is not a
+     * session, and refusing is the only honest answer.
+     */
+    private sessionFromBody;
     private checkResponse;
     /**
      * Map a non-2xx credential/session response to a typed error.

package/dist/cjs/auth.js

@@ -208,6 +208,18 @@ class KoolbaseAuth {
         }
     }
     // ─── Public auth API ────────────────────────────────────────────────────
+    /**
+     * Create an account.
+     *
+     * Two outcomes, and the caller must tell them apart. With
+     * require_verified_contact off, the account is created and signed in.
+     * With it on, the account is created and NO session is issued — the user
+     * verifies their email before their first sign-in. Both are successes.
+     *
+     * Switch on `status` rather than checking the session for null: the point
+     * of the union is that there is no path where an app reads the user and
+     * assumes it is signed in.
+     */
     async register(params) {
         if (params.password.length < 8)
             throw new auth_errors_js_1.WeakPasswordError();
@@ -215,9 +227,25 @@ class KoolbaseAuth {
             method: 'POST',
             body: params,
         });
-        const session = await this.parseSessionResponse(res, false);
+        if (!res.ok)
+            await this.throwTypedError(res); // never returns
+        const data = await res.json();
+        // The server's own discriminator. It sends this deliberately — a 201
+        // meaning "created, not signed in" — and the SDK ignored it until now,
+        // building a session out of a body with no tokens in it.
+        if (data.verification_required === true) {
+            // Nothing is persisted and no listener fires: a pending signup is not
+            // an authentication event, and an existing session on this device
+            // belongs to whoever was already signed in.
+            return {
+                status: 'verification_required',
+                user: this.mapUser(data.user),
+                session: null,
+            };
+        }
+        const session = this.sessionFromBody(data);
         await this.setSessionInternal(session);
-        return session.user;
+        return { status: 'authenticated', user: session.user, session };
     }
     async login(params) {
         const res = await this.authRequest('/v1/sdk/auth/login', {
@@ -324,13 +352,7 @@ class KoolbaseAuth {
      */
     async parseGoogleSessionResponse(res) {
         if (res.status === 200) {
-            const data = await res.json();
-            return {
-                accessToken: data.access_token,
-                refreshToken: data.refresh_token,
-                expiresAt: data.expires_at,
-                user: this.mapUser(data.user),
-            };
+            return this.sessionFromBody(await res.json());
         }
         let body = {};
         try {
@@ -384,13 +406,7 @@ class KoolbaseAuth {
      */
     async parseAppleSessionResponse(res) {
         if (res.status === 200) {
-            const data = await res.json();
-            return {
-                accessToken: data.access_token,
-                refreshToken: data.refresh_token,
-                expiresAt: data.expires_at,
-                user: this.mapUser(data.user),
-            };
+            return this.sessionFromBody(await res.json());
         }
         let body = {};
         try {
@@ -503,6 +519,45 @@ class KoolbaseAuth {
         });
         await this.checkResponse(res);
     }
+    /**
+     * Complete email verification with a token from a verification link.
+     *
+     * The token comes from wherever your verification URL template pointed —
+     * your own page reads it from the query string and passes it here. Throws
+     * if the token is invalid, expired or already used.
+     */
+    async verifyEmail(token) {
+        const res = await this.authRequest('/v1/sdk/auth/verify-email', {
+            method: 'POST',
+            body: { token },
+        });
+        await this.checkResponse(res);
+    }
+    /**
+     * Re-send the verification email to the signed-in but unverified user.
+     *
+     * Safe to call when already verified: nothing is sent and
+     * `alreadyVerified` comes back true. The server throttles this — a short
+     * cooldown between sends and a daily cap — and the refusal arrives as
+     * VerificationResendCooldownError carrying when to retry, or
+     * VerificationResendDailyCapError when the day's allowance is spent.
+     *
+     * Requires a session, since the server verifies the caller rather than
+     * taking an email address — otherwise this would be an open mail relay.
+     */
+    async resendVerificationEmail() {
+        const res = await this.authRequest('/v1/sdk/auth/resend-verification', {
+            method: 'POST',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const body = (await res.json().catch(() => ({})));
+        return {
+            alreadyVerified: body.already_verified ?? false,
+            expiresAt: body.expires_at ? new Date(body.expires_at) : null,
+            cooldownUntil: body.cooldown_until ? new Date(body.cooldown_until) : null,
+        };
+    }
     async unlock(token) {
         const res = await this.authRequest('/v1/sdk/auth/unlock', {
             method: 'POST',
@@ -674,7 +729,24 @@ class KoolbaseAuth {
     async parseSessionResponse(res, isRefresh) {
         if (!res.ok)
             await this.throwTypedError(res, isRefresh); // never returns
-        const data = await res.json();
+        return this.sessionFromBody(await res.json());
+    }
+    /**
+     * A session, or a refusal — never a session-shaped object with nothing in
+     * it.
+     *
+     * This used to read the fields straight off the body, so a response with no
+     * tokens produced a session whose accessToken was undefined. It persisted,
+     * currentUser returned a user, and every authenticated request went out as
+     * `Bearer undefined` and came back 401 — signed in as far as the app could
+     * tell, and unable to do anything. A user object without tokens is not a
+     * session, and refusing is the only honest answer.
+     */
+    sessionFromBody(data) {
+        if (!data?.access_token)
+            throw new auth_errors_js_1.MalformedSessionResponseError('an access token');
+        if (!data?.refresh_token)
+            throw new auth_errors_js_1.MalformedSessionResponseError('a refresh token');
         return {
             accessToken: data.access_token,
             refreshToken: data.refresh_token,
@@ -725,6 +797,10 @@ class KoolbaseAuth {
                 throw new auth_errors_js_1.UnlockTokenInvalidError();
             case 'rate_limit':
                 throw new auth_errors_js_1.RateLimitError(msg || undefined);
+            case 'resend_cooldown':
+                throw new auth_errors_js_1.VerificationResendCooldownError(body.cooldown_until ? new Date(body.cooldown_until) : null, msg || undefined);
+            case 'resend_daily_cap':
+                throw new auth_errors_js_1.VerificationResendDailyCapError(msg || undefined);
         }
         // ─── status fallback (pre-code servers) ───
         if (res.status === 409)

package/dist/cjs/index.d.ts

@@ -18,5 +18,5 @@ export type { RegisterTokenOptions } from './messaging.js';
 export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
-export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
+export type { AuthStateListener, FetchLike, KoolbaseAuthStorage, ResendVerificationResult } from './types.js';
 export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/cjs/types.d.ts

@@ -53,6 +53,48 @@ export interface KoolbaseSession {
  * unavailable), compliant encryption layers, or in-memory test mocks —
  * can implement this interface and inject it via KoolbaseConfig.authStorage.
  */
+/**
+ * What resendVerificationEmail() answers with.
+ *
+ * alreadyVerified is not an error: calling it for a verified account is a
+ * no-op that says so, which is what a "resend" button needs when the user
+ * verified in another tab.
+ *
+ * cooldownUntil is when the next send becomes possible. The server throttles
+ * sends, and a countdown is a better answer to a user than a bare refusal.
+ */
+/**
+ * What register() answers with.
+ *
+ * A discriminated union rather than a nullable session, because registration
+ * succeeding and authentication succeeding are different outcomes and an app
+ * must handle both. A project with require_verified_contact on creates the
+ * account and issues no session — the server returns 201 with
+ * verification_required, deliberately not an error, since reporting failure
+ * for a signup that worked is worse than either alternative.
+ *
+ * Until 10.x this was typed as the user alone, and the SDK built a session
+ * from a response that had no tokens: currentUser returned someone whose
+ * every request went out as `Bearer undefined`. A nullable session would
+ * have let an app read result.user and reproduce that at one remove, so the
+ * status is the only way in.
+ */
+export type SignUpResult = {
+    status: 'authenticated';
+    user: KoolbaseUser;
+    session: KoolbaseSession;
+} | {
+    status: 'verification_required';
+    user: KoolbaseUser;
+    session: null;
+};
+export interface ResendVerificationResult {
+    alreadyVerified: boolean;
+    /** When the link in the email stops working. Null when nothing was sent. */
+    expiresAt: Date | null;
+    /** When another send becomes possible. Null when nothing was sent. */
+    cooldownUntil: Date | null;
+}
 export interface KoolbaseAuthStorage {
     saveSession(session: KoolbaseSession): Promise<void>;
     readSession(): Promise<KoolbaseSession | null>;

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

@@ -64,6 +64,25 @@ export declare class UnlockTokenInvalidError extends KoolbaseAuthError {
 export declare class RateLimitError extends KoolbaseAuthError {
     constructor(message?: string);
 }
+/**
+ * The verification email was refused because one was sent too recently.
+ *
+ * Carries when the next send becomes possible, so an app can show a countdown
+ * rather than a bare refusal — the server sends the timestamp and throwing it
+ * away would waste the only thing that makes this error actionable.
+ */
+export declare class VerificationResendCooldownError extends KoolbaseAuthError {
+    readonly cooldownUntil: Date | null;
+    constructor(cooldownUntil: Date | null, message?: string);
+}
+/**
+ * The day's verification-email allowance is spent. Distinct from the cooldown
+ * because the remedy differs: waiting seconds versus waiting until tomorrow,
+ * and an app should say which.
+ */
+export declare class VerificationResendDailyCapError 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.
@@ -109,6 +128,19 @@ export declare class OAuthEmailConflictError extends KoolbaseAuthError {
 export declare class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
     constructor();
 }
+/**
+ * The server answered a sign-in as though it succeeded, without the tokens a
+ * session needs.
+ *
+ * Distinct from verification_required, which is a legitimate session-less
+ * success the SDK reports through SignUpResult. This is the other case: the
+ * response claims authentication and cannot support it. Inventing a session
+ * from it is what produced a signed-in user whose every request went out as
+ * `Bearer undefined`, so the SDK refuses instead.
+ */
+export declare class MalformedSessionResponseError extends KoolbaseAuthError {
+    constructor(missing: string);
+}
 export declare class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor();
 }

package/dist/esm/auth-errors.js

@@ -107,6 +107,33 @@ export class RateLimitError extends KoolbaseAuthError {
         Object.setPrototypeOf(this, RateLimitError.prototype);
     }
 }
+/**
+ * The verification email was refused because one was sent too recently.
+ *
+ * Carries when the next send becomes possible, so an app can show a countdown
+ * rather than a bare refusal — the server sends the timestamp and throwing it
+ * away would waste the only thing that makes this error actionable.
+ */
+export class VerificationResendCooldownError extends KoolbaseAuthError {
+    constructor(cooldownUntil, message) {
+        super(message ?? 'Please wait before requesting another verification email', 'resend_cooldown');
+        this.cooldownUntil = cooldownUntil;
+        this.name = 'VerificationResendCooldownError';
+        Object.setPrototypeOf(this, VerificationResendCooldownError.prototype);
+    }
+}
+/**
+ * The day's verification-email allowance is spent. Distinct from the cooldown
+ * because the remedy differs: waiting seconds versus waiting until tomorrow,
+ * and an app should say which.
+ */
+export class VerificationResendDailyCapError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Daily verification-email limit reached; try again tomorrow', 'resend_daily_cap');
+        this.name = 'VerificationResendDailyCapError';
+        Object.setPrototypeOf(this, VerificationResendDailyCapError.prototype);
+    }
+}
 // ─── Network ───────────────────────────────────────────────────────────────
 /**
  * Generic network error. The SDK does NOT throw this directly — fetch
@@ -206,6 +233,23 @@ export class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
         Object.setPrototypeOf(this, GoogleSignInNotConfiguredError.prototype);
     }
 }
+/**
+ * The server answered a sign-in as though it succeeded, without the tokens a
+ * session needs.
+ *
+ * Distinct from verification_required, which is a legitimate session-less
+ * success the SDK reports through SignUpResult. This is the other case: the
+ * response claims authentication and cannot support it. Inventing a session
+ * from it is what produced a signed-in user whose every request went out as
+ * `Bearer undefined`, so the SDK refuses instead.
+ */
+export class MalformedSessionResponseError extends KoolbaseAuthError {
+    constructor(missing) {
+        super(`The server returned a session without ${missing}. This is a protocol error, not a credential problem.`, 'malformed_session_response');
+        this.name = 'MalformedSessionResponseError';
+        Object.setPrototypeOf(this, MalformedSessionResponseError.prototype);
+    }
+}
 export class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor() {
         super('Invalid Google identity token', 'invalid_google_token');

package/dist/esm/auth.d.ts

@@ -1,4 +1,4 @@
-import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, SendOtpParams, SignInWithAppleParams, VerifyOtpParams } from './types.js';
+import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, ResendVerificationResult, SendOtpParams, SignUpResult, SignInWithAppleParams, VerifyOtpParams } from './types.js';
 import type { SignInWithGoogleParams } from './types.js';
 export declare class KoolbaseAuth {
     private config;
@@ -72,7 +72,19 @@ export declare class KoolbaseAuth {
     clearStoredSession(): Promise<void>;
     private clearSessionInternal;
     restoreSession(): Promise<RestoreResult>;
-    register(params: RegisterParams): Promise<KoolbaseUser>;
+    /**
+     * Create an account.
+     *
+     * Two outcomes, and the caller must tell them apart. With
+     * require_verified_contact off, the account is created and signed in.
+     * With it on, the account is created and NO session is issued — the user
+     * verifies their email before their first sign-in. Both are successes.
+     *
+     * Switch on `status` rather than checking the session for null: the point
+     * of the union is that there is no path where an app reads the user and
+     * assumes it is signed in.
+     */
+    register(params: RegisterParams): Promise<SignUpResult>;
     login(params: LoginParams): Promise<KoolbaseSession>;
     /**
    * Sign in with Apple using a credential obtained from a native Apple
@@ -143,6 +155,27 @@ export declare class KoolbaseAuth {
     logout(): Promise<boolean>;
     forgotPassword(email: string): Promise<void>;
     resetPassword(token: string, password: string): Promise<void>;
+    /**
+     * Complete email verification with a token from a verification link.
+     *
+     * The token comes from wherever your verification URL template pointed —
+     * your own page reads it from the query string and passes it here. Throws
+     * if the token is invalid, expired or already used.
+     */
+    verifyEmail(token: string): Promise<void>;
+    /**
+     * Re-send the verification email to the signed-in but unverified user.
+     *
+     * Safe to call when already verified: nothing is sent and
+     * `alreadyVerified` comes back true. The server throttles this — a short
+     * cooldown between sends and a daily cap — and the refusal arrives as
+     * VerificationResendCooldownError carrying when to retry, or
+     * VerificationResendDailyCapError when the day's allowance is spent.
+     *
+     * Requires a session, since the server verifies the caller rather than
+     * taking an email address — otherwise this would be an open mail relay.
+     */
+    resendVerificationEmail(): Promise<ResendVerificationResult>;
     unlock(token: string): Promise<void>;
     get currentUser(): KoolbaseUser | null;
     get accessToken(): string | null;
@@ -191,6 +224,18 @@ export declare class KoolbaseAuth {
      * affects how a bare 401 (no code, older server) is interpreted.
      */
     private parseSessionResponse;
+    /**
+     * A session, or a refusal — never a session-shaped object with nothing in
+     * it.
+     *
+     * This used to read the fields straight off the body, so a response with no
+     * tokens produced a session whose accessToken was undefined. It persisted,
+     * currentUser returned a user, and every authenticated request went out as
+     * `Bearer undefined` and came back 401 — signed in as far as the app could
+     * tell, and unable to do anything. A user object without tokens is not a
+     * session, and refusing is the only honest answer.
+     */
+    private sessionFromBody;
     private checkResponse;
     /**
      * Map a non-2xx credential/session response to a typed error.

package/dist/esm/auth.js

@@ -1,5 +1,5 @@
 import { RestoreResult, } from './types.js';
-import { AccountLockedError, EmailAlreadyInUseError, InvalidCredentialsError, InvalidPhoneNumberError, KoolbaseAuthError, OtpExpiredError, OtpInvalidError, OtpMaxAttemptsError, OtpRateLimitError, PhoneAlreadyLinkedError, RateLimitError, SessionExpiredError, SmsConfigMissingError, TokenRevokedError, UnlockTokenInvalidError, UserDisabledError, WeakPasswordError, AppleEmailRequiredError, AppleSignInNotConfiguredError, InvalidAppleTokenError, OAuthEmailConflictError, GoogleEmailRequiredError, GoogleSignInNotConfiguredError, InvalidGoogleTokenError, } from './auth-errors.js';
+import { AccountLockedError, EmailAlreadyInUseError, InvalidCredentialsError, InvalidPhoneNumberError, KoolbaseAuthError, OtpExpiredError, OtpInvalidError, OtpMaxAttemptsError, OtpRateLimitError, PhoneAlreadyLinkedError, MalformedSessionResponseError, RateLimitError, VerificationResendCooldownError, VerificationResendDailyCapError, SessionExpiredError, SmsConfigMissingError, TokenRevokedError, UnlockTokenInvalidError, UserDisabledError, WeakPasswordError, AppleEmailRequiredError, AppleSignInNotConfiguredError, InvalidAppleTokenError, OAuthEmailConflictError, GoogleEmailRequiredError, GoogleSignInNotConfiguredError, InvalidGoogleTokenError, } from './auth-errors.js';
 import { getPlatform } from './platform.js';
 import { DeviceMetadata } from './device-metadata.js';
 export class KoolbaseAuth {
@@ -205,6 +205,18 @@ export class KoolbaseAuth {
         }
     }
     // ─── Public auth API ────────────────────────────────────────────────────
+    /**
+     * Create an account.
+     *
+     * Two outcomes, and the caller must tell them apart. With
+     * require_verified_contact off, the account is created and signed in.
+     * With it on, the account is created and NO session is issued — the user
+     * verifies their email before their first sign-in. Both are successes.
+     *
+     * Switch on `status` rather than checking the session for null: the point
+     * of the union is that there is no path where an app reads the user and
+     * assumes it is signed in.
+     */
     async register(params) {
         if (params.password.length < 8)
             throw new WeakPasswordError();
@@ -212,9 +224,25 @@ export class KoolbaseAuth {
             method: 'POST',
             body: params,
         });
-        const session = await this.parseSessionResponse(res, false);
+        if (!res.ok)
+            await this.throwTypedError(res); // never returns
+        const data = await res.json();
+        // The server's own discriminator. It sends this deliberately — a 201
+        // meaning "created, not signed in" — and the SDK ignored it until now,
+        // building a session out of a body with no tokens in it.
+        if (data.verification_required === true) {
+            // Nothing is persisted and no listener fires: a pending signup is not
+            // an authentication event, and an existing session on this device
+            // belongs to whoever was already signed in.
+            return {
+                status: 'verification_required',
+                user: this.mapUser(data.user),
+                session: null,
+            };
+        }
+        const session = this.sessionFromBody(data);
         await this.setSessionInternal(session);
-        return session.user;
+        return { status: 'authenticated', user: session.user, session };
     }
     async login(params) {
         const res = await this.authRequest('/v1/sdk/auth/login', {
@@ -321,13 +349,7 @@ export class KoolbaseAuth {
      */
     async parseGoogleSessionResponse(res) {
         if (res.status === 200) {
-            const data = await res.json();
-            return {
-                accessToken: data.access_token,
-                refreshToken: data.refresh_token,
-                expiresAt: data.expires_at,
-                user: this.mapUser(data.user),
-            };
+            return this.sessionFromBody(await res.json());
         }
         let body = {};
         try {
@@ -381,13 +403,7 @@ export class KoolbaseAuth {
      */
     async parseAppleSessionResponse(res) {
         if (res.status === 200) {
-            const data = await res.json();
-            return {
-                accessToken: data.access_token,
-                refreshToken: data.refresh_token,
-                expiresAt: data.expires_at,
-                user: this.mapUser(data.user),
-            };
+            return this.sessionFromBody(await res.json());
         }
         let body = {};
         try {
@@ -500,6 +516,45 @@ export class KoolbaseAuth {
         });
         await this.checkResponse(res);
     }
+    /**
+     * Complete email verification with a token from a verification link.
+     *
+     * The token comes from wherever your verification URL template pointed —
+     * your own page reads it from the query string and passes it here. Throws
+     * if the token is invalid, expired or already used.
+     */
+    async verifyEmail(token) {
+        const res = await this.authRequest('/v1/sdk/auth/verify-email', {
+            method: 'POST',
+            body: { token },
+        });
+        await this.checkResponse(res);
+    }
+    /**
+     * Re-send the verification email to the signed-in but unverified user.
+     *
+     * Safe to call when already verified: nothing is sent and
+     * `alreadyVerified` comes back true. The server throttles this — a short
+     * cooldown between sends and a daily cap — and the refusal arrives as
+     * VerificationResendCooldownError carrying when to retry, or
+     * VerificationResendDailyCapError when the day's allowance is spent.
+     *
+     * Requires a session, since the server verifies the caller rather than
+     * taking an email address — otherwise this would be an open mail relay.
+     */
+    async resendVerificationEmail() {
+        const res = await this.authRequest('/v1/sdk/auth/resend-verification', {
+            method: 'POST',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const body = (await res.json().catch(() => ({})));
+        return {
+            alreadyVerified: body.already_verified ?? false,
+            expiresAt: body.expires_at ? new Date(body.expires_at) : null,
+            cooldownUntil: body.cooldown_until ? new Date(body.cooldown_until) : null,
+        };
+    }
     async unlock(token) {
         const res = await this.authRequest('/v1/sdk/auth/unlock', {
             method: 'POST',
@@ -671,7 +726,24 @@ export class KoolbaseAuth {
     async parseSessionResponse(res, isRefresh) {
         if (!res.ok)
             await this.throwTypedError(res, isRefresh); // never returns
-        const data = await res.json();
+        return this.sessionFromBody(await res.json());
+    }
+    /**
+     * A session, or a refusal — never a session-shaped object with nothing in
+     * it.
+     *
+     * This used to read the fields straight off the body, so a response with no
+     * tokens produced a session whose accessToken was undefined. It persisted,
+     * currentUser returned a user, and every authenticated request went out as
+     * `Bearer undefined` and came back 401 — signed in as far as the app could
+     * tell, and unable to do anything. A user object without tokens is not a
+     * session, and refusing is the only honest answer.
+     */
+    sessionFromBody(data) {
+        if (!data?.access_token)
+            throw new MalformedSessionResponseError('an access token');
+        if (!data?.refresh_token)
+            throw new MalformedSessionResponseError('a refresh token');
         return {
             accessToken: data.access_token,
             refreshToken: data.refresh_token,
@@ -722,6 +794,10 @@ export class KoolbaseAuth {
                 throw new UnlockTokenInvalidError();
             case 'rate_limit':
                 throw new RateLimitError(msg || undefined);
+            case 'resend_cooldown':
+                throw new VerificationResendCooldownError(body.cooldown_until ? new Date(body.cooldown_until) : null, msg || undefined);
+            case 'resend_daily_cap':
+                throw new VerificationResendDailyCapError(msg || undefined);
         }
         // ─── status fallback (pre-code servers) ───
         if (res.status === 409)

package/dist/esm/index.d.ts

@@ -18,5 +18,5 @@ export type { RegisterTokenOptions } from './messaging.js';
 export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';
 export { RestoreResult } from './types.js';
-export type { AuthStateListener, FetchLike, KoolbaseAuthStorage } from './types.js';
+export type { AuthStateListener, FetchLike, KoolbaseAuthStorage, ResendVerificationResult } from './types.js';
 export { setPlatform, getPlatform, memoryPlatform, type PlatformAdapter, type PlatformStorage, type PlatformNetwork, type PlatformLifecycle, type PlatformLocks, type PlatformInfo, } from './platform.js';

package/dist/esm/types.d.ts

@@ -53,6 +53,48 @@ export interface KoolbaseSession {
  * unavailable), compliant encryption layers, or in-memory test mocks —
  * can implement this interface and inject it via KoolbaseConfig.authStorage.
  */
+/**
+ * What resendVerificationEmail() answers with.
+ *
+ * alreadyVerified is not an error: calling it for a verified account is a
+ * no-op that says so, which is what a "resend" button needs when the user
+ * verified in another tab.
+ *
+ * cooldownUntil is when the next send becomes possible. The server throttles
+ * sends, and a countdown is a better answer to a user than a bare refusal.
+ */
+/**
+ * What register() answers with.
+ *
+ * A discriminated union rather than a nullable session, because registration
+ * succeeding and authentication succeeding are different outcomes and an app
+ * must handle both. A project with require_verified_contact on creates the
+ * account and issues no session — the server returns 201 with
+ * verification_required, deliberately not an error, since reporting failure
+ * for a signup that worked is worse than either alternative.
+ *
+ * Until 10.x this was typed as the user alone, and the SDK built a session
+ * from a response that had no tokens: currentUser returned someone whose
+ * every request went out as `Bearer undefined`. A nullable session would
+ * have let an app read result.user and reproduce that at one remove, so the
+ * status is the only way in.
+ */
+export type SignUpResult = {
+    status: 'authenticated';
+    user: KoolbaseUser;
+    session: KoolbaseSession;
+} | {
+    status: 'verification_required';
+    user: KoolbaseUser;
+    session: null;
+};
+export interface ResendVerificationResult {
+    alreadyVerified: boolean;
+    /** When the link in the email stops working. Null when nothing was sent. */
+    expiresAt: Date | null;
+    /** When another send becomes possible. Null when nothing was sent. */
+    cooldownUntil: Date | null;
+}
 export interface KoolbaseAuthStorage {
     saveSession(session: KoolbaseSession): Promise<void>;
     readSession(): Promise<KoolbaseSession | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "10.3.0",
+  "version": "11.0.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",