@koolbase/core 12.0.0 → 12.1.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();
 }

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.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');

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,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/cjs/auth.js

@@ -824,20 +824,54 @@ 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;
     }
     // ─── Phone OTP ──────────────────────────────────────────────────────────
     async sendOtp(params) {
@@ -1030,6 +1064,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);

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);

package/dist/cjs/fiscal.d.ts

@@ -0,0 +1,114 @@
+import { KoolbaseConfig } from './types.js';
+import { KoolbaseError } from './errors.js';
+/**
+ * The lifecycle status of a fiscal intent.
+ *
+ * A sale is durably recorded the moment `submit` returns; fiscal numbers and
+ * the authority's certification follow this state machine:
+ *
+ * - `queued` / `submitting` / `retrying` — sealed with allocated numbers;
+ *   delivery to the authority is in progress.
+ * - `fiscalized` — the authority answered; for certifying document kinds the
+ *   `certification` is present.
+ * - `blocked` — a precondition failed BEFORE any fiscal number was consumed
+ *   (see `blockedReason`). Resubmitting the same `clientRef` after fixing the
+ *   cause resumes it.
+ * - `attention` — the authority rejected the document, or its credential died
+ *   after sealing. An operator resolves it; the register's chain waits behind
+ *   it.
+ * - `voided` — terminally closed by an operator without fiscalization.
+ *
+ * `unknown` is the forward-compatible fallback: a status this SDK version has
+ * not heard of parses as unknown rather than throwing, so a server that grows
+ * a state does not break older clients.
+ */
+export type FiscalStatus = 'created' | 'blocked' | 'queued' | 'submitting' | 'retrying' | 'fiscalized' | 'attention' | 'voided' | 'unknown';
+/**
+ * The state of one fiscal intent.
+ *
+ * Jurisdiction-neutral by design: this SDK never learns a jurisdiction's
+ * vocabulary. Payloads travel as objects shaped by the device's adapter, and
+ * `certification` comes back as the authority granted it — for Ghana that
+ * means `ysdcregsig`, `ysdcrecnum`, `qr_code` and so on, which the SDK
+ * passes through without naming.
+ */
+export interface FiscalIntentResult {
+    intentId: string;
+    status: FiscalStatus;
+    /** Why a `blocked` intent stopped, when the server said. */
+    blockedReason?: string;
+    /** Fiscal numbers allocated at sealing. */
+    numbers?: Record<string, number>;
+    /** When the intent was sealed and its numbers allocated. */
+    sealedAt?: string;
+    /**
+     * What the authority granted, once `status` is `fiscalized`. This is the
+     * receipt-rendering payload: for Ghana, the signature, receipt number and
+     * QR verification URL.
+     */
+    certification?: Record<string, unknown>;
+}
+/** True once the authority has certified the document. */
+export declare function isFiscalized(r: FiscalIntentResult): boolean;
+/** True while delivery to the authority is still in progress. */
+export declare function isPending(r: FiscalIntentResult): boolean;
+/** A fiscal request that failed. Carries the HTTP status where there was one. */
+export declare class KoolbaseFiscalError extends KoolbaseError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Classify a response. Status and body in, result or error out.
+ *
+ * Exported for testability, and because auth handling belongs with the
+ * session hook rather than here — the same split the Flutter SDK makes.
+ */
+export declare function decodeFiscalResponse(status: number, body: string): Promise<FiscalIntentResult>;
+/**
+ * Koolbase Fiscal — submitting sales to a tax authority.
+ *
+ * Jurisdiction-neutral: the SDK moves payloads and reads back whatever the
+ * authority certified. Ghana's GRA E-VAT is the first jurisdiction; nothing
+ * here names it.
+ */
+export declare class KoolbaseFiscal {
+    private config;
+    private getToken;
+    private onSessionExpired?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    private buildHeaders;
+    private decode;
+    /**
+     * Submit a sale for fiscalization.
+     *
+     * The sale is durably recorded the moment this returns; fiscal numbers and
+     * the authority's certification follow asynchronously — poll `status()`
+     * with the same `clientRef` to watch it.
+     *
+     * **On timeout, do not resubmit blindly.** The sale may have fiscalized
+     * anyway: the request reached the server and the response was lost. Poll
+     * `status()` with the same `clientRef` instead, which is idempotent and
+     * tells you what actually happened.
+     *
+     * @param clientRef your own reference for this sale; the idempotency key
+     *   and the handle you poll and render receipts by.
+     */
+    submit(params: {
+        deviceId: string;
+        clientRef: string;
+        payload: Record<string, unknown>;
+        timeoutMs?: number;
+    }): Promise<FiscalIntentResult>;
+    /**
+     * Read an intent's current state by the reference it was submitted under.
+     *
+     * This is the receipt-rendering read: once the status is `fiscalized`, the
+     * `certification` carries what the receipt must show — for Ghana, the
+     * signature, receipt number and QR verification URL.
+     */
+    status(params: {
+        deviceId: string;
+        clientRef: string;
+        timeoutMs?: number;
+    }): Promise<FiscalIntentResult>;
+}

