@koolbase/core 11.4.0 → 12.1.0

package/dist/cjs/auth.js

@@ -133,6 +133,22 @@ class KoolbaseAuth {
         return this.authRequest(path, { ...options, includeAuth: true });
     }
     // ─── Internal session lifecycle ─────────────────────────────────────────
+    /**
+     * Replace the user inside the current session and persist it.
+     *
+     * A profile update or a fresh fetch changes the user, not the tokens.
+     * Without this the new values live only in the returned object: the cached
+     * `currentUser` stays stale, anything bound to `onAuthStateChange` never
+     * hears about the change, and a reload restores the old name.
+     *
+     * No session means nobody is signed in, and there is nothing to update —
+     * the caller's own request would have failed first.
+     */
+    async updateUserAndPersist(user) {
+        if (!this.session)
+            return;
+        await this.setSessionInternal({ ...this.session, user });
+    }
     async setSessionInternal(session) {
         this.session = session;
         if (this.storage) {
@@ -586,6 +602,188 @@ class KoolbaseAuth {
             cooldownUntil: body.cooldown_until ? new Date(body.cooldown_until) : null,
         };
     }
+    /**
+     * The signed-in user, fetched fresh from the server.
+     *
+     * `currentUser` returns what was cached at sign-in; this asks. Use it when
+     * something may have changed the user server-side — a verification
+     * completing, a profile updated from another device — and persist the
+     * result so the cached copy stops being stale.
+     */
+    async getCurrentUser() {
+        const res = await this.authRequest('/v1/sdk/auth/me', {
+            method: 'GET',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const user = this.mapUser(await res.json());
+        await this.updateUserAndPersist(user);
+        return user;
+    }
+    /**
+     * Update the signed-in user's profile.
+     *
+     * Only the fields given are sent, so passing one leaves the other
+     * untouched. The updated user is persisted, so `currentUser` reflects it
+     * without a refetch.
+     */
+    async updateProfile(params) {
+        const body = {};
+        if (params.fullName !== undefined)
+            body.full_name = params.fullName;
+        if (params.avatarUrl !== undefined)
+            body.avatar_url = params.avatarUrl;
+        const res = await this.authRequest('/v1/sdk/auth/me', {
+            method: 'PATCH',
+            body,
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const user = this.mapUser(await res.json());
+        await this.updateUserAndPersist(user);
+        return user;
+    }
+    /**
+     * Change the signed-in user's password.
+     *
+     * The current password is required: a stolen session should not be enough
+     * to lock the real owner out. A wrong one throws
+     * CurrentPasswordIncorrectError — the server returns `invalid_password`,
+     * which reads like a rejected new password and means the opposite.
+     *
+     * An account that signed up through Google or Apple has no password to
+     * change and gets the same error, deliberately, so a caller cannot probe
+     * which sign-in methods an account has.
+     */
+    async changePassword(params) {
+        if (params.newPassword.length < 8)
+            throw new auth_errors_js_1.WeakPasswordError();
+        const res = await this.authRequest('/v1/sdk/auth/me/password', {
+            method: 'PATCH',
+            body: {
+                current_password: params.currentPassword,
+                new_password: params.newPassword,
+            },
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+    }
+    /**
+     * Delete the signed-in user's account, and sign out.
+     *
+     * Deletes the caller only — there is no user id to pass, which is the
+     * security property. The server removes the auth record and every session
+     * on every device, then fires an `auth.user.deleted` trigger.
+     *
+     * It does NOT delete the account's records in your collections. Koolbase
+     * cannot know whether a row should be deleted, anonymised, or kept for a
+     * statutory retention period. Subscribe a Function to `auth.user.deleted`
+     * and clean up there — it runs server-side, so a tab closing mid-flow
+     * cannot strand anything.
+     */
+    async deleteAccount() {
+        const res = await this.authRequest('/v1/sdk/auth/me', {
+            method: 'DELETE',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        await this.clearSessionInternal();
+    }
+    /**
+     * Every session the signed-in user has — a "where you're signed in" list.
+     *
+     * Newest first is not guaranteed; sort by createdAt if the order matters.
+     * The entry with `isCurrent` is this device.
+     */
+    async listSessions() {
+        const res = await this.authRequest('/v1/sdk/auth/sessions', {
+            method: 'GET',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const body = (await res.json());
+        return (body.sessions ?? []).map((s) => {
+            const r = s;
+            return {
+                id: String(r.id),
+                ip: r.ip,
+                userAgent: r.user_agent,
+                deviceLabel: r.device_label,
+                createdAt: String(r.created_at),
+                expiresAt: String(r.expires_at),
+                isCurrent: Boolean(r.is_current),
+            };
+        });
+    }
+    /**
+     * Sign out one session by id.
+     *
+     * Revoking the current one ends this session too — the server does not
+     * refuse it, and the local session is cleared here so the app does not keep
+     * a token the server has dropped. Use logout() when that is what you mean.
+     */
+    async revokeSession(sessionId) {
+        const res = await this.authRequest(`/v1/sdk/auth/sessions/${encodeURIComponent(sessionId)}/revoke`, { method: 'POST', includeAuth: true });
+        await this.checkResponse(res);
+        // Revoking your own session leaves a token the server has dropped. The
+        // SDK cannot tell from the response which one it was, and re-listing to
+        // find out would cost a request on every revoke — so it asks the only
+        // party that already knows: the next request. If it was this session,
+        // that request 401s and the normal refresh path clears it.
+        //
+        // A UI listing sessions knows which row is current from isCurrent, and
+        // should call logout() rather than revokeSession() for that one, which
+        // is both clearer to the user and one fewer round trip.
+    }
+    /**
+     * Sign out every OTHER session, keeping this one.
+     *
+     * What "sign out my other devices" means after a lost phone. Returns how
+     * many were ended, so an app can say so rather than guess.
+     */
+    async revokeAllOtherSessions() {
+        const res = await this.authRequest('/v1/sdk/auth/sessions/revoke-all', {
+            method: 'POST',
+            includeAuth: true,
+        });
+        await this.checkResponse(res);
+        const body = (await res.json().catch(() => ({})));
+        return body.revoked_count ?? 0;
+    }
+    /**
+     * What has happened to this account — sign-ins, failures, lockouts,
+     * password changes.
+     *
+     * For a "recent security activity" screen. The server sanitizes each
+     * event, so this carries what that event type is allowed to say and
+     * nothing more.
+     *
+     * @param limit up to 200; the server caps it there.
+     */
+    async auditLog(options) {
+        const params = new URLSearchParams();
+        if (options?.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options?.offset !== undefined)
+            params.set('offset', String(options.offset));
+        const qs = params.toString();
+        const res = await this.authRequest(`/v1/sdk/auth/audit${qs ? `?${qs}` : ''}`, { method: 'GET', includeAuth: true });
+        await this.checkResponse(res);
+        const body = (await res.json());
+        return {
+            events: (body.events ?? []).map((e) => ({
+                id: String(e.id),
+                eventType: String(e.event_type),
+                occurredAt: String(e.occurred_at),
+                ip: e.ip,
+                userAgent: e.user_agent,
+                eventData: e.event_data ?? {},
+            })),
+            total: Number(body.total ?? 0),
+            limit: Number(body.limit ?? 0),
+            offset: Number(body.offset ?? 0),
+        };
+    }
     async unlock(token) {
         const res = await this.authRequest('/v1/sdk/auth/unlock', {
             method: 'POST',
@@ -626,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) {
@@ -832,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/database.d.ts

@@ -1,3 +1,4 @@
+import { KoolbaseAggregateRequest, KoolbaseAggregateResult } from './aggregate.js';
 import { KoolbaseConflict } from './conflict.js';
 import { PendingWrite } from './pending-write.js';
 import { KoolbaseConfig, KoolbaseRecord, QueryOptions, QueryResult, UpsertResult, BatchOp, BatchResult, KoolbaseVector, SemanticSearchResult, SearchMode } from './types.js';
@@ -127,6 +128,28 @@ export declare class KoolbaseDatabase {
      * moment matters. Snapshot, not a live handle; per-user.
      */
     pendingWrites(): Promise<PendingWrite[]>;
+    /**
+     * Count and total over a whole collection, with the read rule applied
+     * inside the query.
+     *
+     * Not a paged query you add up yourself: the server aggregates the entire
+     * authorized set. And never a bare number — collections are schemaless, so
+     * a sum that quietly skipped three malformed rows would be a wrong number
+     * that looks right. Check `accounting` for what contributed.
+     *
+     * ```ts
+     * const r = await db.aggregate({
+     *   collection: 'orders',
+     *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+     *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+     * });
+     * ```
+     *
+     * A calendar bucket requires a timezone and the types enforce it: midnight
+     * means nothing without one, and Accra and UTC disagree about which day a
+     * 23:30 sale belongs to.
+     */
+    aggregate(request: KoolbaseAggregateRequest): Promise<KoolbaseAggregateResult>;
     conflicts(): Promise<KoolbaseConflict[]>;
     /**
      * Resolves by id, reloading the stored conflict first.

package/dist/cjs/database.js

@@ -424,6 +424,70 @@ class KoolbaseDatabase {
         const { pending } = await (0, offline_state_js_1.readOfflineState)(userId);
         return pending.map(pending_write_js_1.toPendingWrite);
     }
+    /**
+     * Count and total over a whole collection, with the read rule applied
+     * inside the query.
+     *
+     * Not a paged query you add up yourself: the server aggregates the entire
+     * authorized set. And never a bare number — collections are schemaless, so
+     * a sum that quietly skipped three malformed rows would be a wrong number
+     * that looks right. Check `accounting` for what contributed.
+     *
+     * ```ts
+     * const r = await db.aggregate({
+     *   collection: 'orders',
+     *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+     *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+     * });
+     * ```
+     *
+     * A calendar bucket requires a timezone and the types enforce it: midnight
+     * means nothing without one, and Accra and UTC disagree about which day a
+     * 23:30 sale belongs to.
+     */
+    async aggregate(request) {
+        const raw = await this.request('POST', '/v1/sdk/db/aggregate', {
+            collection: request.collection,
+            ...(request.where?.length ? { where: request.where } : {}),
+            ...(request.groupBy
+                ? {
+                    group_by: {
+                        field: request.groupBy.field,
+                        ...(request.groupBy.bucket
+                            ? {
+                                bucket: request.groupBy.bucket,
+                                timezone: request.groupBy.timezone,
+                            }
+                            : {}),
+                    },
+                }
+                : {}),
+            measures: request.measures.map((m) => ({
+                aggregate: m.aggregate,
+                ...(m.field ? { field: m.field } : {}),
+                as: m.as,
+            })),
+        });
+        const accounting = {};
+        for (const [name, a] of Object.entries(raw.accounting ?? {})) {
+            accounting[name] = {
+                counted: Number(a.counted ?? 0),
+                skipped: Number(a.skipped ?? 0),
+                skippedReason: a.skipped_reason,
+            };
+        }
+        return {
+            groups: (raw.groups ?? []).map((g) => ({
+                category: String(g.category ?? ''),
+                values: g.values ?? {},
+            })),
+            matched: Number(raw.matched ?? 0),
+            accounting,
+            // Explicitly boolean: a missing field must read as false, not
+            // undefined, or `if (!r.tooManyGroups)` passes on a refused request.
+            tooManyGroups: raw.too_many_groups === true,
+        };
+    }
     async conflicts() {
         const userId = this.requireUserId('the conflict list');
         const { conflicts } = await (0, offline_state_js_1.readOfflineState)(userId);

package/dist/cjs/device-metadata.js

@@ -52,7 +52,13 @@ class DeviceMetadata {
         if (this.cached)
             return this.cached;
         const platform = (0, platform_js_1.getPlatform)().info.os;
-        const platformVersion = (0, platform_js_1.getPlatform)().info.version;
+        // 'unknown' rather than empty, matching appVersion above. A browser
+        // outside the handful browserVersion() recognises — Brave, Opera,
+        // Samsung Internet, an in-app webview — reports nothing, and an empty
+        // header stored against a session is indistinguishable from an SDK that
+        // never reported itself at all. 'unknown' says the SDK spoke and could
+        // not identify the host, which is a different and more useful fact.
+        const platformVersion = (0, platform_js_1.getPlatform)().info.version || 'unknown';
         const deviceLabel = await this.getOrCreateDeviceLabel();
         // No User-Agent: a browser forbids setting it, and the same header set
         // now goes out from both hosts. The platform and version below carry

package/dist/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>;
+}