@yesilsci/health-ai-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yesil Health
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# @yesilsci/health-ai-api
+
+Official TypeScript client for the **Yesil Health enterprise (B2B) API**.
+
+Zero runtime dependencies — uses the platform `fetch` + `ReadableStream`
+(Node ≥ 18, modern browsers, edge runtimes). The hard part of integrating —
+parsing the typed Server-Sent Events stream — is handled for you.
+
+## Install
+
+```bash
+npm install @yesilsci/health-ai-api
+```
+
+## Quick start
+
+```ts
+import { YesilHealthClient } from '@yesilsci/health-ai-api';
+import { randomUUID } from 'node:crypto';
+
+const client = new YesilHealthClient({
+  baseUrl: 'https://api.yesilhealth.com',
+  apiKey: process.env.YESIL_API_KEY!, // sent as X-API-Key
+});
+
+for await (const ev of client.chatStream({
+  question: 'Is metformin safe for a patient with stage 3 CKD?',
+  request_id: randomUUID(),          // idempotent billing — strongly recommended
+  demographics: { age: 62, sex: 'female' },
+  health_context: 'eGFR 45 mL/min/1.73m². On lisinopril 10mg daily.',
+})) {
+  if (ev.type === 'delta') process.stdout.write(ev.content);
+}
+```
+
+One-shot (no live rendering):
+
+```ts
+const { text, events } = await client.chat({ question: '...' });
+```
+
+## Authentication
+
+Every request is authenticated with your enterprise API key via the `X-API-Key`
+header. Keep it server-side; never ship it in a browser bundle or mobile app.
+
+## The event stream
+
+`chatStream()` yields typed events. Route on `event.type`:
+
+| `type`             | Payload                              | Notes |
+|--------------------|--------------------------------------|-------|
+| `meta`             | `phase`, `conversation_id`, research preview fields | Lifecycle + mid-stream research previews. |
+| `delta`            | `content: string`                    | Append `content` to build the answer text. |
+| `citation`         | citation fields                      | A literature citation for the answer. |
+| `graph`            | `data: {...}`                        | Structured chart/diagram, delivered out-of-band from text. |
+| `memory_extracted` | `signals: MemorySignal[]`            | Only if your tenant has `extract_memory` enabled. Persist and replay via `memory`. |
+| `done`             | `summary: {...}`                     | Terminal success event. |
+| `error`            | `message`, `code`                    | Terminal failure event; stream ends. |
+
+> **Forward compatibility.** The API only ever *adds* fields and event types
+> within a contract version — it never renames, removes, or retypes existing
+> ones. Always include a `default` branch in your `switch` and ignore unknown
+> event types. This client surfaces them as `UnknownEvent` rather than throwing.
+
+## Request fields
+
+| Field                  | Required | Description |
+|------------------------|----------|-------------|
+| `question`             | ✅       | The end-user's question. |
+| `request_id`           | —        | Client UUID for idempotent billing. Strongly recommended. |
+| `demographics`         | —        | Small structured profile (`≤ 12 KB` JSON). |
+| `health_context`       | —        | Free-form clinical context (vitals, EHR summary, wearable rollups). |
+| `conversation_history` | —        | Last turns only (max 8), `role` ∈ `user`/`assistant`. |
+| `memory`               | —        | Raw memory signals to replay. |
+| `tenant_id`            | —        | Optional hint; must match the key's tenant. |
+
+## Errors
+
+Non-2xx HTTP responses throw `YesilApiError` with `status`, `code`
+(server `error_code`), and `message`:
+
+```ts
+import { YesilApiError } from '@yesilsci/health-ai-api';
+
+try {
+  await client.chat({ question: '...' });
+} catch (e) {
+  if (e instanceof YesilApiError) {
+    if (e.code === 'RATE_LIMITED') { /* back off */ }
+    if (e.status === 402)          { /* quota exhausted / billing */ }
+  }
+}
+```
+
+Common codes: `RATE_LIMITED` (429), quota/billing (402), `INVALID_API_KEY`
+(401). In-stream failures arrive as an `error` event (see table above), not an
+exception, unless you use the `chat()` convenience wrapper which re-throws them.
+
+## Account endpoints
+
+```ts
+await client.billing(); // billing status
+await client.quota();   // quota / rate-limit status
+await client.usage();   // usage report
+```
+
+## Cancellation
+
+Pass an `AbortSignal` to stop a stream early:
+
+```ts
+const ac = new AbortController();
+setTimeout(() => ac.abort(), 5_000);
+for await (const ev of client.chatStream({ question: '...' }, { signal: ac.signal })) { /* … */ }
+```
+
+## Versioning
+
+The client targets contract **v1** (`/api/v1`). When Yesil Health cuts a new
+major version it ships alongside v1; bump `apiVersion` in `ClientOptions` to
+migrate on your own schedule. v1 is never force-killed.

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import type { BillingStatus, ChatEvent, ChatRequest, QuotaStatus, UsageReport } from './types.js';
+export interface ClientOptions {
+    /** Base URL of the Yesil Health API, e.g. "https://api.yesilhealth.com". No trailing slash needed. */
+    baseUrl: string;
+    /** Your enterprise API key. Sent as the `X-API-Key` header. */
+    apiKey: string;
+    /** Contract version prefix. Defaults to "v1". Change only when migrating to a new major version. */
+    apiVersion?: string;
+    /** Optional custom fetch (for testing / non-standard runtimes). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/** Thrown for non-2xx HTTP responses. `code` mirrors the server's `error_code` when present. */
+export declare class YesilApiError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    constructor(message: string, status: number, code?: string, body?: unknown);
+}
+export interface ChatStreamOptions {
+    /** Abort the stream early. */
+    signal?: AbortSignal;
+}
+/**
+ * Client for the Yesil Health enterprise (B2B) API.
+ *
+ * @example
+ * const client = new YesilHealthClient({ baseUrl: '...', apiKey: '...' });
+ * for await (const ev of client.chatStream({ question: 'Is metformin safe in CKD?' })) {
+ *   if (ev.type === 'delta') process.stdout.write(ev.content);
+ * }
+ */
+export declare class YesilHealthClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly prefix;
+    private readonly _fetch;
+    constructor(opts: ClientOptions);
+    /**
+     * Stream a chat answer as a sequence of typed events. The async generator
+     * yields every event verbatim; route on `event.type`. The stream ends after a
+     * `done` event (success) or an `error` event (failure).
+     */
+    chatStream(body: ChatRequest, opts?: ChatStreamOptions): AsyncGenerator<ChatEvent, void, unknown>;
+    /**
+     * Convenience wrapper: drains the stream, returns the full concatenated answer
+     * text plus the collected events. Use `chatStream` directly when you want to
+     * render tokens live.
+     */
+    chat(body: ChatRequest, opts?: ChatStreamOptions): Promise<{
+        text: string;
+        events: ChatEvent[];
+    }>;
+    /** Current billing status for the authenticated tenant. */
+    billing(): Promise<BillingStatus>;
+    /** Current quota / rate-limit status. */
+    quota(): Promise<QuotaStatus>;
+    /** Usage report for the authenticated tenant. */
+    usage(): Promise<UsageReport>;
+    private get;
+    private toError;
+}

