@wrldbld/dots

Portable dots.id identity, context, app data, attestations, and pute credits for browser applications.

Install

npm install @wrldbld/dots@alpha

Configure

Create a public OAuth client at dev.dots.id. Register your exact callback URL, such as https://app.example/dots/callback.

import { createDots } from "@wrldbld/dots";

export const dots = createDots({
  apiKey: process.env.NEXT_PUBLIC_DOTS_API_KEY!,
  scopes: [
    "openid",
    "profile",
    "email",
    "offline_access",
    "context:read",
    "context:write",
    "data:read",
    "data:write",
    "pute:read",
    "pute:spend",
    "pute:topup",
  ],
});

The apiKey is the public OAuth client_id, not a secret. Never ship a confidential client secret in browser code.

Sign in

await dots.signIn();

// On /dots/callback:
const user = await dots.handleCallback();

console.log(user.sub); // immutable dots subject

Persist app users under a unique (issuer, sub) key. Never merge users by email, wallet, or username.

APIs

const status = await dots.identity.status();
const balance = await dots.credits.balance();
await dots.credits.debit(1, { requestId: jobId });

await dots.context.append({ content: "User selected dark mode", kind: "preference" });
await dots.data.set("prefs", "theme", { mode: "dark" });
const theme = await dots.data.get("prefs", "theme");

const attestations = await dots.attestations.list();
const emails = await dots.emails.list();

Only request scopes your app actually uses. The server binds context, data, and credit operations to the authenticated OAuth client.