@koolbase/core 10.0.0

package/README.md

@@ -0,0 +1,19 @@
+# @koolbase/core
+
+The shared behaviour behind Koolbase's client SDKs. **Install a platform package,
+not this one:**
+
+- Browser — [`@koolbase/js`](https://www.npmjs.com/package/@koolbase/js)
+- React Native — [`@koolbase/react-native`](https://www.npmjs.com/package/@koolbase/react-native)
+
+Each of those depends on this package and composes it with a platform adapter
+for its host: storage, connectivity, lifecycle, and session persistence. The
+auth logic, database client, offline write queue, conflict resolution,
+realtime, storage and functions clients all live here, once, and are proven by
+one test suite run against every adapter.
+
+This package has no runtime dependencies and makes no assumptions about its
+host. If you are building a Koolbase SDK for a new platform, the
+`PlatformAdapter` interface in `src/platform.ts` is the contract.
+
+MIT

package/dist/cjs/analytics.d.ts

@@ -0,0 +1,24 @@
+import { KoolbaseConfig } from './types.js';
+export declare class KoolbaseAnalytics {
+    private config;
+    private queue;
+    private deviceId;
+    private userId?;
+    private environmentId?;
+    private userProperties;
+    private sessionId;
+    private appVersion;
+    private flushTimer?;
+    private initialized;
+    constructor(config: KoolbaseConfig);
+    init(appVersion?: string): Promise<void>;
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    screenView(screenName: string, properties?: Record<string, unknown>): void;
+    identify(userId: string): void;
+    setUserProperty(key: string, value: unknown): void;
+    setUserProperties(properties: Record<string, unknown>): void;
+    setEnvironment(environmentId: string): void;
+    reset(): void;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/cjs/analytics.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseAnalytics = void 0;
+const platform_js_1 = require("./platform.js");
+const device_id_js_1 = require("./device-id.js");
+// ─── KoolbaseAnalytics ───────────────────────────────────────────────────────
+const SDK_VERSION = '1.3.0';
+const DEVICE_ID_KEY = 'koolbase:device_id';
+const FLUSH_INTERVAL_MS = 30000;
+const MAX_BATCH_SIZE = 20;
+class KoolbaseAnalytics {
+    constructor(config) {
+        this.queue = [];
+        this.deviceId = '';
+        this.userProperties = {};
+        this.sessionId = '';
+        this.appVersion = '1.0.0';
+        this.initialized = false;
+        this.config = config;
+    }
+    // ─── Init ─────────────────────────────────────────────────────────────────
+    async init(appVersion) {
+        if (this.initialized)
+            return;
+        this.deviceId = await (0, device_id_js_1.getOrCreateDeviceId)();
+        this.sessionId = `${this.deviceId}-${Date.now()}`;
+        this.appVersion = appVersion ?? '1.0.0';
+        // Auto flush on app background
+        (0, platform_js_1.getPlatform)().lifecycle.onBackground(() => { this.flush(); });
+        // Periodic flush
+        this.flushTimer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+        // Auto track app_open
+        this.track('app_open');
+        this.initialized = true;
+    }
+    // ─── Public API ───────────────────────────────────────────────────────────
+    track(eventName, properties) {
+        const event = {
+            device_id: this.deviceId,
+            user_id: this.userId,
+            environment_id: this.environmentId,
+            event_name: eventName,
+            properties: properties ?? {},
+            user_properties: { ...this.userProperties },
+            platform: (0, platform_js_1.getPlatform)().info.os,
+            app_version: this.appVersion,
+            sdk_version: SDK_VERSION,
+            session_id: this.sessionId,
+            occurred_at: new Date().toISOString(),
+        };
+        this.queue.push(event);
+        if (this.queue.length >= MAX_BATCH_SIZE) {
+            this.flush();
+        }
+    }
+    screenView(screenName, properties) {
+        this.track('screen_view', {
+            screen_name: screenName,
+            ...properties,
+        });
+    }
+    identify(userId) {
+        this.userId = userId;
+    }
+    setUserProperty(key, value) {
+        this.userProperties[key] = value;
+    }
+    setUserProperties(properties) {
+        Object.assign(this.userProperties, properties);
+    }
+    setEnvironment(environmentId) {
+        this.environmentId = environmentId;
+    }
+    reset() {
+        this.userId = undefined;
+        this.userProperties = {};
+    }
+    // ─── Flush ────────────────────────────────────────────────────────────────
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const batch = [...this.queue];
+        this.queue = [];
+        try {
+            const response = await fetch(`${this.config.baseUrl}/v1/analytics/events`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.config.publicKey,
+                },
+                body: JSON.stringify({ events: batch }),
+            });
+            if (!response.ok) {
+                // Re-queue on failure
+                this.queue.unshift(...batch.slice(0, MAX_BATCH_SIZE - this.queue.length));
+            }
+        }
+        catch {
+            // Re-queue on network error
+            this.queue.unshift(...batch.slice(0, MAX_BATCH_SIZE - this.queue.length));
+        }
+    }
+    async dispose() {
+        if (this.flushTimer)
+            clearInterval(this.flushTimer);
+        this.track('session_end');
+        await this.flush();
+    }
+}
+exports.KoolbaseAnalytics = KoolbaseAnalytics;

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

