@warmhub/sdk-ts 0.57.0 → 0.59.0

package/dist/index.d.ts

@@ -1,3 +1,171 @@
+declare const COMMIT_OPERATIONS: readonly ["add", "revise", "retract"];
+type CommitOperation = (typeof COMMIT_OPERATIONS)[number];
+declare const COMMIT_OPERATION_KINDS: readonly ["shape", "thing", "assertion", "collection"];
+type CommitOperationKind = (typeof COMMIT_OPERATION_KINDS)[number];
+type CollectionAbout$2 = {
+    pair: [string, string];
+} | {
+    triple: [string, string, string];
+} | {
+    set: string[];
+} | {
+    list: string[];
+};
+
+/**
+ * Canonical request signing for component CLI dispatch.
+ *
+ * Component workers expose CLI methods over HTTP. The platform dispatcher
+ * signs each call with HMAC-SHA256 over a canonical request representation
+ * so the worker can authenticate the caller without sharing more than a
+ * single secret. The same canonical input works for GET and POST methods:
+ * the difference is whether the method args ride in the query string or
+ * the body.
+ *
+ *   Canonical signing input:
+ *     <METHOD>\n<PATH>\n<CANONICAL_QUERY>\n<INSTALL_REPO>\n<SHA256_HEX(BODY)>\n<TIMESTAMP>
+ *
+ * Where:
+ *   - METHOD is the uppercased HTTP method ('GET' | 'POST').
+ *   - PATH is the URL path component (no scheme, host, or query).
+ *   - CANONICAL_QUERY is `canonicalCliQueryString(query)` — sorted, RFC 3986
+ *     percent-encoded, omitting undefined / null entries.
+ *   - INSTALL_REPO is the `<org>/<repo>` slug of the install, transmitted on
+ *     the wire as the `X-WarmHub-Install-Repo` header.
+ *   - BODY is the raw request body string ('' for GET).
+ *   - TIMESTAMP is unix-seconds since epoch (string-formatted).
+ *
+ * Verifiers should enforce a tolerance window on the timestamp to bound
+ * replay attacks (default 300 s); they should also compare signatures in
+ * constant time.
+ *
+ * This module is intentionally low-level: component authors import the
+ * higher-level `verifyCliCall(request, secret)` wrapper from
+ * `@warmhub/sdk-ts`, which extracts the canonical inputs from a Fetch
+ * `Request` and calls `verifyCliRequest` for them.
+ */
+/**
+ * Wire header names for component CLI dispatch — the single source of truth
+ * shared by the backend dispatcher (which sets them) and `verifyCliCall` (which
+ * reads them). The install repo always rides in {@link CLI_INSTALL_REPO_HEADER};
+ * the signing scheme adds {@link CLI_SIGNATURE_HEADER} + {@link CLI_TIMESTAMP_HEADER}.
+ * @see https://docs.warmhub.ai/sdk-reference/variables/cli_install_repo_header/
+ */
+declare const CLI_INSTALL_REPO_HEADER = "X-WarmHub-Install-Repo";
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/variables/cli_signature_header/
+ */
+declare const CLI_SIGNATURE_HEADER = "X-WarmHub-Signature";
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/variables/cli_timestamp_header/
+ */
+declare const CLI_TIMESTAMP_HEADER = "X-WarmHub-Timestamp";
+/**
+ * HTTP verbs a component CLI method can declare. No-body verbs (GET, DELETE)
+ * carry args in the query string; body verbs (POST, PUT, PATCH) carry args in
+ * the JSON body.
+ */
+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.
+ *
+ * Shape field types:
+ * - "number", "string", "boolean": primitive types
+ * - "wref": string (reference to another thing)
+ * - Typed field objects: { type: primitive, description?: string }
+ * - Nested objects: { fieldName: type, ... }
+ * - Arrays: [elementType]
+ * - Optional fields: field name ending with "?" (e.g. "terminal_reason?": "string")
+ *   OR type string ending with "?" (e.g. "terminal_reason": "string?")
+ *   OR typed object type ending with "?" (e.g. { type: "string?" })
+ *
+ * For v1 this is permissive: validates top-level field existence and basic types.
+ * Returns a {@link ShapeValidatorResult} discriminated union — read `result.valid`
+ * to branch, then `result.errors` (only present when invalid) for the list of
+ * messages. `result.warnings` may be present in either branch and carries
+ * undeclared top-level field names.
+ *
+ * @example
+ * ```ts
+ * import { validateAgainstShape } from "@warmhub/sdk-ts";
+ *
+ * const shapeFields = { x: "number", y: "number", label: "string?" };
+ *
+ * const ok = validateAgainstShape({ x: 1, y: 2 }, shapeFields);
+ * // ok.valid === true
+ *
+ * const bad = validateAgainstShape({ x: "not-a-number" }, shapeFields);
+ * if (!bad.valid) {
+ *   for (const message of bad.errors) console.error(message);
+ *   // ['Field "x" must be a number', 'Missing required field: "y"']
+ * }
+ * ```
+ * @see https://docs.warmhub.ai/sdk-reference/functions/validateagainstshape/
+ */
+declare function validateAgainstShape(data: Record<string, unknown>, shapeFields: Record<string, unknown>): ShapeValidatorResult;
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/undeclaredfieldswarning/
+ */
+type UndeclaredFieldsWarning = {
+    undeclaredFields: string[];
+    undeclaredFieldsTruncated?: true;
+    totalUndeclared?: number;
+};
+/**
+ * @see https://docs.warmhub.ai/sdk-reference/type-aliases/shapevalidatorresult/
+ */
+type ShapeValidatorResult = {
+    valid: true;
+    warnings?: UndeclaredFieldsWarning;
+} | {
+    valid: false;
+    errors: string[];
+    warnings?: UndeclaredFieldsWarning;
+};
+
 type ActionAttempt = {
     attempt: number;
     status: string;
@@ -88,7 +256,7 @@ type AccessResolveResult$1 = {
         orgName: string;
         repoName: string;
         visible: boolean;
-        scopes: Array<'repo:read' | 'repo:write' | 'repo:configure' | 'repo:admin'>;
+        scopes: Array<'repo:read' | 'repo:write' | 'repo:configure' | 'repo:admin' | 'repo:action-callback'>;
         allowedMatches?: Array<string>;
     }>;
     orgs: Array<{
@@ -100,7 +268,7 @@ type AccessResolveResult$1 = {
 type AuthSyncResult = {
     success: boolean;
 };
-type CollectionAbout$2 = {
+type CollectionAbout$1 = {
     pair: [string, string];
 } | {
     triple: [string, string, string];
@@ -333,7 +501,7 @@ type StreamAppendInput$1 = {
     } | {
         operation: 'retract';
         name: string;
-        kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+        kind?: 'shape' | 'thing' | 'assertion' | 'collection';
         reason?: string;
         leaseId?: string;
     }>;
@@ -691,7 +859,7 @@ interface AddOperation {
      * (1–2 segments → thing, 3+ segments → assertion). Shape adds always
      * require explicit `kind: 'shape'`.
      */
-    kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+    kind?: CommitOperationKind;
     /**
      * Target name. Use `Shape/localName` for things and assertions; use the
      * plain shape name for shapes.
@@ -701,7 +869,7 @@ interface AddOperation {
      * Assertion target wref or inline collection descriptor. Presence of
      * `about` makes the add an assertion unless `kind` overrides it.
      */
-    about?: string | CollectionAbout$2;
+    about?: string | CollectionAbout$1;
     /**
      * Shape-validated data payload for shape, thing, or assertion adds.
      */
@@ -741,7 +909,7 @@ interface ReviseOperation {
     /**
      * Optional kind safety hint: `shape`, `thing`, `assertion`, or `collection`.
      */
-    kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+    kind?: CommitOperationKind;
     /**
      * Target name to revise. Equivalent to `wref` for local paths.
      */
@@ -792,7 +960,7 @@ interface RetractOperation {
     /**
      * Optional kind safety hint: `thing`, `assertion`, `shape`, or `collection`.
      */
-    kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+    kind?: CommitOperationKind;
     /**
      * Optional human-readable retraction reason.
      */
@@ -849,6 +1017,7 @@ declare const DEFAULT_STREAM_CHUNK_SIZE = 1000;
  * @internal
  */
 declare const MAX_STREAM_APPEND_OPERATION_COUNT = 10000;
+type CommitResultOperation$1 = CommitOperation | 'noop';
 interface OperationStreamClient {
     stream: {
         append(input: StreamAppendInput$1): Promise<StreamAppendResult$1>;
@@ -868,7 +1037,7 @@ type SubmittedStreamResult = {
     operations: Array<{
         opIndex?: number;
         name: string;
-        operation: 'add' | 'revise' | 'retract' | 'noop';
+        operation: CommitResultOperation$1;
         dataHash: string;
         version: number;
         status?: 'applied' | 'noop' | 'error';
@@ -1060,170 +1229,6 @@ declare function submitOperationsViaStream(client: OperationStreamClient, args:
     retry?: RetryPolicyOptions | false;
 }): Promise<SubmittedStreamResult>;
 
-type CollectionAbout$1 = {
-    pair: [string, string];
-} | {
-    triple: [string, string, string];
-} | {
-    set: string[];
-} | {
-    list: string[];
-};
-
-/**
- * Canonical request signing for component CLI dispatch.
- *
- * Component workers expose CLI methods over HTTP. The platform dispatcher
- * signs each call with HMAC-SHA256 over a canonical request representation
- * so the worker can authenticate the caller without sharing more than a
- * single secret. The same canonical input works for GET and POST methods:
- * the difference is whether the method args ride in the query string or
- * the body.
- *
- *   Canonical signing input:
- *     <METHOD>\n<PATH>\n<CANONICAL_QUERY>\n<INSTALL_REPO>\n<SHA256_HEX(BODY)>\n<TIMESTAMP>
- *
- * Where:
- *   - METHOD is the uppercased HTTP method ('GET' | 'POST').
- *   - PATH is the URL path component (no scheme, host, or query).
- *   - CANONICAL_QUERY is `canonicalCliQueryString(query)` — sorted, RFC 3986
- *     percent-encoded, omitting undefined / null entries.
- *   - INSTALL_REPO is the `<org>/<repo>` slug of the install, transmitted on
- *     the wire as the `X-WarmHub-Install-Repo` header.
- *   - BODY is the raw request body string ('' for GET).
- *   - TIMESTAMP is unix-seconds since epoch (string-formatted).
- *
- * Verifiers should enforce a tolerance window on the timestamp to bound
- * replay attacks (default 300 s); they should also compare signatures in
- * constant time.
- *
- * This module is intentionally low-level: component authors import the
- * higher-level `verifyCliCall(request, secret)` wrapper from
- * `@warmhub/sdk-ts`, which extracts the canonical inputs from a Fetch
- * `Request` and calls `verifyCliRequest` for them.
- */
-/**
- * Wire header names for component CLI dispatch — the single source of truth
- * shared by the backend dispatcher (which sets them) and `verifyCliCall` (which
- * reads them). The install repo always rides in {@link CLI_INSTALL_REPO_HEADER};
- * the signing scheme adds {@link CLI_SIGNATURE_HEADER} + {@link CLI_TIMESTAMP_HEADER}.
- * @see https://docs.warmhub.ai/sdk-reference/variables/cli_install_repo_header/
- */
-declare const CLI_INSTALL_REPO_HEADER = "X-WarmHub-Install-Repo";
-/**
- * @see https://docs.warmhub.ai/sdk-reference/variables/cli_signature_header/
- */
-declare const CLI_SIGNATURE_HEADER = "X-WarmHub-Signature";
-/**
- * @see https://docs.warmhub.ai/sdk-reference/variables/cli_timestamp_header/
- */
-declare const CLI_TIMESTAMP_HEADER = "X-WarmHub-Timestamp";
-/**
- * HTTP verbs a component CLI method can declare. No-body verbs (GET, DELETE)
- * carry args in the query string; body verbs (POST, PUT, PATCH) carry args in
- * the JSON body.
- */
-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.
- *
- * Shape field types:
- * - "number", "string", "boolean": primitive types
- * - "wref": string (reference to another thing)
- * - Typed field objects: { type: primitive, description?: string }
- * - Nested objects: { fieldName: type, ... }
- * - Arrays: [elementType]
- * - Optional fields: field name ending with "?" (e.g. "terminal_reason?": "string")
- *   OR type string ending with "?" (e.g. "terminal_reason": "string?")
- *   OR typed object type ending with "?" (e.g. { type: "string?" })
- *
- * For v1 this is permissive: validates top-level field existence and basic types.
- * Returns a {@link ShapeValidatorResult} discriminated union — read `result.valid`
- * to branch, then `result.errors` (only present when invalid) for the list of
- * messages. `result.warnings` may be present in either branch and carries
- * undeclared top-level field names.
- *
- * @example
- * ```ts
- * import { validateAgainstShape } from "@warmhub/sdk-ts";
- *
- * const shapeFields = { x: "number", y: "number", label: "string?" };
- *
- * const ok = validateAgainstShape({ x: 1, y: 2 }, shapeFields);
- * // ok.valid === true
- *
- * const bad = validateAgainstShape({ x: "not-a-number" }, shapeFields);
- * if (!bad.valid) {
- *   for (const message of bad.errors) console.error(message);
- *   // ['Field "x" must be a number', 'Missing required field: "y"']
- * }
- * ```
- * @see https://docs.warmhub.ai/sdk-reference/functions/validateagainstshape/
- */
-declare function validateAgainstShape(data: Record<string, unknown>, shapeFields: Record<string, unknown>): ShapeValidatorResult;
-/**
- * @see https://docs.warmhub.ai/sdk-reference/type-aliases/undeclaredfieldswarning/
- */
-type UndeclaredFieldsWarning = {
-    undeclaredFields: string[];
-    undeclaredFieldsTruncated?: true;
-    totalUndeclared?: number;
-};
-/**
- * @see https://docs.warmhub.ai/sdk-reference/type-aliases/shapevalidatorresult/
- */
-type ShapeValidatorResult = {
-    valid: true;
-    warnings?: UndeclaredFieldsWarning;
-} | {
-    valid: false;
-    errors: string[];
-    warnings?: UndeclaredFieldsWarning;
-};
-
 /**
  * Server-side verifier for component CLI dispatch calls.
  *
@@ -1347,7 +1352,7 @@ interface AddOp {
     /**
      * Assertion target wref or inline collection descriptor. Presence of `about` makes the add an assertion unless `kind` overrides it.
      */
-    readonly about?: string | CollectionAbout$1;
+    readonly about?: string | CollectionAbout$2;
     /**
      * Collection type. Used only for collection adds.
      */
@@ -1429,7 +1434,7 @@ interface RetractOp {
     /**
      * Optional kind safety hint: `thing`, `assertion`, `shape`, or `collection`.
      */
-    readonly kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+    readonly kind?: CommitOperationKind;
     /**
      * Optional human-readable retraction reason.
      */
@@ -1559,7 +1564,7 @@ declare class OperationBuilder {
      */
     retract(target: string | {
         name: string;
-        kind?: 'thing' | 'assertion' | 'shape' | 'collection';
+        kind?: CommitOperationKind;
         reason?: string;
         leaseId?: string;
     }): this;
@@ -1633,7 +1638,7 @@ declare class OperationBuilder {
 }
 
 /** @internal */
-type CollectionAbout = CollectionAbout$2;
+type CollectionAbout = CollectionAbout$1;
 /** @internal */
 type CollectionTag = CollectionTag$1;
 /** @internal */
@@ -1699,6 +1704,49 @@ interface RequestEvent {
     operation: 'query' | 'mutation' | 'action';
     functionPath: string;
 }
+/**
+ * Argument forms for the single-subscription management methods (`get`,
+ * `reveal`, `pause`, `resume`, `remove`). GH-4679: the positional
+ * `(orgName, repoName, name)` form addresses a repo-scoped subscription; the
+ * object form may omit `repoName` to address an org-scoped (`org.renamed`)
+ * subscription — `get({ orgName, name })`.
+ */
+type SubscriptionRefArgs = [orgName: string, repoName: string, name: string] | [ref: {
+    orgName: string;
+    repoName?: string;
+    name: string;
+}];
+/** Argument forms for `list` — see {@link SubscriptionRefArgs}. */
+type SubscriptionListArgs = [orgName: string, repoName?: string] | [ref: {
+    orgName: string;
+    repoName?: string;
+}];
+/**
+ * Argument forms for `bindCredentials` — positional `(orgName, repoName,
+ * subscriptionName, credentialSetName)` addresses a repo-scoped subscription;
+ * the object form may omit `repoName` for an org-scoped subscription.
+ */
+type SubscriptionBindArgs = [
+    orgName: string,
+    repoName: string,
+    subscriptionName: string,
+    credentialSetName: string
+] | [
+    ref: {
+        orgName: string;
+        repoName?: string;
+        subscriptionName: string;
+        credentialSetName: string;
+    }
+];
+/** Argument forms for `unbindCredentials` — see {@link SubscriptionBindArgs}. */
+type SubscriptionUnbindArgs = [orgName: string, repoName: string, subscriptionName: string] | [
+    ref: {
+        orgName: string;
+        repoName?: string;
+        subscriptionName: string;
+    }
+];
 /** @internal */
 type CoreErrorKind = 'BACKEND' | 'NOT_FOUND' | 'FORBIDDEN' | 'UNAUTHENTICATED' | 'VALIDATION_ERROR' | 'CONFLICT' | 'RATE_LIMITED' | 'CANCELLED' | 'NETWORK';
 /**
@@ -1745,13 +1793,14 @@ type ShapeChange = ShapeChangeResult;
 type Shape = ShapeGetResult;
 /** @internal */
 type ShapeList = ShapeListResult;
+type CommitResultOperation = CommitOperation | 'noop';
 /**
  * Result of `client.shape.remove` — confirms the retraction with the new version metadata.
  * @internal
  */
 type ShapeRemove = {
     name: string;
-    operation: 'add' | 'revise' | 'retract' | 'noop';
+    operation: CommitResultOperation;
     version: number;
     dataHash: string;
     removed: true;
@@ -1799,10 +1848,8 @@ type SubscriptionInfo = {
  */
 type SubscriptionList = SubscriptionInfo[];
 /** @internal */
-type SubscriptionCompatCreateBase = {
+type SubscriptionCompatCreateCommon = {
     orgName: string;
-    repoName: string;
-    shapeName?: string;
     name: string;
     webhookUrl: string;
     fallbackWebhookUrl?: string;
@@ -1810,35 +1857,57 @@ type SubscriptionCompatCreateBase = {
     notifyOnSuccess?: boolean;
     componentRef?: string;
     workspacePolicy?: never;
+    kind: 'webhook';
     /** @internal */
     actionContainer?: string;
     /** @internal */
     actionContainerConfig?: unknown;
 };
 /**
- * Input shape for `client.subscription.create`. Webhook subscriptions require
- * `filterJson` and `webhookUrl`, and must identify a shape via `shapeName`
- * or `filterJson.shape` (or a shape-lifecycle `{ kind: 'shape' }` filter).
- * The cron kind was retired from public surfaces; legacy cron rows remain
- * readable via {@link SubscriptionInfo}.
+ * Input shape for `client.subscription.create`, discriminated on `eventType`
+ * (GH-4679):
+ *
+ * - default / `commit` — operation-based, repo-scoped (`repoName`); requires a
+ *   `filterJson` object and a shape binding (`shapeName` or `filterJson.shape`).
+ * - `repo.renamed` — repo-scoped metadata event; no shape/filter/source.
+ * - `org.renamed` — org-scoped metadata event; no `repoName`/shape/filter/source.
+ *
+ * The metadata variants forbid the commit-only fields at the type level so
+ * invalid shapes fail at compile time, not just server-side.
  *
  * @see https://docs.warmhub.ai/subscriptions/creating/
  */
-type SubscriptionCompatCreateInput = SubscriptionCompatCreateBase & {
-    kind: 'webhook';
+type SubscriptionCompatCreateInput = (SubscriptionCompatCreateCommon & {
+    eventType?: 'commit';
+    repoName: string;
     filterJson: Record<string, unknown>;
+    shapeName?: string;
     sourceRepoRef?: string;
-};
+}) | (SubscriptionCompatCreateCommon & {
+    eventType: 'repo.renamed';
+    repoName: string;
+    filterJson?: never;
+    shapeName?: never;
+    sourceRepoRef?: never;
+}) | (SubscriptionCompatCreateCommon & {
+    eventType: 'org.renamed';
+    repoName?: never;
+    filterJson?: never;
+    shapeName?: never;
+    sourceRepoRef?: never;
+});
 /**
- * Input shape for `client.subscription.update`. `orgName`, `repoName`, and
- * `name` identify the subscription; all other fields are optional and only
- * the ones you provide get patched.
+ * Input shape for `client.subscription.update`. `orgName` and `name` identify
+ * the subscription; omit `repoName` to update an org-scoped (`org.renamed`)
+ * subscription. All other fields are optional and only the ones you provide get
+ * patched. Rename subscriptions (`repo.renamed`/`org.renamed`) reject
+ * `shapeName`/`filterJson` — they have only delivery fields to edit.
  *
  * @see https://docs.warmhub.ai/subscriptions/managing/#update-subscription
  */
 type SubscriptionCompatUpdateInput = {
     orgName: string;
-    repoName: string;
+    repoName?: string;
     name: string;
     shapeName?: string;
     filterJson?: Record<string, unknown>;
@@ -2361,7 +2430,7 @@ type HistoryResult = {
     versions: Array<{
         version: number;
         wref: string;
-        operation: 'add' | 'revise' | 'retract';
+        operation: CommitOperation;
         retractReason?: string;
         active: boolean;
         createdAt: number;
@@ -2381,7 +2450,7 @@ type ThingHeadRequest = {
     orgName: string;
     repoName: string;
     shape?: string;
-    kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+    kind?: CommitOperationKind;
     match?: string;
     dataMode?: 'full' | 'summary' | 'none';
     includeRetracted?: boolean;
@@ -2630,7 +2699,7 @@ type FilterOptions = {
     /** Filter to records of this shape name (for example `Player`). */
     shape?: string;
     /** Filter to records of this kind: `shape`, `thing`, `assertion`, or `collection`. */
-    kind?: 'shape' | 'thing' | 'assertion' | 'collection';
+    kind?: CommitOperationKind;
     /** Filter assertions whose `about` target wref matches the supplied value. */
     about?: string;
     /** Glob pattern matched against record names (for example `Player/*`). */
@@ -3483,8 +3552,12 @@ declare class WarmHubClient {
         create: (input: SubscriptionCompatCreateInput) => Promise<SubscriptionInfo>;
         /**
          * Get one subscription by name.
+         *
+         * Repo-scoped subscriptions are addressed by `(orgName, repoName, name)`;
+         * org-scoped subscriptions (`org.renamed`) omit `repoName` via the object
+         * form: `get({ orgName, name })`.
          */
-        get: (orgName: string, repoName: string, name: string) => Promise<SubscriptionInfo>;
+        get: (...args: SubscriptionRefArgs) => Promise<SubscriptionInfo>;
         /**
          * Reveal the raw webhook URL(s) for a subscription.
          *
@@ -3495,11 +3568,15 @@ declare class WarmHubClient {
          * setup token) may reveal only the subscriptions it is scoped to — a
          * stricter contract than the redacted `get`/`list`, which are unscoped.
          */
-        reveal: (orgName: string, repoName: string, name: string) => Promise<SubscriptionRevealResult>;
+        reveal: (...args: SubscriptionRefArgs) => Promise<SubscriptionRevealResult>;
         /**
-         * List subscriptions attached to a repository.
+         * List subscriptions in a scope.
+         *
+         * Pass `(orgName, repoName)` to list a repository's subscriptions, or omit
+         * `repoName` — `list(orgName)` or `list({ orgName })` — to list the
+         * org-scoped (`org.renamed`) subscriptions.
          */
-        list: (orgName: string, repoName: string) => Promise<SubscriptionList>;
+        list: (...args: SubscriptionListArgs) => Promise<SubscriptionList>;
         /**
          * Update an existing webhook subscription.
          *
@@ -3508,32 +3585,43 @@ declare class WarmHubClient {
         update: (input: SubscriptionCompatUpdateInput) => Promise<SubscriptionInfo>;
         /**
          * Pause a subscription.
+         *
+         * Omit `repoName` (object form) to pause an org-scoped subscription.
          */
-        pause: (orgName: string, repoName: string, name: string) => Promise<{
+        pause: (...args: SubscriptionRefArgs) => Promise<{
             name: string;
             active: boolean;
         }>;
         /**
          * Resume a paused subscription.
+         *
+         * Omit `repoName` (object form) to resume an org-scoped subscription.
          */
-        resume: (orgName: string, repoName: string, name: string) => Promise<{
+        resume: (...args: SubscriptionRefArgs) => Promise<{
             name: string;
             active: boolean;
         }>;
         /**
          * Delete a subscription.
+         *
+         * Omit `repoName` (object form) to delete an org-scoped subscription.
          */
-        remove: (orgName: string, repoName: string, name: string) => Promise<{
+        remove: (...args: SubscriptionRefArgs) => Promise<{
             ok: true;
         }>;
         /**
          * Bind a credential set to a subscription for outbound webhook authentication.
+         *
+         * Omit `repoName` (object form) to bind an org-scoped subscription to one of
+         * the org's org-scoped credential sets.
          */
-        bindCredentials: (orgName: string, repoName: string, subscriptionName: string, credentialSetName: string) => Promise<SubscriptionBindCredentialsResult>;
+        bindCredentials: (...args: SubscriptionBindArgs) => Promise<SubscriptionBindCredentialsResult>;
         /**
          * Remove the credential set currently bound to a subscription.
+         *
+         * Omit `repoName` (object form) for an org-scoped subscription.
          */
-        unbindCredentials: (orgName: string, repoName: string, subscriptionName: string) => Promise<SubscriptionUnbindCredentialsResult>;
+        unbindCredentials: (...args: SubscriptionUnbindArgs) => Promise<SubscriptionUnbindCredentialsResult>;
     };
     /**
      * Low-level action lease, delivery, run, and notification primitives for subscription consumers.