# Configure TypeScript SDK

Configure gives your app the context a user already built up in their AI assistants and apps: who they are, what they work on, what they prefer. The user brings it to Configure once and approves your app; your server reads it from then on.

Full docs: <https://docs.configure.dev>. This README is the short path.

## Install and keys

```bash
npm install configure
npx configure setup    # opens Configure, creates keys, writes them to .env
```

Your server needs `CONFIGURE_API_KEY` (the `sk_` key, never in a browser) and `CONFIGURE_AGENT` (your agent handle). Use a `sk_test_` key for development: it runs against a sandbox user, Nova.

## Add Configure to your app

Key every user by the id your product already has. That one id is the whole identity model: the user never sees it, and when they connect, Configure links their account to it. Never use a session or cookie id.

```ts
import { Configure } from "configure";

const configure = new Configure({
  apiKey: process.env.CONFIGURE_API_KEY,
  agent: process.env.CONFIGURE_AGENT,
});
const profileFor = (userId: string) => configure.profile({ externalId: userId });

// 1. Your "Connect" button links here. Mint a link per click and redirect to it.
app.get("/configure/start", async (req, res) => {
  const connect = await profileFor(req.user.id).connect({ returnUrl: "https://yourapp.com/configure/return" });
  res.redirect(connect.connect_url);
});

// 2. Configure sends the user back. Read their context; profile.linked says whether they connected.
app.get("/configure/return", async (req, res) => {
  const read = await profileFor(req.user.id).read({ sections: ["identity", "preferences", "summary"] });
  if (!read.profile.linked) return res.redirect("/?configure=not-finished");
  await store.set(req.user.id, read.profile.format());   // the text you put in your system prompt
  res.redirect("/chat");
});

// 3. After a chat turn, commit it so the user's context keeps learning.
await profileFor(userId).commit({
  messages: [
    { role: "user", content: userText },
    { role: "assistant", content: assistantText },
  ],
});
```

`returnUrl` must be a constant `https` URL, never built from the request. Their context keeps growing after they connect; register a webhook so your server re-reads it when it changes:

```ts
const hook = await configure.webhooks.set({ url: "https://yourapp.com/configure/webhook" });   // once per environment
app.post("/configure/webhook", configure.webhooks.handler(process.env.CONFIGURE_WEBHOOK_SECRET!, async (event) => {
  await refreshContext(event.data.user.external_id);   // your function: read() and store again
}));   // mount before express.json(): it checks the signature on the raw body
```

Profile text is user data, not instructions. Strip your prompt delimiter from it before you wrap it: see <https://docs.configure.dev/trust>.

## Give the model the Configure tools

To let the model read and search the user's context during a turn, expose the Configure tools next to yours and route `configure_*` calls to Configure. `profile.tools()` is Anthropic-shaped (`{ name, description, input_schema }`); wrap it with `toOpenAIFunctions()` for OpenAI. `executeTool` accepts `{ name, arguments }` or `{ name, input }`.

```ts
const profile = profileFor(userId);
const tools = [...yourTools, ...profile.tools()];
const dispatch = (toolCall) =>
  toolCall.name.startsWith("configure_") ? profile.executeTool(toolCall) : executeYourTool(toolCall);
```

Check the wiring without a model by calling a tool directly:

```ts
const result = await profile.executeTool({
  name: "configure_profile_read",
  arguments: { sections: ["identity", "summary", "preferences", "imports"] },
});
```

To offer connected apps, ask for them explicitly. Tool visibility is app capability, not user authorization: `executeTool` still fails closed when the user has not connected or approved the app, and the structured error tells you to send them through `connect({ app })`.

```ts
const tools = [
  ...yourTools,
  ...profile.tools({
    connectors: ["gmail", "calendar", "drive", "notion"],
    actions: ["email.send", "calendar.create_event"],
  }),
];
```

## Other ways in

- **A browser token instead of your user id.** The hosted Link and Personalization components hand your page a token in the `configure:linked` event, and the server uses `configure.profile({ token })`. Use this only when you have no user id of your own; otherwise keep the one `externalId` path above. See "Browser linking and components" below.
- **Sign in with Configure (OAuth).** `npx configure verify`, `npx configure add callback --framework next|express|vite`, and `npx configure add origin <callback>` set up and prove the OAuth flow. See <https://docs.configure.dev/variations>.
- **Message agents** (SMS, iMessage, WhatsApp): see the next section.

## Message-agent SSO

Every registered agent has one hosted sign-in URL. Send the `sign_in_url` returned by the agent API, or get the same value from `configure.auth.signInUrl()`:

```ts
await message.reply(`Connect your profile: ${configure.auth.signInUrl()}`);
```

Configure resolves the browser credential, branding, phone verification, consent, and connectors server-side. Multiple Gmail accounts work by default. New integrations do not pass a publishable key, delivery mode, or phone number in the URL.

For message channels that provide provider-signed sender binding or need a thread-specific completion webhook, use the advanced SDK helpers below.

