@koolbase/core 11.4.0 → 12.0.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.js

@@ -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);
     }
@@ -205,7 +205,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 +213,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 +221,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 +229,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 +237,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 +245,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 +261,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 +458,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 +466,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;

package/dist/cjs/auth.js

@@ -133,6 +133,22 @@ class KoolbaseAuth {
         return this.authRequest(path, { ...options, includeAuth: true });
     }
     // ─── Internal session lifecycle ─────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async updateUserAndPersist(user) {
+        if (!this.session)
+            return;
+        await this.setSessionInternal({ ...this.session, user });
+    }
     async setSessionInternal(session) {
         this.session = session;
         if (this.storage) {
@@ -586,6 +602,188 @@ class KoolbaseAuth {
             cooldownUntil: body.cooldown_until ? new Date(body.cooldown_until) : null,
         };
     }
+    /**
+     * 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.
+     */
+    async getCurrentUser() {
+        const res = await this.authRequest('/v1/sdk/auth/me', {
+            method: 'GET',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const user = this.mapUser(await res.json());
+        await this.updateUserAndPersist(user);
+        return user;
+    }
+    /**
+     * 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.
+     */
+    async updateProfile(params) {
+        const body = {};
+        if (params.fullName !== undefined)
+            body.full_name = params.fullName;
+        if (params.avatarUrl !== undefined)
+            body.avatar_url = params.avatarUrl;
+        const res = await this.authRequest('/v1/sdk/auth/me', {
+            method: 'PATCH',
+            body,
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const user = this.mapUser(await res.json());
+        await this.updateUserAndPersist(user);
+        return user;
+    }
+    /**
+     * 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.
+     */
+    async changePassword(params) {
+        if (params.newPassword.length < 8)
+            throw new auth_errors_js_1.WeakPasswordError();
+        const res = await this.authRequest('/v1/sdk/auth/me/password', {
+            method: 'PATCH',
+            body: {
+                current_password: params.currentPassword,
+                new_password: params.newPassword,
+            },
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+    }
+    /**
+     * 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.
+     */
+    async deleteAccount() {
+        const res = await this.authRequest('/v1/sdk/auth/me', {
+            method: 'DELETE',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        await this.clearSessionInternal();
+    }
+    /**
+     * 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.
+     */
+    async listSessions() {
+        const res = await this.authRequest('/v1/sdk/auth/sessions', {
+            method: 'GET',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const body = (await res.json());
+        return (body.sessions ?? []).map((s) => {
+            const r = s;
+            return {
+                id: String(r.id),
+                ip: r.ip,
+                userAgent: r.user_agent,
+                deviceLabel: r.device_label,
+                createdAt: String(r.created_at),
+                expiresAt: String(r.expires_at),
+                isCurrent: Boolean(r.is_current),
+            };
+        });
+    }
+    /**
+     * 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.
+     */
+    async revokeSession(sessionId) {
+        const res = await this.authRequest(`/v1/sdk/auth/sessions/${encodeURIComponent(sessionId)}/revoke`, { method: 'POST', includeAuth: true });
+        await this.checkResponse(res);
+        // Revoking your own session leaves a token the server has dropped. The
+        // SDK cannot tell from the response which one it was, and re-listing to
+        // find out would cost a request on every revoke — so it asks the only
+        // party that already knows: the next request. If it was this session,
+        // that request 401s and the normal refresh path clears it.
+        //
+        // A UI listing sessions knows which row is current from isCurrent, and
+        // should call logout() rather than revokeSession() for that one, which
+        // is both clearer to the user and one fewer round trip.
+    }
+    /**
+     * 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.
+     */
+    async revokeAllOtherSessions() {
+        const res = await this.authRequest('/v1/sdk/auth/sessions/revoke-all', {
+            method: 'POST',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const body = (await res.json().catch(() => ({})));
+        return body.revoked_count ?? 0;
+    }
+    /**
+     * 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.
+     */
+    async auditLog(options) {
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options?.offset !== undefined)
+            params.set('offset', String(options.offset));
+        const qs = params.toString();
+        const res = await this.authRequest(`/v1/sdk/auth/audit${qs ? `?${qs}` : ''}`, { method: 'GET', includeAuth: true });
+        await this.checkResponse(res);
+        const body = (await res.json());
+        return {
+            events: (body.events ?? []).map((e) => ({
+                id: String(e.id),
+                eventType: String(e.event_type),
+                occurredAt: String(e.occurred_at),
+                ip: e.ip,
+                userAgent: e.user_agent,
+                eventData: e.event_data ?? {},
+            })),
+            total: Number(body.total ?? 0),
+            limit: Number(body.limit ?? 0),
+            offset: Number(body.offset ?? 0),
+        };
+    }
     async unlock(token) {
         const res = await this.authRequest('/v1/sdk/auth/unlock', {
             method: 'POST',

package/dist/cjs/database.d.ts

@@ -1,3 +1,4 @@
+import { KoolbaseAggregateRequest, KoolbaseAggregateResult } from './aggregate.js';
 import { KoolbaseConflict } from './conflict.js';
 import { PendingWrite } from './pending-write.js';
 import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult, KoolbaseVector, SemanticSearchResult, SearchMode } from './types.js';
@@ -127,6 +128,28 @@ export declare class KoolbaseDatabase {
      * moment matters. Snapshot, not a live handle; per-user.
      */
     pendingWrites(): Promise<PendingWrite[]>;
+    /**
+     * 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.
+     */
+    aggregate(request: KoolbaseAggregateRequest): Promise<KoolbaseAggregateResult>;
     conflicts(): Promise<KoolbaseConflict[]>;
     /**
      * Resolves by id, reloading the stored conflict first.