@warmhub/sdk-ts 0.60.0 → 0.61.0

package/dist/index.d.ts

@@ -67,48 +67,6 @@ declare const CLI_TIMESTAMP_HEADER = "X-WarmHub-Timestamp";
  */
 type CliHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 
-/**
- * Hardcoded meta-schema for validating shape definitions.
- * Shapes are NOT validated against a DB-stored shape — they validate against this constant.
- * This avoids the bootstrap chicken-and-egg problem.
- *
- * A valid shape definition is:
- * { fields: Record<string, TypeSpec>, description?: string }
- * where TypeSpec is one of:
- *   - primitive string: "number", "string", "boolean", "wref", "array"
- *   - optional primitive: "number?", "string?", "boolean?", "wref?", "array?"
- *   - typed field object: { type: primitive, description?: string }
- *   - array: [TypeSpec] (shorthand) or { type: "array", items: TypeSpec }
- *   - nested object: { fieldName: TypeSpec, ... } (key may end with "?" for optional)
- *
- * The primitive vocabulary above is closed: any other type name (e.g. "text",
- * "integer", "json", "date") is rejected. See VALID_PRIMITIVE_TYPES in
- * ./shape-types.ts for the authoritative set.
- */
-/**
- * Maximum size, in bytes (UTF-8 encoded), allowed for a single content field value.
- * WarmHub is not a document store: values larger than this are rejected at validation.
- * Store large documents in S3, Box, Drive, or another document system and reference
- * them from WarmHub instead.
- * @see https://docs.warmhub.ai/sdk-reference/variables/max_content_field_bytes/
- */
-declare const MAX_CONTENT_FIELD_BYTES: number;
-/**
- * Human-readable explanation of the {@link MAX_CONTENT_FIELD_BYTES} limit, suitable for
- * appending to a field-specific validation error. States the byte cap and points callers
- * to an external document store for large payloads.
- * @see https://docs.warmhub.ai/sdk-reference/variables/content_field_limit_error/
- */
-declare const CONTENT_FIELD_LIMIT_ERROR: string;
-/**
- * Returns a validation error message if the given string exceeds
- * {@link MAX_CONTENT_FIELD_BYTES} when UTF-8 encoded, or `null` if it is within the limit.
- *
- * @param path - The field path, used to identify the offending field in the message.
- * @param value - The candidate field value to measure.
- * @see https://docs.warmhub.ai/sdk-reference/functions/contentfieldlimiterror/
- */
-declare function contentFieldLimitError(path: string, value: string): string | null;
 /**
  * Validate a data payload against shape field definitions.
  *
@@ -166,6 +124,54 @@ type ShapeValidatorResult = {
     warnings?: UndeclaredFieldsWarning;
 };
 
+/**
+ * Hardcoded meta-schema for validating shape definitions.
+ * Shapes are NOT validated against a DB-stored shape — they validate against this constant.
+ * This avoids the bootstrap chicken-and-egg problem.
+ *
+ * A valid shape definition is:
+ * { fields: Record<string, TypeSpec>, description?: string }
+ * where TypeSpec is one of:
+ *   - primitive string: "number", "string", "boolean", "wref", "array"
+ *   - optional primitive: "number?", "string?", "boolean?", "wref?", "array?"
+ *   - typed field object: { type: primitive, description?: string }
+ *   - array: [TypeSpec] (shorthand) or { type: "array", items: TypeSpec }
+ *   - nested object: { fieldName: TypeSpec, ... } (key may end with "?" for optional)
+ *
+ * The primitive vocabulary above is closed: any other type name (e.g. "text",
+ * "integer", "json", "date") is rejected. See VALID_PRIMITIVE_TYPES in
+ * ./shape-types.ts for the authoritative set.
+ * String `pattern` constraints use RE2 syntax and are evaluated with re2js so
+ * user-authored patterns run in linear time across backend, SDK, web, CLI, and
+ * worker-adjacent consumers. JavaScript-only constructs such as backreferences
+ * and lookarounds are rejected at shape-definition time.
+ */
+
+/**
+ * Maximum size, in bytes (UTF-8 encoded), allowed for a single content field value.
+ * WarmHub is not a document store: values larger than this are rejected at validation.
+ * Store large documents in S3, Box, Drive, or another document system and reference
+ * them from WarmHub instead.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/max_content_field_bytes/
+ */
+declare const MAX_CONTENT_FIELD_BYTES: number;
+/**
+ * Human-readable explanation of the {@link MAX_CONTENT_FIELD_BYTES} limit, suitable for
+ * appending to a field-specific validation error. States the byte cap and points callers
+ * to an external document store for large payloads.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/content_field_limit_error/
+ */
+declare const CONTENT_FIELD_LIMIT_ERROR: string;
+/**
+ * Returns a validation error message if the given string exceeds
+ * {@link MAX_CONTENT_FIELD_BYTES} when UTF-8 encoded, or `null` if it is within the limit.
+ *
+ * @param path - The field path, used to identify the offending field in the message.
+ * @param value - The candidate field value to measure.
+ * @see https://docs.warmhub.ai/sdk-reference/functions/contentfieldlimiterror/
+ */
+declare function contentFieldLimitError(path: string, value: string): string | null;
+
 type ActionAttempt = {
     attempt: number;
     status: string;
@@ -1096,10 +1102,6 @@ type SubmittedStreamResult = {
         warnings?: NonNullable<StreamAppendResult$1['results'][number]['warnings']>;
     }>;
 };