package/dist/cjs/fiscal.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseFiscal = exports.KoolbaseFiscalError = void 0;
+exports.isFiscalized = isFiscalized;
+exports.isPending = isPending;
+exports.decodeFiscalResponse = decodeFiscalResponse;
+const errors_js_1 = require("./errors.js");
+const KNOWN_STATUSES = [
+    'created', 'blocked', 'queued', 'submitting',
+    'retrying', 'fiscalized', 'attention', 'voided',
+];
+function parseStatus(raw) {
+    return typeof raw === 'string' && KNOWN_STATUSES.includes(raw)
+        ? raw
+        : 'unknown';
+}
+/** True once the authority has certified the document. */
+function isFiscalized(r) {
+    return r.status === 'fiscalized';
+}
+/** True while delivery to the authority is still in progress. */
+function isPending(r) {
+    return r.status === 'queued'
+        || r.status === 'submitting'
+        || r.status === 'retrying';
+}
+/** A fiscal request that failed. Carries the HTTP status where there was one. */
+class KoolbaseFiscalError extends errors_js_1.KoolbaseError {
+    constructor(message, statusCode) {
+        super(message, 'fiscal_failed');
+        this.statusCode = statusCode;
+        this.name = 'KoolbaseFiscalError';
+        Object.setPrototypeOf(this, KoolbaseFiscalError.prototype);
+    }
+}
+exports.KoolbaseFiscalError = KoolbaseFiscalError;
+function resultFromJson(json) {
+    const numbers = json.numbers;
+    return {
+        intentId: String(json.intent_id ?? ''),
+        status: parseStatus(json.status),
+        blockedReason: json.blocked_reason,
+        numbers: numbers ?? undefined,
+        sealedAt: json.sealed_at,
+        certification: json.certification,
+    };
+}
+/**
+ * Classify a response. Status and body in, result or error out.
+ *
+ * Exported for testability, and because auth handling belongs with the
+ * session hook rather than here — the same split the Flutter SDK makes.
+ */
+async function decodeFiscalResponse(status, body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new KoolbaseFiscalError(`fiscal: unreadable response (${status})`, status);
+    }
+    if ((status >= 200 && status < 300) || status === 202) {
+        return resultFromJson(parsed);
+    }
+    throw new KoolbaseFiscalError(parsed.error ?? 'fiscal: request failed', status);
+}
+// ─── KoolbaseFiscal ──────────────────────────────────────────────────────────
+/**
+ * Koolbase Fiscal — submitting sales to a tax authority.
+ *
+ * Jurisdiction-neutral: the SDK moves payloads and reads back whatever the
+ * authority certified. Ghana's GRA E-VAT is the first jurisdiction; nothing
+ * here names it.
+ */
+class KoolbaseFiscal {
+    constructor(config, getToken, onSessionExpired) {
+        this.config = config;
+        this.getToken = getToken;
+        this.onSessionExpired = onSessionExpired;
+    }
+    async buildHeaders() {
+        const token = await this.getToken();
+        return {
+            'Content-Type': 'application/json',
+            'x-api-key': this.config.publicKey,
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        };
+    }
+    async decode(res) {
+        if (res.status === 401 || res.status === 403) {
+            await this.onSessionExpired?.();
+            throw new errors_js_1.KoolbaseUnauthenticatedError(`fiscal: unauthenticated (${res.status})`);
+        }
+        return decodeFiscalResponse(res.status, await res.text());
+    }
+    /**
+     * Submit a sale for fiscalization.
+     *
+     * The sale is durably recorded the moment this returns; fiscal numbers and
+     * the authority's certification follow asynchronously — poll `status()`
+     * with the same `clientRef` to watch it.
+     *
+     * **On timeout, do not resubmit blindly.** The sale may have fiscalized
+     * anyway: the request reached the server and the response was lost. Poll
+     * `status()` with the same `clientRef` instead, which is idempotent and
+     * tells you what actually happened.
+     *
+     * @param clientRef your own reference for this sale; the idempotency key
+     *   and the handle you poll and render receipts by.
+     */
+    async submit(params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 30000);
+        try {
+            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
+                method: 'POST',
+                headers: await this.buildHeaders(),
+                signal: controller.signal,
+                body: JSON.stringify({
+                    device_id: params.deviceId,
+                    client_ref: params.clientRef,
+                    payload: params.payload,
+                }),
+            });
+            return await this.decode(res);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === 'AbortError') {
+                throw new KoolbaseFiscalError('fiscal submit timed out — the sale may still fiscalize; '
+                    + 'poll status with the same clientRef');
+            }
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Read an intent's current state by the reference it was submitted under.
+     *
+     * This is the receipt-rendering read: once the status is `fiscalized`, the
+     * `certification` carries what the receipt must show — for Ghana, the
+     * signature, receipt number and QR verification URL.
+     */
+    async status(params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 15000);
+        try {
+            const q = new URLSearchParams({
+                device_id: params.deviceId,
+                client_ref: params.clientRef,
+            });
+            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
+            return await this.decode(res);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === 'AbortError') {
+                throw new KoolbaseFiscalError('fiscal status timed out');
+            }
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.KoolbaseFiscal = KoolbaseFiscal;

