@koolbase/react-native 9.1.0 → 10.0.0

package/dist/storage-errors.js

@@ -1,249 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KoolbaseStorageMetadataInvalidError = exports.KoolbaseStorageMimeTypeError = exports.KoolbaseStorageFileTooLargeError = exports.KoolbaseStorageQuotaError = exports.KoolbaseStoragePermissionError = exports.KoolbaseStorageValidationError = exports.KoolbaseStorageNotFoundError = exports.KoolbaseStorageConflictError = exports.KoolbaseStorageError = void 0;
-exports.koolbaseStorageError = koolbaseStorageError;
-exports.koolbaseStorageErrorFromResponse = koolbaseStorageErrorFromResponse;
-/**
- * Base error type for all Koolbase storage errors. Catchable via
- * `instanceof KoolbaseStorageError` to handle any storage-related failure
- * generically; subclasses let you handle specific cases.
- */
-class KoolbaseStorageError extends Error {
-    constructor(message, code) {
-        super(message);
-        this.code = code;
-        this.name = 'KoolbaseStorageError';
-        Object.setPrototypeOf(this, KoolbaseStorageError.prototype);
-    }
-}
-exports.KoolbaseStorageError = KoolbaseStorageError;
-/**
- * Thrown when an upload is rejected because an object already exists at
- * the requested path — the server responds with 409 Conflict and code
- * `path_conflict`. Catch it to give the user an "overwrite this file?"
- * prompt, then retry the upload with `overwrite: true`.
- *
- * `path` is the colliding path the server rejected, surfaced from the
- * response body for diagnostics and UI.
- *
- * @example
- * try {
- *   await Koolbase.storage.upload({
- *     bucket: 'avatars',
- *     path: 'me.png',
- *     file: { uri, name, type: 'image/png' },
- *   });
- * } catch (e) {
- *   if (e instanceof KoolbaseStorageConflictError) {
- *     const ok = await confirm(`${e.path} already exists. Overwrite?`);
- *     if (ok) {
- *       await Koolbase.storage.upload({
- *         bucket: 'avatars',
- *         path: 'me.png',
- *         file: { uri, name, type: 'image/png' },
- *         overwrite: true,
- *       });
- *     }
- *   }
- * }
- */
-class KoolbaseStorageConflictError extends KoolbaseStorageError {
-    constructor(message, path) {
-        super(message ?? 'An object already exists at this path', 'path_conflict');
-        this.path = path;
-        this.name = 'KoolbaseStorageConflictError';
-        Object.setPrototypeOf(this, KoolbaseStorageConflictError.prototype);
-    }
-}
-exports.KoolbaseStorageConflictError = KoolbaseStorageConflictError;
-/**
- * Thrown when the requested bucket or object does not exist — the server
- * responds with 404. Also surfaced for cross-tenant access attempts
- * (Koolbase's 404-over-403 convention prevents enumeration in
- * multi-tenant contexts).
- */
-class KoolbaseStorageNotFoundError extends KoolbaseStorageError {
-    constructor(message) {
-        super(message ?? 'The requested bucket or object was not found', 'not_found');
-        this.name = 'KoolbaseStorageNotFoundError';
-        Object.setPrototypeOf(this, KoolbaseStorageNotFoundError.prototype);
-    }
-}
-exports.KoolbaseStorageNotFoundError = KoolbaseStorageNotFoundError;
-/**
- * Thrown when the request is rejected as invalid — the server responds
- * with 400 (e.g. a malformed path, missing field, invalid bucket name).
- */
-class KoolbaseStorageValidationError extends KoolbaseStorageError {
-    constructor(message) {
-        super(message ?? 'The storage request was invalid', 'validation_error');
-        this.name = 'KoolbaseStorageValidationError';
-        Object.setPrototypeOf(this, KoolbaseStorageValidationError.prototype);
-    }
-}
-exports.KoolbaseStorageValidationError = KoolbaseStorageValidationError;
-/**
- * Thrown when the caller is authenticated but not allowed to perform the
- * storage operation — the server responds with 403.
- */
-class KoolbaseStoragePermissionError extends KoolbaseStorageError {
-    constructor(message) {
-        super(message ?? 'You do not have permission to perform this storage action', 'permission_denied');
-        this.name = 'KoolbaseStoragePermissionError';
-        Object.setPrototypeOf(this, KoolbaseStoragePermissionError.prototype);
-    }
-}
-exports.KoolbaseStoragePermissionError = KoolbaseStoragePermissionError;
-/**
- * Thrown when an upload would push the bucket past its configured
- * `max_size_bytes` quota — the server responds with 409 Conflict and code
- * `quota_exceeded`. The server cleans up the underlying R2 object before
- * returning; nothing leaks. Catch this to surface a "bucket is full"
- * message or prompt the caller to delete older files. The per-bucket
- * quota is set at bucket creation time and is currently immutable.
- *
- * Distinct from {@link KoolbaseStorageConflictError} (which also uses
- * 409 but means "path collides"); branch on the error type via
- * `instanceof`, not on status.
- */
-class KoolbaseStorageQuotaError extends KoolbaseStorageError {
-    constructor(message) {
-        super(message ?? 'Bucket quota exceeded', 'quota_exceeded');
-        this.name = 'KoolbaseStorageQuotaError';
-        Object.setPrototypeOf(this, KoolbaseStorageQuotaError.prototype);
-    }
-}
-exports.KoolbaseStorageQuotaError = KoolbaseStorageQuotaError;
-/**
- * Thrown when a single file exceeds the bucket's configured
- * `max_file_size_bytes` — the server responds with 413 Payload Too Large
- * and code `file_too_large`. The server cleans up the underlying R2
- * object before returning. The configured per-file limit lives on the
- * bucket record; check `Bucket.maxFileSizeBytes` to surface a clear
- * "files must be under X MB" message at the call site.
- */
-class KoolbaseStorageFileTooLargeError extends KoolbaseStorageError {
-    constructor(message) {
-        super(message ?? 'File exceeds the bucket maximum file size', 'file_too_large');
-        this.name = 'KoolbaseStorageFileTooLargeError';
-        Object.setPrototypeOf(this, KoolbaseStorageFileTooLargeError.prototype);
-    }
-}
-exports.KoolbaseStorageFileTooLargeError = KoolbaseStorageFileTooLargeError;
-/**
- * Thrown when an upload's content-type isn't in the bucket's configured
- * `allowed_mime_types` allowlist — the server responds with 415
- * Unsupported Media Type and code `mime_not_allowed`. The check runs at
- * presign time, so no bytes are transferred before rejection.
- *
- * Allowlists support `type/*` wildcards (e.g. `image/*` matches every
- * image content-type). A bucket with no allowlist configured accepts
- * every type.
- */
-class KoolbaseStorageMimeTypeError extends KoolbaseStorageError {
-    constructor(message) {
-        super(message ?? 'Content-type not allowed for this bucket', 'mime_not_allowed');
-        this.name = 'KoolbaseStorageMimeTypeError';
-        Object.setPrototypeOf(this, KoolbaseStorageMimeTypeError.prototype);
-    }
-}
-exports.KoolbaseStorageMimeTypeError = KoolbaseStorageMimeTypeError;
-/**
- * Thrown when an object metadata payload (either at upload-confirm time
- * or via `updateMetadata`) fails server-side validation — the server
- * responds with 400 and code `metadata_invalid`.
- *
- * The `detail` field carries the specific reason from the server — e.g.
- * `'key "foo bar": must match [a-z0-9_]+'`, `'exceeds 50 keys (got 53)'`,
- * or `'exceeds 8192 bytes total (sum of all key + value lengths)'`. The
- * detail names the failing key and rule so callers can fix the offending
- * entry without guessing what shape rule was violated.
- *
- * Validation rules (enforced server-side):
- * - At most 50 keys per object.
- * - At most 8KB total (sum of byte lengths across all keys + values).
- * - Keys: 1–64 chars, must match `[a-z0-9_]+`.
- * - Keys with a leading underscore are reserved for system use.
- * - Values: at most 1024 chars each.
- *
- * @example
- * try {
- *   await Koolbase.storage.updateMetadata('photos', 'sunset.jpg', {
- *     tag: 'sunset',
- *     'BAD KEY': 'oops',
- *   });
- * } catch (e) {
- *   if (e instanceof KoolbaseStorageMetadataInvalidError) {
- *     console.warn('Metadata rejected:', e.detail);
- *     // -> 'Metadata rejected: key "BAD KEY": must match [a-z0-9_]+'
- *   }
- * }
- */
-class KoolbaseStorageMetadataInvalidError extends KoolbaseStorageError {
-    constructor(message, detail) {
-        super(message ?? 'Metadata payload is invalid', 'metadata_invalid');
-        this.detail = detail;
-        this.name = 'KoolbaseStorageMetadataInvalidError';
-        Object.setPrototypeOf(this, KoolbaseStorageMetadataInvalidError.prototype);
-    }
-}
-exports.KoolbaseStorageMetadataInvalidError = KoolbaseStorageMetadataInvalidError;
-/**
- * Maps a non-2xx storage-layer response to a typed
- * {@link KoolbaseStorageError}, preferring the server's stable `code` and
- * falling back to the HTTP status for older or uncoded responses. Always
- * returns an error to throw.
- *
- * Status-fallback note: HTTP 409 covers both path_conflict and
- * quota_exceeded. Without a `code` field, the mapper defaults 409 to
- * {@link KoolbaseStorageConflictError} since path collisions are the more
- * common case. Modern Koolbase servers always emit `code`, so this only
- * matters for very old API responses or non-Koolbase 409s.
- */
-function koolbaseStorageError(status, body, fallbackMessage = 'Storage request failed') {
-    const code = body?.code;
-    const message = body?.error ?? fallbackMessage;
-    // ─── code-first ───
-    switch (code) {
-        case 'path_conflict':
-            return new KoolbaseStorageConflictError(message, body?.path);
-        case 'quota_exceeded':
-            return new KoolbaseStorageQuotaError(message);
-        case 'file_too_large':
-            return new KoolbaseStorageFileTooLargeError(message);
-        case 'mime_not_allowed':
-            return new KoolbaseStorageMimeTypeError(message);
-        case 'metadata_invalid':
-            return new KoolbaseStorageMetadataInvalidError(message, body?.detail);
-    }
-    // ─── status fallback (pre-code servers or uncoded paths) ───
-    switch (status) {
-        case 409:
-            return new KoolbaseStorageConflictError(message);
-        case 413:
-            return new KoolbaseStorageFileTooLargeError(message);
-        case 415:
-            return new KoolbaseStorageMimeTypeError(message);
-        case 404:
-            return new KoolbaseStorageNotFoundError(message);
-        case 403:
-            return new KoolbaseStoragePermissionError(message);
-        case 400:
-            return new KoolbaseStorageValidationError(message);
-    }
-    return new KoolbaseStorageError(message, code);
-}
-/**
- * Convenience wrapper over {@link koolbaseStorageError} that decodes the
- * response body for you. Use at call sites that have the raw `Response`.
- */
-async function koolbaseStorageErrorFromResponse(res, fallbackMessage = 'Storage request failed') {
-    let body = {};
-    try {
-        body = await res.json();
-    }
-    catch (_) {
-        // body wasn't JSON — fall through with empty object
-    }
-    return koolbaseStorageError(res.status, body, fallbackMessage);
-}

