@datagrout/conduit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1242 @@
+/**
+ * Identity and mTLS support for Conduit connections.
+ *
+ * A {@link ConduitIdentity} holds the client certificate and private key used
+ * for mutual TLS.  When present, every connection presents the certificate
+ * during the TLS handshake — the server can verify the caller's identity
+ * without a separate application-layer token exchange.
+ *
+ * ## Auto-discovery
+ *
+ * {@link ConduitIdentity.tryDefault} walks this chain and returns the first
+ * identity it finds:
+ *
+ * 1. `CONDUIT_MTLS_CERT` + `CONDUIT_MTLS_KEY` (+ optional `CONDUIT_MTLS_CA`)
+ *    environment variables (inline PEM strings).
+ * 2. `CONDUIT_IDENTITY_DIR` environment variable — a directory containing
+ *    `identity.pem` and `identity_key.pem`.  Useful for running multiple
+ *    agents on the same machine with distinct identities.
+ * 3. `~/.conduit/identity.pem` + `~/.conduit/identity_key.pem`
+ * 4. `.conduit/identity.pem` relative to the current working directory.
+ *
+ * If nothing is found, `tryDefault` returns `null` — the client falls back to
+ * bearer token / API key auth silently.
+ *
+ * ## Rotation awareness
+ *
+ * Attach a known expiry with `withExpiry(date)` and call
+ * `needsRotation(thresholdDays)` to check whether the cert is within
+ * `thresholdDays` of expiry.  Actual re-registration with the DataGrout CA is
+ * handled separately.
+ *
+ * ## Runtime note
+ *
+ * mTLS in HTTP is a Node.js capability — browser `fetch` implementations do
+ * not support client certificates.  In browser environments the identity is
+ * stored but not applied; a warning is emitted instead.
+ */
+/** Raw mTLS material. */
+interface MtlsConfig {
+    /** PEM-encoded X.509 client certificate. */
+    certPem: string;
+    /** PEM-encoded private key (PKCS#8 or PKCS#1). */
+    keyPem: string;
+    /**
+     * PEM-encoded CA certificate(s) for verifying the *server* cert.
+     * When absent the system trust store is used.
+     */
+    caPem?: string;
+    /** Certificate expiry, if known.  Set via {@link ConduitIdentity.withExpiry}. */
+    expiresAt?: Date;
+}
+/**
+ * A Conduit client identity — the cert + key pair used for mTLS.
+ *
+ * Construct via {@link fromPem}, {@link fromPaths}, {@link fromEnv}, or
+ * {@link tryDefault}.
+ */
+declare class ConduitIdentity {
+    private readonly _config;
+    private constructor();
+    /**
+     * Build an identity from PEM strings already in memory.
+     *
+     * @throws {Error} if the PEM strings do not look like a certificate or key.
+     */
+    static fromPem(certPem: string, keyPem: string, caPem?: string): ConduitIdentity;
+    /**
+     * Build an identity by reading PEM files from disk (Node.js only).
+     *
+     * @throws {Error} in browser environments or if the files cannot be read.
+     */
+    static fromPaths(certPath: string, keyPath: string, caPath?: string): ConduitIdentity;
+    /**
+     * Build an identity from environment variables.
+     *
+     * Reads:
+     * - `CONDUIT_MTLS_CERT` — PEM string for the client certificate
+     * - `CONDUIT_MTLS_KEY`  — PEM string for the private key
+     * - `CONDUIT_MTLS_CA`   — PEM string for the CA (optional)
+     *
+     * @returns `null` if `CONDUIT_MTLS_CERT` is not set.
+     * @throws {Error} if `CONDUIT_MTLS_CERT` is set but `CONDUIT_MTLS_KEY` is missing.
+     */
+    static fromEnv(): ConduitIdentity | null;
+    /**
+     * Try to locate an identity using the auto-discovery chain described in the
+     * module docs.  Returns `null` if nothing is found.
+     */
+    static tryDefault(): ConduitIdentity | null;
+    /**
+     * Like {@link tryDefault} but checks `overrideDir` first.
+     *
+     * Discovery order:
+     * 1. `overrideDir` (if provided)
+     * 2. `CONDUIT_MTLS_CERT` + `CONDUIT_MTLS_KEY` env vars
+     * 3. `CONDUIT_IDENTITY_DIR` env var
+     * 4. `~/.conduit/`
+     * 5. `.conduit/` relative to cwd
+     */
+    static tryDiscover(overrideDir?: string): ConduitIdentity | null;
+    /** Attach a known certificate expiry for rotation checks. */
+    withExpiry(expiresAt: Date): ConduitIdentity;
+    /**
+     * Returns `true` if the certificate expires within `thresholdDays`.
+     *
+     * Always returns `false` when no expiry is set.
+     */
+    needsRotation(thresholdDays: number): boolean;
+    get certPem(): string;
+    get keyPem(): string;
+    get caPem(): string | undefined;
+    get expiresAt(): Date | undefined;
+    private static _hasPemPrivateKey;
+    private static _tryLoadFromDir;
+}
+/**
+ * Perform an HTTP/HTTPS request using Node.js built-in `https` with a client
+ * certificate for mTLS.  Returns a `Response`-compatible object usable
+ * everywhere the standard `fetch` response is expected.
+ *
+ * This bypasses the global `fetch` (which doesn't support client certs) and
+ * uses Node.js's `https.request` directly.
+ */
+declare function fetchWithIdentity(url: string, init: RequestInit, identity: ConduitIdentity): Promise<Response>;
+
+/**
+ * Type definitions for DataGrout Conduit
+ */
+/**
+ * Rate limit cap returned in `X-RateLimit-Limit` response headers.
+ *
+ * - `"unlimited"` — authenticated DataGrout users; the gateway never blocks them.
+ * - `{ perHour: number }` — unauthenticated callers hitting a per-hour cap.
+ */
+type RateLimit = 'unlimited' | {
+    perHour: number;
+};
+/**
+ * Parsed rate limit state from a gateway response.
+ *
+ * Surfaced via `RateLimitError.status` when the client receives HTTP 429.
+ */
+interface RateLimitStatus {
+    /** Calls made in the current 1-hour window. */
+    used: number;
+    /** Total allowed calls (or `"unlimited"`). */
+    limit: RateLimit;
+    /** `true` when the caller has been throttled. */
+    isLimited: boolean;
+    /** Remaining calls this window, or `null` when unlimited. */
+    remaining: number | null;
+}
+/** BYOK discount details embedded in a receipt. */
+interface Byok {
+    enabled: boolean;
+    discountApplied: number;
+    discountRate: number;
+}
+/**
+ * Cost receipt attached to every DG tool-call result under `result._meta.datagrout.receipt`.
+ *
+ * Use `extractMeta(result)` to pull this out cleanly.
+ */
+interface Receipt {
+    /** DG-internal receipt identifier (`rcp_…`). */
+    receiptId: string;
+    /** DB transaction ID (set only when a user account was charged). */
+    transactionId?: string;
+    timestamp: string;
+    estimatedCredits: number;
+    actualCredits: number;
+    netCredits: number;
+    savings: number;
+    savingsBonus: number;
+    /** Account balance before the charge. */
+    balanceBefore?: number;
+    /** Account balance after the charge. */
+    balanceAfter?: number;
+    /** Per-component credit breakdown. */
+    breakdown: Record<string, any>;
+    byok: Byok;
+}
+/** Pre-execution credit estimate under `result._meta.datagrout.credit_estimate`. */
+interface CreditEstimate {
+    estimatedTotal: number;
+    actualTotal: number;
+    netTotal: number;
+    breakdown: Record<string, any>;
+}
+/**
+ * The DataGrout billing block attached to every tool-call result in `_meta.datagrout`.
+ *
+ * @example
+ * ```ts
+ * const result = await client.callTool('salesforce@v1/get_lead@v1', { id: '123' });
+ * const meta = extractMeta(result);
+ * if (meta) console.log(`Charged ${meta.receipt.netCredits} credits`);
+ * ```
+ */
+interface ToolMeta {
+    receipt: Receipt;
+    creditEstimate?: CreditEstimate;
+}
+/**
+ * Extract the DataGrout metadata block from a tool-call result.
+ *
+ * Checks `_meta.datagrout` first (current format — MCP spec extension point),
+ * then falls back to top-level `_datagrout`, then bare `_meta`, for
+ * backward compatibility with older gateway responses.
+ *
+ * Returns `null` when no recognized key is found (e.g. upstream servers not
+ * routed through the DG gateway).
+ */
+declare function extractMeta(result: Record<string, any>): ToolMeta | null;
+interface ToolInfo {
+    toolName: string;
+    integration: string;
+    serverId?: string;
+    score?: number;
+    distance?: number;
+    description?: string;
+    sideEffects?: string;
+    inputSchema?: Record<string, any>;
+    outputSchema?: Record<string, any>;
+}
+interface DiscoverResult {
+    queryUsed: string;
+    results: ToolInfo[];
+    total: number;
+    limit: number;
+}
+interface PerformResult {
+    success: boolean;
+    result: any;
+    tool: string;
+    metadata?: Record<string, any>;
+    receipt?: Receipt;
+}
+interface GuideOptions {
+    id: string;
+    label: string;
+    cost: number;
+    viable: boolean;
+    metadata?: Record<string, any>;
+}
+interface GuideState {
+    sessionId: string;
+    step: string;
+    message: string;
+    status: string;
+    options?: GuideOptions[];
+    pathTaken?: string[];
+    totalCost?: number;
+    result?: any;
+    progress?: string;
+}
+interface AuthConfig {
+    bearer?: string;
+    basic?: {
+        username: string;
+        password: string;
+    };
+    /**
+     * OAuth 2.1 `client_credentials` grant.
+     *
+     * When set, the SDK automatically fetches and caches a short-lived JWT from
+     * the DataGrout token endpoint.  No token management needed in application code.
+     *
+     * The `tokenEndpoint` is derived from the client URL automatically if omitted.
+     */
+    clientCredentials?: {
+        clientId: string;
+        clientSecret: string;
+        /** Optional explicit token endpoint URL. Derived from the client URL if omitted. */
+        tokenEndpoint?: string;
+        /** Optional space-separated scope string (e.g. `"mcp tools"`). */
+        scope?: string;
+    };
+    custom?: Record<string, string>;
+}
+interface ClientOptions {
+    url: string;
+    auth?: AuthConfig;
+    /**
+     * mTLS client identity.  When set, every connection presents this
+     * certificate during the TLS handshake (Node.js only).
+     *
+     * Can be set explicitly or discovered automatically via
+     * `ConduitIdentity.tryDefault()`.
+     */
+    identity?: ConduitIdentity;
+    /**
+     * When `true`, auto-discover an mTLS identity from env vars or
+     * `~/.conduit/` before falling back to token auth.  Equivalent to
+     * calling `ConduitIdentity.tryDefault()` and passing the result as
+     * `identity`.
+     */
+    identityAuto?: boolean;
+    /**
+     * Custom directory for identity storage and discovery.  Overrides the
+     * default `~/.conduit/` directory.  Useful for running multiple agents
+     * on the same machine — each gets its own identity directory.
+     */
+    identityDir?: string;
+    /**
+     * Enable the intelligent interface (DataGrout `discover` / `perform` only).
+     *
+     * When `true`, `listTools()` returns only the DataGrout semantic discovery
+     * and execution tools instead of the raw tool list from the MCP server.
+     * Defaults to `true` for DataGrout URLs, `false` otherwise.
+     * Pass explicitly to override.
+     */
+    useIntelligentInterface?: boolean;
+    /**
+     * Disable automatic mTLS even for DataGrout URLs.
+     *
+     * By default, DG URLs (`*.datagrout.ai`) silently attempt to discover an
+     * mTLS identity from env vars or `~/.conduit/`.  Set to `true` to opt out
+     * and use token-only auth.
+     *
+     * @default false
+     */
+    disableMtls?: boolean;
+    transport?: 'mcp' | 'jsonrpc';
+    timeout?: number;
+    /**
+     * Maximum number of automatic retries on "server not initialized" errors.
+     * The client re-initializes the connection between attempts with a 500ms
+     * backoff.
+     *
+     * @default 3
+     */
+    maxRetries?: number;
+}
+interface DiscoverOptions {
+    query?: string;
+    goal?: string;
+    limit?: number;
+    minScore?: number;
+    integrations?: string[];
+    servers?: string[];
+}
+interface PerformOptions {
+    tool: string;
+    args: Record<string, any>;
+    demux?: boolean;
+    demuxMode?: 'strict' | 'fuzzy';
+}
+interface GuideRequestOptions {
+    goal?: string;
+    policy?: Record<string, any>;
+    sessionId?: string;
+    choice?: string;
+}
+interface FlowOptions {
+    plan: Array<Record<string, any>>;
+    validateCtc?: boolean;
+    saveAsSkill?: boolean;
+    inputData?: Record<string, any>;
+}
+interface PrismFocusOptions {
+    data: any;
+    sourceType: string;
+    targetType: string;
+    sourceAnnotations?: Record<string, any>;
+    targetAnnotations?: Record<string, any>;
+    context?: string;
+}
+interface PlanOptions {
+    goal?: string;
+    query?: string;
+    server?: string;
+    k?: number;
+    policy?: any;
+    have?: any;
+    returnCallHandles?: boolean;
+    exposeVirtualSkills?: boolean;
+    modelOverrides?: any;
+}
+interface RefractOptions {
+    goal: string;
+    payload: any;
+    verbose?: boolean;
+    chart?: boolean;
+}
+interface ChartOptions {
+    goal: string;
+    payload: any;
+    format?: string;
+    chartType?: string;
+    title?: string;
+    xLabel?: string;
+    yLabel?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Options for `Client.remember()`.
+ * Supply either `statement` (natural language) or `facts` (pre-structured),
+ * but not neither.
+ */
+interface RememberOptions {
+    /** Natural language statement to convert to symbolic facts. */
+    statement?: string;
+    /** Pre-structured fact list (skips NL conversion). */
+    facts?: Record<string, any>[];
+    /** Tag/namespace for grouping facts (default: `"default"`). */
+    tag?: string;
+}
+/**
+ * Options for `Client.queryCell()`.
+ * Supply either `question` (natural language) or `patterns` (pre-built),
+ * but not neither.
+ */
+interface QueryCellOptions {
+    /** Natural language question to translate into query patterns. */
+    question?: string;
+    /** Pre-built pattern list (skips NL translation). */
+    patterns?: Record<string, any>[];
+    /** Maximum number of results to return (default: 50). */
+    limit?: number;
+}
+/** Options for `Client.forget()`. Supply `handles`, `pattern`, or both. */
+interface ForgetOptions {
+    /** Specific fact handles to retract. */
+    handles?: string[];
+    /** Natural language pattern — retract all matching facts. */
+    pattern?: string;
+}
+/** Options for `Client.constrain()`. */
+interface ConstrainOptions {
+    /** Tag/namespace for this constraint (default: `"constraint"`). */
+    tag?: string;
+}
+/** Options for `Client.reflect()`. */
+interface ReflectOptions {
+    /** Optional entity name to scope the reflection. */
+    entity?: string;
+    /** When `true`, return only summary counts instead of full facts. */
+    summaryOnly?: boolean;
+}
+interface MCPTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, any>;
+    annotations?: Record<string, any>;
+}
+interface MCPResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}
+interface MCPPrompt {
+    name: string;
+    description?: string;
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+}
+
+/**
+ * Stateful guided workflow session returned by `Client.guide()`.
+ *
+ * Call `session.choose(optionId)` to advance through workflow steps,
+ * and `session.complete()` to retrieve the final result once `status === "completed"`.
+ */
+declare class GuidedSession {
+    private client;
+    private state;
+    constructor(client: Client, state: GuideState);
+    /** Unique session identifier used to resume the workflow. */
+    get sessionId(): string;
+    /** Current workflow status (e.g. `"ready"`, `"completed"`). */
+    get status(): string;
+    /** Available options for the current step. */
+    get options(): GuideOptions[];
+    /** Final result, populated once `status === "completed"`. */
+    get result(): any;
+    /** Returns the raw `GuideState` snapshot for this step. */
+    getState(): GuideState;
+    /**
+     * Advance the guided session by selecting an option.
+     *
+     * @param optionId - The `id` of the option to choose (from `session.options`).
+     * @returns A new `GuidedSession` reflecting the next workflow step.
+     */
+    choose(optionId: string): Promise<GuidedSession>;
+    /**
+     * Retrieve the completed workflow result.
+     *
+     * Throws if the session has not yet reached `status === "completed"`.
+     * Use `choose()` to advance through remaining steps first.
+     */
+    complete(): Promise<any>;
+}
+/** Returns `true` when `url` points at a DataGrout-managed endpoint. */
+declare function isDgUrl(url: string): boolean;
+/**
+ * DataGrout Conduit client — a drop-in replacement for MCP clients with
+ * first-class support for DataGrout semantic extensions.
+ *
+ * @example
+ * ```ts
+ * const client = new Client('https://gateway.datagrout.ai/servers/<uuid>/mcp');
+ * await client.connect();
+ * const tools = await client.listTools();
+ * await client.disconnect();
+ * ```
+ */
+declare class Client {
+    private url;
+    private auth?;
+    private useIntelligentInterface;
+    private transport;
+    private readonly isDg;
+    private dgWarned;
+    private initialized;
+    private maxRetries;
+    constructor(options: ClientOptions | string);
+    /**
+     * Create a `Client` with an mTLS identity bootstrapped automatically.
+     *
+     * Checks the auto-discovery chain first. If an existing identity is found
+     * and not within 7 days of expiry, it is reused. Otherwise a new keypair
+     * is generated, registered with DataGrout, and saved locally.
+     *
+     * After the first successful bootstrap the token is no longer needed —
+     * mTLS handles authentication on every subsequent run.
+     *
+     * @param options.url              - DataGrout server URL.
+     * @param options.authToken        - Bearer token for the initial registration call.
+     * @param options.name             - Human-readable identity name (default: `"conduit-client"`).
+     * @param options.identityDir      - Custom identity storage directory.
+     * @param options.substrateEndpoint - Override the DG Substrate endpoint.
+     */
+    static bootstrapIdentity(options: {
+        url: string;
+        authToken: string;
+        name?: string;
+        identityDir?: string;
+        substrateEndpoint?: string;
+    }): Promise<Client>;
+    /**
+     * Like `bootstrapIdentity` but uses OAuth 2.1 `client_credentials` to obtain
+     * the bearer token automatically — no pre-obtained token needed.
+     *
+     * @param options.url              - DataGrout server URL.
+     * @param options.clientId         - OAuth client ID.
+     * @param options.clientSecret     - OAuth client secret.
+     * @param options.name             - Human-readable identity name (default: `"conduit-client"`).
+     * @param options.identityDir      - Custom identity storage directory.
+     * @param options.substrateEndpoint - Override the DG Substrate endpoint.
+     */
+    static bootstrapIdentityOAuth(options: {
+        url: string;
+        clientId: string;
+        clientSecret: string;
+        name?: string;
+        identityDir?: string;
+        substrateEndpoint?: string;
+    }): Promise<Client>;
+    /**
+     * Establish the underlying transport connection.
+     *
+     * Must be called before any other method. For the MCP transport this
+     * performs the JSON-RPC `initialize` handshake; for JSONRPC it is a no-op
+     * (connections are per-request).
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the underlying transport connection and mark the client as
+     * uninitialized. After calling this, `connect()` must be called again
+     * before issuing further requests.
+     */
+    disconnect(): Promise<void>;
+    private ensureInitialized;
+    /**
+     * Wrap a transport call with automatic retry on "not initialized" errors
+     * (JSON-RPC code -32002). Re-initializes the connection and retries up to
+     * `maxRetries` times with 500ms backoff between attempts.
+     */
+    private sendWithRetry;
+    /**
+     * List all tools exposed by the connected MCP server.
+     *
+     * Calls the MCP `tools/list` method with automatic cursor-based pagination.
+     * When `useIntelligentInterface` is enabled (default for DataGrout URLs),
+     * integration tools (names containing `@`) are filtered out, leaving only
+     * the DataGrout semantic discovery interface.
+     *
+     * JSON-RPC method: `tools/list`
+     */
+    listTools(options?: any): Promise<MCPTool[]>;
+    /**
+     * Invoke a named tool on the connected MCP server.
+     *
+     * JSON-RPC method: `tools/call`
+     *
+     * @param name - Fully-qualified tool name (e.g. `salesforce@v1/get_lead@v1`).
+     * @param args - Tool input arguments.
+     */
+    callTool(name: string, args: Record<string, any>, _options?: any): Promise<any>;
+    /**
+     * List resources exposed by the connected MCP server.
+     *
+     * JSON-RPC method: `resources/list`
+     */
+    listResources(options?: any): Promise<MCPResource[]>;
+    /**
+     * Read the content of a named resource.
+     *
+     * JSON-RPC method: `resources/read`
+     *
+     * @param uri - Resource URI as returned by `listResources()`.
+     */
+    readResource(uri: string, options?: any): Promise<any>;
+    /**
+     * List prompt templates exposed by the connected MCP server.
+     *
+     * JSON-RPC method: `prompts/list`
+     */
+    listPrompts(options?: any): Promise<MCPPrompt[]>;
+    /**
+     * Retrieve a prompt template, optionally instantiated with arguments.
+     *
+     * JSON-RPC method: `prompts/get`
+     *
+     * @param name - Prompt name as returned by `listPrompts()`.
+     * @param args - Template argument values.
+     */
+    getPrompt(name: string, args?: Record<string, any>, options?: any): Promise<any>;
+    private warnIfNotDg;
+    /**
+     * Semantically discover tools relevant to a goal or query.
+     *
+     * Uses DataGrout's vector-search index to find the best-matching tools
+     * across all registered integrations. Returns ranked results with scores,
+     * descriptions, and schemas.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/discovery.discover`
+     *
+     * @param options.query        - Natural language search query.
+     * @param options.goal         - High-level goal description (alternative to `query`).
+     * @param options.limit        - Maximum results to return (default: 10).
+     * @param options.minScore     - Minimum relevance score (default: 0.0).
+     * @param options.integrations - Filter by specific integration names.
+     * @param options.servers      - Filter by specific server IDs.
+     */
+    discover(options: DiscoverOptions): Promise<DiscoverResult>;
+    /**
+     * Execute a single tool call routed through DataGrout's gateway.
+     *
+     * The gateway handles credential injection, usage tracking, and receipts.
+     * Use `performBatch()` to execute multiple calls in one request.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/discovery.perform`
+     *
+     * @param options.tool     - Fully-qualified tool name.
+     * @param options.args     - Tool input arguments.
+     * @param options.demux    - When `true`, use semantic demultiplexing.
+     * @param options.demuxMode - Demux strictness (`"strict"` | `"fuzzy"`).
+     */
+    perform(options: PerformOptions): Promise<any>;
+    /**
+     * Execute multiple tool calls in a single gateway request.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/discovery.perform`
+     *
+     * @param calls - Array of `{ tool, args }` call descriptors.
+     */
+    performBatch(calls: Array<{
+        tool: string;
+        args: Record<string, any>;
+    }>): Promise<any[]>;
+    /**
+     * Start or advance a guided workflow session.
+     *
+     * The first call (with only `goal`) starts a new session and returns the
+     * initial options. Subsequent calls provide `sessionId` and `choice` to
+     * advance through steps. Returns a `GuidedSession` that exposes helpers
+     * for navigating the workflow.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/discovery.guide`
+     *
+     * @param options.goal      - High-level goal to accomplish (first call only).
+     * @param options.policy    - Optional policy constraints for tool selection.
+     * @param options.sessionId - Resume an existing session (subsequent calls).
+     * @param options.choice    - Option ID selected at the current step.
+     */
+    guide(options: GuideRequestOptions): Promise<GuidedSession>;
+    /**
+     * Execute a pre-planned sequence of tool calls (a "flow") through the
+     * DataGrout gateway.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/flow.into`
+     *
+     * @param options.plan          - Ordered list of tool call descriptors.
+     * @param options.validateCtc   - Validate each call against its CTC schema (default: `true`).
+     * @param options.saveAsSkill   - Persist the flow as a reusable skill (default: `false`).
+     * @param options.inputData     - Runtime input data for the flow.
+     */
+    flowInto(options: FlowOptions): Promise<any>;
+    /**
+     * Transform data from one annotated type to another using the DataGrout
+     * Prism semantic mapping engine.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/prism.focus`
+     *
+     * @param options.data               - Source payload to transform.
+     * @param options.sourceType         - Semantic type of the source data.
+     * @param options.targetType         - Desired semantic type for the output.
+     * @param options.sourceAnnotations  - Additional schema hints for the source.
+     * @param options.targetAnnotations  - Additional schema hints for the target.
+     * @param options.context            - Free-text context to guide the mapping.
+     */
+    prismFocus(options: PrismFocusOptions): Promise<any>;
+    /**
+     * Generate an execution plan for a goal using DataGrout's planning engine.
+     *
+     * Returns an ordered list of tool calls that, when executed, accomplish the
+     * stated goal. Throws `InvalidConfigError` if neither `goal` nor `query` is
+     * provided.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/discovery.plan`
+     *
+     * @param options.goal                - High-level goal description.
+     * @param options.query               - Search query to anchor the plan (alternative to `goal`).
+     * @param options.server              - Restrict planning to a specific server.
+     * @param options.k                   - Maximum number of plan steps.
+     * @param options.policy              - Policy constraints for tool selection.
+     * @param options.have                - Pre-existing data/context available to the planner.
+     * @param options.returnCallHandles   - Include call handles in the response.
+     * @param options.exposeVirtualSkills - Include virtual skills in the plan.
+     * @param options.modelOverrides      - Override LLM model settings.
+     */
+    plan(options: PlanOptions): Promise<any>;
+    /**
+     * Analyse and summarise a payload using the DataGrout Prism refraction engine.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/prism.refract`
+     *
+     * @param options.goal    - Description of what to extract or summarise.
+     * @param options.payload - Input data to analyse (any JSON-serializable value).
+     * @param options.verbose - Include detailed processing trace in the response.
+     * @param options.chart   - Also generate a chart representation.
+     */
+    refract(options: RefractOptions): Promise<any>;
+    /**
+     * Generate a chart from a data payload using the DataGrout Prism engine.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/prism.chart`
+     *
+     * @param options.goal      - What the chart should visualise.
+     * @param options.payload   - Input data (any JSON-serializable value).
+     * @param options.format    - Output format (e.g. `"png"`, `"svg"`).
+     * @param options.chartType - Chart type (e.g. `"bar"`, `"line"`, `"pie"`).
+     * @param options.title     - Chart title.
+     * @param options.xLabel    - X-axis label.
+     * @param options.yLabel    - Y-axis label.
+     * @param options.width     - Chart width in pixels.
+     * @param options.height    - Chart height in pixels.
+     */
+    chart(options: ChartOptions): Promise<any>;
+    /**
+     * Generate a document toward a natural-language goal.
+     * Supported formats: markdown, html, pdf, json.
+     */
+    render(options: {
+        goal: string;
+        payload?: any;
+        format?: string;
+        sections?: any[];
+        [k: string]: any;
+    }): Promise<any>;
+    /**
+     * Convert content to another format (no LLM). Supports csv, xlsx, pdf, json, html, markdown, etc.
+     */
+    export(options: {
+        content: any;
+        format: string;
+        style?: Record<string, any>;
+        metadata?: Record<string, any>;
+        [k: string]: any;
+    }): Promise<any>;
+    /**
+     * Pause workflow for human approval. Use for destructive or policy-gated actions.
+     */
+    requestApproval(options: {
+        action: string;
+        details?: Record<string, any>;
+        reason?: string;
+        context?: Record<string, any>;
+        [k: string]: any;
+    }): Promise<any>;
+    /**
+     * Request user clarification for missing fields. Pauses until user provides values.
+     */
+    requestFeedback(options: {
+        missing_fields: string[];
+        reason: string;
+        current_data?: Record<string, any>;
+        suggestions?: Record<string, any>;
+        context?: Record<string, any>;
+        [k: string]: any;
+    }): Promise<any>;
+    /**
+     * List recent tool executions for the current server.
+     */
+    executionHistory(options?: {
+        limit?: number;
+        offset?: number;
+        status?: string;
+        refractions_only?: boolean;
+        [k: string]: any;
+    }): Promise<any>;
+    /**
+     * Get details and transcript for a specific execution.
+     */
+    executionDetails(executionId: string): Promise<any>;
+    /**
+     * Call any DataGrout first-party tool by its short name.
+     *
+     * Prepends `data-grout/` to the tool name automatically, so
+     * `client.dg('prism.render', { ... })` calls `data-grout/prism.render`.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/<toolShortName>`
+     *
+     * @param toolShortName - Tool name without the `data-grout/` prefix.
+     * @param params        - Tool input arguments.
+     */
+    dg(toolShortName: string, params?: Record<string, any>): Promise<any>;
+    /**
+     * Store facts in the agent's persistent logic cell.
+     *
+     * Converts natural language to symbolic facts and stores them
+     * durably across sessions. Accepts either a natural language `statement`
+     * (positional or via options) or a pre-structured `facts` array.
+     *
+     * Throws `InvalidConfigError` if neither `statement` nor `facts` is provided.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.remember`
+     *
+     * @param statement - Natural language statement to remember.
+     * @param options.tag   - Tag/namespace for grouping facts (default: `"default"`).
+     * @param options.facts - Optional pre-structured fact list (skips NL conversion).
+     */
+    remember(statement: string, options?: RememberOptions): Promise<{
+        handles: string[];
+        facts: any[];
+        count: number;
+        message: string;
+    }>;
+    /**
+     * Store facts in the agent's persistent logic cell using an options object.
+     *
+     * Throws `InvalidConfigError` if neither `statement` nor `facts` is provided.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.remember`
+     */
+    remember(options: RememberOptions): Promise<{
+        handles: string[];
+        facts: any[];
+        count: number;
+        message: string;
+    }>;
+    /**
+     * Query the agent's logic cell with a natural language question.
+     *
+     * Translates the question to query patterns and retrieves matching facts.
+     * Accepts either a natural language `question` (positional or via options)
+     * or a pre-built `patterns` array.
+     *
+     * Throws `InvalidConfigError` if neither `question` nor `patterns` is provided.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.query`
+     *
+     * @param question       - Natural language question.
+     * @param options.limit  - Maximum results to return (default: 50).
+     * @param options.patterns - Optional pre-built pattern list (skips NL translation).
+     */
+    queryCell(question: string, options?: QueryCellOptions): Promise<{
+        results: any[];
+        total: number;
+        description: string;
+        message: string;
+    }>;
+    /**
+     * Query the agent's logic cell using an options object.
+     *
+     * Throws `InvalidConfigError` if neither `question` nor `patterns` is provided.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.query`
+     */
+    queryCell(options: QueryCellOptions): Promise<{
+        results: any[];
+        total: number;
+        description: string;
+        message: string;
+    }>;
+    /**
+     * Retract facts from the agent's logic cell.
+     *
+     * Throws `InvalidConfigError` if neither `handles` nor `pattern` is provided.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.forget`
+     *
+     * @param options.handles - Specific fact handles to retract.
+     * @param options.pattern - Natural language pattern — retract all matching facts.
+     */
+    forget(options: ForgetOptions): Promise<{
+        retracted: number;
+        handles: string[];
+        message: string;
+    }>;
+    /**
+     * Reflect on the agent's logic cell — returns a full snapshot or a
+     * per-entity view of all stored facts.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.reflect`
+     *
+     * @param options.entity      - Optional entity name to scope reflection.
+     * @param options.summaryOnly - When `true`, return only counts (default: `false`).
+     */
+    reflect(options?: ReflectOptions): Promise<{
+        total: number;
+        summary?: any;
+        entity?: string;
+        facts?: any[];
+        message: string;
+    }>;
+    /**
+     * Store a logical rule or policy in the agent's logic cell.
+     *
+     * Rules are permanent constraints evaluated during `queryCell()` calls.
+     *
+     * JSON-RPC method: `tools/call` → `data-grout/logic.constrain`
+     *
+     * @param rule         - Natural language rule (e.g. `"VIP customers have ARR > $500K"`).
+     * @param options.tag  - Tag/namespace for this constraint (default: `"constraint"`).
+     */
+    constrain(rule: string, options?: ConstrainOptions): Promise<{
+        handle: string;
+        name: string;
+        rule: string;
+        message: string;
+    }>;
+    /**
+     * Estimate the credit cost of a tool call without executing it.
+     *
+     * Passes `estimate_only: true` to the tool, which returns a cost breakdown
+     * without performing any side effects or charging credits.
+     *
+     * @param tool - Fully-qualified tool name.
+     * @param args - Tool input arguments.
+     */
+    estimateCost(tool: string, args: Record<string, any>): Promise<any>;
+    private performWithTracking;
+}
+
+/**
+ * OAuth 2.1 `client_credentials` token provider for Conduit.
+ *
+ * Fetches short-lived JWTs from the DataGrout machine-client token endpoint
+ * and caches them, refreshing proactively before they expire.
+ *
+ * @example
+ * ```ts
+ * // Most users should use the high-level `auth.clientCredentials` option on
+ * // ClientOptions instead of instantiating this class directly.
+ * import { Client } from 'datagrout-conduit';
+ *
+ * const client = new Client({
+ *   url: 'https://app.datagrout.ai/servers/{uuid}/mcp',
+ *   auth: {
+ *     clientCredentials: { clientId: 'abc', clientSecret: 'xyz' },
+ *   },
+ * });
+ * ```
+ */
+/**
+ * Derive the token endpoint URL from a DataGrout MCP URL.
+ *
+ * @example
+ * ```ts
+ * deriveTokenEndpoint('https://app.datagrout.ai/servers/abc/mcp');
+ * // → 'https://app.datagrout.ai/servers/abc/oauth/token'
+ * ```
+ */
+declare function deriveTokenEndpoint(mcpUrl: string): string;
+/** @internal */
+declare class OAuthTokenProvider {
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly tokenEndpoint;
+    private readonly scope?;
+    private cached;
+    private fetchPromise;
+    constructor(opts: {
+        clientId: string;
+        clientSecret: string;
+        tokenEndpoint: string;
+        scope?: string;
+    });
+    /**
+     * Return the current bearer token, fetching a fresh one if necessary.
+     * Concurrent callers share a single in-flight fetch.
+     */
+    getToken(): Promise<string>;
+    /** Invalidate the cached token (e.g. after receiving a 401). */
+    invalidate(): void;
+    private fetchToken;
+}
+
+/**
+ * Substrate identity registration with the DataGrout CA.
+ *
+ * Flow:
+ * 1. Generate an ECDSA P-256 keypair locally — private key never leaves the client.
+ * 2. Send only the public key to DataGrout via {@link registerIdentity}.
+ *    DG signs and returns the certificate + CA cert.
+ * 3. Persist to `~/.conduit/` via {@link saveIdentity}.
+ * 4. On renewal, call {@link rotateIdentity} — authenticated by mTLS, no API key needed.
+ *
+ * CA cert refresh
+ * ---------------
+ * {@link fetchDgCaCert} fetches the current DataGrout CA certificate from
+ * `https://ca.datagrout.ai/ca.pem`. When the DG CA rotates, clients that call
+ * {@link refreshCaCert} at startup automatically pick up the change without a
+ * rebuild or re-registration.
+ */
+/** Canonical URL for the DataGrout CA certificate. */
+declare const DG_CA_URL = "https://ca.datagrout.ai/ca.pem";
+/** Substrate identity registration endpoint. */
+declare const DG_SUBSTRATE_ENDPOINT = "https://app.datagrout.ai/api/v1/substrate/identity";
+/** Default local identity directory. */
+declare const DEFAULT_IDENTITY_DIR: string;
+/**
+ * Fetch the current DataGrout CA certificate from `ca.datagrout.ai`.
+ *
+ * Uses the system trust store for HTTPS (Cloudflare TLS) — no circularity
+ * with the DG CA, which only signs client certificates.
+ *
+ * @param url Override the CA cert URL (default: {@link DG_CA_URL}).
+ * @returns PEM-encoded CA certificate string.
+ */
+declare function fetchDgCaCert(url?: string): Promise<string>;
+/**
+ * Refresh the locally-cached DG CA certificate.
+ *
+ * Fetches the current CA cert from `ca.datagrout.ai` and writes it to
+ * `{identityDir}/ca.pem`. Call at application startup to pick up CA rotations
+ * without requiring a new registration or SDK rebuild.
+ *
+ * @param identityDir Directory to write `ca.pem` into (default: `~/.conduit/`).
+ * @param url Override the CA cert URL.
+ * @returns Path to the written `ca.pem` file.
+ */
+declare function refreshCaCert(identityDir?: string, url?: string): Promise<string>;
+/**
+ * An ECDSA P-256 keypair generated locally.
+ *
+ * Pass to {@link registerIdentity} to exchange for a DG-signed certificate.
+ * The private key never leaves the client process.
+ */
+interface Keypair {
+    /** PEM-encoded PKCS#8 private key (never transmitted). */
+    privateKeyPem: string;
+    /** PEM-encoded SPKI public key (sent to DG during registration). */
+    publicKeyPem: string;
+}
+interface RegistrationOptions {
+    /** DataGrout substrate identity API base URL. */
+    endpoint: string;
+    /** Any valid DG access token for bootstrap Bearer auth. */
+    authToken: string;
+    /** Human-readable label for this Substrate instance. */
+    name: string;
+    /** CA cert URL override (default: {@link DG_CA_URL}). */
+    caUrl?: string;
+}
+interface RenewalOptions {
+    /** DataGrout substrate identity API base URL. */
+    endpoint: string;
+    /** Human-readable label for the renewed identity. */
+    name: string;
+    /** CA cert URL override. */
+    caUrl?: string;
+}
+interface RegisteredIdentity {
+    /** PEM-encoded DG-signed certificate. */
+    certPem: string;
+    /** PEM-encoded private key (never sent to DG). */
+    keyPem: string;
+    /** PEM-encoded DG CA certificate. */
+    caPem?: string;
+    /** Server-assigned identity ID. */
+    id: string;
+    /** Human-readable label assigned during registration. */
+    name: string;
+    /** SHA-256 fingerprint of the certificate. */
+    fingerprint: string;
+    /** ISO-8601 timestamp when the identity was registered. */
+    registeredAt: string;
+    /** ISO-8601 expiry date. */
+    validUntil?: string;
+}
+/**
+ * Generate an ECDSA P-256 keypair for Substrate identity registration.
+ *
+ * Returns a {@link Keypair} holding the private key (local only) and the
+ * public key to send to DataGrout.  Pass the result to {@link registerIdentity}
+ * to receive a DG-CA-signed certificate.
+ *
+ * Node.js only (`crypto.generateKeyPairSync`).
+ */
+declare function generateKeypair(): Keypair;
+/**
+ * Register a Substrate keypair with the DataGrout CA.
+ *
+ * Sends only the public key to DG and receives a DG-CA-signed certificate.
+ * The private key in *keypair* is reused — it never leaves the client.
+ *
+ * @param keypair Generated by {@link generateKeypair}.
+ * @param opts Registration options (endpoint, API key, name).
+ */
+declare function registerIdentity(keypair: Keypair, opts: RegistrationOptions): Promise<RegisteredIdentity>;
+interface RotationOptions {
+    /** DataGrout substrate identity API base URL. */
+    endpoint: string;
+    /** Human-readable label for the renewed identity. */
+    name: string;
+    /** CA cert URL override. */
+    caUrl?: string;
+    /** Current identity PEM strings, used to build the mTLS client cert. */
+    currentCertPem: string;
+    currentKeyPem: string;
+}
+/**
+ * Rotate the Substrate identity by presenting the current cert over mTLS.
+ *
+ * Generates a new ECDSA P-256 keypair and sends the public key to the `/rotate`
+ * endpoint, authenticated with the *existing* client certificate over mTLS.
+ * The server returns a new DG-CA-signed certificate.
+ *
+ * Note: This uses Node.js `https` for mTLS — not compatible with browser environments.
+ */
+declare function rotateIdentity(opts: RotationOptions): Promise<RegisteredIdentity>;
+interface SavedPaths {
+    certPath: string;
+    keyPath: string;
+    caPath?: string;
+}
+/**
+ * Save a registered identity to a directory for auto-discovery by future sessions.
+ *
+ * Writes:
+ * - `{dir}/identity.pem`     — DG-signed certificate
+ * - `{dir}/identity_key.pem` — private key (mode 0600)
+ * - `{dir}/ca.pem`           — DG CA certificate (if present)
+ */
+declare function saveIdentity(identity: RegisteredIdentity, directory?: string): SavedPaths;
+
+/**
+ * Typed error classes for the DataGrout Conduit SDK.
+ *
+ * All errors extend `ConduitError` so callers can catch the whole family with
+ * a single `instanceof ConduitError` check, or target specific subclasses.
+ */
+
+/**
+ * Base class for all errors thrown by the Conduit SDK.
+ *
+ * Fixes the prototype chain so `instanceof` works correctly when compiling
+ * to CommonJS / ES5 targets.
+ */
+declare class ConduitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a `Client` method is called before `connect()` has been invoked,
+ * or after `disconnect()` has been called.
+ */
+declare class NotInitializedError extends ConduitError {
+    constructor();
+}
+/**
+ * Thrown when the DataGrout gateway returns HTTP 429 (Too Many Requests).
+ *
+ * Authenticated DataGrout users are never rate-limited. Unauthenticated
+ * callers hitting the hourly cap will receive this error.
+ *
+ * @property status  - Parsed rate-limit header state.
+ * @property retryAfter - Seconds to wait before retrying (from `Retry-After` header), if present.
+ */
+declare class RateLimitError extends ConduitError {
+    readonly status: RateLimitStatus;
+    readonly retryAfter?: number;
+    constructor(status: RateLimitStatus, retryAfter?: number);
+}
+/**
+ * Thrown when the server returns HTTP 401 Unauthorized or HTTP 403 Forbidden.
+ */
+declare class AuthError extends ConduitError {
+    constructor(message?: string);
+}
+/**
+ * Thrown on network-level failures such as fetch errors, connection refused,
+ * or request timeouts.
+ */
+declare class NetworkError extends ConduitError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the server returns an unexpected non-success HTTP status or
+ * a JSON-RPC error payload.
+ *
+ * @property code          - HTTP status code or JSON-RPC error code.
+ * @property serverMessage - Raw error message from the server.
+ */
+declare class ServerError extends ConduitError {
+    readonly code: number;
+    readonly serverMessage: string;
+    constructor(code: number, serverMessage: string);
+}
+/**
+ * Thrown when required parameters are missing, mutually-exclusive option
+ * combinations are invalid, or a method receives an unusable configuration.
+ */
+declare class InvalidConfigError extends ConduitError {
+    constructor(message: string);
+}
+
+/**
+ * DataGrout Conduit SDK for TypeScript/JavaScript
+ */
+
+declare const version = "0.1.0";
+
+export { type AuthConfig, AuthError, type Byok, type ChartOptions, Client, type ClientOptions, ConduitError, ConduitIdentity, type ConstrainOptions, type CreditEstimate, DEFAULT_IDENTITY_DIR, DG_CA_URL, DG_SUBSTRATE_ENDPOINT, type DiscoverOptions, type DiscoverResult, type FlowOptions, type ForgetOptions, type GuideOptions, type GuideRequestOptions, type GuideState, GuidedSession, InvalidConfigError, type Keypair, type MCPPrompt, type MCPResource, type MCPTool, type MtlsConfig, NetworkError, NotInitializedError, OAuthTokenProvider, type PerformOptions, type PerformResult, type PlanOptions, type PrismFocusOptions, type QueryCellOptions, type RateLimit, RateLimitError, type RateLimitStatus, type Receipt, type ReflectOptions, type RefractOptions, type RegisteredIdentity, type RegistrationOptions, type RememberOptions, type RenewalOptions, type RotationOptions, type SavedPaths, ServerError, type ToolInfo, type ToolMeta, deriveTokenEndpoint, extractMeta, fetchDgCaCert, fetchWithIdentity, generateKeypair, isDgUrl, refreshCaCert, registerIdentity, rotateIdentity, saveIdentity, version };