Dots core

Canonical session/resource client for the Dots runtime CLI and app integrations. Alpha release @wrldbld/[email protected]. Install with npm install @wrldbld/[email protected]. For source builds, run bun run --cwd packages/dots-core build.

import { createDotsClient, createWebStorage } from '@wrldbld/dots-core';
const dots = createDotsClient({
  issuer: 'https://www.dots.id', clientId: 'YOUR_PUBLIC_CLIENT',
  storage: createWebStorage(sessionStorage, "dots:YOUR_PUBLIC_CLIENT:session"),
  transactionStorage: createWebStorage(sessionStorage, "dots:YOUR_PUBLIC_CLIENT:pkce"),
});
await dots.session.restore();
// Browser or native system browser; register the exact callback URI first.
const url = await dots.authorize('https://your-app.example/callback',
  'openid profile context:read context:write offline_access');
// Open url. On the callback page:
await dots.handleCallback(window.location.href);
const snapshot = await dots.whoami();
const results = await dots.context.search('project brief');

Use sessionStorage for pending browser login state; provide secure storage for tokens. A backend session with HttpOnly cookies is preferable when the app has a backend. In Expo use SecureStore, as the Worlds adapter does. loginDevice(scopes, ['api']) exposes { url, userCode, complete(signal) } for CLI/device sign-in. Add 'mcp' explicitly for MCP resource access.

Accounts are (issuer, sub). UserInfo over the authenticated issuer connection supplies identity; this client does not treat decoded ID tokens as proof. Refreshes are serialized, identity changes rejected, writes ordered, and sign-out cannot be reversed by a late refresh. request() stays on the issuer, rejects redirects, and retries a 401 once after refresh. Resource permissions always come from the server.

notes offers list/create/read/write/draft/drafts. grants offers share/list/read/respond/revoke. context offers search/recent/append. logout() clears locally and requests server revocation. Calls return the JSON defined in /openapi.json; use DotsError.code and status for failures.

The original @wrldbld/[email protected] API uses createDots({apiKey}); it is a separate compatibility surface. Migrate integrations to createDotsClient({clientId}) and the canonical session shape, reconnecting rather than copying unverified legacy sessions. Both wrldbld SDK checkouts also export this canonical createDotsClient from generated source; run node scripts/sync-dots-core.mjs --check to detect drift. Historical checkouts are not release sources for this core. packages/worlds-sdk/session.ts is generated from src/session.ts; scripts/sync-worlds-sdk.mjs --session-only distributes just this shared state machine to existing native apps without replacing their screens or API wrappers.

Register once with registerDotsApp({ name, redirectUris, scope }); save clientId and inspect missingScopes before asking the user to sign in. For a headless app, use mode: 'device' without callbacks. createMemoryStorage() supports ephemeral agents. Browser createWebStorage() wraps sessionStorage; native apps supply their OS secure-storage adapter.

@wrldbld/dots-core/mcp exports connectDotsMcp(dots), an authenticated official MCP client for tools and resources. @wrldbld/dots-core/webmcp exports registerDotsWebMcp(dots, { confirm }), which exposes all advertised Dots tools through the browser WebMCP API. Request both API and MCP resources during sign-in. Mutating tools require your confirmation handler; dispose on unmount. Unsupported browsers return supported: false. See the complete setup, catalog and troubleshooting guide (source: docs/WEBMCP.md).

Run the integration release checks from the repository root with bun run test:integrations. No package publication or live login is implied by passing local tests.

For your own headless agent, createDotsAgentAuth(dots, { scope: 'openid profile' }) exposes signIn(), status() and cancel() for model-visible tool handlers. Sign-in returns an approval URL, user code and expiry; the SDK polls in the runtime and stores tokens privately. Status returns only identity, client ID and scopes. Use one instance and secure storage namespace per human, restore saved sessions before exposing tools, keep the runtime alive while polling, and call dispose() at shutdown. cancel() cancels pending sign-in; dots.logout() signs out an approved account. Never return raw SDK sessions from tools.

For generic MCP hosts, /mcp has public setup and register_app tools. Calling signin starts host-managed OAuth through HTTP 401; the human can sign in or create an account on Dots. Retry after approval. A device link returned in chat does not install credentials in a generic MCP host.