configure/dist/types.d.mts

Identity layer SDK for AI agents

/**
 * SDK configuration options.
 */
interface ConfigureOptions {
    /** API key (sk_xxx). Alternative to passing as first constructor argument. */
    apiKey?: string;
    /** Advanced: override API origin for local development or private deployments. */
    baseUrl?: string;
    /** Agent handle — lowercase letters, numbers, and hyphens. */
    agent?: string;
    /** Developer app-local user ID for unlinked profiles — sends X-User-Id. */
    externalId?: string;
    /** Optional timeout in milliseconds for requests */
    timeout?: number;
    /** Custom fetch implementation (for Node.js compatibility) */
    fetch?: typeof fetch;
}
type ProfileSection = 'identity' | 'preferences' | 'integrations' | 'agents' | 'summary';
interface ProfileRuntimeOptions {
    /** Bearer token from Configure Link or auth flow for a linked profile. */
    token?: string;
    /** Developer app-local user ID for an unlinked profile. */
    externalId?: string;
}
interface ProfileReadOptions {
    sections?: ProfileSection[];
}
interface ProfileReadResult {
    profile: UserProfile;
    portable: boolean;
    filtered: boolean;
    hiddenSources?: string[];
}
interface ProfileSearchOptions {
    /** Optional search query. Omit or pass "*" to list bounded permitted attributed results. */
    query?: string;
    source?: string;
    from?: string;
    to?: string;
    limit?: number;
    /** Default "compact" omits raw CFS paths/provenance. "full" includes safe inspectable metadata. */
    detail?: 'compact' | 'full';
}
interface ProfileSearchHit {
    id: string;
    title?: string;
    text: string;
    snippet?: string;
    path?: string;
    source: string;
    written_by?: string;
    created_at?: string;
    updated_at?: string;
    event_at?: string;
    score?: number;
    type?: string;
    markers?: string[];
    provenance?: Record<string, unknown>;
}
interface ProfileSearchResult {
    results: ProfileSearchHit[];
    filtered: boolean;
    hiddenSources?: string[];
}
interface ProfileCommitMessage {
    role: 'user' | 'assistant' | 'tool';
    content: string;
    toolName?: string;
}
interface ProfileCommitInput {
    messages?: ProfileCommitMessage[];
    response?: unknown;
    toolResults?: Array<{
        toolName: string;
        content: string | object;
    }>;
    memories?: string[];
    sync?: boolean;
}
type ConnectorName = 'gmail' | 'calendar' | 'drive' | 'notion';
type ActionName = 'email.send' | 'calendar.create_event';
interface ProfileToolsOptions {
    connectors?: ConnectorName[];
    actions?: ActionName[];
    advanced?: {
        commit?: boolean;
        files?: boolean;
        utilitySearch?: boolean;
    };
}
interface JsonSchemaObject {
    type: 'object';
    properties: Record<string, unknown>;
    required?: string[];
    additionalProperties?: boolean;
}
interface ConfigureToolDefinition {
    name: string;
    description: string;
    input_schema: JsonSchemaObject;
}
interface ConfigureToolCall {
    name?: string;
    arguments?: Record<string, unknown> | string;
    input?: Record<string, unknown>;
    function?: {
        name?: string;
        arguments?: Record<string, unknown> | string;
    };
}
/**
 * Conversation message format used by private commit bridge code.
 */
