@tinycloud/sdk-services 3.1.0-beta.7 → 3.1.0

package/dist/kv/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BaseService } from '../BaseService-C8zRy0ww.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
@@ -333,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.
  */
@@ -363,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];
 
@@ -466,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.
      *
@@ -540,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>>>;
@@ -621,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.
      */
@@ -769,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.
      *
@@ -917,6 +1073,16 @@ declare class KVService extends BaseService implements IKVService {
     private createResponseHeaders;
     private createBatchResponseHeaders;
     private parseBatchValue;
+    /**
+     * Validate a batch read response and return its items in the caller's
+     * request order. The node flattens invocation abilities from a `BTreeMap`,
+     * so results arrive sorted by UTF-8 byte order of the path, not in request
+     * order. Items that carry their path in `key` are matched by path; if no
+     * item carries a key, items are assumed to be in the node's byte-sorted
+     * order and the request is aligned the same way. Any mix of keyed and
+     * keyless items, a missing requested path, an unrequested path, or a
+     * malformed item fails closed (returns undefined).
+     */
     private normalizeBatchReadResponse;
     private batchRead;
     /**
@@ -958,6 +1124,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.
      */
@@ -1016,4 +1195,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-DU-lE-Qx.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
@@ -333,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.
  */
@@ -363,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];
 
@@ -466,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.
      *
@@ -540,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>>>;
@@ -621,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.
      */
@@ -769,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.
      *
@@ -917,6 +1073,16 @@ declare class KVService extends BaseService implements IKVService {
     private createResponseHeaders;
     private createBatchResponseHeaders;
     private parseBatchValue;
+    /**
+     * Validate a batch read response and return its items in the caller's
+     * request order. The node flattens invocation abilities from a `BTreeMap`,
+     * so results arrive sorted by UTF-8 byte order of the path, not in request
+     * order. Items that carry their path in `key` are matched by path; if no
+     * item carries a key, items are assumed to be in the node's byte-sorted
+     * order and the request is aligned the same way. Any mix of keyed and
+     * keyless items, a missing requested path, an unrequested path, or a
+     * malformed item fails closed (returns undefined).
+     */
     private normalizeBatchReadResponse;
     private batchRead;
     /**
@@ -958,6 +1124,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.
      */
@@ -1016,4 +1195,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 };