@tinycloud/sdk-services 3.1.0-beta.9 → 3.2.0-beta.2

package/dist/index.d.cts

@@ -1521,9 +1521,51 @@ interface SubscribeOptions {
 }
 interface HooksServiceConfig extends Record<string, unknown> {
     host?: string;
+    /** Shared-stream retry tuning; see {@link HookStreamRetryConfig}. */
+    streamRetry?: HookStreamRetryConfig;
+}
+/**
+ * Retry policy for the shared `/hooks/events` stream. When the stream fails
+ * (network error, 5xx, or an expired/rotated ticket rejected with 401/403)
+ * it is re-opened with exponential backoff: `HOOK_STREAM_RETRY_BASE_DELAY_MS`
+ * (~250 ms) doubling to `HOOK_STREAM_RETRY_MAX_DELAY_MS` (~30 s) with jitter.
+ * The retry streak resets after an event is received or a stream remains open
+ * for at least 5 seconds. Retries stop when no subscribers remain, when the
+ * service is aborted, or when minting the hook ticket is refused (the iterator
+ * throws that typed error instead).
+ */
+interface HookStreamRetryConfig {
+    /**
+     * Delay before retry attempt `attempt` (1-based). Defaults to the jittered
+     * exponential backoff described above. Must return milliseconds.
+     */
+    delay?: (attempt: number) => number;
+    /**
+     * How a retry delay is awaited — the injectable clock. `delayMs` is the
+     * resolved delay for `attempt`; `signal` aborts the wait early when the
+     * subscription set changes or the service stops. Rejecting or throwing is
+     * treated like a completed wait. After a custom wait returns — whether it
+     * fulfilled, rejected or threw — the service still yields one event-loop
+     * turn so a persistently failing stream can never starve the process.
+     * Defaults to an abortable, unref'd `setTimeout`.
+     */
+    wait?: (delayMs: number, attempt: number, signal: AbortSignal) => Promise<void>;
 }
 
 interface IHooksService {
+    /**
+     * Stream hook events until `options.signal` aborts, the SDK signs out or
+     * the session ends, or the consumer stops iterating. Transient stream
+     * failures — network errors, 5xx, and an expired or rotated ticket rejected
+     * by `/hooks/events` (401/403) — are retried internally with backoff and
+     * never reach the iterator.
+     *
+     * The iterator throws when minting the hook ticket is refused. The thrown
+     * plain `ServiceError` carries `meta.status` with the refusing HTTP status,
+     * so `for await` consumers can branch on it. Stream diagnostics contain only
+     * SDK allow-listed identifiers; foreign error messages and causes are not
+     * copied.
+     */
     subscribe(subscriptions: HookSubscription[], options?: SubscribeOptions): AsyncIterable<HookEvent>;
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
@@ -1534,10 +1576,13 @@ declare class HooksService extends BaseService implements IHooksService {
     static readonly serviceName = "hooks";
     protected _config: HooksServiceConfig;
     private readonly _subscribers;
-    private _sharedStreamTask?;
-    private _sharedStreamAbort?;
-    private _refreshChain;
-    private _activeSignature;
+    /** True while the one supervisor loop runs. Set only by wake(), cleared only at loop exit. */
+    private _supervising;
+    /** The supervisor's current step, interruptible by wake(). */
+    private _phase?;
+    /** Bumped on every session change; part of the plan key. */
+    private _sessionGeneration;
+    private _lastContextSignal?;
     constructor(config?: HooksServiceConfig);
     get config(): HooksServiceConfig;
     private get host();
@@ -1545,14 +1590,60 @@ declare class HooksService extends BaseService implements IHooksService {
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
     unregister(id: string, options?: HookWebhookUnregisterOptions): Promise<Result<void>>;
-    private scheduleSharedStreamRefresh;
-    private refreshSharedStream;
-    private collectSharedStreamState;
-    private runSharedStream;
-    private abortSharedStream;
+    /**
+     * Called after anything that may change what the supervisor should do:
+     * subscribe, unsubscribe, session change, sign-out. Interrupts the running
+     * step if the plan moved away from it, and starts the supervisor if none
+     * runs. Touches only SDK-owned state, so it never throws into callers such
+     * as `ServiceContext.setSession`.
+     */
+    private wake;
+    /**
+     * The only owner of the shared stream. Each iteration is one attempt
+     * (mint → open → drain), then a classification and, unless the attempt was
+     * superseded or released its subscribers, a backoff. Every await is a
+     * `phase` that wake() can interrupt; an interrupted phase yields
+     * `undefined`, so a superseded mint can never act. Outside `attempt` and
+     * `pause`, which each own one catch, the loop touches only SDK state.
+     */
+    private supervise;
+    /**
+     * Run one step under an interrupt that wake() fires when the plan key moves
+     * on. An interrupted step's result is discarded. The interrupt is also
+     * fired when the step returns, which releases whatever it left open: the
+     * request signal and its listeners, an unread response body, a timer.
+     */
+    private phase;
+    /**
+     * One mint → open → drain. The single catch site for everything the
+     * attempt touches that the SDK does not own: context accessors, invoke,
+     * fetch, response bodies, the SSE parser. Never rejects.
+     */
+    private attempt;
+    /**
+     * Back off before the next attempt. `config.streamRetry` overrides the
+     * delay and the clock; whatever they do, the pause ends by the delay or the
+     * interrupt, then yields one timer turn so an instant clock cannot starve
+     * due timers or the process.
+     */
+    private pause;
+    /** The stream the current subscribers need, or undefined when none remain. */
+    private plan;
+    private dispatch;
+    /**
+     * Detach every subscriber. With `error`, their iterators throw it after
+     * draining buffered events; without, they complete.
+     */
+    private release;
+    private report;
+    /**
+     * Unreachable by construction. If the loop ever rejects anyway, fail its
+     * subscribers visibly instead of stranding them or crashing the process.
+     */
+    private collapse;
+    onSessionChange(session: ServiceSession | null): void;
+    onSignOut(): void;
     private createHookHeaders;
-    private mintHookTicket;
-    private openHookStream;
     private createInvokeHeaders;
 }
 
@@ -1617,6 +1708,11 @@ interface VaultPutOptions {
     contentType?: string;
     /** Custom serializer (default: JSON.stringify for objects) */
     serialize?: (value: unknown) => Uint8Array;
+    /**
+     * `"*"` writes only when no value exists at the key. An existing value
+     * fails with `ALREADY_EXISTS`; it is never overwritten.
+     */
+    ifNoneMatch?: "*";
 }
 /**
  * Options for vault get operations.
@@ -1739,6 +1835,28 @@ type VaultErrorInput = {
     code: "STORAGE_ERROR";
     cause: Error;
     message?: string;
+    meta?: Record<string, unknown>;
+} | {
+    code: "ALREADY_EXISTS";
+    key: string;
+    message?: string;
+    meta?: Record<string, unknown>;
+    /** The typed KV error that refused the write (an `Error` carrying its `code`, `service` and `meta`). */
+    cause: ServiceError & Error;
+} | {
+    /** HTTP 401 only: the session must sign in again. */
+    code: "AUTH_UNAUTHORIZED";
+    message: string;
+    meta?: Record<string, unknown>;
+    /** The typed KV error that refused the write (an `Error` carrying its `code`, `service` and `meta`). */
+    cause: ServiceError & Error;
+} | {
+    /** A 403, or an authorization refusal without a status: signing in again does not help. */
+    code: "PERMISSION_DENIED";
+    message: string;
+    meta?: Record<string, unknown>;
+    /** The typed KV error that refused the write (an `Error` carrying its `code`, `service` and `meta`). */
+    cause: ServiceError & Error;
 } | {
     code: "STORAGE_QUOTA_EXCEEDED" | "STORAGE_LIMIT_REACHED";
     message: string;
@@ -2226,6 +2344,21 @@ interface SecretScopeOptions {
     /** Optional logical scope. Omit for the global secret namespace. */
     scope?: string;
 }
+/** Canonical secret scope grammar shared with the TC-832 `/request` link. */
+declare const SECRET_SCOPE_RE: RegExp;
+/** Longest scope the TC-832 `/request` link accepts. */
+declare const MAX_SECRET_SCOPE_LENGTH = 64;
+/** Scopes the TC-832 `/request` link refuses. */
+declare const TC832_RESERVED_SCOPES: readonly string[];
+interface SecretPutOptions extends SecretScopeOptions {
+    /** Write only when no secret exists under this name; never overwrite. */
+    ifAbsent?: boolean;
+}
+/**
+ * Derive the canonical secret scope for an app id such as
+ * `xyz.tinycloud.feed-workflows` → `xyz-tinycloud-feed-workflows`.
+ */
+declare function appSecretScope(appId: string): string;
 interface ResolvedSecretPath {
     /** Canonical env-style secret name. */
     name: string;
@@ -2266,7 +2399,7 @@ interface ISecretsService {
     lock(): void;
     readonly isUnlocked: boolean;
     get(name: string, options?: SecretScopeOptions): Promise<Result<string, SecretsError>>;
-    put(name: string, value: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
+    put(name: string, value: string, options?: SecretPutOptions): Promise<Result<void, SecretsError>>;
     delete(name: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
     /** List global and scoped secrets without decrypting their values. */
@@ -2281,10 +2414,10 @@ declare class SecretsService implements ISecretsService {
     unlock(signer?: unknown): Promise<Result<void, VaultError>>;
     lock(): void;
     get(name: string, options?: SecretScopeOptions): Promise<Result<string, SecretsError>>;
-    put(name: string, value: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
+    put(name: string, value: string, options?: SecretPutOptions): Promise<Result<void, SecretsError>>;
     delete(name: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-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 };
+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 HookStreamRetryConfig, 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, MAX_SECRET_SCOPE_LENGTH, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, SECRET_SCOPE_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretPutOptions, 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, TC832_RESERVED_SCOPES, 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, appSecretScope, 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

@@ -1521,9 +1521,51 @@ interface SubscribeOptions {
 }
 interface HooksServiceConfig extends Record<string, unknown> {
     host?: string;
+    /** Shared-stream retry tuning; see {@link HookStreamRetryConfig}. */
+    streamRetry?: HookStreamRetryConfig;
+}
+/**
+ * Retry policy for the shared `/hooks/events` stream. When the stream fails
+ * (network error, 5xx, or an expired/rotated ticket rejected with 401/403)
+ * it is re-opened with exponential backoff: `HOOK_STREAM_RETRY_BASE_DELAY_MS`
+ * (~250 ms) doubling to `HOOK_STREAM_RETRY_MAX_DELAY_MS` (~30 s) with jitter.
+ * The retry streak resets after an event is received or a stream remains open
+ * for at least 5 seconds. Retries stop when no subscribers remain, when the
+ * service is aborted, or when minting the hook ticket is refused (the iterator
+ * throws that typed error instead).
+ */
+interface HookStreamRetryConfig {
+    /**
+     * Delay before retry attempt `attempt` (1-based). Defaults to the jittered
+     * exponential backoff described above. Must return milliseconds.
+     */
+    delay?: (attempt: number) => number;
+    /**
+     * How a retry delay is awaited — the injectable clock. `delayMs` is the
+     * resolved delay for `attempt`; `signal` aborts the wait early when the
+     * subscription set changes or the service stops. Rejecting or throwing is
+     * treated like a completed wait. After a custom wait returns — whether it
+     * fulfilled, rejected or threw — the service still yields one event-loop
+     * turn so a persistently failing stream can never starve the process.
+     * Defaults to an abortable, unref'd `setTimeout`.
+     */
+    wait?: (delayMs: number, attempt: number, signal: AbortSignal) => Promise<void>;
 }
 
 interface IHooksService {
+    /**
+     * Stream hook events until `options.signal` aborts, the SDK signs out or
+     * the session ends, or the consumer stops iterating. Transient stream
+     * failures — network errors, 5xx, and an expired or rotated ticket rejected
+     * by `/hooks/events` (401/403) — are retried internally with backoff and
+     * never reach the iterator.
+     *
+     * The iterator throws when minting the hook ticket is refused. The thrown
+     * plain `ServiceError` carries `meta.status` with the refusing HTTP status,
+     * so `for await` consumers can branch on it. Stream diagnostics contain only
+     * SDK allow-listed identifiers; foreign error messages and causes are not
+     * copied.
+     */
     subscribe(subscriptions: HookSubscription[], options?: SubscribeOptions): AsyncIterable<HookEvent>;
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
@@ -1534,10 +1576,13 @@ declare class HooksService extends BaseService implements IHooksService {
     static readonly serviceName = "hooks";
     protected _config: HooksServiceConfig;
     private readonly _subscribers;
-    private _sharedStreamTask?;
-    private _sharedStreamAbort?;
-    private _refreshChain;
-    private _activeSignature;
+    /** True while the one supervisor loop runs. Set only by wake(), cleared only at loop exit. */
+    private _supervising;
+    /** The supervisor's current step, interruptible by wake(). */
+    private _phase?;
+    /** Bumped on every session change; part of the plan key. */
+    private _sessionGeneration;
+    private _lastContextSignal?;
     constructor(config?: HooksServiceConfig);
     get config(): HooksServiceConfig;
     private get host();
@@ -1545,14 +1590,60 @@ declare class HooksService extends BaseService implements IHooksService {
     register(webhook: HookWebhookRegistration): Promise<Result<HookWebhookRecord>>;
     list(options?: HookWebhookListOptions): Promise<Result<HookWebhookRecord[]>>;
     unregister(id: string, options?: HookWebhookUnregisterOptions): Promise<Result<void>>;
-    private scheduleSharedStreamRefresh;
-    private refreshSharedStream;
-    private collectSharedStreamState;
-    private runSharedStream;
-    private abortSharedStream;
+    /**
+     * Called after anything that may change what the supervisor should do:
+     * subscribe, unsubscribe, session change, sign-out. Interrupts the running
+     * step if the plan moved away from it, and starts the supervisor if none
+     * runs. Touches only SDK-owned state, so it never throws into callers such
+     * as `ServiceContext.setSession`.
+     */
+    private wake;
+    /**
+     * The only owner of the shared stream. Each iteration is one attempt
+     * (mint → open → drain), then a classification and, unless the attempt was
+     * superseded or released its subscribers, a backoff. Every await is a
+     * `phase` that wake() can interrupt; an interrupted phase yields
+     * `undefined`, so a superseded mint can never act. Outside `attempt` and
+     * `pause`, which each own one catch, the loop touches only SDK state.
+     */
+    private supervise;
+    /**
+     * Run one step under an interrupt that wake() fires when the plan key moves
+     * on. An interrupted step's result is discarded. The interrupt is also
+     * fired when the step returns, which releases whatever it left open: the
+     * request signal and its listeners, an unread response body, a timer.
+     */
+    private phase;
+    /**
+     * One mint → open → drain. The single catch site for everything the
+     * attempt touches that the SDK does not own: context accessors, invoke,
+     * fetch, response bodies, the SSE parser. Never rejects.
+     */
+    private attempt;
+    /**
+     * Back off before the next attempt. `config.streamRetry` overrides the
+     * delay and the clock; whatever they do, the pause ends by the delay or the
+     * interrupt, then yields one timer turn so an instant clock cannot starve
+     * due timers or the process.
+     */
+    private pause;
+    /** The stream the current subscribers need, or undefined when none remain. */
+    private plan;
+    private dispatch;
+    /**
+     * Detach every subscriber. With `error`, their iterators throw it after
+     * draining buffered events; without, they complete.
+     */
+    private release;
+    private report;
+    /**
+     * Unreachable by construction. If the loop ever rejects anyway, fail its
+     * subscribers visibly instead of stranding them or crashing the process.
+     */
+    private collapse;
+    onSessionChange(session: ServiceSession | null): void;
+    onSignOut(): void;
     private createHookHeaders;
-    private mintHookTicket;
-    private openHookStream;
     private createInvokeHeaders;
 }
 
@@ -1617,6 +1708,11 @@ interface VaultPutOptions {
     contentType?: string;
     /** Custom serializer (default: JSON.stringify for objects) */
     serialize?: (value: unknown) => Uint8Array;
+    /**
+     * `"*"` writes only when no value exists at the key. An existing value
+     * fails with `ALREADY_EXISTS`; it is never overwritten.
+     */
+    ifNoneMatch?: "*";
 }
 /**
  * Options for vault get operations.
@@ -1739,6 +1835,28 @@ type VaultErrorInput = {
     code: "STORAGE_ERROR";
     cause: Error;
     message?: string;
+    meta?: Record<string, unknown>;
+} | {
+    code: "ALREADY_EXISTS";
+    key: string;
+    message?: string;
+    meta?: Record<string, unknown>;
+    /** The typed KV error that refused the write (an `Error` carrying its `code`, `service` and `meta`). */
+    cause: ServiceError & Error;
+} | {
+    /** HTTP 401 only: the session must sign in again. */
+    code: "AUTH_UNAUTHORIZED";
+    message: string;
+    meta?: Record<string, unknown>;
+    /** The typed KV error that refused the write (an `Error` carrying its `code`, `service` and `meta`). */
+    cause: ServiceError & Error;
+} | {
+    /** A 403, or an authorization refusal without a status: signing in again does not help. */
+    code: "PERMISSION_DENIED";
+    message: string;
+    meta?: Record<string, unknown>;
+    /** The typed KV error that refused the write (an `Error` carrying its `code`, `service` and `meta`). */
+    cause: ServiceError & Error;
 } | {
     code: "STORAGE_QUOTA_EXCEEDED" | "STORAGE_LIMIT_REACHED";
     message: string;
@@ -2226,6 +2344,21 @@ interface SecretScopeOptions {
     /** Optional logical scope. Omit for the global secret namespace. */
     scope?: string;
 }
+/** Canonical secret scope grammar shared with the TC-832 `/request` link. */
+declare const SECRET_SCOPE_RE: RegExp;
+/** Longest scope the TC-832 `/request` link accepts. */
+declare const MAX_SECRET_SCOPE_LENGTH = 64;
+/** Scopes the TC-832 `/request` link refuses. */
+declare const TC832_RESERVED_SCOPES: readonly string[];
+interface SecretPutOptions extends SecretScopeOptions {
+    /** Write only when no secret exists under this name; never overwrite. */
+    ifAbsent?: boolean;
+}
+/**
+ * Derive the canonical secret scope for an app id such as
+ * `xyz.tinycloud.feed-workflows` → `xyz-tinycloud-feed-workflows`.
+ */
+declare function appSecretScope(appId: string): string;
 interface ResolvedSecretPath {
     /** Canonical env-style secret name. */
     name: string;
@@ -2266,7 +2399,7 @@ interface ISecretsService {
     lock(): void;
     readonly isUnlocked: boolean;
     get(name: string, options?: SecretScopeOptions): Promise<Result<string, SecretsError>>;
-    put(name: string, value: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
+    put(name: string, value: string, options?: SecretPutOptions): Promise<Result<void, SecretsError>>;
     delete(name: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
     /** List global and scoped secrets without decrypting their values. */
@@ -2281,10 +2414,10 @@ declare class SecretsService implements ISecretsService {
     unlock(signer?: unknown): Promise<Result<void, VaultError>>;
     lock(): void;
     get(name: string, options?: SecretScopeOptions): Promise<Result<string, SecretsError>>;
-    put(name: string, value: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
+    put(name: string, value: string, options?: SecretPutOptions): Promise<Result<void, SecretsError>>;
     delete(name: string, options?: SecretScopeOptions): Promise<Result<void, SecretsError>>;
     list(options?: SecretScopeOptions): Promise<Result<string[], SecretsError>>;
     listAll(): Promise<Result<SecretCatalogEntry[], SecretsError>>;
 }
 
-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 };
+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 HookStreamRetryConfig, 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, MAX_SECRET_SCOPE_LENGTH, type ParsedSecretCatalogKey, PermissionHint, type QuotaConfig, type QuotaStatus, type ResolvedSecretPath, Result, RetryPolicy, RetryPolicySchema, type RetryPolicyType, SECRET_NAME_RE, SECRET_SCOPE_RE, STORAGE_FULL_MESSAGE, STORAGE_WRITE_TOO_LARGE_MESSAGE, type SchemaInfo, type SecretCatalogEntry, type SecretPayload, type SecretPutOptions, 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, TC832_RESERVED_SCOPES, 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, appSecretScope, 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 };