@koolbase/core 11.4.0 → 12.1.0

package/dist/esm/database.js

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

package/dist/esm/device-metadata.js

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

package/dist/esm/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

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './errors.js';
+export * from './aggregate.js';
 export * from './conflict.js';
 export * from './pending-write.js';
 export * from './function-errors.js';
@@ -13,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

@@ -5,6 +5,7 @@
 // code installs the platform package, never this one directly.
 export * from './types.js';
 export * from './errors.js';
+export * from './aggregate.js';
 export * from './conflict.js';
 export * from './pending-write.js';
 export * from './function-errors.js';
@@ -18,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/dist/esm/types.d.ts

@@ -88,6 +88,64 @@ export type SignUpResult = {
     user: KoolbaseUser;
     session: null;
 };
+/**
+ * One active session — somewhere the user is signed in.
+ *
+ * Token hashes are never included; the server excludes them deliberately.
+ */
+export interface KoolbaseSessionInfo {
+    id: string;
+    /** Where it signed in from, when the server captured it. */
+    ip?: string;
+    /** What signed in. A browser sets this; native SDKs send their own. */
+    userAgent?: string;
+    /** A per-install label, where the SDK supplied one. */
+    deviceLabel?: string;
+    createdAt: string;
+    expiresAt: string;
+    /**
+     * True for the session making the request.
+     *
+     * A device list needs this: without it a user cannot tell which row is the
+     * phone in their hand, and "sign out everywhere else" has nothing to
+     * exclude.
+     */
+    isCurrent: boolean;
+}
+/**
+ * One thing that happened to this account.
+ *
+ * The server sanitizes these: `eventData` carries only the fields allowed
+ * for that event type, so a lockout can say which address was attempted
+ * while a successful login carries nothing extra.
+ */
+export interface KoolbaseAuditEvent {
+    id: string;
+    /**
+     * What happened. One of: auth.login.success, auth.login.failed,
+     * auth.account.locked, auth.account.unlocked, auth.session.created,
+     * auth.session.refreshed, auth.session.revoked, auth.password.changed,
+     * auth.user.verified.
+     *
+     * A string rather than a union: the server may add one, and an app that
+     * stops compiling because it did would be worse than one that shows an
+     * event it does not recognise.
+     */
+    eventType: string;
+    occurredAt: string;
+    ip?: string;
+    userAgent?: string;
+    /** Whatever that event type is allowed to carry. Often empty. */
+    eventData: Record<string, unknown>;
+}
+/** A page of audit events, and how many there are in total. */
+export interface KoolbaseAuditPage {
+    events: KoolbaseAuditEvent[];
+    /** Across all pages, so an app knows whether to offer "show more". */
+    total: number;
+    limit: number;
+    offset: number;
+}
 export interface ResendVerificationResult {
     alreadyVerified: boolean;
     /** When the link in the email stops working. Null when nothing was sent. */

package/package.json

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