@koolbase/react-native 9.0.0

package/dist/database.js

@@ -0,0 +1,508 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KoolbaseDatabase = void 0;
+const cache_store_1 = require("./cache-store");
+const sync_engine_1 = require("./sync-engine");
+const record_1 = require("./record");
+const database_errors_1 = require("./database-errors");
+function generateId() {
+    return 'local_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+function batchOpToWire(op) {
+    switch (op.type) {
+        case 'insert':
+            return { type: 'insert', collection: op.collection, data: op.data };
+        case 'update':
+            return { type: 'update', record_id: op.recordId, data: op.data };
+        case 'delete':
+            return { type: 'delete', record_id: op.recordId };
+        case 'upsert':
+            return {
+                type: 'upsert',
+                collection: op.collection,
+                match: op.match,
+                data: op.data,
+            };
+    }
+}
+class KoolbaseDatabase {
+    constructor(config, getUserId, getToken) {
+        this.config = config;
+        this.getUserId = getUserId;
+        this.getToken = getToken;
+        this.syncEngine = new sync_engine_1.SyncEngine(config, getUserId, getToken);
+        this.syncEngine.start();
+    }
+    // getUserId is kept only for local cache keys / offline metadata; request
+    // identity now comes solely from the verified access token.
+    async buildHeaders() {
+        const token = await this.getToken();
+        return {
+            'Content-Type': 'application/json',
+            'x-api-key': this.config.publicKey,
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        };
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.config.baseUrl}${path}`, {
+            method,
+            headers: await this.buildHeaders(),
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            throw (0, database_errors_1.koolbaseDataError)(res.status, data, `Request failed: ${res.status}`);
+        }
+        return data;
+    }
+    // ─── Query (cache-first) ───────────────────────────────────────────────────
+    async runQuery(collection, options) {
+        const raw = await this.request('POST', '/v1/sdk/db/query', {
+            collection,
+            filters: options.filters ?? {},
+            limit: options.limit ?? 20,
+            offset: options.offset ?? 0,
+            order_by: options.orderBy,
+            order_desc: options.orderDesc ?? false,
+            populate: options.populate ?? [],
+        });
+        return { records: raw.records.map(record_1.recordFromWire), total: raw.total };
+    }
+    async query(collection, options = {}) {
+        const userId = this.getUserId() ?? 'anonymous';
+        const queryHash = (0, cache_store_1.hashQuery)(collection, options);
+        const cached = await (0, cache_store_1.getCached)(userId, collection, queryHash);
+        this.runQuery(collection, options)
+            .then(result => (0, cache_store_1.setCached)(userId, collection, queryHash, result))
+            .catch(() => {
+            // Network unavailable — cached data already returned
+        });
+        if (cached) {
+            return { ...cached, isFromCache: true };
+        }
+        const result = await this.runQuery(collection, options);
+        await (0, cache_store_1.setCached)(userId, collection, queryHash, result);
+        return { ...result, isFromCache: false };
+    }
+    // ─── Insert (online-first with offline fallback) ───────────────────────────
+    /**
+     * Insert a new record into a collection.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, validation error, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass — `insert` now throws `KoolbaseConflictError`
+     * with the offending field on a 409, matching `upsert` and `update`.
+     *
+     * On genuine network failure (server unreachable, timeout) the write is
+     * accepted optimistically: saved to the local cache and queued for sync
+     * when connectivity returns.
+     */
+    async insert(collection, data) {
+        const userId = this.getUserId() ?? 'anonymous';
+        try {
+            // Online path: await the server and return the authoritative record
+            // (with the server-assigned id). Refresh the collection cache so the
+            // next query sees real data instead of a stale optimistic copy.
+            const raw = await this.request('POST', '/v1/sdk/db/insert', { collection, data });
+            const record = (0, record_1.recordFromWire)(raw);
+            await (0, cache_store_1.invalidateCache)(userId, collection);
+            return record;
+        }
+        catch (e) {
+            // Server-reachable rejection: the server saw the request and refused.
+            // Surface to the caller without writing optimistic state or queuing —
+            // the server has already decided it will not accept this write, and
+            // queuing it would just spin SyncEngine until max retries.
+            if (e instanceof database_errors_1.KoolbaseDataError)
+                throw e;
+            // Genuine network failure → offline path: save to local cache and
+            // queue for SyncEngine to retry when online. Return the optimistic
+            // record so the UI has something to render in the meantime.
+            const optimisticRecord = {
+                id: generateId(),
+                createdBy: userId,
+                data,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            };
+            await (0, cache_store_1.optimisticallyInsert)(userId, collection, optimisticRecord);
+            await (0, cache_store_1.addToWriteQueue)(userId, {
+                id: generateId(),
+                type: 'insert',
+                collection,
+                data,
+            });
+            return optimisticRecord;
+        }
+    }
+    // ─── Upsert (online-only) ─────────────────────────────────────────────────
+    /**
+     * Insert a record, or update the existing one matching `match`.
+     *
+     * The server decides: exactly one match updates it, no match inserts a new
+     * record (seeded with the `match` fields), more than one match is an error.
+     * Returns the resulting record and a `created` flag (true = inserted, false
+     * = updated).
+     *
+     * Online-only by design. Unlike `insert`, an upsert is NOT queued offline:
+     * the insert-vs-update decision needs the server's authoritative view of
+     * what already exists, so deferring it could create a duplicate or apply a
+     * wrong update on later sync. It throws on network failure instead. A raw
+     * fetch is used (not `request`) so the status code is readable: 201 =
+     * created, 200 = updated.
+     */
+    async upsert(collection, match, data) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/upsert`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({ collection, match, data }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Upsert failed: ${res.status}`);
+        }
+        const created = res.status === 201;
+        const record = (0, record_1.recordFromWire)(body);
+        // Keep the cache fresh, same intent as insert's post-success invalidate.
+        const userId = this.getUserId() ?? 'anonymous';
+        await (0, cache_store_1.invalidateCache)(userId, collection);
+        return { record, created };
+    }
+    // ─── Delete where (online-only) ─────────────────────────────────────────────
+    /**
+     * Bulk-delete every record in `collection` matching `filters`.
+     *
+     * The server applies the collection's delete rule (scoping to the caller for
+     * owner/scoped rules) and returns the number of records deleted.
+     *
+     * Online-only by design — like upsert, this is NOT queued offline: a bulk
+     * delete needs the server's authoritative view of what matches, so it throws
+     * on network failure rather than risk deleting the wrong set on later sync.
+     * The collection cache is invalidated on success.
+     */
+    async deleteWhere(collection, filters) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-where`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({ collection, filters }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Delete failed: ${res.status}`);
+        }
+        const userId = this.getUserId() ?? 'anonymous';
+        await (0, cache_store_1.invalidateCache)(userId, collection);
+        return body.deleted ?? 0;
+    }
+    // ─── Batch (atomic, online-only) ────────────────────────────────────────────
+    /**
+     * Run multiple writes as a single atomic transaction.
+     *
+     * All `operations` commit together or none are applied — the server runs
+     * them in one database transaction and rolls back entirely on any failure.
+     * Operations apply in order and may span multiple collections.
+     *
+     * Online-only by design (like `upsert` and `deleteWhere`): atomicity needs
+     * the server's authoritative view, so a batch is never queued offline — it
+     * throws on network failure. A server-side rejection throws a
+     * `KoolbaseDataException` whose message identifies which operation failed;
+     * nothing was persisted.
+     *
+     * Returns one `BatchResult` per operation, in order.
+     *
+     * @example
+     * const results = await Koolbase.db.batch([
+     *   BatchOp.insert('orders', { total: 50 }),
+     *   BatchOp.update(inventoryId, { stock: 9 }),
+     *   BatchOp.upsert('counters', { match: { name: 'orders' }, data: { value: 1 } }),
+     *   BatchOp.delete(cartItemId),
+     * ]);
+     */
+    async batch(operations) {
+        if (operations.length === 0) {
+            throw new Error('batch requires at least one operation');
+        }
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/batch`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({
+                operations: operations.map(batchOpToWire),
+            }),
+        });
+        const body = await res.json();
+        if (!res.ok) {
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, `Batch failed: ${res.status}`);
+        }
+        const results = (body.results ?? []).map(r => ({
+            type: r.type ?? '',
+            record: r.record
+                ? (0, record_1.recordFromWire)(r.record)
+                : undefined,
+            created: r.created,
+            deleted: r.deleted ?? false,
+        }));
+        // Keep the cache consistent with what committed. Insert/upsert carry the
+        // collection in the input op; update/delete address records by id, so we
+        // don't know the collection at this layer — those refresh naturally on
+        // the next query for the affected collection.
+        const userId = this.getUserId() ?? 'anonymous';
+        const touched = new Set();
+        for (const op of operations) {
+            if (op.type === 'insert' || op.type === 'upsert') {
+                touched.add(op.collection);
+            }
+        }
+        for (const col of touched) {
+            await (0, cache_store_1.invalidateCache)(userId, col);
+        }
+        return results;
+    }
+    // ─── Get single record ──────────────────────────────────────────────────────
+    // ─── Get single record ──────────────────────────────────────────────────────
+    async get(recordId) {
+        const raw = await this.request('GET', `/v1/sdk/db/records/${recordId}`);
+        return (0, record_1.recordFromWire)(raw);
+    }
+    // ─── Update (online-first with offline fallback) ───────────────────────────
+    /**
+     * Update a record's fields by id.
+     *
+     * Online-first: awaits the server so a server-side rejection (unique
+     * violation, not found, permission denial) surfaces as the typed
+     * `KoolbaseDataError` subclass. An update that would violate a unique
+     * constraint now throws `KoolbaseConflictError` with the offending field —
+     * same shape as `insert` and `upsert`.
+     *
+     * On genuine network failure the update is queued for sync and a partial
+     * optimistic record is returned so the UI can re-render the new fields
+     * immediately.
+     */
+    async update(recordId, data) {
+        const userId = this.getUserId() ?? 'anonymous';
+        try {
+            const raw = await this.request('PATCH', `/v1/sdk/db/records/${recordId}`, { data });
+            return (0, record_1.recordFromWire)(raw);
+        }
+        catch (e) {
+            // Server-reachable rejection: surface to caller without queuing — the
+            // server already refused the write and will refuse it again on retry.
+            if (e instanceof database_errors_1.KoolbaseDataError)
+                throw e;
+            // Genuine network failure → queue for sync and return an optimistic
+            // partial record so the UI reflects the update immediately.
+            await (0, cache_store_1.addToWriteQueue)(userId, {
+                id: generateId(),
+                type: 'update',
+                recordId,
+                data,
+            });
+            return {
+                id: recordId,
+                data,
+                createdAt: '',
+                updatedAt: new Date().toISOString(),
+            };
+        }
+    }
+    // ─── Delete ─────────────────────────────────────────────────────────────────
+    async delete(recordId) {
+        const userId = this.getUserId() ?? 'anonymous';
+        // Add to write queue
+        await (0, cache_store_1.addToWriteQueue)(userId, {
+            id: generateId(),
+            type: 'delete',
+            recordId,
+        });
+        // Try network
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/records/${recordId}`, { method: 'DELETE', headers: await this.buildHeaders(), });
+        if (!res.ok && res.status !== 204) {
+            // Queued for sync — will retry when online
+        }
+    }
+    // ─── Vectors ────────────────────────────────────────────────────────────────
+    /**
+     * Write (or replace) a vector for a record on the named `field`.
+     *
+     * The field must already be declared on the collection via the dashboard
+     * or CLI. `vector.length` must match the field's declared dimension;
+     * otherwise throws `KoolbaseVectorDimensionMismatchError`.
+     *
+     * Online-only — vectors are not cached locally or queued offline because
+     * HNSW similarity search has no useful offline semantics.
+     *
+     * @example
+     * await Koolbase.db.setVector(
+     *   articleId,
+     *   'embedding',
+     *   await myEmbeddingModel.encode(article.content),
+     * );
+     */
+    async setVector(recordId, field, vector) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/set-vector`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({ record_id: recordId, field, vector }),
+        });
+        if (res.status !== 204) {
+            const body = await res.json().catch(() => ({}));
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, 'Set vector failed');
+        }
+    }
+    /**
+     * Read a record's stored vector on the named `field`.
+     *
+     * Throws `KoolbaseNotFoundError` if either the field is not declared or
+     * no vector has been set for this record on this field. Throws
+     * `KoolbasePermissionError` if the caller cannot read this record per
+     * the collection's read rule.
+     *
+     * Online-only.
+     *
+     * @example
+     * const v = await Koolbase.db.getVector(articleId, 'embedding');
+     * console.log(`${v.vector.length}-dim, updated ${v.updatedAt}`);
+     */
+    async getVector(recordId, field) {
+        const raw = await this.request('POST', '/v1/sdk/db/get-vector', { record_id: recordId, field });
+        return {
+            recordId: raw.record_id,
+            fieldName: raw.field_name,
+            vector: raw.vector,
+            createdAt: raw.created_at,
+            updatedAt: raw.updated_at,
+        };
+    }
+    /**
+     * Remove a record's stored vector on the named `field`.
+     *
+     * Online-only. Throws `KoolbaseNotFoundError` if no vector is set for
+     * `(recordId, field)`; throws `KoolbasePermissionError` if the caller
+     * cannot write this record per the collection's write rule.
+     *
+     * Note: this removes the vector from the dimension table but does NOT
+     * remove the field declaration itself — the field stays on the
+     * collection and is still settable on other records.
+     */
+    async deleteVector(recordId, field) {
+        const res = await fetch(`${this.config.baseUrl}/v1/sdk/db/delete-vector`, {
+            method: 'POST',
+            headers: await this.buildHeaders(),
+            body: JSON.stringify({ record_id: recordId, field }),
+        });
+        if (res.status !== 204) {
+            const body = await res.json().catch(() => ({}));
+            throw (0, database_errors_1.koolbaseDataError)(res.status, body, 'Delete vector failed');
+        }
+    }
+    /**
+     * Queue an embedding job for a record's vector field. The server's
+     * embedding worker picks it up within ~1 second.
+     *
+     * If `text` is omitted, the vector field's configured `source_field`
+     * value on the record is used.
+     *
+     * @example
+     * await Koolbase.db.embedText({
+     *   collection: 'articles',
+     *   recordId: article.$id,
+     *   vectorField: 'content_embedding',
+     * });
+     */
+    async embedText(opts) {
+        const body = {
+            collection: opts.collection,
+            record_id: opts.recordId,
+            vector_field: opts.vectorField,
+        };
+        if (opts.text && opts.text.length > 0) {
+            body.text = opts.text;
+        }
+        await this.request('POST', '/v1/sdk/db/embed-text', body);
+    }
+    /**
+     * Search for records based on their semantic similarity to a query.
+     *
+     * @example
+     * // Server-side embedding — most common:
+     * const result = await Koolbase.db.searchSemantic({
+     *   collection: 'articles',
+     *   field: 'content_embedding',
+     *   queryText: 'how do I configure CI/CD?',
+     *   limit: 10,
+     * });
+     *
+     * // Client-side embedding:
+     * const result = await Koolbase.db.searchSemantic({
+     *   collection: 'articles',
+     *   field: 'content_embedding',
+     *   queryVector: precomputed,
+     *   limit: 10,
+     * });
+     *
+     * // Hybrid search (vector + BM25, RRF-fused):
+     * const result = await Koolbase.db.searchSemantic({
+     *   collection: 'articles',
+     *   field: 'content_embedding',
+     *   queryText: 'how do I configure CI/CD?',
+     *   mode: 'hybrid',
+     *   minSimilarity: 70,
+     * });
+     *
+     * `mode` selects the retrieval strategy:
+     * - `'semantic'` (default) — pure vector search via HNSW
+     * - `'lexical'` — pure BM25 over the field's source text
+     * - `'hybrid'` — vector + lexical, RRF-fused (k=60)
+     *
+     * `minSimilarity` (0..100, optional) filters out results below the
+     * given similarity percentage server-side. Saves bandwidth on weak
+     * matches. Only valid for semantic and hybrid; rejected by the
+     * server on lexical mode.
+     */
+    async searchSemantic(opts) {
+        const hasVector = Array.isArray(opts.queryVector) && opts.queryVector.length > 0;
+        const hasText = typeof opts.queryText === 'string' && opts.queryText.trim().length > 0;
+        if (!hasVector && !hasText) {
+            throw new Error('searchSemantic: provide either queryVector or queryText.');
+        }
+        if (hasVector && hasText) {
+            throw new Error('searchSemantic: provide only one of queryVector or queryText.');
+        }
+        if (opts.minSimilarity !== undefined &&
+            (opts.minSimilarity < 0 || opts.minSimilarity > 100)) {
+            throw new Error(`searchSemantic: minSimilarity must be between 0 and 100, got ${opts.minSimilarity}.`);
+        }
+        const body = {
+            collection: opts.collection,
+            field: opts.field,
+            limit: opts.limit ?? 20,
+            // Always send mode so the server uses the SDK's intent rather
+            // than its own default. Omitting for 'semantic' would also work
+            // (server defaults to semantic) but explicit is safer if the
+            // server's default ever shifts.
+            mode: opts.mode ?? 'semantic',
+        };
+        if (hasVector)
+            body.query_vector = opts.queryVector;
+        if (hasText)
+            body.query_text = opts.queryText;
+        if (opts.where && Object.keys(opts.where).length > 0) {
+            body.where = opts.where;
+        }
+        if (opts.minSimilarity !== undefined) {
+            body.min_similarity = opts.minSimilarity;
+        }
+        const raw = await this.request('POST', '/v1/sdk/db/search-semantic', body);
+        return {
+            hits: (raw.results ?? []).map(r => ({
+                record: (0, record_1.recordFromWire)(r.record),
+                distance: r.distance,
+            })),
+            total: raw.total ?? (raw.results ?? []).length,
+        };
+    }
+    // ─── Manual sync ────────────────────────────────────────────────────────────
+    async syncPendingWrites() {
+        await this.syncEngine.flush();
+    }
+}
+exports.KoolbaseDatabase = KoolbaseDatabase;

