@tangle-network/hub-sdk 0.15.3-develop.20260731000024.8def6ab → 0.16.0

package/README.md

@@ -30,9 +30,7 @@ SaaS vs on-prem flips via env only — there is no per-client default URL.
 | `TANGLE_API_KEY`               | One of   | Long-lived API key (Bearer). User / API key principal.                                        |
 | `TANGLE_HUB_CAPABILITY_TOKEN`  | One of   | Short-lived capability token (Bearer). Sandbox-runtime principal. Auto-minted server-side per action. |
 
-The two auth credentials are mutually exclusive — set exactly one. This
-mirrors the platform-api `hubSandboxEnvironmentSchema` rule
-(`exactly-one-api-key-or-capability-token`).
+The two auth credentials are mutually exclusive — set exactly one.
 
 ### Examples
 
@@ -229,8 +227,54 @@ before starting product work.
 - `HubSdkError` — typed `code: HubErrorCode`, redacted `details`, optional
   HTTP `status`
 - `HUB_URL_ENV_VAR`, `HUB_API_KEY_ENV_VAR`, `HUB_CAPABILITY_TOKEN_ENV_VAR` —
-  string constants for the env-var names (mirrored by the platform-api
-  `hub-sandbox-contract.ts` `z.literal(...)`)
+  string constants for the env-var names
 - `resolveHubBaseUrl(env?)`, `resolveHubAuth(env?)` — standalone resolvers
   with the same fail-loud contract as `fromEnv`
 - All request/response types from the `/v1/hub/*` contract
+
+
+## Link application login to explicit Hub permissions
+
+Use the same `HubClient` for application management; do not add a product-local
+HTTP client. These operations require the authenticated developer account, not
+an app's OIDC access token. Customer grants are created only by the existing
+session-authenticated `/cross-site/app-consent` flow.
+
+```ts
+import { HubClient } from "@tangle-network/hub-sdk";
+
+const hub = HubClient.fromEnv(); // developer account for app administration
+const { app, clientSecret } = await hub.apps.create({
+  name: "Support assistant",
+  redirectUris: ["https://assistant.example/hub/callback"],
+  allowedScopes: ["github.issues.create"],
+});
+// Save clientSecret once in the application's server-side secret store.
+await hub.apps.linkOAuthClient(app.id, oidcClientId);
+const apps = await hub.apps.list(); // includes oauthClientId; never the secret
+```
+
+`oidcClientId` is the application's already-registered Sign in with Tangle client.
+Linking requires the same owner on both records and is immutable and one-to-one.
+It does not reuse the two clients' secrets, change their IDs, create a user grant,
+or authorize spending. Use separate app/client pairs for separate deployments.
+Existing unlinked broker apps remain compatible. There is no automatic link by
+name, callback domain, email, or ownership alone.
+
+With a customer's authenticated Hub client, `hub.apps.grants.list()` returns only
+that customer's active resource grants and `hub.apps.grants.revoke(grantId)`
+revokes one idempotently. App administrators use `hub.apps.revoke(appId)` to
+suspend the app, revoke all its customer grants, and disable its owned linked
+OIDC client. An app's broker credential cannot call these management methods.
+
+Broker execution keeps the one approved connection even when the invocation
+omits `connectionId`; it never substitutes another account. Each one-shot broker
+token is checked against current app policy and the exact active grant when
+minted and consumed. Changing consent revokes the old binding, tokens and codes;
+the fresh consent response supplies a new grant ID. Login disconnect revokes the
+linked app's existing grants for that customer, not other customers or apps.
+An operation already admitted to a provider may finish; revocation blocks new
+admissions and minting, not external side effects already underway.
+
+This is identity and resource delegation, **not** generalized spending delegation.
+Existing product billing checks and action approvals continue to apply.

package/dist/index.d.ts

