@tinycloud/sdk-services 3.0.0 → 3.1.0-beta.2

package/dist/index.d.cts

@@ -1075,6 +1075,24 @@ declare function parseAuthError(responseText: string): {
  * Create a service error for unauthorized action (missing capability).
  */
 declare function authUnauthorizedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/**
+ * Authorization verdict read from an error's structure, never its message:
+ * - `"unauthenticated"`: HTTP 401 — the session is missing or stale.
+ * - `"forbidden"`: HTTP 403, or `AUTH_UNAUTHORIZED` without a status — the
+ *   session is valid but lacks the capability.
+ * - `"other"`: a non-authorization HTTP error status (4xx/5xx).
+ */
+type AuthorizationVerdict = "unauthenticated" | "forbidden" | "other";
+/**
+ * Classify an error from its typed HTTP error status (`status`, `statusCode`,
+ * or `meta.status`, 4xx/5xx only) and `AUTH_UNAUTHORIZED` code, following the
+ * `cause` chain outer-first (at most {@link MAX_CAUSE_DEPTH} links, cycles
+ * stop the walk) so wrappers that rethrow with `cause` keep the verdict. The
+ * outermost error status decides, so an outer 5xx keeps its retry budget even
+ * over an inner 401. Returns `undefined` for untyped errors; only then may
+ * callers fall back to message heuristics.
+ */
+declare function authorizationVerdictOf(error: unknown): AuthorizationVerdict | undefined;
 /**
  * Create a service error for storage quota exceeded (402 Payment Required).
  */
@@ -1083,6 +1101,36 @@ declare function storageQuotaExceededError(service: string, message: string, met
  * Create a service error for storage limit reached (413 Payload Too Large).
  */
 declare function storageLimitReachedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/** Shown when a write is rejected because the owner's storage is full. */
+declare const STORAGE_FULL_MESSAGE = "TinyCloud storage is full, so this change was not saved. Reading still works. Free up space or upgrade your plan to save again.";
+/** Shown when a write is larger than the storage the owner has left. */
+declare const STORAGE_WRITE_TOO_LARGE_MESSAGE = "This change is larger than the TinyCloud storage you have left, so it was not saved. Reading still works. Free up space or upgrade your plan to save it.";
+/**
+ * Parse the byte counts from a node storage rejection
+ * ("... Used: 155744 bytes, Limit: 0 bytes"). The limit is the share of the
+ * owner's account-wide budget left for this space, so it is 0 when the
+ * owner's other spaces already use the whole budget.
+ */
+declare function parseStorageQuotaBytes(responseText: string): {
+    usedBytes: number;
+    limitBytes: number;
+} | undefined;
+/**
+ * Build the error for a write the node rejected for storage: 402 when storage
+ * is already full, 413 when this write is larger than what is left. KV, SQL
+ * and DuckDB all report it with the same codes and message so an app can
+ * detect "storage full" in one place with {@link isStorageFullError}.
+ */
+declare function storageRejectionError(service: string, status: 402 | 413, meta: Record<string, unknown>, responseText: string): ServiceError;
+/**
+ * True when a write failed for storage: the owner's TinyCloud storage is full
+ * (`STORAGE_QUOTA_EXCEEDED`), or this write is larger than what is left
+ * (`STORAGE_LIMIT_REACHED`). Reads keep working in both cases, so apps should
+ * stay usable read-only and point the user at freeing up space or upgrading.
+ */
+declare function isStorageFullError(error: {
+    code?: string;
+} | null | undefined): boolean;
 /**
  * Wrap an unknown error in a ServiceError.
  */
@@ -1701,6 +1749,10 @@ type VaultErrorInput = {
     code: "STORAGE_ERROR";
     cause: Error;
     message?: string;
+} | {
+    code: "STORAGE_QUOTA_EXCEEDED" | "STORAGE_LIMIT_REACHED";
+    message: string;
+    meta?: Record<string, unknown>;
 };
 /**
  * Vault error with service field (compatible with ServiceError).
@@ -2245,4 +2297,4 @@ declare class SecretsService implements ISecretsService {
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, networkError, notFoundError, parseAuthError, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };
+export { type AuthorizationVerdict, BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, authorizationVerdictOf, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, isStorageFullError, networkError, notFoundError, parseAuthError, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };

package/dist/index.d.ts

@@ -1075,6 +1075,24 @@ declare function parseAuthError(responseText: string): {
  * Create a service error for unauthorized action (missing capability).
  */
 declare function authUnauthorizedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/**
+ * Authorization verdict read from an error's structure, never its message:
+ * - `"unauthenticated"`: HTTP 401 — the session is missing or stale.
+ * - `"forbidden"`: HTTP 403, or `AUTH_UNAUTHORIZED` without a status — the
+ *   session is valid but lacks the capability.
+ * - `"other"`: a non-authorization HTTP error status (4xx/5xx).
+ */
+type AuthorizationVerdict = "unauthenticated" | "forbidden" | "other";
+/**
+ * Classify an error from its typed HTTP error status (`status`, `statusCode`,
+ * or `meta.status`, 4xx/5xx only) and `AUTH_UNAUTHORIZED` code, following the
+ * `cause` chain outer-first (at most {@link MAX_CAUSE_DEPTH} links, cycles
+ * stop the walk) so wrappers that rethrow with `cause` keep the verdict. The
+ * outermost error status decides, so an outer 5xx keeps its retry budget even
+ * over an inner 401. Returns `undefined` for untyped errors; only then may
+ * callers fall back to message heuristics.
+ */
+declare function authorizationVerdictOf(error: unknown): AuthorizationVerdict | undefined;
 /**
  * Create a service error for storage quota exceeded (402 Payment Required).
  */
@@ -1083,6 +1101,36 @@ declare function storageQuotaExceededError(service: string, message: string, met
  * Create a service error for storage limit reached (413 Payload Too Large).
  */
 declare function storageLimitReachedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+/** Shown when a write is rejected because the owner's storage is full. */
+declare const STORAGE_FULL_MESSAGE = "TinyCloud storage is full, so this change was not saved. Reading still works. Free up space or upgrade your plan to save again.";
+/** Shown when a write is larger than the storage the owner has left. */
+declare const STORAGE_WRITE_TOO_LARGE_MESSAGE = "This change is larger than the TinyCloud storage you have left, so it was not saved. Reading still works. Free up space or upgrade your plan to save it.";
+/**
+ * Parse the byte counts from a node storage rejection
+ * ("... Used: 155744 bytes, Limit: 0 bytes"). The limit is the share of the
+ * owner's account-wide budget left for this space, so it is 0 when the
+ * owner's other spaces already use the whole budget.
+ */
+declare function parseStorageQuotaBytes(responseText: string): {
+    usedBytes: number;
+    limitBytes: number;
+} | undefined;
+/**
+ * Build the error for a write the node rejected for storage: 402 when storage
+ * is already full, 413 when this write is larger than what is left. KV, SQL
+ * and DuckDB all report it with the same codes and message so an app can
+ * detect "storage full" in one place with {@link isStorageFullError}.
+ */
+declare function storageRejectionError(service: string, status: 402 | 413, meta: Record<string, unknown>, responseText: string): ServiceError;
+/**
+ * True when a write failed for storage: the owner's TinyCloud storage is full
+ * (`STORAGE_QUOTA_EXCEEDED`), or this write is larger than what is left
+ * (`STORAGE_LIMIT_REACHED`). Reads keep working in both cases, so apps should
+ * stay usable read-only and point the user at freeing up space or upgrading.
+ */
+declare function isStorageFullError(error: {
+    code?: string;
+} | null | undefined): boolean;
 /**
  * Wrap an unknown error in a ServiceError.
  */
@@ -1701,6 +1749,10 @@ type VaultErrorInput = {
     code: "STORAGE_ERROR";
     cause: Error;
     message?: string;
+} | {
+    code: "STORAGE_QUOTA_EXCEEDED" | "STORAGE_LIMIT_REACHED";
+    message: string;
+    meta?: Record<string, unknown>;
 };
 /**
  * Vault error with service field (compatible with ServiceError).
@@ -2245,4 +2297,4 @@ declare class SecretsService implements ISecretsService {
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-export { BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, networkError, notFoundError, parseAuthError, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };
+export { type AuthorizationVerdict, BaseService, type BaseServiceOptions, type ColumnInfo, type DataVaultConfig, DataVaultService, DecryptCapabilityProof, DuckDbAction, type DuckDbActionType, type DuckDbBatchOptions, type BatchResponse as DuckDbBatchResponse, DuckDbDatabaseHandle, type DuckDbExecuteOptions, type ExecuteResponse as DuckDbExecuteResponse, type DuckDbOptions, type DuckDbQueryOptions, type QueryResponse as DuckDbQueryResponse, DuckDbService, type DuckDbServiceConfig, type DuckDbStatement, type DuckDbValue, EventHandler, FetchFunction, GenericKVResponseSchema, type GenericKVResponseType, GenericResultSchema, type HookEvent, type HookServiceName, type HookStreamEvent, type HookSubscription, type HookWebhookListOptions, type HookWebhookRecord, type HookWebhookRegistration, type HookWebhookScope, type HookWebhookUnregisterOptions, HooksService, type HooksServiceConfig, type IDataVaultService, type IDuckDbDatabaseHandle, type IDuckDbService, IEncryptionService, type IHooksService, IKVService, type ISecretsService, IService, IServiceContext, InvokeAnyFunction, InvokeFunction, KVListResponseSchema, type KVListResponseType, KVListResultSchema, type KVListResultType, KVResponseHeadersSchema, type KVResponseHeadersType, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretScopeOptions, type SecretsError, SecretsService, type ServiceConstructor, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, type ServiceRegistration, ServiceRequestEventSchema, type ServiceRequestEventType, ServiceResponseEventSchema, type ServiceResponseEventType, ServiceRetryEventSchema, type ServiceRetryEventType, ServiceSession, ServiceSessionSchema, type ServiceSessionType, StorageQuotaInfo, type SubscribeOptions, type TableInfo, TelemetryConfig, TelemetrySpanEventSchema, type TelemetrySpanEventType, type TinyCloudDebugEnableOptions, type TinyCloudDebugEvent, type TinyCloudDebugLevel, TinyCloudDebugLogger, type TinyCloudDebugTimer, TinyCloudQuota, type ValidationError, type VaultCrypto, type VaultEntry, type VaultError, type VaultGetOptions, type VaultGrantOptions, VaultHeaders, type VaultListOptions, type VaultListPage, type VaultNetworkReadResult, VaultPublicSpaceKVActions, type VaultPutOptions, type ViewInfo, type WasmVaultFunctions, abortedError, authExpiredError, authRequiredError, authUnauthorizedError, authorizationVerdictOf, canonicalizeSecretScope, clearTinyCloudDebugLogs, createKVResponseSchema, createResultSchema, createVaultCrypto, disableTinyCloudDebug, enableTinyCloudDebug, errorResult, getTinyCloudDebugLogs, installTinyCloudDebugGlobals, isStorageFullError, networkError, notFoundError, parseAuthError, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, wrapError };