@andco/sdk

OAuth, credentials, typed resource access, and Intent lifecycle for browser, server, and CLI applications. The runtime factories select the appropriate authorization and session behavior.

Developer preview: APIs may change before 1.0.

Install

pnpm add @andco/sdk @andco/bank-sdk

Use ES module imports. Browser integrations need a registered public client and a callback route that loads the app with the same SDK configuration. Server integrations require Node.js 24 or newer and a confidential client; keep its secret in the server environment.

Sign in and read accounts

import { Bank } from "@andco/bank-sdk";
import { createAndcoInstanceForBrowser } from "@andco/sdk/browser";

const andco = createAndcoInstanceForBrowser({
  clientId: "your-public-client-id",
  redirectTo: "https://app.example.com/auth/callback",
});
const bank = new Bank();
const { error: signInError } = await andco.auth.signIn({
  scopes: ["openid", "email"],
  authorizations: [bank.accounts.authorization({ actions: ["read"], subject: { type: "profile" } })],
});
if (signInError) throw signInError;
const { data: accounts, error } = await bank.use(andco.authorized()).client.http.GET("/accounts");
if (error) throw error;
console.log(accounts.edges);

Register the callback URL exactly and run signIn from a user click. OIDC scopes identify the person; the Bank builder requests access to their accounts.

Server OAuth

Set ANDCO_CLIENT_ID and ANDCO_CLIENT_SECRET on the server. Register https://app.example.com/auth/callback for this confidential client. In the login handler:

import { Bank } from "@andco/bank-sdk";
import type { AndcoAuthorizationRequest, AndcoSession } from "@andco/sdk";
import { createAndcoInstanceForServer } from "@andco/sdk/server";

const server = createAndcoInstanceForServer({
  clientId: process.env.ANDCO_CLIENT_ID!,
  clientSecret: process.env.ANDCO_CLIENT_SECRET!,
});
export async function startSignIn() {
  const { data: request, error } = await server.oauth.createAuthorizationRequest({
    redirectTo: "https://app.example.com/auth/callback",
    scopes: ["openid", "email"],
    authorizations: [
      new Bank().accounts.authorization({
        actions: ["read", "read_balance"],
        subject: { type: "profile" },
      }),
    ],
  });
  if (error) throw error;
  return request; // Store privately, then redirect to request.authorizationUrl.
}

// In the callback handler, recover that request and pass the complete callback URL:
export async function finishSignIn(callbackUrl: string, request: AndcoAuthorizationRequest) {
  const { data: session, error } = await server.oauth.exchangeCallback({ callbackUrl, request });
  if (error) throw error;
  return session; // Save privately before making further API calls.
}

// In an authenticated request, load that session from your server-side store:
export async function readAccounts(session: AndcoSession) {
  const { data: page, error } = await new Bank(server.with(session)).client.http.GET("/accounts");
  if (error) throw error;
  return page;
}

These are handler fragments: recover the transaction from your login store in each callback instead of sharing it between requests. Save the returned session privately. A session passed to with is a snapshot; your session layer also owns renewal and storage of rotated tokens. Your application owns the HTTP routes and session persistence; see the server guide for a complete handler.

End the browser session

const { error } = await andco.auth.signOut({ revoke: true });
if (error) throw error;

revoke: true revokes the Resource Grants and Identity Session before clearing local state. Plain signOut() only forgets the local session. Handle a failed revocation before discarding credentials needed to retry it.

Other capabilities

• @andco/sdk/server: confidential OAuth, approved Service credentials, and request-local andco.with(credentials).
• @andco/sdk/cli: terminal authorization with a registered loopback callback.
• andco.intents: read, present, approve, reject, cancel, and follow Intents created by a Resource Server.
• andco.resource: protect an application-owned Resource Server with audience-specific credentials and a live Grant.
• andco.grants: inspect or revoke delegated access.

Each Resource Server resolves its own Resource Token through accessTokenFor(resource). The Identity Session is for UserInfo and sign-out. Keep confidential client secrets on the server.

Learn more

• Integration guide
• API reference
• Runnable example

Method contracts, options, and lifecycle details are documented in the exported JSDoc and API reference.

Collection traversal

See REST pagination for pagination.listIterator, pagination.cursor, backward cursors, offsets, cancellation and stable Grant selection.

Bun and Deno smoke test

The runtime smoke test exercises the built public exports of @andco/sdk and @andco/sdk/server. It checks server client construction, bearer authentication on REST requests, traversal of two pages with opaque cursors, stopping at the terminal page, and UUID generation with the runtime's Web Crypto implementation.

Run these commands from the andco-sdk-js workspace root after installing dependencies with pnpm install. Build first so the test uses the current package code:

pnpm build

bun packages/sdk/tests/runtime-smoke.mjs

deno run --node-modules-dir=manual --no-config --no-lock \
  packages/sdk/tests/runtime-smoke.mjs

If Deno is not installed, replace deno run with pnpm dlx deno run. Manual node_modules mode uses the dependencies already installed by pnpm. The Deno command does not create a lockfile or require network permissions; the test injects a simulated fetch and needs no backend, credentials, or environment variables.

Both runtimes should print:

PASS: public imports, server client, authenticated REST, cursor pagination, Web Crypto

This test passed with Bun 1.3.14 and Deno 2.9.6 on macOS arm64 on October 5, 2026. It checks the local built packages; it does not test installation from npm, a complete OAuth flow against an Authorization Server, or browser and CLI adapters. Run it separately from pnpm test: it is a standalone script, not a Vitest suite.