@@ -1,3 +1,214 @@
+//#region src/apps.d.ts
+/** App identity and customer permissions over the existing Platform transport.
+ * These operations do not authorize spending or expose upstream credentials. */
+interface HubApp {
+  id: string;
+  clientId: string;
+  oauthClientId: string | null;
+  name: string;
+  redirectUris: string[];
+  allowedScopes: string[];
+  homepageUrl: string | null;
+  status: "active" | "revoked";
+  createdAt: string;
+  updatedAt: string;
+}
+interface HubAppCreateInput {
+  name: string;
+  redirectUris: string[];
+  allowedScopes: string[];
+  homepageUrl?: string;
+  /** Associate an existing owned login client in the same transaction as creation. */
+  oauthClientId?: string;
+}
+interface HubAppGrant {
+  id: string;
+  appId: string;
+  userId: string;
+  connectionId: string;
+  scopes: string[];
+  status: "active" | "revoked";
+  createdAt: string;
+  updatedAt: string;
+  revokedAt: string | null;
+  /** Display metadata is additive; older deployments may omit it. */
+  appName?: string | null;
+  oauthClientId?: string | null;
+  providerId?: string | null;
+  accountDisplay?: string | null;
+  connectionDisplayName?: string | null;
+}
+interface HubAppGrantRevoked {
+  grantId: string;
+  status: "revoked";
+  revokedAt: string | null;
+  tokensRevoked: number;
+}
+declare class HubAppsClient {
+  private readonly request;
+  readonly grants: {
+    list: () => Promise<HubAppGrant[]>;
+    revoke: (grantId: string) => Promise<HubAppGrantRevoked>;
+  };
+  constructor(request: <T>(path: string, init: RequestInit) => Promise<T>);
+  list(): Promise<HubApp[]>;
+  /** The secret is returned only by creation; keep it in your server vault. */
+  create(input: HubAppCreateInput): Promise<{
+    app: HubApp;
+    clientSecret: string;
+  }>;
+  /** Immutable association of two existing records with the same owner. */
+  linkOAuthClient(appId: string, clientId: string): Promise<{
+    appId: string;
+    oauthClientId: string;
+  }>;
+  revoke(appId: string): Promise<{
+    appId: string;
+    grantsRevoked: number;
+    tokensRevoked: number;
+  }>;
+}
+//#endregion
+//#region src/inbound-webhooks.d.ts
+/** Provider setup uses the existing authenticated Hub transport and vault. */
+interface HubInboundWebhookCreateOptions {
+  /** Inkbox identity that owns all selected channels. */
+  identityId?: string;
+  mailboxId?: string;
+  phoneNumberId?: string;
+  imessage?: boolean;
+  /** Linq: explicit owned lines; omitted does not mean every account line. */
+  phoneNumbers?: string[];
+  /** Linq WhatsApp: explicit opaque IDs from numbers.list, not E.164 phone strings. */
+  phoneNumberIds?: string[];
+  /** Contiguity Console secret, or an existing Inkbox identity signing key. */
+  signingSecret?: string;
+}
+interface HubInboundWebhookCreateResponse {
+  url: string;
+  /** True only when the provider subscription was created by the server. */
+  provisioned?: boolean;
+  /** Self-configured legacy providers can return a newly minted secret once. */
+  secret?: string;
+  inboundAddress?: string;
+  requiresProviderSetup?: boolean;
+}
+interface HubInboundWebhookStatus {
+  configured: boolean;
+  url?: string;
+  /** Configuration is not evidence of a real delivered message. */
+  deliveryVerified: false;
+  requiresProviderSetup?: boolean;
+}
+/** Live provider readback for one explicitly selected Linq WhatsApp number. */
+interface HubInboundPhoneNumberScope {
+  configured: true;
+  provisioned: true;
+  subscribed: true;
+  phoneNumberIds: string[];
+}
+declare class HubInboundWebhooksClient {
+  private readonly request;
+  constructor(request: <T>(path: string, init: RequestInit) => Promise<T>);
+  create(connectionId: string, options?: HubInboundWebhookCreateOptions): Promise<HubInboundWebhookCreateResponse>;
+  get(connectionId: string): Promise<HubInboundWebhookStatus>;
+  /** Add one owned Linq WhatsApp number without rotating the webhook secret. */
+  ensurePhoneNumber(connectionId: string, phoneNumberId: string): Promise<HubInboundPhoneNumberScope>;
+  /** Remove event subscriptions first. This does not silently rotate a live URL. */
+  delete(connectionId: string): Promise<{
+    removed: boolean;
+  }>;
+  private path;
+}
+//#endregion
+//#region src/managed-numbers.d.ts
+interface HubNumberReadiness {
+  configured: boolean;
+  provider: "inkbox";
+  transports: Array<"sms" | "imessage">;
+  billing: "prepaid_activation";
+  automaticRentalBilling: false;
+  deliveryVerified: false;
+}
+interface HubNumberQuote {
+  transport: "sms" | "imessage";
+  activationCents: number;
+  currency: "usd";
+  termsVersion: string;
+  terms: string;
+  expiresAt: number;
+  token: string;
+}
+/** An operator's terminal decision on an order stuck in `needs_review`.
+ * Read-only for a creator: the resolution is made through the platform's
+ * admin surface, never through this client. */
+interface HubNumberResolution {
+  action: "release" | "settle" | "abandon";
+  operator: string;
+  reason: string;
+  at: number;
+  /** Present while the operator's action is still running. The decision is
+   * not final and the order can still return to review. */
+  pending?: true;
+  /** Present when a `settle` handed a live, unfinished order back to
+   * provisioning, so the order is working again rather than closed. */
+  requeued?: true;
+}
+interface HubNumberOrder {
+  id: string;
+  clientReference: string;
+  transport: "sms" | "imessage";
+  status: "pending" | "provider_pending" | "needs_review" | "ready_for_setup" | "cancelled";
+  phase: "identity" | "number" | "credential" | "connection" | "complete";
+  address: string | null;
+  connectionId: string | null;
+  identityId: string | null;
+  providerNumberId: string | null;
+  billingStatus: "unreserved" | "reserved" | "settled" | "released";
+  cancellation: "none" | "requested" | "needs_review" | "released" | "abandoned";
+  errorCode: string | null;
+  nextAttemptAt: number | null;
+  resolution: HubNumberResolution | null;
+  deliveryVerified: false;
+  activationCents: number;
+  currency: "usd";
+  terms: string;
+}
+/** Administrative number operations through Hub's authenticated transport.
+ * A mutation is one attempt; an uncertain create reuses its quote and reference. */
+declare class HubManagedNumbersClient {
+  private readonly request;
+  constructor(request: <T>(path: string, init: RequestInit) => Promise<T>);
+  readiness(): Promise<HubNumberReadiness>;
+  list(): Promise<{
+    orders: HubNumberOrder[];
+  }>;
+  get(id: string): Promise<{
+    order: HubNumberOrder;
+  }>;
+  quote(input: {
+    transport: "sms" | "imessage";
+    clientReference: string;
+  }): Promise<{
+    quote: HubNumberQuote;
+  }>;
+  create(input: {
+    quoteToken: string;
+    consent: true;
+    state?: string;
+  }): Promise<{
+    order: HubNumberOrder;
+  }>;
+  advance(id: string): Promise<{
+    order: HubNumberOrder;
+  }>;
+  cancel(id: string): Promise<{
+    order: HubNumberOrder;
+  }>;
+  private path;
+  private post;
+}
+//#endregion
 //#region src/types.d.ts
 type HubPrincipalKind = "user_session" | "api_key" | "sandbox_runtime";
 interface HubSuccessEnvelope<TData> {
@@ -14,7 +225,7 @@ interface HubErrorBody {
   message: string;
   details?: unknown;
 }
-type HubErrorCode = "HUB_UNAUTHENTICATED" | "HUB_FORBIDDEN" | "HUB_INVALID_INPUT" | "HUB_INVALID_STATE" | "HUB_PROVIDER_MISSING" | "HUB_CONNECTION_MISSING" | "HUB_CONNECTION_REVOKED" | "HUB_TOKEN_EXPIRED" | "HUB_TOKEN_REPLAYED" | "HUB_TOKEN_REVOKED" | "HUB_TOKEN_ACTION_MISMATCH" | "HUB_POLICY_DENIED" | "HUB_APPROVAL_REQUIRED" | "HUB_EXECUTOR_FAILURE" | "HUB_PROVIDER_FAILURE" | "HUB_CONFIG_MISSING" | "HUB_CONFIG_INVALID" | "HUB_NOT_FOUND" | "HUB_NOT_IMPLEMENTED" | "HUB_CONFLICT" | "VALIDATION_ERROR" | "WORKFLOW_INVALID" | "NOT_FOUND" | "UNAUTHORIZED" | "CONFLICT" | "MISSING_RUN_INPUTS" | "WORKFLOW_DISABLED" | "PAYLOAD_TOO_LARGE" | "WORKFLOW_RUN_TIMEOUT" | `HUB_HTTP_${number}`;
+type HubErrorCode = "HUB_UNAUTHENTICATED" | "HUB_FORBIDDEN" | "HUB_INVALID_INPUT" | "HUB_INVALID_STATE" | "HUB_PROVIDER_MISSING" | "HUB_CONNECTION_MISSING" | "HUB_CONNECTION_REVOKED" | "HUB_TOKEN_EXPIRED" | "HUB_TOKEN_REPLAYED" | "HUB_TOKEN_REVOKED" | "HUB_TOKEN_ACTION_MISMATCH" | "HUB_POLICY_DENIED" | "HUB_APPROVAL_REQUIRED" | "HUB_EXECUTOR_FAILURE" | "HUB_PROVIDER_FAILURE" | "HUB_PROVIDER_REJECTED" | "HUB_CONFIG_MISSING" | "HUB_CONFIG_INVALID" | "HUB_NOT_FOUND" | "HUB_NOT_IMPLEMENTED" | "HUB_CONFLICT" | "HUB_IDEMPOTENCY_CONFLICT" | "HUB_IDEMPOTENCY_IN_FLIGHT" | "VALIDATION_ERROR" | "WORKFLOW_INVALID" | "NOT_FOUND" | "UNAUTHORIZED" | "CONFLICT" | "MISSING_RUN_INPUTS" | "WORKFLOW_DISABLED" | "PAYLOAD_TOO_LARGE" | "WORKFLOW_RUN_TIMEOUT" | `HUB_HTTP_${number}`;
 interface HubStatusResponse {
   contract: unknown;
   principal: HubPrincipal;
@@ -36,6 +247,7 @@ interface HubConnection {
   providerId: string;
   displayName: string;
   accountDisplay: string | null;
+  providerAccountId: string | null;
   scopes: string[];
   status: "active" | "revoked" | "unhealthy" | "reconnect_required";
   health: "unknown" | "healthy" | "unhealthy" | "rate_limited";
@@ -168,6 +380,15 @@ interface HubEventDelivery {
 }
 /** A connector's auth model. */
 type HubProviderAuthKind = "oauth2" | "api_key" | "none" | "custom";
+/** One non-secret value needed before an OAuth redirect can be built. Tenant-
+ * scoped providers use this for the account label in their OAuth hostname. */
+interface HubOAuthConnectionParameter {
+  key: string;
+  label: string;
+  description: string;
+  placeholder: string;
+  required: true;
+}
 interface HubProvider {
   providerId: string;
   title: string;
@@ -193,6 +414,9 @@ interface HubProvider {
   /** True when the provider's OAuth app credentials are wired, i.e. a connect
    *  flow can actually start. UIs offer Connect only for configured providers. */
   configured: boolean;
+  /** Values the user must supply before OAuth starts. Empty or absent means the
+   *  provider can redirect immediately. */
+  connectionParameters?: HubOAuthConnectionParameter[];
   /**
    * True when this deployment can receive this provider's inbound events.
    * This is separate from `configured`: OAuth can be ready while the shared
@@ -209,6 +433,7 @@ interface HubOAuthStartRequest {
   provider: string;
   returnUrl?: string;
   cli?: boolean;
+  connectionParameters?: Record<string, string>;
 }
 interface HubOAuthCallbackSuccessQuery {
   provider: string;
@@ -269,7 +494,18 @@ interface HubOAuthCallbackResponse {
 interface HubApiKeyConnectRequest {
   provider: string;
   apiKey: string;
+  /** Connector-owned setup values. Hub validates them before testing the key. */
+  metadata?: HubApiKeyConnectionMetadata;
 }
+type HubApiKeyConnectionMetadata = {
+  propertyId: string;
+  currency?: string;
+} | {
+  listings: Array<{
+    id: string;
+    pms: string;
+  }>;
+};
 /** Result of an api-key connect: the created (or reconnected) connection.
  *  Synchronous — there is no redirect leg, unlike the OAuth flow. */
 interface HubApiKeyConnectResponse {
@@ -285,7 +521,7 @@ interface HubConnectionDeleteResponse {
 interface HubConnectionHealthRequest {
   connectionId: string;
 }
-type HubConnectionHealthStatus = "healthy" | "reconnect_required" | "unhealthy" | "rate_limited";
+type HubConnectionHealthStatus = "healthy" | "reconnect_required" | "unhealthy" | "rate_limited" | "unsupported";
 interface HubConnectionHealthError {
   code: string;
   message: string;
@@ -345,9 +581,18 @@ interface HubExecRequest {
   path: string;
   input?: unknown;
   connectionId?: string;
+  /** Caller-minted key for this exec. The platform ledger replays the first
+   *  call's result for a retry that carries the same key, and rejects a key
+   *  reused for a different request. On the capability-token arm the key only
+   *  reaches the connector for provider-native dedupe: that arm is at-most-once
+   *  per token and replays no stored result. */
+  idempotencyKey?: string;
 }
 interface HubExecResponse<TResult = unknown> {
   result: TResult;
+  /** True when the result was replayed from a previous call with the same
+   *  idempotency key, so the action did not run again. */
+  replayed?: boolean;
 }
 interface HubTokenMintRequest {
   connectionId?: string;
@@ -512,6 +757,50 @@ interface HubGithubAppInstallation {
 interface HubGithubAppInstallationResponse {
   installation: HubGithubAppInstallation;
 }
+/** An installation as the management surface renders it: the registry record
+ *  plus where to manage it on GitHub (org and personal accounts have different
+ *  settings paths, and the id is not discoverable in GitHub's own UI). */
+interface HubGithubAppManagedInstallation extends HubGithubAppInstallation {
+  manageUrl: string;
+}
+interface HubGithubAppListInstallationsResponse {
+  installations: HubGithubAppManagedInstallation[];
+  /** GitHub's install URL for this deployment, or null when the App slug is
+   *  unconfigured — in which case there is no way to add another account and
+   *  the UI must say so rather than link nowhere. */
+  installUrl: string | null;
+  /** Whether this deployment can ask GitHub for installations it never
+   *  witnessed. Rests on the App CREDENTIAL, not the slug behind `installUrl` —
+   *  a deployment can have one without the other. */
+  syncAvailable?: boolean;
+}
+interface HubGithubAppDisconnectResponse {
+  installationId: number;
+  disconnected: boolean;
+}
+interface HubGithubAppSyncedInstallation {
+  installationId: number;
+  accountLogin: string;
+  accountType: string | null;
+  repositorySelection: "all" | "selected";
+  /** False when this run is what linked it — the newly reachable access. */
+  alreadyLinked: boolean;
+}
+/** Result of reconciling the caller's installations from GitHub. */
+interface HubGithubAppSyncResponse {
+  /** How many of the caller's GitHub accounts were examined. */
+  accountsChecked: number;
+  /** Installations the caller may act through once this returns. */
+  linked: HubGithubAppSyncedInstallation[];
+  /** An installation was found but not linked, and why. An account with no
+   *  installation is absent — that is the ordinary case, not a problem. */
+  skipped: Array<{
+    accountLogin: string;
+    reason: string;
+  }>;
+  /** Why the examined set is not everything, when it isn't. */
+  incomplete?: string;
+}
 interface HubGithubAppListReposResponse {
   installationId: number;
   /** Lowercased "owner/repo" — covers the full registry view of the install. */
@@ -599,10 +888,13 @@ interface HubWorkflowActionResult {
   error?: string;
   costUsd?: number;
   /** Graph-run identity: the topology node this action row belongs to. Present
-   *  only on cycle re-entry rows (a node visited more than once produces one
-   *  row per visit); absent on a linear run's rows. */
+   *  when the id says something the row's position does not — an author's DAG
+   *  node id, and every cycle re-entry row (a node visited more than once
+   *  produces one row per visit). Absent on a linear run's rows, whose node id
+   *  IS their position: read it as `step-${index + 1}`. */
   nodeId?: string;
-  /** Which visit of `nodeId` this row is (1-based), paired with `nodeId`. */
+  /** Which visit of `nodeId` this row is (1-based). Present on cycle re-entry
+   *  rows only; a single-visit row omits it. */
   visit?: number;
   /** `script.run` only (single-run detail): the script's captured stdout
    *  (size-capped), or an artifact ref carrying the full log by reference. */
@@ -937,6 +1229,8 @@ interface HubWorkflowProposalInput {
 }
 /** One node's aggregate across the analyzed runs. */
 interface HubWorkflowNodeHealth {
+  /** The author's graph node id, or `step-N` for a linear run's nodes (and for
+   *  a node whose run cannot be mapped back to a definition). */
   nodeId: string;
   visits: number;
   failures: number;
@@ -1053,6 +1347,14 @@ interface HubWorkflowConnectionRequirement {
   /** Where to satisfy the requirement (App install flow for `github_app`,
    *  integrations page otherwise); null when no target exists. */
   connectUrl: string | null;
+  /** Another requirement in the same list that must be satisfied first — a
+   *  `github_app` install is claimed through the `github` connection, so it is
+   *  refused while that connection is missing. Null when nothing blocks this
+   *  requirement. The list is ordered prerequisite-first. */
+  prerequisite: {
+    provider: string;
+    kind: "integration" | "github_app";
+  } | null;
 }
 /**
  * Result of instantiating a template. `created: false` is NOT an error — an
@@ -1176,8 +1478,10 @@ declare class HubClient {
   readonly fetch: typeof fetch;
   readonly apiKey?: string;
   readonly authHeaders?: HubAuthHeaders;
+  readonly apps: HubAppsClient;
   readonly connections: HubConnectionsClient;
   readonly channels: HubChannelsClient;
+  readonly numbers: HubManagedNumbersClient;
   readonly eventSubscriptions: HubEventSubscriptionsClient;
   readonly permissions: HubPermissionsClient;
   readonly tokens: HubTokensClient;
@@ -1255,6 +1559,13 @@ interface HubToolSearchOptions {
 interface HubToolInvokeOptions {
   connectionId?: string;
   approve?: boolean;
+  /** Caller-minted key for this invoke. On the direct exec arm the platform
+   *  ledger replays the first call's result for a retry that carries the same
+   *  key, and refuses a key bound to a different request. The approval and
+   *  capability-token retries re-send the key, and the connector receives it
+   *  for provider-native dedupe. Capability-token execution stays at-most-once
+   *  per token: it refuses a replay instead of replaying a stored result. */
+  idempotencyKey?: string;
 }
 declare class HubToolsClient {
   private readonly request;
@@ -1262,12 +1573,18 @@ declare class HubToolsClient {
   search(query: string, options?: HubToolSearchOptions): Promise<HubToolsSearchResponse>;
   sources(): Promise<HubToolSourcesResponse>;
   describe(path: string): Promise<HubToolsDescribeResponse>;
-  invoke<TResult = unknown>(path: string, input: unknown, options?: HubToolInvokeOptions): Promise<HubExecResponse<TResult>>;
+  /**
+   * Run one hub tool. `raw` is the tool input: the SDK forwards it verbatim as
+   * the request body's `input`, and the server validates it against the tool's
+   * own schema, so the client never gives it a shape.
+   */
+  invoke<TResult = unknown>(path: string, raw: unknown, options?: HubToolInvokeOptions): Promise<HubExecResponse<TResult>>;
   private buildExecInit;
 }
 interface HubConnectionStartOptions {
   returnUrl?: string;
   cli?: boolean;
+  connectionParameters?: Record<string, string>;
 }
 declare class HubChannelsClient {
   private readonly request;
@@ -1285,6 +1602,7 @@ declare class HubEventSubscriptionsClient {
 }
 declare class HubConnectionsClient {
   private readonly request;
+  readonly inboundWebhook: HubInboundWebhooksClient;
   constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>);
   list(): Promise<HubConnectionsResponse>;
   /** Connector catalog: every provider the hub can expose, each flagged with
@@ -1297,8 +1615,9 @@ declare class HubConnectionsClient {
   /** Connect a non-OAuth (api-key) connector by submitting the user's key.
    *  The server validates the key with a live probe before persisting and
    *  returns the created (or reconnected) connection — there is no redirect,
-   *  unlike `start`. */
-  connectApiKey(provider: string, apiKey: string): Promise<HubApiKeyConnectResponse>;
+   *  unlike `start`. Cloudbeds requires propertyId metadata and PriceLabs
+   *  requires listing ID/PMS pairs; other providers have no metadata. */
+  connectApiKey(provider: string, apiKey: string, metadata?: HubApiKeyConnectRequest["metadata"]): Promise<HubApiKeyConnectResponse>;
   revoke(connectionId: string): Promise<HubConnectionDeleteResponse>;
   health(connectionId: string): Promise<HubConnectionHealthResponse>;
 }
@@ -1313,6 +1632,19 @@ declare class HubGithubAppClient {
   private readonly request;
   constructor(request: <TData>(path: string, init: RequestInit) => Promise<TData>);
   mintInstallationToken(input: HubGithubAppMintInstallationTokenRequest): Promise<HubGithubAppMintInstallationTokenResponse>;
+  /** Every installation the caller may act through — their own and any org's
+   *  they were verified against. The management surface's read. */
+  listInstallations(): Promise<HubGithubAppListInstallationsResponse>;
+  /**
+   * Find installations `listInstallations` cannot show: the hub only registers
+   * what the setup redirect witnessed, so an org install approved out of band —
+   * or created by another member — is invisible until this asks GitHub for it.
+   * Links whatever the caller can prove access to; never uninstalls anything.
+   */
+  syncInstallations(): Promise<HubGithubAppSyncResponse>;
+  /** Give up THIS caller's access. Not an uninstall — the installation is
+   *  account-level and other members may still be using it. */
+  disconnectInstallation(installationId: number): Promise<HubGithubAppDisconnectResponse>;
   getInstallation(installationId: number): Promise<HubGithubAppInstallationResponse>;
   listRepos(installationId: number): Promise<HubGithubAppListReposResponse>;
   isRepoInstalled(input: {
@@ -1567,15 +1899,18 @@ declare class HubWorkflowsClient {
   /**
    * Upsert a key; returns the entry with its NEW version (increments on every
    * write). Throws `HubSdkError(KV_VALUE_TOO_LARGE)` past the 64KiB value cap
-   * or `KV_KEY_LIMIT` past the per-workflow key cap.
+   * or `KV_KEY_LIMIT` past the per-workflow key cap. `raw` is the caller's
+   * value, stored and read back verbatim, so the client never gives it a shape.
    */
-  putKv(id: string, key: string, value: unknown): Promise<HubWorkflowKvEntry>;
+  putKv(id: string, key: string, raw: unknown): Promise<HubWorkflowKvEntry>;
   /**
    * Compare-and-swap: the write lands only when the stored version still
    * equals `expectedVersion`; otherwise `HubSdkError(KV_VERSION_CONFLICT)`
-   * (409) — re-read and retry. Creation is {@link putKv}'s job.
+   * (409) — re-read and retry. Creation is {@link putKv}'s job. `raw` is the
+   * caller's value, stored and read back verbatim, so the client never gives it
+   * a shape.
    */
-  casKv(id: string, key: string, expectedVersion: number, value: unknown): Promise<HubWorkflowKvEntry>;
+  casKv(id: string, key: string, expectedVersion: number, raw: unknown): Promise<HubWorkflowKvEntry>;
   /** Delete a key; idempotent — `deleted` reports whether a row was removed. */
   deleteKv(id: string, key: string): Promise<HubWorkflowKvDeleteResponse>;
   /** The curated starter gallery runnable on THIS deployment: metadata,
@@ -1704,5 +2039,5 @@ declare function parseHubEventDelivery(input: string | unknown): HubEventDeliver
 //#region src/redaction.d.ts
 declare function redactHubValue(value: unknown): unknown;
 //#endregion
-export { type AuthenticateHubEventRequestInput, type DeriveHubEventCallbackSecretInput, HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, type HubAgentIterationSpan, type HubAgentRunDetail, type HubApiKeyConnectRequest, type HubApiKeyConnectResponse, type HubApproval, type HubApprovalCapabilityToken, type HubApprovalDecisionResponse, type HubApprovalStatus, HubApprovalsClient, HubAuditClient, type HubAuditEvent, type HubAuditListRequest, type HubAuditResponse, type HubAuthHeaders, type HubCapabilityToken, type HubChannel, type HubChannelCreateResponse, type HubChannelDeleteResponse, HubChannelsClient, type HubChannelsResponse, HubClient, type HubClientFromEnvOptions, type HubClientOptions, type HubConnection, type HubConnectionDeleteRequest, type HubConnectionDeleteResponse, type HubConnectionHealthError, type HubConnectionHealthInfo, type HubConnectionHealthRequest, type HubConnectionHealthResponse, type HubConnectionHealthStatus, type HubConnectionStartOptions, HubConnectionsClient, type HubConnectionsResponse, type HubEmailChannel, type HubEmailChannelCreateRequest, type HubEnv, type HubEnvelope, type HubErrorBody, type HubErrorCode, type HubErrorEnvelope, type HubEventCondition, type HubEventConditionScalar, type HubEventDelivery, HubEventDeliveryError, type HubEventRequestFailureCode, type HubEventRequestResult, type HubEventSignatureFailure, type HubEventSignatureResult, type HubEventSubscription, type HubEventSubscriptionCallback, type HubEventSubscriptionCreateRequest, type HubEventSubscriptionCreateResponse, type HubEventSubscriptionDeleteResponse, type HubEventSubscriptionFilter, type HubEventSubscriptionSource, HubEventSubscriptionsClient, type HubEventSubscriptionsResponse, type HubExecRequest, type HubExecResponse, HubGithubAppClient, type HubGithubAppInstallation, type HubGithubAppInstallationResponse, type HubGithubAppIsRepoInstalledRequest, type HubGithubAppIsRepoInstalledResponse, type HubGithubAppListReposResponse, type HubGithubAppMintInstallationTokenRequest, type HubGithubAppMintInstallationTokenResponse, type HubManualRunInput, type HubOAuthCallbackErrorQuery, type HubOAuthCallbackQuery, type HubOAuthCallbackResponse, type HubOAuthCallbackSuccessQuery, type HubOAuthStartRequest, type HubOAuthStartResponse, HubPermissionsClient, type HubPolicy, type HubPolicyDecision, type HubPolicyDeleteRequest, type HubPolicyDeleteResponse, type HubPolicyListRequest, type HubPolicyListResponse, type HubPolicyResponse, type HubPolicyUpdateRequest, type HubPrincipal, type HubPrincipalKind, type HubProvider, type HubProviderAuthKind, type HubProviderEvent, type HubProvidersResponse, HubSdkError, type HubStatusConnections, type HubStatusResponse, type HubSuccessEnvelope, type HubTokenListOptions, type HubTokenMintRequest, type HubTokenMintResponse, type HubTokenRevokeResponse, HubTokensClient, type HubTokensListResponse, type HubTool, type HubToolInvokeOptions, type HubToolRisk, type HubToolSearchOptions, type HubToolSource, type HubToolSourcesResponse, HubToolsClient, type HubToolsDescribeRequest, type HubToolsDescribeResponse, type HubToolsSearchRequest, type HubToolsSearchResponse, type HubUnimplementedErrorEnvelope, type HubWhatsappEmbeddedSignupCompleteRequest, type HubWhatsappEmbeddedSignupCompleteResponse, type HubWhatsappEmbeddedSignupStartRequest, type HubWhatsappEmbeddedSignupStartResponse, type HubWorkflow, type HubWorkflowAction, type HubWorkflowActionResult, type HubWorkflowAgentStep, type HubWorkflowArtifact, type HubWorkflowArtifactDownload, type HubWorkflowArtifactRef, type HubWorkflowArtifactsResponse, type HubWorkflowCondition, type HubWorkflowConditionOp, type HubWorkflowConditionScalar, type HubWorkflowConnectionRequirement, type HubWorkflowDecision, type HubWorkflowDecisionOnTimeout, type HubWorkflowDecisionResolveResult, type HubWorkflowDecisionResolvedVia, type HubWorkflowDecisionStatus, type HubWorkflowDistillationCandidate, type HubWorkflowEdgeVerdicts, type HubWorkflowEventFilter, type HubWorkflowFailureCluster, type HubWorkflowFleetEntry, type HubWorkflowFleetInsights, type HubWorkflowFleetWindow, type HubWorkflowGraphEdge, type HubWorkflowGraphJoinRule, type HubWorkflowGraphNode, type HubWorkflowGraphSpec, type HubWorkflowHealth, type HubWorkflowHookEndpoint, type HubWorkflowHookToken, type HubWorkflowKvDeleteResponse, type HubWorkflowKvEntry, type HubWorkflowKvEntryMeta, type HubWorkflowKvListResponse, type HubWorkflowNodeHealth, type HubWorkflowOnErrorOutcome, type HubWorkflowPendingDecision, type HubWorkflowPendingDecisionsResponse, type HubWorkflowProposal, type HubWorkflowProposalInput, type HubWorkflowRevision, type HubWorkflowRevisionMeta, type HubWorkflowRevisionSource, type HubWorkflowRevisionStatus, type HubWorkflowRun, type HubWorkflowRunCancelResult, type HubWorkflowRunDetail, type HubWorkflowRunEnqueued, type HubWorkflowRunInputs, type HubWorkflowRunRetried, type HubWorkflowRunStatus, type HubWorkflowRunStepsPage, type HubWorkflowRunStreamEvent, type HubWorkflowRunSummary, type HubWorkflowRunsPage, type HubWorkflowSchemaResponse, type HubWorkflowTemplate, type HubWorkflowTemplateCategory, type HubWorkflowTemplateInstantiateResult, type HubWorkflowTemplateParameter, type HubWorkflowTrigger, type HubWorkflowValidateResponse, type HubWorkflowValidationError, HubWorkflowsClient, type VerifyHubEventSignatureInput, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
+export { type AuthenticateHubEventRequestInput, type DeriveHubEventCallbackSecretInput, HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, type HubAgentIterationSpan, type HubAgentRunDetail, type HubApiKeyConnectRequest, type HubApiKeyConnectResponse, type HubApiKeyConnectionMetadata, type HubApp, type HubAppCreateInput, type HubAppGrant, type HubAppGrantRevoked, type HubApproval, type HubApprovalCapabilityToken, type HubApprovalDecisionResponse, type HubApprovalStatus, HubApprovalsClient, HubAppsClient, HubAuditClient, type HubAuditEvent, type HubAuditListRequest, type HubAuditResponse, type HubAuthHeaders, type HubCapabilityToken, type HubChannel, type HubChannelCreateResponse, type HubChannelDeleteResponse, HubChannelsClient, type HubChannelsResponse, HubClient, type HubClientFromEnvOptions, type HubClientOptions, type HubConnection, type HubConnectionDeleteRequest, type HubConnectionDeleteResponse, type HubConnectionHealthError, type HubConnectionHealthInfo, type HubConnectionHealthRequest, type HubConnectionHealthResponse, type HubConnectionHealthStatus, type HubConnectionStartOptions, HubConnectionsClient, type HubConnectionsResponse, type HubEmailChannel, type HubEmailChannelCreateRequest, type HubEnv, type HubEnvelope, type HubErrorBody, type HubErrorCode, type HubErrorEnvelope, type HubEventCondition, type HubEventConditionScalar, type HubEventDelivery, HubEventDeliveryError, type HubEventRequestFailureCode, type HubEventRequestResult, type HubEventSignatureFailure, type HubEventSignatureResult, type HubEventSubscription, type HubEventSubscriptionCallback, type HubEventSubscriptionCreateRequest, type HubEventSubscriptionCreateResponse, type HubEventSubscriptionDeleteResponse, type HubEventSubscriptionFilter, type HubEventSubscriptionSource, HubEventSubscriptionsClient, type HubEventSubscriptionsResponse, type HubExecRequest, type HubExecResponse, HubGithubAppClient, type HubGithubAppDisconnectResponse, type HubGithubAppInstallation, type HubGithubAppInstallationResponse, type HubGithubAppIsRepoInstalledRequest, type HubGithubAppIsRepoInstalledResponse, type HubGithubAppListInstallationsResponse, type HubGithubAppListReposResponse, type HubGithubAppManagedInstallation, type HubGithubAppMintInstallationTokenRequest, type HubGithubAppMintInstallationTokenResponse, type HubGithubAppSyncResponse, type HubGithubAppSyncedInstallation, type HubInboundPhoneNumberScope, type HubInboundWebhookCreateOptions, type HubInboundWebhookCreateResponse, type HubInboundWebhookStatus, HubInboundWebhooksClient, HubManagedNumbersClient, type HubManualRunInput, type HubNumberOrder, type HubNumberQuote, type HubNumberReadiness, type HubNumberResolution, type HubOAuthCallbackErrorQuery, type HubOAuthCallbackQuery, type HubOAuthCallbackResponse, type HubOAuthCallbackSuccessQuery, type HubOAuthConnectionParameter, type HubOAuthStartRequest, type HubOAuthStartResponse, HubPermissionsClient, type HubPolicy, type HubPolicyDecision, type HubPolicyDeleteRequest, type HubPolicyDeleteResponse, type HubPolicyListRequest, type HubPolicyListResponse, type HubPolicyResponse, type HubPolicyUpdateRequest, type HubPrincipal, type HubPrincipalKind, type HubProvider, type HubProviderAuthKind, type HubProviderEvent, type HubProvidersResponse, HubSdkError, type HubStatusConnections, type HubStatusResponse, type HubSuccessEnvelope, type HubTokenListOptions, type HubTokenMintRequest, type HubTokenMintResponse, type HubTokenRevokeResponse, HubTokensClient, type HubTokensListResponse, type HubTool, type HubToolInvokeOptions, type HubToolRisk, type HubToolSearchOptions, type HubToolSource, type HubToolSourcesResponse, HubToolsClient, type HubToolsDescribeRequest, type HubToolsDescribeResponse, type HubToolsSearchRequest, type HubToolsSearchResponse, type HubUnimplementedErrorEnvelope, type HubWhatsappEmbeddedSignupCompleteRequest, type HubWhatsappEmbeddedSignupCompleteResponse, type HubWhatsappEmbeddedSignupStartRequest, type HubWhatsappEmbeddedSignupStartResponse, type HubWorkflow, type HubWorkflowAction, type HubWorkflowActionResult, type HubWorkflowAgentStep, type HubWorkflowArtifact, type HubWorkflowArtifactDownload, type HubWorkflowArtifactRef, type HubWorkflowArtifactsResponse, type HubWorkflowCondition, type HubWorkflowConditionOp, type HubWorkflowConditionScalar, type HubWorkflowConnectionRequirement, type HubWorkflowDecision, type HubWorkflowDecisionOnTimeout, type HubWorkflowDecisionResolveResult, type HubWorkflowDecisionResolvedVia, type HubWorkflowDecisionStatus, type HubWorkflowDistillationCandidate, type HubWorkflowEdgeVerdicts, type HubWorkflowEventFilter, type HubWorkflowFailureCluster, type HubWorkflowFleetEntry, type HubWorkflowFleetInsights, type HubWorkflowFleetWindow, type HubWorkflowGraphEdge, type HubWorkflowGraphJoinRule, type HubWorkflowGraphNode, type HubWorkflowGraphSpec, type HubWorkflowHealth, type HubWorkflowHookEndpoint, type HubWorkflowHookToken, type HubWorkflowKvDeleteResponse, type HubWorkflowKvEntry, type HubWorkflowKvEntryMeta, type HubWorkflowKvListResponse, type HubWorkflowNodeHealth, type HubWorkflowOnErrorOutcome, type HubWorkflowPendingDecision, type HubWorkflowPendingDecisionsResponse, type HubWorkflowProposal, type HubWorkflowProposalInput, type HubWorkflowRevision, type HubWorkflowRevisionMeta, type HubWorkflowRevisionSource, type HubWorkflowRevisionStatus, type HubWorkflowRun, type HubWorkflowRunCancelResult, type HubWorkflowRunDetail, type HubWorkflowRunEnqueued, type HubWorkflowRunInputs, type HubWorkflowRunRetried, type HubWorkflowRunStatus, type HubWorkflowRunStepsPage, type HubWorkflowRunStreamEvent, type HubWorkflowRunSummary, type HubWorkflowRunsPage, type HubWorkflowSchemaResponse, type HubWorkflowTemplate, type HubWorkflowTemplateCategory, type HubWorkflowTemplateInstantiateResult, type HubWorkflowTemplateParameter, type HubWorkflowTrigger, type HubWorkflowValidateResponse, type HubWorkflowValidationError, HubWorkflowsClient, type VerifyHubEventSignatureInput, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
 //# sourceMappingURL=index.d.ts.map