@tangle-network/hub-sdk 0.22.0-develop.20260814044321.7b71e30 → 0.22.0

package/dist/index.js

@@ -1,7 +1,277 @@
 import { SSEChunkParser } from "@tangle-network/sdk-telemetry";
+//#region src/json-init.ts
+/** The init of a request whose body is JSON. Every client builds its bodies
+* here, so the content type cannot drift from the encoding. */
+function jsonInit(method, body) {
+	return {
+		method,
+		body: JSON.stringify(body),
+		headers: { "Content-Type": "application/json" }
+	};
+}
+//#endregion
+//#region src/allowances.ts
+var HubAllowancesClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	async plan(meter) {
+		return (await this.request(this.path(meter), { method: "GET" })).plan;
+	}
+	async setPlan(meter, plan) {
+		return (await this.request(this.path(meter), this.body("PUT", plan))).plan;
+	}
+	/** Admit one turn or refuse it. Retrying the same `turnId` never counts twice. */
+	async admit(meter, input) {
+		return (await this.request(`${this.path(meter)}/turns`, this.body("POST", input))).allowance;
+	}
+	/** What the member's next turn would get, without counting anything. */
+	async status(meter, subject) {
+		const query = new URLSearchParams();
+		if (subject.role) query.set("role", subject.role);
+		if (subject.payer) query.set("payer", subject.payer);
+		if (subject.payerRole) query.set("payerRole", subject.payerRole);
+		const suffix = query.size ? `?${query}` : "";
+		return (await this.request(`${this.memberPath(meter, subject.member)}${suffix}`, { method: "GET" })).allowance;
+	}
+	/** Move a member to the paid allowance until `expiresAt` (the paid period's end). */
+	async grant(meter, member, input) {
+		return (await this.request(`${this.memberPath(meter, member)}/grant`, this.body("PUT", {
+			tier: "paid",
+			...input
+		}))).grant;
+	}
+	/** Synchronize a paid grant by durable product revision. Null expiry writes
+	* a retained revocation. A delayed older update is refused, never reactivated.
+	* There is no fallback to the unversioned grant endpoint on older servers. */
+	async syncGrant(meter, member, input) {
+		const { grant } = await this.request(`${this.memberPath(meter, member)}/grant/sync`, this.body("PUT", input));
+		if (grant.member !== member || grant.source !== input.source || grant.revision !== input.revision || grant.reference !== input.reference || grant.expiresAt !== (input.expiresAt === null ? null : new Date(input.expiresAt).toISOString())) throw new Error("The Hub returned a mismatched grant synchronization receipt");
+		return grant;
+	}
+	async revoke(meter, member) {
+		await this.request(`${this.memberPath(meter, member)}/grant`, { method: "DELETE" });
+	}
+	/** Turns per member and per line on one UTC day (default today). */
+	async usage(meter, day) {
+		const suffix = day ? `?day=${encodeURIComponent(day)}` : "";
+		return (await this.request(`${this.path(meter)}/usage${suffix}`, { method: "GET" })).usage;
+	}
+	path(meter) {
+		return `/v1/hub/allowances/${encodeURIComponent(meter)}`;
+	}
+	memberPath(meter, member) {
+		return `${this.path(meter)}/members/${encodeURIComponent(member)}`;
+	}
+	body(method, body) {
+		return jsonInit(method, body);
+	}
+};
+//#endregion
+//#region src/apps.ts
+function encodedId(id) {
+	if (typeof id !== "string" || !id || id.length > 256 || id === "." || id === "..") throw new Error("A bounded app or grant id is required");
+	return encodeURIComponent(id);
+}
+var HubAppsClient = class {
+	grants;
+	constructor(request) {
+		this.request = request;
+		this.grants = {
+			list: () => this.request("/v1/me/app-grants", { method: "GET" }),
+			revoke: async (grantId) => this.request(`/v1/me/app-grants/${encodedId(grantId)}/revoke`, { method: "POST" })
+		};
+	}
+	list() {
+		return this.request("/v1/apps", { method: "GET" });
+	}
+	/** The secret is returned only by creation; keep it in your server vault. */
+	create(input) {
+		return this.request("/v1/apps", jsonInit("POST", input));
+	}
+	/** Immutable association of two existing records with the same owner. */
+	async linkOAuthClient(appId, clientId) {
+		return this.request(`/v1/apps/${encodedId(appId)}/oidc-client`, jsonInit("POST", { clientId }));
+	}
+	async revoke(appId) {
+		return this.request(`/v1/apps/${encodedId(appId)}/revoke`, { method: "POST" });
+	}
+};
+//#endregion
+//#region src/inbound-webhooks.ts
+var HubInboundWebhooksClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	async create(connectionId, options = {}) {
+		return this.request(this.path(connectionId), jsonInit("POST", options));
+	}
+	async get(connectionId) {
+		return this.request(this.path(connectionId), { method: "GET" });
+	}
+	/** Add one owned Linq WhatsApp number without rotating the webhook secret. */
+	async ensurePhoneNumber(connectionId, phoneNumberId) {
+		if (!phoneNumberId || phoneNumberId.length > 128 || !/^[\x21-\x7e]+$/.test(phoneNumberId)) throw new Error("A bounded phone-number id is required");
+		return this.request(`${this.path(connectionId)}/phone-numbers/ensure`, jsonInit("POST", { phoneNumberId }));
+	}
+	/** Remove event subscriptions first. This does not silently rotate a live URL. */
+	async delete(connectionId) {
+		return this.request(this.path(connectionId), { method: "DELETE" });
+	}
+	path(connectionId) {
+		if (!connectionId || connectionId.length > 256) throw new Error("A bounded connection id is required");
+		return `/v1/hub/connections/${encodeURIComponent(connectionId)}/inbound-webhook`;
+	}
+};
+//#endregion
+//#region src/line-grants.ts
+function path(binding, suffix = "") {
+	if (!binding.workspaceId || !binding.workspaceAgentId) throw new Error("A workspace and agent are required for a line grant");
+	return `/v1/hub/line-grants/current${suffix}?${new URLSearchParams({
+		workspaceId: binding.workspaceId,
+		workspaceAgentId: binding.workspaceAgentId
+	})}`;
+}
+/** Every call uses HubClient's authHeaders, so one-use app broker tokens can be minted per request. */
+var HubLineGrantsClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	current(binding) {
+		return this.request(path(binding), { method: "GET" });
+	}
+	async line(binding) {
+		return (await this.request(path(binding, "/line"), { method: "GET" })).line;
+	}
+	async attach(binding, input) {
+		return (await this.request(path(binding, "/attachment"), jsonInit("PUT", input))).attachment;
+	}
+	detach(binding) {
+		return this.request(path(binding, "/attachment"), { method: "DELETE" });
+	}
+	async threads(binding) {
+		return (await this.request(path(binding, "/threads"), { method: "GET" })).threads;
+	}
+	async messages(binding, threadId) {
+		if (!threadId || threadId.length > 256) throw new Error("A bounded line thread id is required");
+		return (await this.request(path(binding, `/threads/${encodeURIComponent(threadId)}/messages`), { method: "GET" })).messages;
+	}
+	revoke(binding) {
+		return this.request(path(binding), { method: "DELETE" });
+	}
+};
+//#endregion
+//#region src/lines.ts
+/** Line calls share HubClient authentication and envelope handling. */
+var HubLinesClient = class {
+	members;
+	checkins;
+	constructor(request, createWorkflow) {
+		this.request = request;
+		this.createWorkflow = createWorkflow;
+		this.members = { list: async (lineId) => (await this.request(`/v1/hub/lines/${encodeURIComponent(lineId)}/members`, { method: "GET" })).members };
+		this.checkins = { schedule: (cron, options) => {
+			const name = options.name ?? `line-checkin-${crypto.randomUUID().slice(0, 8)}`;
+			const yaml = [
+				`name: ${JSON.stringify(name)}`,
+				"on:",
+				`  schedule: { cron: ${JSON.stringify(cron)}, timezone: ${JSON.stringify(options.timezone)} }`,
+				"do:",
+				"  - agent.run:",
+				"      line:",
+				`        id: ${JSON.stringify(options.lineId)}`,
+				`        member: ${JSON.stringify(options.member)}`,
+				`      prompt: ${JSON.stringify(options.prompt)}`
+			].join("\n");
+			return this.createWorkflow(yaml);
+		} };
+	}
+	async scheduleSend(cron, options) {
+		const name = options.name ?? `line-send-${crypto.randomUUID().slice(0, 8)}`;
+		const yaml = [
+			`name: ${JSON.stringify(name)}`,
+			"on:",
+			`  schedule: { cron: ${JSON.stringify(cron)}, timezone: ${JSON.stringify(options.timezone)} }`,
+			"do:",
+			"  - line.send:",
+			`      lineId: ${JSON.stringify(options.lineId)}`,
+			`      memberId: ${JSON.stringify(options.memberId)}`,
+			`      text: ${JSON.stringify(options.text)}`,
+			...options.notBefore ? [`      notBefore: ${JSON.stringify(options.notBefore)}`] : []
+		].join("\n");
+		return this.createWorkflow(yaml);
+	}
+	async context() {
+		return this.request("/v1/hub/lines/context", { method: "GET" });
+	}
+	async send(lineId, input) {
+		return this.request(`/v1/hub/lines/${encodeURIComponent(lineId)}/send`, jsonInit("POST", input));
+	}
+	async remind(lineId, input) {
+		return this.request(`/v1/hub/lines/${encodeURIComponent(lineId)}/remind`, jsonInit("POST", input));
+	}
+};
+//#endregion
+//#region src/managed-numbers.ts
+/** Administrative number operations through Hub's authenticated transport.
+* A mutation is one attempt; an uncertain create reuses its quote and reference. */
+var HubManagedNumbersClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	readiness() {
+		return this.request("/v1/hub/numbers/readiness", { method: "GET" });
+	}
+	/** One page of orders. Scope by `clientReference` to ask about one binding,
+	* and follow `nextCursor` for the rest; a page is never ownership evidence. */
+	list(query = {}) {
+		const params = new URLSearchParams();
+		if (query.clientReference !== void 0) params.set("clientReference", query.clientReference);
+		if (query.cursor !== void 0) params.set("cursor", query.cursor);
+		if (query.limit !== void 0) params.set("limit", String(query.limit));
+		const search = params.toString();
+		return this.request(`/v1/hub/numbers${search ? `?${search}` : ""}`, { method: "GET" });
+	}
+	get(id) {
+		return this.request(this.path(id), { method: "GET" });
+	}
+	quote(input) {
+		return this.request("/v1/hub/numbers/quote", this.post(input));
+	}
+	/** `clientReference` and `transport`, when given, must match the signed
+	* quote or Hub refuses the purchase with a conflict. */
+	create(input) {
+		return this.request("/v1/hub/numbers", this.post(input));
+	}
+	/** Fences references so no order can take them again. Call it as the last
+	* step before retiring the resource they name: a purchase that races the
+	* retirement is then refused (`409 number_reference_fenced`) instead of
+	* binding a line to a resource that is gone. Refused with
+	* `409 number_reference_held` while a live order holds one of them; cancel
+	* it first. A cancelled order no longer holds its reference, so the fence
+	* succeeds as soon as `cancel` returns, whether or not its release is still
+	* pending. Repeating a fence is harmless. */
+	fence(input) {
+		return this.request("/v1/hub/numbers/fences", this.post(input));
+	}
+	advance(id) {
+		return this.request(`${this.path(id)}/advance`, this.post({}));
+	}
+	cancel(id) {
+		return this.request(`${this.path(id)}/cancel`, this.post({}));
+	}
+	path(id) {
+		if (!/^num_[a-f0-9]{36}$/.test(id)) throw new Error("Invalid managed number order id");
+		return `/v1/hub/numbers/${encodeURIComponent(id)}`;
+	}
+	post(body) {
+		return jsonInit("POST", body);
+	}
+};
+//#endregion
 //#region src/redaction.ts
 const SECRET_KEY_PATTERN = /(api[_-]?key|authorization|capability[_-]?token|token|secret)/i;
