@koolbase/core 10.0.0

package/dist/cjs/storage-errors.js

@@ -0,0 +1,253 @@
+"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;
+const errors_js_1 = require("./errors.js");
+/**
+ * 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 errors_js_1.KoolbaseError {
+    constructor(message, code) {
+        super(message, 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 401:
+            // A rejected credential is not a storage problem: a session stops
+            // working for the whole SDK at once, so it raises the shared type.
+            return new errors_js_1.KoolbaseUnauthenticatedError(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/cjs/storage.d.ts

@@ -0,0 +1,198 @@
+import { KoolbaseConfig, UploadOptions, UploadResult, KoolbaseObject, KoolbaseObjectVersion, KoolbaseImageTransform } from './types.js';
+/**
+ * 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;
+    /**
+     * Called when the server rejects the caller's credentials.
+     *
+     * A session stops working for the whole SDK at once, not one subsystem at a
+     * time, so a 401 met during an upload has to clear it just as one met during a
+     * query does. Otherwise an app whose failing call happens to be a file upload
+     * keeps believing it is signed in.
+     */
+    private onSessionExpired?;
+    constructor(config: KoolbaseConfig, getToken: () => Promise<string | null>, onSessionExpired?: () => Promise<void>);
+    /**
+     * Builds the error for a failed response and clears the session when the
+     * credentials were refused, before the error reaches the caller.
+     */
+    private error;
+    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>;
+}