@xeroml/sdk 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @xeroml/sdk
+
+Official TypeScript SDK for the XeroML API.
+
+## Install
+
+```bash
+npm install @xeroml/sdk
+```
+
+## Usage
+
+```typescript
+import { XeroML } from "@xeroml/sdk";
+
+const client = new XeroML({ apiKey: "xml_..." });
+
+const result = await client.classify({
+  text: "I want to cancel my subscription",
+});
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm build         # compile
+pnpm typecheck     # type check
+pnpm test          # run tests
+```

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import { Session } from "./session";
+import type { IntentGraph, ParseOptions, SessionListItem, UsageInfo, XeroMLConfig } from "./types";
+export declare class XeroML {
+    private readonly baseURL;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(config: XeroMLConfig);
+    /**
+     * One-shot parse — no session. Costs 1 credit.
+     */
+    parse(message: string, options?: ParseOptions): Promise<IntentGraph>;
+    /**
+     * Create a new multi-turn session. Free.
+     */
+    createSession(options?: {
+        sessionId?: string;
+    }): Promise<Session>;
+    /**
+     * List all sessions for the authenticated API key.
+     */
+    listSessions(limit?: number): Promise<SessionListItem[]>;
+    /**
+     * Get credit balance and usage stats. Free.
+     */
+    getUsage(): Promise<UsageInfo>;
+    /**
+     * Internal HTTP helper. Exposed for Session to call.
+     * @internal
+     */
+    request<T>(method: string, path: string, body: Record<string, unknown> | null): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,96 @@
+// @xeroml/sdk — XeroML client class
+import { mapError } from "./errors";
+import { Session } from "./session";
+const DEFAULT_BASE_URL = "https://api.xeroml.com";
+const DEFAULT_TIMEOUT = 30_000;
+export class XeroML {
+    baseURL;
+    apiKey;
+    timeout;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("XeroML: apiKey is required.");
+        }
+        this.apiKey = config.apiKey;
+        this.baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    }
+    /**
+     * One-shot parse — no session. Costs 1 credit.
+     */
+    async parse(message, options) {
+        const body = { message };
+        if (options?.provider)
+            body.provider = options.provider;
+        const res = await this.request("POST", "/v1/parse", body);
+        return res.graph;
+    }
+    /**
+     * Create a new multi-turn session. Free.
+     */
+    async createSession(options) {
+        const body = {};
+        if (options?.sessionId)
+            body.session_id = options.sessionId;
+        const res = await this.request("POST", "/v1/sessions", body);
+        return new Session(this, res.session_id);
+    }
+    /**
+     * List all sessions for the authenticated API key.
+     */
+    async listSessions(limit) {
+        const query = limit ? `?limit=${limit}` : "";
+        const res = await this.request("GET", `/v1/sessions${query}`, null);
+        return res.sessions;
+    }
+    /**
+     * Get credit balance and usage stats. Free.
+     */
+    async getUsage() {
+        return this.request("GET", "/v1/usage", null);
+    }
+    /**
+     * Internal HTTP helper. Exposed for Session to call.
+     * @internal
+     */
+    async request(method, path, body) {
+        const url = `${this.baseURL}${path}`;
+        const headers = {
+            "X-API-Key": this.apiKey,
+        };
+        if (body !== null) {
+            headers["Content-Type"] = "application/json";
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(url, {
+                method,
+                headers,
+                body: body !== null ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                let errorBody;
+                try {
+                    errorBody = await res.json();
+                }
+                catch {
+                    errorBody = { error: { message: res.statusText } };
+                }
+                const retryAfter = res.headers.get("Retry-After");
+                throw mapError(res.status, errorBody, retryAfter ? parseInt(retryAfter, 10) : undefined);
+            }
+            return (await res.json());
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw mapError(504, { error: { code: "timeout", message: "Request timed out." } });
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+export interface ErrorBody {
+    error?: {
+        code?: string;
+        message?: string;
+        status?: number;
+        request_id?: string;
+        details?: Record<string, unknown>;
+    };
+}
+export declare class XeroMLError extends Error {
+    code: string;
+    status: number;
+    requestId: string;
+    details?: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, requestId?: string, details?: Record<string, unknown>);
+}
+export declare class XeroMLAuthError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLCreditError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLRateLimitError extends XeroMLError {
+    retryAfter: number;
+    constructor(body: ErrorBody, retryAfter?: number);
+}
+export declare class XeroMLValidationError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLParseError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLNotFoundError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLSessionEndedError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLTimeoutError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+export declare class XeroMLServerError extends XeroMLError {
+    constructor(body: ErrorBody);
+}
+/**
+ * Maps an HTTP error response to a typed XeroMLError.
+ */
+export declare function mapError(status: number, body: ErrorBody, retryAfter?: number): XeroMLError;

package/dist/errors.js

@@ -0,0 +1,96 @@
+// @xeroml/sdk — Error classes matching API error codes
+export class XeroMLError extends Error {
+    code;
+    status;
+    requestId;
+    details;
+    constructor(status, code, message, requestId, details) {
+        super(message);
+        this.name = "XeroMLError";
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId ?? "";
+        this.details = details;
+    }
+}
+export class XeroMLAuthError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(401, err?.code ?? "invalid_api_key", err?.message ?? "Invalid or revoked API key.", err?.request_id, err?.details);
+        this.name = "XeroMLAuthError";
+    }
+}
+export class XeroMLCreditError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(402, err?.code ?? "credits_exhausted", err?.message ?? "Credits exhausted.", err?.request_id, err?.details);
+        this.name = "XeroMLCreditError";
+    }
+}
+export class XeroMLRateLimitError extends XeroMLError {
+    retryAfter;
+    constructor(body, retryAfter) {
+        const err = body.error;
+        super(429, err?.code ?? "rate_limited", err?.message ?? "Rate limit exceeded.", err?.request_id, err?.details);
+        this.name = "XeroMLRateLimitError";
+        this.retryAfter = retryAfter ?? 60;
+    }
+}
+export class XeroMLValidationError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(400, err?.code ?? "invalid_input", err?.message ?? "Invalid input.", err?.request_id, err?.details);
+        this.name = "XeroMLValidationError";
+    }
+}
+export class XeroMLParseError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(422, err?.code ?? "parse_failed", err?.message ?? "Parse failed.", err?.request_id, err?.details);
+        this.name = "XeroMLParseError";
+    }
+}
+export class XeroMLNotFoundError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(404, err?.code ?? "session_not_found", err?.message ?? "Session not found.", err?.request_id, err?.details);
+        this.name = "XeroMLNotFoundError";
+    }
+}
+export class XeroMLSessionEndedError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(409, err?.code ?? "session_ended", err?.message ?? "Session already ended.", err?.request_id, err?.details);
+        this.name = "XeroMLSessionEndedError";
+    }
+}
+export class XeroMLTimeoutError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(504, err?.code ?? "timeout", err?.message ?? "Request timed out.", err?.request_id, err?.details);
+        this.name = "XeroMLTimeoutError";
+    }
+}
+export class XeroMLServerError extends XeroMLError {
+    constructor(body) {
+        const err = body.error;
+        super(err?.status ?? 500, err?.code ?? "internal_error", err?.message ?? "Internal server error.", err?.request_id, err?.details);
+        this.name = "XeroMLServerError";
+    }
+}
+/**
+ * Maps an HTTP error response to a typed XeroMLError.
+ */
+export function mapError(status, body, retryAfter) {
+    switch (status) {
+        case 401: return new XeroMLAuthError(body);
+        case 402: return new XeroMLCreditError(body);
+        case 429: return new XeroMLRateLimitError(body, retryAfter);
+        case 400: return new XeroMLValidationError(body);
+        case 422: return new XeroMLParseError(body);
+        case 404: return new XeroMLNotFoundError(body);
+        case 409: return new XeroMLSessionEndedError(body);
+        case 504: return new XeroMLTimeoutError(body);
+        default: return new XeroMLServerError(body);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { XeroML } from "./client";
+export { Session } from "./session";
+export type { IntentGraph, SubGoal, IntentMeta, LatentStates, DriftReport, ParseResponse, SessionParseResponse, SessionInfo, SessionListItem, SessionGraphResponse, UsageInfo, UsageMonth, XeroMLConfig, ParseOptions, UpdateOptions, } from "./types";
+export { XeroMLError, XeroMLAuthError, XeroMLCreditError, XeroMLRateLimitError, XeroMLValidationError, XeroMLParseError, XeroMLNotFoundError, XeroMLSessionEndedError, XeroMLTimeoutError, XeroMLServerError, mapError, } from "./errors";
+export type { ErrorBody } from "./errors";

package/dist/index.js

@@ -0,0 +1,5 @@
+// @xeroml/sdk — entry point
+export { XeroML } from "./client";
+export { Session } from "./session";
+// Errors
+export { XeroMLError, XeroMLAuthError, XeroMLCreditError, XeroMLRateLimitError, XeroMLValidationError, XeroMLParseError, XeroMLNotFoundError, XeroMLSessionEndedError, XeroMLTimeoutError, XeroMLServerError, mapError, } from "./errors";

package/dist/session.d.ts

@@ -0,0 +1,28 @@
+import type { XeroML } from "./client";
+import type { DriftReport, IntentGraph, ParseOptions, UpdateOptions } from "./types";
+export declare class Session {
+    private client;
+    readonly sessionId: string;
+    /** @internal — use `xeroml.createSession()` instead. */
+    constructor(client: XeroML, sessionId: string);
+    /**
+     * Parse a user message within this session. Costs 1 credit.
+     */
+    parse(message: string, options?: ParseOptions): Promise<IntentGraph>;
+    /**
+     * Feed an LLM response back into the session for drift tracking. Free.
+     */
+    update(message: string, options?: UpdateOptions): Promise<void>;
+    /**
+     * Check if intent drift has occurred. Free.
+     */
+    checkDrift(): Promise<DriftReport>;
+    /**
+     * Get the current IntentGraph snapshot. Free.
+     */
+    getGraph(): Promise<IntentGraph | null>;
+    /**
+     * End this session. Free.
+     */
+    end(): Promise<void>;
+}

package/dist/session.js

@@ -0,0 +1,48 @@
+// @xeroml/sdk — Session class for multi-turn conversations
+export class Session {
+    client;
+    sessionId;
+    /** @internal — use `xeroml.createSession()` instead. */
+    constructor(client, sessionId) {
+        this.client = client;
+        this.sessionId = sessionId;
+    }
+    /**
+     * Parse a user message within this session. Costs 1 credit.
+     */
+    async parse(message, options) {
+        const body = { message };
+        if (options?.provider)
+            body.provider = options.provider;
+        const res = await this.client.request("POST", `/v1/sessions/${this.sessionId}/parse`, body);
+        return res.graph;
+    }
+    /**
+     * Feed an LLM response back into the session for drift tracking. Free.
+     */
+    async update(message, options) {
+        const body = { message };
+        if (options?.role)
+            body.role = options.role;
+        await this.client.request("POST", `/v1/sessions/${this.sessionId}/update`, body);
+    }
+    /**
+     * Check if intent drift has occurred. Free.
+     */
+    async checkDrift() {
+        return this.client.request("GET", `/v1/sessions/${this.sessionId}/drift`, null);
+    }
+    /**
+     * Get the current IntentGraph snapshot. Free.
+     */
+    async getGraph() {
+        const res = await this.client.request("GET", `/v1/sessions/${this.sessionId}/graph`, null);
+        return res.graph;
+    }
+    /**
+     * End this session. Free.
+     */
+    async end() {
+        await this.client.request("POST", `/v1/sessions/${this.sessionId}/end`, {});
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+export interface LatentStates {
+    goal_intent: string;
+    action_readiness: "exploring" | "deciding" | "executing";
+    ambiguity_level: "clear" | "partial" | "conflicting";
+    risk_sensitivity: "low" | "medium" | "high";
+    intent_scope: "single" | "compound" | "multi_step";
+}
+export interface IntentMeta {
+    source: string;
+    confidence: number;
+    negotiation_history: string[];
+    latent_states: LatentStates;
+}
+export interface SubGoal {
+    id: string;
+    goal: string;
+    status: "pending" | "active" | "done" | "blocked" | "abandoned" | "background";
+    priority: number;
+    success_criteria: string[];
+    constraints: string[];
+    uncertainty: number;
+    context_requirements: string[];
+    modality: string;
+    dependencies: string[];
+    children: SubGoal[];
+}
+export interface IntentGraph {
+    schema_version: string;
+    root_goal: string;
+    sub_goals: SubGoal[];
+    meta: IntentMeta;
+}
+export interface DriftReport {
+    detected: boolean;
+    drift_type: string | null;
+    severity: number;
+    description: string;
+    previous_goal: string | null;
+    current_goal: string | null;
+}
+export interface ParseResponse {
+    graph: IntentGraph;
+    session_id?: string | null;
+    request_id: string;
+    latency_ms: number;
+}
+export interface SessionParseResponse {
+    graph: IntentGraph;
+    session_id: string;
+    turn_number: number;
+    request_id: string;
+    latency_ms: number;
+}
+export interface SessionInfo {
+    session_id: string;
+    status: string;
+    created_at: string;
+}
+export interface SessionListItem {
+    session_id: string;
+    status: string;
+    turn_count: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface SessionListResponse {
+    sessions: SessionListItem[];
+}
+export interface SessionGraphResponse {
+    graph: IntentGraph | null;
+    session_id: string;
+    turn_count: number;
+}
+export interface UsageMonth {
+    month: string;
+    parse_calls: number;
+    drift_checks: number;
+    session_creates: number;
+}
+export interface UsageInfo {
+    credits: {
+        used: number;
+        total: number;
+        remaining: number;
+    };
+    tier: string;
+    rate_limit: number;
+    usage: UsageMonth[];
+}
+export interface XeroMLConfig {
+    apiKey: string;
+    baseURL?: string;
+    timeout?: number;
+}
+export interface ParseOptions {
+    provider?: string;
+}
+export interface UpdateOptions {
+    role?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// @xeroml/sdk — TypeScript types matching API Pydantic models exactly
+export {};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xeroml/sdk",
+  "version": "0.1.0",
+  "description": "XeroML TypeScript SDK — intent parsing and drift detection for AI apps",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "lint": "echo 'no lint configured yet'",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Intensee/xeroml-sdk-typescript"
+  }
+}