@koolbase/core 12.0.0 → 12.2.0

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

@@ -101,6 +101,14 @@ export declare class NetworkError extends KoolbaseAuthError {
 export declare class InvalidPhoneNumberError extends KoolbaseAuthError {
     constructor();
 }
+/**
+ * The project has switched off signing in with an emailed code — 403
+ * `email_code_disabled`. Applies to every address alike, so it reveals
+ * nothing about which accounts exist.
+ */
+export declare class EmailCodeDisabledError extends KoolbaseAuthError {
+    constructor();
+}
 export declare class OtpExpiredError extends KoolbaseAuthError {
     constructor();
 }
@@ -249,3 +257,29 @@ export declare class InvalidGoogleTokenError extends KoolbaseAuthError {
 export declare class GoogleEmailRequiredError extends KoolbaseAuthError {
     constructor();
 }
+/**
+ * The first factor passed and this account needs a second: sign-in is not
+ * finished. Pass `challengeToken` to `verifyMfa` with a code from the
+ * person's authenticator app, or to `verifyRecoveryCode`. Apps that never
+ * enable MFA never see this.
+ */
+export declare class MfaRequiredError extends KoolbaseAuthError {
+    readonly challengeToken: string;
+    readonly expiresAt?: string;
+    constructor(challengeToken: string, expiresAt?: string);
+}
+export declare class RecentAuthRequiredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class RecentMfaRequiredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class MfaAlreadyEnabledError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class MfaEnrollmentNotFoundError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class MfaNotEnabledError extends KoolbaseAuthError {
+    constructor();
+}

package/dist/cjs/auth-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.MalformedSessionResponseError = exports.ProviderIdentityAlreadyLinkedError = exports.IdentityNotFoundError = exports.InsufficientScopeError = exports.HideRequiresVerificationError = exports.LastCredentialError = exports.InsufficientAuthorityError = exports.SessionRequiredError = exports.UnsupportedOAuthProviderError = exports.OAuthOnlyAccountError = exports.AccountExistsError = exports.CurrentPasswordIncorrectError = exports.TokenAlreadyUsedError = exports.TokenExpiredError = exports.SignupsDisabledError = exports.ContactNotVerifiedError = exports.GoogleSignInNotConfiguredError = exports.OAuthEmailConflictError = exports.AppleEmailRequiredError = exports.InvalidAppleTokenError = exports.AppleSignInNotConfiguredError = exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.InvalidPhoneNumberError = exports.NetworkError = exports.VerificationResendDailyCapError = exports.VerificationResendCooldownError = exports.RateLimitError = exports.UnlockTokenInvalidError = exports.AccountLockedError = exports.TokenRevokedError = exports.SessionExpiredError = exports.WeakPasswordError = exports.UserDisabledError = exports.EmailAlreadyInUseError = exports.InvalidCredentialsError = exports.KoolbaseAuthError = void 0;
+exports.MfaNotEnabledError = exports.MfaEnrollmentNotFoundError = exports.MfaAlreadyEnabledError = exports.RecentMfaRequiredError = exports.RecentAuthRequiredError = exports.MfaRequiredError = exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = exports.MalformedSessionResponseError = exports.ProviderIdentityAlreadyLinkedError = exports.IdentityNotFoundError = exports.InsufficientScopeError = exports.HideRequiresVerificationError = exports.LastCredentialError = exports.InsufficientAuthorityError = exports.SessionRequiredError = exports.UnsupportedOAuthProviderError = exports.OAuthOnlyAccountError = exports.AccountExistsError = exports.CurrentPasswordIncorrectError = exports.TokenAlreadyUsedError = exports.TokenExpiredError = exports.SignupsDisabledError = exports.ContactNotVerifiedError = exports.GoogleSignInNotConfiguredError = exports.OAuthEmailConflictError = exports.AppleEmailRequiredError = exports.InvalidAppleTokenError = exports.AppleSignInNotConfiguredError = exports.SmsConfigMissingError = exports.PhoneAlreadyLinkedError = exports.OtpRateLimitError = exports.OtpMaxAttemptsError = exports.OtpInvalidError = exports.OtpExpiredError = exports.EmailCodeDisabledError = exports.InvalidPhoneNumberError = exports.NetworkError = exports.VerificationResendDailyCapError = exports.VerificationResendCooldownError = exports.RateLimitError = exports.UnlockTokenInvalidError = exports.AccountLockedError = exports.TokenRevokedError = exports.SessionExpiredError = exports.WeakPasswordError = exports.UserDisabledError = exports.EmailAlreadyInUseError = exports.InvalidCredentialsError = exports.KoolbaseAuthError = void 0;
 const errors_js_1 = require("./errors.js");
 /**
  * Base error type for all Koolbase auth errors. Catchable via
@@ -179,6 +179,19 @@ class InvalidPhoneNumberError extends KoolbaseAuthError {
     }
 }
 exports.InvalidPhoneNumberError = InvalidPhoneNumberError;
+/**
+ * The project has switched off signing in with an emailed code — 403
+ * `email_code_disabled`. Applies to every address alike, so it reveals
+ * nothing about which accounts exist.
+ */
+class EmailCodeDisabledError extends KoolbaseAuthError {
+    constructor() {
+        super('Signing in with an emailed code is switched off for this project', 'email_code_disabled');
+        this.name = 'EmailCodeDisabledError';
+        Object.setPrototypeOf(this, EmailCodeDisabledError.prototype);
+    }
+}
+exports.EmailCodeDisabledError = EmailCodeDisabledError;
 class OtpExpiredError extends KoolbaseAuthError {
     constructor() {
         super('OTP has expired, please request a new code', 'otp_expired');
@@ -472,3 +485,60 @@ class GoogleEmailRequiredError extends KoolbaseAuthError {
     }
 }
 exports.GoogleEmailRequiredError = GoogleEmailRequiredError;
+// ─── Two-step sign-in (MFA) ─────────────────────────────────────────────────
+/**
+ * The first factor passed and this account needs a second: sign-in is not
+ * finished. Pass `challengeToken` to `verifyMfa` with a code from the
+ * person's authenticator app, or to `verifyRecoveryCode`. Apps that never
+ * enable MFA never see this.
+ */
+class MfaRequiredError extends KoolbaseAuthError {
+    constructor(challengeToken, expiresAt) {
+        super('Two-step sign-in required', 'mfa_required');
+        this.name = 'MfaRequiredError';
+        this.challengeToken = challengeToken;
+        this.expiresAt = expiresAt;
+        Object.setPrototypeOf(this, MfaRequiredError.prototype);
+    }
+}
+exports.MfaRequiredError = MfaRequiredError;
+class RecentAuthRequiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Sign in again to change two-step sign-in', 'recent_auth_required');
+        this.name = 'RecentAuthRequiredError';
+        Object.setPrototypeOf(this, RecentAuthRequiredError.prototype);
+    }
+}
+exports.RecentAuthRequiredError = RecentAuthRequiredError;
+class RecentMfaRequiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Confirm with your authenticator first', 'recent_mfa_required');
+        this.name = 'RecentMfaRequiredError';
+        Object.setPrototypeOf(this, RecentMfaRequiredError.prototype);
+    }
+}
+exports.RecentMfaRequiredError = RecentMfaRequiredError;
+class MfaAlreadyEnabledError extends KoolbaseAuthError {
+    constructor() {
+        super('Two-step sign-in is already on for this account', 'mfa_already_enabled');
+        this.name = 'MfaAlreadyEnabledError';
+        Object.setPrototypeOf(this, MfaAlreadyEnabledError.prototype);
+    }
+}
+exports.MfaAlreadyEnabledError = MfaAlreadyEnabledError;
+class MfaEnrollmentNotFoundError extends KoolbaseAuthError {
+    constructor() {
+        super('No enrolment in progress; start again', 'mfa_enrollment_not_found');
+        this.name = 'MfaEnrollmentNotFoundError';
+        Object.setPrototypeOf(this, MfaEnrollmentNotFoundError.prototype);
+    }
+}
+exports.MfaEnrollmentNotFoundError = MfaEnrollmentNotFoundError;
+class MfaNotEnabledError extends KoolbaseAuthError {
+    constructor() {
+        super('Two-step sign-in is not on for this account', 'mfa_not_enabled');
+        this.name = 'MfaNotEnabledError';
+        Object.setPrototypeOf(this, MfaNotEnabledError.prototype);
+    }
+}
+exports.MfaNotEnabledError = MfaNotEnabledError;