@@ -0,0 +1,117 @@
+import { KoolbaseError } from './errors.js';
+/**
+ * Base error type for all Koolbase auth errors. Catchable via
+ * `instanceof KoolbaseAuthError` to handle any auth-related failure
+ * generically; subclasses let you handle specific cases.
+ */
+export declare class KoolbaseAuthError extends KoolbaseError {
+    constructor(message: string, code?: string);
+}
+export declare class InvalidCredentialsError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class EmailAlreadyInUseError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class UserDisabledError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class WeakPasswordError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class SessionExpiredError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the access token references a session that has been revoked
+ * centrally — either by the user (sessions endpoint) or an administrator.
+ * Distinct from {@link SessionExpiredError} which indicates the access
+ * token TTL elapsed without a successful refresh.
+ *
+ * Forward-compatible: matches multiple server message patterns so it stays
+ * accurate as the server's revocation signaling evolves.
+ */
+export declare class TokenRevokedError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the account is temporarily locked due to too many failed
+ * login attempts. The server uses progressive 5/10/20-attempt lockouts;
+ * if an unlock email was issued (level 2+), the user can clear the lock
+ * by passing that token to {@link KoolbaseAuth.unlock}.
+ *
+ * [lockedUntil] is currently null — the server returns a generic 429 but
+ * does not yet include the unlock timestamp in the response body. Field
+ * is forward-compatible for when the server adds it.
+ */
+export declare class AccountLockedError extends KoolbaseAuthError {
+    lockedUntil?: Date;
+    constructor(lockedUntil?: Date);
+}
+/**
+ * Thrown when the unlock token from a brute-force unlock email is
+ * invalid, expired, or already consumed. Unlock tokens are one-shot.
+ */
+export declare class UnlockTokenInvalidError extends KoolbaseAuthError {
+    constructor();
+}
+/**
+ * Thrown when the server rate-limits a non-phone authentication endpoint
+ * (HTTP 429 without the "account temporarily locked" marker). Phone OTP
+ * endpoints throw {@link OtpRateLimitError} instead — they hit a
+ * separate server-side rate-limiter.
+ */
+export declare class RateLimitError extends KoolbaseAuthError {
+    constructor(message?: string);
+}
+/**
+ * Generic network error. The SDK does NOT throw this directly — fetch
+ * failures (DNS, no connection, timeout) propagate as native TypeErrors.
+ * This class exists for consumer code that wants to construct or
+ * `instanceof`-check a typed network error from their own retry logic.
+ */
+export declare class NetworkError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class InvalidPhoneNumberError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpExpiredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpInvalidError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpMaxAttemptsError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OtpRateLimitError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class PhoneAlreadyLinkedError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class SmsConfigMissingError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class AppleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class InvalidAppleTokenError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class AppleEmailRequiredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class OAuthEmailConflictError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class InvalidGoogleTokenError extends KoolbaseAuthError {
+    constructor();
+}
+export declare class GoogleEmailRequiredError extends KoolbaseAuthError {
+    constructor();
+}