package/dist/cjs/index.d.ts

@@ -14,6 +14,8 @@ export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseStorage } from './storage.js';
 export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
+export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';
 export type { RegisterTokenOptions } from './messaging.js';
 export { getOrCreateDeviceId } from './device-id.js';

package/dist/cjs/index.js

@@ -19,7 +19,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
+exports.memoryPlatform = exports.getPlatform = exports.setPlatform = exports.RestoreResult = exports.koolbaseSdkVersion = exports.getOrCreateDeviceId = exports.KoolbaseMessaging = exports.isPending = exports.isFiscalized = exports.decodeFiscalResponse = exports.KoolbaseFiscalError = exports.KoolbaseFiscal = exports.KoolbaseAnalytics = exports.KoolbaseStorage = exports.KoolbaseRealtime = exports.KoolbaseFunctions = exports.KoolbaseFlags = exports.KoolbaseDatabase = exports.KoolbaseAuth = void 0;
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./errors.js"), exports);
 __exportStar(require("./aggregate.js"), exports);
@@ -43,6 +43,12 @@ var storage_js_1 = require("./storage.js");
 Object.defineProperty(exports, "KoolbaseStorage", { enumerable: true, get: function () { return storage_js_1.KoolbaseStorage; } });
 var analytics_js_1 = require("./analytics.js");
 Object.defineProperty(exports, "KoolbaseAnalytics", { enumerable: true, get: function () { return analytics_js_1.KoolbaseAnalytics; } });