```ts
const subjectKey = message.sender?.id || space.id;
const agentPhone = await smsProvider.currentPhone();

await configure.auth.registerMessageLine({
  channel: "sms",
  phone: agentPhone,
  label: "Primary SMS line",
  metadata: { provider: "your-sms-provider" },
});

const handoff = await configure.auth.createMessageSignInUrl({
  reason: "signin",
  channel: "sms",
  subject: {
    key: subjectKey,
    externalId: `sms:${subjectKey}`,
    senderId: message.sender?.id,
  },
  thread: {
    key: space.id,
    spaceId: space.id,
    messageId: message.id,
  },
  messageSenderProof: providerSignedMessageSenderProof,
  agentPhone,
  messageBody: "done",
  connectors: ["gmail", "calendar"],
  idempotencyKey: `${space.id}:${message.id}:signin`,
});

await message.reply(`Connect your profile: ${handoff.url}`);
```

This advanced path binds the provider's current return line and signed sender evidence. Register `agentPhone` before generating a managed URL. `createMessageSignInUrl()` falls back to the canonical hosted URL when Configure cannot verify sender proof. Application code always sends the returned URL unchanged.

On each inbound message, resolve the best Configure identity. A linked user returns a token; everyone else keeps working with your app-local `externalId`:

```ts
const subjectKey = message.sender?.id || space.id;
const stored = await store.get(subjectKey);

const identity = await configure.auth.resolveMessageIdentity({
  externalId: `sms:${subjectKey}`,
  token: stored?.configureToken,
  phoneCandidates: [
    message.sender?.phone,
    message.sender?.address,
    message.sender?.id,
    space.phone,
  ].filter((value): value is string => Boolean(value)),
});

if (identity.token && identity.token !== stored?.configureToken) {
  await store.save(subjectKey, {
    configureToken: identity.token,
    configureUserId: identity.userId,
  });
}
```

Then pass the identity straight to `profile()`: it uses the token when the sender is linked and your `externalId` otherwise. `identity.linked` says which.

```ts
const profile = configure.profile(identity);
if (!identity.linked) await message.reply(`Connect your profile: ${configure.auth.signInUrl()}`);
```

For existing Better Auth apps, pass `configureBetterAuthOAuthProvider()` into Better Auth's Generic OAuth plugin:

```ts
import { configureBetterAuthOAuthProvider } from "configure";
```

Use `configure.auth.signInUrl({ returnTo, state, ... })`, `auth.allowSignInReturnTo()`, and `auth.exchangeSignInCode()` when Configure is an account connection inside an already signed-in app session.

`baseUrl` is only for internal staging/local development and advanced deployments; it should not appear in the normal production path.

Default model tools are only:

- `configure_profile_read`
- `configure_profile_search`
- `configure_profile_remember`

Everything else is explicit app capability. Connector tools, action tools, utility web tools, raw file tools, and hosted UI tool helpers are optional surfaces; expose only the categories your runtime actually supports, then let `profile.executeTool()` enforce user state and permissions.

`profile.search()` returns compact attributed hits by default. Compact hits omit raw CFS paths and provenance; pass `detail: "full"` when an inspector or admin flow needs safe metadata such as `path`, `markers`, `provenance`, and `updated_at`.

Use `sections: ["imports"]` or `profile.search({ query: "*", source: "chatgpt" })` for user-directed ChatGPT/Claude/etc. imported memories. Use `integrations` for connected tools such as Gmail, Outlook, Calendar, Drive, and Notion.

Outlook-aware runtimes opt in with `connectors: ["outlook"]`. This adds `configure_email_search`; omitting `provider` and `account` searches every permitted Gmail and Outlook account. Gmail-only runtimes keep the existing `configure_gmail_search` and email-send schema.

Connector and action tools are enabled explicitly when the hosted/product surface requested those capabilities and the app supports them:

```ts
profile.tools({
  connectors: ["gmail", "calendar", "drive", "notion"],
  actions: ["email.send", "calendar.create_event"],
});
```

You can also enable only the action subset your app supports. Let execution enforce linked state, connector state, permissions, scopes, and any required approval flow:

```ts
profile.tools({
  connectors: ["gmail"],
  actions: ["email.send"],
});
```

Utility web tools are advanced runtime capabilities:

```ts
profile.tools({
  advanced: { utilitySearch: true },
});
```

Raw file path access is advanced and lives under `configure.files.*`. Raw agent filesystem APIs are not part of the public default SDK shape.

Bulk historical/onboarding backfill is separate from runtime `profile.commit()`:

```ts
const job = await configure.importProfiles({
  mode: "backfill",
  users: [
    {
      externalId: "customer-123",
      profile: { preferences: ["Prefers concise replies."] },
      conversations: [{
        id: "thread-1",
        messages: [{ role: "user", content: "I usually fly out of SFO." }],
      }],
    },
  ],
});

const status = await configure.importJobs.get(job.id);
```

Import is server-side only, requires an `sk_` key, and is not exposed as a model-facing tool.

## Browser linking and components

