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

package/dist/index.d.cts

@@ -1,9 +1,10 @@
-import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-qwMmB7qB.cjs';
-export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-qwMmB7qB.cjs';
+import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-CVwwxqXF.cjs';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-CVwwxqXF.cjs';
 import { z } from 'zod';
-import { B as BaseService } from './BaseService-BhpVpA9b.cjs';
+import { B as BaseService } from './BaseService-DWbPbov7.cjs';
+export { a as BaseServiceOptions, R as RequestSignal, S as ServiceConstructor, b as ServiceRegistration } from './BaseService-DWbPbov7.cjs';
 import { IKVService } from './kv/index.cjs';
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVChange, KVChangesAuthority, KVChangesOptions, KVChangesResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.cjs';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.cjs';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.cjs';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.cjs';
@@ -1050,8 +1051,11 @@ declare function authExpiredError(service: string): ServiceError;
 declare function networkError(service: string, message: string, cause?: Error): ServiceError;
 /**
  * Create a service error for timeouts.
+ *
+ * @param timeoutMs - The configured timeout that elapsed, when known
+ * @param cause - The underlying timeout error, when known
  */
-declare function timeoutError(service: string): ServiceError;
+declare function timeoutError(service: string, timeoutMs?: number, cause?: Error): ServiceError;
 /**
  * Create a service error for aborted requests.
  */
@@ -1076,56 +1080,87 @@ declare function parseAuthError(responseText: string): {
  */
 declare function authUnauthorizedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
 /**
- * Create a service error for storage quota exceeded (402 Payment Required).
+ * 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).
  */
-declare function storageQuotaExceededError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+type AuthorizationVerdict = "unauthenticated" | "forbidden" | "other";
 /**
- * Create a service error for storage limit reached (413 Payload Too Large).
+ * Parse a canonical TinyCloud resource, keeping nested space names intact.
+ * The first registered service segment is authoritative: a later matching
+ * segment in the path cannot turn a different service into grant advice.
  */
-declare function storageLimitReachedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+declare function parseCapabilityResource(resource: string, service: string): {
+    space: string;
+    path: string;
+} | undefined;
 /**
- * Wrap an unknown error in a ServiceError.
+ * Return a grantable missing capability only when typed authorization evidence
+ * and both safe, service-matched capability fields are present. Status alone,
+ * message text, wildcard actions and unrecognized actions cannot grant scope.
  */
-declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
+declare function validatedCapabilityOf(error: unknown): {
+    resource: string;
+    requiredAction: string;
+} | undefined;
 /**
- * Create an error Result from a ServiceError.
+ * 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 errorResult(error: ServiceError): Result<never, ServiceError>;
-
+declare function authorizationVerdictOf(error: unknown): AuthorizationVerdict | undefined;
 /**
- * Base Service Types
- *
- * Types specific to the base service infrastructure.
+ * Create a service error for storage quota exceeded (402 Payment Required).
  */
-
+declare function storageQuotaExceededError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
 /**
- * Service constructor type for registration.
- * Used by the SDK to instantiate services.
+ * Create a service error for storage limit reached (413 Payload Too Large).
  */
-interface ServiceConstructor<TConfig = Record<string, unknown>, TService extends IService = IService> {
-    /** Service identifier used for registration */
-    readonly serviceName: string;
-    /** Create a new instance of the service */
-    new (config?: TConfig): TService;
-}
+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;
 /**
- * Service registration entry.
+ * 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}.
  */
-interface ServiceRegistration {
-    /** The service class constructor */
-    constructor: ServiceConstructor;
-    /** Configuration for this service instance */
-    config?: Record<string, unknown>;
-}
+declare function storageRejectionError(service: string, status: 402 | 413, meta: Record<string, unknown>, responseText: string): ServiceError;
 /**
- * Options for base service operations.
+ * 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.
  */
-interface BaseServiceOptions {
-    /** Override the default timeout for this operation */
-    timeout?: number;
-    /** Custom abort signal for this operation */
-    signal?: AbortSignal;
-}
+declare function isStorageFullError(error: {
+    code?: string;
+} | null | undefined): boolean;
+/**
+ * Wrap an unknown error in a ServiceError.
+ */
+declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
+/**
+ * Create an error Result from a ServiceError.
+ */
+declare function errorResult(error: ServiceError): Result<never, ServiceError>;
 
 /**
  * DuckDB Service Types
@@ -1142,7 +1177,10 @@ interface DuckDbServiceConfig {
      */
     defaultDatabase?: string;
     /**
-     * Default timeout in milliseconds for DuckDB operations.
+     * Timeout in milliseconds for each DuckDB request, including reading the
+     * response body. When it elapses the request is aborted and the operation
+     * returns an `ErrorCodes.TIMEOUT` error. Unset (the default), `0`, or
+     * `Infinity` means no timeout.
      */
     timeout?: number;
     /** Allow additional config properties */
@@ -1701,6 +1739,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 +2287,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 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, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, 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, parseCapabilityResource, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, validatedCapabilityOf, wrapError };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-qwMmB7qB.js';
-export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-qwMmB7qB.js';
+import { a as IServiceContext, c as InvokeFunction, d as InvokeAnyFunction, F as FetchFunction, S as ServiceSession, e as RetryPolicy, T as TelemetryConfig, I as IService, E as EventHandler, b as ServiceError, R as Result, P as PermissionHint, f as StorageQuotaInfo } from './types-CVwwxqXF.js';
+export { g as ErrorCode, h as ErrorCodes, i as FetchRequestInit, j as FetchResponse, k as InvocationFact, l as InvocationFacts, m as InvokeAnyEntry, n as ServiceErrorEvent, o as ServiceHeaders, p as ServiceRequestEvent, q as ServiceResponseEvent, r as ServiceRetryEvent, s as TelemetryEventHandler, t as TelemetryEvents, u as TelemetrySpanEvent, v as defaultRetryPolicy, w as err, x as ok, y as serviceError } from './types-CVwwxqXF.js';
 import { z } from 'zod';
