Types Reference

The TypeScript SDK exports these public types from configure.

ConfigureOptions

type ConfigureOptions = {
  apiKey?: string;
  agent?: string;
  externalId?: string;
  timeout?: number;
  fetch?: typeof fetch;
  baseUrl?: string;
};

All fields are optional in the type because the constructor can resolve apiKey from CONFIGURE_API_KEY and agent from CONFIGURE_AGENT. At runtime, construction still fails if no API key or agent handle can be resolved.

externalId is an optional default app-local user identifier for unlinked profiles. When set, profile and file operations use it unless a configure.profile() call supplies another externalId. Connector and web utility operations require the agent-scoped token returned by Configure.link(); they do not use externalId.

baseUrl is an advanced override for local or staging development. Do not include it in normal production snippets.

Agent Handles

agent is the public agent handle. The SDK validates it before sending requests:

• Lowercase letters, numbers, and hyphens only.
• 2 to 63 characters.
• Starts and ends with a letter or number.
• Reserved handles are rejected.

ProfileRuntimeOptions

type ProfileRuntimeOptions = {
  token?: string;
  externalId?: string;
};

Use token for a linked Configure user. Use externalId without token for a developer-scoped app-local user. externalId is the developer's ID, not a Configure-generated user ID.

SignInUrlOptions

type SignInUrlOptions = {
  publishableKey?: string;
  returnTo?: string;
  state?: string;
  journeyId?: string;
  displayName?: string;
  agentName?: string;
  agentLogo?: string;
  delivery?: "browser" | "message" | "messages" | "imessage" | "sms" | "opener" | string;
  messageLinePhone?: string;
  agentPhone?: string;
  messageBody?: string;
  messageCompleteUrl?: string;
  connectors?: ConnectorName[] | string;
  signInOrigin?: string;
  theme?: "light" | "dark";
};

Call configure.auth.signInUrl() with no options for the canonical https://sign-in.me/{agent} URL. Registered agents resolve credentials, branding, and delivery metadata server-side. The options remain for backward compatibility and local or advanced handoffs. Use CreateMessageSignInUrlOptions only for provider-signed message binding or thread-specific completion callbacks.

MessageLine

type RegisterMessageLineOptions = {
  channel?: string;
  phone: string;
  label?: string;
  metadata?: Record<string, unknown>;
};

type RevokeMessageLineOptions = {
  channel?: string;
  phone: string;
};

type MessageLine = {
  id: string;
  channel: string;
  phoneLast4: string;
  label: string | null;
  status: "active" | "revoked";
  metadata: Record<string, unknown>;
  createdAt?: string;
  updatedAt?: string;
};

type RegisterMessageLineResult = { line: MessageLine };
type ListMessageLinesResult = { lines: MessageLine[] };
type RevokeMessageLineResult = { deleted: boolean; lines: MessageLine[] };

Use with configure.auth.registerMessageLine(), listMessageLines(), and revokeMessageLine() on a trusted server. Message lines are agent infrastructure: Configure stores only a hash and last4, and SDK responses never include the raw phone number. metadata is non-secret operator metadata such as provider/source labels; raw phone fields or phone-like values are rejected.

CreateMessageSignInUrlOptions

type MessageSignInReason = "signin" | "reconnect" | "permissions";

type CreateMessageSignInUrlOptions = {
  reason: MessageSignInReason;
  channel: string;
  subject: {
    key: string;
    externalId: string;
    senderId?: string;
  };
  thread?: {
    key?: string;
    spaceId?: string;
    messageId?: string;
  };
  /** Provider-signed evidence that the message sender/thread claim is authentic. */
  messageSenderProof?: string;
  connectors?: ConnectorName[] | string[];
  displayName?: string;
  agentLogo?: string;
  theme?: "light" | "dark";
  messageLinePhone?: string;
  agentPhone?: string;
  messageBody?: string;
  messageCompleteUrl?: string;
  journeyId?: string;
  returnMode?: "message";
  idempotencyKey?: string;
};

type CreateMessageSignInUrlResult =
  | {
      mode: "minted";
      url: string;
      code: string;
      reason: MessageSignInReason;
      expiresAt: string;
      idempotencyKey?: string;
    }
  | {
      mode: "plain";
      url: string;
      reason: MessageSignInReason;
      fallbackReason:
        | "sender_proof_missing"
        | "sender_proof_invalid"
        | "sender_proof_unsupported";
      idempotencyKey?: string;
    };

