@warmhub/sdk-ts 0.52.1 → 0.54.0

package/dist/index.d.ts

@@ -74,6 +74,29 @@ type ActionRunStats = {
         dead_letter: number;
     };
 };
+type AccessResolveInput$1 = {
+    repos?: Array<{
+        orgName: string;
+        repoName: string;
+    }>;
+    orgs?: Array<{
+        orgName: string;
+    }>;
+};
+type AccessResolveResult$1 = {
+    repos: Array<{
+        orgName: string;
+        repoName: string;
+        visible: boolean;
+        scopes: Array<'repo:read' | 'repo:write' | 'repo:configure' | 'repo:admin'>;
+        allowedMatches?: Array<string>;
+    }>;
+    orgs: Array<{
+        orgName: string;
+        visible: boolean;
+        scopes: Array<'org:read' | 'org:configure' | 'org:admin'>;
+    }>;
+};
 type AuthSyncResult = {
     success: boolean;
 };
@@ -107,7 +130,7 @@ type CommitApplyResult = {
     }>;
 };
 type ComponentDetail = {
-    componentId: string;
+    ref?: string;
     componentName: string;
     version?: string;
     state?: string;
@@ -150,14 +173,14 @@ type ComponentDetail = {
             data: unknown;
             dataHash: string;
         } | null;
-        componentId?: string;
+        componentRef?: string;
     }>;
     ownedThings: Array<{
         wref: string;
         name: string;
         kind: 'shape' | 'thing' | 'assertion' | 'collection';
         shapeName?: string;
-        componentId?: string;
+        componentRef?: string;
         version: number;
         createdAt: number;
         data?: unknown;
@@ -172,7 +195,7 @@ type ComponentDetail = {
 };
 type ComponentListResult = {
     items: Array<{
-        componentId: string;
+        ref?: string;
         componentName: string;
         version?: string;
         state?: string;
@@ -188,7 +211,7 @@ type ComponentListResult = {
     nextCursor?: string;
 };
 type ComponentSummary = {
-    componentId: string;
+    ref?: string;
     componentName: string;
     version?: string;
     state?: string;
@@ -222,7 +245,7 @@ type StreamAppendInput$1 = {
     orgName: string;
     repoName: string;
     streamId: string;
-    componentId?: string;
+    componentRef?: string;
     workspaceName?: never;
     committer?: string;
     message?: string;
@@ -407,7 +430,7 @@ type ShapeGetResult = {
         data: unknown;
         dataHash: string;
     } | null;
-    componentId?: string;
+    componentRef?: string;
 };
 type ShapeListResult = {
     items: Array<{
@@ -420,7 +443,7 @@ type ShapeListResult = {
             data: unknown;
             dataHash: string;
         } | null;
-        componentId?: string;
+        componentRef?: string;
     }>;
 };
 type ThingGetManyResult$1 = {
@@ -1006,7 +1029,7 @@ declare function submitOperationsViaStream(client: OperationStreamClient, args:
     committer?: string;
     message?: string;
     operations: Operation[];
-    componentId?: string;
+    componentRef?: string;
     chunkSize?: number;
     skipExisting?: boolean;
     streamId?: string;
@@ -1748,7 +1771,7 @@ type SubscriptionInfo = {
     };
     allowTraceReentry?: boolean;
     notifyOnSuccess?: boolean;
-    componentId?: string;
+    componentRef?: string;
     credentialSetNames: Array<string>;
     createdAt: number;
 };
@@ -1767,7 +1790,7 @@ type SubscriptionCompatCreateBase = {
     fallbackWebhookUrl?: string;
     allowTraceReentry?: boolean;
     notifyOnSuccess?: boolean;
-    componentId?: string;
+    componentRef?: string;
     workspacePolicy?: never;
     /** @internal */
     actionContainer?: string;
@@ -1887,7 +1910,6 @@ type ComponentListOptions = {
     cursor?: string;
 };
 type ComponentRegistryInfo = {
-    id: string;
     ownerOrgName: string;
     componentName: string;
     ref: string;
@@ -1962,7 +1984,7 @@ type ComponentRegistryCliCallResult = ComponentRegistrySetupCallResult;
 /** @internal */
 type ShapeListOptions = {
     match?: string;
-    componentId?: string;
+    componentRef?: string;
     excludeComponents?: boolean;
     includeRetracted?: boolean;
 };
@@ -2027,6 +2049,28 @@ type RepoInfo = {
 };
 /** @internal */
 type RepoList = RepoListResult;
+/**
+ * A cross-org search hit (repo or component). GH-4383.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/globalsearchresultitem/
+ */
+type GlobalSearchResultItem = {
+    kind: 'repo' | 'component';
+    orgName: string;
+    name: string;
+    description: string | null;
+};
+/** @internal */
+type GlobalSearchResult = {
+    items: GlobalSearchResultItem[];
+    nextCursor?: string;
+};
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/globalsearchoptions/
+ */
+type GlobalSearchOptions = {
+    limit?: number;
+    cursor?: string;
+};
 /** @internal */
 type OrgListOptions = {
     includeArchived?: boolean;
@@ -2321,7 +2365,7 @@ type ThingHeadRequest = {
     includeRetracted?: boolean;
     limit?: number;
     cursor?: string;
-    componentId?: string;
+    componentRef?: string;
     excludeComponents?: boolean;
     excludeInfraShapes?: boolean;
     where?: WherePredicate[];
@@ -2575,8 +2619,8 @@ type FilterOptions = {
     limit?: number;
     /** Pagination cursor returned by the prior call. */
     cursor?: string;
-    /** Filter to records attributed to this component identifier. */
-    componentId?: string;
+    /** Filter to records attributed to this installed component's `Org/Name` ref. */
+    componentRef?: string;
     /** Exclude records attributed to any component. */
     excludeComponents?: boolean;
     /** Exclude internal infrastructure shapes from the result set. */
@@ -2797,6 +2841,29 @@ declare function sdkVersionIsBelowMinimum(version: string, minimum: string): boo
  *
  * @see https://docs.warmhub.ai/sdk/client/
  */
+/**
+ * Input for {@link WarmHubClient.access.resolve} — repos/orgs addressed by name.
+ * @internal
+ */
+type AccessResolveInput = AccessResolveInput$1;
+/**
+ * Batch effective-access result; correlate by the echoed `orgName`/`repoName`.
+ * @internal
+ */
+type AccessResolveResult = AccessResolveResult$1;
+/**
+ * Effective repo access for the caller (one entry of {@link AccessResolveResult}).
+ * @internal
+ */
+type RepoAccessResult = AccessResolveResult$1['repos'][number];
+/**
+ * Effective org-level access for the caller (one entry of {@link AccessResolveResult}).
+ * @internal
+ */
+type OrgAccessResult = AccessResolveResult$1['orgs'][number];
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/
+ */
 declare class WarmHubClient {
     /**
      * The resolved API base URL the client issues requests against. Defaults to
@@ -2839,22 +2906,21 @@ declare class WarmHubClient {
         whoami: () => Promise<WhoamiInfo>;
     };
     /**
-     * Lightweight permission checks for UI gating and service-side authorization probes.
-     * @see https://docs.warmhub.ai/sdk-reference/classes/warmhubclient/#access
+     * Effective-access resolution for UI gating and service-side authorization.
+     * First-party surface (web UI + whedge edge); the underlying `access.resolve`
+     * procedure is `@internal`.
+     * @internal
      */
     readonly access: {
         /**
-         * Check whether the caller has a repo-scoped permission.
-         *
-         * @param permission Permission string such as `repo:read`, `repo:write`, `repo:configure`, or `repo:admin`.
-         */
-        checkRepoPermission: (orgName: string, repoName: string, permission: string) => Promise<boolean>;
-        /**
-         * Check whether the caller has an org-scoped permission.
-         *
-         * @param permission Permission string such as `org:read`, `org:configure`, or `org:admin`.
+         * Resolve the caller's effective access for a batch of repos and/or orgs
+         * (addressed by name). Returns the coarse scope SET per target so one call
+         * answers any permission via `scopes.includes(...)` — e.g.
+         * `scopes.includes('repo:configure')`. Non-throwing: `visible: false` means
+         * not-found/not-visible; `scopes: []` means authenticated-but-no-access.
+         * Correlate results by the echoed `orgName`/`repoName`, not by position.
          */
-        checkOrgPermission: (orgName: string, permission: string) => Promise<boolean>;
+        resolve: (input: AccessResolveInput) => Promise<AccessResolveResult>;
     };
     /**
      * Connectivity and compatibility helpers for checking the configured WarmHub backend.
@@ -2897,12 +2963,24 @@ declare class WarmHubClient {
          * List components installed in a repository.
          *
          * Pass pagination options when a repository may have many installed components.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         list: (orgName: string, repoName: string, opts?: ComponentListOptions) => Promise<ComponentList>;
         /**
-         * Fetch one installed component by component ID.
+         * Search public registered components across all orgs (GH-4383).
+         * Public-only at launch. Distinct from listing components installed in a
+         * repo (`component.list`).
+         */
+        search: (query: string, opts?: GlobalSearchOptions) => Promise<GlobalSearchResult>;
+        /**
+         * Fetch one installed component by its `Org/Name` ref.
          */
-        get: (orgName: string, repoName: string, componentId: string) => Promise<ComponentView>;
+        get: (orgName: string, repoName: string, componentRef: string) => Promise<ComponentView>;
         /**
          * Registered-component identity and install-pipeline operations.
          *
@@ -2959,7 +3037,7 @@ declare class WarmHubClient {
          * @param message Optional commit message stored with the submitted operations.
          * @param operations Add, revise, or retract operations to submit in order.
          * @param opts.committer Optional wref identifying the actor on whose behalf the write is made. Must be a full wref string like `"Agent/bot-1"` (a thing that already exists), or a cross-repo wref like `"wh:other-org/other-repo/Agent/bot-1"`. Bare names such as `"eval-runner"` are rejected by the backend with a "Thing wref required" error — there is no implicit shape.
-         * @param opts.componentId Attribute writes to an installed component when the caller is allowed to claim it.
+         * @param opts.componentRef Attribute writes to an installed component, identified by its `Org/Name` ref, when the caller is allowed to claim it.
          * @param opts.chunkSize Maximum operations per stream append. Values are clamped by the SDK.
          * @param opts.skipExisting Return `noop` for add operations whose target already exists.
          * @param opts.streamId Advanced continuation hook for caller-managed streams.
@@ -2967,7 +3045,7 @@ declare class WarmHubClient {
          */
         apply: (orgName: string, repoName: string, message: string | undefined, operations: Operation[], opts?: {
             committer?: string;
-            componentId?: string;
+            componentRef?: string;
             chunkSize?: number;
             skipExisting?: boolean;
             streamId?: string;
@@ -3122,8 +3200,19 @@ declare class WarmHubClient {
          * List repositories in an organization.
          *
          * Archived repositories are hidden by default. Search and sort options are applied before pagination.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         list: (orgName: string, opts?: RepoListOptions) => Promise<RepoList>;
+        /**
+         * Search public repos across all orgs (GH-4383). Public-only at launch;
+         * BM25 over name/description/shape vocabulary/README.
+         */
+        search: (query: string, opts?: GlobalSearchOptions) => Promise<GlobalSearchResult>;
         /**
          * Create a repository inside an organization.
          *
@@ -3194,6 +3283,12 @@ declare class WarmHubClient {
          * Each item includes exact active counts, an activity-oriented `lastWriteAt`, and a `hasErrors` flag for terminal action failures.
          *
          * Search and sort are applied before pagination, so cursors remain stable across the filtered and ordered list.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         listPage: (orgName: string, opts?: RepoListPageOptions) => Promise<RepoListPageResult>;
         /**
@@ -3310,6 +3405,12 @@ declare class WarmHubClient {
          * Return add, revise, retract, and rename history for a shape.
          *
          * Use pagination options for long-lived shapes with many revisions.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         history: (orgName: string, repoName: string, name: string, opts?: ShapeHistoryOptions) => Promise<ShapeHistory>;
     };
@@ -3416,6 +3517,12 @@ declare class WarmHubClient {
          * Query the live delivery feed for a subscription.
          *
          * Use this for polling or live-log views that need recent delivery status entries.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         liveFeed: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => Promise<ActionLiveFeed>;
         /**
@@ -3453,18 +3560,36 @@ declare class WarmHubClient {
          * Filter by shape, kind, assertion target, or glob `match` pattern, and choose the data mode appropriate for the payload size. Component filters can narrow results to component-owned records or hide component infrastructure records.
          *
          * Tokenless reads of public repositories have stricter page-size and page-count limits than authenticated reads.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         head: (orgName: string, repoName: string, opts?: ThingHeadOptions) => Promise<ThingHead>;
         /**
          * Iterate every current HEAD row matching the supplied filters.
          *
          * Prefer this over hand-written cursor loops when scanning all matching records. Pass `opts.cursor` to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass `limit` to control page size.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         headIter: (orgName: string, repoName: string, opts?: ThingHeadOptions) => AsyncIterableIterator<ThingItem>;
         /**
          * Materialize every current HEAD row matching the supplied filters.
          *
          * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` items have actually been observed across pages.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         headAll: (orgName: string, repoName: string, opts?: ThingHeadOptions & {
             max?: number;
@@ -3550,6 +3675,12 @@ declare class WarmHubClient {
          * Return version history and timeline metadata for repository records.
          *
          * Provide at least one selector: a concrete wref, a shape filter, or an assertion target. Shape- and target-filtered histories support pagination and optional collection resolution.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         history: (orgName: string | undefined, repoName: string | undefined, opts: ThingHistoryOptions) => Promise<ThingHistory>;
         /**
@@ -3567,6 +3698,12 @@ declare class WarmHubClient {
          *
          * Filter by assertion shape or glob `match` pattern, optionally resolve collection targets, and page through large assertion sets with `limit` and `cursor`.
          *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
+         *
          * Returns `{ target?, assertions, nextCursor? }`.
          * The array is named `assertions`, **not** `items`. This breaks the repo-wide
          * `items` convention used by `HeadResult`, `FilterResult`, `SearchResult`,
@@ -3584,12 +3721,24 @@ declare class WarmHubClient {
          * Iterate every assertion about a thing or collection target.
          *
          * Prefer this over hand-written cursor loops when scanning all matching assertions. The iterator reads the `assertions` envelope field and advances the cursor automatically; pass `opts.cursor` to resume from a saved cursor and `limit` to control page size.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         aboutIter: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: AboutOptions) => AsyncIterableIterator<Assertion>;
         /**
          * Materialize every assertion about a thing or collection target.
          *
          * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` assertions have actually been observed across pages.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         aboutAll: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: AboutOptions & {
             max?: number;
@@ -3598,18 +3747,36 @@ declare class WarmHubClient {
          * Query repository records by shape, kind, assertion target, text filters, or glob `match` pattern.
          *
          * Use this for structured reads where the caller controls filters. For ranked text or vector search, use `thing.search`. For count-only reads, use `thing.count`.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         query: (orgName: string, repoName: string, opts?: FilterOptions) => Promise<FilterResult>;
         /**
          * Iterate every repository record matching the supplied filters.
          *
          * Prefer this over hand-written cursor loops when scanning all matching records. Pass `opts.cursor` to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass `limit` to control page size.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         queryIter: (orgName: string, repoName: string, opts?: FilterOptions) => AsyncIterableIterator<ThingItem>;
         /**
          * Materialize every repository record matching the supplied filters.
          *
          * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` items have actually been observed across pages.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         queryAll: (orgName: string, repoName: string, opts?: FilterOptions & {
             max?: number;
@@ -3618,6 +3785,12 @@ declare class WarmHubClient {
          * Search repository records with text, vector, or hybrid mode.
          *
          * When searching with an assertion target or collection resolution, pages may be sparse; keep paginating until `nextCursor` is absent.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         search: (orgName: string, repoName: string, query: string, opts?: SearchOptions) => Promise<SearchResult>;
         /**
@@ -3628,18 +3801,36 @@ declare class WarmHubClient {
          * Query wref-typed field references for a record.
          *
          * Inbound mode finds records whose wref fields point at the supplied wref. Outbound mode finds records that the supplied record points to. Inbound queries can be narrowed to a field path.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         refs: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: RefsOptions) => Promise<RefsResult>;
         /**
          * Iterate every wref-typed field reference for a record.
          *
          * Prefer this over hand-written cursor loops when scanning all matching references. Pass `opts.cursor` to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass `limit` to control page size.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         refsIter: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: RefsOptions) => AsyncIterableIterator<RefLink>;
         /**
          * Materialize every wref-typed field reference for a record.
          *
          * Use `max` to guard memory usage; throws a `WarmHubError` with kind `VALIDATION_ERROR` once more than `max` refs have actually been observed across pages.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         refsAll: (orgName: string | undefined, repoName: string | undefined, wref: string, opts?: RefsOptions & {
             max?: number;
@@ -3654,14 +3845,32 @@ declare class WarmHubClient {
          * Stream refreshed `thing.head` results whenever the repository changes.
          *
          * The SDK re-runs the underlying `thing.head` query after each invalidation and passes the latest snapshot to `onUpdate`.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         thingHead: (orgName: string, repoName: string, opts: LiveThingHeadOptions | undefined, onUpdate: (result: ThingHead) => void | Promise<void>) => Promise<LiveHandle>;
         /**
          * Stream refreshed history results for a single wref whenever the repository changes.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         thingHistory: (orgName: string, repoName: string, opts: LiveThingHistoryOptions, onUpdate: (result: ThingHistory) => void | Promise<void>) => Promise<LiveHandle>;
         /**
          * Stream refreshed action live-feed entries for a subscription.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         subscriptionLog: (orgName: string, repoName: string, subscriptionName: string, opts: LiveSubscriptionLogOptions | undefined, onUpdate: (result: ActionLiveFeed) => void | Promise<void>) => Promise<LiveHandle>;
         /**
@@ -3881,6 +4090,12 @@ declare class WarmHubClient {
          * Query the live delivery feed for a subscription.
          *
          * Use this for polling or live-log views that need recent delivery status entries.
+         *
+         * Cursor contract: cursors are short-lived resume tokens for the same query
+         * and result scope. If filters, visibility, or backing streams change, the
+         * backend may reject a saved cursor with `VALIDATION_ERROR` / `Invalid
+         * cursor`; restart the query without `cursor` instead of retrying the stale
+         * token.
          */
         liveFeed: (orgName: string, repoName: string, subscriptionName: string, opts?: ActionLiveFeedOptions) => Promise<ActionLiveFeed>;
         /**
@@ -3914,4 +4129,4 @@ declare class WarmHubClient {
     private watchRepoQuery;
 }
 
-export { type AboutOptions, type AboutResult, type AccessTokenProvider, type ActionAttemptInfo, type ActionLeaseAcquire, type ActionLeaseOp, type ActionListNotificationsOptions, type ActionListRunsOptions, type ActionLiveFeed, type ActionLiveFeedOptions, type ActionNotificationInfo, type ActionRunInfo, type ActionRunStatsInfo, type ActionRunStatsOptions, type AddOp, type AddOperation, AllStreamOperationsFailedError, type Assertion, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, type CliCallSecrets, CliCallVerificationError, type CliCallVerificationFailureReason, type CollectionAbout, type CollectionTag, type ComponentInfo, type ComponentList, type ComponentListOptions, type ComponentView, type CoreErrorKind, type CountOptions, type CountResult, type CredentialAuditEntry, type CredentialDeleteResult, type CredentialGrantResult, type CredentialInfo, type CredentialKeyMutationResult, type CredentialRevokeResult, type CredentialUngrantResult, type CurrentUserInfo, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, type ErrorKind, type FilterOptions, type FilterResult, type FunctionLogMode, type HeadResult, type HistoryResult, type IndexedFieldEntry, type IndexedFieldsReport, type LiveHandle, type LiveRepoEvent, type LiveSubscriptionLogOptions, type LiveThingHeadOptions, type LiveThingHistoryOptions, type LiveWatchResult, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, type Operation, OperationBuilder, type OperationBuilderClient, type OperationBuilderOp, type OperationBuilderOptions, type OperationSubmitResult, type OrgInfo, type OrgList, type OrgListMembersOptions, type OrgListOptions, type OrgMemberInfo, type OrgMemberList, type OrgRef, type OrgRole, type Page, type PageRequest, PartialStreamSubmissionError, type PingResult, type RefLink, type RefsOptions, type RefsResult, type RenameResult, type RepoConfigureStatsView, type RepoDescribeResult, type RepoInfo, type RepoList, type RepoListForCallerOptions, type RepoListOptions, type RepoListPageOptions, type RepoListPageResult, type RepoLocator, type RepoRecentInfo, type RepoRef, type RepoShapeInstanceCountsView, type RepoSort, type RepoStatsBatchResult, type RepoStatsView, type RepoWithStatsInfo, type RequestEvent, type ResolveWrefResult, type RetractOp, type RetractOperation, type RetryPolicyOptions, type ReviseOp, type ReviseOperation, SDK_VERSION, type SearchOptions, type SearchResult, type Shape, type ShapeChange, type ShapeCreateOptions, type ShapeFields, type ShapeGetOptions, type ShapeHistory, type ShapeHistoryOptions, type ShapeList, type ShapeListOptions, type ShapeRef, type ShapeRemove, type ShapeReviseOptions, type ShapeValidatorResult, type StreamAppendInput, type StreamAppendResult, type StreamContinuationState, type SubscriptionBindCredentialsResult, type SubscriptionCompatCreateInput, type SubscriptionCompatUpdateInput, type SubscriptionInfo, type SubscriptionList, type SubscriptionUnbindCredentialsResult, type SynthesizedRepoContent, type ThingDetail, type ThingGet, type ThingGetManyResult, type ThingGetOptions, type ThingGetWithLease, type ThingGraphOptions, type ThingGraphResult, type ThingGraphValue, type ThingHead, type ThingHeadOptions, type ThingHeadRequest, type ThingHeadVersionsResult, type ThingHistory, type ThingHistoryOptions, type ThingItem, type ThingMetadata, type TokenInfo, type TokenResult, type UndeclaredFieldsWarning, type ValidationDiagnostic, type ValidationResult, type VerifiedCliCall, WarmHubClient, type WarmHubClientOptions, WarmHubError, type WarmHubErrorDetails, type WherePredicate, type WhoamiInfo, type WhoamiScopeEntry, type WireScopeEntry, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };
+export { type AboutOptions, type AboutResult, type AccessResolveInput, type AccessResolveResult, type AccessTokenProvider, type ActionAttemptInfo, type ActionLeaseAcquire, type ActionLeaseOp, type ActionListNotificationsOptions, type ActionListRunsOptions, type ActionLiveFeed, type ActionLiveFeedOptions, type ActionNotificationInfo, type ActionRunInfo, type ActionRunStatsInfo, type ActionRunStatsOptions, type AddOp, type AddOperation, AllStreamOperationsFailedError, type Assertion, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, type CliCallSecrets, CliCallVerificationError, type CliCallVerificationFailureReason, type CollectionAbout, type CollectionTag, type ComponentInfo, type ComponentList, type ComponentListOptions, type ComponentView, type CoreErrorKind, type CountOptions, type CountResult, type CredentialAuditEntry, type CredentialDeleteResult, type CredentialGrantResult, type CredentialInfo, type CredentialKeyMutationResult, type CredentialRevokeResult, type CredentialUngrantResult, type CurrentUserInfo, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, type ErrorKind, type FilterOptions, type FilterResult, type FunctionLogMode, type GlobalSearchOptions, type GlobalSearchResult, type GlobalSearchResultItem, type HeadResult, type HistoryResult, type IndexedFieldEntry, type IndexedFieldsReport, type LiveHandle, type LiveRepoEvent, type LiveSubscriptionLogOptions, type LiveThingHeadOptions, type LiveThingHistoryOptions, type LiveWatchResult, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, type Operation, OperationBuilder, type OperationBuilderClient, type OperationBuilderOp, type OperationBuilderOptions, type OperationSubmitResult, type OrgAccessResult, type OrgInfo, type OrgList, type OrgListMembersOptions, type OrgListOptions, type OrgMemberInfo, type OrgMemberList, type OrgRef, type OrgRole, type Page, type PageRequest, PartialStreamSubmissionError, type PingResult, type RefLink, type RefsOptions, type RefsResult, type RenameResult, type RepoAccessResult, type RepoConfigureStatsView, type RepoDescribeResult, type RepoInfo, type RepoList, type RepoListForCallerOptions, type RepoListOptions, type RepoListPageOptions, type RepoListPageResult, type RepoLocator, type RepoRecentInfo, type RepoRef, type RepoShapeInstanceCountsView, type RepoSort, type RepoStatsBatchResult, type RepoStatsView, type RepoWithStatsInfo, type RequestEvent, type ResolveWrefResult, type RetractOp, type RetractOperation, type RetryPolicyOptions, type ReviseOp, type ReviseOperation, SDK_VERSION, type SearchOptions, type SearchResult, type Shape, type ShapeChange, type ShapeCreateOptions, type ShapeFields, type ShapeGetOptions, type ShapeHistory, type ShapeHistoryOptions, type ShapeList, type ShapeListOptions, type ShapeRef, type ShapeRemove, type ShapeReviseOptions, type ShapeValidatorResult, type StreamAppendInput, type StreamAppendResult, type StreamContinuationState, type SubscriptionBindCredentialsResult, type SubscriptionCompatCreateInput, type SubscriptionCompatUpdateInput, type SubscriptionInfo, type SubscriptionList, type SubscriptionUnbindCredentialsResult, type SynthesizedRepoContent, type ThingDetail, type ThingGet, type ThingGetManyResult, type ThingGetOptions, type ThingGetWithLease, type ThingGraphOptions, type ThingGraphResult, type ThingGraphValue, type ThingHead, type ThingHeadOptions, type ThingHeadRequest, type ThingHeadVersionsResult, type ThingHistory, type ThingHistoryOptions, type ThingItem, type ThingMetadata, type TokenInfo, type TokenResult, type UndeclaredFieldsWarning, type ValidationDiagnostic, type ValidationResult, type VerifiedCliCall, WarmHubClient, type WarmHubClientOptions, WarmHubError, type WarmHubErrorDetails, type WherePredicate, type WhoamiInfo, type WhoamiScopeEntry, type WireScopeEntry, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AllStreamOperationsFailedError, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, CliCallVerificationError, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall } from './chunk-OPTB23HY.js';
+export { AllStreamOperationsFailedError, CLI_INSTALL_REPO_HEADER, CLI_SIGNATURE_HEADER, CLI_TIMESTAMP_HEADER, CONTENT_FIELD_LIMIT_ERROR, CliCallVerificationError, DEFAULT_API_URL, DEFAULT_STREAM_CHUNK_SIZE, MAX_CONTENT_FIELD_BYTES, MAX_STREAM_APPEND_OPERATION_COUNT, OperationBuilder, PartialStreamSubmissionError, SDK_VERSION, WarmHubClient, WarmHubError, connectionErrorMessage, contentFieldLimitError, countStreamAppendResultStatuses, isConnectionError, isRetryable, isWarmHubError, normalizeWref, resolveFunctionLogMode, sanitizeErrorMessage, sdkVersionIsBelowMinimum, streamAppendResultStatus, submitOperationsViaStream, toWarmHubError, validateAgainstShape, verifyCliCall } from './chunk-I7PLCYOF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react.js

@@ -1,5 +1,5 @@
-import { WarmHubClient } from './chunk-OPTB23HY.js';
-export { DEFAULT_API_URL, SDK_VERSION, WarmHubClient, WarmHubError, toWarmHubError } from './chunk-OPTB23HY.js';
+import { WarmHubClient } from './chunk-I7PLCYOF.js';
+export { DEFAULT_API_URL, SDK_VERSION, WarmHubClient, WarmHubError, toWarmHubError } from './chunk-I7PLCYOF.js';
 import { createContext, useMemo, useState, useEffect, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/sdk-ts",
-  "version": "0.52.1",
+  "version": "0.54.0",
   "private": false,
   "type": "module",
   "description": "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",