-/** @internal */
-declare function streamAppendResultStatus(result: StreamAppendResult$1['results'][number]): NonNullable<SubmittedStreamResult['operations'][number]['status']>;
-/** @internal */
-declare function countStreamAppendResultStatuses(results: StreamAppendResult$1['results']): NonNullable<SubmittedStreamResult['statusCounts']>;
 /**
  * Continuation state for caller-managed streamed commit submissions.
  * @see https://docs.warmhub.ai/sdk-reference/type-aliases/streamcontinuationstate/
@@ -1173,6 +1175,7 @@ declare class AllStreamOperationsFailedError extends Error {
     readonly cause?: StreamFailureCause;
     constructor(result: SubmittedStreamResult);
 }
+
 /**
  * Submit `operations` to the WarmHub stream-append surface, chunked to
  * stay under MAX_STREAM_APPEND_OPERATION_COUNT.
@@ -1268,6 +1271,15 @@ declare function submitOperationsViaStream(client: OperationStreamClient, args:
     retry?: RetryPolicyOptions | false;
 }): Promise<SubmittedStreamResult>;
 
+/**
+ * Exposed for unit tests and internal callers to avoid re-deriving status values.
+ *
+ * @internal
+ */
+declare function streamAppendResultStatus(result: StreamAppendResult$1['results'][number]): NonNullable<SubmittedStreamResult['operations'][number]['status']>;
+/** @internal */
+declare function countStreamAppendResultStatuses(results: StreamAppendResult$1['results']): NonNullable<SubmittedStreamResult['statusCounts']>;
+
 /**
  * Server-side verifier for component CLI dispatch calls.
  *
@@ -1286,7 +1298,8 @@ declare function submitOperationsViaStream(client: OperationStreamClient, args:
  *
  * Multiple schemes can be configured at once; in that case the verifier
  * requires ALL of them to validate (downgrade-attack defense — an attacker
- * who learns only one credential can't drop the other from the request).
+ * who learns only one credential can't drop the other from the request). Bearer
+ * and Basic both use `Authorization`, so they cannot be configured together.
  * If none are configured, the call is rejected as misconfigured.
  *
  *   import { verifyCliCall } from '@warmhub/sdk-ts'
@@ -1372,34 +1385,23 @@ declare function verifyCliCall(request: Request, secrets: CliCallSecrets, opts?:
 type ShapeFields = Record<string, unknown>;
 
 /**
- * Builder add operation for shapes, things, assertions, and collections.
- * @see https://docs.warmhub.ai/sdk-reference/interfaces/addop/
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/collectionaddtype/
  */