package/dist/cjs/auth-errors.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleEmailRequiredError = exports.InvalidGoogleTokenError = 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.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
+ * `instanceof KoolbaseAuthError` to handle any auth-related failure
+ * generically; subclasses let you handle specific cases.
+ */
+class KoolbaseAuthError extends errors_js_1.KoolbaseError {
+    constructor(message, code) {
+        super(message, code);
+        this.name = 'KoolbaseAuthError';
+        Object.setPrototypeOf(this, KoolbaseAuthError.prototype);
+    }
+}
+exports.KoolbaseAuthError = KoolbaseAuthError;
+// ─── Credentials / Registration ────────────────────────────────────────────
+class InvalidCredentialsError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid email or password', 'invalid_credentials');
+        this.name = 'InvalidCredentialsError';
+        Object.setPrototypeOf(this, InvalidCredentialsError.prototype);
+    }
+}
+exports.InvalidCredentialsError = InvalidCredentialsError;
+class EmailAlreadyInUseError extends KoolbaseAuthError {
+    constructor() {
+        super('Email is already in use', 'email_taken');
+        this.name = 'EmailAlreadyInUseError';
+        Object.setPrototypeOf(this, EmailAlreadyInUseError.prototype);
+    }
+}
+exports.EmailAlreadyInUseError = EmailAlreadyInUseError;
+class UserDisabledError extends KoolbaseAuthError {
+    constructor() {
+        super('This account has been disabled', 'user_disabled');
+        this.name = 'UserDisabledError';
+        Object.setPrototypeOf(this, UserDisabledError.prototype);
+    }
+}
+exports.UserDisabledError = UserDisabledError;
+class WeakPasswordError extends KoolbaseAuthError {
+    constructor() {
+        super('Password must be at least 8 characters', 'weak_password');
+        this.name = 'WeakPasswordError';
+        Object.setPrototypeOf(this, WeakPasswordError.prototype);
+    }
+}
+exports.WeakPasswordError = WeakPasswordError;
+// ─── Session lifecycle ─────────────────────────────────────────────────────
+class SessionExpiredError extends KoolbaseAuthError {
+    constructor() {
+        super('Session expired, please log in again', 'session_expired');
+        this.name = 'SessionExpiredError';
+        Object.setPrototypeOf(this, SessionExpiredError.prototype);
+    }
+}
+exports.SessionExpiredError = SessionExpiredError;
+/**
+ * Thrown when the access token references a session that has been revoked
+ * centrally — either by the user (sessions endpoint) or an administrator.
+ * Distinct from {@link SessionExpiredError} which indicates the access
+ * token TTL elapsed without a successful refresh.
+ *
+ * Forward-compatible: matches multiple server message patterns so it stays
+ * accurate as the server's revocation signaling evolves.
+ */
+class TokenRevokedError extends KoolbaseAuthError {
+    constructor() {
+        super('Session has been revoked, please log in again', 'token_revoked');
+        this.name = 'TokenRevokedError';
+        Object.setPrototypeOf(this, TokenRevokedError.prototype);
+    }
+}
+exports.TokenRevokedError = TokenRevokedError;
+// ─── Brute-force protection ────────────────────────────────────────────────
+/**
+ * Thrown when the account is temporarily locked due to too many failed
+ * login attempts. The server uses progressive 5/10/20-attempt lockouts;
+ * if an unlock email was issued (level 2+), the user can clear the lock
+ * by passing that token to {@link KoolbaseAuth.unlock}.
+ *
+ * [lockedUntil] is currently null — the server returns a generic 429 but
+ * does not yet include the unlock timestamp in the response body. Field
+ * is forward-compatible for when the server adds it.
+ */
+class AccountLockedError extends KoolbaseAuthError {
+    constructor(lockedUntil) {
+        super('Account temporarily locked due to too many failed attempts', 'account_locked');
+        this.lockedUntil = lockedUntil;
+        this.name = 'AccountLockedError';
+        Object.setPrototypeOf(this, AccountLockedError.prototype);
+    }
+}
+exports.AccountLockedError = AccountLockedError;
+/**
+ * Thrown when the unlock token from a brute-force unlock email is
+ * invalid, expired, or already consumed. Unlock tokens are one-shot.
+ */
+class UnlockTokenInvalidError extends KoolbaseAuthError {
+    constructor() {
+        super('Unlock link is invalid or has expired', 'unlock_token_invalid');
+        this.name = 'UnlockTokenInvalidError';
+        Object.setPrototypeOf(this, UnlockTokenInvalidError.prototype);
+    }
+}
+exports.UnlockTokenInvalidError = UnlockTokenInvalidError;
+/**
+ * Thrown when the server rate-limits a non-phone authentication endpoint
+ * (HTTP 429 without the "account temporarily locked" marker). Phone OTP
+ * endpoints throw {@link OtpRateLimitError} instead — they hit a
+ * separate server-side rate-limiter.
+ */
+class RateLimitError extends KoolbaseAuthError {
+    constructor(message) {
+        super(message ?? 'Too many requests, please wait before trying again', 'rate_limit');
+        this.name = 'RateLimitError';
+        Object.setPrototypeOf(this, RateLimitError.prototype);
+    }
+}
+exports.RateLimitError = RateLimitError;
+// ─── Network ───────────────────────────────────────────────────────────────
+/**
+ * Generic network error. The SDK does NOT throw this directly — fetch
+ * failures (DNS, no connection, timeout) propagate as native TypeErrors.
+ * This class exists for consumer code that wants to construct or
+ * `instanceof`-check a typed network error from their own retry logic.
+ */
+class NetworkError extends KoolbaseAuthError {
+    constructor() {
+        super('Network error, please check your connection', 'network_error');
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+exports.NetworkError = NetworkError;
+// ─── Phone OTP (unchanged from earlier releases) ───────────────────────────
+class InvalidPhoneNumberError extends KoolbaseAuthError {
+    constructor() {
+        super('Phone number must be in E.164 format (e.g. +233XXXXXXXXX)', 'invalid_phone');
+        this.name = 'InvalidPhoneNumberError';
+        Object.setPrototypeOf(this, InvalidPhoneNumberError.prototype);
+    }
+}
+exports.InvalidPhoneNumberError = InvalidPhoneNumberError;
+class OtpExpiredError extends KoolbaseAuthError {
+    constructor() {
+        super('OTP has expired, please request a new code', 'otp_expired');
+        this.name = 'OtpExpiredError';
+        Object.setPrototypeOf(this, OtpExpiredError.prototype);
+    }
+}
+exports.OtpExpiredError = OtpExpiredError;
+class OtpInvalidError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid OTP code', 'otp_invalid');
+        this.name = 'OtpInvalidError';
+        Object.setPrototypeOf(this, OtpInvalidError.prototype);
+    }
+}
+exports.OtpInvalidError = OtpInvalidError;
+class OtpMaxAttemptsError extends KoolbaseAuthError {
+    constructor() {
+        super('Too many incorrect attempts, please request a new code', 'otp_max_attempts');
+        this.name = 'OtpMaxAttemptsError';
+        Object.setPrototypeOf(this, OtpMaxAttemptsError.prototype);
+    }
+}
+exports.OtpMaxAttemptsError = OtpMaxAttemptsError;
+class OtpRateLimitError extends KoolbaseAuthError {
+    constructor() {
+        super('Too many OTP requests, please wait before trying again', 'otp_rate_limit');
+        this.name = 'OtpRateLimitError';
+        Object.setPrototypeOf(this, OtpRateLimitError.prototype);
+    }
+}
+exports.OtpRateLimitError = OtpRateLimitError;
+class PhoneAlreadyLinkedError extends KoolbaseAuthError {
+    constructor() {
+        super('Phone number is already associated with another account', 'phone_taken');
+        this.name = 'PhoneAlreadyLinkedError';
+        Object.setPrototypeOf(this, PhoneAlreadyLinkedError.prototype);
+    }
+}
+exports.PhoneAlreadyLinkedError = PhoneAlreadyLinkedError;
+class SmsConfigMissingError extends KoolbaseAuthError {
+    constructor() {
+        super('SMS provider not configured for this project', 'sms_config_missing');
+        this.name = 'SmsConfigMissingError';
+        Object.setPrototypeOf(this, SmsConfigMissingError.prototype);
+    }
+}
+exports.SmsConfigMissingError = SmsConfigMissingError;
+class AppleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor() {
+        super('Apple Sign-In is not configured for this environment', 'apple_not_configured');
+        this.name = 'AppleSignInNotConfiguredError';
+        Object.setPrototypeOf(this, AppleSignInNotConfiguredError.prototype);
+    }
+}
+exports.AppleSignInNotConfiguredError = AppleSignInNotConfiguredError;
+class InvalidAppleTokenError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid Apple identity token', 'invalid_apple_token');
+        this.name = 'InvalidAppleTokenError';
+        Object.setPrototypeOf(this, InvalidAppleTokenError.prototype);
+    }
+}
+exports.InvalidAppleTokenError = InvalidAppleTokenError;
+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');
+        this.name = 'AppleEmailRequiredError';
+        Object.setPrototypeOf(this, AppleEmailRequiredError.prototype);
+    }
+}
+exports.AppleEmailRequiredError = AppleEmailRequiredError;
+class OAuthEmailConflictError extends KoolbaseAuthError {
+    constructor() {
+        super('Email is already in use by another account. Sign in with your existing method and link Apple from settings.', 'oauth_email_conflict');
+        this.name = 'OAuthEmailConflictError';
+        Object.setPrototypeOf(this, OAuthEmailConflictError.prototype);
+    }
+}
+exports.OAuthEmailConflictError = OAuthEmailConflictError;
+class GoogleSignInNotConfiguredError extends KoolbaseAuthError {
+    constructor() {
+        super('Google Sign-In is not configured for this environment', 'google_not_configured');
+        this.name = 'GoogleSignInNotConfiguredError';
+        Object.setPrototypeOf(this, GoogleSignInNotConfiguredError.prototype);
+    }
+}
+exports.GoogleSignInNotConfiguredError = GoogleSignInNotConfiguredError;
+class InvalidGoogleTokenError extends KoolbaseAuthError {
+    constructor() {
+        super('Invalid Google identity token', 'invalid_google_token');
+        this.name = 'InvalidGoogleTokenError';
+        Object.setPrototypeOf(this, InvalidGoogleTokenError.prototype);
+    }
+}
+exports.InvalidGoogleTokenError = InvalidGoogleTokenError;
+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');
+        this.name = 'GoogleEmailRequiredError';
+        Object.setPrototypeOf(this, GoogleEmailRequiredError.prototype);
+    }
+}
+exports.GoogleEmailRequiredError = GoogleEmailRequiredError;