@tangle-network/hub-sdk 0.29.0-develop.20260819122040.176c418 → 0.29.0

package/dist/index.js

@@ -1,7 +1,284 @@
 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/knowledge.ts
+/** Runtime-only retrieval. The authenticated sandbox credential determines the
+* scope on the server; neither a caller nor an agent can supply another scope. */
+var HubKnowledgeClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	query(input, options) {
+		return this.request("/v1/knowledge/runtime/query", {
+			...jsonInit("POST", {
+				query: input.query,
+				...input.limit !== void 0 ? { limit: input.limit } : {}
+			}),
+			signal: options?.signal
+		});
+	}
+};
+//#endregion
+//#region src/lines.ts
+/** The `on.schedule` mapping a Line schedule helper writes. */
+function scheduleYaml(cron, timezone, until) {
+	return `  schedule: { ${[
+		`cron: ${JSON.stringify(cron)}`,
+		`timezone: ${JSON.stringify(timezone)}`,
+		...until ? [`until: ${JSON.stringify(until)}`] : []
+	].join(", ")} }`;
+}
+/** Line calls share HubClient authentication and envelope handling. */
+var HubLinesClient = class {
+	members;
+	memberApplications;
+	checkins;
+	constructor(request, createWorkflow, requestApplicationDispatchCurrent) {
+		this.request = request;
+		this.createWorkflow = createWorkflow;
+		this.requestApplicationDispatchCurrent = requestApplicationDispatchCurrent;
+		this.members = { list: async (lineId) => (await this.request(`/v1/hub/lines/${encodeURIComponent(lineId)}/members`, { method: "GET" })).members };
+		const applicationPath = (lineId, memberId) => `/v1/hub/lines/${encodeURIComponent(lineId)}/members/${encodeURIComponent(memberId)}/application`;
+		this.memberApplications = {
+			get: async (lineId, memberId) => await this.request(applicationPath(lineId, memberId), { method: "GET" }),
+			select: async (lineId, memberId, input) => (await this.request(applicationPath(lineId, memberId), jsonInit("PUT", input))).selection,
+			clear: async (lineId, memberId, input) => {
+				await this.request(applicationPath(lineId, memberId), jsonInit("DELETE", input));
+			}
+		};
+		this.checkins = { schedule: (cron, options) => {
+			const name = options.name ?? `line-checkin-${crypto.randomUUID().slice(0, 8)}`;
+			const yaml = [
+				`name: ${JSON.stringify(name)}`,
+				"on:",
+				scheduleYaml(cron, options.timezone, options.until),
+				"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:",
+			scheduleYaml(cron, options.timezone, options.until),
+			"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));
+	}
+	/** Read an owner send's receipt, including its coded answer. Queued is not delivered. */
+	async sentMessage(lineId, messageId) {
+		return this.request(`/v1/hub/lines/${encodeURIComponent(lineId)}/outbox/${encodeURIComponent(messageId)}`, { method: "GET" });
+	}
+	async remind(lineId, input) {
+		return this.request(`/v1/hub/lines/${encodeURIComponent(lineId)}/remind`, jsonInit("POST", input));
+	}
+	async applicationDispatchCurrent(lineId, messageId, input, callbackBearer) {
+		if (!this.requestApplicationDispatchCurrent) throw new Error("Use HubClient to check application dispatch authority");
+		return (await this.requestApplicationDispatchCurrent(`/v1/hub/lines/${encodeURIComponent(lineId)}/messages/${encodeURIComponent(messageId)}/application-dispatch/current`, jsonInit("POST", input), callbackBearer)).current;
+	}
+};
+//#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));
@@ -26,16 +303,18 @@ function bodySnippet(body, max = 200) {
 	const trimmed = body.trim();
 	return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
 }
-function httpError(path, status, statusText, body, contentType) {
-	const suffix = statusText ? ` ${statusText}` : "";
+function httpError(path, status, statusText, body, contentType, omitResponseDetails = false) {
+	const suffix = !omitResponseDetails && statusText ? ` ${statusText}` : "";
 	return new HubSdkError({
 		code: `HUB_HTTP_${status}`,
 		message: `Hub request ${path} failed: HTTP ${status}${suffix}`,
 		details: {
 			status,
 			path,
-			contentType: contentType || null,
-			bodySnippet: bodySnippet(body)
+			...omitResponseDetails ? {} : {
+				contentType: contentType || null,
+				bodySnippet: bodySnippet(body)
+			}
 		}
 	}, { status });
 }
@@ -52,6 +331,9 @@ function isHubSuccessEnvelope(value) {
 function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
+function isDispatchCurrentData(value) {
+	return isRecord$1(value) && typeof value.current === "boolean";
+}
 /** 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) {
@@ -222,13 +504,69 @@ function nonEmpty(value) {
 function readProcessEnv() {
 	return globalThis.process?.env ?? {};
 }
-var HubClient = class HubClient {
+var HubTransport = class {
 	baseUrl;
 	fetch;
 	apiKey;
 	authHeaders;
+	constructor(options) {
+		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.apiKey = options.apiKey;
+		this.authHeaders = options.authHeaders;
+		this.fetch = options.fetch ?? fetch.bind(globalThis);
+	}
+	async request(path, init, options = {}) {
+		const callerAuth = options.auth === "caller";
+		const response = await this.fetch(`${this.baseUrl}${path}`, {
+			...init,
+			headers: await this.buildHeaders(init.headers, callerAuth)
+		});
+		const status = response.status;
+		const contentType = response.headers.get("content-type") ?? "";
+		const bodyText = await response.text();
+		if (!contentType.includes("application/json")) throw httpError(path, status, response.statusText, bodyText, contentType, callerAuth);
+		let parsed;
+		try {
+			parsed = JSON.parse(bodyText);
+		} catch {
+			throw httpError(path, status, response.statusText, bodyText, contentType, callerAuth);
+		}
+		if (isHubErrorEnvelope(parsed)) {
+			if (callerAuth) throw new HubSdkError({
+				code: parsed.error.code,
+				message: `Hub request ${path} failed: HTTP ${status}`
+			}, { status });
+			throw new HubSdkError(parsed.error, { status });
+		}
+		if (isHubSuccessEnvelope(parsed)) {
+			if (callerAuth && !response.ok) throw httpError(path, status, response.statusText, bodyText, contentType, callerAuth);
+			if (options.validateData && !options.validateData(parsed.data)) throw new HubSdkError({
+				code: `HUB_HTTP_${status}`,
+				message: `Hub request ${path} returned invalid data`,
+				details: {
+					status,
+					path
+				}
+			}, { status });
+			return parsed.data;
+		}
+		throw httpError(path, status, response.statusText, bodyText, contentType, callerAuth);
+	}
+	async buildHeaders(headers, callerAuth = false) {
+		const mergedHeaders = new Headers({ Accept: "application/json" });
+		if (!callerAuth && this.apiKey) mergedHeaders.set("Authorization", `Bearer ${this.apiKey}`);
+		if (!callerAuth && this.authHeaders) for (const [key, value] of new Headers(await this.authHeaders())) mergedHeaders.set(key, value);
+		for (const [key, value] of new Headers(headers)) mergedHeaders.set(key, value);
+		return mergedHeaders;
+	}
+};
+var HubClient = class HubClient extends HubTransport {
+	knowledge;
+	allowances;
+	apps;
 	connections;
 	channels;
+	numbers;
 	eventSubscriptions;
 	permissions;
 	tokens;
@@ -237,11 +575,13 @@ var HubClient = class HubClient {
 	audit;
 	githubApp;
 	workflows;
+	lines;
 	constructor(options) {
-		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
-		this.apiKey = options.apiKey;
-		this.authHeaders = options.authHeaders;
-		this.fetch = options.fetch ?? fetch.bind(globalThis);
+		super(options);
+		this.knowledge = new HubKnowledgeClient((path, init) => this.request(path, init));
+		this.allowances = new HubAllowancesClient((path, init) => this.request(path, init));
+		this.apps = new HubAppsClient((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));
@@ -252,6 +592,23 @@ 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), (path, init, callbackBearer) => {
+			if (typeof callbackBearer !== "string" || !/^[\x21-\x7e]{16,512}$/.test(callbackBearer)) throw new HubSdkError({
+				code: "HUB_INVALID_INPUT",
+				message: "Application callback bearer is invalid"
+			});
+			const headers = new Headers(init.headers);
+			headers.set("Authorization", `Bearer ${callbackBearer}`);
+			return this.request(path, {
+				...init,
+				headers,
+				credentials: "omit",
+				redirect: "manual"
+			}, {
+				auth: "caller",
+				validateData: isDispatchCurrentData
+			});
+		});
 	}
 	static fromEnv(options = {}) {
 		const env = options.env ?? readProcessEnv();
@@ -265,25 +622,6 @@ var HubClient = class HubClient {
 	async status() {
 		return this.request("/v1/hub/status", { method: "GET" });
 	}
-	async request(path, init) {
-		const response = await this.fetch(`${this.baseUrl}${path}`, {
-			...init,
-			headers: await this.buildHeaders(init.headers)
-		});
-		const status = response.status;
-		const contentType = response.headers.get("content-type") ?? "";
-		const bodyText = await response.text();
-		if (!contentType.includes("application/json")) throw httpError(path, status, response.statusText, bodyText, contentType);
-		let parsed;
-		try {
-			parsed = JSON.parse(bodyText);
-		} catch {
-			throw httpError(path, status, response.statusText, bodyText, contentType);
-		}
-		if (isHubErrorEnvelope(parsed)) throw new HubSdkError(parsed.error, { status });
-		if (isHubSuccessEnvelope(parsed)) return parsed.data;
-		throw httpError(path, status, response.statusText, bodyText, contentType);
-	}
 	/**
 	* Open a streaming (Server-Sent Events) response and return its raw body.
 	* Shares auth-header building + `fetch` with {@link request}, but does NOT
@@ -350,25 +688,13 @@ var HubClient = class HubClient {
 			contentType
 		};
 	}
-	async buildHeaders(headers) {
-		const mergedHeaders = new Headers(headers);
-		if (!mergedHeaders.has("Accept")) mergedHeaders.set("Accept", "application/json");
-		if (this.apiKey) mergedHeaders.set("Authorization", `Bearer ${this.apiKey}`);
-		if (this.authHeaders) for (const [key, value] of new Headers(await this.authHeaders())) mergedHeaders.set(key, value);
-		for (const [key, value] of new Headers(headers)) mergedHeaders.set(key, value);
-		return mergedHeaders;
-	}
 };
 var HubTokensClient = class {
 	constructor(request) {
 		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();
@@ -402,38 +728,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 {
@@ -441,25 +751,17 @@ 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 }));
 	}
 	/**
 	* Run one hub tool. `raw` is the tool input: the SDK forwards it verbatim as
@@ -472,8 +774,9 @@ var HubToolsClient = class {
 			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);
@@ -491,15 +794,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: {
@@ -509,16 +808,12 @@ var HubToolsClient = class {
 		});
 	}
 	buildExecInit(path, raw, options) {
-		return {
-			method: "POST",
-			body: JSON.stringify({
-				path,
-				input: raw,
-				connectionId: options.connectionId,
-				idempotencyKey: options.idempotencyKey
-			}),
-			headers: { "Content-Type": "application/json" }
-		};
+		return jsonInit("POST", {
+			path,
+			input: raw,
+			connectionId: options.connectionId,
+			idempotencyKey: options.idempotencyKey
+		});
 	}
 };
 function requiresCapabilityToken(error) {
@@ -548,6 +843,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;
@@ -556,11 +862,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" });
@@ -574,19 +876,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" });
@@ -598,40 +898,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" });
@@ -659,11 +957,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. */
@@ -738,11 +1032,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,
@@ -753,14 +1043,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" });
@@ -771,11 +1057,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
@@ -803,9 +1085,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 } : {}
 		});
 	}
@@ -984,11 +1264,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
@@ -1009,11 +1285,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
@@ -1040,11 +1312,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.
@@ -1124,11 +1392,7 @@ var HubWorkflowsClient = class {
 	* value, stored and read back verbatim, so the client never gives it a shape.
 	*/
 	async putKv(id, key, raw) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}`, {
-			method: "PUT",
-			body: JSON.stringify({ value: raw }),
-			headers: { "Content-Type": "application/json" }
-		});
+		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
@@ -1138,14 +1402,10 @@ var HubWorkflowsClient = class {
 	* a shape.
 	*/
 	async casKv(id, key, expectedVersion, raw) {
-		return this.request(`/v1/workflows/${encodeURIComponent(id)}/kv/${encodeURIComponent(key)}/cas`, {
-			method: "POST",
-			body: JSON.stringify({
-				expectedVersion,
-				value: raw
-			}),
-			headers: { "Content-Type": "application/json" }
-		});
+		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) {
@@ -1165,11 +1425,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
@@ -1196,11 +1452,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.
@@ -1213,17 +1465,93 @@ var HubWorkflowsClient = class {
 	* the unconnected providers is the point.
 	*/
 	async validate(yaml, opts = {}) {
-		return this.request("/v1/workflows/validate", {
+		return this.request("/v1/workflows/validate", jsonInit("POST", {
+			yaml,
+			...opts.structural ? { structural: true } : {}
+		}));
+	}
+	async schema() {
+		return this.request("/v1/workflows/schema", { method: "GET" });
+	}
+};
+//#endregion
+//#region src/broker.ts
+/** Server-only client. App secrets never become a user's general API key.
+* Every invocation mints and consumes one short-lived, exact-grant token. */
+var HubAppBrokerClient = class {
+	baseUrl;
+	fetcher;
+	constructor(options) {
+		this.options = options;
+		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.fetcher = options.fetch ?? fetch.bind(globalThis);
+	}
+	async token(path, body) {
+		const response = await this.fetcher(`${this.baseUrl}${path}`, {
 			method: "POST",
+			redirect: "error",
+			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({
-				yaml,
-				...opts.structural ? { structural: true } : {}
-			}),
-			headers: { "Content-Type": "application/json" }
+				...body,
+				client_id: this.options.clientId,
+				client_secret: this.options.clientSecret
+			})
+		});
+		const result = await response.json().catch(() => null);
+		if (!response.ok || !result || typeof result !== "object" || Array.isArray(result)) throw new HubSdkError({
+			code: "HUB_CONFIG_MISSING",
+			message: "Application authorization is unavailable"
+		}, { status: response.status });
+		return result;
+	}
+	readToken(body) {
+		if (typeof body.access_token !== "string" || !body.access_token.startsWith("sk-tan-broker-") || body.token_type !== "Bearer" || typeof body.expires_in !== "number" || !Number.isSafeInteger(body.expires_in) || body.expires_in <= 0 || typeof body.scope !== "string") throw new HubSdkError({
+			code: "HUB_CONFIG_MISSING",
+			message: "Invalid application authorization response"
 		});
+		return {
+			accessToken: body.access_token,
+			expiresIn: body.expires_in,
+			scopes: body.scope.split(" ").filter(Boolean)
+		};
 	}
-	async schema() {
-		return this.request("/v1/workflows/schema", { method: "GET" });
+	async exchange(input) {
+		const body = await this.token("/v1/apps/oauth/token", {
+			grant_type: "authorization_code",
+			code: input.code,
+			redirect_uri: input.redirectUri,
+			connection_id: input.connectionId,
+			ttl_seconds: 60
+		});
+		const token = this.readToken(body);
+		if (typeof body.grant_id !== "string" || !body.grant_id || body.connection_id !== input.connectionId) throw new HubSdkError({
+			code: "HUB_CONFIG_MISSING",
+			message: "Application connection did not match consent"
+		});
+		return {
+			...token,
+			grantId: body.grant_id,
+			connectionId: input.connectionId
+		};
+	}
+	async mint(grantId) {
+		if (!/^[A-Za-z0-9_-]{1,256}$/.test(grantId)) throw new Error("Invalid application grant");
+		return this.readToken(await this.token(`/v1/apps/grants/${encodeURIComponent(grantId)}/mint-broker-token`, {
+			grant_id: grantId,
+			ttl_seconds: 60
+		}));
+	}
+	async invoke(grantId, connectionId, actionPath, input) {
+		const token = await this.mint(grantId);
+		if (!token.scopes.includes(actionPath)) throw new HubSdkError({
+			code: "HUB_POLICY_DENIED",
+			message: "This action was not granted to the application"
+		});
+		return new HubClient({
+			baseUrl: this.baseUrl,
+			apiKey: token.accessToken,
+			fetch: this.fetcher
+		}).tools.invoke(actionPath, input, { connectionId });
 	}
 };
 //#endregion
@@ -1484,6 +1812,55 @@ 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 };
+//#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 HubTransport's authHeaders, so one-use app broker tokens can be minted per request. */
+var HubLineGrantsClient = class extends HubTransport {
+	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;
+	}
+	memberApplication(binding) {
+		return this.request(path(binding, "/member-application"), { method: "GET" });
+	}
+	/**
+	* Route the owner's texts to this app's callback; the incumbent attachment
+	* stays. `replaceSelectionId` moves them from another app on the owner's
+	* explicit choice.
+	*/
+	async selectApplication(binding, input) {
+		return (await this.request(path(binding, "/member-application"), jsonInit("PUT", input))).selection;
+	}
+	/** Return the owner's texts to the incumbent attachment. */
+	async clearApplication(binding, input) {
+		await this.request(path(binding, "/member-application"), jsonInit("DELETE", input));
+	}
+	revoke(binding) {
+		return this.request(path(binding), { method: "DELETE" });
+	}
+};
+//#endregion
+export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, HubAllowancesClient, HubAppBrokerClient, HubApprovalsClient, HubAppsClient, HubAuditClient, HubChannelsClient, HubClient, HubConnectionsClient, HubEventDeliveryError, HubEventSubscriptionsClient, HubGithubAppClient, HubInboundWebhooksClient, HubKnowledgeClient, HubLineGrantsClient, HubLinesClient, HubManagedNumbersClient, HubPermissionsClient, HubSdkError, HubTokensClient, HubToolsClient, HubWorkflowsClient, authenticateHubEventRequest, deriveHubEventCallbackSecret, parseHubEventDelivery, redactHubValue, resolveHubAuth, resolveHubBaseUrl, verifyHubEventSignature };
 
 //# sourceMappingURL=index.js.map