-import { B as BaseService } from './BaseService-CuV-ZVPs.js';
+import { B as BaseService } from './BaseService-B_UKhVht.js';
+export { a as BaseServiceOptions, R as RequestSignal, S as ServiceConstructor, b as ServiceRegistration } from './BaseService-B_UKhVht.js';
 import { IKVService } from './kv/index.js';
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, IPrefixedKVService, KVAction, KVActionType, KVBatchPutItem, KVBatchPutOptions, KVBatchPutResponse, KVBatchReadResponse, KVChange, KVChangesAuthority, KVChangesOptions, KVChangesResponse, KVCreateSignedReadUrlOptions, KVDeleteOptions, KVGetOptions, KVHeadOptions, KVListOptions, KVListResponse, KVPutOptions, KVResponse, KVResponseHeaders, KVService, KVServiceConfig, KVSignedReadUrlResponse, PrefixedKVService } from './kv/index.js';
 export { BatchOptions, BatchResponse, DatabaseHandle, ExecuteOptions, ExecuteResponse, IDatabaseHandle, ISQLMigrations, ISQLService, QueryOptions, QueryResponse, SQLAction, SQLActionType, SQLMigrations, SQLService, SQLServiceConfig, SqlMigration, SqlMigrationApplyOptions, SqlMigrationApplyResponse, SqlStatement, SqlValue } from './sql/index.js';
 import { IEncryptionService, DecryptCapabilityProof } from './encryption/index.js';
 export { BuildCanonicalDecryptRequestInput, BuildDecryptFactsInput, BuildDecryptInvocationInput, BuiltDecryptInvocation, CanonicalDecryptRequest, CanonicalJson, DECRYPT_ACTION, DECRYPT_FACT_TYPE, DECRYPT_RESULT_TYPE, DEFAULT_ENCRYPTION_ALG, DEFAULT_KEY_VERSION, DecryptEnvelopeOptions, DecryptInvocationFact, DecryptInvocationSigner, DecryptRequestBody, DecryptResponseBody, DecryptTransport, DiscoverNetworkInput, DiscoveredNetwork, DiscoverySource, ENCRYPTION_NETWORK_URN_PREFIX, ENCRYPTION_SERVICE, ENCRYPTION_SERVICE_SHORT, ENVELOPE_VERSION, EncryptToNetworkInput, EncryptToNetworkOptions, EncryptToNetworkResult, EncryptionCrypto, EncryptionError, EncryptionErrorInput, EncryptionService, EncryptionServiceConfig, InlineEncryptedEnvelope, Json, NETWORK_NAME_PATTERN, NetworkDescriptor, NetworkIdError, NodeDescriptorFetcher, ParsedNetworkId, RandomReceiverKeyInput, ReceiverKeyPair, ReceiverKeySigner, SignedReceiverKeyInput, VerifyDecryptResponseInput, WellKnownDescriptorFetcher, base64Decode, base64Encode, buildCanonicalDecryptRequest, buildDecryptAttenuation, buildDecryptFacts, buildDecryptInvocation, buildNetworkId, canonicalHashHex, canonicalSignedResponse, canonicalize as canonicalizeEncryptionJson, checkDecryptInvocationInput, decryptEnvelopeWithKey, deriveSignedReceiverKey, discoverNetwork, encryptToNetwork, encryptionError, ensureNetworkUsableForDecrypt, generateRandomReceiverKey, hexDecode, hexEncode, isNetworkId, networkDiscoveryKey, openWrappedKey, parseNetworkId, utf8Decode, utf8Encode, validateEnvelope, verifyDecryptResponse } from './encryption/index.js';
