@koolbase/core 11.4.0 → 12.1.0

package/dist/cjs/aggregate.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Asking "how many" and "how much" over a collection, correctly.
+ *
+ * Correct means the whole authorized set — never the first page — with the
+ * caller's read rule applied inside the query, and never a bare number:
+ * collections are schemaless, so a total that quietly excluded three
+ * malformed rows would be a wrong number that looks right. Every result
+ * carries its accounting.
+ *
+ * ```ts
+ * const r = await Koolbase.db.aggregate({
+ *   collection: 'orders',
+ *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+ *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+ * });
+ *
+ * for (const g of r.groups) {
+ *   console.log(g.category, g.values.revenue);
+ * }
+ * if (r.accounting.revenue.skipped > 0) {
+ *   // some orders had a total that was not a number — say so
+ * }
+ * ```
+ */
+/** A record filter, AND-ed on top of the read rule. */
+export interface KoolbaseAggregateFilter {
+    field: string;
+    op: 'eq' | 'neq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte';
+    value: unknown;
+}
+/**
+ * The category axis: a field's value, or a calendar bucket of a timestamp
+ * field.
+ *
+ * A bucket REQUIRES a timezone, and the union makes omitting it a type
+ * error. "Midnight" means nothing without one — Africa/Accra and UTC
+ * disagree about which day a 23:30 sale belongs to — and the API refuses a
+ * bucket that arrives without one.
+ */
+export type KoolbaseGroupBy = {
+    field: string;
+    bucket?: never;
+    timezone?: never;
+} | {
+    field: string;
+    bucket: 'day' | 'week' | 'month' | 'year';
+    timezone: string;
+};
+/**
+ * One number per group.
+ *
+ * `count` counts RECORDS, so it takes no field and skips nothing. The others
+ * read a field, and a record whose value is missing or not a number is
+ * skipped and reported in the result's accounting.
+ */
+export type KoolbaseMeasure = {
+    aggregate: 'count';
+    field?: never;
+    as: string;
+} | {
+    aggregate: 'sum' | 'avg' | 'min' | 'max';
+    field: string;
+    as: string;
+};
+/** One aggregation request. */
+export interface KoolbaseAggregateRequest {
+    collection: string;
+    /** AND-ed record filters on top of the read rule. */
+    where?: KoolbaseAggregateFilter[];
+    /** Absent means one group: the measures over everything. */
+    groupBy?: KoolbaseGroupBy;
+    /** At least one. */
+    measures: KoolbaseMeasure[];
+}
+/** One category and its numbers. */
+export interface KoolbaseAggregateGroup {
+    /** Empty string for the single group when there was no groupBy. */
+    category: string;
+    /** Keyed by each measure's `as`. Null where a group had nothing to measure. */
+    values: Record<string, number | null>;
+}
+/**
+ * How a measure arrived at its number.
+ *
+ * `skipped` is not an error. It is what you need to decide whether the
+ * number means what it appears to mean — a revenue total over 900 of 903
+ * orders is a different fact from one over all of them, and only this says
+ * which you are looking at.
+ */
+export interface KoolbaseAggregateAccounting {
+    counted: number;
+    skipped: number;
+    /** Present when skipped > 0. */
+    skippedReason?: 'missing' | 'not_numeric' | 'mixed';
+}
+/** The whole answer, including what could not be counted. */
+export interface KoolbaseAggregateResult {
+    /**
+     * One per category, sorted — or exactly one with an empty category when
+     * there was no groupBy.
+     */
+    groups: KoolbaseAggregateGroup[];
+    /** Records that matched the read rule and filters: the denominator. */
+    matched: number;
+    /** Per measure name, keyed by its `as`. */
+    accounting: Record<string, KoolbaseAggregateAccounting>;
+    /**
+     * True when the groupBy produced more categories than allowed and the
+     * whole request was refused.
+     *
+     * `groups` is EMPTY when this is set: a partial set drawn as the whole
+     * would be exactly the wrong number this API exists to prevent.
+     */
+    tooManyGroups: boolean;
+}

