@koolbase/core 10.4.0 → 11.1.0

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

@@ -17,7 +17,13 @@ export declare class UserDisabledError extends KoolbaseAuthError {
     constructor();
 }
 export declare class WeakPasswordError extends KoolbaseAuthError {
-    constructor();
+    /**
+     * The message is optional so the server's own rule can be carried through.
+     * The SDK checks length before sending; a project may require more than
+     * that, and "must be at least 8 characters" would then be wrong as well as
+     * unhelpful.
+     */
+    constructor(message?: string);
 }
 export declare class SessionExpiredError extends KoolbaseAuthError {
     constructor();
@@ -128,6 +134,92 @@ 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.
+ */
+/**
+ * Sign-in refused because the account has not verified its email or phone.
+ *
+ * In a project with require_verified_contact on, this is the most common auth
+ * error there is — the user registered, did not click the link, and came back.
+ * It arrived untyped until 11.1.0, so apps showed "something went wrong" for
+ * the one case with an obvious remedy: offer to resend.
+ */
+export declare class ContactNotVerifiedError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** The project has registration turned off. Not a credential problem. */
+export declare class SignupsDisabledError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * A verification or reset link that has expired.
+ *
+ * Distinct from TokenAlreadyUsedError because the remedy differs: expired
+ * means request another, used means it already worked and they may simply be
+ * clicking an old email.
+ */
+export declare class TokenExpiredError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** A one-shot link clicked twice. Often means it already succeeded. */
+export declare class TokenAlreadyUsedError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * The current password given for a password change was wrong.
+ *
+ * Named for the operation rather than the code: the server calls this
+ * `invalid_password`, which reads like a rejected new password and is not.
+ */
+export declare class CurrentPasswordIncorrectError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * An OAuth sign-in for an email that already has an account by another
+ * method. The remedy is to sign in the original way and connect the provider
+ * afterwards, which the server's message says.
+ */
+export declare class AccountExistsError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** A password attempt against an account that only has Google or Apple. */
+export declare class OAuthOnlyAccountError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** A provider the project has not enabled. */
+export declare class UnsupportedOAuthProviderError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** The call needs a signed-in user and did not have one. */
+export declare class SessionRequiredError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** The caller is authenticated but not permitted to do this. */
+export declare class InsufficientAuthorityError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * Refused because it would remove the account's last way of signing in —
+ * unlinking the only provider, or clearing the only password.
+ */
+export declare class LastCredentialError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** Hiding account existence needs verification on; the project has it off. */
+export declare class HideRequiresVerificationError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+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.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;
+exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.MalformedSessionResponseError = exports.HideRequiresVerificationError = exports.LastCredentialError = exports.InsufficientAuthorityError = exports.SessionRequiredError = exports.UnsupportedOAuthProviderError = exports.OAuthOnlyAccountError = exports.AccountExistsError = exports.CurrentPasswordIncorrectError = exports.TokenAlreadyUsedError = exports.TokenExpiredError = exports.SignupsDisabledError = exports.ContactNotVerifiedError = 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
@@ -41,8 +41,14 @@ class UserDisabledError extends KoolbaseAuthError {
 }
 exports.UserDisabledError = UserDisabledError;
 class WeakPasswordError extends KoolbaseAuthError {
-    constructor() {
-        super('Password must be at least 8 characters', 'weak_password');
+    /**
+     * The message is optional so the server's own rule can be carried through.
+     * The SDK checks length before sending; a project may require more than
+     * that, and "must be at least 8 characters" would then be wrong as well as
+     * unhelpful.
+     */
+    constructor(message) {
+        super(message ?? 'Password must be at least 8 characters', 'weak_password');
         this.name = 'WeakPasswordError';
         Object.setPrototypeOf(this, WeakPasswordError.prototype);
     }
@@ -261,6 +267,157 @@ 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.
+ */
+/**
+ * Sign-in refused because the account has not verified its email or phone.
+ *
+ * In a project with require_verified_contact on, this is the most common auth
+ * error there is — the user registered, did not click the link, and came back.
+ * It arrived untyped until 11.1.0, so apps showed "something went wrong" for
+ * the one case with an obvious remedy: offer to resend.
+ */
+class ContactNotVerifiedError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Verify your email or phone before signing in', 'contact_not_verified');
+        this.name = 'ContactNotVerifiedError';
+        Object.setPrototypeOf(this, ContactNotVerifiedError.prototype);
+    }
+}
+exports.ContactNotVerifiedError = ContactNotVerifiedError;
+/** The project has registration turned off. Not a credential problem. */
+class SignupsDisabledError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Registration is disabled for this project', 'signups_disabled');
+        this.name = 'SignupsDisabledError';
+        Object.setPrototypeOf(this, SignupsDisabledError.prototype);
+    }
+}
+exports.SignupsDisabledError = SignupsDisabledError;
+/**
+ * A verification or reset link that has expired.
+ *
+ * Distinct from TokenAlreadyUsedError because the remedy differs: expired
+ * means request another, used means it already worked and they may simply be
+ * clicking an old email.
+ */
+class TokenExpiredError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This link has expired — request a new one', 'token_expired');
+        this.name = 'TokenExpiredError';
+        Object.setPrototypeOf(this, TokenExpiredError.prototype);
+    }
+}
+exports.TokenExpiredError = TokenExpiredError;
+/** A one-shot link clicked twice. Often means it already succeeded. */
+class TokenAlreadyUsedError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This link has already been used', 'token_used');
+        this.name = 'TokenAlreadyUsedError';
+        Object.setPrototypeOf(this, TokenAlreadyUsedError.prototype);
+    }
+}
+exports.TokenAlreadyUsedError = TokenAlreadyUsedError;
+/**
+ * The current password given for a password change was wrong.
+ *
+ * Named for the operation rather than the code: the server calls this
+ * `invalid_password`, which reads like a rejected new password and is not.
+ */
+class CurrentPasswordIncorrectError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Current password is incorrect', 'invalid_password');
+        this.name = 'CurrentPasswordIncorrectError';
+        Object.setPrototypeOf(this, CurrentPasswordIncorrectError.prototype);
+    }
+}
+exports.CurrentPasswordIncorrectError = CurrentPasswordIncorrectError;
+/**
+ * An OAuth sign-in for an email that already has an account by another
+ * method. The remedy is to sign in the original way and connect the provider
+ * afterwards, which the server's message says.
+ */
+class AccountExistsError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'An account with this email already exists — sign in with your existing method first', 'account_exists');
+        this.name = 'AccountExistsError';
+        Object.setPrototypeOf(this, AccountExistsError.prototype);
+    }
+}
+exports.AccountExistsError = AccountExistsError;
+/** A password attempt against an account that only has Google or Apple. */
+class OAuthOnlyAccountError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This account uses Google or Apple sign-in and has no password', 'oauth_only_account');
+        this.name = 'OAuthOnlyAccountError';
+        Object.setPrototypeOf(this, OAuthOnlyAccountError.prototype);
+    }
+}
+exports.OAuthOnlyAccountError = OAuthOnlyAccountError;
+/** A provider the project has not enabled. */
+class UnsupportedOAuthProviderError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'That sign-in provider is not supported', 'unsupported_oauth_provider');
+        this.name = 'UnsupportedOAuthProviderError';
+        Object.setPrototypeOf(this, UnsupportedOAuthProviderError.prototype);
+    }
+}
+exports.UnsupportedOAuthProviderError = UnsupportedOAuthProviderError;
+/** The call needs a signed-in user and did not have one. */
+class SessionRequiredError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This action requires a signed-in user', 'session_required');
+        this.name = 'SessionRequiredError';
+        Object.setPrototypeOf(this, SessionRequiredError.prototype);
+    }
+}
+exports.SessionRequiredError = SessionRequiredError;
+/** The caller is authenticated but not permitted to do this. */
+class InsufficientAuthorityError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'You do not have permission to do that', 'insufficient_authority');
+        this.name = 'InsufficientAuthorityError';
+        Object.setPrototypeOf(this, InsufficientAuthorityError.prototype);
+    }
+}
+exports.InsufficientAuthorityError = InsufficientAuthorityError;
+/**
+ * Refused because it would remove the account's last way of signing in —
+ * unlinking the only provider, or clearing the only password.
+ */
+class LastCredentialError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This is the account\'s only sign-in method and cannot be removed', 'last_credential');
+        this.name = 'LastCredentialError';
+        Object.setPrototypeOf(this, LastCredentialError.prototype);
+    }
+}
+exports.LastCredentialError = LastCredentialError;
+/** Hiding account existence needs verification on; the project has it off. */
+class HideRequiresVerificationError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Hiding account existence requires verified contact to be enabled', 'hide_requires_verification');
+        this.name = 'HideRequiresVerificationError';
+        Object.setPrototypeOf(this, HideRequiresVerificationError.prototype);
+    }
+}
+exports.HideRequiresVerificationError = HideRequiresVerificationError;
+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, ResendVerificationResult, 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
@@ -212,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 {
@@ -713,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,
@@ -764,6 +797,49 @@ class KoolbaseAuth {
                 throw new auth_errors_js_1.UnlockTokenInvalidError();
             case 'rate_limit':
                 throw new auth_errors_js_1.RateLimitError(msg || undefined);
+            // Verification state. Two codes, one situation — projectauth and the
+            // dashboard's auth package name it differently and an app should not
+            // have to know which spoke.
+            // Verification state. Two codes, one situation — projectauth and the
+            // dashboard's auth package name it differently and an app should not
+            // have to know which spoke.
+            case 'contact_not_verified':
+            case 'email_not_verified':
+                throw new auth_errors_js_1.ContactNotVerifiedError(msg || undefined);
+            // Registration
+            case 'signups_disabled':
+                throw new auth_errors_js_1.SignupsDisabledError(msg || undefined);
+            case 'weak_password':
+                // The class existed and was only ever thrown client-side for length.
+                // The server has its own rules, and a password that passes ours and
+                // fails theirs deserves the same error, not a generic one.
+                throw new auth_errors_js_1.WeakPasswordError(msg || undefined);
+            case 'account_exists':
+                throw new auth_errors_js_1.AccountExistsError(msg || undefined);
+            // Link tokens — verification and password reset
+            case 'token_expired':
+                throw new auth_errors_js_1.TokenExpiredError(msg || undefined);
+            case 'token_used':
+                throw new auth_errors_js_1.TokenAlreadyUsedError(msg || undefined);
+            case 'invalid_token':
+                throw new auth_errors_js_1.UnlockTokenInvalidError();
+            // Password change
+            case 'invalid_password':
+                throw new auth_errors_js_1.CurrentPasswordIncorrectError(msg || undefined);
+            // OAuth
+            case 'oauth_only_account':
+                throw new auth_errors_js_1.OAuthOnlyAccountError(msg || undefined);
+            case 'unsupported_oauth_provider':
+                throw new auth_errors_js_1.UnsupportedOAuthProviderError(msg || undefined);
+            // Authority
+            case 'session_required':
+                throw new auth_errors_js_1.SessionRequiredError(msg || undefined);
+            case 'insufficient_authority':
+                throw new auth_errors_js_1.InsufficientAuthorityError(msg || undefined);
+            case 'last_credential':
+                throw new auth_errors_js_1.LastCredentialError(msg || undefined);
+            case 'hide_requires_verification':
+                throw new auth_errors_js_1.HideRequiresVerificationError(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':

package/dist/cjs/types.d.ts

@@ -63,6 +63,31 @@ export interface KoolbaseSession {
  * 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. */

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

@@ -17,7 +17,13 @@ export declare class UserDisabledError extends KoolbaseAuthError {
     constructor();
 }
 export declare class WeakPasswordError extends KoolbaseAuthError {
-    constructor();
+    /**
+     * The message is optional so the server's own rule can be carried through.
+     * The SDK checks length before sending; a project may require more than
+     * that, and "must be at least 8 characters" would then be wrong as well as
+     * unhelpful.
+     */
+    constructor(message?: string);
 }
 export declare class SessionExpiredError extends KoolbaseAuthError {
     constructor();
@@ -128,6 +134,92 @@ 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.
+ */
+/**
+ * Sign-in refused because the account has not verified its email or phone.
+ *
+ * In a project with require_verified_contact on, this is the most common auth
+ * error there is — the user registered, did not click the link, and came back.
+ * It arrived untyped until 11.1.0, so apps showed "something went wrong" for
+ * the one case with an obvious remedy: offer to resend.
+ */
+export declare class ContactNotVerifiedError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** The project has registration turned off. Not a credential problem. */
+export declare class SignupsDisabledError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * A verification or reset link that has expired.
+ *
+ * Distinct from TokenAlreadyUsedError because the remedy differs: expired
+ * means request another, used means it already worked and they may simply be
+ * clicking an old email.
+ */
+export declare class TokenExpiredError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** A one-shot link clicked twice. Often means it already succeeded. */
+export declare class TokenAlreadyUsedError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * The current password given for a password change was wrong.
+ *
+ * Named for the operation rather than the code: the server calls this
+ * `invalid_password`, which reads like a rejected new password and is not.
+ */
+export declare class CurrentPasswordIncorrectError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * An OAuth sign-in for an email that already has an account by another
+ * method. The remedy is to sign in the original way and connect the provider
+ * afterwards, which the server's message says.
+ */
+export declare class AccountExistsError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** A password attempt against an account that only has Google or Apple. */
+export declare class OAuthOnlyAccountError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** A provider the project has not enabled. */
+export declare class UnsupportedOAuthProviderError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** The call needs a signed-in user and did not have one. */
+export declare class SessionRequiredError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** The caller is authenticated but not permitted to do this. */
+export declare class InsufficientAuthorityError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * Refused because it would remove the account's last way of signing in —
+ * unlinking the only provider, or clearing the only password.
+ */
+export declare class LastCredentialError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/** Hiding account existence needs verification on; the project has it off. */
+export declare class HideRequiresVerificationError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+export declare class MalformedSessionResponseError extends KoolbaseAuthError {
+    constructor(missing: string);
+}
 export declare class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor();
 }

package/dist/esm/auth-errors.js

@@ -34,8 +34,14 @@ export class UserDisabledError extends KoolbaseAuthError {
     }
 }
 export class WeakPasswordError extends KoolbaseAuthError {
-    constructor() {
-        super('Password must be at least 8 characters', 'weak_password');
+    /**
+     * The message is optional so the server's own rule can be carried through.
+     * The SDK checks length before sending; a project may require more than
+     * that, and "must be at least 8 characters" would then be wrong as well as
+     * unhelpful.
+     */
+    constructor(message) {
+        super(message ?? 'Password must be at least 8 characters', 'weak_password');
         this.name = 'WeakPasswordError';
         Object.setPrototypeOf(this, WeakPasswordError.prototype);
     }
@@ -233,6 +239,144 @@ 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.
+ */
+/**
+ * Sign-in refused because the account has not verified its email or phone.
+ *
+ * In a project with require_verified_contact on, this is the most common auth
+ * error there is — the user registered, did not click the link, and came back.
+ * It arrived untyped until 11.1.0, so apps showed "something went wrong" for
+ * the one case with an obvious remedy: offer to resend.
+ */
+export class ContactNotVerifiedError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Verify your email or phone before signing in', 'contact_not_verified');
+        this.name = 'ContactNotVerifiedError';
+        Object.setPrototypeOf(this, ContactNotVerifiedError.prototype);
+    }
+}
+/** The project has registration turned off. Not a credential problem. */
+export class SignupsDisabledError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Registration is disabled for this project', 'signups_disabled');
+        this.name = 'SignupsDisabledError';
+        Object.setPrototypeOf(this, SignupsDisabledError.prototype);
+    }
+}
+/**
+ * A verification or reset link that has expired.
+ *
+ * Distinct from TokenAlreadyUsedError because the remedy differs: expired
+ * means request another, used means it already worked and they may simply be
+ * clicking an old email.
+ */
+export class TokenExpiredError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This link has expired — request a new one', 'token_expired');
+        this.name = 'TokenExpiredError';
+        Object.setPrototypeOf(this, TokenExpiredError.prototype);
+    }
+}
+/** A one-shot link clicked twice. Often means it already succeeded. */
+export class TokenAlreadyUsedError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This link has already been used', 'token_used');
+        this.name = 'TokenAlreadyUsedError';
+        Object.setPrototypeOf(this, TokenAlreadyUsedError.prototype);
+    }
+}
+/**
+ * The current password given for a password change was wrong.
+ *
+ * Named for the operation rather than the code: the server calls this
+ * `invalid_password`, which reads like a rejected new password and is not.
+ */
+export class CurrentPasswordIncorrectError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Current password is incorrect', 'invalid_password');
+        this.name = 'CurrentPasswordIncorrectError';
+        Object.setPrototypeOf(this, CurrentPasswordIncorrectError.prototype);
+    }
+}
+/**
+ * An OAuth sign-in for an email that already has an account by another
+ * method. The remedy is to sign in the original way and connect the provider
+ * afterwards, which the server's message says.
+ */
+export class AccountExistsError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'An account with this email already exists — sign in with your existing method first', 'account_exists');
+        this.name = 'AccountExistsError';
+        Object.setPrototypeOf(this, AccountExistsError.prototype);
+    }
+}
+/** A password attempt against an account that only has Google or Apple. */
+export class OAuthOnlyAccountError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This account uses Google or Apple sign-in and has no password', 'oauth_only_account');
+        this.name = 'OAuthOnlyAccountError';
+        Object.setPrototypeOf(this, OAuthOnlyAccountError.prototype);
+    }
+}
+/** A provider the project has not enabled. */
+export class UnsupportedOAuthProviderError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'That sign-in provider is not supported', 'unsupported_oauth_provider');
+        this.name = 'UnsupportedOAuthProviderError';
+        Object.setPrototypeOf(this, UnsupportedOAuthProviderError.prototype);
+    }
+}
+/** The call needs a signed-in user and did not have one. */
+export class SessionRequiredError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This action requires a signed-in user', 'session_required');
+        this.name = 'SessionRequiredError';
+        Object.setPrototypeOf(this, SessionRequiredError.prototype);
+    }
+}
+/** The caller is authenticated but not permitted to do this. */
+export class InsufficientAuthorityError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'You do not have permission to do that', 'insufficient_authority');
+        this.name = 'InsufficientAuthorityError';
+        Object.setPrototypeOf(this, InsufficientAuthorityError.prototype);
+    }
+}
+/**
+ * Refused because it would remove the account's last way of signing in —
+ * unlinking the only provider, or clearing the only password.
+ */
+export class LastCredentialError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'This is the account\'s only sign-in method and cannot be removed', 'last_credential');
+        this.name = 'LastCredentialError';
+        Object.setPrototypeOf(this, LastCredentialError.prototype);
+    }
+}
+/** Hiding account existence needs verification on; the project has it off. */
+export class HideRequiresVerificationError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Hiding account existence requires verified contact to be enabled', 'hide_requires_verification');
+        this.name = 'HideRequiresVerificationError';
+        Object.setPrototypeOf(this, HideRequiresVerificationError.prototype);
+    }
+}
+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, ResendVerificationResult, 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
@@ -212,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, VerificationResendCooldownError, VerificationResendDailyCapError, 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, AccountExistsError, ContactNotVerifiedError, CurrentPasswordIncorrectError, HideRequiresVerificationError, InsufficientAuthorityError, LastCredentialError, OAuthOnlyAccountError, SessionRequiredError, SignupsDisabledError, TokenAlreadyUsedError, TokenExpiredError, UnsupportedOAuthProviderError, 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 {
@@ -710,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,
@@ -761,6 +794,49 @@ export class KoolbaseAuth {
                 throw new UnlockTokenInvalidError();
             case 'rate_limit':
                 throw new RateLimitError(msg || undefined);
+            // Verification state. Two codes, one situation — projectauth and the
+            // dashboard's auth package name it differently and an app should not
+            // have to know which spoke.
+            // Verification state. Two codes, one situation — projectauth and the
+            // dashboard's auth package name it differently and an app should not
+            // have to know which spoke.
+            case 'contact_not_verified':
+            case 'email_not_verified':
+                throw new ContactNotVerifiedError(msg || undefined);
+            // Registration
+            case 'signups_disabled':
+                throw new SignupsDisabledError(msg || undefined);
+            case 'weak_password':
+                // The class existed and was only ever thrown client-side for length.
+                // The server has its own rules, and a password that passes ours and
+                // fails theirs deserves the same error, not a generic one.
+                throw new WeakPasswordError(msg || undefined);
+            case 'account_exists':
+                throw new AccountExistsError(msg || undefined);
+            // Link tokens — verification and password reset
+            case 'token_expired':
+                throw new TokenExpiredError(msg || undefined);
+            case 'token_used':
+                throw new TokenAlreadyUsedError(msg || undefined);
+            case 'invalid_token':
+                throw new UnlockTokenInvalidError();
+            // Password change
+            case 'invalid_password':
+                throw new CurrentPasswordIncorrectError(msg || undefined);
+            // OAuth
+            case 'oauth_only_account':
+                throw new OAuthOnlyAccountError(msg || undefined);
+            case 'unsupported_oauth_provider':
+                throw new UnsupportedOAuthProviderError(msg || undefined);
+            // Authority
+            case 'session_required':
+                throw new SessionRequiredError(msg || undefined);
+            case 'insufficient_authority':
+                throw new InsufficientAuthorityError(msg || undefined);
+            case 'last_credential':
+                throw new LastCredentialError(msg || undefined);
+            case 'hide_requires_verification':
+                throw new HideRequiresVerificationError(msg || undefined);
             case 'resend_cooldown':
                 throw new VerificationResendCooldownError(body.cooldown_until ? new Date(body.cooldown_until) : null, msg || undefined);
             case 'resend_daily_cap':

package/dist/esm/types.d.ts

@@ -63,6 +63,31 @@ export interface KoolbaseSession {
  * 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "10.4.0",
+  "version": "11.1.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",