llms-ink 0.4.0 → 0.5.0

package/README.md

@@ -211,3 +211,27 @@ gets its own daily quota (1000 new links by default) and 60 requests a minute;
 ## License
 
 MIT
+
+## Hosted Inspect (experimental, 0.5.0)
+
+```ts
+// Server-side; requires llms-ink >=0.5.0.
+import { LlmsInk } from 'llms-ink';
+
+const ink = new LlmsInk({ key: process.env.LLMS_INK_INSPECT_KEY });
+const receipt = await ink.inspect('Install the package and read the documentation.');
+if (receipt.recommendation !== 'continue') {
+  throw new Error(`Withhold content: ${receipt.detection}`);
+}
+console.log(receipt.contentDigest);
+```
+
+Requires an inspection-enabled pilot key. This call uploads only the supplied text to llms.ink; existing retrieval calls, loaders, plugins and the local guard do not opt in automatically. Keep the key server-side.
+
+The client checks the exact UTF-8 SHA-256 digest, model/policy/preprocessing revisions, coverage and token counts before returning an immutable receipt. A flagged result can use HTTP 200; incomplete 422/503 receipts return `unknown`. HTTP problems and invalid receipts raise an error. Withhold on either `withhold` or any exception. `no_finding` is not a safety guarantee, and receipts are unsigned.
+
+Requests are limited to 128 KiB after JSON encoding and responses to 16 KiB. There are no automatic retries: admitted attempts consume pilot allowance even when incomplete. Redirects are refused. Inspection ignores `LLMS_INK_API`; an explicit client base URL may select an HTTPS endpoint or localhost for development. The key follows that explicitly configured endpoint.
+
+For JSON, serialize it yourself and pass the resulting string to `inspect()`. The SDK sends `format: "text"`, so its digest covers those exact bytes; it does not promise cross-language JSON canonicalization. See [pilot limits and privacy](https://llms.ink/inspect/).
+
+JavaScript uses a 65-second total request deadline; pass `{ signal }` to cancel earlier.

package/dist/index.d.ts

@@ -13,7 +13,9 @@
  *
  * @module
  */
-export declare const VERSION = "0.4.0";
+import { type InspectionReceipt } from './inspect.ts';
+export type { InspectionReceipt } from './inspect.ts';
+export declare const VERSION = "0.5.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';
@@ -137,7 +139,7 @@ export interface CheckResult {
     checkedAt: string;
 }
 /** Every error code the API answers with (https://llms.ink/docs/#errors). */
-export type ErrorCode = 'invalid_request' | 'invalid_url' | 'invalid_key' | 'key_required' | 'site_claimed' | 'not_found' | 'unknown_version' | 'method_not_allowed' | 'payload_too_large' | 'too_large' | 'unsupported_media_type' | 'unprocessable' | 'rate_limited' | 'quota_exceeded' | 'internal' | 'upstream_error' | 'unavailable' | 'timeout' | 'loop_detected';
+export type ErrorCode = 'inspection_not_enabled' | 'inspection_quota' | 'inspection_unavailable' | 'invalid_request' | 'invalid_url' | 'invalid_key' | 'key_required' | 'site_claimed' | 'not_found' | 'unknown_version' | 'method_not_allowed' | 'payload_too_large' | 'too_large' | 'unsupported_media_type' | 'unprocessable' | 'rate_limited' | 'quota_exceeded' | 'internal' | 'upstream_error' | 'unavailable' | 'timeout' | 'loop_detected';
 /** `invalid_request` only: one invalid parameter. */
 export interface Issue {
     path: string;
@@ -268,6 +270,15 @@ export declare class LlmsInk {
      * any public link.
      */
     llms(url: string, options?: LlmsOptions): Promise<Result>;
+    /**
+     * Explicitly upload supplied text to the hosted Inspect pilot. Requires an enabled key.
+     * The receipt binds to these exact UTF-8 bytes; no finding is not a safety guarantee.
+     * No retries. 65-second default deadline. LLMS_INK_API is ignored; baseUrl must be explicit.
+     * Keep keys server-side. Malformed receipts and HTTP problems throw LlmsInkError.
+     */
+    inspect(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<InspectionReceipt>;
     /** Checks a site's published llms.txt against the llmstxt.org format and that its links answer. */
     check(url: string, options?: CheckOptions): Promise<CheckResult>;
     /** Parses and checks llms.txt text you already have (`POST /api/v0/check`); nothing is published. */

package/dist/index.js

@@ -13,8 +13,9 @@
  *
  * @module
  */
+import { prepareInspection, inspectionJson, inspectionReceipt } from "./inspect.js";
 import { env } from "./env.js";
-export const VERSION = '0.4.0';
+export const VERSION = '0.5.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).
@@ -83,10 +84,12 @@ export class LlmsInk {
     key;
     /** Origin of the API, without a trailing slash. */
     baseUrl;
+    #inspectBaseUrl;
     #fetch;
     constructor(options = {}) {
         const key = (options.key ?? env('LLMS_INK_KEY'))?.trim();
         this.key = key || undefined;
+        this.#inspectBaseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         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.');
@@ -102,6 +105,44 @@ export class LlmsInk {
         const res = await this.#request('/api/v0/llms', llmsParams(url, options), 'application/json', options.signal);
         return (await this.#json(res));
     }
+    /**
+     * Explicitly upload supplied text to the hosted Inspect pilot. Requires an enabled key.
+     * The receipt binds to these exact UTF-8 bytes; no finding is not a safety guarantee.
+     * No retries. 65-second default deadline. LLMS_INK_API is ignored; baseUrl must be explicit.
+     * Keep keys server-side. Malformed receipts and HTTP problems throw LlmsInkError.
+     */
+    async inspect(text, options = {}) {
+        if (!this.key)
+            throw new LlmsInkError('Inspect requires an inspection-enabled API key.', { code: 'key_required' });
+        const { body, digest } = await prepareInspection(text, this.#inspectBaseUrl);
+        const controller = new AbortController();
+        const abort = () => controller.abort(options.signal?.reason);
+        const timer = setTimeout(() => controller.abort(new DOMException('Inspection timed out.', 'TimeoutError')), 65000);
+        if (options.signal?.aborted)
+            abort();
+        options.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            const res = await this.#fetch(`${this.#inspectBaseUrl}/api/v0/inspect`, {
+                method: 'POST', redirect: 'error', signal: controller.signal,
+                headers: { authorization: `Bearer ${this.key}`, 'content-type': 'application/json', accept: 'application/json' }, body,
+            });
+            const data = await inspectionJson(res);
+            if (!res.ok && data && typeof data === 'object' && !('detection' in data)) {
+                const p = data;
+                throw errorFor(p.detail || p.title || `Inspect returned HTTP ${res.status}.`, { status: res.status, code: p.code, retryAfter: retryAfter(res.headers.get('retry-after')) });
+            }
+            return inspectionReceipt(data, digest, res.status);
+        }
+        catch (err) {
+            if (err instanceof LlmsInkError || isAbort(err))
+                throw err;
+            throw new LlmsInkError('Inspection did not return a valid receipt. Withhold the content.', { code: 'inspection_unavailable' });
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
     /** 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.#request('/api/v0/check', { url }, 'application/json', options.signal);

package/dist/inspect.d.ts

@@ -0,0 +1,21 @@
+/** Hosted Inspect pilot. Only explicit inspect() calls upload content. */
+export interface InspectionReceipt {
+    readonly detection: 'no_finding' | 'flagged' | 'unknown';
+    readonly coverage: 'complete' | 'partial' | 'none';
+    readonly recommendation: 'continue' | 'withhold';
+    readonly reason: string;
+    readonly modelRevision: string;
+    readonly policyRevision: string;
+    readonly preprocessingRevision: string;
+    readonly contentDigest: string;
+    readonly inputTokens: number;
+    readonly inspectedTokens: number;
+    readonly windows: number;
+    readonly enforced: false;
+}
+export declare function prepareInspection(text: string, baseUrl: string): Promise<{
+    body: string;
+    digest: string;
+}>;
+export declare function inspectionJson(res: Response): Promise<unknown>;
+export declare function inspectionReceipt(value: unknown, digest: string, status: number): InspectionReceipt;

package/dist/inspect.js

@@ -0,0 +1,67 @@
+export async function prepareInspection(text, baseUrl) {
+    const url = new URL(baseUrl);
+    if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))))
+        throw new TypeError('Inspect requires HTTPS (or localhost for development).');
+    if (typeof text !== 'string' || !text.length)
+        throw new TypeError('Inspect requires nonempty text.');
+    const bytes = new TextEncoder().encode(text);
+    if (new TextDecoder('utf-8', { ignoreBOM: true }).decode(bytes) !== text)
+        throw new TypeError('Inspect requires valid Unicode.');
+    const body = JSON.stringify({ format: 'text', content: text });
+    if (new TextEncoder().encode(body).length > 131072)
+        throw new TypeError('Inspect request exceeds 128 KiB after JSON encoding.');
+    const crypto = globalThis.crypto ?? (await import('node:crypto')).webcrypto;
+    const digest = [...new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))].map(b => b.toString(16).padStart(2, '0')).join('');
+    return { body, digest };
+}
+export async function inspectionJson(res) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        throw new Error('Inspect returned an empty response.');
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.length;
+            if (size > 16384) {
+                await reader.cancel();
+                throw new Error('Inspect response exceeds 16 KiB.');
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+}
+export function inspectionReceipt(value, digest, status) {
+    const fail = () => { throw new Error('Inspect returned an invalid or unsupported receipt. Withhold the content.'); };
+    if (!value || typeof value !== 'object')
+        return fail();
+    const r = value;
+    if (![200, 422, 503].includes(status) || (status !== 200 && r.detection !== 'unknown') || r.contentDigest !== digest || r.modelRevision !== '4a43fec65a670e48835d8e8c85c705b4b0d1c907' || r.policyRevision !== 'llms-ink-inspect-1' || r.preprocessingRevision !== 'utf8-json-stringify-1' || r.enforced !== false)
+        return fail();
+    if (!Number.isSafeInteger(r.inputTokens) || r.inputTokens < 0 || !Number.isSafeInteger(r.inspectedTokens) || r.inspectedTokens < 0 || r.inspectedTokens > r.inputTokens || !Number.isInteger(r.windows) || r.windows < 0 || r.windows > 43)
+        return fail();
+    let valid = false;
+    if (r.detection === 'no_finding')
+        valid = r.coverage === 'complete' && r.recommendation === 'continue' && r.reason === 'no_finding' && r.inputTokens <= 8192 && r.inspectedTokens === r.inputTokens && (r.inputTokens === 0 || r.windows > 0);
+    if (r.detection === 'flagged')
+        valid = ['complete', 'partial'].includes(r.coverage) && r.recommendation === 'withhold' && ['instruction_pattern', 'model_detection'].includes(r.reason) && r.inputTokens <= 8192 && r.inspectedTokens > 0 && r.windows > 0 && (r.coverage !== 'complete' || r.inspectedTokens === r.inputTokens);
+    if (r.detection === 'unknown')
+        valid = r.coverage === 'none' && r.recommendation === 'withhold' && r.inspectedTokens === 0 && r.windows === 0 && ['token_limit', 'model_unavailable', 'model_failure', 'inspection_timeout'].includes(r.reason);
+    if (!valid)
+        return fail();
+    const { detection, coverage, recommendation, reason, modelRevision, policyRevision, preprocessingRevision, contentDigest, inputTokens, inspectedTokens, windows, enforced } = r;
+    return Object.freeze({ detection, coverage, recommendation, reason, modelRevision, policyRevision, preprocessingRevision, contentDigest, inputTokens, inspectedTokens, windows, enforced });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llms-ink",
-  "version": "0.4.0",
+  "version": "0.5.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": {
@@ -31,9 +31,9 @@
   "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/traffic.test.mjs",
+    "test": "npm run build && node --test test/client.test.mjs test/plugins.test.mjs test/middleware.test.mjs test/traffic.test.mjs test/inspect.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/traffic.test.mjs",
+    "test:bun": "npm run build && bun test ./test/client.test.mjs ./test/plugins.test.mjs ./test/middleware.test.mjs ./test/traffic.test.mjs ./test/inspect.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"],
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
-    "astro": "^7.4.1",
+    "astro": "^7.4.7",
     "typescript": "^5.9.3",
     "vite": "^8.3.8"
   }