@koolbase/core 11.4.0 → 12.1.0

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

@@ -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/cjs/index.js

@@ -19,9 +19,10 @@ 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);
 __exportStar(require("./conflict.js"), exports);
 __exportStar(require("./pending-write.js"), exports);
 __exportStar(require("./function-errors.js"), exports);
@@ -42,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/cjs/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/dist/esm/aggregate.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Asking "how many" and "how much" over a collection, correctly.
+ *
+ * Correct means the whole authorized set — never the first page — with the
+ * caller's read rule applied inside the query, and never a bare number:
+ * collections are schemaless, so a total that quietly excluded three
+ * malformed rows would be a wrong number that looks right. Every result
+ * carries its accounting.
+ *
+ * ```ts
+ * const r = await Koolbase.db.aggregate({
+ *   collection: 'orders',
+ *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+ *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+ * });
+ *
+ * for (const g of r.groups) {
+ *   console.log(g.category, g.values.revenue);
+ * }
+ * if (r.accounting.revenue.skipped > 0) {
+ *   // some orders had a total that was not a number — say so
+ * }
+ * ```
+ */
+/** A record filter, AND-ed on top of the read rule. */
+export interface KoolbaseAggregateFilter {
+    field: string;
+    op: 'eq' | 'neq' | 'in' | 'gt' | 'gte' | 'lt' | 'lte';
+    value: unknown;
+}
+/**
+ * The category axis: a field's value, or a calendar bucket of a timestamp
+ * field.
+ *
+ * A bucket REQUIRES a timezone, and the union makes omitting it a type
+ * error. "Midnight" means nothing without one — Africa/Accra and UTC
+ * disagree about which day a 23:30 sale belongs to — and the API refuses a
+ * bucket that arrives without one.
+ */
+export type KoolbaseGroupBy = {
+    field: string;
+    bucket?: never;
+    timezone?: never;
+} | {
+    field: string;
+    bucket: 'day' | 'week' | 'month' | 'year';
+    timezone: string;
+};
+/**
+ * One number per group.
+ *
+ * `count` counts RECORDS, so it takes no field and skips nothing. The others
+ * read a field, and a record whose value is missing or not a number is
+ * skipped and reported in the result's accounting.
+ */
+export type KoolbaseMeasure = {
+    aggregate: 'count';
+    field?: never;
+    as: string;
+} | {
+    aggregate: 'sum' | 'avg' | 'min' | 'max';
+    field: string;
+    as: string;
+};
+/** One aggregation request. */
+export interface KoolbaseAggregateRequest {
+    collection: string;
+    /** AND-ed record filters on top of the read rule. */
+    where?: KoolbaseAggregateFilter[];
+    /** Absent means one group: the measures over everything. */
+    groupBy?: KoolbaseGroupBy;
+    /** At least one. */
+    measures: KoolbaseMeasure[];
+}
+/** One category and its numbers. */
+export interface KoolbaseAggregateGroup {
+    /** Empty string for the single group when there was no groupBy. */
+    category: string;
+    /** Keyed by each measure's `as`. Null where a group had nothing to measure. */
+    values: Record<string, number | null>;
+}
+/**
+ * How a measure arrived at its number.
+ *
+ * `skipped` is not an error. It is what you need to decide whether the
+ * number means what it appears to mean — a revenue total over 900 of 903
+ * orders is a different fact from one over all of them, and only this says
+ * which you are looking at.
+ */
+export interface KoolbaseAggregateAccounting {
+    counted: number;
+    skipped: number;
+    /** Present when skipped > 0. */
+    skippedReason?: 'missing' | 'not_numeric' | 'mixed';
+}
+/** The whole answer, including what could not be counted. */
+export interface KoolbaseAggregateResult {
+    /**
+     * One per category, sorted — or exactly one with an empty category when
+     * there was no groupBy.
+     */
+    groups: KoolbaseAggregateGroup[];
+    /** Records that matched the read rule and filters: the denominator. */
+    matched: number;
+    /** Per measure name, keyed by its `as`. */
+    accounting: Record<string, KoolbaseAggregateAccounting>;
+    /**
+     * True when the groupBy produced more categories than allowed and the
+     * whole request was refused.
+     *
+     * `groups` is EMPTY when this is set: a partial set drawn as the whole
+     * would be exactly the wrong number this API exists to prevent.
+     */
+    tooManyGroups: boolean;
+}

package/dist/esm/aggregate.js

@@ -0,0 +1,25 @@
+/**
+ * Asking "how many" and "how much" over a collection, correctly.
+ *
+ * Correct means the whole authorized set — never the first page — with the
+ * caller's read rule applied inside the query, and never a bare number:
+ * collections are schemaless, so a total that quietly excluded three
+ * malformed rows would be a wrong number that looks right. Every result
+ * carries its accounting.
+ *
+ * ```ts
+ * const r = await Koolbase.db.aggregate({
+ *   collection: 'orders',
+ *   groupBy: { field: 'created_at', bucket: 'month', timezone: 'Africa/Accra' },
+ *   measures: [{ aggregate: 'sum', field: 'total', as: 'revenue' }],
+ * });
+ *
+ * for (const g of r.groups) {
+ *   console.log(g.category, g.values.revenue);
+ * }
+ * if (r.accounting.revenue.skipped > 0) {
+ *   // some orders had a total that was not a number — say so
+ * }
+ * ```
+ */
+export {};

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

