@tangle-network/hub-sdk 0.23.0-develop.20260814095115.1610dd0 → 0.23.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,128 @@ 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, binding, dispatchFence, dispatchDeadline },
+  callbackBearer,
+);
+```
+
+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`.
+
+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.