ailo.life 1.0.0

package/README.md

@@ -0,0 +1,89 @@
+# ailo.life
+
+Add verifiable AI outputs to your agent. Every call gets a tamper-proof verify code; recipients can verify at ailo.life/verify.
+
+## Install
+
+```bash
+npm install ailo.life
+```
+
+## Setup
+
+```ts
+// .env
+AILO_VERIFY_API_KEY=sk_xxx
+
+// agent.ts
+import { Verify } from 'ailo.life';
+
+const verify = Verify.init();
+```
+
+## Usage
+
+### Single-turn
+
+```ts
+export async function handleQuery(query: string) {
+  const { result, verifyCode } = await verify.trace('support', async (trace) => {
+    const response = await openai.chat.completions.create({ ... });
+    trace.llmCall({ model: 'gpt-4o', promptTokens: 150, completionTokens: 80 });
+    trace.toolCall('send_email', { to: 'user@example.com' });
+    return response.choices[0].message.content;
+  });
+
+  return result + '\n\n' + verify.embed(verifyCode);
+}
+```
+
+### Multi-turn (conversationId)
+
+```ts
+export async function handleTurn(conversationId: string, message: string) {
+  const { result, verifyCode } = await verify.trace('support', { conversationId }, async (trace) => {
+    // ... LLM + tool calls
+    return response;
+  });
+  return result + '\n\n' + verify.embed(verifyCode);
+}
+```
+
+### With customerId (optional)
+
+```ts
+const { result, verifyCode, sessionHash } = await verify.trace('support', {
+  conversationId: 'conv_abc',
+  customerId: 'cust_123',
+}, async (trace) => { ... });
+```
+
+## Verification
+
+- **Each call**: Has its own `verifyCode` (e.g. `100X2K9MPN`). Verify at ailo.life/verify?code=...
+- **Privacy**: Verify page shows only the verified event (not the full chain). Chain integrity is attested server-side. `sessionHash` for programmatic checks.
+
+## Testing & Publishing
+
+### Testing locally
+
+1. **Dry-run mode** — Use `Verify.init({ dryRun: true })` to skip API calls in tests:
+   ```ts
+   const verify = Verify.init({ dryRun: true });
+   const { result, verifyCode } = await verify.trace('test', async (trace) => {
+     trace.llmCall({ model: 'gpt-4o', promptTokens: 10, completionTokens: 5 });
+     return 'ok';
+   });
+   // verifyCode will be mock value like "100DRY0000"
+   ```
+
+2. **Link locally** — From the monorepo root: `cd packages/verify && npm link`. In your test app: `npm link ailo.life`.
+
+3. **Run build** — `cd packages/verify && npm run build` (runs `tsc`).
+
+### Publishing to npm
+
+1. **Login**: `npm login` (create account at npmjs.com if needed).
+2. **Version**: Bump in `package.json` or run `npm version patch|minor|major`.
+3. **Publish**: `cd packages/verify && npm publish`. For scoped packages, first publish: `npm publish --access public`.
+4. **Verify**: `npm view ailo.life` to confirm the package is live.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Ailo Verify SDK — Add verifiable AI outputs to your agent.
+ *
+ * Wrap your agent with trace() to mint verify codes. Embed codes in output
+ * so recipients can verify at ailo.life/verify.
+ */
+export interface TraceEvent {
+    type: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TraceOptions {
+    conversationId?: string;
+    customerId?: string;
+}
+export interface EmbedOptions {
+    /** Base URL for the verify link (default: SDK baseUrl) */
+    baseUrl?: string;
+    /** Output format: 'plain' | 'markdown' | 'html' */
+    format?: "plain" | "markdown" | "html";
+    /** Custom label text (default: "Verify") */
+    text?: string;
+}
+export interface InitOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    /** When true, skip API calls and return mock codes. Use in tests. */
+    dryRun?: boolean;
+}
+export interface IngestResponse {
+    verifyCodes: string[];
+    lastVerifyCode: string | null;
+    runVerifyCode?: string;
+    sessionHash: string | null;
+}
+export interface TraceResult<T> {
+    result: T;
+    verifyCodes: string[];
+    verifyCode: string | null;
+    runVerifyCode: string | null;
+    sessionHash: string | null;
+}
+/** Known error codes for programmatic handling */
+export declare const AiloVerifyErrorCode: {
+    readonly INVALID_API_KEY: "AILO_VERIFY_INVALID_API_KEY";
+    readonly REVOKED_API_KEY: "AILO_VERIFY_REVOKED_API_KEY";
+    readonly RATE_LIMITED: "AILO_VERIFY_RATE_LIMITED";
+    readonly NETWORK_ERROR: "AILO_VERIFY_NETWORK_ERROR";
+    readonly SERVER_ERROR: "AILO_VERIFY_SERVER_ERROR";
+};
+export declare class AiloVerifyError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(message: string, code: string, status?: number | undefined);
+}
+export declare class Verify {
+    private apiKey;
+    private baseUrl;
+    private dryRun;
+    private constructor();
+    static init(options?: InitOptions): Verify;
+    /**
+     * Wrap your agent function. Buffers events and POSTs to Ailo at the end.
+     * Returns { result, verifyCodes, verifyCode, runVerifyCode, sessionHash }.
+     */
+    trace<T>(_agentName: string, callbackOrOptions: TraceOptions | ((trace: Trace) => Promise<T>), callback?: (trace: Trace) => Promise<T>): Promise<TraceResult<T>>;
+    private postWithRetry;
+    private delay;
+    /**
+     * Return footer string for embedding in output.
+     * @param verifyCode - Use lastVerifyCode, runVerifyCode, or a specific event's code
+     * @param options - baseUrl, format ('plain' | 'markdown' | 'html'), text
+     */
+    embed(verifyCode: string | null, options?: EmbedOptions | string): string;
+}
+export interface Trace {
+    llmCall: (meta: {
+        model?: string;
+        promptTokens?: number;
+        completionTokens?: number;
+    }) => void;
+    toolCall: (name: string, meta?: Record<string, unknown>) => void;
+    agentResponse: (content: string | object) => void;
+    event: (type: string, content: string, meta?: Record<string, unknown>) => void;
+}

