@koolbase/core 11.3.0 → 12.0.0

package/dist/cjs/database.js

@@ -424,6 +424,70 @@ class KoolbaseDatabase {
         const { pending } = await (0, offline_state_js_1.readOfflineState)(userId);
         return pending.map(pending_write_js_1.toPendingWrite);
     }
+    /**
+     * Count and total over a whole collection, with the read rule applied
+     * inside the query.
+     *
+     * Not a paged query you add up yourself: the server aggregates the entire
+     * authorized set. And never a bare number — collections are schemaless, so
+     * a sum that quietly skipped three malformed rows would be a wrong number
+     * that looks right. Check `accounting` for what contributed.
+     *
+     * ```ts
+     * const r = await db.aggregate({
+     *   collection: 'orders',
+     *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+     *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+     * });
+     * ```
+     *
+     * A calendar bucket requires a timezone and the types enforce it: midnight
+     * means nothing without one, and Accra and UTC disagree about which day a
+     * 23:30 sale belongs to.
+     */
+    async aggregate(request) {
+        const raw = await this.request('POST', '/v1/sdk/db/aggregate', {
+            collection: request.collection,
+            ...(request.where?.length ? { where: request.where } : {}),
+            ...(request.groupBy
+                ? {
+                    group_by: {
+                        field: request.groupBy.field,
+                        ...(request.groupBy.bucket
+                            ? {
+                                bucket: request.groupBy.bucket,
+                                timezone: request.groupBy.timezone,
+                            }
+                            : {}),
+                    },
+                }
+                : {}),
+            measures: request.measures.map((m) => ({
+                aggregate: m.aggregate,
+                ...(m.field ? { field: m.field } : {}),
+                as: m.as,
+            })),
+        });
+        const accounting = {};
+        for (const [name, a] of Object.entries(raw.accounting ?? {})) {
+            accounting[name] = {
+                counted: Number(a.counted ?? 0),
+                skipped: Number(a.skipped ?? 0),
+                skippedReason: a.skipped_reason,
+            };
+        }
+        return {
+            groups: (raw.groups ?? []).map((g) => ({
+                category: String(g.category ?? ''),
+                values: g.values ?? {},
+            })),
+            matched: Number(raw.matched ?? 0),
+            accounting,
+            // Explicitly boolean: a missing field must read as false, not
+            // undefined, or `if (!r.tooManyGroups)` passes on a refused request.
+            tooManyGroups: raw.too_many_groups === true,
+        };
+    }
     async conflicts() {
         const userId = this.requireUserId('the conflict list');
         const { conflicts } = await (0, offline_state_js_1.readOfflineState)(userId);

package/dist/cjs/device-metadata.js

@@ -52,7 +52,13 @@ class DeviceMetadata {
         if (this.cached)
             return this.cached;
         const platform = (0, platform_js_1.getPlatform)().info.os;
-        const platformVersion = (0, platform_js_1.getPlatform)().info.version;
+        // 'unknown' rather than empty, matching appVersion above. A browser
+        // outside the handful browserVersion() recognises — Brave, Opera,
+        // Samsung Internet, an in-app webview — reports nothing, and an empty
+        // header stored against a session is indistinguishable from an SDK that
+        // never reported itself at all. 'unknown' says the SDK spoke and could
+        // not identify the host, which is a different and more useful fact.
+        const platformVersion = (0, platform_js_1.getPlatform)().info.version || 'unknown';
         const deviceLabel = await this.getOrCreateDeviceLabel();
         // No User-Agent: a browser forbids setting it, and the same header set
         // now goes out from both hosts. The platform and version below carry

package/dist/cjs/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './errors.js';
+export * from './aggregate.js';
 export * from './conflict.js';
 export * from './pending-write.js';
 export * from './function-errors.js';

package/dist/cjs/index.js

@@ -22,6 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
+__exportStar(require("./aggregate.js"), exports);
 __exportStar(require("./conflict.js"), exports);
 __exportStar(require("./pending-write.js"), exports);
 __exportStar(require("./function-errors.js"), exports);

package/dist/cjs/types.d.ts

@@ -88,6 +88,64 @@ export type SignUpResult = {
     user: KoolbaseUser;
     session: null;
 };
+/**
+ * One active session — somewhere the user is signed in.
+ *
+ * Token hashes are never included; the server excludes them deliberately.
+ */
+export interface KoolbaseSessionInfo {
+    id: string;
+    /** Where it signed in from, when the server captured it. */
+    ip?: string;
+    /** What signed in. A browser sets this; native SDKs send their own. */
+    userAgent?: string;
+    /** A per-install label, where the SDK supplied one. */
+    deviceLabel?: string;
+    createdAt: string;
+    expiresAt: string;
+    /**
+     * True for the session making the request.
+     *
+     * A device list needs this: without it a user cannot tell which row is the
+     * phone in their hand, and "sign out everywhere else" has nothing to
+     * exclude.
+     */
+    isCurrent: boolean;
+}
+/**
+ * One thing that happened to this account.
+ *
+ * The server sanitizes these: `eventData` carries only the fields allowed
+ * for that event type, so a lockout can say which address was attempted
+ * while a successful login carries nothing extra.
+ */
+export interface KoolbaseAuditEvent {
+    id: string;
+    /**
+     * What happened. One of: auth.login.success, auth.login.failed,
+     * auth.account.locked, auth.account.unlocked, auth.session.created,
+     * auth.session.refreshed, auth.session.revoked, auth.password.changed,
+     * auth.user.verified.
+     *
+     * A string rather than a union: the server may add one, and an app that
+     * stops compiling because it did would be worse than one that shows an
+     * event it does not recognise.
+     */
+    eventType: string;
+    occurredAt: string;
+    ip?: string;
+    userAgent?: string;
+    /** Whatever that event type is allowed to carry. Often empty. */
+    eventData: Record<string, unknown>;
+}
+/** A page of audit events, and how many there are in total. */
+export interface KoolbaseAuditPage {
+    events: KoolbaseAuditEvent[];
+    /** Across all pages, so an app knows whether to offer "show more". */
+    total: number;
+    limit: number;
+    offset: number;
+}
 export interface ResendVerificationResult {
     alreadyVerified: boolean;
     /** When the link in the email stops working. Null when nothing was sent. */

package/dist/esm/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/esm/aggregate.js

@@ -0,0 +1,25 @@
+/**
+ * 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
+ * }
+ * ```
+ */
+export {};

package/dist/esm/auth-errors.js

@@ -21,14 +21,14 @@ export class InvalidCredentialsError extends KoolbaseAuthError {
 }
 export 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);
     }
 }
 export 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);
     }