+var fiscal_js_1 = require("./fiscal.js");
+Object.defineProperty(exports, "KoolbaseFiscal", { enumerable: true, get: function () { return fiscal_js_1.KoolbaseFiscal; } });
+Object.defineProperty(exports, "KoolbaseFiscalError", { enumerable: true, get: function () { return fiscal_js_1.KoolbaseFiscalError; } });
+Object.defineProperty(exports, "decodeFiscalResponse", { enumerable: true, get: function () { return fiscal_js_1.decodeFiscalResponse; } });
+Object.defineProperty(exports, "isFiscalized", { enumerable: true, get: function () { return fiscal_js_1.isFiscalized; } });
+Object.defineProperty(exports, "isPending", { enumerable: true, get: function () { return fiscal_js_1.isPending; } });
 var messaging_js_1 = require("./messaging.js");
 Object.defineProperty(exports, "KoolbaseMessaging", { enumerable: true, get: function () { return messaging_js_1.KoolbaseMessaging; } });
 var device_id_js_1 = require("./device-id.js");

package/dist/esm/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();
 }

package/dist/esm/auth-errors.js

@@ -162,6 +162,18 @@ export class InvalidPhoneNumberError extends KoolbaseAuthError {
         Object.setPrototypeOf(this, InvalidPhoneNumberError.prototype);
     }
 }
