@tangle-network/hub-sdk 0.2.2 → 0.4.0

package/README.md

@@ -1,7 +1,8 @@
 # @tangle-network/hub-sdk
 
 Typed SDK for the Tangle Hub `/v1/hub/*` surface. Status, connections, tools
-discovery and invocation, capability tokens, policies, approvals, audit.
+discovery and invocation, capability tokens, policies, approvals, audit,
+inbound channels, and product event subscriptions.
 
 ## Install
 
@@ -125,11 +126,106 @@ const hub = HubClient.fromEnv({
 });
 ```
 
+## Workflows
+
+`hub.workflows` covers the `/v1/workflows` surface — the same resource the
+platform web UI and the `tangle workflows` CLI drive. It authenticates with the
+`sk-tan-*` API key (or a session), **not** a hub capability token. Alongside
+CRUD (`list`/`get`/`create`/`update`/`delete`), `setEnabled`, `validate`, and
+`schema`, it can trigger and observe runs:
+
+```ts
+const hub = HubClient.fromEnv();
+
+// Trigger a run with the trigger fields the workflow reads, then wait for it.
+const { runId } = await hub.workflows.run("wf_123", {
+  "pull_request.number": "123",
+});
+const run = await hub.workflows.waitForRun("wf_123", runId, {
+  timeoutMs: 300_000,
+});
+console.log(run.status, run.actionResults);
+
+// Or tail live progress as it executes.
+for await (const event of hub.workflows.watchRun("wf_123", runId)) {
+  if (event.type === "token") process.stdout.write(event.delta);
+  if (event.type === "run.done") console.log("\n", event.status);
+}
+
+// One page of run history + a single run's full detail.
+const { runs, nextCursor } = await hub.workflows.listRuns("wf_123");
+const detail = await hub.workflows.getRun("wf_123", runs[0].id);
+```
+
+`run` throws `HubSdkError` with `MISSING_RUN_INPUTS` (the workflow reads trigger
+fields none were supplied for — `details.missing` names them) or
+`WORKFLOW_DISABLED` (enable it first). `waitForRun` throws
+`WORKFLOW_RUN_TIMEOUT` if the run has not finished within `timeoutMs`. Live
+`watchRun` ticks require the worker executing the run to share the API process;
+across instances only `snapshot` + `run.done` arrive, and the persisted record
+read via `getRun` stays the source of truth.
+
+## Product event subscriptions
+
+Products can bind a managed channel or a hosted provider connection to a signed
+server callback without authoring workflow YAML:
+
+OAuth readiness and inbound-event readiness are separate.
+Check `provider.eventIngressConfigured === true` before presenting an inbound
+channel as available.
+An absent value means the server predates readiness discovery and should be
+treated as unavailable.
+
+```ts
+const callbackSecret = await deriveHubEventCallbackSecret({
+  rootSecret: env.HUB_EVENT_CALLBACK_ROOT_SECRET,
+  productId: "relationships",
+  ownerId: tangleUserId,
+  bindingId: channel.id,
+});
+
+const { subscription } = await hub.eventSubscriptions.create({
+  clientReference: `relationships:${channel.id}`,
+  label: "Relationship workspace inbound",
+  source: { type: "channel", channelId: channel.id },
+  event: "email.received",
+  callback: {
+    url: "https://relationships.example/api/events",
+    secret: callbackSecret,
+  },
+});
+```
+
+`clientReference` is the product-owned idempotency key.
+The callback URL and secret are encrypted by the platform and never returned.
+The derivation scopes one callback secret to one product, owner, and binding, so
+the product stores only those existing ids.
+On receipt, authenticate and parse the exact raw request in one call:
+
+```ts
+const authenticated = await authenticateHubEventRequest({
+  request,
+  secret: callbackSecret,
+});
+if (!authenticated.ok) return authenticated.response;
+
+const { delivery } = authenticated;
+const email = delivery.providerEvent.payload;
+```
+
+The signed delivery includes the verified provider event directly, so the
+product does not need a second workflow-run request.
+Callbacks may be retried; use `delivery.runId` as the durable idempotency key
+before starting product work.
+
 ## Exports
 
 - `HubClient`, `HubClient.fromEnv(options?)`
 - `HubConnectionsClient`, `HubPermissionsClient`, `HubTokensClient`,
-  `HubToolsClient`, `HubApprovalsClient`, `HubAuditClient`
+  `HubChannelsClient`, `HubEventSubscriptionsClient`, `HubToolsClient`,
+  `HubApprovalsClient`, `HubAuditClient`, `HubWorkflowsClient`
+- `deriveHubEventCallbackSecret`, `authenticateHubEventRequest`,
+  `verifyHubEventSignature`, `parseHubEventDelivery`, `HubEventDeliveryError`
 - `HubSdkError` — typed `code: HubErrorCode`, redacted `details`, optional
   HTTP `status`
 - `HUB_URL_ENV_VAR`, `HUB_API_KEY_ENV_VAR`, `HUB_CAPABILITY_TOKEN_ENV_VAR` —