Use with configure.auth.createMessageSignInUrl() on a trusted server. agentPhone is an alias for messageLinePhone and should be the current provider-owned return line for the agent. messageCompleteUrl and journeyId let hosted completion map approval back to the message thread without exposing raw message content. The result is a plain sign-in.me/{agent} handoff unless Configure can verify provider-signed messageSenderProof and mint a short-lived message-bound code. Plain sign-in and reconnect fallbacks preserve message return metadata when a current line is supplied.

MessageIdentity

type MessageIdentityResolveOptions = {
  externalId: string;
  token?: string | null;
  phoneCandidates?: string | string[] | null;
  validateToken?: boolean;
  throwOnAuthError?: boolean;
};

type MessageIdentity = {
  externalId: string;
  token?: string;
  userId?: string;
  linked: boolean;
  approved: boolean;
  recognized: boolean;
  displayName?: string | null;
  source: "token" | "phone_recognition" | "external_id";
};

Use with configure.auth.resolveMessageIdentity() in iMessage, SMS, and other message-channel agents. A linked result includes token; an unlinked result keeps the supplied externalId.

ConfigureBetterAuthOAuthProviderOptions

type ConfigureBetterAuthOAuthProviderOptions = {
  clientId: string;
  clientSecret: string;
  apiKey: string;
  agent: string;
  providerId?: string;
  baseUrl?: string;
  accountsOrigin?: string;
  resource?: string;
  scopes?: string[];
  fetch?: typeof fetch;
};

Use with configureBetterAuthOAuthProvider() when Configure should appear as a Better Auth Generic OAuth provider. The helper returns a provider config with PKCE enabled, authentication: "basic", the Configure API resource, and a server-side getUserInfo() implementation backed by configure.profile({ token }).

Hosted Sign-In Results

type SignInExchangeResult = {
  token: string;
  userId: string;
  tokenUse: "agent";
  approved: boolean;
  agent: string;
};

type SignInTokenValidationResult = {
  valid: boolean;
  userId?: string;
  tokenUse?: "agent";
  approved?: boolean;
  agent?: string;
};

type SignInPhoneRecognitionResult = {
  matched: boolean;
  recognized?: boolean;
  approved: boolean;
  linked: boolean;
  token?: string;
  agentToken?: string;
  userId?: string;
  agent?: string;
  displayName?: string | null;
  phoneCandidateCount: number;
};

exchangeSignInCode() returns a token after a hosted callback. validateSignInToken() checks a stored or callback token. recognizePhone() recognizes verified phone candidates and exact OAuth-verified email-form message handles, and returns a token only when the recognized user has approved the acting agent.

ProfileReadOptions

type ProfileReadOptions = {
  sections?: Array<"identity" | "preferences" | "integrations" | "imports" | "agents" | "summary">;
  box?: string;
  page?: number;
  since?: string;
  detail?: "compact" | "full";
};

imports contains user-directed ChatGPT, Claude, Gemini, Grok, or other memory imports. integrations contains connected tools such as Gmail, Calendar, Drive, and Notion. Omit sections to receive all six sections.

box opens one box from the profile read's table of contents: a category such as work, a source such as agents/parry or imports/chatgpt, or a shared project tag such as projects/<slug>. page continues a long box; pages start at 1 and the option only applies with box.

Usage:

const result = await configure.profile({ token }).read();

ProfileReadResult

type ProfileReadResult = {
  profile: UserProfile;
  portable: boolean;
  filtered: boolean;
  hiddenSources?: string[];
};

profile.read() resolves to this shape. The profile sections live under result.profile, not at the top level.

UserProfile

type UserIdentity = {
  name?: string;
  email?: string;
  phone_last4?: string;
  occupation?: string;
  location?: string;
  bio?: string;
  interests?: string[];
};

type UserProfile = {
  identity: UserIdentity;
  preferences: string[];
  summary?: string;
  integrations: Record<string, IntegrationData>;
  imports: Record<string, ImportedSourceData>;
  agents: Record<string, Record<string, unknown>>;
  linked?: boolean;
  filtered?: boolean;
  hiddenSections?: string[];
  format(options?: ProfileFormatOptions): string;
};

identity has no displayName field; use identity.name. integrations is a record keyed by connector name, not an array.

ProfileFormatOptions

type ProfileFormatOptions = {
  includeTools?: boolean;
  includeConnectorSnapshots?: boolean;
  guidelines?: boolean;
};