interface ConversationMessage {
    role: 'user' | 'assistant';
    content: string;
}
interface OtpStartResponse {
    ok: boolean;
    mocked?: boolean;
}
interface OtpVerifyResponse {
    token: string;
    userId: string;
    embedReceipt?: string;
}
interface IntegrationData {
    connected: boolean;
    ranked?: Record<string, unknown>[];
    synthesis?: {
        facts: {
            category: string;
            fact: string;
            confidence: number;
        }[];
        summary: string;
    };
    preferences?: string[];
    events?: unknown[];
    files?: unknown[];
    pages?: unknown[];
}
interface UserIdentity {
    name?: string;
    email?: string;
    phone_last4?: string;
    occupation?: string;
    location?: string;
    bio?: string;
    interests?: string[];
}
interface UserProfile {
    identity: UserIdentity;
    preferences: string[];
    summary?: string;
    integrations: Record<string, IntegrationData>;
    agents: Record<string, Record<string, unknown>>;
    /** Whether the user has linked their identity (completed auth at least once) */
    linked?: boolean;
    /** Whether any sections were filtered due to user permissions */
    filtered?: boolean;
    /** Section names hidden by user permissions (e.g., ['integrations.gmail', 'agents.travelbot']) */
    hiddenSections?: string[];
    /** Format this profile as a prompt-ready string */
    format(options?: {
        includeTools?: boolean;
        guidelines?: boolean;
    }): string;
}
interface MemoriesResponse {
    user: Record<string, unknown>;
    prefs: string[];
    apps: Record<string, unknown>;
    connectors: Record<string, unknown>;
    updatedAt: number;
}
interface RememberResponse {
    saved: boolean;
    app: string;
    fact: string;
    memory?: ProfileSearchHit;
}
interface ProfileCommitResult {
    status: 'processing' | 'completed';
    /** Facts extracted and saved to the user's memory */
    facts_written?: string[];
    /** Updated user summary after commit */
    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;
    }>;
}
type ImportMode = 'backfill';
type ImportJobStatus = 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
interface ImportProfilesRequest {
    mode: ImportMode;
    users: ImportProfileUser[];
    idempotencyKey?: string;
}
interface ImportProfileUser {
    externalId: string;
    idempotencyKey?: string;
    profile?: {
        summary?: string;
        preferences?: string[];
        facts?: string[];
        identity?: Record<string, string>;
        [key: string]: unknown;
    };
    conversations?: ImportConversation[];
}
interface ImportConversation {
    id?: string;
    messages: ImportMessage[];
}
interface ImportMessage {
    role: 'system' | 'user' | 'assistant' | 'tool';
    content: string;
}
interface ImportQuotaState {
    used: number;
    limit: number | 'unlimited';
    requestedNew: number;
    remaining: number | 'unlimited';
}
interface ImportCaps {
    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;
}
interface ImportJob {
    id: string;
    mode: ImportMode;
    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: ImportQuotaState;
    };
    caps?: ImportCaps;
    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;
}
/** A single document in the document suite */
interface DocumentEntry {
    content: string;
    generated_at: string;
}
/** Response from getDocuments() */
interface DocumentsResponse {
    documents: {
        'user.md'?: DocumentEntry | null;
        'soul.md'?: DocumentEntry | null;
        'preferences.md'?: DocumentEntry | null;
        'context.md'?: DocumentEntry | null;
    };
}
/** Response from generateDocuments() */
interface GenerateDocumentsResponse {
    documents: {
        'user.md'?: (DocumentEntry & {
            chars: number;
        }) | null;
        'soul.md'?: (DocumentEntry & {
            chars: number;
        }) | null;
        'preferences.md'?: (DocumentEntry & {
            chars: number;
        }) | null;
        'context.md'?: (DocumentEntry & {
            chars: number;
        }) | null;
    };
    cached: boolean;
}
interface CreateEventResponse {
    created: boolean;
    event: {
        title: string;
        start: string;
        end: string;
        description?: string;
        location?: string;
    };
    message: string;
}
interface SendEmailResponse {
    sent: boolean;
    email: {
        to: string;
        subject: string;
        bodyPreview: string;
    };
    message: string;
}
interface SearchOptions {
    maxResults?: number;
}
interface UIResult {
    component: string;
    data: unknown;
}
type ConnectorType = 'gmail' | 'calendar' | 'drive' | 'notion';
interface Connector {
    id: ConnectorType;
    name: string;
    connected: boolean;
    description?: string;
}
interface ListConnectorsResponse {
    connectors: Connector[];
}
interface ConnectConnectorResponse {
    success: boolean;
    url?: string;
    connectionRequestId: string;
    alreadyConnected?: boolean;
}
interface ConfirmConnectorResponse {
    success: boolean;
    connected: boolean;
    sync?: {
        itemsSynced?: number;
        [key: string]: unknown;
    };
}
interface SyncConnectorResponse {
    synced: boolean;
    connector: ConnectorType;
    threads_count?: number;
    events_count?: number;
    files_count?: number;
    pages_count?: number;
}
interface SearchEmailsResponse {
    query: string;
    count: number;
    emails: Array<{
        subject: string;
        snippet: string;
        date?: string;
        from?: string;
    }>;
}
interface SearchCalendarResponse {
    range: string;
    count: number;
    events: Array<{
        summary: string;
        start?: string;
        end?: string;
        location?: string;
        description?: string;
    }>;
}
interface SearchFilesResponse {
    query: string;
    count: number;
    files: Array<{
        name: string;
        mimeType?: string;
        modifiedTime?: string;
        webViewLink?: string;
    }>;
}
interface SearchNotesResponse {
    query: string;
    count: number;
    notes: Array<{
        title: string;
        url?: string;
        lastEdited?: string;
    }>;
}
interface SearchWebResponse {
    query: string;
    count: number;
    results: Array<{
        title: string;
        url?: string;
        snippet: string;
        publishedDate?: string;
    }>;
}
interface FetchUrlResponse {
    url: string;
    title: string;
    content: string;
    content_type: string;
    status_code: number;
    truncated: boolean;
}
type UIComponentType = 'phone_input' | 'otp_input' | 'memory_card' | 'connection_list' | 'single_connector' | 'confirmation' | 'memory_import' | 'status_indicator' | 'searching_indicator' | 'memory_badge' | 'tool_confirmation';
interface UIComponent {
    type: UIComponentType;
    props: Record<string, unknown>;
}
interface SyncConnectorsResponse {
    userId: string;
    synced: Record<string, unknown>;
}
/**
 * Payment method metadata stored in profile files at /payments/{id}.json.
 * No actual secret values — just labels, hints, and env var references.
 */