@@ -49,7 +49,7 @@ export class WeakPasswordError extends KoolbaseAuthError {
 // ─── Session lifecycle ─────────────────────────────────────────────────────
 export 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);
     }
@@ -95,7 +95,7 @@ export class AccountLockedError extends KoolbaseAuthError {
  */
 export 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);
     }
@@ -185,42 +185,42 @@ export class OtpMaxAttemptsError extends KoolbaseAuthError {
 }
 export 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);
     }
 }
 export 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);
     }
 }
 export 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);
     }
 }
 export 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);
     }
 }
 export 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);
     }
 }
 export 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);
     }
@@ -234,7 +234,7 @@ export class OAuthEmailConflictError extends KoolbaseAuthError {
 }
 export 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);
     }
@@ -414,14 +414,14 @@ export class MalformedSessionResponseError extends KoolbaseAuthError {
 }
 export 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);
     }
 }
 export 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/esm/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.
@@ -154,6 +166,21 @@ export declare class KoolbaseAuth {
     private _doRefresh;
     logout(): Promise<boolean>;
     forgotPassword(email: string): Promise<void>;
+    /**
+     * Ask for a new verification email, with no session.
+     *
+     * For the state a project with verified contact required creates:
+     * registered, unverified, refused at login, and holding a link that may
+     * never have arrived or has since expired. `resendVerificationEmail()`
+     * cannot help there — it needs a session the user cannot get.
+     *
+     * Returns nothing, and throws only on a malformed request, because the
+     * server answers identically whether the address has an account, has none,
+     * or is already verified. Anything else would let anyone discover who has
+     * signed up. So there is no "we sent it" to report: show the same "check
+     * your email" either way.
+     */
+    resendVerificationEmailToAddress(email: string): Promise<void>;
     resetPassword(token: string, password: string): Promise<void>;
     /**
      * Complete email verification with a token from a verification link.
@@ -176,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;