package/dist/cjs/auth.d.ts

@@ -302,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').
      */
@@ -318,6 +316,74 @@ 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>;
+    private mfaRequired;
+    /** Finishes sign-in with a code from the person's authenticator app. */
+    verifyMfa(params: {
+        challengeToken: string;
+        code: string;
+    }): Promise<KoolbaseSession>;
+    /**
+     * Finishes sign-in with a recovery code. Each works once; prompt the person
+     * to regenerate when recoveryCodesRemaining reaches zero.
+     */
+    verifyRecoveryCode(params: {
+        challengeToken: string;
+        code: string;
+    }): Promise<{
+        session: KoolbaseSession;
+        recoveryCodesRemaining: number;
+    }>;
+    /**
+     * Starts adding an authenticator; needs a sign-in within ten minutes. Show
+     * otpauthUri as a QR code, then call confirmMfaEnrollment with the first
+     * code the app shows.
+     */
+    enrollMfa(): Promise<{
+        otpauthUri: string;
+        secret: string;
+    }>;
+    /** Turns MFA on and returns ten recovery codes, shown this once only. Other devices are signed out. */
+    confirmMfaEnrollment(code: string): Promise<string[]>;
+    mfaStatus(): Promise<{
+        enabled: boolean;
+        recoveryCodesRemaining: number;
+    }>;
+    /** Re-confirms the second factor, opening ten minutes to change MFA. */
+    stepUpMfa(params: {
+        code?: string;
+        recoveryCode?: string;
+    }): Promise<void>;
+    /** Turns MFA off. Needs stepUpMfa() within the last ten minutes. */
+    disableMfa(): Promise<void>;
+    /** Replaces all recovery codes; the old ones stop working. Needs stepUpMfa() within ten minutes. */
+    regenerateRecoveryCodes(): Promise<string[]>;
     sendOtp(params: SendOtpParams): Promise<OtpSendResult>;
     verifyOtp(params: VerifyOtpParams): Promise<PhoneVerifyResult>;
     linkPhone(params: LinkPhoneParams): Promise<void>;

