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

package/dist/kv/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BaseService } from '../BaseService-BhpVpA9b.cjs';
-import { R as Result, I as IService } from '../types-qwMmB7qB.cjs';
+import { B as BaseService } from '../BaseService-DWbPbov7.cjs';
+import { R as Result, I as IService } from '../types-CVwwxqXF.cjs';
 
 /**
  * KV Service Types
@@ -23,8 +23,11 @@ interface KVServiceConfig {
      */
     prefix?: string;
     /**
-     * Default timeout in milliseconds for KV operations.
-     * Overrides the context-level timeout if set.
+     * Default timeout in milliseconds for each KV request, including reading
+     * the response body. When it elapses the request is aborted and the
+     * operation returns an `ErrorCodes.TIMEOUT` error. A per-call `timeout`
+     * option overrides it. Unset (the default), `0`, or `Infinity` means no
+     * timeout.
      */
     timeout?: number;
     /** Allow additional config properties */
@@ -55,7 +58,8 @@ interface KVGetOptions {
      */
     maxResponseBytes?: number;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -85,7 +89,8 @@ interface KVPutOptions {
     /** Only write when the key does not exist. */
     ifNoneMatch?: "*";
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -123,7 +128,8 @@ interface KVBatchPutOptions {
      */
     prefix?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -182,7 +188,8 @@ interface KVListOptions {
     /** Opaque scope-bound cursor returned by a previous bounded list. */
     cursor?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -201,7 +208,8 @@ interface KVDeleteOptions {
     /** Only delete when the current object has this strong ETag. */
     ifMatch?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -218,7 +226,8 @@ interface KVHeadOptions {
      */
     prefix?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -259,7 +268,8 @@ interface KVCreateSignedReadUrlOptions {
      */
     etag?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -323,6 +333,102 @@ interface KVListResponse {
     /** Opaque cursor for the next page, when the node returned one. */
     nextCursor?: string;
 }
+/**
+ * Options for {@link IKVService.changes}, the `tinycloud.kv/sync` change feed.
+ */
+interface KVChangesOptions {
+    /**
+     * The space-relative KV prefix to follow, sent as the invocation path. It
+     * is not joined with the service's configured prefix, and must be non-empty.
+     * Prefixes match whole path segments: `notes` covers `notes` and
+     * `notes/a`, while `notes/` covers everything under `notes/` but not
+     * `notes` itself. The session must hold `tinycloud.kv/sync` on it by name.
+     *
+     * Returned `changes[].key` values are full paths in the space, like this
+     * prefix. On a service with a configured prefix (for example
+     * `DelegatedAccess.kv`, whose prefix is the delegation path), `get` joins
+     * that prefix again, so strip it from the key first, or follow the feed
+     * with `kv.withPrefix(...).changes()`, which returns relative keys.
+     */
+    prefix: string;
+    /**
+     * The `cursor` from the previous page. Omit it to bootstrap from the start
+     * of the prefix. Opaque; never parse or build one.
+     */
+    cursor?: string;
+    /**
+     * Page size, 1 through 1000 (node default 500). A page never splits one
+     * invocation's changes, so it can hold more than `limit` changes.
+     */
+    limit?: number;
+    /**
+     * CID of a never-invoked delegation carrying `tinycloud.kv/retain` on the
+     * prefix. When valid, the node attests `authority.retainUntil`.
+     */
+    retentionGrant?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * One key's latest state in a change feed page. Content is not included:
+ * read it with `get`/`batchGet` and check it against `etag`.
+ */
+type KVChange = {
+    key: string;
+    deleted: false;
+    /** The strong ETag `get` returns for this state. */
+    etag: string;
+    metadata: Record<string, string>;
+} | {
+    key: string;
+    deleted: true;
+};
+/**
+ * The node-attested window in which the caller's authority holds. Values are
+ * RFC 3339 timestamps, or `null` when nothing in the chain sets one.
+ */
+interface KVChangesAuthority {
+    /** The latest `nbf` across the invocation's whole delegation chain. */
+    notBefore: string | null;
+    /** The earliest `exp` across the invocation's whole delegation chain. */
+    expiresAt: string | null;
+    /**
+     * The earliest `exp` across a valid retention grant's own chain. `null`
+     * means no retention: none was presented, or its chain sets no expiry.
+     */
+    retainUntil: string | null;
+}
+/**
+ * One page of the `tinycloud.kv/sync` change feed.
+ */
+interface KVChangesResponse {
+    /** Each changed key's latest state, in commit order. */
+    changes: KVChange[];
+    /**
+     * More changes are available now. A page may be empty with `more: true`;
+     * keep paging with the returned cursor.
+     */
+    more: boolean;
+    /**
+     * The cursor for the next request. An empty poll returns the request's
+     * cursor unchanged.
+     */
+    cursor: string;
+    /** The node, space and prefix that served the page. */
+    source: {
+        nodeDid: string;
+        space: string;
+        prefix: string;
+    };
+    authority: KVChangesAuthority;
+}
 /**
  * Response from signed KV read URL creation.
  */
@@ -353,6 +459,10 @@ declare const KVAction: {
     readonly LIST: "tinycloud.kv/list";
     readonly DELETE: "tinycloud.kv/del";
     readonly HEAD: "tinycloud.kv/metadata";
+    /** The change feed; never implied by `*` or `tinycloud.kv/*`. */
+    readonly SYNC: "tinycloud.kv/sync";
+    /** Retention attestation; presented through `retentionGrant`, never invoked or implied. */
+    readonly RETAIN: "tinycloud.kv/retain";
 };
 type KVActionType = (typeof KVAction)[keyof typeof KVAction];
 
@@ -456,6 +566,20 @@ interface IPrefixedKVService {
      * ```
      */
     list(options?: Omit<KVListOptions, 'prefix'>): Promise<Result<KVListResponse>>;
+    /**
+     * Read one page of the change feed for everything under this prefix
+     * (`tinycloud.kv/sync` on `<prefix>/`). Keys are returned relative to the
+     * prefix, like `list`; `source.prefix` stays the node's full prefix.
+     * See `IKVService.changes` for paging and errors.
+     *
+     * @example
+     * ```typescript
+     * const notes = kv.withPrefix('notes');
+     * const page = await notes.changes({ limit: 100 });
+     * // -> Feed of: notes/*, keys like 'a.md'
+     * ```
+     */
+    changes(options?: Omit<KVChangesOptions, 'prefix'>): Promise<Result<KVChangesResponse>>;
     /**
      * Delete a key.
      *
@@ -530,6 +654,7 @@ interface IKVServiceLike {
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
     batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    changes(options: KVChangesOptions): Promise<Result<KVChangesResponse>>;
     delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
     batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
@@ -611,6 +736,12 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * List keys within this prefix.
      */
     list(options?: Omit<KVListOptions, 'prefix'>): Promise<Result<KVListResponse>>;
+    /**
+     * Read the change feed for everything under this prefix. A view with an
+     * empty prefix (`""` or `"/"`) is refused: the node does not serve a
+     * whole-space feed.
+     */
+    changes(options?: Omit<KVChangesOptions, 'prefix'>): Promise<Result<KVChangesResponse>>;
     /**
      * Delete a key.
      */
@@ -759,6 +890,41 @@ interface IKVService extends IService {
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
     batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
+    /**
+     * Read one page of the ordered, delete-aware change feed for a KV prefix
+     * (`tinycloud.kv/sync`). Each change is a key's latest state; read content
+     * with `get`/`batchGet` and check it against the change's `etag`.
+     *
+     * `options.prefix` and every returned `key` are full paths in the space;
+     * the service's configured prefix is not applied to either. On a prefixed
+     * service (for example `DelegatedAccess.kv`), `get(change.key)` would join
+     * that prefix twice: strip the prefix from the key, or use
+     * `withPrefix(...).changes()`, which returns keys relative to the view.
+     *
+     * The session must hold `tinycloud.kv/sync` on `options.prefix` by name: no
+     * wildcard grants it. Page with the returned `cursor` while `more` is true;
+     * a page can exceed `limit`, or be empty with `more: true`.
+     *
+     * Errors: `KV_SYNC_RESET_REQUIRED` (410, `meta.reason`) means discard sync
+     * state and restart without a cursor. `AUTH_DELEGATION_REVOKED` and
+     * `AUTH_DELEGATION_ANCESTOR_REVOKED` mean the grant is revoked.
+     * `KV_RETENTION_GRANT_REFUSED` (403, `meta.reason`) rejects `retentionGrant`.
+     *
+     * Requires a node that advertises the `kv-sync-v1` feature in `/info`.
+     *
+     * @example
+     * ```typescript
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await kv.changes({ prefix: 'notes/', cursor });
+     *   if (!page.ok) throw new Error(page.error.message);
+     *   for (const change of page.data.changes) apply(change);
+     *   cursor = page.data.cursor;
+     *   if (!page.data.more) break;
+     * } while (true);
+     * ```
+     */
+    changes(options: KVChangesOptions): Promise<Result<KVChangesResponse>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      *
@@ -850,7 +1016,6 @@ declare class KVService extends BaseService implements IKVService {
      * Get the service configuration.
      */
     get config(): KVServiceConfig;
-    private parseQuotaInfo;
     private handleQuotaErrorResponse;
     /**
      * Classify a KV 404 by reading the response body once.
@@ -883,7 +1048,7 @@ declare class KVService extends BaseService implements IKVService {
      * @param path - Resource path
      * @param action - KV action
      * @param body - Optional request body
-     * @param signal - Optional abort signal
+     * @param signal - Request signal from createRequestSignal()
      * @returns Fetch response
      */
     private invokeOperation;
@@ -919,12 +1084,16 @@ declare class KVService extends BaseService implements IKVService {
      */
     private parseResponse;
     private createSignedReadUrlError;
+    /** A known 401/403 keeps its typed status even if reading its body fails. */
+    private readAuthorizationText;
     /**
      * AUTH_UNAUTHORIZED for a 401/403 response. The message keeps the HTTP
      * status and the server text (`<context>: <status> - <text>`, the same
      * shape as every other KV failure) so callers that rethrow only the message
      * still see the status; `meta.status` carries it for typed callers.
-     * Resource/ability hints are parsed from the raw body, never the message.
+     * Server hints must match the requested path/action (whether the node sends
+     * a relative path or full resource); metadata uses only the request-derived
+     * canonical resource under the authenticated session's space.
      */
     private authorizationFailure;
     private normalizeSignedReadUrlResponse;
@@ -945,6 +1114,19 @@ declare class KVService extends BaseService implements IKVService {
      * List keys with optional prefix filtering.
      */
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    /**
+     * Read one page of the `tinycloud.kv/sync` change feed for a prefix.
+     */
+    changes(options: KVChangesOptions): Promise<Result<KVChangesResponse>>;
+    /**
+     * Map a failed `kv/sync` response. 410 and the retention 403 carry
+     * `{"error":{"code","reason"}}`; a revoked grant is a 401 whose whole body
+     * is the node's revocation error (see REVOKED_BODY). A body read that
+     * fails because the request was cancelled or timed out rethrows, so the
+     * caller sees `ABORTED`/`TIMEOUT` rather than a mapped status.
+     */
+    private changesFailure;
+    private normalizeChangesResponse;
     /**
      * Delete a key.
      */
@@ -1003,4 +1185,4 @@ declare class KVService extends BaseService implements IKVService {
     withPrefix(prefix: string): IPrefixedKVService;
 }
 
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVBatchReadResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVBatchReadResponse, type KVChange, type KVChangesAuthority, type KVChangesOptions, type KVChangesResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };

package/dist/kv/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BaseService } from '../BaseService-CuV-ZVPs.js';
-import { R as Result, I as IService } from '../types-qwMmB7qB.js';
+import { B as BaseService } from '../BaseService-B_UKhVht.js';
+import { R as Result, I as IService } from '../types-CVwwxqXF.js';
 
 /**
  * KV Service Types
@@ -23,8 +23,11 @@ interface KVServiceConfig {
      */
     prefix?: string;
     /**
-     * Default timeout in milliseconds for KV operations.
-     * Overrides the context-level timeout if set.
+     * Default timeout in milliseconds for each KV request, including reading
+     * the response body. When it elapses the request is aborted and the
+     * operation returns an `ErrorCodes.TIMEOUT` error. A per-call `timeout`
+     * option overrides it. Unset (the default), `0`, or `Infinity` means no
+     * timeout.
      */
     timeout?: number;
     /** Allow additional config properties */
@@ -55,7 +58,8 @@ interface KVGetOptions {
      */
     maxResponseBytes?: number;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -85,7 +89,8 @@ interface KVPutOptions {
     /** Only write when the key does not exist. */
     ifNoneMatch?: "*";
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -123,7 +128,8 @@ interface KVBatchPutOptions {
      */
     prefix?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -182,7 +188,8 @@ interface KVListOptions {
     /** Opaque scope-bound cursor returned by a previous bounded list. */
     cursor?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -201,7 +208,8 @@ interface KVDeleteOptions {
     /** Only delete when the current object has this strong ETag. */
     ifMatch?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -218,7 +226,8 @@ interface KVHeadOptions {
      */
     prefix?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -259,7 +268,8 @@ interface KVCreateSignedReadUrlOptions {
      */
     etag?: string;
     /**
-     * Custom timeout for this operation in milliseconds.
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
      */
     timeout?: number;
     /**
@@ -323,6 +333,102 @@ interface KVListResponse {
     /** Opaque cursor for the next page, when the node returned one. */
     nextCursor?: string;
 }
+/**
+ * Options for {@link IKVService.changes}, the `tinycloud.kv/sync` change feed.
+ */
+interface KVChangesOptions {
+    /**
+     * The space-relative KV prefix to follow, sent as the invocation path. It
+     * is not joined with the service's configured prefix, and must be non-empty.
+     * Prefixes match whole path segments: `notes` covers `notes` and
+     * `notes/a`, while `notes/` covers everything under `notes/` but not
+     * `notes` itself. The session must hold `tinycloud.kv/sync` on it by name.
+     *
+     * Returned `changes[].key` values are full paths in the space, like this
+     * prefix. On a service with a configured prefix (for example
+     * `DelegatedAccess.kv`, whose prefix is the delegation path), `get` joins
+     * that prefix again, so strip it from the key first, or follow the feed
+     * with `kv.withPrefix(...).changes()`, which returns relative keys.
+     */
+    prefix: string;
+    /**
+     * The `cursor` from the previous page. Omit it to bootstrap from the start
+     * of the prefix. Opaque; never parse or build one.
+     */
+    cursor?: string;
+    /**
+     * Page size, 1 through 1000 (node default 500). A page never splits one
+     * invocation's changes, so it can hold more than `limit` changes.
+     */
+    limit?: number;
+    /**
+     * CID of a never-invoked delegation carrying `tinycloud.kv/retain` on the
+     * prefix. When valid, the node attests `authority.retainUntil`.
+     */
+    retentionGrant?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * One key's latest state in a change feed page. Content is not included:
+ * read it with `get`/`batchGet` and check it against `etag`.
+ */
+type KVChange = {
+    key: string;
+    deleted: false;
+    /** The strong ETag `get` returns for this state. */
+    etag: string;
+    metadata: Record<string, string>;
+} | {
+    key: string;
+    deleted: true;
+};
+/**
+ * The node-attested window in which the caller's authority holds. Values are
+ * RFC 3339 timestamps, or `null` when nothing in the chain sets one.
+ */
+interface KVChangesAuthority {
+    /** The latest `nbf` across the invocation's whole delegation chain. */
+    notBefore: string | null;
+    /** The earliest `exp` across the invocation's whole delegation chain. */
+    expiresAt: string | null;
+    /**
+     * The earliest `exp` across a valid retention grant's own chain. `null`
+     * means no retention: none was presented, or its chain sets no expiry.
+     */
+    retainUntil: string | null;
+}
+/**
+ * One page of the `tinycloud.kv/sync` change feed.
+ */
+interface KVChangesResponse {
+    /** Each changed key's latest state, in commit order. */
+    changes: KVChange[];
+    /**
+     * More changes are available now. A page may be empty with `more: true`;
+     * keep paging with the returned cursor.
+     */
+    more: boolean;
+    /**
+     * The cursor for the next request. An empty poll returns the request's
+     * cursor unchanged.
+     */
+    cursor: string;
+    /** The node, space and prefix that served the page. */
+    source: {
+        nodeDid: string;
+        space: string;
+        prefix: string;
+    };
+    authority: KVChangesAuthority;
+}
 /**
  * Response from signed KV read URL creation.
  */
@@ -353,6 +459,10 @@ declare const KVAction: {
     readonly LIST: "tinycloud.kv/list";
     readonly DELETE: "tinycloud.kv/del";
     readonly HEAD: "tinycloud.kv/metadata";
+    /** The change feed; never implied by `*` or `tinycloud.kv/*`. */
+    readonly SYNC: "tinycloud.kv/sync";
+    /** Retention attestation; presented through `retentionGrant`, never invoked or implied. */
+    readonly RETAIN: "tinycloud.kv/retain";
 };
 type KVActionType = (typeof KVAction)[keyof typeof KVAction];
 
@@ -456,6 +566,20 @@ interface IPrefixedKVService {
      * ```
      */
     list(options?: Omit<KVListOptions, 'prefix'>): Promise<Result<KVListResponse>>;
+    /**
+     * Read one page of the change feed for everything under this prefix
+     * (`tinycloud.kv/sync` on `<prefix>/`). Keys are returned relative to the
+     * prefix, like `list`; `source.prefix` stays the node's full prefix.
+     * See `IKVService.changes` for paging and errors.
+     *
+     * @example
+     * ```typescript
+     * const notes = kv.withPrefix('notes');
+     * const page = await notes.changes({ limit: 100 });
+     * // -> Feed of: notes/*, keys like 'a.md'
+     * ```
+     */
+    changes(options?: Omit<KVChangesOptions, 'prefix'>): Promise<Result<KVChangesResponse>>;
     /**
      * Delete a key.
      *
@@ -530,6 +654,7 @@ interface IKVServiceLike {
     put(key: string, value: unknown, options?: KVPutOptions): Promise<Result<KVResponse<void>>>;
     batchPut(items: KVBatchPutItem[], options?: KVBatchPutOptions): Promise<Result<KVBatchPutResponse>>;
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    changes(options: KVChangesOptions): Promise<Result<KVChangesResponse>>;
     delete(key: string, options?: KVDeleteOptions): Promise<Result<KVResponse<void>>>;
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
     batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
@@ -611,6 +736,12 @@ declare class PrefixedKVService implements IPrefixedKVService {
      * List keys within this prefix.
      */
     list(options?: Omit<KVListOptions, 'prefix'>): Promise<Result<KVListResponse>>;
+    /**
+     * Read the change feed for everything under this prefix. A view with an
+     * empty prefix (`""` or `"/"`) is refused: the node does not serve a
+     * whole-space feed.
+     */
+    changes(options?: Omit<KVChangesOptions, 'prefix'>): Promise<Result<KVChangesResponse>>;
     /**
      * Delete a key.
      */
@@ -759,6 +890,41 @@ interface IKVService extends IService {
      */
     head(key: string, options?: KVHeadOptions): Promise<Result<KVResponse<void>>>;
     batchHead(keys: string[], options?: KVHeadOptions): Promise<Result<KVBatchReadResponse<void>>>;
+    /**
+     * Read one page of the ordered, delete-aware change feed for a KV prefix
+     * (`tinycloud.kv/sync`). Each change is a key's latest state; read content
+     * with `get`/`batchGet` and check it against the change's `etag`.
+     *
+     * `options.prefix` and every returned `key` are full paths in the space;
+     * the service's configured prefix is not applied to either. On a prefixed
+     * service (for example `DelegatedAccess.kv`), `get(change.key)` would join
+     * that prefix twice: strip the prefix from the key, or use
+     * `withPrefix(...).changes()`, which returns keys relative to the view.
+     *
+     * The session must hold `tinycloud.kv/sync` on `options.prefix` by name: no
+     * wildcard grants it. Page with the returned `cursor` while `more` is true;
+     * a page can exceed `limit`, or be empty with `more: true`.
+     *
+     * Errors: `KV_SYNC_RESET_REQUIRED` (410, `meta.reason`) means discard sync
+     * state and restart without a cursor. `AUTH_DELEGATION_REVOKED` and
+     * `AUTH_DELEGATION_ANCESTOR_REVOKED` mean the grant is revoked.
+     * `KV_RETENTION_GRANT_REFUSED` (403, `meta.reason`) rejects `retentionGrant`.
+     *
+     * Requires a node that advertises the `kv-sync-v1` feature in `/info`.
+     *
+     * @example
+     * ```typescript
+     * let cursor: string | undefined;
+     * do {
+     *   const page = await kv.changes({ prefix: 'notes/', cursor });
+     *   if (!page.ok) throw new Error(page.error.message);
+     *   for (const change of page.data.changes) apply(change);
+     *   cursor = page.data.cursor;
+     *   if (!page.data.more) break;
+     * } while (true);
+     * ```
+     */
+    changes(options: KVChangesOptions): Promise<Result<KVChangesResponse>>;
     /**
      * Create a short-lived signed URL for reading a KV object.
      *
@@ -850,7 +1016,6 @@ declare class KVService extends BaseService implements IKVService {
      * Get the service configuration.
      */
     get config(): KVServiceConfig;
-    private parseQuotaInfo;
     private handleQuotaErrorResponse;
     /**
      * Classify a KV 404 by reading the response body once.
@@ -883,7 +1048,7 @@ declare class KVService extends BaseService implements IKVService {
      * @param path - Resource path
      * @param action - KV action
      * @param body - Optional request body
-     * @param signal - Optional abort signal
+     * @param signal - Request signal from createRequestSignal()
      * @returns Fetch response
      */
     private invokeOperation;
@@ -919,12 +1084,16 @@ declare class KVService extends BaseService implements IKVService {
      */
     private parseResponse;
     private createSignedReadUrlError;
+    /** A known 401/403 keeps its typed status even if reading its body fails. */
+    private readAuthorizationText;
     /**
      * AUTH_UNAUTHORIZED for a 401/403 response. The message keeps the HTTP
      * status and the server text (`<context>: <status> - <text>`, the same
      * shape as every other KV failure) so callers that rethrow only the message
      * still see the status; `meta.status` carries it for typed callers.
-     * Resource/ability hints are parsed from the raw body, never the message.
+     * Server hints must match the requested path/action (whether the node sends
+     * a relative path or full resource); metadata uses only the request-derived
+     * canonical resource under the authenticated session's space.
      */
     private authorizationFailure;
     private normalizeSignedReadUrlResponse;
@@ -945,6 +1114,19 @@ declare class KVService extends BaseService implements IKVService {
      * List keys with optional prefix filtering.
      */
     list(options?: KVListOptions): Promise<Result<KVListResponse>>;
+    /**
+     * Read one page of the `tinycloud.kv/sync` change feed for a prefix.
+     */
+    changes(options: KVChangesOptions): Promise<Result<KVChangesResponse>>;
+    /**
+     * Map a failed `kv/sync` response. 410 and the retention 403 carry
+     * `{"error":{"code","reason"}}`; a revoked grant is a 401 whose whole body
+     * is the node's revocation error (see REVOKED_BODY). A body read that
+     * fails because the request was cancelled or timed out rethrows, so the
+     * caller sees `ABORTED`/`TIMEOUT` rather than a mapped status.
+     */
+    private changesFailure;
+    private normalizeChangesResponse;
     /**
      * Delete a key.
      */
@@ -1003,4 +1185,4 @@ declare class KVService extends BaseService implements IKVService {
     withPrefix(prefix: string): IPrefixedKVService;
 }
 
-export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVBatchReadResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };
+export { DEFAULT_SIGNED_READ_URL_EXPIRY_MS, type IKVService, type IPrefixedKVService, KVAction, type KVActionType, type KVBatchPutItem, type KVBatchPutOptions, type KVBatchPutResponse, type KVBatchReadResponse, type KVChange, type KVChangesAuthority, type KVChangesOptions, type KVChangesResponse, type KVCreateSignedReadUrlOptions, type KVDeleteOptions, type KVGetOptions, type KVHeadOptions, type KVListOptions, type KVListResponse, type KVPutOptions, type KVResponse, type KVResponseHeaders, KVService, type KVServiceConfig, type KVSignedReadUrlResponse, PrefixedKVService };