interface PaymentMeta {
    /** Payment type */
    type: 'card' | 'bank_account' | 'digital_wallet' | 'crypto_wallet';
    /** Human-readable label (e.g., "Personal Visa ****4242") */
    label: string;
    /** Whether this is the default payment method */
    isDefault?: boolean;
    /** Card-specific metadata */
    brand?: string;
    last4?: string;
    expMonth?: number;
    expYear?: number;
    /** Crypto wallet metadata */
    chain?: string;
    address?: string;
    /** Payment processor (e.g., "stripe") */
    processor?: string;
    /** Env var name holding the actual token/secret */
    envVar?: string;
    /** When this payment method was added */
    addedAt?: number;
}
/**
 * Credential metadata stored in profile files at /credentials/{id}.json.
 * No actual secret values — just labels, hints, and env var references.
 */
interface CredentialMeta {
    /** Credential type */
    type: 'login' | 'api_key' | 'token' | 'certificate' | 'ssh_key' | 'other';
    /** Human-readable label (e.g., "OpenAI Production") */
    label: string;
    /** Service domain (e.g., "openai.com") */
    service: string;
    /** Optional category (e.g., "ai", "development", "finance") */
    category?: string;
    /** Non-secret username (if applicable) */
    username?: string;
    /** Hint showing last few chars (e.g., "sk-...4f2x") */
    hint?: string;
    /** Env var name holding the actual credential */
    envVar?: string;
    /** When this credential was added */
    addedAt?: number;
}
/**
 * Assembled agent profile for internal agent file operations.
 */
interface AgentProfile {
    /** Agent's soul/identity document (markdown) */
    soul?: string;
    /** Agent configuration */
    config?: Record<string, unknown>;
    /** List of skill files */
    skills?: {
        path: string;
        name: string;
    }[];
    /** Number of memory entries */
    memoryCount?: number;
    /** List of note files */
    notes?: {
        path: string;
        name: string;
    }[];
}
/**
 * A single agent memory entry for internal agent file operations.
 */
interface AgentMemoryEntry {
    /** Date of the memory (YYYY-MM-DD) */
    date: string;
    /** Memory content (markdown) */
    content: string;
    /** Profile file path to the memory file */
    path: string;
}

export type { ActionName, AgentMemoryEntry, AgentProfile, ConfigureOptions, ConfigureToolCall, ConfigureToolDefinition, ConfirmConnectorResponse, ConnectConnectorResponse, Connector, ConnectorName, ConnectorType, ConversationMessage, CreateEventResponse, CredentialMeta, DocumentEntry, DocumentsResponse, FetchUrlResponse, GenerateDocumentsResponse, ImportCaps, ImportConversation, ImportJob, ImportJobStatus, ImportMessage, ImportMode, ImportProfileUser, ImportProfilesRequest, ImportQuotaState, IntegrationData, JsonSchemaObject, ListConnectorsResponse, MemoriesResponse, OtpStartResponse, OtpVerifyResponse, PaymentMeta, ProfileCommitInput, ProfileCommitMessage, ProfileCommitResult, ProfileReadOptions, ProfileReadResult, ProfileRuntimeOptions, ProfileSearchHit, ProfileSearchOptions, ProfileSearchResult, ProfileSection, ProfileToolsOptions, RememberResponse, SearchCalendarResponse, SearchEmailsResponse, SearchFilesResponse, SearchNotesResponse, SearchOptions, SearchWebResponse, SendEmailResponse, SyncConnectorResponse, SyncConnectorsResponse, UIComponent, UIComponentType, UIResult, UserIdentity, UserProfile };