package/dist/device-metadata.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Koolbase React Native SDK version. Sent in the `x-koolbase-sdk-version`
+ * header on every authenticated request so the server can route
+ * version-conditional logic (deprecation warnings, schema migrations,
+ * feature flags). Must match the `version` field in package.json.
+ */
+export declare const koolbaseSdkVersion = "1.11.0";
+/**
+ * Builds device-identifying headers attached to every Koolbase auth
+ * request. Mirrors the Flutter SDK's `DeviceMetadata` for parity. Apps
+ * with privacy concerns can swap in a custom storage adapter to avoid
+ * persisting the device label.
+ *
+ * Headers emitted:
+ * - User-Agent: koolbase-react-native/<sdk> (<platform> <version>)
+ * - x-koolbase-sdk:              react-native
+ * - x-koolbase-sdk-version:      <koolbaseSdkVersion>
+ * - x-koolbase-platform:         ios | android | web | etc.
+ * - x-koolbase-platform-version: numeric SDK level or OS version string
+ * - x-koolbase-app-version:      from KoolbaseConfig.appVersion or 'unknown'
+ * - x-koolbase-device-label:     persistent UUID per install
+ */
+export declare class DeviceMetadata {
+    private cached;
+    private ephemeralLabel;
+    private readonly appVersion;
+    constructor(appVersion?: string);
+    /**
+     * Build (or return cached) device headers. The first call may perform
+     * an async keychain read to look up the persisted device label;
+     * subsequent calls return the in-memory cache synchronously via the
+     * returned Promise.
+     */
+    build(): Promise<Record<string, string>>;
+    private getOrCreateDeviceLabel;
+}