@@ -21,14 +21,14 @@ export class InvalidCredentialsError extends KoolbaseAuthError {
 }
 export class EmailAlreadyInUseError extends KoolbaseAuthError {
     constructor() {
-        super('Email is already in use', 'email_taken');
+        super('Email is already in use', 'email_in_use');
         this.name = 'EmailAlreadyInUseError';
         Object.setPrototypeOf(this, EmailAlreadyInUseError.prototype);
     }
 }
 export class UserDisabledError extends KoolbaseAuthError {
     constructor() {
-        super('This account has been disabled', 'user_disabled');
+        super('This account has been disabled', 'account_disabled');
         this.name = 'UserDisabledError';
         Object.setPrototypeOf(this, UserDisabledError.prototype);
     }
@@ -49,7 +49,7 @@ export class WeakPasswordError extends KoolbaseAuthError {
 // ─── Session lifecycle ─────────────────────────────────────────────────────
 export class SessionExpiredError extends KoolbaseAuthError {
     constructor() {
-        super('Session expired, please log in again', 'session_expired');
+        super('Session expired, please log in again', 'invalid_refresh_token');
         this.name = 'SessionExpiredError';
         Object.setPrototypeOf(this, SessionExpiredError.prototype);
     }
@@ -95,7 +95,7 @@ export class AccountLockedError extends KoolbaseAuthError {
  */
 export class UnlockTokenInvalidError extends KoolbaseAuthError {
     constructor() {
-        super('Unlock link is invalid or has expired', 'unlock_token_invalid');
+        super('Unlock link is invalid or has expired', 'invalid_unlock_token');
         this.name = 'UnlockTokenInvalidError';
         Object.setPrototypeOf(this, UnlockTokenInvalidError.prototype);
     }
@@ -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');
@@ -185,42 +197,42 @@ export class OtpMaxAttemptsError extends KoolbaseAuthError {
 }
 export class OtpRateLimitError extends KoolbaseAuthError {
     constructor() {
-        super('Too many OTP requests, please wait before trying again', 'otp_rate_limit');
+        super('Too many OTP requests, please wait before trying again', 'rate_limit');
         this.name = 'OtpRateLimitError';
         Object.setPrototypeOf(this, OtpRateLimitError.prototype);
     }
 }
 export class PhoneAlreadyLinkedError extends KoolbaseAuthError {
     constructor() {
-        super('Phone number is already associated with another account', 'phone_taken');
+        super('Phone number is already associated with another account', 'phone_in_use');
         this.name = 'PhoneAlreadyLinkedError';
         Object.setPrototypeOf(this, PhoneAlreadyLinkedError.prototype);
     }
 }
 export class SmsConfigMissingError extends KoolbaseAuthError {
     constructor() {
-        super('SMS provider not configured for this project', 'sms_config_missing');
+        super('SMS provider not configured for this project', 'sms_not_configured');
         this.name = 'SmsConfigMissingError';
         Object.setPrototypeOf(this, SmsConfigMissingError.prototype);
     }
 }
 export class AppleSignInNotConfiguredError extends KoolbaseAuthError {
     constructor() {
-        super('Apple Sign-In is not configured for this environment', 'apple_not_configured');
+        super('Apple Sign-In is not configured for this environment', 'oauth_not_configured');
         this.name = 'AppleSignInNotConfiguredError';
         Object.setPrototypeOf(this, AppleSignInNotConfiguredError.prototype);
     }
 }
 export class InvalidAppleTokenError extends KoolbaseAuthError {
     constructor() {
-        super('Invalid Apple identity token', 'invalid_apple_token');
+        super('Invalid Apple identity token', 'invalid_oauth_token');
         this.name = 'InvalidAppleTokenError';
         Object.setPrototypeOf(this, InvalidAppleTokenError.prototype);
     }
 }
 export class AppleEmailRequiredError extends KoolbaseAuthError {
     constructor() {
-        super('Apple did not return email for this sign-in. Revoke this app in iOS Settings → Apple ID and retry.', 'apple_email_required');
+        super('Apple did not return email for this sign-in. Revoke this app in iOS Settings → Apple ID and retry.', 'oauth_email_required');
         this.name = 'AppleEmailRequiredError';
         Object.setPrototypeOf(this, AppleEmailRequiredError.prototype);
     }
@@ -234,7 +246,7 @@ export class OAuthEmailConflictError extends KoolbaseAuthError {
 }
 export class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
     constructor() {
-        super('Google Sign-In is not configured for this environment', 'google_not_configured');
+        super('Google Sign-In is not configured for this environment', 'oauth_not_configured');
         this.name = 'GoogleSignInNotConfiguredError';
         Object.setPrototypeOf(this, GoogleSignInNotConfiguredError.prototype);
     }
@@ -414,14 +426,14 @@ export class MalformedSessionResponseError extends KoolbaseAuthError {
 }
 export class InvalidGoogleTokenError extends KoolbaseAuthError {
     constructor() {
-        super('Invalid Google identity token', 'invalid_google_token');
+        super('Invalid Google identity token', 'invalid_oauth_token');
         this.name = 'InvalidGoogleTokenError';
         Object.setPrototypeOf(this, InvalidGoogleTokenError.prototype);
     }
 }
 export class GoogleEmailRequiredError extends KoolbaseAuthError {
     constructor() {
-        super('Google did not return email for this sign-in. Ensure the email scope is requested in the native flow.', 'google_email_required');
+        super('Google did not return email for this sign-in. Ensure the email scope is requested in the native flow.', 'oauth_email_required');
         this.name = 'GoogleEmailRequiredError';
         Object.setPrototypeOf(this, GoogleEmailRequiredError.prototype);
     }