-interface AddOp {
+type CollectionAddType = CollectionTag$1;
+type NonCollectionAddKind = Exclude<CommitOperationKind, 'collection'>;
+interface BaseAddOp {
     /**
      * Operation discriminator. Always `add`.
      */
     readonly operation: 'add';
     /**
-     * Target name. Use `Shape/localName` for things and assertions; use the plain shape name for shapes.
-     */
-    readonly name: string;
-    /**
-     * Optional kind override: `shape`, `thing`, `assertion`, or `collection`.
+     * Optional kind override: `shape`, `thing`, or `assertion`.
      */
-    readonly kind?: string;
+    readonly kind?: NonCollectionAddKind;
     /**
-     * Assertion target wref or inline collection descriptor. Presence of `about` makes the add an assertion unless `kind` overrides it.
+     * Assertion target wref. Presence of `about` makes the add an assertion unless `kind` overrides it.
      */
     readonly about?: string | CollectionAbout$2;
-    /**
-     * Collection type. Used only for collection adds.
-     */
-    readonly type?: string;
-    /**
-     * Collection member wrefs. Used only for collection adds.
-     */
-    readonly members?: string[];
     /**
      * Optional shape wref used by local validation.
      */
@@ -1417,6 +1419,54 @@ interface AddOp {
      */
     readonly skipExisting?: boolean;
 }
+/**
+ * Builder add operation for shapes, things, and assertions.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/addop/
+ */
+interface AddOp extends BaseAddOp {
+    /**
+     * Target name. Use `Shape/localName` for things and assertions; use the plain shape name for shapes.
+     */
+    readonly name: string;
+}
+/**
+ * Builder collection add operation. Omitting `name` creates the backend's
+ * canonical auto-named collection from the supplied members.
+ * @see https://docs.warmhub.ai/sdk-reference/interfaces/collectionaddop/
+ */
+interface CollectionAddOp {
+    /**
+     * Operation discriminator. Always `add`.
+     */
+    readonly operation: 'add';
+    /**
+     * Optional kind override. Collection add inputs may omit this when `type` and
+     * `members` are present.
+     */
+    readonly kind?: 'collection';
+    /**
+     * Optional collection name. Omit to let the backend assign the canonical
+     * collection name from the supplied members.
+     */
+    readonly name?: string;
+    /**
+     * Collection type.
+     */
+    readonly type: CollectionAddType;
+    /**
+     * Collection member wrefs.
+     */
+    readonly members: string[];
+    /**
+     * When true, an existing target returns `noop` instead of failing.
+     */
+    readonly skipExisting?: boolean;
+}
+/**
+ * Input accepted by `OperationBuilder.add`.
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/operationbuilderaddinput/
+ */
+type OperationBuilderAddInput = Omit<AddOp, 'operation'> | AddOp | Omit<CollectionAddOp, 'operation'> | CollectionAddOp;
 /**
  * Builder revise operation.
  * @see https://docs.warmhub.ai/sdk-reference/interfaces/reviseop/
@@ -1490,7 +1540,7 @@ interface RetractOp {
  * Operation queued by `OperationBuilder`.
  * @see https://docs.warmhub.ai/sdk-reference/type-aliases/operationbuilderop/
  */
-type OperationBuilderOp = AddOp | ReviseOp | RetractOp;
+type OperationBuilderOp = AddOp | CollectionAddOp | ReviseOp | RetractOp;
 type OperationSubmitResult$1 = SubmittedStreamResult;
 /**
  * Client-side validation diagnostic returned by `OperationBuilder.validate`.
@@ -1540,7 +1590,7 @@ interface OperationBuilderOptions {
 }
 /** @internal */
 type OperationBuilderClient = OperationStreamClient;
-type AddInput = Omit<AddOp, 'operation'> | AddOp;
+
 type ReviseInput = Omit<ReviseOp, 'operation'> | ReviseOp;
 /**
  * Fluent builder for composing, validating, and submitting WarmHub commit
@@ -1587,7 +1637,7 @@ declare class OperationBuilder {
      * Set `kind: 'thing'` explicitly for hierarchical thing names that would otherwise look like assertion paths.
      * @see https://docs.warmhub.ai/sdk-reference/classes/operationbuilder/#add
      */
-    add(op: AddInput): this;
+    add(op: OperationBuilderAddInput): this;
     /**
      * Add a revise operation.
      *
@@ -1725,6 +1775,18 @@ interface WarmHubClientOptions {
      * Control replay of backend function log lines. Defaults to `off`.
      */
     functionLogs?: FunctionLogMode;
+    /**
+     * Self-identification sent on the `X-WarmHub-Client` header (`name/version`)
+     * for backend observability + read-analytics surface attribution. Defaults to
+     * `@warmhub/sdk-ts/<SDK_VERSION>`. A wrapper such as the WarmHub CLI overrides
+     * `name` (and usually `version`) to identify itself instead. An untrusted
+     * hint — never an authz signal. A per-request `X-WarmHub-Client` header on a
+     * raw request still wins over this default.
+     */
+    client?: {
+        name?: string;
+        version?: string;
+    };
 }
 /**
  * Version string for the installed SDK package.
@@ -1801,7 +1863,7 @@ type CoreErrorKind = 'BACKEND' | 'NOT_FOUND' | 'FORBIDDEN' | 'UNAUTHENTICATED' |
  * - `NOT_FOUND` — cause: a referenced entity (repo, org, thing, shape, subscription, credential set, etc.) is missing or the caller cannot see it; retryable: false; action: verify the identifier the call site used (wref, slug, name) and escalate to a caller with read access if the entity should exist; origin: SDK reads across all surfaces, commit pipeline, REST query endpoints
  * - `FORBIDDEN` — cause: caller is authenticated but lacks the required permission; retryable: false; action: request the missing permission or use a token with broader scope; origin: SDK + REST authorization middleware
  * - `UNAUTHENTICATED` — cause: missing, expired, or invalid bearer token on a tRPC or REST call; retryable: false; action: mint a fresh PAT and update whichever client option the application wires it into (`auth.getToken` callback or `accessToken` — the SDK does not read `WH_TOKEN` or any env var directly); `wh auth login` only refreshes the CLI's on-disk credentials and does not propagate to a constructed SDK client; for export tickets, remint via the appropriate backend endpoint; origin: SDK + REST auth middleware. Live-ticket SSE auth failures surface as `BACKEND`, not `UNAUTHENTICATED`, because `openSse` maps every non-OK SSE response to `BACKEND`.
- * - `VALIDATION_ERROR` — cause: input failed schema, shape, or content-length validation; retryable: false; action: fix the offending field per the error message; origin: commit pipeline, SDK writes, client-side content limits
+ * - `VALIDATION_ERROR` — cause: input failed schema, shape, content-length, or read-pagination cursor validation; retryable: false; action: fix the offending field per the error message, or restart the read without a stale/non-advancing cursor; origin: commit pipeline, SDK writes, SDK read pagination helpers, client-side content limits
  * - `CONFLICT` — cause: write collides with current state (concurrent edit, name already in use); retryable: false; action: refetch the current state and reconcile before retrying the write; origin: commit pipeline, repo/org creation. Archived org / repo writes surface as the pass-through code `ARCHIVED`, not `CONFLICT`.
  * - `RATE_LIMITED` — cause: caller exceeded the per-token or per-org request budget; retryable: true; action: wait {@link WarmHubError.retryAfter} seconds before retrying; origin: REST + tRPC throttling
  * - `CANCELLED` — cause: caller aborted the request via `AbortSignal`; retryable: true; action: retry only if the caller still wants the result; origin: SDK `AbortError` mapping
@@ -3004,6 +3066,8 @@ declare class WarmHubClient {
     readonly apiUrl: string;
     private readonly fetchImpl;
     private readonly accessToken;
+    /** Resolved `X-WarmHub-Client` identity; defaults to this SDK's name/version. */
+    private readonly clientIdentity;
     protected readonly functionLogMode: FunctionLogMode;
     protected readonly getToken?: () => Promise<string | undefined>;
     private readonly trpc;
@@ -3433,12 +3497,6 @@ declare class WarmHubClient {
         delete: (orgName: string, repoName: string) => Promise<{
             graceExpiresAt: Date;
         }>;
-        /**
-         * Immediately and irreversibly purge a repository.
-         *
-         * This owner-only operation has no grace window and uses the same inbound-reference guard as `delete`.
-         */
-        hardDelete: (orgName: string, repoName: string) => Promise<void>;
         /**
          * List repositories with dashboard-oriented per-repository metadata.
          *
@@ -4304,10 +4362,15 @@ declare class WarmHubClient {
         listNotifications: (orgName: string, repoName: string, opts?: ActionListNotificationsOptions) => Promise<ActionNotificationInfo[]>;
     };
     private openSse;
+    /**
+     * Stamp the `X-WarmHub-Client` self-identification header, unless the caller
+     * already set it on the request (a per-request header wins over the default).
+     */
+    private applyClientHeader;
     private fetchWithAuth;
     private requestResponse;
     private requestJson;
     private watchRepoQuery;
 }
 
-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 ComponentInstallResult, type ComponentList, type ComponentListOptions, type ComponentUninstallResult, 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 RenameOperation, 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 };
+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 CollectionAddOp, type CollectionAddType, type CollectionTag, type ComponentInfo, type ComponentInstallResult, type ComponentList, type ComponentListOptions, type ComponentUninstallResult, 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 OperationBuilderAddInput, 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 RenameOperation, 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-E4ZCBSQZ.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-QS6ABKPJ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react.d.ts

