lyrenth-sdk 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# lyrenth-sdk (TypeScript / JavaScript)
+
+Read the web as clean **AIDocuments** through [Lyrenth](https://lyrenth.com),
+with a ready-made **Vercel AI SDK** tool.
+
+Each URL resolves to a stable AIDocument: cleaned Markdown plus title,
+description, and structure, with navigation and boilerplate stripped. Reads go
+through Lyrenth's cross-caller cache, and for verified domains you get the
+publisher's canonical version.
+
+## Install
+
+```sh
+npm install lyrenth-sdk
+```
+
+Get a free API key at <https://lyrenth.com/signup> and set `LYRENTH_API_KEY`.
+The core client has no dependencies (uses the platform `fetch`); the AI-SDK tool
+uses your existing `ai` and `zod`.
+
+## Client
+
+```ts
+import { Lyrenth } from "lyrenth-sdk";
+
+const lyrenth = new Lyrenth(); // reads LYRENTH_API_KEY from the environment
+const doc = await lyrenth.read("https://example.com/article");
+
+console.log(doc.title);
+console.log(doc.markdown);      // cleaned, agent-ready body
+console.log(doc.wordCount);
+console.log(doc.raw);           // full v2 envelope (structure, economics, ...)
+
+// just the text:
+const text = await lyrenth.readMarkdown("https://example.com/article");
+
+// force a fresh fetch instead of the cached copy:
+const fresh = await lyrenth.read("https://example.com/article", { fresh: true });
+```
+
+## Vercel AI SDK tool
+
+```ts
+import { generateText } from "ai";
+import { lyrenthReadTool } from "lyrenth-sdk/ai";
+
+const { text } = await generateText({
+  model: yourModel,
+  tools: { read_url: lyrenthReadTool() },
+  prompt: "Read https://example.com/article and summarize it.",
+});
+```
+
+The model can now call `read_url` to fetch any page as clean text instead of
+raw HTML. Pass your own configured client with `lyrenthReadTool(new Lyrenth({ apiKey }))`.
+
+Targets Vercel AI SDK **v3 / v4** (v5 renamed the tool schema field). The core
+`Lyrenth` client works with any version, wire it into a tool by hand if you are
+on v5.
+
+## Why read through Lyrenth
+
+- **Cleaner, cheaper.** One stable shape per URL, far fewer tokens than raw HTML.
+- **Cached across callers.** Repeat URLs collapse to a minimal number of origin
+  fetches, so it is fast and origin-friendly.
+- **Canonical when verified.** When a site's owner has verified with Lyrenth,
+  you get the version they authored, kept fresh by their change signal.
+
+## Config
+
+| Option / env | Default | Notes |
+|--------------|---------|-------|
+| `apiKey` / `LYRENTH_API_KEY` | none | Free key at <https://lyrenth.com/signup> |
+| `baseUrl` | `https://api.lyrenth.com` | Override for staging / self-host |
+
+The AIDocument format is an open contract; see
+<https://lyrenth.com/llms-full.txt>. MIT licensed.

package/dist/ai.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import { Lyrenth } from "./index.js";
+/**
+ * Build a Vercel AI SDK tool that reads a URL into a clean AIDocument.
+ * Pass your own configured `Lyrenth` client, or omit it to construct one from
+ * the `LYRENTH_API_KEY` environment variable.
+ */
+export declare function lyrenthReadTool(client?: Lyrenth): import("ai").Tool<z.ZodObject<{
+    url: z.ZodString;
+    fresh: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    fresh?: boolean | undefined;
+}, {
+    url: string;
+    fresh?: boolean | undefined;
+}>, {
+    url: string;
+    title: string;
+    description: string;
+    markdown: string;
+    wordCount: number;
+}> & {
+    execute: (args: {
+        url: string;
+        fresh?: boolean | undefined;
+    }, options: import("ai").ToolExecutionOptions) => PromiseLike<{
+        url: string;
+        title: string;
+        description: string;
+        markdown: string;
+        wordCount: number;
+    }>;
+};

package/dist/ai.js

@@ -0,0 +1,50 @@
+/**
+ * Vercel AI SDK tool backed by Lyrenth (subpath export: "lyrenth-sdk/ai").
+ *
+ *   import { generateText } from "ai";
+ *   import { lyrenthReadTool } from "lyrenth-sdk/ai";
+ *
+ *   const { text } = await generateText({
+ *     model: yourModel,
+ *     tools: { read_url: lyrenthReadTool() },
+ *     prompt: "Read https://example.com/article and summarize it.",
+ *   });
+ *
+ * Requires the `ai` (Vercel AI SDK v3 or v4) and `zod` peer dependencies. v5
+ * renamed the tool schema field, so this targets v3/v4; the core `Lyrenth`
+ * client in "lyrenth-sdk" works with any version (wire it in by hand).
+ */
+import { tool } from "ai";
+import { z } from "zod";
+import { Lyrenth } from "./index.js";
+/**
+ * Build a Vercel AI SDK tool that reads a URL into a clean AIDocument.
+ * Pass your own configured `Lyrenth` client, or omit it to construct one from
+ * the `LYRENTH_API_KEY` environment variable.
+ */
+export function lyrenthReadTool(client) {
+    const lyrenth = client ?? new Lyrenth();
+    return tool({
+        description: "Read any public web page as a clean AIDocument: Markdown plus title, " +
+            "description, and structure, with navigation and boilerplate stripped. " +
+            "Prefer this over a raw HTTP fetch whenever you need the content of a web " +
+            "page; it returns far cleaner, lower-token text. Powered by Lyrenth.",
+        parameters: z.object({
+            url: z.string().url().describe("Absolute http(s) URL of the page to read."),
+            fresh: z
+                .boolean()
+                .optional()
+                .describe("Force a fresh fetch instead of the cached version. Default false."),
+        }),
+        execute: async ({ url, fresh }) => {
+            const doc = await lyrenth.read(url, { fresh: fresh ?? false });
+            return {
+                url: doc.url,
+                title: doc.title,
+                description: doc.description,
+                markdown: doc.markdown,
+                wordCount: doc.wordCount,
+            };
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lyrenth TypeScript client: read the web as clean AIDocuments.
+ *
+ *   import { Lyrenth } from "lyrenth-sdk";
+ *
+ *   const lyrenth = new Lyrenth();              // reads LYRENTH_API_KEY from env
+ *   const doc = await lyrenth.read("https://example.com/article");
+ *   console.log(doc.title, doc.markdown);
+ *
+ * Free key: https://lyrenth.com/signup. No third-party dependencies (uses the
+ * platform `fetch`). The Vercel AI SDK tool lives in the "lyrenth-sdk/ai"
+ * subpath export.
+ */
+export interface AIDocument {
+    /** Canonical URL of the page (falls back to the requested URL). */
+    url: string;
+    title: string;
+    description: string;
+    /** The cleaned, agent-ready Markdown body. */
+    markdown: string;
+    wordCount: number;
+    /** The full v2 envelope (source, cache, structure, signals, economics). */
+    raw: Record<string, unknown>;
+}
+export interface LyrenthOptions {
+    /** API key (aiwk_...). Falls back to process.env.LYRENTH_API_KEY. */
+    apiKey?: string;
+    /** API base URL. Defaults to https://api.lyrenth.com. */
+    baseUrl?: string;
+}
+export declare class LyrenthError extends Error {
+    status?: number;
+    constructor(message: string, status?: number);
+}
+export declare class Lyrenth {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(opts?: LyrenthOptions);
+    /**
+     * Resolve a URL into a clean AIDocument via POST /v1/aidocument.
+     * Pass `{ fresh: true }` to force a live re-fetch instead of the cached copy.
+     */
+    read(url: string, opts?: {
+        fresh?: boolean;
+    }): Promise<AIDocument>;
+    /** Convenience: return just the cleaned Markdown body for a URL. */
+    readMarkdown(url: string, opts?: {
+        fresh?: boolean;
+    }): Promise<string>;
+}

package/dist/index.js

@@ -0,0 +1,80 @@
+/**
+ * Lyrenth TypeScript client: read the web as clean AIDocuments.
+ *
+ *   import { Lyrenth } from "lyrenth-sdk";
+ *
+ *   const lyrenth = new Lyrenth();              // reads LYRENTH_API_KEY from env
+ *   const doc = await lyrenth.read("https://example.com/article");
+ *   console.log(doc.title, doc.markdown);
+ *
+ * Free key: https://lyrenth.com/signup. No third-party dependencies (uses the
+ * platform `fetch`). The Vercel AI SDK tool lives in the "lyrenth-sdk/ai"
+ * subpath export.
+ */
+export class LyrenthError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "LyrenthError";
+        this.status = status;
+    }
+}
+const DEFAULT_BASE_URL = "https://api.lyrenth.com";
+export class Lyrenth {
+    apiKey;
+    baseUrl;
+    constructor(opts = {}) {
+        const envKey = typeof process !== "undefined" && process.env
+            ? process.env.LYRENTH_API_KEY ?? ""
+            : "";
+        this.apiKey = opts.apiKey ?? envKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    }
+    /**
+     * Resolve a URL into a clean AIDocument via POST /v1/aidocument.
+     * Pass `{ fresh: true }` to force a live re-fetch instead of the cached copy.
+     */
+    async read(url, opts = {}) {
+        if (!this.apiKey) {
+            throw new LyrenthError("no API key: pass { apiKey } or set LYRENTH_API_KEY (free key at https://lyrenth.com/signup)");
+        }
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}/v1/aidocument`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    url,
+                    freshness_policy: opts.fresh ? "force_refresh" : "cache_first",
+                }),
+            });
+        }
+        catch (e) {
+            throw new LyrenthError(`could not reach Lyrenth: ${e.message}`);
+        }
+        if (!res.ok) {
+            const detail = (await res.text().catch(() => "")).slice(0, 500);
+            throw new LyrenthError(`Lyrenth returned HTTP ${res.status}: ${detail}`.trim(), res.status);
+        }
+        const d = (await res.json());
+        const identity = d.identity ?? {};
+        const source = d.source ?? {};
+        const content = d.content ?? {};
+        const signals = d.signals ?? {};
+        return {
+            url: source.canonical_url || source.url || url,
+            title: identity.title ?? "",
+            description: identity.description ?? "",
+            markdown: content.markdown ?? "",
+            wordCount: Number(signals.word_count ?? 0),
+            raw: d,
+        };
+    }
+    /** Convenience: return just the cleaned Markdown body for a URL. */
+    async readMarkdown(url, opts = {}) {
+        return (await this.read(url, opts)).markdown;
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "lyrenth-sdk",
+  "version": "0.1.0",
+  "description": "Read the web as clean AIDocuments through Lyrenth, with a Vercel AI SDK tool.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./ai": {
+      "types": "./dist/ai.d.ts",
+      "import": "./dist/ai.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "lyrenth",
+    "aidocument",
+    "web",
+    "reader",
+    "agent",
+    "rag",
+    "llm",
+    "vercel",
+    "ai-sdk",
+    "tool"
+  ],
+  "homepage": "https://lyrenth.com",
+  "peerDependencies": {
+    "ai": "^3 || ^4",
+    "zod": "^3"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ai": "^4.0.0",
+    "typescript": "^5.5.0",
+    "zod": "^3.23.0"
+  }
+}