@tangle-network/hub-sdk 0.28.0-develop.20260819054947.83fb85f → 0.28.0

package/README.md

@@ -30,9 +30,7 @@ SaaS vs on-prem flips via env only — there is no per-client default URL.
 | `TANGLE_API_KEY`               | One of   | Long-lived API key (Bearer). User / API key principal.                                        |
 | `TANGLE_HUB_CAPABILITY_TOKEN`  | One of   | Short-lived capability token (Bearer). Sandbox-runtime principal. Auto-minted server-side per action. |
 
-The two auth credentials are mutually exclusive — set exactly one. This
-mirrors the platform-api `hubSandboxEnvironmentSchema` rule
-(`exactly-one-api-key-or-capability-token`).
+The two auth credentials are mutually exclusive — set exactly one.
 
 ### Examples
 
@@ -126,6 +124,29 @@ const hub = HubClient.fromEnv({
 });
 ```
 
+## Tool approvals
+
+`tools.invoke()` preserves an existing `HUB_APPROVAL_REQUIRED` error instead of requesting another token.
+The error retains the original approval ID and the server's action details.
+Present that approval through the product's decision flow.
+Set `approve: true` only after the caller has authorized that action.
+Automatic capability-token minting remains available when the server returns no concrete approval.
+
+## GitHub OAuth scopes
+
+Pass the exact scope set when the caller needs GitHub repository selection.
+Platform accepts `read:user`, `repo`, and `read:org` together for this request.
+It rejects a callback if GitHub grants a different set.
+Omitting `requestedScopes` retains the existing default GitHub flow.
+The SDK refuses a start response with different scopes, including responses from an older Platform deployment.
+
+```ts
+const hub = HubClient.fromEnv();
+await hub.connections.start("github", {
+  requestedScopes: ["read:user", "repo", "read:org"],
+});
+```
+
 ## Workflows
 
 `hub.workflows` covers the `/v1/workflows` surface — the same resource the
@@ -218,19 +239,183 @@ 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.
 
+## Allowances and the paywall decision
+
+A product that bills its end users sets a free allowance, and optionally a paid one, on a meter.
+Hub admits every turn against it, counts turns per member and per line, and reads each payer's dollars from the ledger.
+The product keeps only its checkout: after a payment it records the member as paid until the period ends.
+
+```ts
+await hub.allowances.setPlan(`agent:${agentId}`, {
+  free: { turnsPerDay: 20, usdPerDay: 2 },
+  paid: { turnsPerDay: 200, usdPerDay: 5, priceUsdMonthly: 10 },
+  spendResourceType: "hosted_enrollment",
+});
+
+const turn = await hub.allowances.admit(`agent:${agentId}`, {
+  member: enrollmentId,
+  turnId: messageId,
+  line: lineId,
+});
+if (turn.decision === "paywall") return sendCheckoutLink();
+if (turn.decision === "allowance_reached") return sendComeBackTomorrow();
+
+// From the checkout webhook:
+await hub.allowances.grant(`agent:${agentId}`, enrollmentId, {
+  expiresAt: periodEnd.toISOString(),
+  reference: subscriptionId,
+});
+```
+
+`admit` is idempotent by `turnId`, so a retried turn is never counted twice.
+A member's dollars are the sum of today's ledger charges on keys bound to `(spendResourceType, member)` and on every key delegated below them, so delegate each member's key with that resource.
+A paid member also has a funded capacity for the period: the price less Tangle's 10% fee, plus the free daily dollars for the period's 31 days.
+With the plan above, that is $9 + $62 = $71 against the $155 that $5 a day would allow.
+Past it, `admit` answers `allowance_reached`, and `turn.period` shows `spent`, `funded` and `remaining`.
+Only the meter's owner may call these, signed in or with a root key of their own.
+A delegated or resource-bound key is refused, so an end user's sandbox cannot grant itself the paid tier.
+
+## Shared-Line application dispatch
+
+Before admitting a shared-Line callback, check its current Hub authority:
+
+```ts
+const current = await hub.lines.applicationDispatchCurrent(
+  lineId,
+  messageId,
+  { attachmentId, memberId, memberRevision, senderAddress, textSha256, binding, dispatchFence, dispatchDeadline },
+  callbackBearer,
+);
+```
+
+`textSha256` is the lowercase SHA-256 hex digest of the exact callback `text` UTF-8 bytes, with no normalization.
+Compute it from the received callback text, not from a caller-supplied digest.
+Hub compares it with the persisted inbound message text before returning `current: true`.
+This uses the callback bearer alone; account credentials, cookies, and redirects are excluded.
+It returns a boolean only from a successful, valid Hub response and makes no retry.
+HTTP failures retain their status and code without response bodies or credential details.
+Configure the client's injected `fetch` to enforce the caller's request deadline.
+A current result authorizes this observation; native admission must still enforce its own expiry and deduplication contract.
+
 ## Exports
 
 - `HubClient`, `HubClient.fromEnv(options?)`
 - `HubConnectionsClient`, `HubPermissionsClient`, `HubTokensClient`,
   `HubChannelsClient`, `HubEventSubscriptionsClient`, `HubToolsClient`,
-  `HubApprovalsClient`, `HubAuditClient`, `HubWorkflowsClient`
+  `HubApprovalsClient`, `HubAuditClient`, `HubWorkflowsClient`,
+  `HubAllowancesClient`
 - `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` —
-  string constants for the env-var names (mirrored by the platform-api
-  `hub-sandbox-contract.ts` `z.literal(...)`)
+  string constants for the env-var names
 - `resolveHubBaseUrl(env?)`, `resolveHubAuth(env?)` — standalone resolvers
   with the same fail-loud contract as `fromEnv`
 - All request/response types from the `/v1/hub/*` contract
+
+
+## Link application login to explicit Hub permissions
+
+Use the same `HubClient` for application management; do not add a product-local
+HTTP client. These operations require the authenticated developer account, not
+an app's OIDC access token. Customer grants are created only by the existing
+session-authenticated `/cross-site/app-consent` flow.
+
+```ts
+import { HubClient } from "@tangle-network/hub-sdk";
+
+const hub = HubClient.fromEnv(); // developer account for app administration
+const { app, clientSecret } = await hub.apps.create({
+  name: "Support assistant",
+  redirectUris: ["https://assistant.example/hub/callback"],
+  allowedScopes: ["github.issues.create"],
+});
+// Save clientSecret once in the application's server-side secret store.
+await hub.apps.linkOAuthClient(app.id, oidcClientId);
+const apps = await hub.apps.list(); // includes oauthClientId; never the secret
+```
+
+`oidcClientId` is the application's already-registered Sign in with Tangle client.
+Linking requires the same owner on both records and is immutable and one-to-one.
+It does not reuse the two clients' secrets, change their IDs, create a user grant,
+or authorize spending. Use separate app/client pairs for separate deployments.
+Existing unlinked broker apps remain compatible. There is no automatic link by
+name, callback domain, email, or ownership alone.
+
+With a customer's authenticated Hub client, `hub.apps.grants.list()` returns only
+that customer's active resource grants and `hub.apps.grants.revoke(grantId)`
+revokes one idempotently. App administrators use `hub.apps.revoke(appId)` to
+suspend the app, revoke all its customer grants, and disable its owned linked
+OIDC client. An app's broker credential cannot call these management methods.
+
+An app broker can create `new HubLineGrantsClient(options)` for a line approved by its owner.
+Pass an `authHeaders` provider that mints a fresh scoped broker token for each call.
+Pass the exact `workspaceId` and `workspaceAgentId` binding to every method.
+The `current` response includes `intakeMode`, `priorAttachmentId`, and `priorAttachmentActive`.
+An `owner_only` grant attaches one declared owner sender and rejects unknown senders.
+The app cannot choose its own sender or change the approved intake mode in `attach`.
+
+An owner can instead consent with `execution=application` (and `owner_test=1`).
+Then `current().execution` is `"application"` and `attach` is refused.
+The owner's existing attachment stays on the Line.
+`memberApplication()` reads the declared owner member, its `memberRevision`, `eligible`, and the Hub-derived `binding`.
+`selectApplication()` routes that member's texts to an HTTPS callback on the approved origin, with the app's own bearer `secret`.
+`clearApplication()` returns them to the incumbent agent.
+When another app answers, `selection.own` is false and `selection.app.name` and `selection.selectedAt` say which app and since when; its callback URL stays private.
+Show that to the owner with an explicit choice to answer here instead.
+Only on that choice, pass the selection id you read as both `replaceSelectionId` and `expectedSelectionId` to `selectApplication()`.
+Without `replaceSelectionId`, or with a stale id, Hub refuses with 409 and the other app keeps answering.
+The app cannot clear another app's selection, and revoking the grant revokes its selection.
+Each callback carries `binding`; verify currentness with `lines.applicationDispatchCurrent`.
+
+Broker execution keeps the one approved connection even when the invocation
+omits `connectionId`; it never substitutes another account. Each one-shot broker
+token is checked against current app policy and the exact active grant when
+minted and consumed. Changing consent revokes the old binding, tokens and codes;
+the fresh consent response supplies a new grant ID. Login disconnect revokes the
+linked app's existing grants for that customer, not other customers or apps.
+An operation already admitted to a provider may finish; revocation blocks new
+admissions and minting, not external side effects already underway.
+
+This is identity and resource delegation, **not** generalized spending delegation.
+Existing product billing checks and action approvals continue to apply.
+
+
+### Select an application for one verified line member
+
+The account owner can select an app without changing the Line attachment.
+Unselected members keep the existing default agent.
+The member must already be active, declared, verified, and consented.
+An owner without a customer subject can select only their own Platform subject.
+Other members must retain their existing customer subject.
+The app authorizes and funds its own agent execution.
+
+Use `hub.lines.memberApplications.get(lineId, memberId)` to read the current selection.
+Its `app.name` is Hub's name for the app that answers: the registered app of a consented grant, or the trusted app that serves the callback origin, else the callback host.
+Bindings starting with `line-grant:` belong to consented app grants and are refused here.
+Use `select(lineId, memberId, input)` with `expectedSelectionId`, `expectedMemberRevision`, `subjectId`, and `application`.
+The application supplies its approved HTTPS callback, binding, and callback secret.
+Use `clear(lineId, memberId, { expectedSelectionId, expectedMemberRevision })` to restore the default for future messages.
+Selection changes use compare-and-swap and refuse while this member has an active callback or provider delivery.
+Each inbound message pins its selected target.
+Revoked selections refuse pending work instead of redirecting it.
+Existing messages and execution receipts retain their original identity.
+This path uses the existing shared-application flag and remains disabled by default.
+Account-owner channel authority is separate from the app's agent workspace key.
+
+### Customer grants with separate sponsorship
+
+A server registers an application with `accessPayer: "app-owner"` when its owner sponsors platform eligibility. This is immutable: Hub uses the authenticated stored application owner, never a payer ID from the customer. Connections and grants still belong to the customer. The customer's native consent names the exact connection and actions. Existing explicit deny or approval policies still take precedence.
+
+Keep the application secret on your server. After same-session callback and state validation, use the maintained broker client:
+
+```ts
+import { HubAppBrokerClient } from "@tangle-network/hub-sdk";
+
+const broker = new HubAppBrokerClient({ baseUrl, clientId, clientSecret });
+const grant = await broker.exchange({ code, redirectUri, connectionId });
+const result = await broker.invoke(grant.grantId, connectionId, "github.issues.list", { owner: "example", repo: "project" });
+```
+
+`invoke` mints a fresh one-use, 60-second broker token and checks its selected scope before execution. The host application must recheck its own current customer enrollment on every call and revoke the app grant when access ends. Do not return broker tokens or application secrets to a browser or persist them in agent profiles.