-const SECRET_VALUE_PATTERN = /\b(?:sk-tan[-_]|hubcap_|hct_|gh[pousr]_)[A-Za-z0-9_=-]+\b/g;
+const SECRET_VALUE_PATTERN = /\b(?:sk-tan[-_]|hubcap_|hct_|lrc_|gh[pousr]_)[A-Za-z0-9_.=-]+\b/g;
 function redactHubValue(value) {
 	if (typeof value === "string") return value.replace(SECRET_VALUE_PATTERN, "[REDACTED]");
 	if (Array.isArray(value)) return value.map((item) => redactHubValue(item));
@@ -52,8 +322,10 @@ function isHubSuccessEnvelope(value) {
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
-function optString(value) {
-	return typeof value === "string" ? value : "";
+/** Read a wire field as a string, or "" when the server sent anything else.
+*  `raw` is that field straight off the parsed payload, before any check. */
+function optString(raw) {
+	return typeof raw === "string" ? raw : "";
 }
 /** An agent iteration's terminal status (`iteration.ended`) — only ever
 *  succeeded/failed; an iteration is never guard-skipped. */
@@ -81,63 +353,63 @@ function isRunDoneStatus(value) {
 * malformed `token` can never reach a consumer as `{ delta: undefined }`, and
 * new server event kinds don't break older clients.
 */
-function toRunStreamEvent(eventType, data) {
+function toRunStreamEvent(eventType, raw) {
 	if (eventType === "ping") return { type: "ping" };
-	if (!isRecord$1(data)) return null;
+	if (!isRecord$1(raw)) return null;
 	switch (eventType) {
-		case "snapshot": return typeof data.id === "string" && typeof data.workflowId === "string" && typeof data.status === "string" && Array.isArray(data.actionResults) ? {
+		case "snapshot": return typeof raw.id === "string" && typeof raw.workflowId === "string" && typeof raw.status === "string" && Array.isArray(raw.actionResults) ? {
 			type: "snapshot",
-			run: data
+			run: raw
 		} : null;
-		case "token": return typeof data.delta === "string" && typeof data.actionIndex === "number" ? {
+		case "token": return typeof raw.delta === "string" && typeof raw.actionIndex === "number" ? {
 			type: "token",
-			actionIndex: data.actionIndex,
-			delta: data.delta,
-			at: optString(data.at)
+			actionIndex: raw.actionIndex,
+			delta: raw.delta,
+			at: optString(raw.at)
 		} : null;
-		case "run.done": return isRunDoneStatus(data.status) ? {
+		case "run.done": return isRunDoneStatus(raw.status) ? {
 			type: "run.done",
-			status: data.status,
-			error: typeof data.error === "string" ? data.error : null,
-			...typeof data.at === "string" ? { at: data.at } : {}
+			status: raw.status,
+			error: typeof raw.error === "string" ? raw.error : null,
+			...typeof raw.at === "string" ? { at: raw.at } : {}
 		} : null;
-		case "run.waiting": return typeof data.decisionId === "string" && data.decisionId.length > 0 ? {
+		case "run.waiting": return typeof raw.decisionId === "string" && raw.decisionId.length > 0 ? {
 			type: "run.waiting",
-			decisionId: data.decisionId,
-			...typeof data.at === "string" ? { at: data.at } : {}
+			decisionId: raw.decisionId,
+			...typeof raw.at === "string" ? { at: raw.at } : {}
 		} : null;
-		case "action.started": return typeof data.index === "number" && typeof data.kind === "string" && typeof data.at === "string" ? {
+		case "action.started": return typeof raw.index === "number" && typeof raw.kind === "string" && typeof raw.at === "string" ? {
 			type: "action.started",
-			index: data.index,
-			kind: data.kind,
-			at: data.at
+			index: raw.index,
+			kind: raw.kind,
+			at: raw.at
 		} : null;
-		case "action.finished": return typeof data.index === "number" && typeof data.kind === "string" && isActionFinishedStatus(data.status) && typeof data.at === "string" ? {
+		case "action.finished": return typeof raw.index === "number" && typeof raw.kind === "string" && isActionFinishedStatus(raw.status) && typeof raw.at === "string" ? {
 			type: "action.finished",
-			index: data.index,
-			kind: data.kind,
-			status: data.status,
-			at: data.at,
-			...typeof data.costUsd === "number" ? { costUsd: data.costUsd } : {},
-			...typeof data.error === "string" ? { error: data.error } : {}
+			index: raw.index,
+			kind: raw.kind,
+			status: raw.status,
+			at: raw.at,
+			...typeof raw.costUsd === "number" ? { costUsd: raw.costUsd } : {},
+			...typeof raw.error === "string" ? { error: raw.error } : {}
 		} : null;
-		case "iteration.started": return typeof data.actionIndex === "number" && typeof data.iterationIndex === "number" && typeof data.at === "string" ? {
+		case "iteration.started": return typeof raw.actionIndex === "number" && typeof raw.iterationIndex === "number" && typeof raw.at === "string" ? {
 			type: "iteration.started",
-			actionIndex: data.actionIndex,
-			iterationIndex: data.iterationIndex,
-			at: data.at,
-			...typeof data.model === "string" ? { model: data.model } : {}
+			actionIndex: raw.actionIndex,
+			iterationIndex: raw.iterationIndex,
+			at: raw.at,
+			...typeof raw.model === "string" ? { model: raw.model } : {}
 		} : null;
-		case "iteration.ended": return typeof data.actionIndex === "number" && typeof data.iterationIndex === "number" && isIterationStatus(data.status) && typeof data.at === "string" ? {
+		case "iteration.ended": return typeof raw.actionIndex === "number" && typeof raw.iterationIndex === "number" && isIterationStatus(raw.status) && typeof raw.at === "string" ? {
 			type: "iteration.ended",
-			actionIndex: data.actionIndex,
-			iterationIndex: data.iterationIndex,
-			status: data.status,
-			at: data.at,
-			...typeof data.outputPreview === "string" ? { outputPreview: data.outputPreview } : {},
-			...typeof data.inputTokens === "number" ? { inputTokens: data.inputTokens } : {},
-			...typeof data.outputTokens === "number" ? { outputTokens: data.outputTokens } : {},
-			...typeof data.costUsd === "number" ? { costUsd: data.costUsd } : {}
+			actionIndex: raw.actionIndex,
+			iterationIndex: raw.iterationIndex,
+			status: raw.status,
+			at: raw.at,
+			...typeof raw.outputPreview === "string" ? { outputPreview: raw.outputPreview } : {},
+			...typeof raw.inputTokens === "number" ? { inputTokens: raw.inputTokens } : {},
+			...typeof raw.outputTokens === "number" ? { outputTokens: raw.outputTokens } : {},
+			...typeof raw.costUsd === "number" ? { costUsd: raw.costUsd } : {}
 		} : null;
 		default: return null;
 	}
@@ -145,8 +417,8 @@ function toRunStreamEvent(eventType, data) {
 /** True for an aborted/timed-out fetch (or any abort). fetch rejects with the
 *  signal's reason — a DOMException named `AbortError` (caller) or `TimeoutError`
 *  (AbortSignal.timeout). */
-function isAbortError(err) {
-	return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+function isAbortError(cause) {
+	return cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError");
 }
 /** A signal that aborts when the caller's signal aborts OR `timeoutMs` elapses.
 *  Returns undefined when neither bound applies (no per-request abort needed). */
@@ -225,8 +497,11 @@ var HubClient = class HubClient {
 	fetch;
 	apiKey;
 	authHeaders;
+	allowances;
+	apps;
 	connections;
 	channels;
+	numbers;
 	eventSubscriptions;
 	permissions;
 	tokens;
@@ -235,11 +510,17 @@ var HubClient = class HubClient {
 	audit;
 	githubApp;
 	workflows;
+	lines;
+	lineGrants;
 	constructor(options) {
 		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
 		this.apiKey = options.apiKey;
 		this.authHeaders = options.authHeaders;
 		this.fetch = options.fetch ?? fetch.bind(globalThis);
+		this.allowances = new HubAllowancesClient((path, init) => this.request(path, init));
+		this.apps = new HubAppsClient((path, init) => this.request(path, init));
+		this.lineGrants = new HubLineGrantsClient((path, init) => this.request(path, init));
+		this.numbers = new HubManagedNumbersClient((path, init) => this.request(path, init));
 		this.connections = new HubConnectionsClient((path, init) => this.request(path, init));
 		this.channels = new HubChannelsClient((path, init) => this.request(path, init));
 		this.eventSubscriptions = new HubEventSubscriptionsClient((path, init) => this.request(path, init));
@@ -250,6 +531,7 @@ var HubClient = class HubClient {
 		this.audit = new HubAuditClient((path, init) => this.request(path, init));
 		this.githubApp = new HubGithubAppClient((path, init) => this.request(path, init));
 		this.workflows = new HubWorkflowsClient((path, init) => this.request(path, init), (path, init) => this.stream(path, init), (path, init) => this.requestBytes(path, init));
+		this.lines = new HubLinesClient((path, init) => this.request(path, init), (yaml) => this.workflows.create(yaml));
 	}
 	static fromEnv(options = {}) {
 		const env = options.env ?? readProcessEnv();
@@ -362,11 +644,7 @@ var HubTokensClient = class {
 		this.request = request;
 	}
 	async mint(options) {
-		return this.request("/v1/hub/tokens", {
-			method: "POST",
-			body: JSON.stringify(options),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/tokens", jsonInit("POST", options));
 	}
 	async list(options = {}) {
 		const searchParams = new URLSearchParams();
@@ -400,38 +678,22 @@ var HubPermissionsClient = class {
 		return this.request(`/v1/hub/policies?connectionId=${encodeURIComponent(connectionId)}`, { method: "GET" });
 	}
 	async set(input) {
-		return this.request("/v1/hub/policies", {
-			method: "PUT",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/policies", jsonInit("PUT", input));
 	}
 	/** Reset an action to its default by deleting any stored override. */
 	async delete(input) {
-		return this.request("/v1/hub/policies", {
-			method: "DELETE",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/policies", jsonInit("DELETE", input));
 	}
 	/** Bulk-allow every write action of a connection's provider. Reads are
 	*  already allowed for sandbox agents; destructive actions stay `ask`.
 	*  Idempotent: actions with an existing policy are left untouched. */
 	async allowWrites(connectionId) {
-		return this.request("/v1/hub/policies/allow-writes", {
-			method: "POST",
-			body: JSON.stringify({ connectionId }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/policies/allow-writes", jsonInit("POST", { connectionId }));
 	}
 	/** Inverse of `allowWrites`: delete only the rows it created for this
 	*  connection. Manual per-action decisions are left intact. */
 	async revertWrites(connectionId) {
-		return this.request("/v1/hub/policies/revert-writes", {
-			method: "POST",
-			body: JSON.stringify({ connectionId }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/policies/revert-writes", jsonInit("POST", { connectionId }));
 	}
 };
 var HubToolsClient = class {
@@ -439,34 +701,32 @@ var HubToolsClient = class {
 		this.request = request;
 	}
 	async search(query, options = {}) {
-		return this.request("/v1/hub/tools/search", {
-			method: "POST",
-			body: JSON.stringify({
-				query,
-				provider: options.provider,
-				limit: options.limit
-			}),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/tools/search", jsonInit("POST", {
+			query,
+			provider: options.provider,
+			limit: options.limit
+		}));
 	}
 	async sources() {
 		return this.request("/v1/hub/tools/sources", { method: "GET" });
 	}
 	async describe(path) {
-		return this.request("/v1/hub/tools/describe", {
-			method: "POST",
-			body: JSON.stringify({ path }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/tools/describe", jsonInit("POST", { path }));
 	}
-	async invoke(path, input, options = {}) {
-		const execInit = this.buildExecInit(path, input, options.connectionId);
+	/**
+	* 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.
+	*/
+	async invoke(path, raw, options = {}) {
+		const execInit = this.buildExecInit(path, raw, options);
 		try {
 			return await this.request("/v1/hub/exec", execInit);
 		} catch (error) {
 			if (!(error instanceof HubSdkError) || !requiresCapabilityToken(error)) throw error;
+			const approvalId = getApprovalId(error);
+			if (approvalId && options.approve !== true) throw error;
 			if (options.approve) {
-				const approvalId = getApprovalId(error);
 				if (!approvalId) throw error;
 				const approved = await this.request(`/v1/hub/approvals/${encodeURIComponent(approvalId)}/approve`, { method: "POST" });
 				validateApprovedExecution(approved, path, options.connectionId);
@@ -484,15 +744,11 @@ var HubToolsClient = class {
 				});
 			}
 		}
-		const minted = await this.request("/v1/hub/tokens", {
-			method: "POST",
-			body: JSON.stringify({
-				actionPath: path,
-				connectionId: options.connectionId,
-				provider: options.connectionId ? void 0 : path.split(".")[0]
-			}),
-			headers: { "Content-Type": "application/json" }
-		});
+		const minted = await this.request("/v1/hub/tokens", jsonInit("POST", {
+			actionPath: path,
+			connectionId: options.connectionId,
+			provider: options.connectionId ? void 0 : path.split(".")[0]
+		}));
 		return this.request("/v1/hub/exec", {
 			...execInit,
 			headers: {
@@ -501,16 +757,13 @@ var HubToolsClient = class {
 			}
 		});
 	}
-	buildExecInit(path, input, connectionId) {
-		return {
-			method: "POST",
-			body: JSON.stringify({
-				path,
-				input,
-				connectionId
-			}),
-			headers: { "Content-Type": "application/json" }
-		};
+	buildExecInit(path, raw, options) {
+		return jsonInit("POST", {
+			path,
+			input: raw,
+			connectionId: options.connectionId,
+			idempotencyKey: options.idempotencyKey
+		});
 	}
 };
 function requiresCapabilityToken(error) {
@@ -540,6 +793,17 @@ function validateApprovedExecution(approved, path, connectionId) {
 		}
 	});
 }
+const GITHUB_EXACT_CONNECT_SCOPES = [
+	"read:user",
+	"repo",
+	"read:org"
+];
+function sameOAuthScopeSet(left, right) {
+	if (!Array.isArray(left)) return false;
+	const leftSet = new Set(left);
+	const rightSet = new Set(right);
+	return leftSet.size === left.length && rightSet.size === right.length && leftSet.size === rightSet.size && [...leftSet].every((scope) => rightSet.has(scope));
+}
 var HubChannelsClient = class {
 	constructor(request) {
 		this.request = request;
@@ -548,11 +812,7 @@ var HubChannelsClient = class {
 		return this.request("/v1/hub/channels", { method: "GET" });
 	}
 	async createEmail(input = {}) {
-		return this.request("/v1/hub/channels/email", {
-			method: "POST",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/channels/email", jsonInit("POST", input));
 	}
 	async delete(channelId) {
 		return this.request(`/v1/hub/channels/${encodeURIComponent(channelId)}`, { method: "DELETE" });
@@ -566,19 +826,17 @@ var HubEventSubscriptionsClient = class {
 		return this.request("/v1/hub/event-subscriptions", { method: "GET" });
 	}
 	async create(input) {
-		return this.request("/v1/hub/event-subscriptions", {
-			method: "POST",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/event-subscriptions", jsonInit("POST", input));
 	}
 	async delete(subscriptionId) {
 		return this.request(`/v1/hub/event-subscriptions/${encodeURIComponent(subscriptionId)}`, { method: "DELETE" });
 	}
 };
 var HubConnectionsClient = class {
+	inboundWebhook;
 	constructor(request) {
 		this.request = request;
+		this.inboundWebhook = new HubInboundWebhooksClient(request);
 	}
 	async list() {
 		return this.request("/v1/hub/connections", { method: "GET" });
@@ -590,40 +848,38 @@ var HubConnectionsClient = class {
 		return this.request("/v1/hub/providers", { method: "GET" });
 	}
 	async start(provider, options = {}) {
-		return this.request(`/v1/hub/connections/${encodeURIComponent(provider)}/start`, {
-			method: "POST",
-			body: JSON.stringify({
-				returnUrl: options.returnUrl,
-				cli: options.cli,
-				connectionParameters: options.connectionParameters
-			}),
-			headers: { "Content-Type": "application/json" }
+		if (options.requestedScopes !== void 0 && (provider !== "github" || !sameOAuthScopeSet(options.requestedScopes, GITHUB_EXACT_CONNECT_SCOPES))) throw new HubSdkError({
+			code: "HUB_INVALID_INPUT",
+			message: "GitHub requestedScopes must be read:user, repo, and read:org"
+		});
+		const started = await this.request(`/v1/hub/connections/${encodeURIComponent(provider)}/start`, jsonInit("POST", {
+			returnUrl: options.returnUrl,
+			cli: options.cli,
+			connectionParameters: options.connectionParameters,
+			requestedScopes: options.requestedScopes
+		}));
+		if (options.requestedScopes !== void 0 && (started.provider !== provider || !sameOAuthScopeSet(started.scopes, options.requestedScopes))) throw new HubSdkError({
+			code: "HUB_CONFIG_MISSING",
+			message: "Hub did not preserve the requested OAuth scopes"
 		});
+		return started;
 	}
 	async startWhatsappEmbeddedSignup(options = {}) {
-		return this.request("/v1/hub/connections/whatsapp-business/embedded-signup/start", {
-			method: "POST",
-			body: JSON.stringify({ returnUrl: options.returnUrl }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/connections/whatsapp-business/embedded-signup/start", jsonInit("POST", { returnUrl: options.returnUrl }));
 	}
 	async completeWhatsappEmbeddedSignup(input) {
-		return this.request("/v1/hub/connections/whatsapp-business/embedded-signup/complete", {
-			method: "POST",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/connections/whatsapp-business/embedded-signup/complete", jsonInit("POST", input));
 	}
 	/** 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`. */
-	async connectApiKey(provider, apiKey) {
-		return this.request(`/v1/hub/connections/${encodeURIComponent(provider)}/connect-key`, {
-			method: "POST",
-			body: JSON.stringify({ apiKey }),
-			headers: { "Content-Type": "application/json" }
-		});
+	*  unlike `start`. Cloudbeds requires propertyId metadata and PriceLabs
+	*  requires listing ID/PMS pairs; other providers have no metadata. */
+	async connectApiKey(provider, apiKey, metadata) {
+		return this.request(`/v1/hub/connections/${encodeURIComponent(provider)}/connect-key`, jsonInit("POST", {
+			apiKey,
+			...metadata === void 0 ? {} : { metadata }
+		}));
 	}
 	async revoke(connectionId) {
 		return this.request(`/v1/hub/connections/${encodeURIComponent(connectionId)}`, { method: "DELETE" });
@@ -651,11 +907,7 @@ var HubGithubAppClient = class {
 		this.request = request;
 	}
 	async mintInstallationToken(input) {
-		return this.request("/v1/hub/github-app/mint-installation-token", {
-			method: "POST",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/hub/github-app/mint-installation-token", jsonInit("POST", input));
 	}
 	/** Every installation the caller may act through — their own and any org's
 	*  they were verified against. The management surface's read. */
@@ -730,11 +982,7 @@ var HubWorkflowsClient = class {
 		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, { method: "GET" });
 	}
 	async create(yaml) {
-		return this.request("/v1/workflows", {
-			method: "POST",
-			body: JSON.stringify({ yaml }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/workflows", jsonInit("POST", { yaml }));
 	}
 	/**
 	* Replace the workflow's definition from YAML (recompiled server-side,
@@ -745,14 +993,10 @@ var HubWorkflowsClient = class {
 	* concurrent modification, `NOT_FOUND` for an unknown/foreign id.
 	*/
 	async update(id, yaml, opts = {}) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, {
-			method: "PUT",
-			body: JSON.stringify({
-				yaml,
-				...opts.note !== void 0 ? { note: opts.note } : {}
-			}),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, jsonInit("PUT", {
+			yaml,
+			...opts.note !== void 0 ? { note: opts.note } : {}
+		}));
 	}
 	async delete(id) {
 		await this.request(`/v1/workflows/${encodeURIComponent(id)}`, { method: "DELETE" });
@@ -763,11 +1007,7 @@ var HubWorkflowsClient = class {
 	* via `update`, but it can still be paused/resumed here).
 	*/
 	async setEnabled(id, enabled) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, {
-			method: "PATCH",
-			body: JSON.stringify({ enabled }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, jsonInit("PATCH", { enabled }));
 	}
 	/**
 	* One page of run history, newest first. Pass the previous page's
@@ -795,9 +1035,7 @@ var HubWorkflowsClient = class {
 	async run(id, inputs, opts = {}) {
 		const hasInputs = inputs !== void 0 && Object.keys(inputs).length > 0;
 		return this.request(`/v1/workflows/${encodeURIComponent(id)}/run`, {
-			method: "POST",
-			body: JSON.stringify(hasInputs ? { inputs } : {}),
-			headers: { "Content-Type": "application/json" },
+			...jsonInit("POST", hasInputs ? { inputs } : {}),
 			...opts.signal ? { signal: opts.signal } : {}
 		});
 	}
@@ -976,11 +1214,7 @@ var HubWorkflowsClient = class {
 	* YAML no longer compiles, `CONFLICT` on a concurrent modification.
 	*/
 	async rollback(id, rev) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/rollback`, {
-			method: "POST",
-			body: JSON.stringify({ rev }),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/rollback`, jsonInit("POST", { rev }));
 	}
 	/**
 	* Deterministic health stats over the workflow's last N terminal runs
@@ -1001,11 +1235,7 @@ var HubWorkflowsClient = class {
 	* until an owner approves.
 	*/
 	async propose(id, input) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals`, {
-			method: "POST",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals`, jsonInit("POST", input));
 	}
 	/**
 	* Pending (proposed) and declined (rejected) revisions, newest first, with
@@ -1032,11 +1262,7 @@ var HubWorkflowsClient = class {
 	* pending proposal.
 	*/
 	async rejectProposal(id, rev, opts = {}) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals/${encodeURIComponent(String(rev))}/reject`, {
-			method: "POST",
-			body: JSON.stringify(opts.reason !== void 0 ? { reason: opts.reason } : {}),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/proposals/${encodeURIComponent(String(rev))}/reject`, jsonInit("POST", opts.reason !== void 0 ? { reason: opts.reason } : {}));
 	}
 	/**
 	* Mint a fresh webhook hook token, retiring the current one immediately.
@@ -1112,29 +1338,24 @@ var HubWorkflowsClient = class {
 	/**
 	* 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.
 	*/
-	async putKv(id, key, value) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}`, {
-			method: "PUT",
-			body: JSON.stringify({ value }),
-			headers: { "Content-Type": "application/json" }
-		});
+	async putKv(id, key, raw) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}`, jsonInit("PUT", { value: raw }));
 	}
 	/**
 	* 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.
 	*/
-	async casKv(id, key, expectedVersion, value) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}/cas`, {
-			method: "POST",
-			body: JSON.stringify({
-				expectedVersion,
-				value
-			}),
-			headers: { "Content-Type": "application/json" }
-		});
+	async casKv(id, key, expectedVersion, raw) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}/cas`, jsonInit("POST", {
+			expectedVersion,
+			value: raw
+		}));
 	}
 	/** Delete a key; idempotent — `deleted` reports whether a row was removed. */
 	async deleteKv(id, key) {
@@ -1154,11 +1375,7 @@ var HubWorkflowsClient = class {
 	* (400); an unknown template id throws `NOT_FOUND`.
 	*/
 	async instantiateTemplate(templateId, parameters) {
-		return this.request(`/v1/workflows/templates/${encodeURIComponent(templateId)}/instantiate`, {
-			method: "POST",
-			body: JSON.stringify(parameters ? { parameters } : {}),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/templates/${encodeURIComponent(templateId)}/instantiate`, jsonInit("POST", parameters ? { parameters } : {}));
 	}
 	/**
 	* The caller's open decisions across all workflows — the always-available
@@ -1185,11 +1402,7 @@ var HubWorkflowsClient = class {
 	* (409 — answered, timed out, or cancelled first).
 	*/
 	async resolveRunDecision(id, runId, input) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/decision/resolve`, {
-			method: "POST",
-			body: JSON.stringify(input),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/decision/resolve`, jsonInit("POST", input));
 	}
 	/**
 	* Dry-run a YAML definition against the platform compiler without saving it.
@@ -1202,14 +1415,10 @@ var HubWorkflowsClient = class {
 	* the unconnected providers is the point.
 	*/
 	async validate(yaml, opts = {}) {
-		return this.request("/v1/workflows/validate", {
-			method: "POST",
-			body: JSON.stringify({
-				yaml,
-				...opts.structural ? { structural: true } : {}
-			}),
-			headers: { "Content-Type": "application/json" }
-		});
+		return this.request("/v1/workflows/validate", jsonInit("POST", {
+			yaml,
+			...opts.structural ? { structural: true } : {}
+		}));
 	}
 	async schema() {
 		return this.request("/v1/workflows/schema", { method: "GET" });
@@ -1473,6 +1682,6 @@ function requestFailure(code, status, error, headers) {
 	};
 }
 //#endregion
-export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, HubApprovalsClient, HubAuditClient, HubChannelsClient, HubClient, HubConnectionsClient, HubEventDeliveryError, HubEventSubscriptionsClient, HubGithubAppClient, HubPermissionsClient, HubSdkError, HubTokensClient, HubToolsClient, HubWorkflowsClient, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
+export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, HubAllowancesClient, HubApprovalsClient, HubAppsClient, HubAuditClient, HubChannelsClient, HubClient, HubConnectionsClient, HubEventDeliveryError, HubEventSubscriptionsClient, HubGithubAppClient, HubInboundWebhooksClient, HubLineGrantsClient, HubLinesClient, HubManagedNumbersClient, HubPermissionsClient, HubSdkError, HubTokensClient, HubToolsClient, HubWorkflowsClient, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
 
 //# sourceMappingURL=index.js.map