@koolbase/core 11.4.0 → 12.1.0

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.
@@ -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>;

package/dist/esm/auth.js

@@ -1,5 +1,5 @@
 import { RestoreResult, } from './types.js';
-import { AccountLockedError, EmailAlreadyInUseError, InvalidCredentialsError, InvalidPhoneNumberError, KoolbaseAuthError, OtpExpiredError, OtpInvalidError, OtpMaxAttemptsError, OtpRateLimitError, PhoneAlreadyLinkedError, IdentityNotFoundError, InsufficientScopeError, MalformedSessionResponseError, ProviderIdentityAlreadyLinkedError, AccountExistsError, ContactNotVerifiedError, CurrentPasswordIncorrectError, HideRequiresVerificationError, InsufficientAuthorityError, LastCredentialError, OAuthOnlyAccountError, SessionRequiredError, SignupsDisabledError, TokenAlreadyUsedError, TokenExpiredError, UnsupportedOAuthProviderError, RateLimitError, VerificationResendCooldownError, VerificationResendDailyCapError, SessionExpiredError, SmsConfigMissingError, UnlockTokenInvalidError, UserDisabledError, WeakPasswordError, AppleEmailRequiredError, AppleSignInNotConfiguredError, InvalidAppleTokenError, OAuthEmailConflictError, GoogleEmailRequiredError, GoogleSignInNotConfiguredError, InvalidGoogleTokenError, } from './auth-errors.js';
+import { AccountLockedError, EmailAlreadyInUseError, InvalidCredentialsError, InvalidPhoneNumberError, KoolbaseAuthError, OtpExpiredError, OtpInvalidError, OtpMaxAttemptsError, OtpRateLimitError, PhoneAlreadyLinkedError, IdentityNotFoundError, InsufficientScopeError, MalformedSessionResponseError, ProviderIdentityAlreadyLinkedError, AccountExistsError, ContactNotVerifiedError, CurrentPasswordIncorrectError, HideRequiresVerificationError, InsufficientAuthorityError, LastCredentialError, OAuthOnlyAccountError, SessionRequiredError, SignupsDisabledError, TokenAlreadyUsedError, TokenExpiredError, UnsupportedOAuthProviderError, RateLimitError, VerificationResendCooldownError, VerificationResendDailyCapError, SessionExpiredError, SmsConfigMissingError, UnlockTokenInvalidError, UserDisabledError, WeakPasswordError, AppleEmailRequiredError, AppleSignInNotConfiguredError, InvalidAppleTokenError, OAuthEmailConflictError, GoogleEmailRequiredError, GoogleSignInNotConfiguredError, InvalidGoogleTokenError, EmailCodeDisabledError, } from './auth-errors.js';
 import { getPlatform } from './platform.js';
 import { DeviceMetadata } from './device-metadata.js';
 export class KoolbaseAuth {
@@ -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',
@@ -623,20 +821,54 @@ export class KoolbaseAuth {
     }
     // ─── OAuth (DEPRECATED — see v1.10.0) ───────────────────────────────────
     /**
-     * @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').
      */
     async oauthLogin(_params) {
-        throw new KoolbaseAuthError('OAuth sign-in is not yet implemented for the Koolbase SDK. ' +
-            'Planned for v1.10.0 (server-side endpoints under ' +
-            '/v1/sdk/auth/oauth/{provider}). Use email/password authentication ' +
-            'in the meantime.', 'not_implemented');
+        throw new KoolbaseAuthError('oauthLogin() was never implemented and is kept only so existing ' +
+            'code compiles. Use signInWithGoogle() or signInWithApple().', 'not_implemented');
+    }
+    // ─── Email code ─────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async requestEmailCode(params) {
+        const res = await this.authRequest('/v1/sdk/auth/email/code', {
+            method: 'POST',
+            body: { email: params.email },
+        });
+        if (!res.ok)
+            await this.throwTypedError(res, false);
+    }
+    /**
+     * 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
+     */
+    async signInWithEmailCode(params) {
+        const res = await this.authRequest('/v1/sdk/auth/email/code/verify', {
+            method: 'POST',
+            body: { email: params.email, code: params.code },
+        });
+        const session = await this.parseSessionResponse(res, false);
+        await this.setSessionInternal(session);
+        return session;
     }
     // ─── Phone OTP ──────────────────────────────────────────────────────────
     async sendOtp(params) {
@@ -829,6 +1061,16 @@ export class KoolbaseAuth {
             case 'contact_not_verified':
             case 'email_not_verified':
                 throw new ContactNotVerifiedError(msg || undefined);
+            // Sign-in codes. The otp_* codes are shared with phone sign-in; mapped
+            // here, every path that returns them throws the class an app catches.
+            case 'email_code_disabled':
+                throw new EmailCodeDisabledError();
+            case 'otp_expired':
+                throw new OtpExpiredError();
+            case 'otp_invalid':
+                throw new OtpInvalidError();
+            case 'otp_max_attempts':
+                throw new OtpMaxAttemptsError();
             // Registration
             case 'signups_disabled':
                 throw new SignupsDisabledError(msg || undefined);

package/dist/esm/database-errors.d.ts

@@ -195,6 +195,52 @@ export declare class KoolbaseConflictError extends KoolbaseDataError {
     field?: string;
     constructor(message?: string, field?: string);
 }
+/**
+ * A reference field points at a record that does not exist, is deleted, or
+ * lives in another collection — the server responds 400 `reference_invalid`.
+ *
+ * Checked when the write commits, so it can surface from an insert, an update,
+ * an upsert or a batch. In a batch the whole transaction is refused: nothing
+ * in it was written.
+ */
+export declare class KoolbaseReferenceInvalidError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * A record could not be deleted because live records still reference it, under
+ * a reference declared `on_delete: restrict` — 409 `reference_in_use`.
+ *
+ * Delete the referencing records first, or in the same batch: the check runs at
+ * commit, so one batch may delete a parent and its children in any order.
+ */
+export declare class KoolbaseReferenceInUseError extends KoolbaseDataError {
+    constructor(message?: string);
+}
+/**
+ * A reference could not be declared because existing records already point at
+ * records that do not exist — 409 `dangling_references`.
+ *
+ * `dangling` lists the offending records so they can be repaired; Koolbase
+ * never repairs them for you. It is capped at the first 50.
+ */
+export declare class KoolbaseDanglingReferencesError extends KoolbaseDataError {
+    dangling: Array<{
+        record_id: string;
+        value: string;
+    }>;
+    constructor(message?: string, dangling?: Array<{
+        record_id: string;
+        value: string;
+    }>);
+}
+/**
+ * A collection could not be deleted because another collection has a reference
+ * field pointing at it — 409 `collection_referenced`. Remove that reference
+ * first.
+ */
+export declare class KoolbaseCollectionReferencedError extends KoolbaseDataError {
+    constructor(message?: string);
+}
 /**
  * Thrown when the requested record or collection does not exist — the server
  * responds with 404 and code `not_found` / `record_not_found` /

package/dist/esm/database-errors.js

@@ -272,6 +272,62 @@ export class KoolbaseConflictError extends KoolbaseDataError {
         Object.setPrototypeOf(this, KoolbaseConflictError.prototype);
     }
 }
+/**
+ * A reference field points at a record that does not exist, is deleted, or
+ * lives in another collection — the server responds 400 `reference_invalid`.
+ *
+ * Checked when the write commits, so it can surface from an insert, an update,
+ * an upsert or a batch. In a batch the whole transaction is refused: nothing
+ * in it was written.
+ */
+export class KoolbaseReferenceInvalidError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'A reference points at a record that does not exist', 'reference_invalid');
+        this.name = 'KoolbaseReferenceInvalidError';
+        Object.setPrototypeOf(this, KoolbaseReferenceInvalidError.prototype);
+    }
+}
+/**
+ * A record could not be deleted because live records still reference it, under
+ * a reference declared `on_delete: restrict` — 409 `reference_in_use`.
+ *
+ * Delete the referencing records first, or in the same batch: the check runs at
+ * commit, so one batch may delete a parent and its children in any order.
+ */
+export class KoolbaseReferenceInUseError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'This record is still referenced by other records', 'reference_in_use');
+        this.name = 'KoolbaseReferenceInUseError';
+        Object.setPrototypeOf(this, KoolbaseReferenceInUseError.prototype);
+    }
+}
+/**
+ * A reference could not be declared because existing records already point at
+ * records that do not exist — 409 `dangling_references`.
+ *
+ * `dangling` lists the offending records so they can be repaired; Koolbase
+ * never repairs them for you. It is capped at the first 50.
+ */
+export class KoolbaseDanglingReferencesError extends KoolbaseDataError {
+    constructor(message, dangling) {
+        super(message ?? 'Existing records point at records that do not exist', 'dangling_references');
+        this.dangling = dangling ?? [];
+        this.name = 'KoolbaseDanglingReferencesError';
+        Object.setPrototypeOf(this, KoolbaseDanglingReferencesError.prototype);
+    }
+}
+/**
+ * A collection could not be deleted because another collection has a reference
+ * field pointing at it — 409 `collection_referenced`. Remove that reference
+ * first.
+ */
+export class KoolbaseCollectionReferencedError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Another collection references this one', 'collection_referenced');
+        this.name = 'KoolbaseCollectionReferencedError';
+        Object.setPrototypeOf(this, KoolbaseCollectionReferencedError.prototype);
+    }
+}
 /**
  * Thrown when the requested record or collection does not exist — the server
  * responds with 404 and code `not_found` / `record_not_found` /
@@ -396,6 +452,16 @@ export function koolbaseDataError(status, body, fallbackMessage = 'Request faile
     switch (code) {
         case 'unique_violation':
             return attach(new KoolbaseConflictError(message, field));
+        case 'reference_invalid':
+            return attach(new KoolbaseReferenceInvalidError(message));
+        case 'reference_in_use':
+            return attach(new KoolbaseReferenceInUseError(message));
+        case 'dangling_references': {
+            const d = (body?.details ?? {});
+            return attach(new KoolbaseDanglingReferencesError(message, d.dangling));
+        }
+        case 'collection_referenced':
+            return attach(new KoolbaseCollectionReferencedError(message));
         case 'plan_limit_reached': {
             const d = (body?.details ?? {});
             return new KoolbasePlanLimitError(message, d.resource, d.limit, d.plan);

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.