@tangle-network/hub-sdk 0.3.0 → 0.5.1

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
 
@@ -164,11 +165,67 @@ fields none were supplied for — `details.missing` names them) or
 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`, `HubWorkflowsClient`
+  `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` —