@tangle-network/hub-sdk 0.54.2-develop.20260926224237.f161716 → 0.60.12-develop.20261003121634.9b53e11

package/README.md

@@ -124,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
@@ -252,6 +275,28 @@ Past it, `admit` answers `allowance_reached`, and `turn.period` shows `spent`, `
 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?)`
@@ -304,6 +349,26 @@ 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
@@ -315,3 +380,26 @@ 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.