@railtownai/railengine-ingest 0.0.2 → 0.0.3

package/README.md

@@ -1,516 +1,56 @@
-# @railtownai/railengine-ingest
-
-JavaScript/TypeScript SDK for Railtown AI Rail Engine - Ingestion package. This package provides a simple interface for publishing data to Rail Engine and handling webhook events.
-
-## Installation
-
-```bash
-npm install @railtownai/railengine-ingest
-```
-
-## Requirements
-
-- Node.js 20+
-- TypeScript 5.0+ (optional, but recommended)
-
-## Quick Start
-
-### Basic Usage
-
-```typescript
-import { RailEngineIngest } from "@railtownai/railengine-ingest";
-import { Buffer } from "buffer";
-
-// Create ENGINE_TOKEN (get this from your Rail Engine dashboard)
-const tokenData = {
-  IngestionUrl: "https://eng123.railtownlogs.com",
-  IngestionApiToken: "your-auth-token",
-  EngineId: "your-engine-id"
-};
-const engineToken = Buffer.from(JSON.stringify(tokenData)).toString("base64");
-
-// Initialize client
-const client = new RailEngineIngest({ engineToken });
-
-// Send data
-await client.upsert({
-  EventId: "guid",
-  EngineId: client.engineId,
-  ProjectId: "project-id",
-  Body: JSON.stringify({ title: "My Document", content: "..." }),
-  CustomerKey: "doc-123" // Optional
-});
-```
-
-### Using Environment Variables
-
-```typescript
-import { RailEngineIngest } from "@railtownai/railengine-ingest";
-
-// ENGINE_TOKEN is read from environment variable automatically
-const client = new RailEngineIngest();
-
-await client.upsert({
-  EventId: "guid",
-  EngineId: client.engineId,
-  ProjectId: "project-id",
-  Body: JSON.stringify({ title: "My Document" })
-});
-```
-
-## ENGINE_TOKEN Configuration
-
-The `ENGINE_TOKEN` is a base64-encoded JSON string containing your ingestion configuration. You can create it like this:
-
-```typescript
-import { Buffer } from "buffer";
-
-const tokenData = {
-  IngestionUrl: "https://eng123.railtownlogs.com",
-  IngestionApiToken: "your-auth-token-here",
-  EngineId: "your-engine-guid-here"
-};
-
-const engineToken = Buffer.from(JSON.stringify(tokenData)).toString("base64");
-```
-
-### Setting Environment Variables
-
-#### Windows (PowerShell)
-
-```powershell
-$env:ENGINE_TOKEN="<base64-encoded-token>"
-```
-
-#### Windows (Command Prompt)
-
-```cmd
-set ENGINE_TOKEN=<base64-encoded-token>
-```
-
-#### macOS/Linux
-
-```bash
-export ENGINE_TOKEN="<base64-encoded-token>"
-```
-
-#### .env file
-
-Create a `.env` file in your project root:
-
-```
-ENGINE_TOKEN=<base64-encoded-token>
-```
-
-Then use a package like `dotenv` to load it:
-
-```typescript
-import "dotenv/config";
-import { RailEngineIngest } from "@railtownai/railengine-ingest";
-
-const client = new RailEngineIngest(); // Reads from process.env.ENGINE_TOKEN
-```
-
-## Zod Schema Support
-
-You can provide a Zod schema during client initialization to automatically validate ingested data:
-
-```typescript
-import { z } from "zod";
-import { RailEngineIngest } from "@railtownai/railengine-ingest";
-import { Buffer } from "buffer";
-
-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 token = Buffer.from(
-  JSON.stringify({
-    IngestionUrl: "https://eng123.railtownlogs.com",
-    IngestionApiToken: "your-auth-token",
-    EngineId: "your-engine-id"
-  })
-).toString("base64");
-
-const client = new RailEngineIngest({
-  engineToken: token,
-  schema: FoodDiaryItemSchema
-});
-
-// Ingest using validated object
-const item: FoodDiaryItem = {
-  food_name: "Apple",
-  calories: 95,
-  carbs: 25.0,
-  proteins: 0.5,
-  fats: 0.3
-};
-
-await client.upsert(item); // Automatically validates and serializes
-```
-
-## Webhook Handling
-
-The ingestion package provides webhook handling capabilities for receiving and processing webhook events from Rail Engine's Publishing cylinder.
-
-### Basic Webhook Handler
-
-```typescript
-import { z } from "zod";
-import { WebhookHandler } from "@railtownai/railengine-ingest";
-
-const FoodDiaryItemSchema = z.object({
-  food_name: z.string(),
-  calories: z.number()
-});
-
-// Create handler with schema
-const handler = new WebhookHandler({ schema: FoodDiaryItemSchema });
-
-// Parse webhook payload (list of events)
-const events = handler.parse(await request.json());
-
-// Process each event
-for (const event of events) {
-  console.log(`Event ID: ${event.eventId}`);
-  console.log(`Engine ID: ${event.engineId}`);
-  console.log(`Project ID: ${event.projectId}`);
-
-  // Access deserialized body (FoodDiaryItem)
-  const item = event.body;
-  console.log(`Food: ${item.food_name}, Calories: ${item.calories}`);
-}
-```
-
-### Using Client's Webhook Handler
-
-If your client was initialized with a schema, you can get a pre-configured webhook handler:
-
-```typescript
-import { z } from "zod";
-import { RailEngineIngest } from "@railtownai/railengine-ingest";
-import { Buffer } from "buffer";
-
-const FoodDiaryItemSchema = z.object({
-  food_name: z.string(),
-  calories: z.number()
-});
-
-const token = Buffer.from(
-  JSON.stringify({
-    IngestionUrl: "https://eng123.railtownlogs.com",
-    IngestionApiToken: "your-auth-token",
-    EngineId: "your-engine-id"
-  })
-).toString("base64");
-
-// Initialize client with schema
-const client = new RailEngineIngest({
-  engineToken: token,
-  schema: FoodDiaryItemSchema
-});
-
-// Get handler (automatically uses FoodDiaryItemSchema)
-const handler = client.getWebhookHandler();
-
-// Parse webhook payload
-const events = handler.parse(await request.json());
-
-// events[0].body is a FoodDiaryItem
-```
-
-### Express.js Integration Example
-
-```typescript
-import express from "express";
-import { z } from "zod";
-import { RailEngineIngest } from "@railtownai/railengine-ingest";
-import { Buffer } from "buffer";
-
-const app = express();
-
-const FoodDiaryItemSchema = z.object({
-  food_name: z.string(),
-  calories: z.number(),
-  carbs: z.number(),
-  proteins: z.number(),
-  fats: z.number()
-});
-
-const token = Buffer.from(
-  JSON.stringify({
-    IngestionUrl: "https://eng123.railtownlogs.com",
-    IngestionApiToken: "your-auth-token",
-    EngineId: "your-engine-id"
-  })
-).toString("base64");
-
-const client = new RailEngineIngest({
-  engineToken: token,
-  schema: FoodDiaryItemSchema
-});
-
-const handler = client.getWebhookHandler();
-
-app.post("/webhook", express.json(), async (req, res) => {
-  try {
-    // Parse webhook payload (list of events)
-    const events = handler.parse(req.body);
-
-    // Process each event
-    for (const event of events) {
-      // Access metadata
-      console.log(`Event ID: ${event.eventId}`);
-      console.log(`Engine ID: ${event.engineId}`);
-      console.log(`Project ID: ${event.projectId}`);
-
-      // Access deserialized body (FoodDiaryItem)
-      const item = event.body;
-      console.log(`Food: ${item.food_name}, Calories: ${item.calories}`);
-    }
-
-    res.json({ status: "ok" });
-  } catch (error) {
-    console.error("Webhook processing error:", error);
-    res.status(400).json({ error: "Invalid webhook payload" });
-  }
-});
-
-app.listen(3000);
-```
-
-### Manual Deserialization
-
-You can also deserialize webhook payloads manually:
-
-```typescript
-import { WebhookPublishingPayload, WebhookPublishingPayloadHelper } from "@railtownai/railengine-ingest";
-import { z } from "zod";
-
-const FoodDiaryItemSchema = z.object({
-  food_name: z.string(),
-  calories: z.number()
-});
-
-// Parse raw payload
-const payload = req.body[0] as WebhookPublishingPayload; // First event
-
-// Deserialize body manually
-const item = WebhookPublishingPayloadHelper.getBodyAs(payload, FoodDiaryItemSchema);
-console.log(`Food: ${item.food_name}, Calories: ${item.calories}`);
-```
-
-## API Reference
-
-### RailEngineIngest
-
-Main client class for ingesting data to Rail Engine.
-
-#### Constructor
-
-```typescript
-new RailEngineIngest(options?: RailEngineIngestOptions<T>)
-```
-
-**Options:**
-
-- `engineToken?: string` - Base64-encoded ENGINE_TOKEN. If not provided, reads from `ENGINE_TOKEN` environment variable.
-- `schema?: z.ZodSchema<T>` - Optional Zod schema for validating ingested data and deserializing webhook bodies.
-- `timeout?: number` - Request timeout in milliseconds. Defaults to 30000 (30 seconds).
-
-**Example:**
-
-```typescript
-const client = new RailEngineIngest({
-  engineToken: token,
-  schema: MySchema,
-  timeout: 60000
-});
-```
-
-#### Properties
-
-- `ingestionUrl: string` - Logic App ingestion URL from decoded ENGINE_TOKEN
-- `ingestionApiToken: string` - Authentication token for x-rail-auth header
-- `engineId: string` - Engine identifier from decoded ENGINE_TOKEN
-
-#### Methods
-
-##### upsert(data)
-
-Send data to Rail Engine ingestion endpoint.
-
-```typescript
-await client.upsert(data: T | string | Record<string, unknown>): Promise<Response>
-```
-
-**Parameters:**
-
-- `data` - Data to ingest. Can be an object, JSON string, or Zod-validated object (if schema provided).
-
-**Returns:**
-
-- `Promise<Response>` - HTTP response from the ingestion endpoint
-
-**Throws:**
-
-- `RailtownError` - If the request fails
-- `z.ZodError` - If schema validation fails
-
-**Example:**
-
-```typescript
-await client.upsert({ name: "test", value: 123 });
-```
-
-##### getWebhookHandler()
-
-Get a webhook handler configured with this client's schema.
-
-```typescript
-client.getWebhookHandler(): WebhookHandler<T>
-```
-
-**Returns:**
-
-- `WebhookHandler<T>` - Webhook handler instance configured with the client's schema (if provided)
-
-**Example:**
-
-```typescript
-const handler = client.getWebhookHandler();
-const events = handler.parse(webhookPayload);
-```
-
-### WebhookHandler
-
-Generic handler class for parsing webhook events.
-
-#### Constructor
-
-```typescript
-new WebhookHandler<T>(options?: { schema?: z.ZodSchema<T> })
-```
-
-**Options:**
-
-- `schema?: z.ZodSchema<T>` - Optional Zod schema for deserializing webhook bodies.
-
-#### Methods
-
-##### parse(payload)
-
-Parse webhook payload into list of WebhookEvent objects.
-
-```typescript
-handler.parse(payload: WebhookPublishingPayload[] | WebhookPublishingPayload): WebhookEvent<T>[]
-```
-
-**Parameters:**
-
-- `payload` - Either a list of webhook payload objects or a single object
-
-**Returns:**
-
-- `WebhookEvent<T>[]` - List of WebhookEvent objects
-
-**Throws:**
-
-- `Error` - If no schema is provided
-- `z.ZodError` - If body JSON doesn't match the schema
-
-### WebhookEvent
-
-Generic wrapper class that combines webhook payload metadata with deserialized body.
-
-#### Properties
-
-- `eventId: string` - Event identifier from payload
-- `engineId: string` - Engine identifier from payload
-- `projectId: string` - Project identifier from payload
-- `customerKey?: string` - Customer key from payload (if present)
-- `body: T` - Deserialized body as validated object
-
-### WebhookPublishingPayload
-
-TypeScript interface representing the webhook payload structure.
-
-```typescript
-interface WebhookPublishingPayload {
-  EventId: string;
-  EngineId: string;
-  ProjectId: string;
-  CustomerKey?: string;
-  Body: string; // JSON stringified document
-}
-```
-
-### WebhookPublishingPayloadHelper
-
-Helper class for working with WebhookPublishingPayload.
-
-#### Methods
-
-##### getBodyAs(payload, schema)
-
-Deserializes the Body field (JSON string) into a Zod-validated object.
-
-```typescript
-WebhookPublishingPayloadHelper.getBodyAs<T>(
-  payload: WebhookPublishingPayload,
-  schema: z.ZodSchema<T>
-): T
-```
-
-**Parameters:**
-
-- `payload` - The webhook payload
-- `schema` - Zod schema to validate the Body against
-
-**Returns:**
-
-- `T` - Validated object
-
-**Throws:**
-
-- `z.ZodError` - If the JSON doesn't match the schema
-
-## Error Handling
-
-The SDK uses custom exception classes for different error scenarios:
-
-- `RailtownError` - Base error class
-- `RailtownUnauthorizedError` - Authentication failed (401)
-- `RailtownNotFoundError` - Resource not found (404)
-- `RailtownBadRequestError` - Bad request (400)
-- `RailtownConflictError` - Conflict (409)
-- `RailtownServerError` - Server error (500+)
-
-**Example:**
-
-```typescript
-import { RailEngineIngest, RailtownUnauthorizedError, RailtownBadRequestError } from "@railtownai/railengine-ingest";
-
-try {
-  await client.upsert(data);
-} catch (error) {
-  if (error instanceof RailtownUnauthorizedError) {
-    console.error("Authentication failed:", error.message);
-  } else if (error instanceof RailtownBadRequestError) {
-    console.error("Invalid request:", error.message);
-  } else {
-    console.error("Unexpected error:", error);
-  }
-}
-```
-
-## License
-
-See [LICENSE](../../LICENSE) file for details.
+# @railtownai/railengine-ingest
+
+JavaScript/TypeScript SDK for Railtown AI Rail Engine - Ingestion package. This package provides a simple interface for publishing data to Rail Engine and handling webhook events.
+
+## Installation
+
+```bash
+npm install @railtownai/railengine-ingest
+```
+
+## Requirements
+
+- Node.js 20+
+- TypeScript 5.0+ (optional, but recommended)
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { RailEngineIngest } from "@railtownai/railengine-ingest";
+
+const engineToken = "[Your ENGINE_TOKEN]";
+
+// Initialize client
+const client = new RailEngineIngest({ engineToken });
+
+// Send data
+await client.upsert({
+  EventId: "guid",
+  EngineId: client.engineId,
+  ProjectId: "project-id",
+  Body: JSON.stringify({ title: "My Document", content: "..." }),
+  CustomerKey: "doc-123" // Optional
+});
+```
+
+### Using Environment Variables
+
+```typescript
+import { RailEngineIngest } from "@railtownai/railengine-ingest";
+
+// ENGINE_TOKEN is read from environment variable automatically
+const client = new RailEngineIngest();
+
+await client.upsert({
+  EventId: "guid",
+  EngineId: client.engineId,
+  ProjectId: "project-id",
+  Body: JSON.stringify({ title: "My Document" })
+});
+```
+
+## License
+
+See [LICENSE](../../LICENSE) file for details.

package/package.json

@@ -2,7 +2,7 @@
   "name": "@railtownai/railengine-ingest",
   "license": "MIT",
   "author": "Railtown AI",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "JavaScript/TypeScript SDK for Railtown AI Rail Engine - Ingestion",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -42,6 +42,7 @@
     "test": "vitest run --passWithNoTests",
     "format": "prettier --write src",
     "update": "npx npm-check-updates -u",
-    "dry-run": "pnpm publish --no-git-checks --access public --registry https://registry.npmjs.org --dry-run"
+    "dry-run": "pnpm publish --no-git-checks --access public --registry https://registry.npmjs.org --dry-run",
+    "release": "pnpm publish --no-git-checks --access public --registry https://registry.npmjs.org"
   }
 }