@tinycloud/sdk-services 3.1.0-beta.1 → 3.1.0-beta.11

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.
  */
@@ -1083,6 +1087,24 @@ declare function authUnauthorizedError(service: string, message: string, meta?:
  * - `"other"`: a non-authorization HTTP error status (4xx/5xx).
  */
 type AuthorizationVerdict = "unauthenticated" | "forbidden" | "other";
+/**
+ * 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 parseCapabilityResource(resource: string, service: string): {
+    space: string;
+    path: string;
+} | undefined;
+/**
+ * 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 validatedCapabilityOf(error: unknown): {
+    resource: string;
+    requiredAction: string;
+} | undefined;
 /**
  * Classify an error from its typed HTTP error status (`status`, `statusCode`,
  * or `meta.status`, 4xx/5xx only) and `AUTH_UNAUTHORIZED` code, following the
@@ -1101,49 +1123,44 @@ 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;
 /**
- * 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>;
-
-/**
- * Base Service Types
- *
- * Types specific to the base service infrastructure.
+ * 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;
 /**
- * Service constructor type for registration.
- * Used by the SDK to instantiate services.
+ * 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 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 isStorageFullError(error: {
+    code?: string;
+} | null | undefined): boolean;
 /**
- * Service registration entry.
+ * Wrap an unknown error in a ServiceError.
  */
-interface ServiceRegistration {
-    /** The service class constructor */
-    constructor: ServiceConstructor;
-    /** Configuration for this service instance */
-    config?: Record<string, unknown>;
-}
+declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
 /**
- * Options for base service operations.
+ * Create an error Result from a ServiceError.
  */
-interface BaseServiceOptions {
-    /** Override the default timeout for this operation */
-    timeout?: number;
-    /** Custom abort signal for this operation */
-    signal?: AbortSignal;
-}
+declare function errorResult(error: ServiceError): Result<never, ServiceError>;
 
 /**
  * DuckDB Service Types
@@ -1160,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 */
@@ -1719,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).
@@ -2263,4 +2287,4 @@ declare class SecretsService implements ISecretsService {
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-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, 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, 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.
  */
@@ -1083,6 +1087,24 @@ declare function authUnauthorizedError(service: string, message: string, meta?:
  * - `"other"`: a non-authorization HTTP error status (4xx/5xx).
  */
 type AuthorizationVerdict = "unauthenticated" | "forbidden" | "other";
+/**
+ * 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 parseCapabilityResource(resource: string, service: string): {
+    space: string;
+    path: string;
+} | undefined;
+/**
+ * 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 validatedCapabilityOf(error: unknown): {
+    resource: string;
+    requiredAction: string;
+} | undefined;
 /**
  * Classify an error from its typed HTTP error status (`status`, `statusCode`,
  * or `meta.status`, 4xx/5xx only) and `AUTH_UNAUTHORIZED` code, following the
@@ -1101,49 +1123,44 @@ 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;
 /**
- * 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>;
-
-/**
- * Base Service Types
- *
- * Types specific to the base service infrastructure.
+ * 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;
 /**
- * Service constructor type for registration.
- * Used by the SDK to instantiate services.
+ * 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 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 isStorageFullError(error: {
+    code?: string;
+} | null | undefined): boolean;
 /**
- * Service registration entry.
+ * Wrap an unknown error in a ServiceError.
  */
-interface ServiceRegistration {
-    /** The service class constructor */
-    constructor: ServiceConstructor;
-    /** Configuration for this service instance */
-    config?: Record<string, unknown>;
-}
+declare function wrapError(service: string, error: unknown, defaultCode?: string): ServiceError;
 /**
- * Options for base service operations.
+ * Create an error Result from a ServiceError.
  */
-interface BaseServiceOptions {
-    /** Override the default timeout for this operation */
-    timeout?: number;
-    /** Custom abort signal for this operation */
-    signal?: AbortSignal;
-}
+declare function errorResult(error: ServiceError): Result<never, ServiceError>;
 
 /**
  * DuckDB Service Types
@@ -1160,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 */
@@ -1719,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).
@@ -2263,4 +2287,4 @@ declare class SecretsService implements ISecretsService {
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-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, 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, 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 };