@infolang/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Authentication providers for the InfoLang SDK.
+ *
+ * A provider returns the headers to attach to each request. `headers()` is
+ * called before every request so providers can refresh short-lived tokens.
+ */
+declare const DEFAULT_SESSION_PATH: string;
+interface AuthProvider {
+    headers(): Promise<Record<string, string>>;
+}
+/** Bearer authentication with an InfoLang API key (`il_live_...`). */
+declare class ApiKeyAuth implements AuthProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    headers(): Promise<Record<string, string>>;
+}
+/** Self-hosted dev key in `key:namespace` form (matches INFOLANG_API_KEYS). */
+declare class DevKeyAuth implements AuthProvider {
+    readonly namespace: string;
+    private readonly token;
+    constructor(devKey: string);
+    headers(): Promise<Record<string, string>>;
+}
+/**
+ * OAuth bearer token read from the cursor-setup session file (default
+ * `~/.config/infolang/session.json`, written by `npx @infolang/cursor-setup`).
+ * Refreshes transparently when the file carries a `refresh_token` + `token_url`.
+ */
+declare class SessionFileAuth implements AuthProvider {
+    private readonly path;
+    private cache?;
+    constructor(path?: string);
+    private load;
+    headers(): Promise<Record<string, string>>;
+    private isExpired;
+    private refresh;
+}
+/** Worker-to-origin shared secret. For internal integrators only. */
+declare class OriginAuth implements AuthProvider {
+    private readonly workspace;
+    private readonly secret;
+    constructor(workspace: string, secret: string);
+    headers(): Promise<Record<string, string>>;
+}
+
+/**
+ * Request and response types mirroring the il-runtime REST contract
+ * (`openapi/il-runtime.yaml`). The runtime emits compact keys (`i`, `s`, `t`,
+ * `g`); the SDK normalizes them into readable fields.
+ */
+/** A single recalled memory chunk (normalized from the compact wire shape). */
+interface Chunk {
+    /** Memory id (wire: `i`). */
+    id: string;
+    /** Similarity score (wire: `s`). */
+    score?: number;
+    /** Chunk text (wire: `t`). */
+    text: string;
+    /** Tags (wire: `g`). */
+    tags?: string;
+}
+/** Usage metadata parsed from managed-cloud response headers. */
+interface MeteringMeta {
+    tokensSaved?: number;
+    chunksUsed?: number;
+    repoCoverage?: number;
+    requestId?: string;
+}
+/** Result of a `recall` / `investigate` call. */
+interface RecallResult {
+    chunks: Chunk[];
+    namespace?: string;
+    metering?: MeteringMeta;
+    /** True when the top match scores below the 0.85 confidence floor. */
+    weak: boolean;
+}
+/** Result of a `remember` / `memorize` call. */
+interface RememberResult {
+    memoryId?: string;
+    namespace?: string;
+}
+/** Result of a `contextPack` call: a token-budgeted context string. */
+interface ContextPack {
+    pack: string;
+    tokensEstimated?: number;
+    namespace?: string;
+    metering?: MeteringMeta;
+}
+/** A memory bank descriptor. */
+interface Bank {
+    namespace: string;
+    count?: number;
+}
+interface RecallOptions {
+    namespace?: string;
+    topK?: number;
+    filters?: Record<string, unknown>;
+    verbose?: boolean;
+}
+interface InvestigateOptions {
+    namespaceHint?: string;
+    topK?: number;
+}
+interface RememberOptions {
+    namespace?: string;
+    source?: string;
+    tags?: string;
+}
+interface ContextPackOptions {
+    namespace?: string;
+    maxTokens?: number;
+    repoRoot?: string;
+}
+interface ListRecentOptions {
+    namespace?: string;
+    n?: number;
+}
+
+/**
+ * fetch-native HTTP transport.
+ *
+ * Works on Node 18+, Bun, Deno, Cloudflare Workers and browsers without
+ * polyfills. Adds the resilience defaults expected of a modern SDK: targeted
+ * retries (429 + 5xx) with exponential backoff and full jitter, an explicit
+ * timeout budget via AbortController, and typed error mapping.
+ */
+
+type FetchLike = typeof fetch;
+interface TransportOptions {
+    baseUrl: string;
+    auth: AuthProvider;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    maxRetries?: number;
+    backoffBaseMs?: number;
+    backoffCapMs?: number;
+    userAgent: string;
+    /** When set, sent as X-InfoLang-Workspace-Id on every request. */
+    workspaceId?: string;
+}
+interface RequestOptions {
+    method: string;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+interface TransportResult<T> {
+    data: T;
+    metering: MeteringMeta;
+}
+declare class Transport {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly backoffBaseMs;
+    private readonly backoffCapMs;
+    private readonly userAgent;
+    private readonly workspaceId?;
+    constructor(options: TransportOptions);
+    private delay;
+    request<T>(options: RequestOptions): Promise<TransportResult<T>>;
+    private finish;
+}
+
+/** Context resource: context-pack, repo ingest, and batch execute. */
+
+declare class ContextResource {
+    private readonly transport;
+    private readonly defaultNamespace?;
+    constructor(transport: Transport, defaultNamespace?: string | undefined);
+    contextPack(query: string, options?: ContextPackOptions): Promise<ContextPack>;
+    ingestRepo(namespace: string, options: {
+        repoRoot: string;
+        ref?: string;
+    }): Promise<Record<string, unknown>>;
+    execute(operations: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+}
+
+/** Health resource: liveness/readiness checks against the runtime. */
+
+declare class HealthResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    check(): Promise<Record<string, unknown>>;
+}
+
+/** Memory resource: recall, remember, forget, and agent-friendly aliases. */
+
+declare class MemoryResource {
+    private readonly transport;
+    private readonly defaultNamespace?;
+    constructor(transport: Transport, defaultNamespace?: string | undefined);
+    recall(query: string, options?: RecallOptions): Promise<RecallResult>;
+    /** Agent-style recall with a sensible default `topK` of 5. */
+    investigate(query: string, options?: InvestigateOptions): Promise<RecallResult>;
+    remember(text: string, options?: RememberOptions): Promise<RememberResult>;
+    /** Alias for `remember` matching the `auto_memorize` tool. */
+    memorize(content: string, options?: RememberOptions): Promise<RememberResult>;
+    forget(memoryId: string, options?: {
+        namespace?: string;
+    }): Promise<void>;
+    listBanks(): Promise<Bank[]>;
+    listRecent(options?: ListRecentOptions): Promise<unknown[]>;
+    /** Recall with tag-inclusion ordering over a candidate pool (client-side). */
+    recallHybrid(query: string, options?: {
+        namespace?: string;
+        topK?: number;
+        tagFilter?: string[];
+        candidatePool?: number;
+        useHybrid?: boolean;
+    }): Promise<RecallResult>;
+    /** Store many memories via POST /v1/execute remember_batch. */
+    rememberBatch(items: Array<string | {
+        text: string;
+        tags?: string | string[];
+        source?: string;
+    }>, options?: {
+        namespace?: string;
+        source?: string;
+    }): Promise<RememberResult[]>;
+    /** Best-effort bulk clear (list + forget loop). */
+    resetNamespace(namespace?: string, options?: {
+        batch?: number;
+    }): Promise<number>;
+}
+
+/**
+ * The InfoLang client: one-line construction over the il-runtime REST API.
+ *
+ * Exposes grouped resources (`client.memory`, `client.context`,
+ * `client.health`) plus the common operations as top-level aliases so the
+ * first call is a one-liner.
+ */
+
+declare const CLOUD_BASE_URL = "https://api.infolang.ai";
+declare const DIRECT_BASE_URL = "http://127.0.0.1:8766";
+interface InfoLangOptions {
+    /** Managed-cloud API key (`il_live_...`). Defaults to the cloud base URL. */
+    apiKey?: string;
+    /** Self-hosted dev key in `key:namespace` form. Defaults to the direct base URL. */
+    devKey?: string;
+    /** An explicit auth provider (e.g. `new SessionFileAuth()`). */
+    auth?: AuthProvider;
+    baseUrl?: string;
+    namespace?: string;
+    /**
+     * Account workspace to target. Sent as `X-InfoLang-Workspace-Id`.
+     * Must be in the API key's allowlist (or a membership for JWT auth).
+     * Also reads `INFOLANG_WORKSPACE` / `INFOLANG_WORKSPACE_ID`.
+     */
+    workspace?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Custom fetch (for Workers, mocks, or a TLS-configured agent). */
+    fetch?: FetchLike;
+}
+declare class InfoLang {
+    readonly namespace?: string;
+    readonly workspace?: string;
+    readonly baseUrl: string;
+    readonly memory: MemoryResource;
+    readonly context: ContextResource;
+    readonly health: HealthResource;
+    constructor(options?: InfoLangOptions);
+    static fromApiKey(apiKey: string, options?: Omit<InfoLangOptions, "apiKey">): InfoLang;
+    static fromDevKey(devKey: string, options?: Omit<InfoLangOptions, "devKey">): InfoLang;
+    static fromSessionFile(path?: string, options?: Omit<InfoLangOptions, "auth">): InfoLang;
+    recall(query: string, options?: RecallOptions): Promise<RecallResult>;
+    investigate(query: string, options?: InvestigateOptions): Promise<RecallResult>;
+    remember(text: string, options?: RememberOptions): Promise<RememberResult>;
+    memorize(content: string, options?: RememberOptions): Promise<RememberResult>;
+    forget(memoryId: string, options?: {
+        namespace?: string;
+    }): Promise<void>;
+    listBanks(): Promise<Bank[]>;
+    listRecent(options?: ListRecentOptions): Promise<unknown[]>;
+    recallHybrid(query: string, options?: {
+        namespace?: string;
+        topK?: number;
+        tagFilter?: string[];
+        candidatePool?: number;
+        useHybrid?: boolean;
+    }): Promise<RecallResult>;
+    rememberBatch(items: Array<string | {
+        text: string;
+        tags?: string | string[];
+        source?: string;
+    }>, options?: {
+        namespace?: string;
+        source?: string;
+    }): Promise<RememberResult[]>;
+    resetNamespace(namespace?: string, options?: {
+        batch?: number;
+    }): Promise<number>;
+    contextPack(query: string, options?: ContextPackOptions): Promise<ContextPack>;
+    ingestRepo(namespace: string, options: {
+        repoRoot: string;
+        ref?: string;
+    }): Promise<Record<string, unknown>>;
+    execute(operations: Record<string, unknown>[]): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Typed error hierarchy for the InfoLang SDK.
+ *
+ * Catch these instead of inspecting raw responses. Every API error carries the
+ * originating `requestId` (from the `x-request-id` header) when available.
+ */
+declare class InfoLangError extends Error {
+    constructor(message: string);
+}
+/** Client misconfiguration (missing credentials, bad base URL). */
+declare class InfoLangConfigError extends InfoLangError {
+}
+/** The runtime could not be reached, or the request timed out. */
+declare class InfoLangConnectionError extends InfoLangError {
+}
+interface APIErrorOptions {
+    status: number;
+    body?: unknown;
+    requestId?: string;
+    retryAfter?: number;
+}
+/** A non-2xx response from the runtime. */
+declare class InfoLangAPIError extends InfoLangError {
+    readonly status: number;
+    readonly body: unknown;
+    readonly requestId?: string;
+    constructor(message: string, options: APIErrorOptions);
+}
+/** 401/403 — credential missing, invalid, or lacking permission. */
+declare class AuthenticationError extends InfoLangAPIError {
+}
+/** 404 — namespace, bank, or memory id does not exist. */
+declare class NotFoundError extends InfoLangAPIError {
+}
+/** 400/422 — the request payload was rejected. */
+declare class ValidationError extends InfoLangAPIError {
+}
+/** 429 — quota exceeded. `retryAfter` is seconds when the server sets it. */
+declare class RateLimitError extends InfoLangAPIError {
+    readonly retryAfter?: number;
+    constructor(message: string, options: APIErrorOptions);
+}
+/** 5xx — the runtime failed to process the request. */
+declare class ServerError extends InfoLangAPIError {
+}
+
+declare const version = "0.2.0";
+
+export { ApiKeyAuth, type AuthProvider, AuthenticationError, type Bank, CLOUD_BASE_URL, type Chunk, type ContextPack, type ContextPackOptions, DEFAULT_SESSION_PATH, DIRECT_BASE_URL, DevKeyAuth, InfoLang, InfoLangAPIError, InfoLangConfigError, InfoLangConnectionError, InfoLangError, type InfoLangOptions, type InvestigateOptions, type ListRecentOptions, type MeteringMeta, NotFoundError, OriginAuth, RateLimitError, type RecallOptions, type RecallResult, type RememberOptions, type RememberResult, ServerError, SessionFileAuth, ValidationError, version };