package/dist/index.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Ailo Verify SDK — Add verifiable AI outputs to your agent.
+ *
+ * Wrap your agent with trace() to mint verify codes. Embed codes in output
+ * so recipients can verify at ailo.life/verify.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Verify = exports.AiloVerifyError = exports.AiloVerifyErrorCode = void 0;
+const DEFAULT_BASE_URL = "https://ailo.life";
+/** Known error codes for programmatic handling */
+exports.AiloVerifyErrorCode = {
+    INVALID_API_KEY: "AILO_VERIFY_INVALID_API_KEY",
+    REVOKED_API_KEY: "AILO_VERIFY_REVOKED_API_KEY",
+    RATE_LIMITED: "AILO_VERIFY_RATE_LIMITED",
+    NETWORK_ERROR: "AILO_VERIFY_NETWORK_ERROR",
+    SERVER_ERROR: "AILO_VERIFY_SERVER_ERROR",
+};
+class AiloVerifyError extends Error {
+    constructor(message, code, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "AiloVerifyError";
+    }
+}
+exports.AiloVerifyError = AiloVerifyError;
+class Verify {
+    constructor(apiKey, baseUrl, dryRun) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.dryRun = dryRun;
+    }
+    static init(options) {
+        const env = typeof globalThis.process !== "undefined"
+            ? globalThis.process.env
+            : undefined;
+        const apiKey = options?.apiKey ?? env?.AILO_VERIFY_API_KEY ?? "";
+        const dryRun = options?.dryRun ?? false;
+        if (!dryRun && !apiKey) {
+            throw new Error("AILO_VERIFY_API_KEY is required. Set it in env or pass to init().");
+        }
+        return new Verify(apiKey || "dry-run", options?.baseUrl ?? DEFAULT_BASE_URL, dryRun);
+    }
+    /**
+     * Wrap your agent function. Buffers events and POSTs to Ailo at the end.
+     * Returns { result, verifyCodes, verifyCode, runVerifyCode, sessionHash }.
+     */
+    async trace(_agentName, callbackOrOptions, callback) {
+        const opts = typeof callbackOrOptions === "function" ? {} : callbackOrOptions ?? {};
+        const fn = typeof callbackOrOptions === "function" ? callbackOrOptions : callback;
+        if (!fn)
+            throw new Error("trace() requires a callback function");
+        const sessionId = (typeof crypto !== "undefined" && crypto.randomUUID?.()) ??
+            `sess_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+        const events = [];
+        const trace = {
+            llmCall: (meta) => {
+                events.push({
+                    type: "llm_call",
+                    content: meta.model ?? "unknown",
+                    metadata: meta,
+                });
+            },
+            toolCall: (name, meta) => {
+                events.push({
+                    type: "tool_call",
+                    content: name,
+                    metadata: meta,
+                });
+            },
+            agentResponse: (content) => {
+                events.push({
+                    type: "agent_response",
+                    content: typeof content === "string" ? content : JSON.stringify(content),
+                });
+            },
+            event: (type, content, meta) => {
+                events.push({ type, content, metadata: meta });
+            },
+        };
+        const result = await fn(trace);
+        let verifyCodes = [];
+        let verifyCode = null;
+        let runVerifyCode = null;
+        let sessionHash = null;
+        if (events.length > 0) {
+            if (this.dryRun) {
+                verifyCodes = events.map((_, i) => `100DRY${String(i).padStart(4, "0")}`);
+                verifyCode = verifyCodes[verifyCodes.length - 1] ?? null;
+                runVerifyCode = `100DRYRUN0`;
+                sessionHash = "dry-run-session-hash";
+            }
+            else {
+                const body = {
+                    sessionId,
+                    events,
+                };
+                if (opts.conversationId)
+                    body.conversationId = opts.conversationId;
+                if (opts.customerId)
+                    body.customerId = opts.customerId;
+                const data = await this.postWithRetry(body);
+                verifyCodes = data.verifyCodes ?? [];
+                verifyCode = data.lastVerifyCode ?? null;
+                runVerifyCode = data.runVerifyCode ?? null;
+                sessionHash = data.sessionHash ?? null;
+            }
+        }
+        return {
+            result,
+            verifyCodes,
+            verifyCode,
+            runVerifyCode,
+            sessionHash,
+        };
+    }
+    async postWithRetry(body, maxRetries = 2) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const res = await fetch(`${this.baseUrl}/api/verify/sdk/events`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify(body),
+                });
+                const data = (await res.json().catch(() => ({})));
+                if (!res.ok) {
+                    const msg = data.error ?? res.statusText;
+                    if (res.status === 401) {
+                        if (msg.toLowerCase().includes("revoked")) {
+                            throw new AiloVerifyError(msg, exports.AiloVerifyErrorCode.REVOKED_API_KEY, res.status);
+                        }
+                        throw new AiloVerifyError(msg, exports.AiloVerifyErrorCode.INVALID_API_KEY, res.status);
+                    }
+                    if (res.status === 429) {
+                        throw new AiloVerifyError(msg, exports.AiloVerifyErrorCode.RATE_LIMITED, res.status);
+                    }
+                    if (res.status >= 500 && attempt < maxRetries) {
+                        lastError = new AiloVerifyError(msg, exports.AiloVerifyErrorCode.SERVER_ERROR, res.status);
+                        await this.delay(500 * (attempt + 1));
+                        continue;
+                    }
+                    throw new AiloVerifyError(msg, exports.AiloVerifyErrorCode.SERVER_ERROR, res.status);
+                }
+                return data;
+            }
+            catch (err) {
+                if (err instanceof AiloVerifyError)
+                    throw err;
+                if (attempt < maxRetries) {
+                    lastError = err instanceof Error ? err : new Error(String(err));
+                    await this.delay(500 * (attempt + 1));
+                    continue;
+                }
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new AiloVerifyError(msg, exports.AiloVerifyErrorCode.NETWORK_ERROR);
+            }
+        }
+        throw lastError ?? new AiloVerifyError("Request failed", exports.AiloVerifyErrorCode.NETWORK_ERROR);
+    }
+    delay(ms) {
+        return new Promise((r) => setTimeout(r, ms));
+    }
+    /**
+     * Return footer string for embedding in output.
+     * @param verifyCode - Use lastVerifyCode, runVerifyCode, or a specific event's code
+     * @param options - baseUrl, format ('plain' | 'markdown' | 'html'), text
+     */
+    embed(verifyCode, options) {
+        if (!verifyCode)
+            return "";
+        const opts = typeof options === "string" ? { baseUrl: options } : options ?? {};
+        const url = opts.baseUrl ?? this.baseUrl;
+        const base = `${url}/api/verify?code=${encodeURIComponent(verifyCode)}`;
+        const text = opts.text ?? "Verify";
+        switch (opts.format) {
+            case "markdown":
+                return `[${text}](${base})`;
+            case "html":
+                return `<a href="${base}">${text}</a>`;
+            default:
+                return `${text}: ${base}`;
+        }
+    }
+}
+exports.Verify = Verify;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "ailo.life",
+  "version": "1.0.0",
+  "description": "Ailo Verify SDK — add verifiable AI outputs to your agent",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["ailo", "verify", "ai", "agent", "compliance"],
+  "author": "Ailo",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}