Production browser integrations should use the hosted script:

```html
<script src="https://configure.dev/js/configure.js"></script>
```

`Configure.link()` handles user-present identity, seeding, consent, iframe isolation, resizing, and the `configure:linked` event. The host sends the returned agent-scoped token to its backend, then the backend uses `configure.profile({ token })`.

For chat inputs, `Configure.personalizationButton()` renders a compact `+` menu entry with the canonical Personalization toggle. The entry should trigger Configure, while `linkEl` mounts Configure Link in a dismissible inline chat panel. Let the panel span the assistant message lane (`width: min(100%, var(--chat-max, 640px))`) and do not cap the host at 420px or mount it inside the composer row. This is the default placement for chat products — not a settings page or a standalone chat-bar button. The `onEvent` callback exposes the agent-scoped token at `event.payload.token`; send only that token to your backend:

```js
Configure.personalizationButton({
  el: "#configure-entry",
  linkEl: "#configure-link-host",
  publishableKey: "pk_...",
  agent: "your-agent",
  displayName: "Your Agent",
  font: "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
  onImage: () => openImagePicker(),
  onFile: () => openFilePicker(),
  onEvent(event) {
    if (event.type === "configure:personalization-open") {
      showInlineConfigurePanel();
      return;
    }
    if (event.type === "configure:linked") {
      hideInlineConfigurePanel();
      fetch("/api/configure/session", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ token: event.payload.token }),
      });
    }
  },
});
```

`displayName` is cosmetic UI copy. The `agent` handle is the identity used for tokens, storage, permissions, and attribution.

For a polished personalization entry, render the hosted surface with the agent-scoped token returned by Link:

```js
Configure.personalizationPage({
  el: "#personalization",
  publishableKey: "pk_...",
  agent: "your-agent",
  displayName: "Your Agent",
  token: configureAgentToken,
  theme: "light",
  onEvent(event) {
    if (event.type === "configure:personalization-connect") {
      window.location.href = "/configure/start";   // your route: connect({ returnUrl }), then redirect
    }
  },
});
```

The surface emits `configure:personalization-connect` only after the user clicks **Connect Configure**. Send the user to a route on your server that mints a link with `profile.connect({ returnUrl })` and redirects to its `connect_url`; Configure brings them back to `returnUrl` when they finish ([Quickstart](https://docs.configure.dev/quickstart)). Passive navigation makes no profile or model request.

Images and Files stay host-owned; the helper also emits `configure:image-select` and `configure:file-select`. (The declarative `data-configure-link` trigger instead exposes the token at `event.detail.token` — use it only for settings pages or static buttons.)

If your chat UI already has an inline integrations list instead of a `+` menu, render Configure as a rounded lockup button:

```js
Configure.personalizationButton({
  el: "#configure-integration",
  publishableKey: "pk_...",
  agent: "your-agent",
  displayName: "Your Agent",
  variant: "integration",
});
```

Never expose `sk_` keys in browser code. Browser code uses publishable keys (`pk_...`); the model receives Configure tool results or formatted approved profile context, not Link tokens or user IDs.

When Configure is the auth handoff for your app, use the hosted first-party surface instead of building a custom OTP flow:

```js
Configure.signInWithPopup({
  publishableKey: "pk_...",
  agent: "your-agent",
  displayName: "Your Agent",
  returnTo: "https://app.example/auth/configure/callback",
  state: "opaque",
  fallback: "redirect",
});
```

Allowlist `returnTo` with `POST /v1/auth/sign-in/return-destinations` using your `sk_` key, then exchange the returned `cfgsic_...` code server-side with `POST /v1/auth/sign-in/exchange`. Store the returned agent-scoped token in your app session and pass it into later inline Configure surfaces with `Configure.link({ token, userId, ... })` so the user does not repeat OTP. Use the popup path when preserving desktop app context matters; redirect to `https://accounts.configure.dev/?pk=...&agent=...&return_to=...` for mobile, popup-blocked browsers, or simpler auth routes.

Raw web components are included for local labs and advanced self-hosted surfaces:

```ts
import "configure/components";
```

`configure/components` imports `lucide` and `xstate`, which are not installed with `configure`. Install them first: `npm install lucide xstate`, plus `lit` if you compile against the element types. The CDN bundle below carries everything it needs.

The browser bundle is also packaged at `configure/components/cdn`, and the narrow `configure/browser` entry point exists for browser bundlers. The hosted script remains the recommended production path.

### Hosted plugin context (staging candidate)

With your server-side secret key, read the context selected for your agent's
exact hosted setup. A public `setup_ref` does not authorize a read. Configure
checks the key's agent, developer, data plane and the user's current permissions.
Installation and redirecting are separate from a confirmed context read.

```ts
const selected = await configure.setups.context(setupRef);
// Use selected.memories in this agent's next turn before acknowledging.
await configure.setups.acknowledge(setupRef, selected.revision);
```

This candidate API is enabled on staging. It is not part of the published plugin
runtime until the updated adapters and backend are released.