package/dist/client.js

@@ -0,0 +1,129 @@
+import { parseSSE } from './sse.js';
+/** Thrown for non-2xx HTTP responses. `code` mirrors the server's `error_code` when present. */
+export class YesilApiError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, status, code, body) {
+        super(message);
+        this.name = 'YesilApiError';
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+/**
+ * Client for the Yesil Health enterprise (B2B) API.
+ *
+ * @example
+ * const client = new YesilHealthClient({ baseUrl: '...', apiKey: '...' });
+ * for await (const ev of client.chatStream({ question: 'Is metformin safe in CKD?' })) {
+ *   if (ev.type === 'delta') process.stdout.write(ev.content);
+ * }
+ */
+export class YesilHealthClient {
+    baseUrl;
+    apiKey;
+    prefix;
+    _fetch;
+    constructor(opts) {
+        if (!opts.baseUrl)
+            throw new Error('baseUrl is required');
+        if (!opts.apiKey)
+            throw new Error('apiKey is required');
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.apiKey = opts.apiKey;
+        this.prefix = `/api/${opts.apiVersion ?? 'v1'}`;
+        this._fetch = opts.fetch ?? globalThis.fetch;
+        if (!this._fetch) {
+            throw new Error('No fetch available. Use Node >=18 or pass a custom fetch in ClientOptions.');
+        }
+    }
+    /**
+     * Stream a chat answer as a sequence of typed events. The async generator
+     * yields every event verbatim; route on `event.type`. The stream ends after a
+     * `done` event (success) or an `error` event (failure).
+     */
+    async *chatStream(body, opts = {}) {
+        const res = await this._fetch(`${this.baseUrl}${this.prefix}/chat/stream`, {
+            method: 'POST',
+            headers: {
+                'X-API-Key': this.apiKey,
+                'Content-Type': 'application/json',
+                Accept: 'text/event-stream',
+            },
+            body: JSON.stringify(body),
+            signal: opts.signal,
+        });
+        if (!res.ok || !res.body) {
+            throw await this.toError(res);
+        }
+        for await (const ev of parseSSE(res.body, opts.signal)) {
+            yield ev;
+        }
+    }
+    /**
+     * Convenience wrapper: drains the stream, returns the full concatenated answer
+     * text plus the collected events. Use `chatStream` directly when you want to
+     * render tokens live.
+     */
+    async chat(body, opts = {}) {
+        let text = '';
+        const events = [];
+        for await (const ev of this.chatStream(body, opts)) {
+            events.push(ev);
+            if (ev.type === 'delta')
+                text += ev.content;
+            if (ev.type === 'error') {
+                const err = ev;
+                throw new YesilApiError(err.message, 502, err.code, err);
+            }
+        }
+        return { text, events };
+    }
+    /** Current billing status for the authenticated tenant. */
+    billing() {
+        return this.get('/billing');
+    }
+    /** Current quota / rate-limit status. */
+    quota() {
+        return this.get('/quota');
+    }
+    /** Usage report for the authenticated tenant. */
+    usage() {
+        return this.get('/usage');
+    }
+    async get(path) {
+        const res = await this._fetch(`${this.baseUrl}${this.prefix}${path}`, {
+            method: 'GET',
+            headers: { 'X-API-Key': this.apiKey, Accept: 'application/json' },
+        });
+        if (!res.ok)
+            throw await this.toError(res);
+        return (await res.json());
+    }
+    async toError(res) {
+        let body;
+        let code;
+        let message = `HTTP ${res.status}`;
+        try {
+            body = await res.json();
+            const detail = body?.detail ?? body;
+            if (detail && typeof detail === 'object') {
+                code = detail.error_code;
+                const m = detail.message;
+                if (m)
+                    message = m;
+            }
+        }
+        catch {
+            try {
+                message = (await res.text()) || message;
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        return new YesilApiError(message, res.status, code, body);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { YesilHealthClient, YesilApiError } from './client.js';
+export type { ClientOptions, ChatStreamOptions } from './client.js';
+export { parseSSE } from './sse.js';
+export type { ChatRequest, ChatEvent, ConversationTurn, MemorySignal, MetaEvent, DeltaEvent, CitationEvent, GraphEvent, MemoryExtractedEvent, DoneEvent, ErrorEvent, UnknownEvent, BillingStatus, QuotaStatus, UsageReport, } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { YesilHealthClient, YesilApiError } from './client.js';
+export { parseSSE } from './sse.js';

package/dist/sse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal SSE parser for the Yesil Health stream.
+ *
+ * The server emits each event as:
+ *   event: <type>\n
+ *   data: {"type":"<type>", ...}\n
+ *   \n
+ *
+ * The `type` is carried both in the `event:` line and in the JSON body. We route
+ * on the JSON body's `type` (authoritative) and fall back to the `event:` line.
+ * Events whose data line isn't valid JSON are skipped defensively rather than
+ * crashing the stream.
+ */
+/** Parse a raw fetch Response body (ReadableStream) into a stream of parsed JSON event objects. */
+export declare function parseSSE(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Record<string, unknown>, void, unknown>;

package/dist/sse.js

@@ -0,0 +1,69 @@
+/**
+ * Minimal SSE parser for the Yesil Health stream.
+ *
+ * The server emits each event as:
+ *   event: <type>\n
+ *   data: {"type":"<type>", ...}\n
+ *   \n
+ *
+ * The `type` is carried both in the `event:` line and in the JSON body. We route
+ * on the JSON body's `type` (authoritative) and fall back to the `event:` line.
+ * Events whose data line isn't valid JSON are skipped defensively rather than
+ * crashing the stream.
+ */
+/** Parse a raw fetch Response body (ReadableStream) into a stream of parsed JSON event objects. */
+export async function* parseSSE(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            if (signal?.aborted)
+                throw new DOMException('Aborted', 'AbortError');
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Events are separated by a blank line. Drain every complete one.
+            let sep;
+            while ((sep = buffer.indexOf('\n\n')) !== -1) {
+                const rawEvent = buffer.slice(0, sep);
+                buffer = buffer.slice(sep + 2);
+                const parsed = parseEventBlock(rawEvent);
+                if (parsed)
+                    yield parsed;
+            }
+        }
+        // Flush any trailing event without a final blank line.
+        const tail = parseEventBlock(buffer);
+        if (tail)
+            yield tail;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+function parseEventBlock(block) {
+    let eventType;
+    const dataLines = [];
+    for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) {
+            eventType = line.slice(6).trim();
+        }
+        else if (line.startsWith('data:')) {
+            dataLines.push(line.slice(5).trim());
+        }
+    }
+    if (dataLines.length === 0)
+        return null;
+    try {
+        const obj = JSON.parse(dataLines.join('\n'));
+        // Body `type` is authoritative; fall back to the SSE event: line.
+        if (typeof obj.type !== 'string' && eventType)
+            obj.type = eventType;
+        return obj;
+    }
+    catch {
+        return null; // unparseable data line — skip, don't kill the stream
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Wire types for the Yesil Health enterprise (B2B) API — contract v1.
+ *
+ * Contract rule (server side): ADD only. The server may add new fields or new
+ * SSE event types at any time; it will never rename, remove, or retype an
+ * existing one without cutting a new major version (/api/v2). This client is
+ * written to honor that: unknown event types surface as `UnknownEvent` instead
+ * of throwing, and extra fields on known events are preserved.
+ */
+export interface ConversationTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/** Raw memory signal. Echoed back via the `memory_extracted` event so you can persist it. */
+export interface MemorySignal {
+    domain?: string;
+    kind?: string;
+    flag?: string;
+    tag?: string;
+    signal_date?: string;
+    [key: string]: unknown;
+}
+export interface ChatRequest {
+    /** The end-user's question. Required, non-empty. */
+    question: string;
+    /** Small structured profile object. Large EHR/wearable summaries go in `health_context`. */
+    demographics?: Record<string, unknown>;
+    /** Raw memory signals. Max items enforced server-side. */
+    memory?: MemorySignal[];
+    /** Last few turns only (max 8). Role must be user|assistant. */
+    conversation_history?: ConversationTurn[];
+    /** Pre-built free-form health context block (vitals, EHR summary, wearable rollups, etc.). */
+    health_context?: string;
+    /** Client-generated UUID v1-5 for idempotent billing. Strongly recommended. */
+    request_id?: string;
+    /** Optional hint; must match the tenant resolved from the API key. */
+    tenant_id?: string;
+}
+/** Stream lifecycle / phase marker. Also carries mid-stream research previews. */
+export interface MetaEvent {
+    type: 'meta';
+    phase?: string;
+    conversation_id?: string;
+    update_type?: string;
+    subtype?: string;
+    [key: string]: unknown;
+}
+/** A chunk of the answer text. Concatenate `content` across all deltas. */
+export interface DeltaEvent {
+    type: 'delta';
+    content: string;
+}
+/** A literature citation surfaced for the current answer. */
+export interface CitationEvent {
+    type: 'citation';
+    [key: string]: unknown;
+}
+/** A structured data graph (chart/diagram) payload, delivered out-of-band from text. */
+export interface GraphEvent {
+    type: 'graph';
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Memory signals the AI extracted from this turn — only emitted if your tenant
+ * has the `extract_memory` feature flag enabled. Persist these on your side and
+ * pass them back in `memory` on future requests.
+ */
+export interface MemoryExtractedEvent {
+    type: 'memory_extracted';
+    signals: MemorySignal[];
+}
+/** Terminal event. Carries the run summary (usage, research persist payload, etc.). */
+export interface DoneEvent {
+    type: 'done';
+    summary?: Record<string, unknown>;
+}
+/** Stream-level error. The stream ends after this. */
+export interface ErrorEvent {
+    type: 'error';
+    message: string;
+    code?: string;
+}
+/** Any event type this client version doesn't know about yet (forward-compatible). */
+export interface UnknownEvent {
+    type: string;
+    [key: string]: unknown;
+}
+export type ChatEvent = MetaEvent | DeltaEvent | CitationEvent | GraphEvent | MemoryExtractedEvent | DoneEvent | ErrorEvent | UnknownEvent;
+export interface BillingStatus {
+    [key: string]: unknown;
+}
+export interface QuotaStatus {
+    [key: string]: unknown;
+}
+export interface UsageReport {
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * Wire types for the Yesil Health enterprise (B2B) API — contract v1.
+ *
+ * Contract rule (server side): ADD only. The server may add new fields or new
+ * SSE event types at any time; it will never rename, remove, or retype an
+ * existing one without cutting a new major version (/api/v2). This client is
+ * written to honor that: unknown event types surface as `UnknownEvent` instead
+ * of throwing, and extra fields on known events are preserved.
+ */
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@yesilsci/health-ai-api",
+  "version": "0.1.0",
+  "description": "Official TypeScript client for the Yesil Health AI enterprise (B2B) API.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "example": "tsx examples/basic.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["yesil", "health", "ai", "sse", "medical"],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}