kaibo 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# kaibo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+TypeScript client for kaibo: memory for AI agents. It knows what is current, retires what is stale, and returns the smallest context for a task, with the events it came from.
+
+```bash
+bun add kaibo        # or: npm install kaibo, pnpm add kaibo, yarn add kaibo
+export KAIBO_KEY=kaibo_<id>.<secret>
+```
+
+```ts
+import { Kaibo } from "kaibo";
+
+const kaibo = new Kaibo(); // reads KAIBO_KEY
+
+await kaibo.remember("The release target is July 13.");
+await kaibo.remember("Move the release target from July 13 to July 17.", { wait: true });
+
+const pack = await kaibo.recall("release target");
+console.log(pack.found ? pack.answer : `no answer: ${pack.reason}`);
+console.log(pack.sources); // the events it came from
+```
+
+Put memory in a prompt:
+
+```ts
+const memory = await kaibo.context("what did we decide about the release?");
+```
+
+That is `recall` as text: delimited as stored data, cited, with outdated, unverified and untrusted items marked.
+
+Set up your agent tools (Claude Code, Cursor, Codex) with `kaibo init`. Docs: /docs/quickstart on your kaibo address

package/dist/client-CJM5BK2n.d.ts

@@ -0,0 +1,360 @@
+import { A as Project, B as WebhookEventType, D as MemoryStatus, F as RememberResult, H as WhoAmI, I as StoredEvent, L as Usage, M as RecallInput, N as ReceiptVerification, P as RememberInput, R as Webhook, S as JobStatus, T as Memory, _ as ForgetDryRun, a as ContextPack, b as ImportResult, c as CreatedWebhook, f as EventInput, g as ExportRecord, h as ExportInput, i as ContextItem, j as RecallEvent, k as Page, l as DeletionReceipt, m as Explanation, n as AttestVerification, o as CreateKeyInput, r as Citation, s as CreatedApiKey, t as ApiKey, u as Diff, v as ImportInput, z as WebhookDelivery } from "./types-q09Fds4e.js";
+/** What most code wants from a recall, without digging through `abstain` and `items[0]`. */
+interface Shared {
+  /** Every item's text, one per line, for putting in a prompt. Empty when there is no answer. */
+  readonly text: string;
+  /** The events the items came from, each once. */
+  readonly sources: Citation[];
+}
+/** Something citable matched. */
+interface Found extends Shared {
+  readonly found: true;
+  /** The best match. */
+  readonly top: ContextItem;
+  /** The best match's text. */
+  readonly answer: string;
+  readonly reason: null;
+}
+/** Nothing citable matched: say you do not know instead of guessing. */
+interface NotFound extends Shared {
+  readonly found: false;
+  readonly top: null;
+  readonly answer: null;
+  /** Why there is no answer. */
+  readonly reason: string;
+}
+type PackHelpers = Found | NotFound;
+/**
+ * A recall result: the plain JSON from the server plus the helpers above. Check `pack.found` and
+ * TypeScript knows `pack.top` and `pack.answer` are there.
+ */
+type Pack = ContextPack & PackHelpers;
+/**
+ * Adds the helpers as non-enumerable properties, so `JSON.stringify(pack)` and `verifyPack(pack)`
+ * still see exactly what the server sent.
+ */
+declare function withHelpers(pack: ContextPack): Pack;
+interface TransportOptions {
+  apiKey: string;
+  baseUrl: string;
+  /** Sent as `X-Project-Id`. Only needed for org-wide keys; project-bound keys carry theirs. */
+  project?: string | undefined;
+  fetch?: typeof fetch | undefined;
+  /** Retries after the first attempt. Default 2. */
+  retries?: number | undefined;
+  /** Per-attempt timeout. Default 30 000. */
+  timeoutMs?: number | undefined;
+  userAgent?: string | undefined;
+  /** Replaceable in tests so backoff does not take real time. */
+  sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** Replaceable in tests so jitter is deterministic. */
+  random?: (() => number) | undefined;
+}
+interface RequestOptions {
+  method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+  path: string;
+  query?: Record<string, string | number | undefined>;
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** Retry on 5xx, 429 and network errors. Only for requests that are safe to repeat. */
+  retry: boolean;
+  signal?: AbortSignal | undefined;
+  /** Return the raw response (for streaming). */
+  raw?: boolean;
+}
+declare class Transport {
+  private readonly o;
+  constructor(options: TransportOptions);
+  private url;
+  /** Sends a request, retrying when allowed. Throws a typed `KaiboError` on failure. */
+  request<T>(opts: RequestOptions): Promise<T>;
+  /** Like `request`, but returns the successful response untouched (for streaming bodies). */
+  stream(opts: RequestOptions): Promise<Response>;
+  private send;
+}
+interface KaiboOptions {
+  /** `kaibo_...` key from the dashboard. Defaults to the `KAIBO_KEY` environment variable. */
+  apiKey?: string;
+  /** The address of your kaibo site (the API lives under `/v1` there). Defaults to the `KAIBO_URL` environment variable. */
+  baseUrl?: string;
+  /** Project id, only for org-wide keys. Defaults to `KAIBO_PROJECT`. */
+  project?: string;
+  /** Custom `fetch` (proxies, tests, edge runtimes). Defaults to the global one. */
+  fetch?: typeof fetch;
+  /** Retries after the first attempt, for requests that are safe to repeat. Default 2. */
+  retries?: number;
+  /** Per-attempt timeout in ms. Default 30 000. */
+  timeoutMs?: number;
+}
+declare const SDK_VERSION = "0.1.0";
+interface WaitOptions {
+  /** Give up after this long. Default 10 000. */
+  timeoutMs?: number;
+  /** First poll delay, doubled up to 1 s. Default 100. */
+  intervalMs?: number;
+  signal?: AbortSignal;
+}
+/**
+ * Client for the four memory operations and the data behind them.
+ *
+ * @example
+ * ```ts
+ * const kaibo = new Kaibo(); // reads KAIBO_KEY (and KAIBO_URL, KAIBO_PROJECT) from the environment
+ * await kaibo.remember('Move the release target from July 13 to July 17.', { wait: true });
+ * const pack = await kaibo.recall('release target');
+ * console.log(pack.found ? pack.answer : `no answer: ${pack.reason}`, pack.sources);
+ * ```
+ */
+/** A memory id, or anything that carries one: a recalled item (`pack.top`), a memory from a list. */
+type MemoryRef = string | {
+  memoryId: string;
+} | {
+  id: string;
+};
+declare class Kaibo {
+  /** @internal */
+  readonly t: Transport;
+  readonly events: EventsApi;
+  readonly memories: MemoriesApi;
+  readonly jobs: JobsApi;
+  /** Manage webhook endpoints. Needs an `admin` key. */
+  readonly webhooks: WebhooksApi;
+  /** Bring memory in from Mem0, Zep, Letta, JSON Lines or Markdown. Needs a key that can write. */
+  readonly imports: ImportsApi;
+  /** Take events and memories out as JSON Lines. */
+  readonly exports: ExportsApi;
+  /** Create, list and revoke API keys. Needs an `admin` key. */
+  readonly keys: KeysApi;
+  /** List, create and rename projects. Needs an `admin` key. */
+  readonly projects: ProjectsApi;
+  /** Same as `new Kaibo()`: configuration comes from `KAIBO_KEY`, `KAIBO_URL` and `KAIBO_PROJECT`. */
+  static fromEnv(overrides?: KaiboOptions): Kaibo;
+  private readonly resolved;
+  /** The same client, acting on one project. For org-wide keys, which must say which project a call is about. */
+  withProject(project: string): Kaibo;
+  constructor(options?: KaiboOptions & Partial<Pick<TransportOptions, 'sleep' | 'random'>>);
+  /**
+   * Store raw events. Returns once they are durably appended and hash-chained; turning them into
+   * memory happens right after. Pass `wait: true` to return only when that has finished.
+   * Safe to retry: every request carries an idempotency key.
+   */
+  remember(input: string | RememberInput, options?: {
+    wait?: boolean | WaitOptions;
+    signal?: AbortSignal;
+  }): Promise<RememberResult>;
+  /**
+   * The smallest context that answers `query`, with a citation for every item. When nothing
+   * citable matches, `pack.found` is false and `pack.reason` says why: say you do not know instead of guessing.
+   * `pack.answer` is the best match's text, `pack.text` all of them for a prompt, `pack.sources` the events they came from.
+   */
+  recall: {
+    (input: string | RecallInput, options?: {
+      signal?: AbortSignal;
+    }): Promise<Pack>;
+    /** Same request, as server-sent events: candidates, packing, then the final pack. */
+    stream(input: string | RecallInput, options?: {
+      signal?: AbortSignal;
+    }): AsyncGenerator<RecallEvent>;
+  };
+  private recallStream;
+  /**
+   * Recall, rendered as text you can put straight into a prompt: delimited as stored data, with
+   * citations, and with outdated, unverified and untrusted items marked. Says so when there is no answer.
+   */
+  context(input: string | RecallInput, options?: {
+    signal?: AbortSignal;
+  }): Promise<string>;
+  /** Is this pack unchanged since kaibo issued it, and do its citations still match the stored events? */
+  verifyPack(pack: ContextPack, options?: {
+    signal?: AbortSignal;
+  }): Promise<AttestVerification>;
+  /** What became true and what stopped being true between two instants. Pair with `recall({ asOf })` to replay what an agent knew. */
+  diff(range: {
+    from: string;
+    to: string;
+  }, options?: {
+    signal?: AbortSignal;
+  }): Promise<Diff>;
+  /** Confirm a memory is still true; its freshness clock restarts. */
+  verifyMemory(memory: MemoryRef, options?: {
+    signal?: AbortSignal;
+  }): Promise<{
+    memoryId: string;
+    verifiedAt: string;
+  }>;
+  /** Why does this memory say what it says? Provenance back to the source events. */
+  explain(memory: MemoryRef, options?: {
+    depth?: number;
+    signal?: AbortSignal;
+  }): Promise<Explanation>;
+  /**
+   * Forget by memory id or by query. Recall stops returning it immediately; the text is purged
+   * after a grace window. Use `dryRun: true` first when selecting by query.
+   * Needs a key with the `forget` scope.
+   */
+  forget: {
+    (selector: {
+      memoryId: string;
+    } | {
+      query: string;
+    }, options: {
+      reason: string;
+      dryRun: true;
+      signal?: AbortSignal;
+    }): Promise<ForgetDryRun>;
+    (selector: {
+      memoryId: string;
+    } | {
+      query: string;
+    }, options: {
+      reason: string;
+      dryRun?: false;
+      signal?: AbortSignal;
+    }): Promise<{
+      receipt: DeletionReceipt;
+    }>;
+    /** Recompute the deletion ledger and check the memories are gone. */
+    verify(receiptId: string): Promise<ReceiptVerification>;
+    receipt(receiptId: string): Promise<DeletionReceipt>;
+  };
+  private verifyReceipt;
+  private getReceipt;
+  /** Counts for the project: events, memories by status, receipts. Numbers stop at 1000 and say so (`capped`). */
+  usage(): Promise<Usage>;
+  /** Describes the key in use (prefix, scopes, project). Handy as a connection check. */
+  whoami(): Promise<WhoAmI>;
+}
+declare class EventsApi {
+  private readonly t;
+  constructor(t: Transport);
+  /** Low-level append. Prefer `remember` unless you are shaping events yourself. */
+  append(events: EventInput[], options?: {
+    streamId?: string;
+    signal?: AbortSignal;
+  }): Promise<{
+    streamId: string;
+    firstSeq: number;
+    lastSeq: number;
+    headHash: string;
+    events: Array<{
+      id: string;
+      seq: number;
+      hash: string;
+      replayed: boolean;
+    }>;
+  }>;
+  get(id: string): Promise<StoredEvent>;
+  /** One page, with the cursor for the next. */
+  page(params?: {
+    stream?: string;
+    limit?: number;
+    cursor?: string;
+  }): Promise<Page<StoredEvent>>;
+  /** Every event of a stream in order, fetching pages as you iterate. */
+  list(params?: {
+    stream?: string;
+    pageSize?: number;
+  }): AsyncGenerator<StoredEvent>;
+  /** Pages as they arrive, for callers that batch. */
+  pages(params?: {
+    stream?: string;
+    pageSize?: number;
+  }): AsyncGenerator<StoredEvent[]>;
+}
+declare class MemoriesApi {
+  private readonly t;
+  constructor(t: Transport);
+  get(memory: MemoryRef): Promise<Memory>;
+  /**
+   * Replace what a current memory says. The old text stays as a superseded version, so history,
+   * `asOf` recall and `explain` still work. Returns the new version. Needs `write`.
+   */
+  edit(memory: MemoryRef, content: string): Promise<Memory>;
+  page(params?: {
+    status?: MemoryStatus;
+    limit?: number;
+    cursor?: string;
+  }): Promise<Page<Memory>>;
+  list(params?: {
+    status?: MemoryStatus;
+    pageSize?: number;
+  }): AsyncGenerator<Memory>;
+}
+declare class WebhooksApi {
+  private readonly t;
+  constructor(t: Transport);
+  /**
+   * Register an https endpoint. The signing secret is in the response and is never shown again.
+   * Verify deliveries with `verifyWebhook` from `kaibo/webhooks`.
+   */
+  create(input: {
+    url: string;
+    events?: WebhookEventType[];
+  }): Promise<CreatedWebhook>;
+  list(): Promise<Webhook[]>;
+  /** Recent deliveries, newest first, with status and attempts. */
+  deliveries(webhookId: string, options?: {
+    limit?: number;
+  }): Promise<WebhookDelivery[]>;
+  /** Queue a signed `webhook.test` delivery. */
+  test(webhookId: string): Promise<{
+    queued: true;
+  }>;
+  delete(webhookId: string): Promise<void>;
+}
+declare class ImportsApi {
+  private readonly t;
+  constructor(t: Transport);
+  /**
+   * Parse an export and append its events. With `dryRun: true` nothing is written and you get the
+   * report: what was read, what would be created, what was skipped and why. Safe to repeat: events
+   * carry idempotency keys derived from the records. The file must fit in one request (about 1 MB
+   * and 2000 events); `kaibo import` sends bigger files in chunks.
+   */
+  create(input: ImportInput, options?: {
+    dryRun?: boolean;
+    signal?: AbortSignal;
+  }): Promise<ImportResult>;
+}
+declare class ExportsApi {
+  private readonly t;
+  constructor(t: Transport);
+  /**
+   * The project's events and memories, one record at a time. Throws if the stream ends without
+   * its `end` record, because that means the export was cut off. At most 10 exports an hour per key.
+   */
+  stream(input?: ExportInput, options?: {
+    signal?: AbortSignal;
+  }): AsyncGenerator<ExportRecord>;
+  /** Collects a whole export in memory. Fine for small projects; prefer `stream`. */
+  create(input?: ExportInput, options?: {
+    signal?: AbortSignal;
+  }): Promise<ExportRecord[]>;
+}
+declare class ProjectsApi {
+  private readonly t;
+  constructor(t: Transport);
+  list(): Promise<Project[]>;
+  /** Needs an organization-wide admin key; a project-bound key cannot create projects. */
+  create(name: string): Promise<Project>;
+  /** Permanent: the project stops working at once and its data is removed in the background. Needs an organization-wide admin key. */
+  delete(projectId: string): Promise<void>;
+  rename(projectId: string, name: string): Promise<Project>;
+}
+declare class KeysApi {
+  private readonly t;
+  constructor(t: Transport);
+  list(): Promise<ApiKey[]>;
+  /** The secret is in `key` and is never shown again. A key can only grant scopes it holds. */
+  create(input: CreateKeyInput): Promise<CreatedApiKey>;
+  /** Revokes at once. Revoking the key you are calling with works and ends your access. */
+  revoke(keyId: string): Promise<ApiKey>;
+}
+declare class JobsApi {
+  private readonly t;
+  constructor(t: Transport);
+  get(jobId: string): Promise<JobStatus>;
+  /** Polls with a growing delay until extraction has caught up, or throws `TimeoutError`. */
+  wait(jobId: string, options?: WaitOptions): Promise<JobStatus>;
+}
+export { Kaibo as a, MemoriesApi as c, WaitOptions as d, WebhooksApi as f, withHelpers as h, JobsApi as i, ProjectsApi as l, PackHelpers as m, ExportsApi as n, KaiboOptions as o, Pack as p, ImportsApi as r, KeysApi as s, EventsApi as t, SDK_VERSION as u };