@tangle-network/hub-sdk 0.2.2 → 0.4.0

package/dist/index.js

@@ -1,3 +1,4 @@
+import { SSEChunkParser } from "@tangle-network/sdk-telemetry";
 //#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;
@@ -21,6 +22,160 @@ var HubSdkError = class extends Error {
 		this.status = options.status;
 	}
 };
+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}` : "";
+	return new HubSdkError({
+		code: `HUB_HTTP_${status}`,
+		message: `Hub request ${path} failed: HTTP ${status}${suffix}`,
+		details: {
+			status,
+			path,
+			contentType: contentType || null,
+			bodySnippet: bodySnippet(body)
+		}
+	}, { status });
+}
+function isHubErrorEnvelope(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	if (candidate.success !== false) return false;
+	const error = candidate.error;
+	return typeof error === "object" && error !== null && typeof error.code === "string";
+}
+function isHubSuccessEnvelope(value) {
+	return typeof value === "object" && value !== null && value.success === true;
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null;
+}
+function optString(value) {
+	return typeof value === "string" ? value : "";
+}
+/** An agent iteration's terminal status (`iteration.ended`) — only ever
+*  succeeded/failed; an iteration is never guard-skipped. */
+function isIterationStatus(value) {
+	return value === "succeeded" || value === "failed";
+}
+/** An action's terminal status on `action.finished`. Beyond succeeded/failed a
+*  guarded action can end `skipped` (its `if` resolved false, so it never ran) —
+*  accepted here so a skipped event is surfaced, not dropped as malformed. */
+function isActionFinishedStatus(value) {
+	return value === "succeeded" || value === "failed" || value === "skipped";
+}
+/** Terminal status of a whole run's `run.done` event. A run can end `cancelled`
+*  (a user cancel) — a value neither the action nor iteration status checkers
+*  accept — so `run.done` uses this rather than them, which would drop a
+*  cancelled terminal event and hang the stream. */
+function isRunDoneStatus(value) {
+	return value === "succeeded" || value === "failed" || value === "cancelled";
+}
+/**
+* Map one raw SSE event (its `event:` name + parsed JSON `data:`) to a typed
+* run-stream event, validating the fields each variant declares rather than
+* blindly casting the wire payload. A frame that doesn't match its event's
+* shape (or an unknown event name) returns null so the consumer skips it — a
+* malformed `token` can never reach a consumer as `{ delta: undefined }`, and
+* new server event kinds don't break older clients.
+*/
+function toRunStreamEvent(eventType, data) {
+	if (eventType === "ping") return { type: "ping" };
+	if (!isRecord$1(data)) return null;
+	switch (eventType) {
+		case "snapshot": return typeof data.id === "string" && typeof data.workflowId === "string" && typeof data.status === "string" && Array.isArray(data.actionResults) ? {
+			type: "snapshot",
+			run: data
+		} : null;
+		case "token": return typeof data.delta === "string" && typeof data.actionIndex === "number" ? {
+			type: "token",
+			actionIndex: data.actionIndex,
+			delta: data.delta,
+			at: optString(data.at)
+		} : null;
+		case "run.done": return isRunDoneStatus(data.status) ? {
+			type: "run.done",
+			status: data.status,
+			error: typeof data.error === "string" ? data.error : null,
+			...typeof data.at === "string" ? { at: data.at } : {}
+		} : null;
+		case "run.waiting": return typeof data.decisionId === "string" && data.decisionId.length > 0 ? {
+			type: "run.waiting",
+			decisionId: data.decisionId,
+			...typeof data.at === "string" ? { at: data.at } : {}
+		} : null;
+		case "action.started": return typeof data.index === "number" && typeof data.kind === "string" && typeof data.at === "string" ? {
+			type: "action.started",
+			index: data.index,
+			kind: data.kind,
+			at: data.at
+		} : null;
+		case "action.finished": return typeof data.index === "number" && typeof data.kind === "string" && isActionFinishedStatus(data.status) && typeof data.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 } : {}
+		} : null;
+		case "iteration.started": return typeof data.actionIndex === "number" && typeof data.iterationIndex === "number" && typeof data.at === "string" ? {
+			type: "iteration.started",
+			actionIndex: data.actionIndex,
+			iterationIndex: data.iterationIndex,
+			at: data.at,
+			...typeof data.model === "string" ? { model: data.model } : {}
+		} : null;
+		case "iteration.ended": return typeof data.actionIndex === "number" && typeof data.iterationIndex === "number" && isIterationStatus(data.status) && typeof data.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 } : {}
+		} : null;
+		default: return null;
+	}
+}
+/** 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");
+}
+/** A signal that aborts when the caller's signal aborts OR `timeoutMs` elapses.
+*  Returns undefined when neither bound applies (no per-request abort needed). */
+function combineAbortSignals(caller, timeoutMs) {
+	const signals = [];
+	if (caller) signals.push(caller);
+	if (timeoutMs !== null) signals.push(AbortSignal.timeout(timeoutMs));
+	if (signals.length === 0) return void 0;
+	return signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+}
+/** Resolve after `ms`, or reject if `signal` aborts first. Clears its timer on
+*  abort so a cancelled wait leaves nothing pending. */
+function delay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason ?? /* @__PURE__ */ new Error("The operation was aborted"));
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(signal?.reason ?? /* @__PURE__ */ new Error("The operation was aborted"));
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
 const HUB_URL_ENV_VAR = "TANGLE_HUB_URL";
 const HUB_API_KEY_ENV_VAR = "TANGLE_API_KEY";
 const HUB_CAPABILITY_TOKEN_ENV_VAR = "TANGLE_HUB_CAPABILITY_TOKEN";
@@ -71,24 +226,30 @@ var HubClient = class HubClient {
 	apiKey;
 	authHeaders;
 	connections;
+	channels;
+	eventSubscriptions;
 	permissions;
 	tokens;
 	tools;
 	approvals;
 	audit;
 	githubApp;
+	workflows;
 	constructor(options) {
 		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
 		this.apiKey = options.apiKey;
 		this.authHeaders = options.authHeaders;
-		this.fetch = options.fetch ?? fetch;
+		this.fetch = options.fetch ?? fetch.bind(globalThis);
 		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));
 		this.permissions = new HubPermissionsClient((path, init) => this.request(path, init));
 		this.tokens = new HubTokensClient((path, init) => this.request(path, init));
 		this.tools = new HubToolsClient((path, init) => this.request(path, init));
 		this.approvals = new HubApprovalsClient((path, init) => this.request(path, init));
 		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));
 	}
 	static fromEnv(options = {}) {
 		const env = options.env ?? readProcessEnv();
@@ -107,13 +268,57 @@ var HubClient = class HubClient {
 			...init,
 			headers: await this.buildHeaders(init.headers)
 		});
-		const envelope = await response.json();
-		if (!envelope.success) throw new HubSdkError(envelope.error, { status: response.status });
-		return envelope.data;
+		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
+	* buffer or JSON-parse the body — the caller consumes the stream.
+	*
+	* A successful stream comes back as `text/event-stream`. Anything else is an
+	* error envelope (404/429/401 JSON) or a transport failure (gateway/HTML
+	* page); it is surfaced the same way {@link request} surfaces errors — a
+	* typed `HubSdkError` from a `{success:false}` envelope, otherwise an
+	* `HUB_HTTP_<status>` transport error — rather than handed back as bogus SSE.
+	*/
+	async stream(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") ?? "";
+		if (!response.ok || !contentType.includes("text/event-stream")) {
+			const bodyText = await response.text().catch(() => "");
+			if (contentType.includes("application/json")) {
+				let parsed;
+				try {
+					parsed = JSON.parse(bodyText);
+				} catch {
+					parsed = void 0;
+				}
+				if (isHubErrorEnvelope(parsed)) throw new HubSdkError(parsed.error, { status });
+			}
+			throw httpError(path, status, response.statusText, bodyText, contentType);
+		}
+		if (!response.body) throw httpError(path, status, response.statusText, "event-stream response had no body", contentType);
+		return response.body;
 	}
 	async buildHeaders(headers) {
 		const mergedHeaders = new Headers(headers);
-		mergedHeaders.set("Accept", "application/json");
+		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);
@@ -169,6 +374,33 @@ var HubPermissionsClient = class {
 			headers: { "Content-Type": "application/json" }
 		});
 	}
+	/** 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" }
+		});
+	}
+	/** 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" }
+		});
+	}
+	/** 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" }
+		});
+	}
 };
 var HubToolsClient = class {
 	constructor(request) {
@@ -179,7 +411,8 @@ var HubToolsClient = class {
 			method: "POST",
 			body: JSON.stringify({
 				query,
-				provider: options.provider
+				provider: options.provider,
+				limit: options.limit
 			}),
 			headers: { "Content-Type": "application/json" }
 		});
@@ -275,6 +508,42 @@ function validateApprovedExecution(approved, path, connectionId) {
 		}
 	});
 }
+var HubChannelsClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	async list() {
+		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" }
+		});
+	}
+	async delete(channelId) {
+		return this.request(`/v1/hub/channels/${encodeURIComponent(channelId)}`, { method: "DELETE" });
+	}
+};
+var HubEventSubscriptionsClient = class {
+	constructor(request) {
+		this.request = request;
+	}
+	async list() {
+		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" }
+		});
+	}
+	async delete(subscriptionId) {
+		return this.request(`/v1/hub/event-subscriptions/${encodeURIComponent(subscriptionId)}`, { method: "DELETE" });
+	}
+};
 var HubConnectionsClient = class {
 	constructor(request) {
 		this.request = request;
@@ -282,6 +551,12 @@ var HubConnectionsClient = class {
 	async list() {
 		return this.request("/v1/hub/connections", { method: "GET" });
 	}
+	/** Connector catalog: every provider the hub can expose, each flagged with
+	*  `configured` (whether its OAuth app credentials are wired). Callers render
+	*  this alongside `list()` to offer Connect for not-yet-connected providers. */
+	async providers() {
+		return this.request("/v1/hub/providers", { method: "GET" });
+	}
 	async start(provider, options = {}) {
 		return this.request(`/v1/hub/connections/${encodeURIComponent(provider)}/start`, {
 			method: "POST",
@@ -292,6 +567,31 @@ var HubConnectionsClient = class {
 			headers: { "Content-Type": "application/json" }
 		});
 	}
+	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" }
+		});
+	}
+	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" }
+		});
+	}
+	/** 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" }
+		});
+	}
 	async revoke(connectionId) {
 		return this.request(`/v1/hub/connections/${encodeURIComponent(connectionId)}`, { method: "DELETE" });
 	}
@@ -355,7 +655,480 @@ var HubAuditClient = class {
 		return this.request(`/v1/hub/audit${query ? `?${query}` : ""}`, { method: "GET" });
 	}
 };
+var HubWorkflowsClient = class {
+	constructor(request, stream) {
+		this.request = request;
+		this.stream = stream;
+	}
+	async list() {
+		return this.request("/v1/workflows", { method: "GET" });
+	}
+	async get(id) {
+		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" }
+		});
+	}
+	async update(id, yaml) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}`, {
+			method: "PUT",
+			body: JSON.stringify({ yaml }),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	async delete(id) {
+		await this.request(`/v1/workflows/${encodeURIComponent(id)}`, { method: "DELETE" });
+	}
+	/**
+	* Enable or disable a workflow without editing its YAML. Works even when the
+	* workflow's connection was revoked (a disabled workflow can't be recompiled
+	* 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" }
+		});
+	}
+	/**
+	* One page of run history, newest first. Pass the previous page's
+	* `nextCursor` to fetch the next; a null `nextCursor` means the last page.
+	*/
+	async listRuns(id, opts = {}) {
+		const params = new URLSearchParams();
+		if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+		if (opts.cursor !== void 0) params.set("cursor", opts.cursor);
+		const query = params.toString();
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs${query ? `?${query}` : ""}`, { method: "GET" });
+	}
+	/**
+	* Enqueue an immediate ("Run now") run and return its `runId`. The run goes
+	* through the identical execution path a trigger delivery uses.
+	*
+	* `inputs` supplies the trigger fields the workflow reads (its
+	* {@link HubWorkflow.manualRunInputs}), as a flat `{ path: value }` map — e.g.
+	* `{ "pull_request.number": "123" }`. Omit it for a one-click run of a
+	* workflow that reads no trigger fields. Throws `HubSdkError`:
+	* `MISSING_RUN_INPUTS` when a required field is absent (`details.missing`
+	* names them), `WORKFLOW_DISABLED` when the workflow is paused, `NOT_FOUND`
+	* for an unknown/foreign id. Pass `opts.signal` to abort a slow request.
+	*/
+	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" },
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+	}
+	/**
+	* A single run's full detail: per-action `output` + `agentRun` execution
+	* detail (size-capped server-side) and the trigger context — the deep "why
+	* did this run do what it did" view. `NOT_FOUND` when the run is unknown or
+	* does not belong to both the caller and this workflow.
+	*/
+	async getRun(id, runId, opts = {}) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}`, {
+			method: "GET",
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+	}
+	/**
+	* Stop a queued or in-flight run. A `queued` run is cancelled synchronously
+	* and comes back `{ status: "cancelled" }` (already terminal); a `running` run
+	* is signalled to abort and comes back `{ status: "cancelling", signalled }` —
+	* it settles `cancelled` a moment later as its current action tears down, which
+	* a {@link watchRun}/{@link getRun} observes. Throws `HubSdkError`:
+	* `RUN_NOT_CANCELLABLE` when the run already finished, `NOT_FOUND` for an
+	* unknown/foreign run id. Pass `opts.signal` to abort a slow request.
+	*/
+	async cancel(id, runId, opts = {}) {
+		return this.request(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/cancel`, {
+			method: "POST",
+			...opts.signal ? { signal: opts.signal } : {}
+		});
+	}
+	/**
+	* Stream a run's live progress as an async iterable of typed events. The
+	* first event is always a `snapshot` of the current persisted state; then
+	* `action.*` / `iteration.*` / `token` ticks arrive as the run executes;
+	* `ping` is a keepalive; a terminal `run.done` ends the iteration. If the run
+	* is already finished when the stream opens, it yields the snapshot then
+	* `run.done` and completes.
+	*
+	* Live ticks require the worker executing the run to share the API process;
+	* across instances only `snapshot` + `run.done` (from the server's terminal
+	* poll) arrive — the persisted record, read via {@link getRun}, stays the
+	* source of truth. Pass `signal` to cancel; iterating to `run.done` (or
+	* breaking early) releases the connection.
+	*/
+	async *watchRun(id, runId, opts = {}) {
+		const openStream = this.stream;
+		if (!openStream) throw new HubSdkError({
+			code: "HUB_CONFIG_INVALID",
+			message: "watchRun needs a streaming transport; use HubClient (which wires it up) rather than constructing HubWorkflowsClient directly"
+		});
+		const reader = (await openStream(`/v1/workflows/${encodeURIComponent(id)}/runs/${encodeURIComponent(runId)}/events`, {
+			method: "GET",
+			headers: { Accept: "text/event-stream" },
+			...opts.signal ? { signal: opts.signal } : {}
+		})).getReader();
+		const decoder = new TextDecoder();
+		const parser = new SSEChunkParser({ transform: (raw) => {
+			try {
+				return JSON.parse(raw);
+			} catch {
+				return null;
+			}
+		} });
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				const text = done ? decoder.decode() : decoder.decode(value, { stream: true });
+				const parsedEvents = done ? [...parser.push(text), ...parser.flush()] : parser.push(text);
+				for (const parsed of parsedEvents) {
+					const event = toRunStreamEvent(parsed.eventType, parsed.data);
+					if (!event) continue;
+					yield event;
+					if (event.type === "run.done" || event.type === "run.waiting") return;
+				}
+				if (done) return;
+			}
+		} finally {
+			await reader.cancel().catch(() => {});
+		}
+	}
+	/**
+	* Poll {@link getRun} until the run reaches a terminal state (`succeeded` or
+	* `failed`) and return its detail. The scripting primitive behind "run and
+	* print the result": pairs with {@link run} for a one-call trigger-and-wait.
+	*
+	* Returns as soon as the run leaves the active set (`queued` / `running`) —
+	* i.e. on `succeeded`, `failed`, or any future non-active status — so a new
+	* terminal state can never hang the wait. Polls every `pollIntervalMs`
+	* (default 2000). With `timeoutMs` set, throws
+	* `HubSdkError(WORKFLOW_RUN_TIMEOUT)` — carrying the last observed status on
+	* `details.status` — only once the deadline has actually passed; the last
+	* wait is clamped to the remaining time so a `timeoutMs` shorter than the
+	* poll interval still waits the full requested window rather than giving up a
+	* poll early. Pass `signal` to cancel the wait between polls.
+	*/
+	async waitForRun(id, runId, opts = {}) {
+		const pollIntervalMs = opts.pollIntervalMs ?? 2e3;
+		if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) throw new HubSdkError({
+			code: "HUB_CONFIG_INVALID",
+			message: `waitForRun pollIntervalMs must be a positive number (got ${opts.pollIntervalMs})`
+		});
+		if (opts.timeoutMs !== void 0 && (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs <= 0)) throw new HubSdkError({
+			code: "HUB_CONFIG_INVALID",
+			message: `waitForRun timeoutMs must be a positive number (got ${opts.timeoutMs})`
+		});
+		const deadline = opts.timeoutMs !== void 0 ? Date.now() + opts.timeoutMs : null;
+		const timeoutError = (status) => new HubSdkError({
+			code: "WORKFLOW_RUN_TIMEOUT",
+			message: `Workflow run ${runId} did not reach a terminal state within ${opts.timeoutMs}ms${status ? ` (last status: ${status})` : ""}`,
+			details: {
+				runId,
+				status,
+				timeoutMs: opts.timeoutMs
+			}
+		});
+		let lastStatus;
+		for (;;) {
+			if (opts.signal?.aborted) throw opts.signal.reason ?? /* @__PURE__ */ new Error("The operation was aborted");
+			const remainingMs = deadline !== null ? deadline - Date.now() : null;
+			if (remainingMs !== null && remainingMs <= 0) throw timeoutError(lastStatus);
+			const pollSignal = combineAbortSignals(opts.signal, remainingMs);
+			let run;
+			try {
+				run = await this.getRun(id, runId, pollSignal ? { signal: pollSignal } : {});
+			} catch (err) {
+				if (opts.signal?.aborted) throw err;
+				if (deadline !== null && isAbortError(err)) throw timeoutError(lastStatus);
+				throw err;
+			}
+			lastStatus = run.status;
+			if (run.status !== "queued" && run.status !== "running") return run;
+			const delayRemainingMs = deadline !== null ? deadline - Date.now() : null;
+			if (delayRemainingMs !== null && delayRemainingMs <= 0) throw timeoutError(lastStatus);
+			await delay(delayRemainingMs !== null ? Math.min(pollIntervalMs, delayRemainingMs) : pollIntervalMs, opts.signal);
+		}
+	}
+	async validate(yaml) {
+		return this.request("/v1/workflows/validate", {
+			method: "POST",
+			body: JSON.stringify({ yaml }),
+			headers: { "Content-Type": "application/json" }
+		});
+	}
+	async schema() {
+		return this.request("/v1/workflows/schema", { method: "GET" });
+	}
+};
+//#endregion
+//#region src/event-delivery.ts
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const MAX_TOLERANCE_SECONDS = 3600;
+const MAX_SIGNATURE_HEADER_LENGTH = 1024;
+const MAX_SIGNATURES = 5;
+const SHA256_HEX_LENGTH = 64;
+const MIN_CALLBACK_SECRET_BYTES = 32;
+const MAX_SECRET_SCOPE_COMPONENT_BYTES = 512;
+const DEFAULT_MAX_CALLBACK_BODY_BYTES = 5308416;
+const MAX_CALLBACK_BODY_BYTES = 10 * 1024 * 1024;
+var HubEventDeliveryError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "HubEventDeliveryError";
+		this.code = code;
+	}
+};
+/**
+* Derive one callback secret per product binding from a single server-held root
+* secret. Products persist only the binding id; the derived secret can be
+* reproduced for callback authentication without another secret table.
+*/
+async function deriveHubEventCallbackSecret(input) {
+	const encoder = new TextEncoder();
+	if (encoder.encode(input.rootSecret).byteLength < MIN_CALLBACK_SECRET_BYTES) throw new HubEventDeliveryError("INVALID_CALLBACK_SECRET", `Hub event root secret must contain at least ${MIN_CALLBACK_SECRET_BYTES} UTF-8 bytes`);
+	for (const [name, value] of [
+		["productId", input.productId],
+		["ownerId", input.ownerId],
+		["bindingId", input.bindingId]
+	]) {
+		const bytes = encoder.encode(value).byteLength;
+		if (bytes === 0 || bytes > MAX_SECRET_SCOPE_COMPONENT_BYTES) throw new HubEventDeliveryError("INVALID_SECRET_SCOPE", `${name} must contain 1-${MAX_SECRET_SCOPE_COMPONENT_BYTES} UTF-8 bytes`);
+	}
+	const subtle = requireSubtleCrypto();
+	const key = await subtle.importKey("raw", encoder.encode(input.rootSecret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const scope = JSON.stringify([
+		"tangle-hub-event-callback",
+		1,
+		input.productId,
+		input.ownerId,
+		input.bindingId
+	]);
+	return bytesToBase64Url(new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(scope))));
+}
+/**
+* Authenticate and parse the platform's callback as one operation. The exact
+* raw body is read once with a size limit before its signature is checked.
+*
+* A successful callback can be retried. Use `delivery.runId` as the durable
+* idempotency key before starting product work.
+*/
+async function authenticateHubEventRequest(input) {
+	if (input.request.method !== "POST") return requestFailure("METHOD_NOT_ALLOWED", 405, "method_not_allowed", { Allow: "POST" });
+	if (input.request.headers.get("x-tangle-event") !== "hub.event") return requestFailure("UNEXPECTED_EVENT", 400, "invalid_hub_event");
+	const contentType = input.request.headers.get("content-type") ?? "";
+	if (!/^application\/json(?:\s*;|$)/i.test(contentType)) return requestFailure("UNSUPPORTED_MEDIA_TYPE", 415, "unsupported_media_type");
+	const maxBodyBytes = input.maxBodyBytes ?? DEFAULT_MAX_CALLBACK_BODY_BYTES;
+	if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || maxBodyBytes > MAX_CALLBACK_BODY_BYTES) throw new HubEventDeliveryError("INVALID_BODY_LIMIT", `Hub event body limit must be an integer from 1 to ${MAX_CALLBACK_BODY_BYTES} bytes`);
+	if (new TextEncoder().encode(input.secret).byteLength < MIN_CALLBACK_SECRET_BYTES) throw new HubEventDeliveryError("INVALID_CALLBACK_SECRET", `Hub event callback secret must contain at least ${MIN_CALLBACK_SECRET_BYTES} UTF-8 bytes`);
+	const declaredLength = input.request.headers.get("content-length");
+	if (declaredLength !== null && /^\d+$/.test(declaredLength) && Number(declaredLength) > maxBodyBytes) return requestFailure("PAYLOAD_TOO_LARGE", 413, "payload_too_large");
+	const body = await readRequestBody(input.request, maxBodyBytes);
+	if (body === null) return requestFailure("PAYLOAD_TOO_LARGE", 413, "payload_too_large");
+	if (!(await verifyHubEventSignature({
+		body,
+		signature: input.request.headers.get("x-tangle-signature"),
+		secret: input.secret,
+		...input.toleranceSeconds !== void 0 ? { toleranceSeconds: input.toleranceSeconds } : {},
+		...input.now !== void 0 ? { now: input.now } : {}
+	})).valid) return requestFailure("INVALID_SIGNATURE", 401, "invalid_signature");
+	let delivery;
+	try {
+		delivery = parseHubEventDelivery(body);
+	} catch (error) {
+		if (error instanceof HubEventDeliveryError) return requestFailure("INVALID_DELIVERY", 400, "invalid_delivery");
+		throw error;
+	}
+	if (input.request.headers.get("x-tangle-delivery-id") !== delivery.runId) return requestFailure("DELIVERY_ID_MISMATCH", 400, "invalid_delivery");
+	return {
+		ok: true,
+		delivery
+	};
+}
+/**
+* Authenticate a Hub event callback against its exact raw request body.
+* The timestamp window rejects captured-request replay, and byte-wise
+* comparison avoids secret-dependent string comparison behavior.
+*/
+async function verifyHubEventSignature(input) {
+	if (!input.signature) return {
+		valid: false,
+		reason: "missing"
+	};
+	if (input.signature.length > MAX_SIGNATURE_HEADER_LENGTH) return {
+		valid: false,
+		reason: "malformed"
+	};
+	const parsed = parseSignatureHeader(input.signature);
+	if (!parsed) return {
+		valid: false,
+		reason: "malformed"
+	};
+	const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+	if (!Number.isFinite(tolerance) || !Number.isInteger(tolerance) || tolerance < 0 || tolerance > MAX_TOLERANCE_SECONDS) throw new HubEventDeliveryError("INVALID_TOLERANCE", `Signature tolerance must be an integer from 0 to ${MAX_TOLERANCE_SECONDS} seconds`);
+	const nowMs = input.now instanceof Date ? input.now.getTime() : typeof input.now === "number" ? input.now : Date.now();
+	if (!Number.isFinite(nowMs) || Math.abs(Math.floor(nowMs / 1e3) - parsed.timestamp) > tolerance) return {
+		valid: false,
+		reason: "stale"
+	};
+	const subtle = requireSubtleCrypto();
+	const encoder = new TextEncoder();
+	const key = await subtle.importKey("raw", encoder.encode(input.secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const expected = new Uint8Array(await subtle.sign("HMAC", key, encoder.encode(`${parsed.timestamp}.${input.body}`)));
+	let matched = 0;
+	for (const signature of parsed.signatures) matched |= constantTimeEqual(expected, signature);
+	return matched === 1 ? {
+		valid: true,
+		timestamp: parsed.timestamp
+	} : {
+		valid: false,
+		reason: "mismatch"
+	};
+}
+function parseHubEventDelivery(input) {
+	let value = input;
+	if (typeof input === "string") try {
+		value = JSON.parse(input);
+	} catch {
+		throw new HubEventDeliveryError("INVALID_JSON", "Hub event callback body is not valid JSON");
+	}
+	if (!isRecord(value)) return invalidDelivery();
+	const source = value.source;
+	const providerEvent = value.providerEvent;
+	if (!nonEmptyString(value.subscriptionId) || !nonEmptyString(value.workflowId) || !nonEmptyString(value.runId) || !isRecord(source) || source.kind !== "channel" && source.kind !== "connection" || !nonEmptyString(source.id) || !nonEmptyString(source.provider) || !nonEmptyString(source.event) || !isRecord(providerEvent) || !nonEmptyString(providerEvent.provider) || !nonEmptyString(providerEvent.connectionId) || !nonEmptyString(providerEvent.type) || providerEvent.provider !== source.provider || providerEvent.type !== source.event || !Object.hasOwn(providerEvent, "payload") || !optionalString(providerEvent.action) || !optionalString(providerEvent.repo) || !optionalString(providerEvent.deliveryId) || !nonEmptyString(value.firedAt) || !Number.isFinite(Date.parse(value.firedAt))) return invalidDelivery();
+	return {
+		subscriptionId: value.subscriptionId,
+		workflowId: value.workflowId,
+		runId: value.runId,
+		source: {
+			kind: source.kind,
+			id: source.id,
+			provider: source.provider,
+			event: source.event
+		},
+		providerEvent: {
+			provider: providerEvent.provider,
+			connectionId: providerEvent.connectionId,
+			type: providerEvent.type,
+			...typeof providerEvent.action === "string" ? { action: providerEvent.action } : {},
+			...typeof providerEvent.repo === "string" ? { repo: providerEvent.repo } : {},
+			...typeof providerEvent.deliveryId === "string" ? { deliveryId: providerEvent.deliveryId } : {},
+			payload: providerEvent.payload
+		},
+		firedAt: value.firedAt
+	};
+}
+function parseSignatureHeader(header) {
+	let timestamp;
+	const signatures = [];
+	for (const segment of header.split(",")) {
+		const separator = segment.indexOf("=");
+		if (separator <= 0) return null;
+		const key = segment.slice(0, separator).trim();
+		const value = segment.slice(separator + 1).trim();
+		if (key === "t") {
+			if (timestamp !== void 0 || !/^\d+$/.test(value)) return null;
+			const candidate = Number(value);
+			if (!Number.isSafeInteger(candidate) || candidate <= 0) return null;
+			timestamp = candidate;
+		} else if (key === "v1") {
+			if (signatures.length >= MAX_SIGNATURES || value.length !== SHA256_HEX_LENGTH || !/^[0-9a-f]+$/i.test(value)) return null;
+			signatures.push(hexToBytes(value));
+		}
+	}
+	return timestamp !== void 0 && signatures.length > 0 ? {
+		timestamp,
+		signatures
+	} : null;
+}
+function hexToBytes(hex) {
+	const bytes = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return bytes;
+}
+function constantTimeEqual(expected, actual) {
+	let difference = expected.length ^ actual.length;
+	const length = Math.max(expected.length, actual.length);
+	for (let index = 0; index < length; index += 1) difference |= (expected[index % expected.length] ?? 0) ^ (actual[index % actual.length] ?? 0);
+	return difference === 0 ? 1 : 0;
+}
+function nonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+function optionalString(value) {
+	return value === void 0 || nonEmptyString(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidDelivery() {
+	throw new HubEventDeliveryError("INVALID_PAYLOAD", "Hub event callback body does not match the delivery contract");
+}
+function requireSubtleCrypto() {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new HubEventDeliveryError("CRYPTO_UNAVAILABLE", "Web Crypto is required for Hub event callback authentication");
+	return subtle;
+}
+function bytesToBase64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+async function readRequestBody(request, maxBytes) {
+	const reader = request.body?.getReader();
+	if (!reader) return "";
+	const chunks = [];
+	let total = 0;
+	try {
+		while (true) {
+			const next = await reader.read();
+			if (next.done) break;
+			total += next.value.byteLength;
+			if (total > maxBytes) return null;
+			chunks.push(next.value);
+		}
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	const body = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		body.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(body);
+}
+function requestFailure(code, status, error, headers) {
+	return {
+		ok: false,
+		code,
+		response: Response.json({ error }, {
+			status,
+			headers: {
+				"cache-control": "no-store",
+				...headers ? Object.fromEntries(new Headers(headers)) : {}
+			}
+		})
+	};
+}
 //#endregion
-export { HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR, HUB_URL_ENV_VAR, HubApprovalsClient, HubAuditClient, HubClient, HubConnectionsClient, HubGithubAppClient, HubPermissionsClient, HubSdkError, HubTokensClient, HubToolsClient, redactHubValue, resolveHubAuth, resolveHubBaseUrl };
+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 };
 
 //# sourceMappingURL=index.js.map