@koolbase/core 10.4.0 → 11.0.0

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

@@ -128,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.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.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
@@ -261,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, 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,

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

@@ -128,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

@@ -233,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, 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, 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,

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.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",