package/dist/cjs/aggregate.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Asking "how many" and "how much" over a collection, correctly.
+ *
+ * Correct means the whole authorized set — never the first page — with the
+ * caller's read rule applied inside the query, and never a bare number:
+ * collections are schemaless, so a total that quietly excluded three
+ * malformed rows would be a wrong number that looks right. Every result
+ * carries its accounting.
+ *
+ * ```ts
+ * const r = await Koolbase.db.aggregate({
+ *   collection: 'orders',
+ *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+ *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+ * });
+ *
+ * for (const g of r.groups) {
+ *   console.log(g.category, g.values.revenue);
+ * }
+ * if (r.accounting.revenue.skipped > 0) {
+ *   // some orders had a total that was not a number — say so
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -101,6 +101,14 @@ export declare class NetworkError extends KoolbaseAuthError {
 export declare class InvalidPhoneNumberError extends KoolbaseAuthError {
     constructor();
 }
+/**
+ * The project has switched off signing in with an emailed code — 403
+ * `email_code_disabled`. Applies to every address alike, so it reveals
+ * nothing about which accounts exist.
+ */
+export declare class EmailCodeDisabledError extends KoolbaseAuthError {
+    constructor();
+}
 export declare class OtpExpiredError 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.MalformedSessionResponseError = exports.ProviderIdentityAlreadyLinkedError = exports.IdentityNotFoundError = exports.InsufficientScopeError = 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;
+exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.MalformedSessionResponseError = exports.ProviderIdentityAlreadyLinkedError = exports.IdentityNotFoundError = exports.InsufficientScopeError = 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.EmailCodeDisabledError = 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
@@ -26,7 +26,7 @@ class InvalidCredentialsError extends KoolbaseAuthError {
 exports.InvalidCredentialsError = InvalidCredentialsError;
 class EmailAlreadyInUseError extends KoolbaseAuthError {
     constructor() {
-        super('Email is already in use', 'email_taken');
+        super('Email is already in use', 'email_in_use');
         this.name = 'EmailAlreadyInUseError';
         Object.setPrototypeOf(this, EmailAlreadyInUseError.prototype);
     }
@@ -34,7 +34,7 @@ class EmailAlreadyInUseError extends KoolbaseAuthError {
 exports.EmailAlreadyInUseError = EmailAlreadyInUseError;
 class UserDisabledError extends KoolbaseAuthError {
     constructor() {
-        super('This account has been disabled', 'user_disabled');
+        super('This account has been disabled', 'account_disabled');
         this.name = 'UserDisabledError';
         Object.setPrototypeOf(this, UserDisabledError.prototype);
     }
@@ -57,7 +57,7 @@ exports.WeakPasswordError = WeakPasswordError;
 // ─── Session lifecycle ─────────────────────────────────────────────────────
 class SessionExpiredError extends KoolbaseAuthError {
     constructor() {
-        super('Session expired, please log in again', 'session_expired');
+        super('Session expired, please log in again', 'invalid_refresh_token');
         this.name = 'SessionExpiredError';
         Object.setPrototypeOf(this, SessionExpiredError.prototype);
     }
@@ -106,7 +106,7 @@ exports.AccountLockedError = AccountLockedError;
  */
 class UnlockTokenInvalidError extends KoolbaseAuthError {
     constructor() {
-        super('Unlock link is invalid or has expired', 'unlock_token_invalid');
+        super('Unlock link is invalid or has expired', 'invalid_unlock_token');
         this.name = 'UnlockTokenInvalidError';
         Object.setPrototypeOf(this, UnlockTokenInvalidError.prototype);
     }
@@ -179,6 +179,19 @@ class InvalidPhoneNumberError extends KoolbaseAuthError {
     }
 }
 exports.InvalidPhoneNumberError = InvalidPhoneNumberError;
+/**
+ * The project has switched off signing in with an emailed code — 403
+ * `email_code_disabled`. Applies to every address alike, so it reveals
+ * nothing about which accounts exist.
+ */
+class EmailCodeDisabledError extends KoolbaseAuthError {
+    constructor() {
+        super('Signing in with an emailed code is switched off for this project', 'email_code_disabled');
+        this.name = 'EmailCodeDisabledError';
+        Object.setPrototypeOf(this, EmailCodeDisabledError.prototype);
+    }
+}
+exports.EmailCodeDisabledError = EmailCodeDisabledError;
 class OtpExpiredError extends KoolbaseAuthError {
     constructor() {
         super('OTP has expired, please request a new code', 'otp_expired');
@@ -205,7 +218,7 @@ class OtpMaxAttemptsError extends KoolbaseAuthError {
 exports.OtpMaxAttemptsError = OtpMaxAttemptsError;
 class OtpRateLimitError extends KoolbaseAuthError {
     constructor() {
-        super('Too many OTP requests, please wait before trying again', 'otp_rate_limit');
+        super('Too many OTP requests, please wait before trying again', 'rate_limit');
         this.name = 'OtpRateLimitError';
         Object.setPrototypeOf(this, OtpRateLimitError.prototype);
     }
@@ -213,7 +226,7 @@ class OtpRateLimitError extends KoolbaseAuthError {
 exports.OtpRateLimitError = OtpRateLimitError;
 class PhoneAlreadyLinkedError extends KoolbaseAuthError {
     constructor() {
-        super('Phone number is already associated with another account', 'phone_taken');
+        super('Phone number is already associated with another account', 'phone_in_use');
         this.name = 'PhoneAlreadyLinkedError';
         Object.setPrototypeOf(this, PhoneAlreadyLinkedError.prototype);
     }
@@ -221,7 +234,7 @@ class PhoneAlreadyLinkedError extends KoolbaseAuthError {
 exports.PhoneAlreadyLinkedError = PhoneAlreadyLinkedError;
 class SmsConfigMissingError extends KoolbaseAuthError {
     constructor() {
-        super('SMS provider not configured for this project', 'sms_config_missing');
+        super('SMS provider not configured for this project', 'sms_not_configured');
         this.name = 'SmsConfigMissingError';
         Object.setPrototypeOf(this, SmsConfigMissingError.prototype);
     }
@@ -229,7 +242,7 @@ class SmsConfigMissingError extends KoolbaseAuthError {
 exports.SmsConfigMissingError = SmsConfigMissingError;
 class AppleSignInNotConfiguredError extends KoolbaseAuthError {
     constructor() {
-        super('Apple Sign-In is not configured for this environment', 'apple_not_configured');
+        super('Apple Sign-In is not configured for this environment', 'oauth_not_configured');
         this.name = 'AppleSignInNotConfiguredError';
         Object.setPrototypeOf(this, AppleSignInNotConfiguredError.prototype);
     }
@@ -237,7 +250,7 @@ class AppleSignInNotConfiguredError extends KoolbaseAuthError {
 exports.AppleSignInNotConfiguredError = AppleSignInNotConfiguredError;
 class InvalidAppleTokenError extends KoolbaseAuthError {
     constructor() {
-        super('Invalid Apple identity token', 'invalid_apple_token');
+        super('Invalid Apple identity token', 'invalid_oauth_token');
         this.name = 'InvalidAppleTokenError';
         Object.setPrototypeOf(this, InvalidAppleTokenError.prototype);
     }
@@ -245,7 +258,7 @@ class InvalidAppleTokenError extends KoolbaseAuthError {
 exports.InvalidAppleTokenError = InvalidAppleTokenError;
 class AppleEmailRequiredError extends KoolbaseAuthError {
     constructor() {
-        super('Apple did not return email for this sign-in. Revoke this app in iOS Settings → Apple ID and retry.', 'apple_email_required');
+        super('Apple did not return email for this sign-in. Revoke this app in iOS Settings → Apple ID and retry.', 'oauth_email_required');
         this.name = 'AppleEmailRequiredError';
         Object.setPrototypeOf(this, AppleEmailRequiredError.prototype);
     }
@@ -261,7 +274,7 @@ class OAuthEmailConflictError extends KoolbaseAuthError {
 exports.OAuthEmailConflictError = OAuthEmailConflictError;
 class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
     constructor() {
-        super('Google Sign-In is not configured for this environment', 'google_not_configured');
+        super('Google Sign-In is not configured for this environment', 'oauth_not_configured');
         this.name = 'GoogleSignInNotConfiguredError';
         Object.setPrototypeOf(this, GoogleSignInNotConfiguredError.prototype);
     }
@@ -458,7 +471,7 @@ class MalformedSessionResponseError extends KoolbaseAuthError {
 exports.MalformedSessionResponseError = MalformedSessionResponseError;
 class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor() {
-        super('Invalid Google identity token', 'invalid_google_token');
+        super('Invalid Google identity token', 'invalid_oauth_token');
         this.name = 'InvalidGoogleTokenError';
         Object.setPrototypeOf(this, InvalidGoogleTokenError.prototype);
     }
@@ -466,7 +479,7 @@ class InvalidGoogleTokenError extends KoolbaseAuthError {
 exports.InvalidGoogleTokenError = InvalidGoogleTokenError;
 class GoogleEmailRequiredError extends KoolbaseAuthError {
     constructor() {
-        super('Google did not return email for this sign-in. Ensure the email scope is requested in the native flow.', 'google_email_required');
+        super('Google did not return email for this sign-in. Ensure the email scope is requested in the native flow.', 'oauth_email_required');
         this.name = 'GoogleEmailRequiredError';
         Object.setPrototypeOf(this, GoogleEmailRequiredError.prototype);
     }

package/dist/cjs/auth.d.ts

@@ -1,4 +1,4 @@
-import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, ResendVerificationResult, SendOtpParams, SignUpResult, SignInWithAppleParams, VerifyOtpParams } from './types.js';
+import { AuthStateListener, KoolbaseConfig, KoolbaseSession, KoolbaseUser, LinkPhoneParams, LoginParams, OtpSendResult, PhoneVerifyResult, RegisterParams, RestoreResult, KoolbaseAuditPage, KoolbaseSessionInfo, ResendVerificationResult, SendOtpParams, SignUpResult, SignInWithAppleParams, VerifyOtpParams } from './types.js';
 import type { SignInWithGoogleParams } from './types.js';
 export declare class KoolbaseAuth {
     private config;
@@ -55,6 +55,18 @@ export declare class KoolbaseAuth {
      * delegates to {@link authRequest} with includeAuth=true.
      */
     private authedRequest;
+    /**
+     * Replace the user inside the current session and persist it.
+     *
+     * A profile update or a fresh fetch changes the user, not the tokens.
+     * Without this the new values live only in the returned object: the cached
+     * `currentUser` stays stale, anything bound to `onAuthStateChange` never
+     * hears about the change, and a reload restores the old name.
+     *
+     * No session means nobody is signed in, and there is nothing to update —
+     * the caller's own request would have failed first.
+     */
+    private updateUserAndPersist;
     private setSessionInternal;
     /**
      * Discards the stored session without contacting the server.
@@ -191,6 +203,92 @@ export declare class KoolbaseAuth {
      * taking an email address — otherwise this would be an open mail relay.
      */
     resendVerificationEmail(): Promise<ResendVerificationResult>;
+    /**
+     * The signed-in user, fetched fresh from the server.
+     *
+     * `currentUser` returns what was cached at sign-in; this asks. Use it when
+     * something may have changed the user server-side — a verification
+     * completing, a profile updated from another device — and persist the
+     * result so the cached copy stops being stale.
+     */
+    getCurrentUser(): Promise<KoolbaseUser>;
+    /**
+     * Update the signed-in user's profile.
+     *
+     * Only the fields given are sent, so passing one leaves the other
+     * untouched. The updated user is persisted, so `currentUser` reflects it
+     * without a refetch.
+     */
+    updateProfile(params: {
+        fullName?: string;
+        avatarUrl?: string;
+    }): Promise<KoolbaseUser>;
+    /**
+     * Change the signed-in user's password.
+     *
+     * The current password is required: a stolen session should not be enough
+     * to lock the real owner out. A wrong one throws
+     * CurrentPasswordIncorrectError — the server returns `invalid_password`,
+     * which reads like a rejected new password and means the opposite.
+     *
+     * An account that signed up through Google or Apple has no password to
+     * change and gets the same error, deliberately, so a caller cannot probe
+     * which sign-in methods an account has.
+     */
+    changePassword(params: {
+        currentPassword: string;
+        newPassword: string;
+    }): Promise<void>;
+    /**
+     * Delete the signed-in user's account, and sign out.
+     *
+     * Deletes the caller only — there is no user id to pass, which is the
+     * security property. The server removes the auth record and every session
+     * on every device, then fires an `auth.user.deleted` trigger.
+     *
+     * It does NOT delete the account's records in your collections. Koolbase
+     * cannot know whether a row should be deleted, anonymised, or kept for a
+     * statutory retention period. Subscribe a Function to `auth.user.deleted`
+     * and clean up there — it runs server-side, so a tab closing mid-flow
+     * cannot strand anything.
+     */
+    deleteAccount(): Promise<void>;
+    /**
+     * Every session the signed-in user has — a "where you're signed in" list.
+     *
+     * Newest first is not guaranteed; sort by createdAt if the order matters.
+     * The entry with `isCurrent` is this device.
+     */
+    listSessions(): Promise<KoolbaseSessionInfo[]>;
+    /**
+     * Sign out one session by id.
+     *
+     * Revoking the current one ends this session too — the server does not
+     * refuse it, and the local session is cleared here so the app does not keep
+     * a token the server has dropped. Use logout() when that is what you mean.
+     */
+    revokeSession(sessionId: string): Promise<void>;
+    /**
+     * Sign out every OTHER session, keeping this one.
+     *
+     * What "sign out my other devices" means after a lost phone. Returns how
+     * many were ended, so an app can say so rather than guess.
+     */
+    revokeAllOtherSessions(): Promise<number>;
+    /**
+     * What has happened to this account — sign-ins, failures, lockouts,
+     * password changes.
+     *
+     * For a "recent security activity" screen. The server sanitizes each
+     * event, so this carries what that event type is allowed to say and
+     * nothing more.
+     *
+     * @param limit up to 200; the server caps it there.
+     */
+    auditLog(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<KoolbaseAuditPage>;
     unlock(token: string): Promise<void>;
     get currentUser(): KoolbaseUser | null;
     get accessToken(): string | null;
@@ -204,12 +302,10 @@ export declare class KoolbaseAuth {
     validAccessToken(): Promise<string | null>;
     setSession(session: KoolbaseSession | null): Promise<void>;
     /**
-     * @deprecated v1.9.0: Server endpoint /v1/sdk/auth/oauth not yet
-     * shipped. This method previously routed to /v1/auth/oauth (dashboard
-     * developer OAuth) which never created project-scoped end-user
-     * sessions. Properly implemented in v1.10.0 with provider-specific
-     * server endpoints under /v1/sdk/auth/oauth/{apple,google,github}.
-     * Use email/password sign-in for now.
+     * @deprecated Never implemented; kept only so existing code compiles.
+     * Google and Apple sign-in are supported — use signInWithGoogle() or
+     * signInWithApple(). This used to say OAuth was not yet shipped and to
+     * use email and password instead, which stopped being true long ago.
      *
      * @throws Always throws KoolbaseAuthError('not_implemented').
      */
@@ -220,6 +316,33 @@ export declare class KoolbaseAuth {
         name?: string;
         avatarUrl?: string;
     }): Promise<never>;
+    /**
+     * Emails a six-digit sign-in code.
+     *
+     * Resolves the same way whether or not the address has an account, so it
+     * cannot be used to check who is registered. A new address receives a code
+     * only while the project accepts sign-ups; a disabled account receives
+     * nothing.
+     *
+     * @throws EmailCodeDisabledError if the project has switched this off
+     * @throws RateLimitError after too many requests for one address
+     */
+    requestEmailCode(params: {
+        email: string;
+    }): Promise<void>;
+    /**
+     * Signs in with a code from requestEmailCode(), storing the session exactly
+     * as login() does. An unknown address becomes an account only if the
+     * project still accepts sign-ups at this moment. Each code works once and
+     * allows three attempts.
+     *
+     * @throws OtpInvalidError, OtpExpiredError, OtpMaxAttemptsError
+     * @throws EmailCodeDisabledError if the project has switched this off
+     */
+    signInWithEmailCode(params: {
+        email: string;
+        code: string;
+    }): Promise<KoolbaseSession>;
     sendOtp(params: SendOtpParams): Promise<OtpSendResult>;
     verifyOtp(params: VerifyOtpParams): Promise<PhoneVerifyResult>;
     linkPhone(params: LinkPhoneParams): Promise<void>;