@@ -1050,8 +1051,11 @@ declare function authExpiredError(service: string): ServiceError;
 declare function networkError(service: string, message: string, cause?: Error): ServiceError;
 /**
  * Create a service error for timeouts.
+ *
+ * @param timeoutMs - The configured timeout that elapsed, when known
+ * @param cause - The underlying timeout error, when known
  */
-declare function timeoutError(service: string): ServiceError;
+declare function timeoutError(service: string, timeoutMs?: number, cause?: Error): ServiceError;
 /**
  * Create a service error for aborted requests.
  */
@@ -1076,56 +1080,87 @@ declare function parseAuthError(responseText: string): {
  */
 declare function authUnauthorizedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
 /**
- * Create a service error for storage quota exceeded (402 Payment Required).
+ * 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).
  */
-declare function storageQuotaExceededError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+type AuthorizationVerdict = "unauthenticated" | "forbidden" | "other";
 /**
- * Create a service error for storage limit reached (413 Payload Too Large).
+ * Parse a canonical TinyCloud resource, keeping nested space names intact.
+ * The first registered service segment is authoritative: a later matching
+ * segment in the path cannot turn a different service into grant advice.
  */
-declare function storageLimitReachedError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
+declare function parseCapabilityResource(resource: string, service: string): {
+    space: string;
+    path: string;
+} | undefined;
 /**
- * Wrap an unknown error in a ServiceError.
+ * Return a grantable missing capability only when typed authorization evidence
+ * and both safe, service-matched capability fields are present. Status alone,
+ * message text, wildcard actions and unrecognized actions cannot grant scope.
  */
-declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
+declare function validatedCapabilityOf(error: unknown): {
+    resource: string;
+    requiredAction: string;
+} | undefined;
 /**
- * Create an error Result from a ServiceError.
+ * 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 errorResult(error: ServiceError): Result<never, ServiceError>;
-
+declare function authorizationVerdictOf(error: unknown): AuthorizationVerdict | undefined;
 /**
- * Base Service Types
- *
- * Types specific to the base service infrastructure.
+ * Create a service error for storage quota exceeded (402 Payment Required).
  */
-
+declare function storageQuotaExceededError(service: string, message: string, meta?: Record<string, unknown>): ServiceError;
 /**
- * Service constructor type for registration.
- * Used by the SDK to instantiate services.
+ * Create a service error for storage limit reached (413 Payload Too Large).
  */
-interface ServiceConstructor<TConfig = Record<string, unknown>, TService extends IService = IService> {
-    /** Service identifier used for registration */
-    readonly serviceName: string;
-    /** Create a new instance of the service */
-    new (config?: TConfig): TService;
-}
+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;
 /**
- * Service registration entry.
+ * 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}.
  */
-interface ServiceRegistration {
-    /** The service class constructor */
-    constructor: ServiceConstructor;
-    /** Configuration for this service instance */
-    config?: Record<string, unknown>;
-}
+declare function storageRejectionError(service: string, status: 402 | 413, meta: Record<string, unknown>, responseText: string): ServiceError;
 /**
- * Options for base service operations.
+ * 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.
  */
-interface BaseServiceOptions {
-    /** Override the default timeout for this operation */
-    timeout?: number;
-    /** Custom abort signal for this operation */
-    signal?: AbortSignal;
-}
+declare function isStorageFullError(error: {
+    code?: string;
+} | null | undefined): boolean;
+/**
+ * Wrap an unknown error in a ServiceError.
+ */
+declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
+/**
+ * Create an error Result from a ServiceError.
+ */
+declare function errorResult(error: ServiceError): Result<never, ServiceError>;
 
 /**
  * DuckDB Service Types
@@ -1142,7 +1177,10 @@ interface DuckDbServiceConfig {
      */
     defaultDatabase?: string;
     /**
-     * Default timeout in milliseconds for DuckDB operations.
+     * Timeout in milliseconds for each DuckDB request, including reading the
+     * response body. When it elapses the request is aborted and the operation
+     * returns an `ErrorCodes.TIMEOUT` error. Unset (the default), `0`, or
+     * `Infinity` means no timeout.
      */
     timeout?: number;
     /** Allow additional config properties */
@@ -1701,6 +1739,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 +2287,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 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, ServiceContext, type ServiceContextConfig, ServiceError, ServiceErrorEventSchema, type ServiceErrorEventType, ServiceErrorSchema, type ServiceErrorType, 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, parseCapabilityResource, parsePermissionHint, parsePermissionHintFromErrorText, parseSecretCatalogKey, parseStorageQuotaBytes, permissionDeniedError, resolveSecretListPrefix, resolveSecretPath, storageLimitReachedError, storageQuotaExceededError, storageRejectionError, timeoutError, tinyCloudDebugLogger, validateKVListResponse, validateKVResponseHeaders, validateRetryPolicy, validateServiceError, validateServiceRequestEvent, validateServiceResponseEvent, validateServiceSession, validateTelemetrySpanEvent, validatedCapabilityOf, wrapError };