@koolbase/core 11.4.0 → 12.0.0

package/dist/esm/auth.js

@@ -130,6 +130,22 @@ export 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) {
@@ -583,6 +599,188 @@ export 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 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/esm/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.

package/dist/esm/database.js

@@ -421,6 +421,70 @@ export class KoolbaseDatabase {
         const { pending } = await readOfflineState(userId);
         return pending.map(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 readOfflineState(userId);

package/dist/esm/device-metadata.js

@@ -49,7 +49,13 @@ export class DeviceMetadata {
         if (this.cached)
             return this.cached;
         const platform = getPlatform().info.os;
-        const platformVersion = 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 = 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/esm/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/esm/index.js

@@ -5,6 +5,7 @@
 // code installs the platform package, never this one directly.
 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/esm/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/package.json

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