package/dist/storage.d.ts

@@ -1,184 +0,0 @@
-import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseObjectVersion, KoolbaseImageTransform } from './types';
-/**
- * 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.
- */
-export declare class KoolbaseStorage {
-    private config;
-    private getToken;
-    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>);
-    private buildHeaders;
-    /**
-     * 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.
-     */
-    upload(options: UploadOptions): Promise<UploadResult>;
-    /**
-     * 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' }
-     */
-    updateMetadata(bucket: string, path: string, metadata: Record<string, string | null>): Promise<KoolbaseObject>;
-    /**
-     * Get a signed download URL for a file.
-     */
-    getDownloadUrl(bucket: string, path: string, versionId?: string): Promise<string>;
-    /**
-     * 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: {
-        projectId: string;
-        bucket: string;
-        path: string;
-        /**
-         * Optional Cloudflare Image Transformations. Adds a `/cdn-cgi/image/`
-         * URL prefix; billed against the koolbase.com zone's free monthly
-         * allocation (5,000 unique transforms/month). Each unique combination
-         * of `path` + options is cached and billed only once per calendar month.
-         */
-        transform?: KoolbaseImageTransform;
-    }): string;
-    /**
-     * 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: KoolbaseObject, bucket: string, options?: {
-        transform?: KoolbaseImageTransform;
-    }): string | null;
-    /**
-     * 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: {
-        projectId: string;
-        presetName: string;
-        bucket: string;
-        path: string;
-    }): string;
-    /**
-     * 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: KoolbaseObject, bucket: string, presetName: string): string | null;
-    /**
-     * Delete a file from a bucket.
-     */
-    delete(bucket: string, path: string, forcePurge?: boolean): Promise<void>;
-    /**
-     * 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.
-     */
-    listVersions(bucket: string, path: string): Promise<KoolbaseObjectVersion[]>;
-    /**
-     * 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.
-     */
-    getVersion(bucket: string, path: string, versionId: string): Promise<KoolbaseObjectVersion>;
-    /**
-     * 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.
-     */
-    restoreVersion(bucket: string, path: string, versionId: string): Promise<KoolbaseObject>;
-    /**
-     * 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.
-     */
-    purgeVersion(bucket: string, path: string, versionId: string): Promise<void>;
-}