@koolbase/core 11.1.0 → 11.3.0

package/dist/esm/database-errors.js

@@ -1,4 +1,4 @@
-import { KoolbaseError, KoolbaseUnauthenticatedError } from './errors.js';
+import { KoolbaseError, KoolbasePlanLimitError, KoolbaseUnauthenticatedError } from './errors.js';
 /**
  * Base class for errors surfaced by the Koolbase data layer (database reads
  * and writes). Every data error carries a `message` and, when the server
@@ -39,6 +39,231 @@ export class KoolbaseDataError extends KoolbaseError {
  *   }
  * }
  */
+/**
+ * An upsert whose filter matched more than one record.
+ *
+ * Refused rather than resolved: picking one of several would be a silent
+ * guess about which row the caller meant, and the wrong guess overwrites data
+ * nobody asked to change. Narrow the filter, or add a unique constraint over
+ * the fields you are matching on so the ambiguity cannot arise.
+ */
+/**
+ * The record changed between reading it and writing it.
+ *
+ * Optimistic concurrency: a write carrying a revision is refused when the
+ * server has moved on, rather than overwriting whatever happened in between.
+ * The refusal carries the server's current record and both revisions, so
+ * resolving needs no second fetch — and cannot race one.
+ *
+ * Distinct from KoolbaseConflict, which models a queued OFFLINE write and
+ * carries a baseline as well, because a change composed hours ago needs its
+ * original context to be resolvable. Here the caller still has their data in
+ * hand.
+ *
+ * Until 11.3.0 this arrived as a generic data error and the details had to be
+ * dug out of an untyped bag — the information the server went to the trouble
+ * of attaching, unreachable in practice.
+ */
+/** A vector field with that name already exists on the collection. */
+/**
+ * A seed or import operation was refused. The code says which stage:
+ * invalid_seed_file (the file itself, with a "problems" list in details),
+ * seed_key_not_unique (the key does not identify rows uniquely),
+ * seed_needs_decision (conflicts need a choice before proceeding), or
+ * seed_conflicts_require_force (overwriting would discard the target's
+ * version of rows that changed on both sides — details carry the rows).
+ *
+ * One class with the code distinguishing them, rather than four: these are
+ * dashboard and CLI operations, and a caller handling one handles them the
+ * same way — show the reason and let a human decide.
+ */
+export class KoolbaseSeedError extends KoolbaseDataError {
+    constructor(message, code) {
+        super(message, code);
+        this.name = 'KoolbaseSeedError';
+        Object.setPrototypeOf(this, KoolbaseSeedError.prototype);
+    }
+}
+/** A project slug that another project already holds. */
+export class KoolbaseSlugTakenError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'A project with this slug already exists', 'slug_taken');
+        this.name = 'KoolbaseSlugTakenError';
+        Object.setPrototypeOf(this, KoolbaseSlugTakenError.prototype);
+    }
+}
+/** An invitation that has been revoked or has expired. */
+export class KoolbaseInvitationInvalidError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'This invitation has been revoked or expired', 'invitation_invalid');
+        this.name = 'KoolbaseInvitationInvalidError';
+        Object.setPrototypeOf(this, KoolbaseInvitationInvalidError.prototype);
+    }
+}
+/** The project id in the request is not valid. */
+export class KoolbaseProjectInvalidError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Invalid project id', 'project_invalid');
+        this.name = 'KoolbaseProjectInvalidError';
+        Object.setPrototypeOf(this, KoolbaseProjectInvalidError.prototype);
+    }
+}
+/** The request body could not be decoded. */
+export class KoolbaseInvalidBodyError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Could not decode the request body', 'invalid_body');
+        this.name = 'KoolbaseInvalidBodyError';
+        Object.setPrototypeOf(this, KoolbaseInvalidBodyError.prototype);
+    }
+}
+/**
+ * The request asked for no change — an update with nothing to update.
+ */
+export class KoolbaseNoChangesError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'The request contains no changes', 'no_changes');
+        this.name = 'KoolbaseNoChangesError';
+        Object.setPrototypeOf(this, KoolbaseNoChangesError.prototype);
+    }
+}
+/**
+ * Something already exists, or something is in the wrong state, where the
+ * server did not say more than that.
+ *
+ * Carries whichever generic code arrived — conflict, duplicate,
+ * state_conflict — rather than four classes for codes that differ only in
+ * spelling. A caller who needs to branch finely is being underserved by the
+ * server, not by this.
+ */
+export class KoolbaseStateConflictError extends KoolbaseDataError {
+    constructor(message, code) {
+        super(message, code);
+        this.name = 'KoolbaseStateConflictError';
+        Object.setPrototypeOf(this, KoolbaseStateConflictError.prototype);
+    }
+}
+export class KoolbaseVectorFieldExistsError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'A vector field with that name already exists on this collection', 'vector_field_exists');
+        this.name = 'KoolbaseVectorFieldExistsError';
+        Object.setPrototypeOf(this, KoolbaseVectorFieldExistsError.prototype);
+    }
+}
+/**
+ * A backfill was asked for on a field that embeds nothing automatically.
+ * Set provider, model and source_field on the field first.
+ */
+export class KoolbaseFieldNotAutoEmbedError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'This vector field has no auto-embedding config; set provider, model and source_field first', 'field_not_auto_embed');
+        this.name = 'KoolbaseFieldNotAutoEmbedError';
+        Object.setPrototypeOf(this, KoolbaseFieldNotAutoEmbedError.prototype);
+    }
+}
+/**
+ * Embedding config is partial. Provider, model and source_field are set
+ * together or cleared together — half a configuration is refused rather than
+ * half-applied, which would embed against a model nobody chose.
+ */
+export class KoolbaseInvalidEmbeddingConfigError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Embedding config requires provider, model and source_field together, or all cleared', 'invalid_embedding_config');
+        this.name = 'KoolbaseInvalidEmbeddingConfigError';
+        Object.setPrototypeOf(this, KoolbaseInvalidEmbeddingConfigError.prototype);
+    }
+}
+/**
+ * The project has no embedding provider configured. Embedding runs on the
+ * project's own Gemini or OpenAI key.
+ */
+export class KoolbaseProviderNotConfiguredError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'No embedding provider is configured for this project', 'provider_not_configured');
+        this.name = 'KoolbaseProviderNotConfiguredError';
+        Object.setPrototypeOf(this, KoolbaseProviderNotConfiguredError.prototype);
+    }
+}
+/** The configured provider's credentials were rejected by the provider. */
+export class KoolbaseProviderInvalidError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'The embedding provider credentials are not valid', 'provider_invalid');
+        this.name = 'KoolbaseProviderInvalidError';
+        Object.setPrototypeOf(this, KoolbaseProviderInvalidError.prototype);
+    }
+}
+export class KoolbaseRevisionMismatchError extends KoolbaseDataError {
+    constructor(message, expectedRevision, currentRevision, 
+    /** The record as the server holds it now. */
+    current) {
+        super(message ?? 'The record has changed since you read it', 'revision_mismatch');
+        this.expectedRevision = expectedRevision;
+        this.currentRevision = currentRevision;
+        this.current = current;
+        this.name = 'KoolbaseRevisionMismatchError';
+        Object.setPrototypeOf(this, KoolbaseRevisionMismatchError.prototype);
+    }
+}
+/**
+ * The same idempotency key sent with different data.
+ *
+ * Refused rather than replayed: the two requests do not agree, so neither
+ * answer is safe. Usually a key reused by accident across two operations.
+ */
+export class KoolbaseIdempotencyKeyReusedError extends KoolbaseDataError {
+    /**
+     * Carries its code: the database package calls this idempotency_key_reused
+     * and fiscal calls it idempotency_conflict, and an error reporting a code
+     * the server did not send is a small lie that apps branching on e.code act
+     * on.
+     */
+    constructor(message, code = 'idempotency_key_reused') {
+        super(message ?? 'Idempotency key reused with different data', code);
+        this.name = 'KoolbaseIdempotencyKeyReusedError';
+        Object.setPrototypeOf(this, KoolbaseIdempotencyKeyReusedError.prototype);
+    }
+}
+/** A batch write failed for a reason the server did not classify further. */
+export class KoolbaseBatchFailedError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'The batch write failed', 'batch_failed');
+        this.name = 'KoolbaseBatchFailedError';
+        Object.setPrototypeOf(this, KoolbaseBatchFailedError.prototype);
+    }
+}
+/**
+ * Creating a unique constraint over data that already breaks it. details
+ * carry the offending values, so they can be shown rather than hunted for.
+ */
+export class KoolbaseDuplicateValuesError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'The collection has duplicate values for these fields', 'duplicate_values');
+        this.name = 'KoolbaseDuplicateValuesError';
+        Object.setPrototypeOf(this, KoolbaseDuplicateValuesError.prototype);
+    }
+}
+export class KoolbaseAmbiguousMatchError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Upsert match resolved to more than one record', 'ambiguous_match');
+        this.name = 'KoolbaseAmbiguousMatchError';
+        Object.setPrototypeOf(this, KoolbaseAmbiguousMatchError.prototype);
+    }
+}
+/** A unique constraint already covers those fields. */
+export class KoolbaseConstraintExistsError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'A unique constraint already exists for these fields', 'constraint_exists');
+        this.name = 'KoolbaseConstraintExistsError';
+        Object.setPrototypeOf(this, KoolbaseConstraintExistsError.prototype);
+    }
+}
+/** No such unique constraint. */
+export class KoolbaseConstraintNotFoundError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'Unique constraint not found', 'constraint_not_found');
+        this.name = 'KoolbaseConstraintNotFoundError';
+        Object.setPrototypeOf(this, KoolbaseConstraintNotFoundError.prototype);
+    }
+}
 export class KoolbaseConflictError extends KoolbaseDataError {
     constructor(message, field) {
         super(message ?? 'Value violates a unique constraint', 'unique_violation');
@@ -53,8 +278,15 @@ export class KoolbaseConflictError extends KoolbaseDataError {
  * `collection_not_found`.
  */
 export class KoolbaseNotFoundError extends KoolbaseDataError {
-    constructor(message) {
-        super(message ?? 'The requested resource was not found', 'not_found');
+    /**
+     * The code is carried rather than fixed, because the server distinguishes
+     * what was missing — a record, a collection, a vector field — and an app
+     * reading e.code should get that answer rather than the category. Catching
+     * the class still works for anyone who only cares that something was
+     * absent.
+     */
+    constructor(message, code = 'not_found') {
+        super(message ?? 'The requested resource was not found', code);
         this.name = 'KoolbaseNotFoundError';
         Object.setPrototypeOf(this, KoolbaseNotFoundError.prototype);
     }
@@ -64,8 +296,14 @@ export class KoolbaseNotFoundError extends KoolbaseDataError {
  * 400 and code `validation_error`.
  */
 export class KoolbaseValidationError extends KoolbaseDataError {
-    constructor(message) {
-        super(message ?? 'The request was invalid', 'validation_error');
+    /**
+     * Carries its code for the same reason KoolbaseNotFoundError does: a
+     * dimension the platform does not support and a vector pointed at the wrong
+     * collection are both validation failures, and an app should still be able
+     * to tell which without reading the message.
+     */
+    constructor(message, code = 'validation_error') {
+        super(message ?? 'The request was invalid', code);
         this.name = 'KoolbaseValidationError';
         Object.setPrototypeOf(this, KoolbaseValidationError.prototype);
     }
@@ -75,6 +313,20 @@ export class KoolbaseValidationError extends KoolbaseDataError {
  * operation — the server responds with 403 and code `permission_denied`
  * (typically a collection access rule rejecting the read/write).
  */
+/**
+ * Authenticated, and not permitted to do this — distinct from a rule denying
+ * access to a record. Its own class rather than folding into
+ * KoolbasePermissionError, which hardcodes permission_denied: an error
+ * reporting a code the server did not send is a small lie, and apps that
+ * branch on e.code rather than instanceof would act on it.
+ */
+export class KoolbaseInsufficientAuthorityError extends KoolbaseDataError {
+    constructor(message) {
+        super(message ?? 'You do not have the authority to perform this action', 'insufficient_authority');
+        this.name = 'KoolbaseInsufficientAuthorityError';
+        Object.setPrototypeOf(this, KoolbaseInsufficientAuthorityError.prototype);
+    }
+}
 export class KoolbasePermissionError extends KoolbaseDataError {
     constructor(message) {
         super(message ?? 'You do not have permission to perform this action', 'permission_denied');
@@ -144,14 +396,70 @@ export function koolbaseDataError(status, body, fallbackMessage = 'Request faile
     switch (code) {
         case 'unique_violation':
             return attach(new KoolbaseConflictError(message, field));
+        case 'plan_limit_reached': {
+            const d = (body?.details ?? {});
+            return new KoolbasePlanLimitError(message, d.resource, d.limit, d.plan);
+        }
+        case 'invalid_seed_file':
+        case 'seed_key_not_unique':
+        case 'seed_needs_decision':
+        case 'seed_conflicts_require_force':
+            return attach(new KoolbaseSeedError(message, code));
+        case 'slug_taken':
+            return attach(new KoolbaseSlugTakenError(message));
+        case 'invitation_invalid':
+            return attach(new KoolbaseInvitationInvalidError(message));
+        case 'project_invalid':
+            return attach(new KoolbaseProjectInvalidError(message));
+        case 'invalid_body':
+            return attach(new KoolbaseInvalidBodyError(message));
+        case 'no_changes':
+            return attach(new KoolbaseNoChangesError(message));
+        case 'conflict':
+        case 'duplicate':
+        case 'state_conflict':
+            return attach(new KoolbaseStateConflictError(message, code));
+        case 'vector_field_exists':
+            return attach(new KoolbaseVectorFieldExistsError(message));
+        case 'field_not_auto_embed':
+            return attach(new KoolbaseFieldNotAutoEmbedError(message));
+        case 'invalid_embedding_config':
+            return attach(new KoolbaseInvalidEmbeddingConfigError(message));
+        case 'provider_not_configured':
+            return attach(new KoolbaseProviderNotConfiguredError(message));
+        case 'provider_invalid':
+            return attach(new KoolbaseProviderInvalidError(message));
+        case 'revision_mismatch': {
+            // The typed fields come off details, which the server attaches for
+            // exactly this. attach() still puts the whole bag on the error, so
+            // nothing is lost for a caller reading it directly.
+            const d = (body?.details ?? {});
+            return attach(new KoolbaseRevisionMismatchError(message, d.expected_revision, d.current_revision, d.record));
+        }
+        // Two codes, one situation — the database and fiscal packages name it
+        // differently and a caller should not have to know which spoke.
+        case 'idempotency_key_reused':
+        case 'idempotency_conflict':
+            return attach(new KoolbaseIdempotencyKeyReusedError(message, code));
+        case 'batch_failed':
+            return attach(new KoolbaseBatchFailedError(message));
+        case 'duplicate_values':
+            return attach(new KoolbaseDuplicateValuesError(message));
+        case 'ambiguous_match':
+            return attach(new KoolbaseAmbiguousMatchError(message));
+        case 'constraint_exists':
+            return attach(new KoolbaseConstraintExistsError(message));
+        case 'constraint_not_found':
+            return attach(new KoolbaseConstraintNotFoundError(message));
+        case 'insufficient_authority':
+            return attach(new KoolbaseInsufficientAuthorityError(message));
         case 'not_found':
         case 'record_not_found':
         case 'collection_not_found':
         case 'vector_not_found':
         case 'vector_field_not_found':
-            return attach(new KoolbaseNotFoundError(message));
+            return attach(new KoolbaseNotFoundError(message, code));
         case 'unauthenticated':
-        case 'session_expired':
         case 'invalid_token':
             return attach(new KoolbaseUnauthenticatedError(message));
         case 'permission_denied':
@@ -161,7 +469,7 @@ export function koolbaseDataError(status, body, fallbackMessage = 'Request faile
         case 'validation_error':
         case 'vector_collection_mismatch':
         case 'unsupported_dimension':
-            return attach(new KoolbaseValidationError(message));
+            return attach(new KoolbaseValidationError(message, code));
         case 'vector_dimension_mismatch':
             return attach(new KoolbaseVectorDimensionMismatchError(message));
     }

package/dist/esm/errors.d.ts

@@ -59,6 +59,20 @@ export declare class KoolbaseUnauthenticatedError extends KoolbaseError {
  * updates are conflict-safe and some quietly are not, which is a worse guarantee
  * than a clear refusal.
  */
+/**
+ * The project's plan does not allow this — a 402 carrying which resource, the
+ * limit, and the plan.
+ *
+ * Shared rather than per-domain: creating a collection, uploading an object
+ * and deploying a function can all hit it, and an app showing an upgrade
+ * prompt wants one type to catch.
+ */
+export declare class KoolbasePlanLimitError extends KoolbaseError {
+    readonly resource?: string | undefined;
+    readonly limit?: number | undefined;
+    readonly plan?: string | undefined;
+    constructor(message?: string, resource?: string | undefined, limit?: number | undefined, plan?: string | undefined);
+}
 export declare class KoolbaseOfflineBaselineUnavailableError extends KoolbaseError {
     constructor(message: string);
 }

package/dist/esm/errors.js

@@ -70,6 +70,24 @@ export class KoolbaseUnauthenticatedError extends KoolbaseError {
  * updates are conflict-safe and some quietly are not, which is a worse guarantee
  * than a clear refusal.
  */
+/**
+ * The project's plan does not allow this — a 402 carrying which resource, the
+ * limit, and the plan.
+ *
+ * Shared rather than per-domain: creating a collection, uploading an object
+ * and deploying a function can all hit it, and an app showing an upgrade
+ * prompt wants one type to catch.
+ */
+export class KoolbasePlanLimitError extends KoolbaseError {
+    constructor(message, resource, limit, plan) {
+        super(message ?? 'This exceeds your plan limit', 'plan_limit_reached');
+        this.resource = resource;
+        this.limit = limit;
+        this.plan = plan;
+        this.name = 'KoolbasePlanLimitError';
+        Object.setPrototypeOf(this, KoolbasePlanLimitError.prototype);
+    }
+}
 export class KoolbaseOfflineBaselineUnavailableError extends KoolbaseError {
     constructor(message) {
         super(message, 'offline_baseline_unavailable');

package/dist/esm/function-errors.d.ts

@@ -47,5 +47,24 @@ export declare class FunctionQuotaExceededError extends FunctionInvokeError {
 export declare class FunctionExecutionError extends FunctionInvokeError {
     constructor(message: string, statusCode?: number);
 }
+/**
+ * The function ran past its timeout and was killed.
+ *
+ * Its own type because the remedy is different from a function that threw:
+ * a timeout means retry, or raise the function's timeout at deploy, or move
+ * the slow part elsewhere. Without this it arrived as FunctionExecutionError
+ * — indistinguishable from an exception, which is the one thing it is not.
+ * The server already tells them apart; it logs 504 as "timeout".
+ */
+export declare class FunctionTimeoutError extends FunctionInvokeError {
+    constructor(message: string);
+}
+/**
+ * Too many invocations, too fast. Distinct from a quota being spent: this one
+ * clears by waiting.
+ */
+export declare class FunctionRateLimitError extends FunctionInvokeError {
+    constructor(message: string);
+}
 /** Builds the right error for a failed invocation. */
 export declare function functionInvokeError(status: number, message: string): KoolbaseError;

package/dist/esm/function-errors.js

@@ -71,6 +71,33 @@ export class FunctionExecutionError extends FunctionInvokeError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * The function ran past its timeout and was killed.
+ *
+ * Its own type because the remedy is different from a function that threw:
+ * a timeout means retry, or raise the function's timeout at deploy, or move
+ * the slow part elsewhere. Without this it arrived as FunctionExecutionError
+ * — indistinguishable from an exception, which is the one thing it is not.
+ * The server already tells them apart; it logs 504 as "timeout".
+ */
+export class FunctionTimeoutError extends FunctionInvokeError {
+    constructor(message) {
+        super(message, 504, 'timeout');
+        this.name = 'FunctionTimeoutError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/**
+ * Too many invocations, too fast. Distinct from a quota being spent: this one
+ * clears by waiting.
+ */
+export class FunctionRateLimitError extends FunctionInvokeError {
+    constructor(message) {
+        super(message, 429, 'rate_limit');
+        this.name = 'FunctionRateLimitError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** Builds the right error for a failed invocation. */
 export function functionInvokeError(status, message) {
     switch (status) {
@@ -86,6 +113,11 @@ export function functionInvokeError(status, message) {
             return new FunctionValidationError(message);
         case 402:
             return new FunctionQuotaExceededError(message);
+        case 429:
+            return new FunctionRateLimitError(message);
+        case 504:
+            // Before the generic 5xx branch: a timeout is not an exception.
+            return new FunctionTimeoutError(message);
     }
     if (status >= 500)
         return new FunctionExecutionError(message, status);

package/dist/esm/storage-errors.d.ts

@@ -76,6 +76,34 @@ export declare class KoolbaseStoragePermissionError extends KoolbaseStorageError
  * 409 but means "path collides"); branch on the error type via
  * `instanceof`, not on status.
  */
+/**
+ * The presigned upload was confirmed after its window closed.
+ *
+ * An upload URL has a lifetime. A user who picks a file, gets distracted and
+ * comes back twenty minutes later hits this — so it is a retry, not a
+ * failure: presign again and send the same bytes. Worth catching rather than
+ * showing "upload failed" to someone whose file was fine.
+ */
+/**
+ * Minting a presigned upload URL failed. The message carries the underlying
+ * reason — a misconfigured bucket, or the object store refusing.
+ *
+ * Not the user's doing, and not a retry they can fix: distinct from
+ * KoolbaseUploadExpiredError, which is a retry that will work.
+ */
+export declare class KoolbaseUploadURLFailedError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+export declare class KoolbaseUploadExpiredError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
+/**
+ * A bucket cap set below what the bucket already holds. A dashboard
+ * operation rather than an app one, mapped so it does not arrive untyped.
+ */
+export declare class KoolbaseCapBelowUsageError extends KoolbaseStorageError {
+    constructor(message?: string);
+}
 export declare class KoolbaseStorageQuotaError extends KoolbaseStorageError {
     constructor(message?: string);
 }

package/dist/esm/storage-errors.js

@@ -1,4 +1,4 @@
-import { KoolbaseError, KoolbaseUnauthenticatedError } from './errors.js';
+import { KoolbaseError, KoolbasePlanLimitError, KoolbaseUnauthenticatedError } from './errors.js';
 /**
  * Base error type for all Koolbase storage errors. Catchable via
  * `instanceof KoolbaseStorageError` to handle any storage-related failure
@@ -96,6 +96,46 @@ export class KoolbaseStoragePermissionError extends KoolbaseStorageError {
  * 409 but means "path collides"); branch on the error type via
  * `instanceof`, not on status.
  */
+/**
+ * The presigned upload was confirmed after its window closed.
+ *
+ * An upload URL has a lifetime. A user who picks a file, gets distracted and
+ * comes back twenty minutes later hits this — so it is a retry, not a
+ * failure: presign again and send the same bytes. Worth catching rather than
+ * showing "upload failed" to someone whose file was fine.
+ */
+/**
+ * Minting a presigned upload URL failed. The message carries the underlying
+ * reason — a misconfigured bucket, or the object store refusing.
+ *
+ * Not the user's doing, and not a retry they can fix: distinct from
+ * KoolbaseUploadExpiredError, which is a retry that will work.
+ */
+export class KoolbaseUploadURLFailedError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'Could not create an upload URL', 'upload_url_failed');
+        this.name = 'KoolbaseUploadURLFailedError';
+        Object.setPrototypeOf(this, KoolbaseUploadURLFailedError.prototype);
+    }
+}
+export class KoolbaseUploadExpiredError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'This upload is past the confirmation window — please re-upload', 'upload_expired');
+        this.name = 'KoolbaseUploadExpiredError';
+        Object.setPrototypeOf(this, KoolbaseUploadExpiredError.prototype);
+    }
+}
+/**
+ * A bucket cap set below what the bucket already holds. A dashboard
+ * operation rather than an app one, mapped so it does not arrive untyped.
+ */
+export class KoolbaseCapBelowUsageError extends KoolbaseStorageError {
+    constructor(message) {
+        super(message ?? 'The cap is below the bucket\'s current usage', 'cap_below_usage');
+        this.name = 'KoolbaseCapBelowUsageError';
+        Object.setPrototypeOf(this, KoolbaseCapBelowUsageError.prototype);
+    }
+}
 export class KoolbaseStorageQuotaError extends KoolbaseStorageError {
     constructor(message) {
         super(message ?? 'Bucket quota exceeded', 'quota_exceeded');
@@ -193,14 +233,24 @@ export function koolbaseStorageError(status, body, fallbackMessage = 'Storage re
     switch (code) {
         case 'path_conflict':
             return new KoolbaseStorageConflictError(message, body?.path);
+        case 'plan_limit_reached': {
+            const d = (body?.details ?? {});
+            return new KoolbasePlanLimitError(message, d.resource, d.limit, d.plan);
+        }
         case 'quota_exceeded':
             return new KoolbaseStorageQuotaError(message);
+        case 'upload_expired':
+            return new KoolbaseUploadExpiredError(message);
+        case 'cap_below_usage':
+            return new KoolbaseCapBelowUsageError(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);
+        case 'upload_url_failed':
+            return new KoolbaseUploadURLFailedError(message);
     }
     // ─── status fallback (pre-code servers or uncoded paths) ───
     switch (status) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koolbase/core",
-  "version": "11.1.0",
+  "version": "11.3.0",
   "description": "Koolbase SDK core \u2014 shared behaviour behind @koolbase/react-native and @koolbase/js. Install one of those, not this.",
   "main": "./dist/cjs/index.js",
   "types": "./dist/esm/index.d.ts",