+/**
+ * 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 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);
+    }
+}
 export class OtpExpiredError extends KoolbaseAuthError {
     constructor() {
         super('OTP has expired, please request a new code', 'otp_expired');

package/dist/esm/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,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 {
@@ -821,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) {
@@ -1027,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/fiscal.d.ts

@@ -0,0 +1,114 @@
+import { KoolbaseConfig } from './types.js';
+import { KoolbaseError } from './errors.js';
+/**
+ * The lifecycle status of a fiscal intent.
+ *
+ * A sale is durably recorded the moment `submit` returns; fiscal numbers and
+ * the authority's certification follow this state machine:
+ *
+ * - `queued` / `submitting` / `retrying` — sealed with allocated numbers;
+ *   delivery to the authority is in progress.
+ * - `fiscalized` — the authority answered; for certifying document kinds the
+ *   `certification` is present.
+ * - `blocked` — a precondition failed BEFORE any fiscal number was consumed
+ *   (see `blockedReason`). Resubmitting the same `clientRef` after fixing the
+ *   cause resumes it.
+ * - `attention` — the authority rejected the document, or its credential died
+ *   after sealing. An operator resolves it; the register's chain waits behind
+ *   it.
+ * - `voided` — terminally closed by an operator without fiscalization.
+ *
+ * `unknown` is the forward-compatible fallback: a status this SDK version has
+ * not heard of parses as unknown rather than throwing, so a server that grows
+ * a state does not break older clients.
+ */
+export type FiscalStatus = 'created' | 'blocked' | 'queued' | 'submitting' | 'retrying' | 'fiscalized' | 'attention' | 'voided' | 'unknown';
+/**
+ * The state of one fiscal intent.
+ *
+ * Jurisdiction-neutral by design: this SDK never learns a jurisdiction's
+ * vocabulary. Payloads travel as objects shaped by the device's adapter, and
+ * `certification` comes back as the authority granted it — for Ghana that
+ * means `ysdcregsig`, `ysdcrecnum`, `qr_code` and so on, which the SDK
+ * passes through without naming.
+ */
+export interface FiscalIntentResult {
+    intentId: string;
+    status: FiscalStatus;
+    /** Why a `blocked` intent stopped, when the server said. */
+    blockedReason?: string;
+    /** Fiscal numbers allocated at sealing. */
+    numbers?: Record<string, number>;
+    /** When the intent was sealed and its numbers allocated. */
+    sealedAt?: string;
+    /**
+     * What the authority granted, once `status` is `fiscalized`. This is the
+     * receipt-rendering payload: for Ghana, the signature, receipt number and
+     * QR verification URL.
+     */
+    certification?: Record<string, unknown>;
+}
+/** True once the authority has certified the document. */
+export declare function isFiscalized(r: FiscalIntentResult): boolean;
+/** True while delivery to the authority is still in progress. */
+export declare function isPending(r: FiscalIntentResult): boolean;
+/** A fiscal request that failed. Carries the HTTP status where there was one. */
+export declare class KoolbaseFiscalError extends KoolbaseError {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Classify a response. Status and body in, result or error out.
+ *
+ * Exported for testability, and because auth handling belongs with the
+ * session hook rather than here — the same split the Flutter SDK makes.
+ */
+export declare function decodeFiscalResponse(status: number, body: string): Promise<FiscalIntentResult>;
+/**
+ * Koolbase Fiscal — submitting sales to a tax authority.
+ *
+ * Jurisdiction-neutral: the SDK moves payloads and reads back whatever the
+ * authority certified. Ghana's GRA E-VAT is the first jurisdiction; nothing
+ * here names it.
+ */
+export declare class KoolbaseFiscal {
+    private config;
+    private getToken;
+    private onSessionExpired?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    private buildHeaders;
+    private decode;
+    /**
+     * Submit a sale for fiscalization.
+     *
+     * The sale is durably recorded the moment this returns; fiscal numbers and
+     * the authority's certification follow asynchronously — poll `status()`
+     * with the same `clientRef` to watch it.
+     *
+     * **On timeout, do not resubmit blindly.** The sale may have fiscalized
+     * anyway: the request reached the server and the response was lost. Poll
+     * `status()` with the same `clientRef` instead, which is idempotent and
+     * tells you what actually happened.
+     *
+     * @param clientRef your own reference for this sale; the idempotency key
+     *   and the handle you poll and render receipts by.
+     */
+    submit(params: {
+        deviceId: string;
+        clientRef: string;
+        payload: Record<string, unknown>;
+        timeoutMs?: number;
+    }): Promise<FiscalIntentResult>;
+    /**
+     * Read an intent's current state by the reference it was submitted under.
+     *
+     * This is the receipt-rendering read: once the status is `fiscalized`, the
+     * `certification` carries what the receipt must show — for Ghana, the
+     * signature, receipt number and QR verification URL.
+     */
+    status(params: {
+        deviceId: string;
+        clientRef: string;
+        timeoutMs?: number;
+    }): Promise<FiscalIntentResult>;
+}

package/dist/esm/fiscal.js

@@ -0,0 +1,159 @@
+import { KoolbaseError, KoolbaseUnauthenticatedError } from './errors.js';
+const KNOWN_STATUSES = [
+    'created', 'blocked', 'queued', 'submitting',
+    'retrying', 'fiscalized', 'attention', 'voided',
+];
+function parseStatus(raw) {
+    return typeof raw === 'string' && KNOWN_STATUSES.includes(raw)
+        ? raw
+        : 'unknown';
+}
+/** True once the authority has certified the document. */
+export function isFiscalized(r) {
+    return r.status === 'fiscalized';
+}
+/** True while delivery to the authority is still in progress. */
+export function isPending(r) {
+    return r.status === 'queued'
+        || r.status === 'submitting'
+        || r.status === 'retrying';
+}
+/** A fiscal request that failed. Carries the HTTP status where there was one. */
+export class KoolbaseFiscalError extends KoolbaseError {
+    constructor(message, statusCode) {
+        super(message, 'fiscal_failed');
+        this.statusCode = statusCode;
+        this.name = 'KoolbaseFiscalError';
+        Object.setPrototypeOf(this, KoolbaseFiscalError.prototype);
+    }
+}
+function resultFromJson(json) {
+    const numbers = json.numbers;
+    return {
+        intentId: String(json.intent_id ?? ''),
+        status: parseStatus(json.status),
+        blockedReason: json.blocked_reason,
+        numbers: numbers ?? undefined,
+        sealedAt: json.sealed_at,
+        certification: json.certification,
+    };
+}
+/**
+ * Classify a response. Status and body in, result or error out.
+ *
+ * Exported for testability, and because auth handling belongs with the
+ * session hook rather than here — the same split the Flutter SDK makes.
+ */
+export async function decodeFiscalResponse(status, body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new KoolbaseFiscalError(`fiscal: unreadable response (${status})`, status);
+    }
+    if ((status >= 200 && status < 300) || status === 202) {
+        return resultFromJson(parsed);
+    }
+    throw new KoolbaseFiscalError(parsed.error ?? 'fiscal: request failed', status);
+}
+// ─── KoolbaseFiscal ──────────────────────────────────────────────────────────
+/**
+ * Koolbase Fiscal — submitting sales to a tax authority.
+ *
+ * Jurisdiction-neutral: the SDK moves payloads and reads back whatever the
+ * authority certified. Ghana's GRA E-VAT is the first jurisdiction; nothing
+ * here names it.
+ */
+export class KoolbaseFiscal {
+    constructor(config, getToken, onSessionExpired) {
+        this.config = config;
+        this.getToken = getToken;
+        this.onSessionExpired = onSessionExpired;
+    }
+    async buildHeaders() {
+        const token = await this.getToken();
+        return {
+            'Content-Type': 'application/json',
+            'x-api-key': this.config.publicKey,
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        };
+    }
+    async decode(res) {
+        if (res.status === 401 || res.status === 403) {
+            await this.onSessionExpired?.();
+            throw new KoolbaseUnauthenticatedError(`fiscal: unauthenticated (${res.status})`);
+        }
+        return decodeFiscalResponse(res.status, await res.text());
+    }
+    /**
+     * Submit a sale for fiscalization.
+     *
+     * The sale is durably recorded the moment this returns; fiscal numbers and
+     * the authority's certification follow asynchronously — poll `status()`
+     * with the same `clientRef` to watch it.
+     *
+     * **On timeout, do not resubmit blindly.** The sale may have fiscalized
+     * anyway: the request reached the server and the response was lost. Poll
+     * `status()` with the same `clientRef` instead, which is idempotent and
+     * tells you what actually happened.
+     *
+     * @param clientRef your own reference for this sale; the idempotency key
+     *   and the handle you poll and render receipts by.
+     */
+    async submit(params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 30000);
+        try {
+            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/submit`, {
+                method: 'POST',
+                headers: await this.buildHeaders(),
+                signal: controller.signal,
+                body: JSON.stringify({
+                    device_id: params.deviceId,
+                    client_ref: params.clientRef,
+                    payload: params.payload,
+                }),
+            });
+            return await this.decode(res);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === 'AbortError') {
+                throw new KoolbaseFiscalError('fiscal submit timed out — the sale may still fiscalize; '
+                    + 'poll status with the same clientRef');
+            }
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Read an intent's current state by the reference it was submitted under.
+     *
+     * This is the receipt-rendering read: once the status is `fiscalized`, the
+     * `certification` carries what the receipt must show — for Ghana, the
+     * signature, receipt number and QR verification URL.
+     */
+    async status(params) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), params.timeoutMs ?? 15000);
+        try {
+            const q = new URLSearchParams({
+                device_id: params.deviceId,
+                client_ref: params.clientRef,
+            });
+            const res = await fetch(`${this.config.baseUrl}/v1/sdk/fiscal/status?${q.toString()}`, { method: 'GET', headers: await this.buildHeaders(), signal: controller.signal });
+            return await this.decode(res);
+        }
+        catch (e) {
+            if (e instanceof Error && e.name === 'AbortError') {
+                throw new KoolbaseFiscalError('fiscal status timed out');
+            }
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/esm/index.d.ts

@@ -14,6 +14,8 @@ export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseStorage } from './storage.js';
 export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
+export type { FiscalIntentResult, FiscalStatus } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';
 export type { RegisterTokenOptions } from './messaging.js';
 export { getOrCreateDeviceId } from './device-id.js';

package/dist/esm/index.js

@@ -19,6 +19,7 @@ export { KoolbaseFunctions } from './functions.js';
 export { KoolbaseRealtime } from './realtime.js';
 export { KoolbaseStorage } from './storage.js';
 export { KoolbaseAnalytics } from './analytics.js';
+export { KoolbaseFiscal, KoolbaseFiscalError, decodeFiscalResponse, isFiscalized, isPending } from './fiscal.js';
 export { KoolbaseMessaging } from './messaging.js';
 export { getOrCreateDeviceId } from './device-id.js';
 export { koolbaseSdkVersion } from './device-metadata.js';

package/package.json

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