Options for profile.format(). includeConnectorSnapshots includes small connector-derived snapshots already present in the profile read response; includeTools is its legacy alias. guidelines defaults to true; pass false to omit the CONFIGURE_GUIDELINES block.

IntegrationData

type IntegrationData = {
  connected: boolean;
  reconnectRequired?: boolean;
  error?: string;
  accountEmail?: string;
  accountName?: string;
  accountUsername?: string;
  providerAccountId?: string;
  connectedAccountId?: string;
  defaultAccountId?: string;
  accounts?: Array<{
    connectedAccountId: string;
    providerAccountId?: string;
    accountEmail?: string;
    accountName?: string;
    accountUsername?: string;
    status?: "ready" | "reconnect";
    error?: string;
  }>;
  ranked?: Record<string, unknown>[];
  synthesis?: {
    facts: { category: string; fact: string; confidence: number }[];
    summary: string;
  };
  preferences?: string[];
  events?: unknown[];
  files?: unknown[];
  pages?: unknown[];
  spreadsheets?: unknown[];
};

List the connected integrations by filtering the record:

const connected = Object.entries(result.profile.integrations)
  .filter(([, data]) => data.connected)
  .map(([name]) => name);

ConnectorName

type ConnectorName = "gmail" | "outlook" | "calendar" | "drive" | "notion" | "sheets";

ProfileSearchOptions

type ProfileSearchOptions = {
  query?: string;
  box?: string;
  source?: string;
  from?: string;
  to?: string;
  limit?: number;
  detail?: "compact" | "full";
};

Search returns ranked attributed profile data scoped by user and agent permissions. Omit query or pass query: "*" to list bounded permitted results. Compact hits include source attribution and omit raw CFS paths/provenance; full detail includes safe path, marker, provenance, and update metadata.

box scopes the search to one box id from the profile read's table of contents and composes with query. Shared projects/<slug> boxes work from SDK apps, and the REST endpoint accepts ?box=.

A bare provider name in source (chatgpt, claude, gemini, grok, or other) matches both an agent with that name and the import shelf; each hit keeps its own source label. Use imports/<provider> or import:<provider> for import-only filtering, and agents/<name> for agent-only filtering.

ProfileSearchResult

type ProfileSearchResult = {
  results: ProfileSearchHit[];
  filtered: boolean;
  hiddenSources?: string[];
  visibleSources?: string[];
  sourceCounts?: Record<string, { matched: number; returned: number; hidden?: number }>;
  diagnostic?: {
    status:
      | "ok"
      | "partial_results"
      | "truncated"
      | "no_matches"
      | "source_not_found"
      | "filtered_by_permissions"
      | "auth_missing"
      | "agent_unresolved";
    message: string;
    next_action?: string;
  };
  truncated?: boolean;
};

type ProfileSearchHit = {
  id: string;
  title?: string;
  text: string;
  snippet?: string;
  path?: string;
  source: string;
  source_type?: "agent" | "import";
  provider?: "chatgpt" | "gemini" | "claude" | "grok" | "other";
  written_by?: string;
  imported_by_agent?: string;
  created_at?: string;
  updated_at?: string;
  event_at?: string;
  score?: number;
  type?: string;
  markers?: string[];
  provenance?: Record<string, unknown>;
};

ProfileCommitInput

type ProfileCommitInput = {
  messages?: Array<{ role: "user" | "assistant" | "tool"; content: string; toolName?: string }>;
  response?: unknown;
  toolResults?: Array<{ toolName: string; content: string | object }>;
  memories?: string[];
  sync?: boolean;
};

commit() accepts bounded source material. messages or toolResults can clear read-backed commit obligations; memories are optional durable facts/preferences. It does not accept metadata or internal read-obligation/source-context fields.

ProfileCommitResult

type ProfileCommitResult = {
  status: "processing" | "completed";
  facts_written?: string[];
  user_summary?: string;
  memories_written?: Array<{
    id?: string;
    path: string;
    source: string;
    written_by?: string;
    created_at?: string;
    type?: string;
    marker?: string;
  }>;
  obligations_committed?: string[];
  rejected_memories?: Array<{ memory: string; reason: string }>;
};

commit() resolves to this shape. facts_written lists facts extracted and saved to the user's memory; user_summary is the updated summary after commit. rejected_memories explains any candidate memories the admission gate declined.