package/dist/cjs/auth.js

@@ -388,6 +388,8 @@ class KoolbaseAuth {
         const errorMessage = body?.error ?? '';
         // ─── code-first ───
         switch (code) {
+            case 'mfa_required':
+                throw this.mfaRequired(body);
             case 'oauth_not_configured':
                 throw new auth_errors_js_1.GoogleSignInNotConfiguredError();
             case 'invalid_oauth_token':
@@ -442,6 +444,8 @@ class KoolbaseAuth {
         const errorMessage = body?.error ?? '';
         // ─── code-first ───
         switch (code) {
+            case 'mfa_required':
+                throw this.mfaRequired(body);
             case 'oauth_not_configured':
                 throw new auth_errors_js_1.AppleSignInNotConfiguredError();
             case 'invalid_oauth_token':
@@ -824,20 +828,150 @@ 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 auth_errors_js_1.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 auth_errors_js_1.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;
+    }
+    // ─── Two-step sign-in (MFA) ─────────────────────────────────────────────
+    //
+    // When an account has MFA on, every sign-in method throws MfaRequiredError.
+    // Finish with verifyMfa() or verifyRecoveryCode().
+    // One builder for every parser, so the four cannot drift apart in how the
+    // challenge reaches the app.
+    mfaRequired(body) {
+        const d = body?.details ?? {};
+        return new auth_errors_js_1.MfaRequiredError(String(d.challenge_token ?? ''), d.expires_at);
+    }
+    /** Finishes sign-in with a code from the person's authenticator app. */
+    async verifyMfa(params) {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/verify', {
+            method: 'POST',
+            body: { challenge_token: params.challengeToken, code: params.code },
+        });
+        const session = await this.parseSessionResponse(res, false);
+        await this.setSessionInternal(session);
+        return session;
+    }
+    /**
+     * Finishes sign-in with a recovery code. Each works once; prompt the person
+     * to regenerate when recoveryCodesRemaining reaches zero.
+     */
+    async verifyRecoveryCode(params) {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/verify-recovery', {
+            method: 'POST',
+            body: { challenge_token: params.challengeToken, code: params.code },
+        });
+        if (!res.ok)
+            await this.throwTypedError(res, false);
+        // Read once: the session and the remaining count come from one body.
+        const data = await res.json();
+        if (!data?.access_token)
+            throw new auth_errors_js_1.MalformedSessionResponseError('an access token');
+        if (!data?.refresh_token)
+            throw new auth_errors_js_1.MalformedSessionResponseError('a refresh token');
+        const session = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token,
+            expiresAt: data.expires_at,
+            user: this.mapUser(data.user),
+        };
+        await this.setSessionInternal(session);
+        return { session, recoveryCodesRemaining: Number(data.recovery_codes_remaining ?? 0) };
+    }
+    /**
+     * Starts adding an authenticator; needs a sign-in within ten minutes. Show
+     * otpauthUri as a QR code, then call confirmMfaEnrollment with the first
+     * code the app shows.
+     */
+    async enrollMfa() {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/enroll', { method: 'POST', includeAuth: true });
+        await this.checkResponse(res);
+        const d = await res.json();
+        return { otpauthUri: d.otpauth_uri, secret: d.secret };
+    }
+    /** Turns MFA on and returns ten recovery codes, shown this once only. Other devices are signed out. */
+    async confirmMfaEnrollment(code) {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/enroll/confirm', {
+            method: 'POST',
+            body: { code },
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        return (await res.json()).recovery_codes;
+    }
+    async mfaStatus() {
+        const res = await this.authRequest('/v1/sdk/auth/mfa', { method: 'GET', includeAuth: true });
+        await this.checkResponse(res);
+        const d = await res.json();
+        return { enabled: !!d.enabled, recoveryCodesRemaining: Number(d.recovery_codes_remaining ?? 0) };
+    }
+    /** Re-confirms the second factor, opening ten minutes to change MFA. */
+    async stepUpMfa(params) {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/step-up', {
+            method: 'POST',
+            body: {
+                ...(params.code ? { code: params.code } : {}),
+                ...(params.recoveryCode ? { recovery_code: params.recoveryCode } : {}),
+            },
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+    }
+    /** Turns MFA off. Needs stepUpMfa() within the last ten minutes. */
+    async disableMfa() {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/disable', { method: 'POST', includeAuth: true });
+        await this.checkResponse(res);
+    }
+    /** Replaces all recovery codes; the old ones stop working. Needs stepUpMfa() within ten minutes. */
+    async regenerateRecoveryCodes() {
+        const res = await this.authRequest('/v1/sdk/auth/mfa/recovery-codes', { method: 'POST', includeAuth: true });
+        await this.checkResponse(res);
+        return (await res.json()).recovery_codes;
     }
     // ─── Phone OTP ──────────────────────────────────────────────────────────
     async sendOtp(params) {
@@ -1006,6 +1140,18 @@ class KoolbaseAuth {
         const msg = body.error ?? '';
         // ─── code-first ───
         switch (code) {
+            case 'mfa_required':
+                throw this.mfaRequired(body);
+            case 'recent_auth_required':
+                throw new auth_errors_js_1.RecentAuthRequiredError();
+            case 'recent_mfa_required':
+                throw new auth_errors_js_1.RecentMfaRequiredError();
+            case 'mfa_already_enabled':
+                throw new auth_errors_js_1.MfaAlreadyEnabledError();
+            case 'mfa_enrollment_not_found':
+                throw new auth_errors_js_1.MfaEnrollmentNotFoundError();
+            case 'mfa_not_enabled':
+                throw new auth_errors_js_1.MfaNotEnabledError();
             case 'invalid_credentials':
                 throw new auth_errors_js_1.InvalidCredentialsError();
             case 'email_in_use':
@@ -1030,6 +1176,16 @@ class KoolbaseAuth {
             case 'contact_not_verified':
             case 'email_not_verified':
                 throw new auth_errors_js_1.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 auth_errors_js_1.EmailCodeDisabledError();
+            case 'otp_expired':
+                throw new auth_errors_js_1.OtpExpiredError();
+            case 'otp_invalid':
+                throw new auth_errors_js_1.OtpInvalidError();
+            case 'otp_max_attempts':
+                throw new auth_errors_js_1.OtpMaxAttemptsError();
             // Registration
             case 'signups_disabled':
                 throw new auth_errors_js_1.SignupsDisabledError(msg || undefined);
@@ -1116,6 +1272,8 @@ class KoolbaseAuth {
         const msg = body.error ?? '';
         // ─── code-first ───
         switch (code) {
+            case 'mfa_required':
+                throw this.mfaRequired(body);
             case 'invalid_phone':
                 throw new auth_errors_js_1.InvalidPhoneNumberError();
             case 'otp_expired':

package/dist/cjs/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/cjs/database-errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseVectorDimensionMismatchError = exports.KoolbaseRateLimitError = exports.KoolbasePermissionError = exports.KoolbaseInsufficientAuthorityError = exports.KoolbaseValidationError = exports.KoolbaseNotFoundError = exports.KoolbaseConflictError = exports.KoolbaseConstraintNotFoundError = exports.KoolbaseConstraintExistsError = exports.KoolbaseAmbiguousMatchError = exports.KoolbaseDuplicateValuesError = exports.KoolbaseBatchFailedError = exports.KoolbaseIdempotencyKeyReusedError = exports.KoolbaseRevisionMismatchError = exports.KoolbaseProviderInvalidError = exports.KoolbaseProviderNotConfiguredError = exports.KoolbaseInvalidEmbeddingConfigError = exports.KoolbaseFieldNotAutoEmbedError = exports.KoolbaseVectorFieldExistsError = exports.KoolbaseStateConflictError = exports.KoolbaseNoChangesError = exports.KoolbaseInvalidBodyError = exports.KoolbaseProjectInvalidError = exports.KoolbaseInvitationInvalidError = exports.KoolbaseSlugTakenError = exports.KoolbaseSeedError = exports.KoolbaseDataError = void 0;
+exports.KoolbaseVectorDimensionMismatchError = exports.KoolbaseRateLimitError = exports.KoolbasePermissionError = exports.KoolbaseInsufficientAuthorityError = exports.KoolbaseValidationError = exports.KoolbaseNotFoundError = exports.KoolbaseCollectionReferencedError = exports.KoolbaseDanglingReferencesError = exports.KoolbaseReferenceInUseError = exports.KoolbaseReferenceInvalidError = exports.KoolbaseConflictError = exports.KoolbaseConstraintNotFoundError = exports.KoolbaseConstraintExistsError = exports.KoolbaseAmbiguousMatchError = exports.KoolbaseDuplicateValuesError = exports.KoolbaseBatchFailedError = exports.KoolbaseIdempotencyKeyReusedError = exports.KoolbaseRevisionMismatchError = exports.KoolbaseProviderInvalidError = exports.KoolbaseProviderNotConfiguredError = exports.KoolbaseInvalidEmbeddingConfigError = exports.KoolbaseFieldNotAutoEmbedError = exports.KoolbaseVectorFieldExistsError = exports.KoolbaseStateConflictError = exports.KoolbaseNoChangesError = exports.KoolbaseInvalidBodyError = exports.KoolbaseProjectInvalidError = exports.KoolbaseInvitationInvalidError = exports.KoolbaseSlugTakenError = exports.KoolbaseSeedError = exports.KoolbaseDataError = void 0;
 exports.koolbaseDataError = koolbaseDataError;
 const errors_js_1 = require("./errors.js");
 /**
@@ -297,6 +297,66 @@ class KoolbaseConflictError extends KoolbaseDataError {
     }
 }
 exports.KoolbaseConflictError = KoolbaseConflictError;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.KoolbaseReferenceInvalidError = KoolbaseReferenceInvalidError;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.KoolbaseReferenceInUseError = KoolbaseReferenceInUseError;
+/**
+ * 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.
+ */
+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);
+    }
+}
+exports.KoolbaseDanglingReferencesError = KoolbaseDanglingReferencesError;
+/**
+ * A collection could not be deleted because another collection has a reference
+ * field pointing at it — 409 `collection_referenced`. Remove that reference
+ * first.
+ */
+class KoolbaseCollectionReferencedError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Another collection references this one', 'collection_referenced');
+        this.name = 'KoolbaseCollectionReferencedError';
+        Object.setPrototypeOf(this, KoolbaseCollectionReferencedError.prototype);
+    }
+}
+exports.KoolbaseCollectionReferencedError = KoolbaseCollectionReferencedError;
 /**
  * Thrown when the requested record or collection does not exist — the server
  * responds with 404 and code `not_found` / `record_not_found` /
@@ -427,6 +487,16 @@ function koolbaseDataError(status, body, fallbackMessage = 'Request failed') {
     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 errors_js_1.KoolbasePlanLimitError(message, d.resource, d.limit, d.plan);