package/dist/device-metadata.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeviceMetadata = exports.koolbaseSdkVersion = void 0;
+const react_native_1 = require("react-native");
+const auth_storage_1 = require("./auth-storage");
+/**
+ * Koolbase React Native SDK version. Sent in the `x-koolbase-sdk-version`
+ * header on every authenticated request so the server can route
+ * version-conditional logic (deprecation warnings, schema migrations,
+ * feature flags). Must match the `version` field in package.json.
+ */
+exports.koolbaseSdkVersion = '1.11.0';
+/**
+ * Generate a UUIDv4-shaped string for use as a stable per-install
+ * device label. Not cryptographically secure — this is a label, not a
+ * security primitive. Avoids pulling in a crypto-grade UUID dependency.
+ */
+function generateDeviceLabel() {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/**
+ * Builds device-identifying headers attached to every Koolbase auth
+ * request. Mirrors the Flutter SDK's `DeviceMetadata` for parity. Apps
+ * with privacy concerns can swap in a custom storage adapter to avoid
+ * persisting the device label.
+ *
+ * Headers emitted:
+ * - User-Agent: koolbase-react-native/<sdk> (<platform> <version>)
+ * - x-koolbase-sdk:              react-native
+ * - x-koolbase-sdk-version:      <koolbaseSdkVersion>
+ * - x-koolbase-platform:         ios | android | web | etc.
+ * - x-koolbase-platform-version: numeric SDK level or OS version string
+ * - x-koolbase-app-version:      from KoolbaseConfig.appVersion or 'unknown'
+ * - x-koolbase-device-label:     persistent UUID per install
+ */
+class DeviceMetadata {
+    constructor(appVersion) {
+        this.cached = null;
+        this.ephemeralLabel = null;
+        this.appVersion = appVersion ?? 'unknown';
+    }
+    /**
+     * Build (or return cached) device headers. The first call may perform
+     * an async keychain read to look up the persisted device label;
+     * subsequent calls return the in-memory cache synchronously via the
+     * returned Promise.
+     */
+    async build() {
+        if (this.cached)
+            return this.cached;
+        const platform = String(react_native_1.Platform.OS);
+        const platformVersion = String(react_native_1.Platform.Version);
+        const deviceLabel = await this.getOrCreateDeviceLabel();
+        const userAgent = `koolbase-react-native/${exports.koolbaseSdkVersion} (${platform} ${platformVersion})`;
+        this.cached = {
+            'User-Agent': userAgent,
+            'x-koolbase-sdk': 'react-native',
+            'x-koolbase-sdk-version': exports.koolbaseSdkVersion,
+            'x-koolbase-platform': platform,
+            'x-koolbase-platform-version': platformVersion,
+            'x-koolbase-app-version': this.appVersion,
+            'x-koolbase-device-label': deviceLabel,
+        };
+        return this.cached;
+    }
+    async getOrCreateDeviceLabel() {
+        // No keychain available → ephemeral per-session label.
+        // (Better than no label — still useful for in-session debugging.)
+        if (!(0, auth_storage_1.isKeychainAvailable)()) {
+            if (!this.ephemeralLabel) {
+                this.ephemeralLabel = generateDeviceLabel();
+            }
+            return this.ephemeralLabel;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const Keychain = require('react-native-keychain');
+        const service = 'koolbase_device_label_v1';
+        try {
+            const existing = await Keychain.getGenericPassword({ service });
+            if (existing && existing.password) {
+                return existing.password;
+            }
+        }
+        catch {
+            // fall through to create
+        }
+        const newLabel = generateDeviceLabel();
+        try {
+            await Keychain.setGenericPassword('device', newLabel, { service });
+        }
+        catch {
+            // Persistence failed — return the generated label anyway, but
+            // don't cache it as ephemeral since future requests may persist.
+        }
+        return newLabel;
+    }
+}
+exports.DeviceMetadata = DeviceMetadata;

package/dist/flags.d.ts

@@ -0,0 +1,15 @@
+import { KoolbaseConfig, VersionCheckResult } from './types';
+export declare class KoolbaseFlags {
+    private config;
+    private payload;
+    private deviceId;
+    constructor(config: KoolbaseConfig, deviceId: string);
+    fetch(appVersion: string, platform: string): Promise<void>;
+    isEnabled(key: string): boolean;
+    getString(key: string, fallback?: string): string;
+    getNumber(key: string, fallback?: number): number;
+    getBool(key: string, fallback?: boolean): boolean;
+    checkVersion(currentVersion: string): VersionCheckResult;
+    private parseVersion;
+    private stableHash;
+}