npm package: @railtownai/railengine
Description: JavaScript/TypeScript SDK for Railtown AI Rail Engine - Retrieval
Author: Railtown AI
Latest version: 0.0.5

# @railtownai/railengine

JavaScript/TypeScript SDK for [Railtown AI Rail Engine](https://railengine.ai/) - Retrieval package. This package provides a simple interface for reading and searching data from Rail Engine.

## Installation

```bash
npm install @railtownai/railengine
```

## Requirements

- Node.js 20+
- TypeScript 5.0+ (optional, but recommended)

## Quick Start

### Basic Usage

```typescript
import { RailEngine } from "@railtownai/railengine";

// ENGINE_PAT and ENGINE_ID are read from environment variables automatically

// Initialize client
const client = new RailEngine();

// Get storage document by EventId
const document = await client.getStorageDocumentByEventId({
  eventId: "event-id"
});
console.log(document);
```

### Using Environment Variables

```typescript
import { RailEngine } from "@railtownai/railengine";

const client = new RailEngine();

// Use client.engineId if you need it
const results = client.searchVectorStore(client.engineId, "VectorStore1", "query");
for await (const result of results) {
  console.log(result);
}
```

## Zod Schema Support

You can provide a Zod schema during client initialization to automatically validate retrieved data:

```typescript
import { z } from "zod";
import { RailEngine } from "@railtownai/railengine";

const FoodDiaryItemSchema = z.object({
  food_name: z.string(),
  calories: z.number(),
  carbs: z.number(),
  proteins: z.number(),
  fats: z.number()
});

type FoodDiaryItem = z.infer<typeof FoodDiaryItemSchema>;

// Initialize with schema
const client = new RailEngine({
  schema: FoodDiaryItemSchema
});

// Results automatically validated against FoodDiaryItemSchema
const results = client.searchVectorStore({
  vectorStore: "VectorStore1",
  query: "apple"
});
for await (const item of results) {
  // item is FoodDiaryItem
  console.log(item.food_name, item.calories);
}
```

## API Methods

### Embeddings API

#### searchVectorStore

Search a vector store using semantic similarity.

**Example:**

```typescript
const results = client.searchVectorStore({
  engineId: "engine-id", // Optional, defaults to process.env.ENGINE_ID
  vectorStore: "VectorStore1",
  query: "apple"
});
for await (const result of results) {
  console.log(result);
}
```

### Storage API

#### getStorageDocumentByEventId

Get a single storage document by EventId.

**Example:**

```typescript
const document = await client.getStorageDocumentByEventId({
  eventId: "event-id",
  engineId: "engine-id" // Optional, defaults to process.env.ENGINE_ID
});
if (document) {
  console.log(document);
}
```

#### getStorageDocumentByCustomerKey

Get storage documents by CustomerKey with automatic pagination.

**Example:**

```typescript
const documents = client.getStorageDocumentByCustomerKey({
  customerKey: "doc-123",
  engineId: "engine-id", // Optional, defaults to process.env.ENGINE_ID
  pageSize: 50
});

for await (const doc of documents) {
  console.log(doc);
}
```

#### queryStorageByJsonPath

Query storage documents using JSONPath.

```typescript
const documents = client.queryStorageByJsonPath(
  engineId: string,
  jsonPathQuery: string,
  options?: {
    filterFn?: (item: T | Record<string, unknown>) => boolean;
    schema?: z.ZodSchema<unknown>;
  }
): AsyncIterable<T | Record<string, unknown>>
```

**Example:**

```typescript
const documents = await client.queryStorageByJsonPath({
  engineId: "engine-id",
  jsonPathQuery: "$.status:active"
});
for await (const doc of documents) {
  console.log(doc);
}
```

#### listStorageDocuments

List storage documents with automatic pagination.

**Example:**

```typescript
// List all documents
const documents = await client.listStorageDocuments({
  engineId: "engine-id"
});

// List documents filtered by customerKey
const filtered = await client.listStorageDocuments({
  engineId: "engine-id",
  customerKey: "doc-123"
});

for await (const doc of documents) {
  console.log(doc);
}
```

### Indexing API

#### searchIndex

Search Railengine Index.

**Example:**

```typescript
const results = client.searchIndex("engine-id", { search: "example query" });

for await (const result of results) {
  console.log(result);
}
```

## License

MIT.