@@ -12,13 +12,23 @@ interface WarmHubProviderProps {
         isLoading: boolean;
         getAccessToken: () => Promise<string | null>;
     };
+    /**
+     * Self-identification forwarded to the `X-WarmHub-Client` header. First-party
+     * apps set `name` (e.g. `warmhub-web`) so backend observability can tell them
+     * apart from raw SDK consumers; an omitted `version` falls through to the SDK
+     * version. See `WarmHubClientOptions.client`.
+     */
+    client?: {
+        name?: string;
+        version?: string;
+    };
 }
 interface WarmHubAuthState {
     isAuthenticated: boolean;
     isLoading: boolean;
 }
 /** @internal */
-declare function WarmHubProvider({ apiUrl, children, auth, }: WarmHubProviderProps): react_jsx_runtime.JSX.Element;
+declare function WarmHubProvider({ apiUrl, children, auth, client: clientIdentity, }: WarmHubProviderProps): react_jsx_runtime.JSX.Element;
 /** @internal */
 declare function useWarmHubClient(): WarmHubClient;
 /** @internal */

package/dist/react.js

@@ -1,5 +1,5 @@
-import { WarmHubClient } from './chunk-E4ZCBSQZ.js';
-export { DEFAULT_API_URL, SDK_VERSION, WarmHubClient, WarmHubError, toWarmHubError } from './chunk-E4ZCBSQZ.js';
+import { WarmHubClient } from './chunk-QS6ABKPJ.js';
+export { DEFAULT_API_URL, SDK_VERSION, WarmHubClient, WarmHubError, toWarmHubError } from './chunk-QS6ABKPJ.js';
 import { createContext, useMemo, useState, useEffect, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
@@ -11,17 +11,21 @@ var AuthContext = createContext({
 function WarmHubProvider({
   apiUrl,
   children,
-  auth
+  auth,
+  client: clientIdentity
 }) {
+  const clientName = clientIdentity?.name;
+  const clientVersion = clientIdentity?.version;
   const client = useMemo(
     () => new WarmHubClient({
       apiUrl,
       accessToken: async () => {
         const token = await auth.getAccessToken();
         return token ?? void 0;
-      }
+      },
+      client: { name: clientName, version: clientVersion }
     }),
-    [apiUrl, auth.getAccessToken]
+    [apiUrl, auth.getAccessToken, clientName, clientVersion]
   );
   return /* @__PURE__ */ jsx(ClientContext.Provider, { value: client, children: /* @__PURE__ */ jsx(AuthSyncGate, { auth, client, children }) });
 }

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react/provider.tsx"],"names":[],"mappings":";;;;;AA0BA,IAAM,aAAA,GAAgB,cAAoC,IAAI,CAAA;AAC9D,IAAM,cAAc,aAAA,CAAgC;AAAA,EAClD,eAAA,EAAiB,KAAA;AAAA,EACjB,SAAA,EAAW;AACb,CAAC,CAAA;AAGM,SAAS,eAAA,CAAgB;AAAA,EAC9B,MAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF,CAAA,EAAyB;AACvB,EAAA,MAAM,MAAA,GAAS,OAAA;AAAA,IACb,MACE,IAAI,aAAA,CAAc;AAAA,MAChB,MAAA;AAAA,MACA,aAAa,YAAY;AACvB,QAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,cAAA,EAAe;AACxC,QAAA,OAAO,KAAA,IAAS,MAAA;AAAA,MAClB;AAAA,KACD,CAAA;AAAA,IACH,CAAC,MAAA,EAAQ,IAAA,CAAK,cAAc;AAAA,GAC9B;AAEA,EAAA,uBACE,GAAA,CAAC,aAAA,CAAc,QAAA,EAAd,EAAuB,KAAA,EAAO,MAAA,EAC7B,QAAA,kBAAA,GAAA,CAAC,YAAA,EAAA,EAAa,IAAA,EAAY,MAAA,EACvB,QAAA,EACH,CAAA,EACF,CAAA;AAEJ;AAEA,SAAS,YAAA,CAAa;AAAA,EACpB,IAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,EAIG;AACD,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,SAAS,KAAK,CAAA;AAE1C,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,CAAC,KAAK,eAAA,EAAiB;AACzB,MAAA,SAAA,CAAU,KAAK,CAAA;AACf,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,SAAA,GAAY,KAAA;AAChB,IAAA,MAAA,CAAO,IAAA,CACJ,IAAA,EAAK,CACL,IAAA,CAAK,MAAM;AACV,MAAA,IAAI,CAAC,SAAA,EAAW,SAAA,CAAU,IAAI,CAAA;AAAA,IAChC,CAAC,CAAA,CACA,KAAA,CAAM,CAAC,GAAA,KAAQ;AACd,MAAA,OAAA,CAAQ,KAAA,CAAM,qBAAqB,GAAG,CAAA;AACtC,MAAA,IAAI,CAAC,SAAA,EAAW,SAAA,CAAU,IAAI,CAAA;AAAA,IAChC,CAAC,CAAA;AACH,IAAA,OAAO,MAAM;AACX,MAAA,SAAA,GAAY,IAAA;AAAA,IACd,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,IAAA,CAAK,eAAA,EAAiB,MAAM,CAAC,CAAA;AAEjC,EAAA,MAAM,SAAA,GAAY,OAAA;AAAA,IAChB,OAAO;AAAA,MACL,eAAA,EAAiB,KAAK,eAAA,IAAmB,MAAA;AAAA,MACzC,SAAA,EAAW,IAAA,CAAK,SAAA,IAAc,IAAA,CAAK,mBAAmB,CAAC;AAAA,KACzD,CAAA;AAAA,IACA,CAAC,IAAA,CAAK,eAAA,EAAiB,IAAA,CAAK,WAAW,MAAM;AAAA,GAC/C;AAGA,EAAA,IAAI,IAAA,CAAK,SAAA,IAAc,IAAA,CAAK,eAAA,IAAmB,CAAC,MAAA,EAAS;AACvD,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,2BACG,WAAA,CAAY,QAAA,EAAZ,EAAqB,KAAA,EAAO,WAAY,QAAA,EAAS,CAAA;AAEtD;AAGO,SAAS,gBAAA,GAAkC;AAChD,EAAA,MAAM,MAAA,GAAS,WAAW,aAAa,CAAA;AACvC,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,MAAM,wDAAwD,CAAA;AAAA,EAC1E;AACA,EAAA,OAAO,MAAA;AACT;AAGO,SAAS,cAAA,GAAmC;AACjD,EAAA,OAAO,WAAW,WAAW,CAAA;AAC/B","file":"react.js"}
+{"version":3,"sources":["../src/react/provider.tsx"],"names":[],"mappings":";;;;;AAiCA,IAAM,aAAA,GAAgB,cAAoC,IAAI,CAAA;AAC9D,IAAM,cAAc,aAAA,CAAgC;AAAA,EAClD,eAAA,EAAiB,KAAA;AAAA,EACjB,SAAA,EAAW;AACb,CAAC,CAAA;AAGM,SAAS,eAAA,CAAgB;AAAA,EAC9B,MAAA;AAAA,EACA,QAAA;AAAA,EACA,IAAA;AAAA,EACA,MAAA,EAAQ;AACV,CAAA,EAAyB;AAKvB,EAAA,MAAM,aAAa,cAAA,EAAgB,IAAA;AACnC,EAAA,MAAM,gBAAgB,cAAA,EAAgB,OAAA;AACtC,EAAA,MAAM,MAAA,GAAS,OAAA;AAAA,IACb,MACE,IAAI,aAAA,CAAc;AAAA,MAChB,MAAA;AAAA,MACA,aAAa,YAAY;AACvB,QAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,CAAK,cAAA,EAAe;AACxC,QAAA,OAAO,KAAA,IAAS,MAAA;AAAA,MAClB,CAAA;AAAA,MACA,MAAA,EAAQ,EAAE,IAAA,EAAM,UAAA,EAAY,SAAS,aAAA;AAAc,KACpD,CAAA;AAAA,IACH,CAAC,MAAA,EAAQ,IAAA,CAAK,cAAA,EAAgB,YAAY,aAAa;AAAA,GACzD;AAEA,EAAA,uBACE,GAAA,CAAC,aAAA,CAAc,QAAA,EAAd,EAAuB,KAAA,EAAO,MAAA,EAC7B,QAAA,kBAAA,GAAA,CAAC,YAAA,EAAA,EAAa,IAAA,EAAY,MAAA,EACvB,QAAA,EACH,CAAA,EACF,CAAA;AAEJ;AAEA,SAAS,YAAA,CAAa;AAAA,EACpB,IAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,EAIG;AACD,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,SAAS,KAAK,CAAA;AAE1C,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,CAAC,KAAK,eAAA,EAAiB;AACzB,MAAA,SAAA,CAAU,KAAK,CAAA;AACf,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,SAAA,GAAY,KAAA;AAChB,IAAA,MAAA,CAAO,IAAA,CACJ,IAAA,EAAK,CACL,IAAA,CAAK,MAAM;AACV,MAAA,IAAI,CAAC,SAAA,EAAW,SAAA,CAAU,IAAI,CAAA;AAAA,IAChC,CAAC,CAAA,CACA,KAAA,CAAM,CAAC,GAAA,KAAQ;AACd,MAAA,OAAA,CAAQ,KAAA,CAAM,qBAAqB,GAAG,CAAA;AACtC,MAAA,IAAI,CAAC,SAAA,EAAW,SAAA,CAAU,IAAI,CAAA;AAAA,IAChC,CAAC,CAAA;AACH,IAAA,OAAO,MAAM;AACX,MAAA,SAAA,GAAY,IAAA;AAAA,IACd,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,IAAA,CAAK,eAAA,EAAiB,MAAM,CAAC,CAAA;AAEjC,EAAA,MAAM,SAAA,GAAY,OAAA;AAAA,IAChB,OAAO;AAAA,MACL,eAAA,EAAiB,KAAK,eAAA,IAAmB,MAAA;AAAA,MACzC,SAAA,EAAW,IAAA,CAAK,SAAA,IAAc,IAAA,CAAK,mBAAmB,CAAC;AAAA,KACzD,CAAA;AAAA,IACA,CAAC,IAAA,CAAK,eAAA,EAAiB,IAAA,CAAK,WAAW,MAAM;AAAA,GAC/C;AAGA,EAAA,IAAI,IAAA,CAAK,SAAA,IAAc,IAAA,CAAK,eAAA,IAAmB,CAAC,MAAA,EAAS;AACvD,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,2BACG,WAAA,CAAY,QAAA,EAAZ,EAAqB,KAAA,EAAO,WAAY,QAAA,EAAS,CAAA;AAEtD;AAGO,SAAS,gBAAA,GAAkC;AAChD,EAAA,MAAM,MAAA,GAAS,WAAW,aAAa,CAAA;AACvC,EAAA,IAAI,CAAC,MAAA,EAAQ;AACX,IAAA,MAAM,IAAI,MAAM,wDAAwD,CAAA;AAAA,EAC1E;AACA,EAAA,OAAO,MAAA;AACT;AAGO,SAAS,cAAA,GAAmC;AACjD,EAAA,OAAO,WAAW,WAAW,CAAA;AAC/B","file":"react.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/sdk-ts",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "private": false,
   "type": "module",
   "description": "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -86,13 +86,13 @@
     "@trpc/client": "11.17.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "4.1.5",
-    "@types/react": "19.2.14",
+    "@vitest/coverage-v8": "catalog:",
+    "@types/react": "catalog:",
     "react": "19.2.6",
     "tsup": "8.5.1",
     "typedoc": "0.28.19",
     "typedoc-plugin-markdown": "4.11.0",
-    "typescript": "5.9.3",
-    "vitest": "4.1.5"
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   }
 }