@tangle-network/agent-runtime / platform
Thrown when a PlatformAuthClient request returns a non-success status.
Error
new PlatformAuthError(
message,status,body):PlatformAuthError
string
number
unknown
Error.constructor
readonlystatus:number
readonlybody:unknown
HTTP client for the Tangle Platform SSO: builds authorize URLs and exchanges auth codes for API keys.
new PlatformAuthClient(
options):PlatformAuthClient
authorizeUrl(
options):string
Build the URL the user is redirected to in order to start SSO.
The platform redirects back to one of appId's registered
redirectUris with ?code=...&app=...&state=....
string
exchange(
code):Promise<ExchangeCodeResult>
Exchange a single-use auth code (delivered to the consumer's callback by the platform) for an API key + the user's identity. Codes are single-use and expire ~5 minutes after issue.
string
Promise<ExchangeCodeResult>
Thrown when a PlatformHubClient request returns a non-success status.
Error
new PlatformHubError(
message,status,code,body):PlatformHubError
string
number
string | undefined
unknown
Error.constructor
readonlystatus:number
readonlycode:string|undefined
readonlybody:unknown
HTTP client for the Tangle Platform Hub API: provider catalog, connection flow, and status.
new PlatformHubClient(
options):PlatformHubClient
catalog():
Promise<CatalogResult>
GET /v1/hub/providers — the connectable provider catalog.
Promise<CatalogResult>
listConnections():
Promise<PlatformConnection[]>
GET /v1/hub/connections — the calling user's live connections.
Promise<PlatformConnection[]>
revokeConnection(
connectionId):Promise<{connection:PlatformConnection; }>
DELETE /v1/hub/connections/:connectionId — revoke + disable a connection.
string
Promise<{ connection: PlatformConnection; }>
startAuth(
input):Promise<StartAuthResult>
POST /v1/hub/connections/:provider/start — begin OAuth/grant. The provider
is taken from the URL; the body carries returnUrl (+ cli). The platform's
two start branches name the URL field differently (github → authorizationUrl,
substrate → redirectUrl); this normalizes to authorizationUrl.
Promise<StartAuthResult>
listHealthchecks():
Promise<HealthCheck[]>
Last-known health for every connection. The platform has no global
healthcheck listing — health rides on each connection row — so this derives
the list from listConnections() (one request, no extra round-trips).
Promise<HealthCheck[]>
checkConnectionHealth(
connectionId):Promise<ConnectionHealthResult>
POST /v1/hub/connections/:connectionId/health — trigger a fresh health probe for one connection and return its updated state.
string
Promise<ConnectionHealthResult>
runHealthchecks():
Promise<{scheduled:number; }>
Trigger a fresh health probe across all of the user's connections. The
platform exposes health per-connection only, so this fans out over
listConnections(). scheduled is the number of probes dispatched.
Promise<{ scheduled: number; }>
status():
Promise<PlatformHubStatus>
GET /v1/hub/status — principal + aggregate connection counts.
Promise<PlatformHubStatus>
mintToken(
input):Promise<MintTokenResult>
POST /v1/hub/tokens — mint a short-lived, action-scoped capability token a sandbox can use to invoke one hub action on the user's behalf without seeing the underlying provider credential.
Promise<MintTokenResult>
exec(
input):Promise<unknown>
POST /v1/hub/exec — execute a hub action and return its result.
Promise<unknown>
Server-side client for the Tangle platform's cross-site SSO bridge.
Consumer apps (gtm-agent, tax-agent, legal-agent, creative-agent, …) use this to:
- Build an /authorize URL that lands the user on id.tangle.tools and brings them back with a single-use code.
- Exchange that code for an API key + the user's identity.
The platform endpoint contract is documented in
products/platform/api/src/routes/cross-site.ts. This client only
speaks HTTP — no SDK weight, no transitive deps.
baseUrl:
string
Platform base URL, e.g. https://id.tangle.tools.
appId:
string
App id as registered in the platform's TRUSTED_APPS registry.
optionalfetchImpl?: (input,init?) =>Promise<Response>
Override the global fetch (useful for tests + edge runtimes).
string | URL | Request
RequestInit
Promise<Response>
@tangle-network/agent-runtime/platform — typed server-side clients
for the Tangle platform's cross-site SSO bridge and integrations
hub. Apps consume these to avoid rolling their own OAuth, session,
and connection storage.
See:
- PlatformAuthClient for "Login with Tangle"
- PlatformHubClient for the
/v1/hub/*surface
state:
string
Required CSRF token; the consumer verifies it on the callback.
optionalredirectUri?:string
Final redirect URI. Must be one of the URIs registered for appId
on the platform. Omit to use the first registered URI.
optionalprompt?:"login"
Force the login screen even if a session is already active.
optionalemail?:string
Pre-fill the email field on the login screen.
@tangle-network/agent-runtime/platform — typed server-side clients
for the Tangle platform's cross-site SSO bridge and integrations
hub. Apps consume these to avoid rolling their own OAuth, session,
and connection storage.
See:
- PlatformAuthClient for "Login with Tangle"
- PlatformHubClient for the
/v1/hub/*surface
apiKey:
string
user:
object
id:
string
email:
string
optionalname?:string
plan:
object
tier:
string
Server-side client for the Tangle platform's integration hub
(/v1/hub/*). Consumer apps use this instead of rolling their own
OAuth + connection tables.
Auth: the caller supplies a bearer (either the user's API key from cross-site exchange, or a platform service token) on construction.
Endpoint contract (authoritative): the platform's src/lib/hub-contract.ts
src/routes/hub.ts. The platform wraps every response in{ success, data }; non-2xx orsuccess:falsesurfaces asPlatformHubErrorcarrying the real upstream status.
baseUrl:
string
Platform base URL, e.g. https://id.tangle.tools.
bearer:
string
Bearer credential — user API key or service token.
optionalfetchImpl?: (input,init?) =>Promise<Response>
Override fetch (tests + edge runtimes).
string | URL | Request
RequestInit
Promise<Response>
A live integration connection, as returned by /v1/hub/connections.
id:
string
providerId:
string
displayName:
string
accountDisplay:
string|null
scopes:
string[]
status:
string&object|"active"|"unhealthy"|"revoked"|"reconnect_required"
health:
string&object|"unknown"|"healthy"|"unhealthy"|"rate_limited"
createdAt:
string
updatedAt:
string
lastUsedAt:
string|null
A connectable provider in the catalog (/v1/hub/providers).
[
k:string]:unknown
providerId:
string
optionaltitle?:string
optionalauthKind?:string
optionalcategory?:string
optionalscopes?:string[]
optionalcapabilityCount?:number
optionalnative?:boolean
optionalconfigured?:boolean
Whether the OAuth app's credentials are wired — the UI offers Connect only when true.
[
k:string]:unknown
providers:
PlatformCatalogProvider[]
optionalsubstrateBundled?:number
Count of substrate-bundled connectors behind the catalog.
providerId:
string
The provider to connect (goes in the URL path).
optionalconnectorId?:string
Accepted for interface compatibility; the platform's start endpoint is provider-level and does not consume a connector id.
returnUrl:
string
Where the platform redirects the user back to after OAuth.
optionalrequestedScopes?:string[]
Accepted for interface compatibility; not consumed by the start endpoint.
optionalcli?:boolean
CLI flow flag — affects the platform's post-auth redirect handling.
authorizationUrl:
string
The URL to send the user to. Normalized across the platform's two start
branches: github returns authorizationUrl, substrate returns
redirectUrl.
state:
string
optionalexpiresAt?:string
optionalscopes?:string[]
status:
string&object|"unknown"|"healthy"|"unhealthy"|"rate_limited"
checkedAt:
string
optionalerror?:object
code:
string
message:
string
connection:
PlatformConnection
health:
ConnectionHealth
Last-known health for a connection, derived from the connection row.
connectionId:
string
providerId:
string
status:
string&object|"unknown"|"healthy"|"unhealthy"|"rate_limited"
Mirrors PlatformConnection.health.
optionalcheckedAt?:string
actionPath:
string
The hub action the token authorizes (e.g. slack.chat.postMessage).
optionalconnectionId?:string
Bind to a specific connection, or …
optionalprovider?:string
… resolve the connection by provider for the calling user.
tokenId:
string
token:
string
expiresAt:
string
path:
string
The hub action path to execute.
optionalinput?:unknown
optionalconnectionId?:string
optionalcontract?:unknown
principal:
object
[k: string]: unknown
kind:
string
userId:
string
connections:
object
connectedProviderCount:
number
unhealthyProviderCount:
number