@artchristech/fillin-client 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @fillin/client
+
+TypeScript client for [Fillin](https://fillin.glyphapi.dev) — search engine for AI agents. Closes the gap between an LLM's training cutoff and now across HN, arXiv, GitHub Releases, and curated RSS, plus daily snapshots of supply-chain CVEs, new research papers, and frontier AI lab releases.
+
+## Install
+
+```bash
+npm install @fillin/client
+```
+
+## Quickstart
+
+```ts
+import { FillinClient } from "@fillin/client";
+
+const fillin = new FillinClient({
+  apiKey: process.env.FILLIN_API_KEY!,
+});
+
+// Generic post-cutoff vector search across all corpora — $0.01/call
+const { results } = await fillin.query({
+  cutoff: "2026-01-01",                // your model's training cutoff
+  query: "rust async runtime developments",
+  k: 5,                                 // 1–20
+});
+
+for (const hit of results) {
+  console.log(`[${hit.source}] ${hit.title}  ←  ${hit.url}`);
+}
+```
+
+Get a bearer key at [fillin.glyphapi.dev/signup](https://fillin.glyphapi.dev/signup) (20 free queries, no card). For per-call pricing see [fillin.glyphapi.dev/pricing](https://fillin.glyphapi.dev/pricing).
+
+## API
+
+### `new FillinClient(options)`
+
+| Option       | Type     | Default                            | Description                              |
+|--------------|----------|------------------------------------|------------------------------------------|
+| `apiKey`     | `string` | —                                  | Pre-issued bearer key.                   |
+| `host`       | `string` | `https://fillin.glyphapi.dev`      | API base URL.                            |
+| `timeoutMs`  | `number` | `30000`                            | Per-request abort timeout.               |
+| `fetch`      | function | `globalThis.fetch`                 | Inject for testing or custom transports. |
+
+### Methods
+
+- `query(params)` — generic post-cutoff vector search across all corpora. **$0.01/call.**
+- `stats()` — bearer-gated corpus stats.
+- `freshness()` — public corpus freshness (no auth).
+- `health()` — liveness check (no auth).
+- `paymentInfo()` — public x402 payment surface.
+
+> **Slice routes** (`/query/cves` $0.02, `/query/papers` $0.03, `/query/frontier` $0.05) and `/answer` ($0.02) ship in the underlying API but aren't yet wrapped in this client. Hit them directly via `fetch`, or open an issue/PR if you want first-class methods.
+
+### Errors
+
+Non-2xx responses throw `FillinError` carrying `.status` and `.body` (truncated to 500 chars).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fillin/client — TypeScript client for Fillin.
+ *
+ * Two surfaces:
+ *   - Bearer auth: pre-pay credits, paste your key, call .query().
+ *   - x402 auth: agent-native, pays USDC per call (separate handshake — see /docs).
+ *
+ * @example
+ * ```ts
+ * import { FillinClient } from "@fillin/client";
+ * const fillin = new FillinClient({ apiKey: process.env.FILLIN_API_KEY! });
+ * const { results } = await fillin.query({
+ *   cutoff: "2026-01-01",
+ *   query: "rust async runtime developments",
+ *   k: 5,
+ * });
+ * ```
+ */
+export declare const DEFAULT_HOST = "https://fillin.glyphapi.dev";
+export interface FillinOptions {
+    /** Pre-issued bearer key. Get one at https://fillin.glyphapi.dev/pricing */
+    apiKey?: string;
+    /** API host. Defaults to https://fillin.glyphapi.dev */
+    host?: string;
+    /** Per-request timeout in ms. Default 30000. */
+    timeoutMs?: number;
+    /** Override fetch (for testing or custom transports). */
+    fetch?: typeof fetch;
+}
+export interface QueryParams {
+    /** ISO-8601 date — your model's training cutoff. Documents on or before are excluded. */
+    cutoff: string;
+    /** Natural-language query. Max 512 chars (truncated server-side). */
+    query: string;
+    /** Number of results to return, 1–20. Default 5. */
+    k?: number;
+}
+export interface Hit {
+    id: string;
+    source: string;
+    url: string;
+    published_at: string;
+    title: string;
+    text: string;
+    score: number | null;
+}
+export interface QueryResult {
+    cutoff: string;
+    query: string;
+    gap_days: number;
+    results: Hit[];
+}
+export interface Stats {
+    rows: number;
+    earliest: string | null;
+    latest: string | null;
+    by_source: Record<string, number>;
+}
+export interface Freshness extends Stats {
+    now: string;
+}
+export declare class FillinError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export declare class FillinClient {
+    private readonly host;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts?: FillinOptions);
+    /** Paid retrieval. Requires apiKey (bearer) or an x402-signed handshake. */
+    query(params: QueryParams): Promise<QueryResult>;
+    /** Bearer-gated corpus stats. Requires apiKey. */
+    stats(): Promise<Stats>;
+    /** Public corpus freshness. No auth. */
+    freshness(): Promise<Freshness>;
+    /** Liveness check. No auth. */
+    health(): Promise<{
+        ok: boolean;
+    }>;
+    /** Public payment surface (x402 wallet, asset, pricing). */
+    paymentInfo(): Promise<unknown>;
+    private request;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,eAAO,MAAM,YAAY,gCAAgC,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,GAAG,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,SAAU,SAAQ,KAAK;IACtC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qBAAa,WAAY,SAAQ,KAAK;aAGlB,MAAM,EAAE,MAAM;aACd,IAAI,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM;CAK/B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,GAAE,aAAkB;IAUpC,4EAA4E;IACtE,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAWtD,kDAAkD;IAC5C,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAM7B,wCAAwC;IAClC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;IAIrC,+BAA+B;IACzB,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;IAIxC,4DAA4D;IACtD,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;YAIvB,OAAO;CA2BtB"}

package/dist/index.js

@@ -0,0 +1,96 @@
+/**
+ * @fillin/client — TypeScript client for Fillin.
+ *
+ * Two surfaces:
+ *   - Bearer auth: pre-pay credits, paste your key, call .query().
+ *   - x402 auth: agent-native, pays USDC per call (separate handshake — see /docs).
+ *
+ * @example
+ * ```ts
+ * import { FillinClient } from "@fillin/client";
+ * const fillin = new FillinClient({ apiKey: process.env.FILLIN_API_KEY! });
+ * const { results } = await fillin.query({
+ *   cutoff: "2026-01-01",
+ *   query: "rust async runtime developments",
+ *   k: 5,
+ * });
+ * ```
+ */
+export const DEFAULT_HOST = "https://fillin.glyphapi.dev";
+export class FillinError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "FillinError";
+    }
+}
+export class FillinClient {
+    host;
+    apiKey;
+    timeoutMs;
+    fetchImpl;
+    constructor(opts = {}) {
+        this.host = (opts.host ?? DEFAULT_HOST).replace(/\/+$/, "");
+        this.apiKey = opts.apiKey;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+        this.fetchImpl = opts.fetch ?? globalThis.fetch;
+        if (!this.fetchImpl) {
+            throw new Error("FillinClient: no global fetch — pass `fetch` in options or use Node 18+");
+        }
+    }
+    /** Paid retrieval. Requires apiKey (bearer) or an x402-signed handshake. */
+    async query(params) {
+        const body = JSON.stringify({
+            cutoff: params.cutoff,
+            query: params.query,
+            k: params.k ?? 5,
+        });
+        const headers = { "content-type": "application/json" };
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        return this.request("POST", "/query", { headers, body });
+    }
+    /** Bearer-gated corpus stats. Requires apiKey. */
+    async stats() {
+        const headers = {};
+        if (this.apiKey)
+            headers.authorization = `Bearer ${this.apiKey}`;
+        return this.request("GET", "/stats", { headers });
+    }
+    /** Public corpus freshness. No auth. */
+    async freshness() {
+        return this.request("GET", "/freshness");
+    }
+    /** Liveness check. No auth. */
+    async health() {
+        return this.request("GET", "/healthz");
+    }
+    /** Public payment surface (x402 wallet, asset, pricing). */
+    async paymentInfo() {
+        return this.request("GET", "/v1/payment/info");
+    }
+    async request(method, path, init = {}) {
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchImpl(`${this.host}${path}`, {
+                method,
+                headers: init.headers,
+                body: init.body,
+                signal: ctl.signal,
+            });
+            const text = await res.text();
+            if (!res.ok) {
+                throw new FillinError(`fillin ${method} ${path} → HTTP ${res.status}`, res.status, text.slice(0, 500));
+            }
+            return JSON.parse(text);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@artchristech/fillin-client",
+  "version": "0.1.0",
+  "description": "TypeScript client for Fillin — search engine for AI agents (post-cutoff retrieval + daily snapshot slices).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test --import=tsx test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "llm", "retrieval", "rag", "x402", "agent"],
+  "homepage": "https://fillin.glyphapi.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/artchristech/fillin.git",
+    "directory": "clients/fillin-ts"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}