RememberResponse

type RememberResponse = {
  saved: boolean;
  app: string;
  fact: string;
  memory?: ProfileSearchHit;
};

profile.remember(fact, options?) resolves to this shape. The optional second argument is { box?: string }: the writer-chosen box to file the fact into, including shared projects/<slug> boxes. Remember is part of the default model-facing tool set alongside read, search, and forget. The RememberResponse type is not currently re-exported from the package, so treat this shape as the reference.

ForgetResponse

type ForgetResponse = {
  deleted: boolean;
  id: string;
  path?: string;
  source?: string;
  suppressed?: boolean;
  suppressed_copies?: number;
  message?: string;
};

profile.forget(id, options?) resolves to this shape. The optional second argument is { date?: string; reason?: "correction" | "user_request" }. Forget deletes only the acting agent's own memories. Passing reason: "user_request" also suppresses matching copies held elsewhere; suppressed and suppressed_copies report that outcome. Forget is part of the default model-facing tool set, so agents can handle "forget that" everywhere. The ForgetResponse type is not currently re-exported from the package, so treat this shape as the reference.

Import Types

type ImportMode = "backfill";
type ImportJobStatus = "queued" | "processing" | "completed" | "failed" | "cancelled";

type ImportProfilesRequest = {
  mode: "backfill";
  // Scoped to the developer account and acting agent.
  idempotencyKey?: string;
  users: Array<{
    externalId: string;
    idempotencyKey?: string;
    profile?: {
      summary?: string;
      preferences?: string[];
      facts?: string[];
      identity?: Record<string, string>;
      [key: string]: unknown;
    };
    conversations?: Array<{
      id?: string;
      messages: Array<{
        role: "system" | "user" | "assistant" | "tool";
        content: string;
      }>;
    }>;
  }>;
};

type ImportJob = {
  id: string;
  mode: "backfill";
  status: ImportJobStatus;
  accepted_profiles: number;
  estimated_message_count: number;
  estimated_input_chars: number;
  imported_memory_count: number;
  processed_profile_count: number;
  failed_profile_count: number;
  quota?: {
    imported_profiles: {
      used: number;
      limit: number | "unlimited";
      requestedNew: number;
      remaining: number | "unlimited";
    };
  };
  caps?: {
    max_profiles_per_job: number;
    max_total_input_chars_per_job: number;
    max_concurrent_import_jobs: number;
    max_conversations_per_profile: number;
    max_messages_per_conversation: number;
    max_chars_per_message: number;
  };
  created_at: string;
  updated_at: string;
  started_at?: string | null;
  completed_at?: string | null;
  cancelled_at?: string | null;
  error?: {
    code?: string | null;
    message?: string | null;
  };
  reused?: boolean;
};

Use configure.importProfiles() for historical/onboarding backfill and configure.importJobs.get(jobId) for polling. Check error when a polled job reports status: "failed". reused is true when an idempotency key matched an existing job and the request was replayed instead of creating a new one. Import is server-side and secret-key only; it is not a model tool and does not write root profile files.

ProfileToolsOptions

type ProfileToolsOptions = {
  connectors?: Array<"gmail" | "outlook" | "calendar" | "drive" | "notion" | "sheets">;
  actions?: Array<
    | "email.send"
    | "calendar.create_event"
    | "sheets.values_update"
    | "sheets.values_append"
    | "sheets.create_spreadsheet"
    | "sheets.add_sheet"
  >;
  advanced?: {
    commit?: boolean;
    files?: boolean;
    utilitySearch?: boolean;
  };
};

connectors and actions control which non-default tools are returned and executable for that profile object. Use them for capabilities the hosted/product surface requested and the app supports. advanced exposes adapter tools, utility web tools, and raw profile file tools; these are not part of the default model-facing tool set. Hosted UI helpers are separate optional surfaces, not default model tools.

ConfigureToolCall

type ConfigureToolCall = {
  name?: string;
  arguments?: Record<string, unknown> | string;
  input?: Record<string, unknown>;
  function?: {
    name?: string;
    arguments?: Record<string, unknown> | string;
  };
};

profile.executeTool() accepts common tool-call shapes from model SDKs and normalizes them internally.

ConfigureError

SDK failures throw ConfigureError with a stable code, optional statusCode, and structured fields such as type, param, retryable, suggestedAction, docUrl, retryAfter, and requestId. See Errors Reference for the code list and field semantics.