llms-ink 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Espindola
+
+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

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# llms-ink
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn any link — site, docs section, page, GitHub repo, PDF or video — into llms.txt and llms-full.txt. A typed
+client for the [llms.ink](https://llms.ink) API with no dependencies. Runs on Node 18+, Bun, Deno, Cloudflare
+Workers and browsers. Also a [Vite plugin, an Astro integration and middleware](#serve-llmstxt-from-your-site) that
+serve llms.txt from your own site.
+
+```sh
+npm install llms-ink        # or: bun add llms-ink
+deno add jsr:@lukax/llms-ink   # or: npx jsr add @lukax/llms-ink
+```
+
+```ts
+import { LlmsInk } from 'llms-ink'; // Deno/JSR: from 'jsr:@lukax/llms-ink'
+
+const ink = new LlmsInk();
+
+const index = await ink.llms('developers.cloudflare.com/kv/');            // llms.txt: an index of links
+const full = await ink.llms('github.com/honojs/hono', { mode: 'full' });  // llms-full.txt: the content
+console.log(full.title, full.tokens, full.text);
+
+const report = await ink.check('llmstxt.org'); // is a site's own llms.txt valid, do its links answer?
+console.log(report.found, report.summary, report.issues);
+```
+
+## API
+
+### `new LlmsInk({ key?, baseUrl?, fetch? })`
+
+- `key`: an API key (`lk_…`), sent as `Authorization: Bearer`. Defaults to the `LLMS_INK_KEY` environment
+  variable where there is one (Node, Bun, Deno with `--allow-env`). Without a key, requests are anonymous and
+  share the free limits. An invalid or revoked key throws `InvalidKeyError`; it never falls back to anonymous.
+- `baseUrl`: defaults to `LLMS_INK_API`, else `https://llms.ink`.
+- `fetch`: a `fetch` to use instead of the global one.
+
+### `ink.llms(url, { mode?, fresh?, native?, signal? })` → `Promise<Result>`
+
+`mode` is `'llms'` (default) or `'full'` (up to 20 pages inlined). `fresh: true` skips the cache and rebuilds
+(counts against the daily quota). `native: false` always generates the file and never returns the site's own
+llms.txt (by default a site's own file is returned as is, unless llms.ink generated it). The result:
+
+```ts
+{ url, kind, source, mode, title, text, tokens, pages, model, cached, generatedAt, media? }
+```
+
+`kind` is `site | section | page | repo | document | video`; `source` is `native` (the site publishes it) or
+`generated`. `media` is set for videos (duration, thumbnail, downloads, transcript segments).
+
+Building a big site or a video can take minutes. Bound a call with a signal:
+`ink.llms(url, { signal: AbortSignal.timeout(120_000) })`. Aborts are rethrown as is.
+
+### `ink.check(url, { signal? })` → `Promise<CheckResult>`
+
+Checks the site's (or docs section's) published llms.txt against the llmstxt.org format and fetches its first
+25 links: `{ site, url, found, status, title, tokens, sections, links, llmsFull, issues, summary, checkedAt }`.
+
+### `ink.stream(url, { mode?, fresh?, signal? })` → `AsyncGenerator<StreamEvent>`
+
+The same build as `llms()`, as it happens:
+
+```ts
+for await (const event of ink.stream('docs.astro.build', { mode: 'full' })) {
+  if (event.type === 'progress') console.log(event.stage, event.detail);
+  if (event.type === 'partial') preview(event.text); // incomplete so far
+  if (event.type === 'result') save(event.result);   // always last
+}
+```
+
+Breaking out of the loop cancels the request.
+
+## Serve llms.txt from your site
+
+### Vite: `llms-ink/vite`
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { llmsInk } from 'llms-ink/vite';
+
+export default defineConfig({ plugins: [llmsInk({ site: 'https://example.com', full: true })] });
+```
+
+After `vite build` (not the dev server or SSR builds), writes `llms.txt` (and `llms-full.txt` with `full`) for
+`site` into `build.outDir`. llms.ink reads the live site, so the files describe the previous deploy. If llms.ink
+fails, the plugin warns and keeps any existing file (e.g. one from `public/`); `strict: true` fails the build.
+Options: `site`, `full`, `key` (default `LLMS_INK_KEY`), `native` (default `true`; a file llms.ink generated before
+is regenerated, not echoed), `strict`, `timeout` (ms, default 300000), `baseUrl`.
+
+### Astro: `llms-ink/astro`
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import llmsInk from 'llms-ink/astro';
+
+export default defineConfig({ site: 'https://example.com', integrations: [llmsInk({ full: true })] });
+```
+
+The same, on `astro:build:done`, into the static output. `site` defaults to Astro's `site` plus `base`.
+
+### Middleware: `llms-ink/middleware`
+
+```ts
+import { llmsInkHandler, llmsInkExpress } from 'llms-ink/middleware';
+
+const llms = llmsInkHandler({ site: 'https://example.com', markdown: true });
+const response = (await llms(request)) ?? (await app(request)); // Workers, Next.js proxy, Deno, Bun, Hono
+
+expressApp.use(llmsInkExpress({ site: 'https://example.com' })); // Express, Connect
+```
+
+Answers `GET`/`HEAD` `/llms.txt` and `/llms-full.txt` from llms.ink, always generated (`native=0`, so it can't
+loop through itself), with llms.ink's `Cache-Control`. Each answer is kept in memory for its `max-age` and served as
+a last good copy (`Warning: 110`, `Cache-Control: max-age=60`) when llms.ink fails. With `markdown: true` it also
+answers `/<page>.md` and requests whose `Accept` prefers `text/markdown` over `text/html` with the page as Markdown.
+Everything else, and llms.ink's own fetcher, gets `undefined` (Express: `next()`). Options: `site`, `key` (default
+`LLMS_INK_KEY`; recommended on shared hosting IPs), `markdown`, `baseUrl`. Don't also ship a static `llms.txt`:
+most hosts serve it before the middleware runs.
+
+## Errors
+
+Every failure is an `LlmsInkError` with `status`, `code`, `title`, `detail`, `errors` (per-parameter issues of
+`invalid_request`) and `retryAfter` (seconds, from `Retry-After`). When llms.ink can't be reached, `status` and
+`code` are undefined and `cause` holds the network error. Codes are listed at
+[llms.ink/docs](https://llms.ink/docs/#errors).
+
+| Class | Status | Code | When |
+|---|---|---|---|
+| `InvalidKeyError` | 401 | `invalid_key` | The key is malformed, unknown or revoked. |
+| `RateLimitedError` | 429 | `rate_limited` | Too many requests this minute; wait `retryAfter` seconds. |
+| `QuotaExceededError` | 429 | `quota_exceeded` | Daily quota of new links used up; `retryAfter` is the seconds until midnight UTC. Cached links still work. |
+
+```ts
+import { LlmsInk, RateLimitedError } from 'llms-ink';
+
+try {
+  await ink.llms('example.com');
+} catch (err) {
+  if (err instanceof RateLimitedError) await new Promise((r) => setTimeout(r, err.retryAfter! * 1000));
+  else throw err;
+}
+```
+
+## Limits
+
+Anonymous: 10 requests a minute per IP, 60 new (uncached) links a day per IP. Cached results are free. A key
+gets its own daily quota (1000 new links by default) and 60 requests a minute;
+[ask for one](https://lucasespindola.com/message?text=Hi+Lucas%2C+I%E2%80%99d+like+an+llms.ink+API+key+for+...).
+
+## License
+
+MIT

package/dist/astro.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Astro integration: writes llms.txt (and llms-full.txt) from llms.ink into the build output.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import llmsInk from 'llms-ink/astro';
+ *
+ * export default defineConfig({ site: 'https://example.com', integrations: [llmsInk({ full: true })] });
+ * ```
+ *
+ * @module
+ */
+import type { AstroIntegration } from 'astro';
+import { type LlmsFilesOptions } from './files.ts';
+/** {@link LlmsFilesOptions} with `site` optional: it defaults to Astro's `site` (plus `base`). */
+export type LlmsInkAstroOptions = Omit<LlmsFilesOptions, 'site'> & {
+    site?: string;
+};
+/**
+ * After `astro build`, fetches llms.txt — and llms-full.txt with `full: true` — for `site` (default: the
+ * `site` and `base` of the Astro config) and writes them into the static output directory. llms.ink reads the
+ * live site, so the files describe the previous deploy. When llms.ink can't be reached it warns and keeps any
+ * existing file (e.g. one copied from `public/`); `strict: true` fails the build instead.
+ */
+export declare function llmsInk(options?: LlmsInkAstroOptions): AstroIntegration;
+export default llmsInk;

package/dist/astro.js

@@ -0,0 +1,39 @@
+/**
+ * Astro integration: writes llms.txt (and llms-full.txt) from llms.ink into the build output.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import llmsInk from 'llms-ink/astro';
+ *
+ * export default defineConfig({ site: 'https://example.com', integrations: [llmsInk({ full: true })] });
+ * ```
+ *
+ * @module
+ */
+import { fileURLToPath } from 'node:url';
+import { llmsFilesWriter } from "./files.js";
+/**
+ * After `astro build`, fetches llms.txt — and llms-full.txt with `full: true` — for `site` (default: the
+ * `site` and `base` of the Astro config) and writes them into the static output directory. llms.ink reads the
+ * live site, so the files describe the previous deploy. When llms.ink can't be reached it warns and keeps any
+ * existing file (e.g. one copied from `public/`); `strict: true` fails the build instead.
+ */
+export function llmsInk(options = {}) {
+    const settings = { ...options, site: options.site ?? '' };
+    const write = llmsFilesWriter(settings);
+    return {
+        name: 'llms-ink',
+        hooks: {
+            'astro:config:done': ({ config }) => {
+                if (!settings.site && config.site)
+                    settings.site = new URL(config.base, config.site).href;
+            },
+            'astro:build:done': async ({ dir, logger }) => {
+                await write(fileURLToPath(dir), logger);
+            },
+        },
+    };
+}
+export default llmsInk;

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+/** `process.env[name]` where there is a `process` (Node, Bun, Deno with env access); undefined elsewhere. */
+export declare function env(name: string): string | undefined;

package/dist/env.js

@@ -0,0 +1,11 @@
+/** `process.env[name]` where there is a `process` (Node, Bun, Deno with env access); undefined elsewhere. */
+export function env(name) {
+    // Read off globalThis, not a declared global, so it neither needs nor clashes with @types/node.
+    const scope = globalThis;
+    try {
+        return scope.process?.env?.[name]?.trim() || undefined;
+    }
+    catch {
+        return undefined; // Deno without --allow-env throws
+    }
+}

package/dist/files.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared by the Vite plugin and the Astro integration: fetch llms.txt (and llms-full.txt) for a site and write
+ * them into a build's output directory.
+ *
+ * @module
+ */
+/** Options for the Vite plugin and the Astro integration. */
+export interface LlmsFilesOptions {
+    /** The deployed site to describe, e.g. `https://example.com`. llms.ink reads the live site. */
+    site: string;
+    /** Also write llms-full.txt (the content of up to 20 pages). Default `false`. */
+    full?: boolean;
+    /** API key (`lk_…`). Defaults to the `LLMS_INK_KEY` environment variable; anonymous without one. */
+    key?: string;
+    /**
+     * Default `true`: when the live site publishes its own llms.txt, that file is used as is, unless it's one
+     * llms.ink generated before (it carries the llms.ink credit line), which is regenerated. `false` always
+     * generates (`native=0`).
+     */
+    native?: boolean;
+    /** Fail the build when a file can't be fetched. Default `false`: warn and keep any existing file. */
+    strict?: boolean;
+    /** Milliseconds to wait for llms.ink per file. Default 300000 (building a big site can take minutes). */
+    timeout?: number;
+    /** Defaults to the `LLMS_INK_API` environment variable, else https://llms.ink. */
+    baseUrl?: string;
+}
+/** Where messages go: Vite's or Astro's logger. */
+export interface Log {
+    info(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * A writer that fetches the files once and writes them into `dir` on every call (watch builds call it again;
+ * a failed fetch is retried on the next call).
+ */
+export declare function llmsFilesWriter(options: LlmsFilesOptions): (dir: string, log: Log) => Promise<void>;

package/dist/files.js

@@ -0,0 +1,52 @@
+/**
+ * Shared by the Vite plugin and the Astro integration: fetch llms.txt (and llms-full.txt) for a site and write
+ * them into a build's output directory.
+ *
+ * @module
+ */
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { LlmsInk } from "./index.js";
+const FILES = [['llms.txt', 'llms'], ['llms-full.txt', 'full']];
+/**
+ * A writer that fetches the files once and writes them into `dir` on every call (watch builds call it again;
+ * a failed fetch is retried on the next call).
+ */
+export function llmsFilesWriter(options) {
+    let fetched;
+    return async (dir, log) => {
+        const { site, strict = false } = options;
+        if (!site) {
+            const message = 'No `site` set: llms.txt not written.';
+            if (strict)
+                throw new Error(message);
+            return log.warn(message);
+        }
+        fetched ??= fetchFiles(options);
+        const results = await fetched;
+        const failures = [];
+        for (const result of results) {
+            const path = join(dir, result.name);
+            if ('text' in result) {
+                await mkdir(dir, { recursive: true });
+                await writeFile(path, result.text);
+                log.info(`Wrote ${result.name} for ${site} (${result.source}, ~${result.tokens} tokens).`);
+                continue;
+            }
+            const reason = result.error instanceof Error ? result.error.message : String(result.error);
+            const kept = await access(path).then(() => 'kept the existing file', () => 'none written');
+            failures.push(`Couldn't get ${result.name} for ${site}: ${reason} (${kept}).`);
+        }
+        if (failures.length)
+            fetched = undefined;
+        if (strict && failures.length)
+            throw new Error(failures.join(' '));
+        for (const message of failures)
+            log.warn(message);
+    };
+}
+async function fetchFiles({ site, full, key, native = true, timeout = 300_000, baseUrl }) {
+    const ink = new LlmsInk({ key, baseUrl });
+    const files = full ? FILES : FILES.slice(0, 1);
+    return Promise.all(files.map(([name, mode]) => ink.llms(site, { mode, native, signal: AbortSignal.timeout(timeout) }).then(({ text, tokens, source }) => ({ name, text, tokens, source }), (error) => ({ name, error }))));
+}

package/dist/index.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Client for the llms.ink JSON API (https://llms.ink/docs/): any public link — site, docs section, page,
+ * GitHub repo, PDF or video — as llms.txt or llms-full.txt. No dependencies; uses the global `fetch`, so it
+ * runs on Node ≥ 18, Bun, Deno, Cloudflare Workers and browsers.
+ *
+ * @example
+ * ```ts
+ * import { LlmsInk } from "llms-ink";
+ *
+ * const ink = new LlmsInk();
+ * const { title, text } = await ink.llms("developers.cloudflare.com/kv/", { mode: "full" });
+ * ```
+ *
+ * @module
+ */
+export declare const VERSION = "0.2.0";
+export declare const DEFAULT_BASE_URL = "https://llms.ink";
+/** `llms` for the index (llms.txt), `full` for llms-full.txt. */
+export type Mode = 'llms' | 'full';
+/** What the link is. */
+export type Kind = 'site' | 'section' | 'page' | 'repo' | 'document' | 'video';
+/** `native` = published by the site; `generated` = made by llms.ink. */
+export type Source = 'native' | 'generated';
+/** A transcript line; `start` and `end` are seconds into the source video. */
+export interface Segment {
+    start: number;
+    end: number;
+    text: string;
+}
+/** Video results only: what `/api/v0/frame` and `/api/v0/media` can serve. */
+export interface Media {
+    /** Seconds. */
+    duration: number | null;
+    hasVideo: boolean;
+    hasAudio: boolean;
+    thumbnail: string | null;
+    downloads: Array<'mp4' | 'm4a'>;
+    isLive?: boolean;
+    transcript?: {
+        source: string;
+        segments: Segment[];
+    };
+}
+/** `GET /api/v0/llms`: the llms.txt or llms-full.txt of a link and what it was built from. */
+export interface Result {
+    /** The link after normalization. */
+    url: string;
+    kind: Kind;
+    source: Source;
+    mode: Mode;
+    title: string;
+    /** The llms.txt or llms-full.txt content (Markdown). */
+    text: string;
+    /** Approximate token count (characters ÷ 4). */
+    tokens: number;
+    /** Links in llms.txt (mode `llms`) or pages inlined (mode `full`). */
+    pages: number;
+    /** Model that wrote the descriptions; null for native files or path-based grouping. */
+    model: string | null;
+    cached: boolean;
+    /** ISO 8601 date-time. */
+    generatedAt: string;
+    media?: Media;
+}
+/** One finding of the checker. */
+export interface CheckIssue {
+    /** `error` breaks the format or a link; `warning` is worth fixing; `info` is a note. */
+    level: 'error' | 'warning' | 'info';
+    /** Stable name of the check, e.g. `missing_title`, `broken_link`. */
+    code: string;
+    /** Line in the file, when the issue has one. */
+    line: number | null;
+    message: string;
+}
+/** `GET /api/v0/check`: a published llms.txt checked against the format and its links. */
+export interface CheckResult {
+    /** The site's origin. */
+    site: string;
+    /** The llms.txt that was checked (or the last place looked when none was found). */
+    url: string;
+    found: boolean;
+    /** HTTP status of the llms.txt request. */
+    status: number;
+    title: string | null;
+    tokens: number;
+    /** H2 sections. */
+    sections: number;
+    links: {
+        total: number;
+        /** Links fetched this run (the first 25). */
+        checked: number;
+        /** `status` is 0 when the link didn't answer in time. */
+        broken: Array<{
+            url: string;
+            status: number;
+        }>;
+    };
+    /** Whether llms-full.txt is published next to it. */
+    llmsFull: boolean;
+    /** Errors first, then warnings and notes, in line order. */
+    issues: CheckIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+    };
+    /** ISO 8601 date-time. */
+    checkedAt: string;
+}
+/** Every error code the API answers with (https://llms.ink/docs/#errors). */
+export type ErrorCode = 'invalid_request' | 'invalid_url' | 'invalid_key' | 'not_found' | 'unknown_version' | 'method_not_allowed' | 'payload_too_large' | 'unprocessable' | 'rate_limited' | 'quota_exceeded' | 'internal' | 'upstream_error' | 'unavailable' | 'timeout' | 'loop_detected';
+/** `invalid_request` only: one invalid parameter. */
+export interface Issue {
+    path: string;
+    message: string;
+}
+/** An error body (RFC 9457 problem details), sent as `application/problem+json`. */
+export interface Problem {
+    type: string;
+    title: string;
+    status: number;
+    code: ErrorCode;
+    detail: string;
+    errors?: Issue[];
+}
+/** Build stages reported while streaming. */
+export type Stage = 'cache' | 'index' | 'extract' | 'ready';
+/**
+ * One line of the `application/x-ndjson` stream of `GET /api/v0/llms`. `partial` text is explicitly
+ * incomplete; `result` is the last event. A terminal `error` event is thrown as an {@link LlmsInkError}.
+ */
+export type StreamEvent = {
+    type: 'progress';
+    stage: Stage;
+    detail: string;
+} | {
+    type: 'partial';
+    text: string;
+} | {
+    type: 'result';
+    result: Result;
+};
+/** Fields of an {@link LlmsInkError} besides the message. */
+export interface LlmsInkErrorInit {
+    status?: number;
+    code?: string;
+    title?: string;
+    errors?: Issue[];
+    retryAfter?: number;
+    cause?: unknown;
+}
+/**
+ * An API error, or llms.ink couldn't be reached (then `status` and `code` are undefined).
+ * `code` is the problem's machine-readable code (`invalid_url`, `unprocessable`, `upstream_error`…),
+ * `detail` the human-readable message, `errors` the per-parameter issues of `invalid_request`.
+ * `retryAfter` is the `Retry-After` header in seconds, when the response had one.
+ */
+export declare class LlmsInkError extends Error {
+    readonly detail: string;
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    readonly title: string | undefined;
+    readonly errors: Issue[];
+    readonly retryAfter: number | undefined;
+    constructor(detail: string, init?: LlmsInkErrorInit);
+}
+/** 401 `invalid_key`: the API key is malformed, unknown or revoked. Requests never fall back to anonymous. */
+export declare class InvalidKeyError extends LlmsInkError {
+}
+/** 429 `rate_limited`: too many requests this minute; wait `retryAfter` seconds. */
+export declare class RateLimitedError extends LlmsInkError {
+}
+/**
+ * 429 `quota_exceeded`: the daily quota of new links is used up; `retryAfter` is the seconds until it resets
+ * (midnight UTC). Cached links still work.
+ */
+export declare class QuotaExceededError extends LlmsInkError {
+}
+/** Options for {@link LlmsInk}. */
+export interface LlmsInkOptions {
+    /**
+     * API key (`lk_…`), sent as `Authorization: Bearer`. Defaults to the `LLMS_INK_KEY` environment variable
+     * where there is one; without a key, requests are anonymous and share the free limits.
+     */
+    key?: string;
+    /** Defaults to the `LLMS_INK_API` environment variable, else https://llms.ink. */
+    baseUrl?: string;
+    /** A `fetch` to use instead of the global one. */
+    fetch?: typeof fetch;
+}
+/** Options for {@link LlmsInk.llms} and {@link LlmsInk.stream}. */
+export interface LlmsOptions {
+    /** `llms` (default) for the index, `full` for llms-full.txt (the content inlined, up to 20 pages). */
+    mode?: Mode;
+    /** Skip the cache and rebuild (counts against the daily quota). */
+    fresh?: boolean;
+    /**
+     * `false` always generates the file from the site's pages and never returns the site's own llms.txt or
+     * llms-full.txt (`native=0`). Defaults to `true`: a site's own file is returned as is, unless it carries the
+     * llms.ink credit line (then it's regenerated).
+     */
+    native?: boolean;
+    /** Aborts the request; the abort error is rethrown as is. */
+    signal?: AbortSignal;
+}
+/** Options for {@link LlmsInk.check}. */
+export interface CheckOptions {
+    signal?: AbortSignal;
+}
+/**
+ * A client for https://llms.ink.
+ *
+ * Building a big site or a video can take minutes; pass a `signal` (e.g. `AbortSignal.timeout(300_000)`) to
+ * bound a call, or use {@link LlmsInk.stream} to watch progress.
+ */
+export declare class LlmsInk {
+    #private;
+    /** The API key in use, if any. */
+    readonly key: string | undefined;
+    /** Origin of the API, without a trailing slash. */
+    readonly baseUrl: string;
+    constructor(options?: LlmsInkOptions);
+    /**
+     * llms.txt (`mode: 'llms'`, an index of links) or llms-full.txt (`mode: 'full'`, the content inlined) for
+     * any public link.
+     */
+    llms(url: string, options?: LlmsOptions): Promise<Result>;
+    /** Checks a site's published llms.txt against the llmstxt.org format and that its links answer. */
+    check(url: string, options?: CheckOptions): Promise<CheckResult>;
+    /**
+     * Like {@link LlmsInk.llms}, as the build happens: yields `progress` and `partial` events, then one
+     * `result`. Errors — including a terminal `error` event — are thrown as {@link LlmsInkError}s.
+     * Breaking out of the loop cancels the request.
+     */
+    stream(url: string, options?: LlmsOptions): AsyncGenerator<StreamEvent, void, undefined>;
+}

package/dist/index.js

@@ -0,0 +1,237 @@
+/**
+ * Client for the llms.ink JSON API (https://llms.ink/docs/): any public link — site, docs section, page,
+ * GitHub repo, PDF or video — as llms.txt or llms-full.txt. No dependencies; uses the global `fetch`, so it
+ * runs on Node ≥ 18, Bun, Deno, Cloudflare Workers and browsers.
+ *
+ * @example
+ * ```ts
+ * import { LlmsInk } from "llms-ink";
+ *
+ * const ink = new LlmsInk();
+ * const { title, text } = await ink.llms("developers.cloudflare.com/kv/", { mode: "full" });
+ * ```
+ *
+ * @module
+ */
+import { env } from "./env.js";
+export const VERSION = '0.2.0';
+export const DEFAULT_BASE_URL = 'https://llms.ink';
+/**
+ * An API error, or llms.ink couldn't be reached (then `status` and `code` are undefined).
+ * `code` is the problem's machine-readable code (`invalid_url`, `unprocessable`, `upstream_error`…),
+ * `detail` the human-readable message, `errors` the per-parameter issues of `invalid_request`.
+ * `retryAfter` is the `Retry-After` header in seconds, when the response had one.
+ */
+export class LlmsInkError extends Error {
+    detail;
+    status;
+    code;
+    title;
+    errors;
+    retryAfter;
+    constructor(detail, init = {}) {
+        super(detail, init.cause === undefined ? undefined : { cause: init.cause });
+        this.name = new.target.name;
+        this.detail = detail;
+        this.status = init.status;
+        this.code = init.code;
+        this.title = init.title;
+        this.errors = init.errors ?? [];
+        this.retryAfter = init.retryAfter;
+    }
+}
+/** 401 `invalid_key`: the API key is malformed, unknown or revoked. Requests never fall back to anonymous. */
+export class InvalidKeyError extends LlmsInkError {
+}
+/** 429 `rate_limited`: too many requests this minute; wait `retryAfter` seconds. */
+export class RateLimitedError extends LlmsInkError {
+}
+/**
+ * 429 `quota_exceeded`: the daily quota of new links is used up; `retryAfter` is the seconds until it resets
+ * (midnight UTC). Cached links still work.
+ */
+export class QuotaExceededError extends LlmsInkError {
+}
+const BY_CODE = {
+    invalid_key: InvalidKeyError,
+    rate_limited: RateLimitedError,
+    quota_exceeded: QuotaExceededError,
+};
+const errorFor = (detail, init) => new (BY_CODE[init.code ?? ''] ?? LlmsInkError)(detail, init);
+/** Browsers refuse or preflight a custom User-Agent, so it's only sent from servers. */
+const IS_BROWSER = 'document' in globalThis || 'WorkerGlobalScope' in globalThis;
+/** `Retry-After` as seconds: delta-seconds, or an HTTP date turned into seconds from now. */
+function retryAfter(value) {
+    if (!value)
+        return undefined;
+    const v = value.trim();
+    if (/^\d+$/.test(v))
+        return Number(v);
+    const when = Date.parse(v);
+    return Number.isNaN(when) ? undefined : Math.max(0, Math.ceil((when - Date.now()) / 1000));
+}
+/** Aborts (`signal`, `AbortSignal.timeout`) are the caller's doing and pass through unwrapped. */
+const isAbort = (err) => err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError');
+/**
+ * A client for https://llms.ink.
+ *
+ * Building a big site or a video can take minutes; pass a `signal` (e.g. `AbortSignal.timeout(300_000)`) to
+ * bound a call, or use {@link LlmsInk.stream} to watch progress.
+ */
+export class LlmsInk {
+    /** The API key in use, if any. */
+    key;
+    /** Origin of the API, without a trailing slash. */
+    baseUrl;
+    #fetch;
+    constructor(options = {}) {
+        const key = (options.key ?? env('LLMS_INK_KEY'))?.trim();
+        this.key = key || undefined;
+        this.baseUrl = (options.baseUrl ?? env('LLMS_INK_API') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        if (!options.fetch && typeof globalThis.fetch !== 'function') {
+            throw new TypeError('No global fetch: use Node 18+ or pass options.fetch.');
+        }
+        // Wrapped so the global is called unbound-safe (browsers throw "Illegal invocation" otherwise).
+        this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    }
+    /**
+     * llms.txt (`mode: 'llms'`, an index of links) or llms-full.txt (`mode: 'full'`, the content inlined) for
+     * any public link.
+     */
+    async llms(url, options = {}) {
+        const res = await this.#get('/api/v0/llms', llmsParams(url, options), 'application/json', options.signal);
+        return (await this.#json(res));
+    }
+    /** Checks a site's published llms.txt against the llmstxt.org format and that its links answer. */
+    async check(url, options = {}) {
+        const res = await this.#get('/api/v0/check', { url }, 'application/json', options.signal);
+        return (await this.#json(res));
+    }
+    /**
+     * Like {@link LlmsInk.llms}, as the build happens: yields `progress` and `partial` events, then one
+     * `result`. Errors — including a terminal `error` event — are thrown as {@link LlmsInkError}s.
+     * Breaking out of the loop cancels the request.
+     */
+    async *stream(url, options = {}) {
+        const res = await this.#get('/api/v0/llms', llmsParams(url, options), 'application/x-ndjson', options.signal);
+        if (!res.headers.get('content-type')?.includes('ndjson')) {
+            yield { type: 'result', result: (await this.#json(res)) };
+            return;
+        }
+        if (!res.body)
+            throw new LlmsInkError(`${this.baseUrl} sent an empty stream.`, { status: res.status });
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let done = false;
+        try {
+            while (!done) {
+                let chunk;
+                try {
+                    chunk = await reader.read();
+                }
+                catch (err) {
+                    if (isAbort(err))
+                        throw err;
+                    throw new LlmsInkError(`The stream from ${this.baseUrl} broke off: ${err instanceof Error ? err.message : err}`, { cause: err });
+                }
+                done = chunk.done;
+                buffer += done ? decoder.decode() : decoder.decode(chunk.value, { stream: true });
+                const lines = buffer.split('\n');
+                buffer = done ? '' : lines.pop();
+                for (const line of lines) {
+                    const event = line.trim() ? this.#event(line) : undefined;
+                    if (!event)
+                        continue;
+                    yield event;
+                    if (event.type === 'result')
+                        return;
+                }
+            }
+        }
+        finally {
+            reader.cancel().catch(() => { });
+        }
+        throw new LlmsInkError(`The stream from ${this.baseUrl} ended without a result.`);
+    }
+    /** A stream line → its event; unknown event types (added later) are skipped, `error` is thrown. */
+    #event(line) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch (err) {
+            throw new LlmsInkError(`${this.baseUrl} sent a stream line that isn't JSON.`, { cause: err });
+        }
+        if (!event || typeof event !== 'object' || !('type' in event))
+            return undefined;
+        if (event.type === 'error') {
+            const { detail, code, status } = event;
+            throw errorFor(detail || 'The build failed.', { status, code });
+        }
+        // The server's own event shapes, by type.
+        const known = event.type === 'progress' || event.type === 'partial' || event.type === 'result';
+        return known ? event : undefined;
+    }
+    async #get(path, params, accept, signal) {
+        const headers = { accept };
+        if (!IS_BROWSER)
+            headers['user-agent'] = `llms-ink-js/${VERSION}`;
+        if (this.key)
+            headers.authorization = `Bearer ${this.key}`;
+        const target = `${this.baseUrl}${path}?${new URLSearchParams(params)}`;
+        let res;
+        try {
+            res = await this.#fetch(target, { headers, signal });
+        }
+        catch (err) {
+            if (isAbort(err))
+                throw err;
+            throw new LlmsInkError(`Couldn't reach ${this.baseUrl}: ${err instanceof Error ? err.message : err}`, { cause: err });
+        }
+        if (!res.ok)
+            throw await problem(res);
+        return res;
+    }
+    async #json(res) {
+        const body = await res.text();
+        try {
+            return JSON.parse(body);
+        }
+        catch (err) {
+            throw new LlmsInkError(`${this.baseUrl} answered with something other than JSON.`, { status: res.status, cause: err });
+        }
+    }
+}
+function llmsParams(url, { mode = 'llms', fresh, native = true }) {
+    if (mode !== 'llms' && mode !== 'full') {
+        throw new TypeError(`mode must be 'llms' (the index) or 'full' (llms-full.txt), not ${JSON.stringify(mode)}`);
+    }
+    const params = { url, mode };
+    if (fresh)
+        params.fresh = '1';
+    if (!native)
+        params.native = '0';
+    return params;
+}
+/** An HTTP error response → the typed error for its problem `code`. */
+async function problem(res) {
+    let data = {};
+    try {
+        const parsed = JSON.parse(await res.text());
+        if (parsed && typeof parsed === 'object')
+            data = parsed;
+    }
+    catch {
+        // not problem+json: fall back to the status line
+    }
+    const status = typeof data.status === 'number' ? data.status : res.status;
+    const detail = data.detail || data.title || `HTTP ${res.status} ${res.statusText || 'error'}`.trim();
+    return errorFor(detail, {
+        status,
+        code: data.code,
+        title: data.title,
+        errors: data.errors,
+        retryAfter: retryAfter(res.headers.get('retry-after')),
+    });
+}

package/dist/middleware.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Serve llms.txt, llms-full.txt and (optionally) Markdown versions of pages from llms.ink, inside your own app.
+ * A fetch-API handler for Cloudflare Workers, Next.js middleware, Deno, Bun and Hono, plus an Express/Connect
+ * adapter.
+ *
+ * @example
+ * ```ts
+ * import { llmsInkHandler } from 'llms-ink/middleware';
+ *
+ * const llms = llmsInkHandler({ site: 'https://example.com', markdown: true });
+ * export default {
+ *   async fetch(request: Request): Promise<Response> {
+ *     return (await llms(request)) ?? fetch(request); // undefined: not ours, the app answers
+ *   },
+ * };
+ * ```
+ *
+ * @module
+ */
+/** Options for {@link llmsInkHandler} and {@link llmsInkExpress}. */
+export interface LlmsInkHandlerOptions {
+    /** The deployed site to describe, e.g. `https://example.com`. */
+    site: string;
+    /**
+     * API key (`lk_…`), sent as `Authorization: Bearer`. Defaults to the `LLMS_INK_KEY` environment variable
+     * where there is one. Recommended: proxies on shared hosting IPs otherwise share the anonymous limits.
+     */
+    key?: string;
+    /**
+     * Also answer `<path>.md`, and page requests whose `Accept` prefers `text/markdown` over `text/html`, with the
+     * page as Markdown (`https://llms.ink/full/<page>`). Default `false`.
+     */
+    markdown?: boolean;
+    /** Defaults to the `LLMS_INK_API` environment variable, else https://llms.ink. */
+    baseUrl?: string;
+}
+/** A fetch-API handler: a `Response` for the requests it serves, `undefined` for everything else. */
+export type LlmsInkHandler = (request: Request) => Promise<Response | undefined>;
+/**
+ * Answers `GET`/`HEAD` `/llms.txt` and `/llms-full.txt` with llms.ink's generated files for `site`
+ * (`native=0`, so a site whose /llms.txt is this handler can't loop), and, with `markdown: true`, Markdown
+ * versions of pages. Responses keep llms.ink's `Cache-Control`; each one is kept in memory for its `max-age`
+ * and served as a last good copy (with `Warning: 110`) when llms.ink fails. Returns `undefined` for every
+ * other request, and for llms.ink's own fetcher.
+ */
+export declare function llmsInkHandler(options: LlmsInkHandlerOptions): LlmsInkHandler;
+/** Node's `IncomingMessage` (Express, Connect, plain `node:http`), as far as the adapter reads it. */
+export interface NodeRequest {
+    method?: string;
+    url?: string;
+    /** Express: the URL before mounting stripped a prefix. */
+    originalUrl?: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+/** Node's `ServerResponse`, as far as the adapter writes it. */
+export interface NodeResponse {
+    statusCode: number;
+    setHeader(name: string, value: string): unknown;
+    end(chunk: Uint8Array): unknown;
+}
+/** Express/Connect middleware: `next()` when the request isn't one {@link llmsInkHandler} serves. */
+export type NodeMiddleware = (req: NodeRequest, res: NodeResponse, next: (err?: unknown) => void) => void;
+/** {@link llmsInkHandler} as Express/Connect middleware: `app.use(llmsInkExpress({ site }))`. */
+export declare function llmsInkExpress(options: LlmsInkHandlerOptions): NodeMiddleware;

package/dist/middleware.js

@@ -0,0 +1,183 @@
+/**
+ * Serve llms.txt, llms-full.txt and (optionally) Markdown versions of pages from llms.ink, inside your own app.
+ * A fetch-API handler for Cloudflare Workers, Next.js middleware, Deno, Bun and Hono, plus an Express/Connect
+ * adapter.
+ *
+ * @example
+ * ```ts
+ * import { llmsInkHandler } from 'llms-ink/middleware';
+ *
+ * const llms = llmsInkHandler({ site: 'https://example.com', markdown: true });
+ * export default {
+ *   async fetch(request: Request): Promise<Response> {
+ *     return (await llms(request)) ?? fetch(request); // undefined: not ours, the app answers
+ *   },
+ * };
+ * ```
+ *
+ * @module
+ */
+import { env } from "./env.js";
+import { DEFAULT_BASE_URL, VERSION } from "./index.js";
+const FILES = { '/llms.txt': 'llms', '/llms-full.txt': 'full' };
+/** llms.ink's own fetcher (`compatible; llms.ink/0.1`): answering it from llms.ink would loop. */
+const LLMS_INK_FETCHER = /\bllms\.ink\/\d/;
+/** Response headers passed through from llms.ink. */
+const PASS = ['content-type', 'cache-control', 'x-llms-kind', 'x-llms-source', 'x-llms-tokens'];
+/** Pages kept in memory as last good copies; the oldest is dropped first. */
+const MAX_ENTRIES = 200;
+/** How long downstream caches may keep a stale copy served while llms.ink fails. */
+const STALE_CACHE_CONTROL = 'public, max-age=60';
+/**
+ * Answers `GET`/`HEAD` `/llms.txt` and `/llms-full.txt` with llms.ink's generated files for `site`
+ * (`native=0`, so a site whose /llms.txt is this handler can't loop), and, with `markdown: true`, Markdown
+ * versions of pages. Responses keep llms.ink's `Cache-Control`; each one is kept in memory for its `max-age`
+ * and served as a last good copy (with `Warning: 110`) when llms.ink fails. Returns `undefined` for every
+ * other request, and for llms.ink's own fetcher.
+ */
+export function llmsInkHandler(options) {
+    const base = (options.baseUrl ?? env('LLMS_INK_API') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const key = (options.key ?? env('LLMS_INK_KEY'))?.trim();
+    const site = new URL(/^https?:\/\//i.test(options.site) ? options.site : `https://${options.site}`);
+    const headers = { accept: 'text/plain', 'user-agent': `llms-ink-js/${VERSION}` };
+    if (key)
+        headers.authorization = `Bearer ${key}`;
+    const cache = new Map();
+    const pending = new Map();
+    /** Fetches `upstream`; on failure the last good copy, else llms.ink's error. */
+    async function refresh(upstream) {
+        const last = cache.get(upstream);
+        let res;
+        try {
+            res = await fetch(upstream, { headers });
+        }
+        catch (err) {
+            return last ? stale(last) : failure(502, 'upstream_error', `Couldn't reach llms.ink: ${err instanceof Error ? err.message : err}`);
+        }
+        // An older llms.ink without `format=text` answers JSON; never serve that as the file.
+        const isText = res.headers.get('content-type')?.startsWith('text/');
+        if (!res.ok || !isText) {
+            if (last) {
+                await res.body?.cancel();
+                return stale(last);
+            }
+            if (res.ok)
+                return failure(502, 'upstream_error', `llms.ink answered ${res.headers.get('content-type')}, not text.`);
+            return new Response(res.body, { status: res.status, headers: pick(res.headers, [...PASS, 'x-error-code', 'retry-after']) });
+        }
+        const maxAge = Number(/(?:^|,)\s*max-age=(\d+)/i.exec(res.headers.get('cache-control') ?? '')?.[1] ?? 0);
+        const entry = { body: await res.text(), headers: pick(res.headers, PASS), at: Date.now(), maxAge };
+        cache.delete(upstream);
+        cache.set(upstream, entry);
+        if (cache.size > MAX_ENTRIES)
+            cache.delete(cache.keys().next().value);
+        return fresh(entry);
+    }
+    async function serve(upstream) {
+        const hit = cache.get(upstream);
+        if (hit && Date.now() - hit.at < hit.maxAge * 1000)
+            return fresh(hit);
+        let loading = pending.get(upstream);
+        if (!loading) {
+            loading = refresh(upstream).finally(() => pending.delete(upstream));
+            pending.set(upstream, loading);
+        }
+        // Concurrent requests share one fetch; each gets its own copy of the body.
+        return (await loading).clone();
+    }
+    return async (request) => {
+        if (request.method !== 'GET' && request.method !== 'HEAD')
+            return undefined;
+        if (LLMS_INK_FETCHER.test(request.headers.get('user-agent') ?? ''))
+            return undefined;
+        const { pathname } = new URL(request.url);
+        const mode = FILES[pathname];
+        let response;
+        if (mode) {
+            const query = new URLSearchParams({ url: site.href, mode, native: '0', format: 'text' });
+            response = await serve(`${base}/api/v0/llms?${query}`);
+        }
+        else if (options.markdown && pathname.endsWith('.md')) {
+            const page = pathname.slice(0, -3).replace(/\/index$/, '/');
+            response = await serve(`${base}/full/${site.host}${page}`);
+        }
+        else if (options.markdown && isPage(pathname) && prefersMarkdown(request.headers.get('accept') ?? '')) {
+            response = await serve(`${base}/full/${site.host}${pathname}`);
+            response.headers.append('vary', 'Accept');
+        }
+        else {
+            return undefined;
+        }
+        return request.method === 'HEAD' ? new Response(null, response) : response;
+    };
+}
+/** {@link llmsInkHandler} as Express/Connect middleware: `app.use(llmsInkExpress({ site }))`. */
+export function llmsInkExpress(options) {
+    const handle = llmsInkHandler(options);
+    return (req, res, next) => {
+        const headers = new Headers();
+        for (const name of ['accept', 'user-agent']) {
+            const value = req.headers[name];
+            if (typeof value === 'string')
+                headers.set(name, value);
+        }
+        const request = new Request(new URL(req.originalUrl ?? req.url ?? '/', 'http://localhost'), { method: req.method, headers });
+        handle(request)
+            .then(async (response) => {
+            if (!response)
+                return next();
+            res.statusCode = response.status;
+            response.headers.forEach((value, name) => res.setHeader(name, value));
+            res.end(new Uint8Array(await response.arrayBuffer()));
+        })
+            .catch(next);
+    };
+}
+function pick(from, names) {
+    const to = new Headers();
+    for (const name of names) {
+        const value = from.get(name);
+        if (value !== null)
+            to.set(name, value);
+    }
+    return to;
+}
+function fresh(entry) {
+    const headers = new Headers(entry.headers);
+    headers.set('age', String(Math.floor((Date.now() - entry.at) / 1000)));
+    return new Response(entry.body, { headers });
+}
+function stale(entry) {
+    const response = fresh(entry);
+    response.headers.set('cache-control', STALE_CACHE_CONTROL);
+    response.headers.set('warning', '110 - "Response is Stale"');
+    return response;
+}
+function failure(status, code, detail) {
+    return new Response(`${detail}\n`, { status, headers: { 'content-type': 'text/plain; charset=utf-8', 'x-error-code': code } });
+}
+/** A page path: no file extension, or `.html`/`.htm`. */
+function isPage(pathname) {
+    const last = pathname.slice(pathname.lastIndexOf('/') + 1);
+    return !last.includes('.') || /\.html?$/i.test(last);
+}
+/**
+ * Whether `Accept` names `text/markdown` with a quality at least that of `text/html` (or, when `text/html`
+ * isn't listed, `text/*`, then `*\/*`). Browsers never list `text/markdown`, so they get the app.
+ */
+function prefersMarkdown(accept) {
+    let markdown = 0;
+    const html = {};
+    for (const part of accept.toLowerCase().split(',')) {
+        const [type = '', ...params] = part.split(';').map((s) => s.trim());
+        const q = params.find((p) => p.startsWith('q='));
+        const quality = q === undefined ? 1 : Number(q.slice(2));
+        if (!Number.isFinite(quality))
+            continue;
+        if (type === 'text/markdown' || type === 'text/x-markdown')
+            markdown = Math.max(markdown, quality);
+        else if (type === 'text/html' || type === 'text/*' || type === '*/*')
+            html[type] = Math.max(html[type] ?? 0, quality);
+    }
+    return markdown > 0 && markdown >= (html['text/html'] ?? html['text/*'] ?? html['*/*'] ?? 0);
+}

package/dist/vite.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Vite plugin: writes llms.txt (and llms-full.txt) from llms.ink into the build output.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { llmsInk } from 'llms-ink/vite';
+ *
+ * export default defineConfig({ plugins: [llmsInk({ site: 'https://example.com', full: true })] });
+ * ```
+ *
+ * @module
+ */
+import type { Plugin } from 'vite';
+import { type LlmsFilesOptions } from './files.ts';
+export type { LlmsFilesOptions };
+/**
+ * After `vite build` (not the dev server, not SSR builds), fetches llms.txt — and llms-full.txt with
+ * `full: true` — for `site` and writes them into `build.outDir`. llms.ink reads the live site, so the files
+ * describe the previous deploy. When llms.ink can't be reached it warns and keeps any existing file (e.g. one
+ * copied from `public/`); `strict: true` fails the build instead.
+ */
+export declare function llmsInk(options: LlmsFilesOptions): Plugin;
+export default llmsInk;

package/dist/vite.js

@@ -0,0 +1,47 @@
+/**
+ * Vite plugin: writes llms.txt (and llms-full.txt) from llms.ink into the build output.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { llmsInk } from 'llms-ink/vite';
+ *
+ * export default defineConfig({ plugins: [llmsInk({ site: 'https://example.com', full: true })] });
+ * ```
+ *
+ * @module
+ */
+import { resolve } from 'node:path';
+import { llmsFilesWriter } from "./files.js";
+/**
+ * After `vite build` (not the dev server, not SSR builds), fetches llms.txt — and llms-full.txt with
+ * `full: true` — for `site` and writes them into `build.outDir`. llms.ink reads the live site, so the files
+ * describe the previous deploy. When llms.ink can't be reached it warns and keeps any existing file (e.g. one
+ * copied from `public/`); `strict: true` fails the build instead.
+ */
+export function llmsInk(options) {
+    const write = llmsFilesWriter(options);
+    let config;
+    return {
+        name: 'llms-ink',
+        apply: 'build',
+        configResolved(resolved) {
+            config = resolved;
+        },
+        async closeBundle(error) {
+            if (error)
+                return;
+            // Vite 6+ runs the hook once per environment; only the browser build is served as static files.
+            const environment = this.environment;
+            if (environment ? environment.name !== 'client' : config.build.ssr)
+                return;
+            const { outDir } = environment ? environment.config.build : config.build;
+            await write(resolve(config.root, outDir), {
+                info: (message) => config.logger.info(`[llms-ink] ${message}`),
+                warn: (message) => config.logger.warn(`[llms-ink] ${message}`),
+            });
+        },
+    };
+}
+export default llmsInk;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "llms-ink",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Turn any link — site, docs section, page, GitHub repo, PDF or video — into llms.txt and llms-full.txt. Typed client for llms.ink, plus a Vite plugin, an Astro integration and middleware that serve the files from your site. No dependencies.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "default": "./dist/astro.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "default": "./dist/middleware.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "npm run build && node --test test/client.test.mjs test/plugins.test.mjs test/middleware.test.mjs",
+    "test:live": "npm run build && node --test test/live.test.mjs",
+    "test:bun": "npm run build && bun test ./test/client.test.mjs ./test/plugins.test.mjs ./test/middleware.test.mjs",
+    "test:bun:live": "npm run build && bun test --timeout 300000 ./test/live.test.mjs"
+  },
+  "keywords": ["llms.txt", "llms-full.txt", "llm", "ai", "markdown", "docs", "context", "rag", "sdk", "llms-ink", "vite-plugin", "astro-integration", "middleware"],
+  "homepage": "https://llms.ink/docs/",
+  "author": "Lucas Espindola (https://lucasespindola.com)",
+  "license": "MIT",
+  "peerDependencies": {
+    "astro": ">=4",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "astro": { "optional": true },
+    "vite": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "astro": "^7.4.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.3.8"
+  }
+}