> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/reference/typescript-sdk.md).

# TypeScript SDK

Reference for the TypeScript SDK (npm \`telys-ai\`) — the encapsulated in-process runtime, the Telys/Collection surface, Eq filters, persistence shared with Python, and the runtime ops.

Telys ships a TypeScript SDK alongside the Python one: **`npm install telys-ai`** (Node >= 22). It is the same engine with the same guarantees — embedded, on-device, zero cloud roundtrips at query time — loaded **in-process** inside your Node process. There is no sidecar process and nothing to manage.

```bash
npm install telys-ai
```

```typescript
import { Telys, Eq } from "telys-ai";

const db = await Telys.open("./memory");
const col = db.createCollection("docs", {
  dim: 768,
  partitionBy: "tenant_id",
  filterColumns: ["lang"],
});

col.add(vectors, ids, metadata);                    // bring your own vectors (embedding-agnostic)
const hits = col.search(queryVec, {
  topK: 10,
  where: new Eq("tenant_id", "acme"),
  explain: true,
});
```

## How the runtime gets there (encapsulated)

The closed Mojo runtime (`libty_runtime`) is loaded through a frozen C-ABI inside your process:

1. A runtime already installed by the Python CLI (`telys runtime install`) is **reused** from `$TELYS_HOME/runtime/<platform>/` (default `~/.telys`) — both SDKs share one verified install.
2. Otherwise, when a token is available (`TELYS_TOKEN` / `TELYS_API_KEY`), the SDK **fetches the signed bundle itself** from the download host and verifies it OFFLINE — RS256 manifest signature over the exact shipped bytes, SHA-256 artifact hashes, and the strict ver:2 license policy (alg pinned to RS256, no `crit`, issuer/audience/expiry/grace, `products.telys` with a tier + features). This is the same trust core as the Python SDK, ported to `node:crypto`.

Installing the runtime is the only networked step. Queries never touch the network.

## The surface

| Area        | API                                                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Engine      | `await Telys.open(path)` · `Telys.openSync(path)` · `createCollection` · `openCollection` · `collections()` · `scopeKey(...parts)`                                       |
| Collection  | `add` (new ids only) · `upsert` · `update` (strict — unknown ids raise) · `search` · `ids(where?)` · `fetch(ids)` · `delete` · `compact` · `snapshot` · `stats` · `save` |
| Filters     | `new Eq(column, value)` on the partition key or a declared filter column                                                                                                 |
| Runtime ops | `ensureRuntime()` · `installFromHost()` · `installFromFile()` · `verifyInstalled()` · `resolveRuntimeLib()`                                                              |
| Trust core  | `verifyManifest()` · `verifyLicense()` · `verifyArtifact()`                                                                                                              |

Semantics match the Python SDK exactly: `add` raises on existing ids, `upsert` adds-or-replaces (a new visible version, never a duplicate row), `update` replaces existing rows only and raises for unknown or deleted ids, deletes are tombstones reclaimed by `compact`.

## Shared persistence

Collections persist in the **same on-disk format** as the Python SDK (`ty_base.npy` + `ty_native.json` + `collection.json`), so a store is portable across languages in either direction — a collection written by Python opens in TypeScript and vice versa.

## Scope today

Vectors in, vectors out: filtered dense search over bring-your-own embeddings. Text embedders (the kernel-backed bigram/multigram) and the lexical code index are Python-side today and come to this SDK later — from TypeScript, embed with any model and pass the vectors.

Platforms: macOS arm64 and Linux x86\_64 runtime targets (the signed-bundle P0 set). See [Supported platforms](https://docs.telys.ai/operations/supported-platforms.md).

## Next

| Task                     | What it covers                                     | Guide                                                                                                 |
| ------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Install Telys**        | SDK + runtime install and verification.            | [../install.md](https://docs.telys.ai/start-here/install.md)                                          |
| **First collection**     | Create, add, and search your first collection.     | [../quickstart-first-collection.md](https://docs.telys.ai/quickstarts/quickstart-first-collection.md) |
| **Filters (Eq)**         | The equality filter semantics shared by both SDKs. | [filters.md](https://docs.telys.ai/reference/filters.md)                                              |
| **Python SDK API index** | The full Python surface this SDK mirrors.          | [sdk-api-index.md](https://docs.telys.ai/reference/sdk-api-index.md)                                  |
