@koolbase/react-native 9.2.0 → 10.0.0

package/dist/storage.js

@@ -1,451 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStorage = void 0;
-const errors_1 = require("./errors");
-const storage_errors_1 = require("./storage-errors");
-// --- Cloudflare image-transform URL helpers -------------------------------
-// Module-private — callers use KoolbaseStorage.publicUrl / publicUrlForObject.
-function clampInt(v, min, max) {
-    return Math.max(min, Math.min(max, Math.floor(v)));
-}
-/**
- * Serializes a transform spec to Cloudflare's comma-separated key=value
- * options segment (e.g. `width=400,format=webp,quality=80`). Returns the
- * empty string when no fields are set — callers can use that to skip the
- * `/cdn-cgi/image/` URL prefix entirely.
- */
-function serializeTransform(t) {
-    const parts = [];
-    if (t.width != null)
-        parts.push(`width=${clampInt(t.width, 1, 2000)}`);
-    if (t.height != null)
-        parts.push(`height=${clampInt(t.height, 1, 2000)}`);
-    if (t.format)
-        parts.push(`format=${t.format}`);
-    if (t.quality != null)
-        parts.push(`quality=${clampInt(t.quality, 1, 100)}`);
-    if (t.fit)
-        parts.push(`fit=${t.fit}`);
-    if (t.dpr != null)
-        parts.push(`dpr=${clampInt(t.dpr, 1, 3)}`);
-    if (t.gravity)
-        parts.push(`gravity=${t.gravity}`);
-    return parts.join(',');
-}
-/**
- * Koolbase storage client — uploads, downloads, and deletes via presigned
- * Cloudflare R2 URLs.
- *
- * Uploads are **safe-by-default** (v5+): an upload to a path where an object
- * already exists is rejected with {@link KoolbaseStorageConflictError} unless
- * `overwrite: true` is passed.
- */
-class KoolbaseStorage {
-    constructor(config, getToken, onSessionExpired) {
-        this.config = config;
-        this.getToken = getToken;
-        this.onSessionExpired = onSessionExpired;
-    }
-    /**
-     * Builds the error for a failed response and clears the session when the
-     * credentials were refused, before the error reaches the caller.
-     */
-    async error(res, fallback) {
-        const err = await (0, storage_errors_1.koolbaseStorageErrorFromResponse)(res, fallback);
-        if (err instanceof errors_1.KoolbaseUnauthenticatedError) {
-            await this.onSessionExpired?.();
-        }
-        return err;
-    }
-    async buildHeaders() {
-        const token = await this.getToken();
-        return {
-            'x-api-key': this.config.publicKey,
-            ...(token ? { Authorization: `Bearer ${token}` } : {}),
-        };
-    }
-    /**
-     * Upload a file to a bucket. Returns the object metadata and a download URL.
-     *
-     * By default (`overwrite: false`), uploads to a path where an object
-     * already exists are **rejected** with a {@link KoolbaseStorageConflictError}.
-     * Catch it to prompt the user, then retry with `overwrite: true` to replace
-     * the existing object — or with a different `path`.
-     *
-     * Set `overwrite: true` for true upsert semantics — silently replace any
-     * existing object at this path.
-     *
-     * Pass `options.metadata` to attach arbitrary user-defined key/value pairs
-     * to the object at confirm time. Subject to the limits documented on
-     * {@link KoolbaseObject.metadata}; violations throw
-     * `KoolbaseStorageMetadataInvalidError`. On the `overwrite: true` path the
-     * metadata REPLACES any prior metadata at this path (matches GCS semantics).
-     * Use {@link updateMetadata} for post-upload merge changes.
-     *
-     * **Breaking change in v5.0.0**: the default flipped from silent overwrite
-     * (legacy behavior) to safe-by-default. If you previously relied on uploads
-     * overwriting silently, pass `overwrite: true` explicitly.
-     */
-    async upload(options) {
-        const overwrite = options.overwrite ?? false;
-        const contentType = options.file.type;
-        // ─── Step 1: Get presigned upload URL ───
-        const urlRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/upload-url`, {
-            method: 'POST',
-            headers: {
-                ...(await this.buildHeaders()),
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
-                bucket: options.bucket,
-                path: options.path,
-                content_type: contentType,
-                overwrite,
-            }),
-        });
-        if (!urlRes.ok) {
-            throw await this.error(urlRes, 'Failed to get upload URL');
-        }
-        const { upload_url } = (await urlRes.json());
-        // ─── Step 2: Upload directly to R2 ───
-        // RN's fetch resolves local file URIs and Blob bodies on a raw PUT.
-        // R2 presigned URLs expect raw binary, NOT multipart/form-data.
-        const fileResp = await fetch(options.file.uri);
-        const fileBlob = await fileResp.blob();
-        const fileSize = fileBlob.size;
-        const uploadRes = await fetch(upload_url, {
-            method: 'PUT',
-            headers: { 'Content-Type': contentType },
-            body: fileBlob,
-        });
-        if (!uploadRes.ok) {
-            // R2 PUT errors don't follow the Koolbase error shape — surface as a
-            // generic storage error rather than trying to decode a Koolbase body.
-            throw new storage_errors_1.KoolbaseStorageError(`Upload to storage failed: ${uploadRes.status}`);
-        }
-        const etag = uploadRes.headers.get('etag') ?? '';
-        // ─── Step 3: Confirm upload ───
-        // Build the body conditionally so the `metadata` field is only sent
-        // when the caller passed it — keeps the wire shape clean for callers
-        // that don't care, and lets the server's omitempty path treat absent
-        // as "no metadata."
-        const confirmBody = {
-            bucket: options.bucket,
-            path: options.path,
-            size: fileSize,
-            content_type: contentType,
-            etag,
-            overwrite,
-        };
-        if (options.metadata !== undefined) {
-            confirmBody.metadata = options.metadata;
-        }
-        const confirmRes = await fetch(`${this.config.baseUrl}/v1/sdk/storage/confirm`, {
-            method: 'POST',
-            headers: {
-                ...(await this.buildHeaders()),
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify(confirmBody),
-        });
-        if (!confirmRes.ok) {
-            throw await this.error(confirmRes, 'Failed to confirm upload');
-        }
-        const raw = await confirmRes.json();
-        const object = mapObjectFromServer(raw);
-        // ─── Step 4: Get download URL ───
-        const downloadUrl = await this.getDownloadUrl(options.bucket, options.path);
-        return { object, downloadUrl };
-    }
-    /**
-     * Apply a partial metadata update to an existing object. Returns the
-     * post-update {@link KoolbaseObject} with the merged metadata.
-     *
-     * **Merge semantics** (mirrors the server's JSONB merge):
-     *
-     * - Keys with a non-null string value are SET — added if missing,
-     *   replacing any existing value at the key otherwise.
-     * - Keys with `null` are DELETED from the stored metadata.
-     * - Keys ABSENT from `metadata` are untouched — pre-existing entries
-     *   for those keys remain unchanged.
-     *
-     * Validation runs server-side against the same rules as upload-time
-     * metadata; violations throw `KoolbaseStorageMetadataInvalidError`,
-     * whose `detail` field names the failing key and rule. The check is
-     * performed against the projected post-merge state, so adding a key
-     * that would push the object past the 50-key or 8KB ceiling is
-     * rejected before the row is mutated.
-     *
-     * @example
-     * // Add a tag, update an existing key, and drop another in one call:
-     * const updated = await Koolbase.storage.updateMetadata(
-     *   'photos',
-     *   'sunset.jpg',
-     *   {
-     *     category: 'landscape',  // SET or UPDATE
-     *     tag:      'sunset',     // SET or UPDATE
-     *     owner:    null,         // DELETE
-     *   }
-     * );
-     * console.log(updated.metadata);
-     * // -> { category: 'landscape', tag: 'sunset' }
-     */
-    async updateMetadata(bucket, path, metadata) {
-        const res = await fetch(`${this.config.baseUrl}/v1/sdk/storage/objects/metadata`, {
-            method: 'PATCH',
-            headers: {
-                ...(await this.buildHeaders()),
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({ bucket, path, metadata }),
-        });
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to update metadata');
-        }
-        const raw = await res.json();
-        return mapObjectFromServer(raw);
-    }
-    /**
-     * Get a signed download URL for a file.
-     */
-    async getDownloadUrl(bucket, path, versionId) {
-        let url = `${this.config.baseUrl}/v1/sdk/storage/download-url` +
-            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        if (versionId) {
-            url += `&version_id=${encodeURIComponent(versionId)}`;
-        }
-        const res = await fetch(url, { headers: await this.buildHeaders() });
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to get download URL');
-        }
-        const data = (await res.json());
-        return data.url;
-    }
-    /**
-     * Build the stable public CDN URL for a file in a public bucket.
-     *
-     * Returns the URL unconditionally — no check on whether the file
-     * exists or whether the bucket is actually public. Use when you
-     * know the file is in a public bucket and want the URL without a
-     * network round-trip (build-time URL generation, server-side
-     * rendering, batch image processing, etc.).
-     *
-     * For safer construction from an Object you already have, use
-     * {@link KoolbaseStorage.publicUrlForObject} — it checks the stored
-     * `r2Bucket` value and returns `null` when the object isn't in the
-     * public R2 bucket.
-     */
-    static publicUrl(args) {
-        // Encode each path segment individually so slashes are preserved
-        // while spaces, parens, hashes, and query characters are escaped.
-        const encoded = args.path.split('/').map(encodeURIComponent).join('/');
-        const opts = args.transform ? serializeTransform(args.transform) : '';
-        if (!opts) {
-            return `https://cdn.koolbase.com/${args.projectId}/${args.bucket}/${encoded}`;
-        }
-        return `https://cdn.koolbase.com/cdn-cgi/image/${opts}/${args.projectId}/${args.bucket}/${encoded}`;
-    }
-    /**
-     * Returns the stable CDN URL for an object when its bytes physically
-     * live in the public R2 bucket, `null` otherwise.
-     *
-     * Returns `null` for:
-     * - Files in private buckets (no public URL ever)
-     * - Legacy files in public buckets whose bytes still live in the
-     *   private R2 bucket from before Gap #2 (no permanent URL until
-     *   they're re-uploaded)
-     *
-     * The bucket name must be supplied because {@link KoolbaseObject}
-     * carries only the bucket ID, not its name. Typically the caller
-     * already knows which bucket they queried.
-     */
-    static publicUrlForObject(obj, bucket, options) {
-        if (obj.r2Bucket !== 'koolbase-storage-public')
-            return null;
-        return KoolbaseStorage.publicUrl({
-            projectId: obj.projectId,
-            bucket,
-            path: obj.path,
-            transform: options?.transform,
-        });
-    }
-    /**
-     * Builds a named-preset CDN URL. The preset is resolved at the Cloudflare
-     * edge by the koolbase-cdn-worker, which looks up
-     * `preset:{project_id}:{preset_name}` in Workers KV and applies the stored
-     * transformation options. Presets are managed in the dashboard under
-     * Storage → Presets.
-     *
-     * Unknown preset names yield a 404 at the edge — the URL itself always
-     * constructs successfully without a network round-trip.
-     *
-     * For safer construction from an Object you already have, use
-     * {@link KoolbaseStorage.publicUrlForObjectWithPreset} — it checks the
-     * stored `r2Bucket` value and returns `null` when the object isn't in the
-     * public R2 bucket.
-     */
-    static publicUrlWithPreset(args) {
-        const encoded = args.path.split('/').map(encodeURIComponent).join('/');
-        return `https://cdn.koolbase.com/p/${args.projectId}/${args.presetName}/${args.bucket}/${encoded}`;
-    }
-    /**
-     * Returns the named-preset CDN URL for the given object, or `null` if the
-     * object isn't in the public R2 bucket.
-     */
-    static publicUrlForObjectWithPreset(obj, bucket, presetName) {
-        if (obj.r2Bucket !== 'koolbase-storage-public')
-            return null;
-        return KoolbaseStorage.publicUrlWithPreset({
-            projectId: obj.projectId,
-            presetName,
-            bucket,
-            path: obj.path,
-        });
-    }
-    /**
-     * Delete a file from a bucket.
-     */
-    async delete(bucket, path, forcePurge) {
-        const url = forcePurge
-            ? `${this.config.baseUrl}/v1/sdk/storage/object?force_purge=true`
-            : `${this.config.baseUrl}/v1/sdk/storage/object`;
-        const res = await fetch(url, {
-            method: 'DELETE',
-            headers: {
-                ...(await this.buildHeaders()),
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({ bucket, path }),
-        });
-        if (res.status === 204)
-            return;
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to delete file');
-        }
-    }
-    /**
-     * List all versions of a file path, newest-first. Returns a flat list
-     * mixing the current row (with `isCurrent: true`) and all history
-     * rows. Delete markers are included so callers can render the full
-     * timeline; filter client-side to hide them if the UI only wants
-     * restorable versions.
-     *
-     * Returns an empty array (not an error) when the path has no history
-     * and no current row.
-     */
-    async listVersions(bucket, path) {
-        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions` +
-            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, { headers: await this.buildHeaders() });
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to list versions');
-        }
-        const data = (await res.json());
-        const list = Array.isArray(data.versions) ? data.versions : [];
-        return list.map((v) => fromVersionJson(v));
-    }
-    /**
-     * Fetch metadata for a single version by id. Works against both the
-     * current row and any history row — the response's `isCurrent` tells
-     * you which.
-     */
-    async getVersion(bucket, path, versionId) {
-        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
-            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, { headers: await this.buildHeaders() });
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to fetch version');
-        }
-        return fromVersionJson((await res.json()));
-    }
-    /**
-     * Bring a history version back as the current version. The
-     * previously-current row (if any) is snapshotted into history first,
-     * so this operation is itself a versioned event you can undo. The
-     * restored row gets a freshly-minted version_id; the target stays in
-     * history at its original version_id.
-     *
-     * Throws if the bucket has versioning off, if the target is the
-     * already-current version, or if the target is a delete marker.
-     */
-    async restoreVersion(bucket, path, versionId) {
-        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}/restore` +
-            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, {
-            method: 'POST',
-            headers: await this.buildHeaders(),
-        });
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to restore version');
-        }
-        return mapObjectFromServer(await res.json());
-    }
-    /**
-     * Hard-remove a single history version — both the metadata row and
-     * the .versions/ R2 bytes (or just the row, for delete markers).
-     * Refuses to operate on the current version; use {@link delete} with
-     * `forcePurge: true` to wipe everything for a path.
-     */
-    async purgeVersion(bucket, path, versionId) {
-        const url = `${this.config.baseUrl}/v1/sdk/storage/object-versions/${encodeURIComponent(versionId)}` +
-            `?bucket=${encodeURIComponent(bucket)}&path=${encodeURIComponent(path)}`;
-        const res = await fetch(url, {
-            method: 'DELETE',
-            headers: await this.buildHeaders(),
-        });
-        if (res.status === 204)
-            return;
-        if (!res.ok) {
-            throw await this.error(res, 'Failed to purge version');
-        }
-    }
-}
-exports.KoolbaseStorage = KoolbaseStorage;
-/**
- * Maps the snake_case server JSON to the camelCase {@link KoolbaseObject}.
- * Defensive: missing or null `metadata` (older / non-Koolbase responses)
- * is coerced to an empty object so callers always see a typed
- * `Record<string, string>` rather than null.
- */
-function mapObjectFromServer(raw) {
-    return {
-        id: raw.id,
-        projectId: raw.project_id,
-        bucketId: raw.bucket_id,
-        userId: raw.user_id ?? null,
-        path: raw.path,
-        size: raw.size ?? 0,
-        contentType: raw.content_type ?? null,
-        metadata: raw.metadata ?? {},
-        r2Bucket: raw.r2_bucket ?? 'koolbase-storage',
-        createdAt: raw.created_at,
-        updatedAt: raw.updated_at,
-    };
-}
-/**
- * Maps the snake_case server JSON of a version row to the camelCase
- * {@link KoolbaseObjectVersion}. Mirrors `fromObjectJson` shape.
- */
-function fromVersionJson(j) {
-    const rawMeta = j.metadata;
-    const metadata = {};
-    if (rawMeta && typeof rawMeta === 'object') {
-        for (const [k, v] of Object.entries(rawMeta)) {
-            if (typeof v === 'string')
-                metadata[k] = v;
-        }
-    }
-    return {
-        versionId: j.version_id ?? null,
-        path: j.path,
-        size: Number(j.size ?? 0),
-        contentType: j.content_type ?? null,
-        etag: j.etag ?? null,
-        metadata,
-        r2Bucket: j.r2_bucket ?? '',
-        userId: j.user_id ?? null,
-        isDeleteMarker: Boolean(j.is_delete_marker),
-        isCurrent: Boolean(j.is_current),
-        createdAt: j.created_at,
-    };
-}

package/dist/sync-engine.d.ts

@@ -1,30 +0,0 @@
-import { KoolbaseConfig } from './types';
-type SyncCallback = () => void;
-export declare class SyncEngine {
-    private config;
-    private getUserId;
-    private getToken;
-    private onSyncComplete?;
-    /**
-     * Called when the server rejects the caller's credentials during replay.
-     *
-     * Background sync is the likeliest place to meet a dead session: the queue
-     * replays writes made long before the session stopped being honoured.
-     */
-    private onSessionExpired?;
-    private unsubscribe?;
-    private isSyncing;
-    constructor(config: KoolbaseConfig, getUserId: () => string | null, getToken: () => Promise<string | null>, onSyncComplete?: SyncCallback, onSessionExpired?: () => Promise<void>);
-    start(): void;
-    stop(): void;
-    flush(): Promise<void>;
-    /**
-     * Sends one queued write, returning the revision the record now carries.
-     *
-     * The revision matters to whatever is queued behind this for the same record:
-     * those were composed against this one's result and cannot know its revision
-     * until the server assigns it.
-     */
-    private executeWrite;
-}
-export {};