Federation SDK
Federation SDK
Federation exposes separate user and administrator access.
Use new Federation({ id: "team", name: "Team connection", url }) to assign a stable local identity and display name. The read-only id and name properties do not change the address or sign-in state. Without an explicit ID, remote instances use the normalized URL and local instances use local. The name defaults to the ID. Assign unique IDs when managing multiple connections.
A host can install an execution gate for HTTP/user requests with federation.guard_requests(acquire). acquire synchronously obtains a lease and returns its release function. The lease remains held until the response body ends, is cancelled, or fails. The method returns a function that removes this gate. Each instance accepts one gate; its creating host retains resource ownership. Local queue sending, consumption, and maintenance also pass through this gate. Callers retaining a connection use const release = federation.retain() to obtain a borrowing lease and call release() when disconnecting or dropping the handle. A retained instance remains subject to its owner's lifecycle.
A Federation user session owns identity, permissions, and Credits. Sign in by selecting a Federation and Provider, or supply an existing user_token.
import { Federation } from "@downcity/federation";
const federation = new Federation({ url: "https://fed.example.com" });
const providers = await federation.user.account.providers();
await federation.user.account.login({
provider: "email", client_type: "cli",
input: { email: "[email protected]", password: "password" },
});
const current_user = await federation.user.current();
const result = await federation.user.service("rewrite").action("formal").invoke({ text: "hello" });Verify an email before signing in. login() exchanges the completed flow and updates the user credential; status() only returns progress. await federation.user.account.logout() revokes the token before clearing it, preserving credentials on failure for retry. Federation validates signature, issuer, audience, expiry, and revocation. Admin Sessions remain separate from User Tokens.
City model and Power requests automatically carry the locally persisted city_id. Direct user requests may omit it. Independent callers can use federation.user.with_city("city_product") to create a source view. Source labels are recorded for logs, usage, and jobs and grant no permission. Use user.service(name) for business requests to the current Federation.
OAuth requires random state, S256 PKCE, and a single exchange. Website callbacks must exactly match server trusted_web_callbacks; an empty list rejects web OAuth. CLI/Desktop use an exclusive local 127.0.0.1 callback receiver. See account sign-in.