@pageindex/search 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vectify AI
+
+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,56 @@
-# Temporary Holding Version
+# @pageindex/search
 
-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.
+JavaScript client for [Page Search API](https://search.pageindex.ai) by PageIndex. Upload a PDF, ask up to 10
+questions at once, and get back the pages that answer each one, ranked by relevance. Every page is read.
+
+```bash
+npm install @pageindex/search
+```
+
+Create an API key in the [console](https://search.pageindex.ai/console/keys) and set it:
+
+```bash
+export PAGEINDEX_SEARCH_API_KEY=pis_live_...
+```
+
+Node 18 or later. Keep the key on your server: don't ship it to a browser.
+
+## Quick start
+
+```ts
+import { PageSearch } from "@pageindex/search";
+
+const client = new PageSearch();
+
+const doc = await client.upload("NVDA_2026_10K.pdf");
+const result = await client.search(doc, [
+  "What was total revenue in fiscal 2026?",
+  "How much stock did NVIDIA buy back?",
+]);
+
+for (const answer of result.results) {
+  console.log(answer.question);
+  for (const page of answer.pages) console.log(`  page ${page.page}: ${page.relevance.toFixed(2)}`);
+}
+
+console.log(`cost $${result.usage.cost_usd}, credit left $${result.usage.balance_usd}`);
+```
+
+Upload a document once and search it as often as you like; uploading the same file again returns the same
+document.
+
+## Reference
+
+| | |
+| --- | --- |
+| `new PageSearch({ apiKey, baseURL, timeout, maxRetries })` | The key defaults to `PAGEINDEX_SEARCH_API_KEY`; `timeout` is in milliseconds (default 120,000). |
+| `upload(file, { filename, wait })` | A path, or the file's bytes (`Uint8Array`, `ArrayBuffer`, `Blob`). Resolves to a `Document`, ready to search unless `wait: false`. |
+| `search(document, questions, { topK })` | Up to 10 questions. Each answer lists the pages likely to help (relevance 0.3 or more; 0.2 or more when fewer than 3 are; possibly none), or exactly `topK`. |
+| `document(id)`, `documents({ limit, after })`, `iterDocuments()` | Your documents. |
+| `delete(document)` | Delete a document. |
+| `usage({ start, end })` | Uploads, searches and cost by day, your credit and stored pages. |
+
+Errors reject with `PageSearchError`, with the API's `status`, `code`, `message` and `requestId`.
+
+See the [API reference](https://search.pageindex.ai/docs/api) for every field and the
+[pricing](https://search.pageindex.ai/pricing).

package/dist/cjs/index.d.ts

@@ -0,0 +1,143 @@
+export declare const VERSION = "0.1.0";
+export declare const DEFAULT_BASE_URL = "https://api.search.pageindex.ai/v1";
+/** A path (Node), or the file's bytes. */
+export type FileInput = string | Uint8Array | ArrayBuffer | Blob;
+export interface Document {
+    object: "document";
+    id: string;
+    status: "processing" | "ready" | "failed";
+    filename: string | null;
+    pages: number | null;
+    bytes: number;
+    created_at: string;
+    error?: string;
+    duplicate?: boolean;
+}
+export interface Page {
+    page: number;
+    relevance: number;
+}
+export interface Answer {
+    question: string;
+    pages: Page[];
+}
+export interface SearchResult {
+    object: "search";
+    id: string;
+    document_id: string;
+    results: Answer[];
+    failed_pages: number[];
+    usage: {
+        pages: number;
+        questions: number;
+        billable_pages: number;
+        cost_usd: number;
+        balance_usd: number;
+    };
+    seconds: number;
+}
+export interface UsageDay {
+    date: string;
+    uploads: number;
+    pages_uploaded: number;
+    searches: number;
+    questions: number;
+    billable_pages: number;
+    storage_cost_usd: number;
+    cost_usd: number;
+}
+export interface Usage {
+    object: "usage";
+    start: string;
+    end: string;
+    data: UsageDay[];
+    total: Omit<UsageDay, "date">;
+    balance_usd: number;
+    storage: {
+        stored_pages: number;
+        free_pages: number;
+        price_per_1000_pages_month_usd: number;
+    };
+}
+export interface PageSearchOptions {
+    /** Defaults to the PAGEINDEX_SEARCH_API_KEY environment variable. */
+    apiKey?: string;
+    baseURL?: string;
+    /** Milliseconds a request may take. */
+    timeout?: number;
+    maxRetries?: number;
+    /** A fetch to use instead of the global one. */
+    fetch?: typeof fetch;
+}
+/** An error the API returned, or a document that could not be made. */
+export declare class PageSearchError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        requestId?: string;
+    });
+}
+/**
+ * A client for the Page Search API.
+ *
+ *     const client = new PageSearch(); // reads PAGEINDEX_SEARCH_API_KEY
+ *     const doc = await client.upload("report.pdf");
+ *     const result = await client.search(doc, ["What was revenue in 2024?"]);
+ *     for (const answer of result.results) console.log(answer.question, answer.pages.map((p) => p.page));
+ */
+export declare class PageSearch {
+    readonly baseURL: string;
+    readonly maxRetries: number;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly fetch;
+    constructor(options?: PageSearchOptions);
+    /**
+     * Uploads a PDF: a path (in Node) or its bytes. Uploading the same file again returns its document.
+     *
+     * With wait (the default), resolves once the document is ready to search, or rejects if it failed; most are
+     * ready in a second or two. Without it, resolves at once; the document may still be processing.
+     */
+    upload(file: FileInput, options?: {
+        filename?: string;
+        wait?: boolean;
+        timeout?: number;
+    }): Promise<Document>;
+    /** The document once it is ready; rejects if it failed or is not ready within timeout (milliseconds). */
+    wait(document: Document | string, options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<Document>;
+    document(documentId: string): Promise<Document>;
+    /** One page of your documents, newest first; after: the last id of the previous page. */
+    documents(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<Document[]>;
+    /** Every document you have, newest first, a page at a time. */
+    iterDocuments(): AsyncGenerator<Document>;
+    /** Deletes a document and its pages; searches of it then fail. */
+    delete(document: Document | string): Promise<void>;
+    /**
+     * Asks up to 10 questions about a document. For each, the pages that help answer it, most relevant first.
+     *
+     * Without topK, each answer lists the pages likely to help: relevance 0.3 or more, or 0.2 or more when fewer
+     * than 3 are, and possibly none. With it, exactly topK pages.
+     */
+    search(document: Document | string, questions: string | string[], options?: {
+        topK?: number;
+    }): Promise<SearchResult>;
+    /**
+     * Uploads, searches and cost by day (UTC, dates as YYYY-MM-DD; the last 30 days by default), your credit
+     * balance and the pages you have stored.
+     */
+    usage(options?: {
+        start?: string;
+        end?: string;
+    }): Promise<Usage>;
+    private request;
+}
+export default PageSearch;

package/dist/cjs/index.js

@@ -0,0 +1,211 @@
+"use strict";
+// The Page Search API client: upload a PDF, then search its pages with up to 10 questions at once.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageSearch = exports.PageSearchError = exports.DEFAULT_BASE_URL = exports.VERSION = void 0;
+exports.VERSION = "0.1.0";
+exports.DEFAULT_BASE_URL = "https://api.search.pageindex.ai/v1";
+const API_KEY_ENV = "PAGEINDEX_SEARCH_API_KEY";
+// Retried, after a short wait that doubles: the server was busy or briefly unreachable.
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+/** An error the API returned, or a document that could not be made. */
+class PageSearchError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "PageSearchError";
+        this.status = options.status;
+        this.code = options.code;
+        this.requestId = options.requestId;
+    }
+}
+exports.PageSearchError = PageSearchError;
+/**
+ * A client for the Page Search API.
+ *
+ *     const client = new PageSearch(); // reads PAGEINDEX_SEARCH_API_KEY
+ *     const doc = await client.upload("report.pdf");
+ *     const result = await client.search(doc, ["What was revenue in 2024?"]);
+ *     for (const answer of result.results) console.log(answer.question, answer.pages.map((p) => p.page));
+ */
+class PageSearch {
+    baseURL;
+    maxRetries;
+    apiKey;
+    timeout;
+    fetch;
+    constructor(options = {}) {
+        const env = typeof process !== "undefined" ? process.env : {};
+        const apiKey = options.apiKey ?? env[API_KEY_ENV];
+        if (!apiKey) {
+            throw new PageSearchError(`No API key: pass apiKey or set ${API_KEY_ENV}. ` +
+                "Create one at https://search.pageindex.ai/console/keys.");
+        }
+        this.apiKey = apiKey;
+        this.baseURL = (options.baseURL ?? env.PAGEINDEX_SEARCH_BASE_URL ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = options.timeout ?? 120_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    // Documents
+    /**
+     * Uploads a PDF: a path (in Node) or its bytes. Uploading the same file again returns its document.
+     *
+     * With wait (the default), resolves once the document is ready to search, or rejects if it failed; most are
+     * ready in a second or two. Without it, resolves at once; the document may still be processing.
+     */
+    async upload(file, options = {}) {
+        let blob;
+        let filename = options.filename;
+        if (typeof file === "string") {
+            const { readFile } = await Promise.resolve().then(() => require("node:fs/promises"));
+            const { basename } = await Promise.resolve().then(() => require("node:path"));
+            blob = new Blob([await readFile(file)], { type: "application/pdf" });
+            filename ??= basename(file);
+        }
+        else if (file instanceof Blob) {
+            blob = file;
+            filename ??= file.name;
+        }
+        else {
+            blob = new Blob([file], { type: "application/pdf" });
+        }
+        const form = new FormData();
+        form.append("file", blob, filename || "document.pdf");
+        const doc = await this.request("POST", "/documents", { body: form });
+        return options.wait === false ? doc : this.wait(doc, { timeout: options.timeout });
+    }
+    /** The document once it is ready; rejects if it failed or is not ready within timeout (milliseconds). */
+    async wait(document, options = {}) {
+        let doc = typeof document === "string" ? await this.document(document) : document;
+        const deadline = Date.now() + (options.timeout ?? 300_000);
+        while (doc.status === "processing") {
+            if (Date.now() > deadline)
+                throw new PageSearchError(`Document ${doc.id} is still processing.`);
+            await sleep(options.interval ?? 1000);
+            doc = await this.document(doc.id);
+        }
+        if (doc.status === "failed") {
+            throw new PageSearchError(doc.error || `Document ${doc.id} could not be processed.`, { code: "document_failed" });
+        }
+        return doc;
+    }
+    document(documentId) {
+        return this.request("GET", `/documents/${encodeURIComponent(documentId)}`);
+    }
+    /** One page of your documents, newest first; after: the last id of the previous page. */
+    async documents(options = {}) {
+        const page = await this.request("GET", "/documents", {
+            query: { limit: options.limit ?? 20, after: options.after },
+        });
+        return page.data;
+    }
+    /** Every document you have, newest first, a page at a time. */
+    async *iterDocuments() {
+        let after;
+        for (;;) {
+            const page = await this.request("GET", "/documents", {
+                query: { limit: 100, after },
+            });
+            yield* page.data;
+            if (!page.has_more || !page.data.length)
+                return;
+            after = page.data[page.data.length - 1].id;
+        }
+    }
+    /** Deletes a document and its pages; searches of it then fail. */
+    async delete(document) {
+        await this.request("DELETE", `/documents/${encodeURIComponent(id(document))}`);
+    }
+    // Search
+    /**
+     * Asks up to 10 questions about a document. For each, the pages that help answer it, most relevant first.
+     *
+     * Without topK, each answer lists the pages likely to help: relevance 0.3 or more, or 0.2 or more when fewer
+     * than 3 are, and possibly none. With it, exactly topK pages.
+     */
+    search(document, questions, options = {}) {
+        const body = { questions: typeof questions === "string" ? [questions] : questions };
+        if (options.topK !== undefined)
+            body.top_k = options.topK;
+        return this.request("POST", `/documents/${encodeURIComponent(id(document))}/search`, { json: body });
+    }
+    // Account
+    /**
+     * Uploads, searches and cost by day (UTC, dates as YYYY-MM-DD; the last 30 days by default), your credit
+     * balance and the pages you have stored.
+     */
+    usage(options = {}) {
+        return this.request("GET", "/usage", { query: options });
+    }
+    // Plumbing
+    async request(method, path, options = {}) {
+        const url = new URL(this.baseURL + path);
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== "")
+                url.searchParams.set(name, String(value));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "User-Agent": `pageindex-search-js/${exports.VERSION}`,
+        };
+        let body = options.body;
+        if (options.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(options.json);
+        }
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.fetch(url, { method, headers, body, signal: AbortSignal.timeout(this.timeout) });
+            }
+            catch (error) {
+                if (attempt >= this.maxRetries)
+                    throw new PageSearchError(`Could not reach the API: ${error.message}`);
+                await sleep(500 * 2 ** attempt);
+                continue;
+            }
+            if (RETRY_STATUSES.has(response.status) && attempt < this.maxRetries) {
+                await sleep(500 * 2 ** attempt);
+                continue;
+            }
+            return parse(response);
+        }
+    }
+}
+exports.PageSearch = PageSearch;
+function id(document) {
+    return typeof document === "string" ? document : document.id;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parse(response) {
+    const text = await response.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = undefined;
+    }
+    if (response.ok && data && typeof data === "object")
+        return data;
+    const requestId = response.headers.get("x-request-id") ?? undefined;
+    const doc = data;
+    if (doc?.object === "document" && doc.status === "failed") {
+        // An upload whose file could not be read answers with the document, failed, and why.
+        throw new PageSearchError(doc.error || `Document ${doc.id} could not be read.`, {
+            status: response.status, code: "document_failed", requestId,
+        });
+    }
+    const found = data?.error;
+    const error = found && typeof found === "object" ? found : {};
+    throw new PageSearchError(error.message || text.slice(0, 200) || response.statusText, {
+        status: response.status,
+        code: error.code,
+        requestId: error.request_id ?? requestId,
+    });
+}
+exports.default = PageSearch;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,143 @@
+export declare const VERSION = "0.1.0";
+export declare const DEFAULT_BASE_URL = "https://api.search.pageindex.ai/v1";
+/** A path (Node), or the file's bytes. */
+export type FileInput = string | Uint8Array | ArrayBuffer | Blob;
+export interface Document {
+    object: "document";
+    id: string;
+    status: "processing" | "ready" | "failed";
+    filename: string | null;
+    pages: number | null;
+    bytes: number;
+    created_at: string;
+    error?: string;
+    duplicate?: boolean;
+}
+export interface Page {
+    page: number;
+    relevance: number;
+}
+export interface Answer {
+    question: string;
+    pages: Page[];
+}
+export interface SearchResult {
+    object: "search";
+    id: string;
+    document_id: string;
+    results: Answer[];
+    failed_pages: number[];
+    usage: {
+        pages: number;
+        questions: number;
+        billable_pages: number;
+        cost_usd: number;
+        balance_usd: number;
+    };
+    seconds: number;
+}
+export interface UsageDay {
+    date: string;
+    uploads: number;
+    pages_uploaded: number;
+    searches: number;
+    questions: number;
+    billable_pages: number;
+    storage_cost_usd: number;
+    cost_usd: number;
+}
+export interface Usage {
+    object: "usage";
+    start: string;
+    end: string;
+    data: UsageDay[];
+    total: Omit<UsageDay, "date">;
+    balance_usd: number;
+    storage: {
+        stored_pages: number;
+        free_pages: number;
+        price_per_1000_pages_month_usd: number;
+    };
+}
+export interface PageSearchOptions {
+    /** Defaults to the PAGEINDEX_SEARCH_API_KEY environment variable. */
+    apiKey?: string;
+    baseURL?: string;
+    /** Milliseconds a request may take. */
+    timeout?: number;
+    maxRetries?: number;
+    /** A fetch to use instead of the global one. */
+    fetch?: typeof fetch;
+}
+/** An error the API returned, or a document that could not be made. */
+export declare class PageSearchError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        requestId?: string;
+    });
+}
+/**
+ * A client for the Page Search API.
+ *
+ *     const client = new PageSearch(); // reads PAGEINDEX_SEARCH_API_KEY
+ *     const doc = await client.upload("report.pdf");
+ *     const result = await client.search(doc, ["What was revenue in 2024?"]);
+ *     for (const answer of result.results) console.log(answer.question, answer.pages.map((p) => p.page));
+ */
+export declare class PageSearch {
+    readonly baseURL: string;
+    readonly maxRetries: number;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly fetch;
+    constructor(options?: PageSearchOptions);
+    /**
+     * Uploads a PDF: a path (in Node) or its bytes. Uploading the same file again returns its document.
+     *
+     * With wait (the default), resolves once the document is ready to search, or rejects if it failed; most are
+     * ready in a second or two. Without it, resolves at once; the document may still be processing.
+     */
+    upload(file: FileInput, options?: {
+        filename?: string;
+        wait?: boolean;
+        timeout?: number;
+    }): Promise<Document>;
+    /** The document once it is ready; rejects if it failed or is not ready within timeout (milliseconds). */
+    wait(document: Document | string, options?: {
+        timeout?: number;
+        interval?: number;
+    }): Promise<Document>;
+    document(documentId: string): Promise<Document>;
+    /** One page of your documents, newest first; after: the last id of the previous page. */
+    documents(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<Document[]>;
+    /** Every document you have, newest first, a page at a time. */
+    iterDocuments(): AsyncGenerator<Document>;
+    /** Deletes a document and its pages; searches of it then fail. */
+    delete(document: Document | string): Promise<void>;
+    /**
+     * Asks up to 10 questions about a document. For each, the pages that help answer it, most relevant first.
+     *
+     * Without topK, each answer lists the pages likely to help: relevance 0.3 or more, or 0.2 or more when fewer
+     * than 3 are, and possibly none. With it, exactly topK pages.
+     */
+    search(document: Document | string, questions: string | string[], options?: {
+        topK?: number;
+    }): Promise<SearchResult>;
+    /**
+     * Uploads, searches and cost by day (UTC, dates as YYYY-MM-DD; the last 30 days by default), your credit
+     * balance and the pages you have stored.
+     */
+    usage(options?: {
+        start?: string;
+        end?: string;
+    }): Promise<Usage>;
+    private request;
+}
+export default PageSearch;

package/dist/esm/index.js

@@ -0,0 +1,206 @@
+// The Page Search API client: upload a PDF, then search its pages with up to 10 questions at once.
+export const VERSION = "0.1.0";
+export const DEFAULT_BASE_URL = "https://api.search.pageindex.ai/v1";
+const API_KEY_ENV = "PAGEINDEX_SEARCH_API_KEY";
+// Retried, after a short wait that doubles: the server was busy or briefly unreachable.
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+/** An error the API returned, or a document that could not be made. */
+export class PageSearchError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "PageSearchError";
+        this.status = options.status;
+        this.code = options.code;
+        this.requestId = options.requestId;
+    }
+}
+/**
+ * A client for the Page Search API.
+ *
+ *     const client = new PageSearch(); // reads PAGEINDEX_SEARCH_API_KEY
+ *     const doc = await client.upload("report.pdf");
+ *     const result = await client.search(doc, ["What was revenue in 2024?"]);
+ *     for (const answer of result.results) console.log(answer.question, answer.pages.map((p) => p.page));
+ */
+export class PageSearch {
+    baseURL;
+    maxRetries;
+    apiKey;
+    timeout;
+    fetch;
+    constructor(options = {}) {
+        const env = typeof process !== "undefined" ? process.env : {};
+        const apiKey = options.apiKey ?? env[API_KEY_ENV];
+        if (!apiKey) {
+            throw new PageSearchError(`No API key: pass apiKey or set ${API_KEY_ENV}. ` +
+                "Create one at https://search.pageindex.ai/console/keys.");
+        }
+        this.apiKey = apiKey;
+        this.baseURL = (options.baseURL ?? env.PAGEINDEX_SEARCH_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeout = options.timeout ?? 120_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    // Documents
+    /**
+     * Uploads a PDF: a path (in Node) or its bytes. Uploading the same file again returns its document.
+     *
+     * With wait (the default), resolves once the document is ready to search, or rejects if it failed; most are
+     * ready in a second or two. Without it, resolves at once; the document may still be processing.
+     */
+    async upload(file, options = {}) {
+        let blob;
+        let filename = options.filename;
+        if (typeof file === "string") {
+            const { readFile } = await import("node:fs/promises");
+            const { basename } = await import("node:path");
+            blob = new Blob([await readFile(file)], { type: "application/pdf" });
+            filename ??= basename(file);
+        }
+        else if (file instanceof Blob) {
+            blob = file;
+            filename ??= file.name;
+        }
+        else {
+            blob = new Blob([file], { type: "application/pdf" });
+        }
+        const form = new FormData();
+        form.append("file", blob, filename || "document.pdf");
+        const doc = await this.request("POST", "/documents", { body: form });
+        return options.wait === false ? doc : this.wait(doc, { timeout: options.timeout });
+    }
+    /** The document once it is ready; rejects if it failed or is not ready within timeout (milliseconds). */
+    async wait(document, options = {}) {
+        let doc = typeof document === "string" ? await this.document(document) : document;
+        const deadline = Date.now() + (options.timeout ?? 300_000);
+        while (doc.status === "processing") {
+            if (Date.now() > deadline)
+                throw new PageSearchError(`Document ${doc.id} is still processing.`);
+            await sleep(options.interval ?? 1000);
+            doc = await this.document(doc.id);
+        }
+        if (doc.status === "failed") {
+            throw new PageSearchError(doc.error || `Document ${doc.id} could not be processed.`, { code: "document_failed" });
+        }
+        return doc;
+    }
+    document(documentId) {
+        return this.request("GET", `/documents/${encodeURIComponent(documentId)}`);
+    }
+    /** One page of your documents, newest first; after: the last id of the previous page. */
+    async documents(options = {}) {
+        const page = await this.request("GET", "/documents", {
+            query: { limit: options.limit ?? 20, after: options.after },
+        });
+        return page.data;
+    }
+    /** Every document you have, newest first, a page at a time. */
+    async *iterDocuments() {
+        let after;
+        for (;;) {
+            const page = await this.request("GET", "/documents", {
+                query: { limit: 100, after },
+            });
+            yield* page.data;
+            if (!page.has_more || !page.data.length)
+                return;
+            after = page.data[page.data.length - 1].id;
+        }
+    }
+    /** Deletes a document and its pages; searches of it then fail. */
+    async delete(document) {
+        await this.request("DELETE", `/documents/${encodeURIComponent(id(document))}`);
+    }
+    // Search
+    /**
+     * Asks up to 10 questions about a document. For each, the pages that help answer it, most relevant first.
+     *
+     * Without topK, each answer lists the pages likely to help: relevance 0.3 or more, or 0.2 or more when fewer
+     * than 3 are, and possibly none. With it, exactly topK pages.
+     */
+    search(document, questions, options = {}) {
+        const body = { questions: typeof questions === "string" ? [questions] : questions };
+        if (options.topK !== undefined)
+            body.top_k = options.topK;
+        return this.request("POST", `/documents/${encodeURIComponent(id(document))}/search`, { json: body });
+    }
+    // Account
+    /**
+     * Uploads, searches and cost by day (UTC, dates as YYYY-MM-DD; the last 30 days by default), your credit
+     * balance and the pages you have stored.
+     */
+    usage(options = {}) {
+        return this.request("GET", "/usage", { query: options });
+    }
+    // Plumbing
+    async request(method, path, options = {}) {
+        const url = new URL(this.baseURL + path);
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== "")
+                url.searchParams.set(name, String(value));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "User-Agent": `pageindex-search-js/${VERSION}`,
+        };
+        let body = options.body;
+        if (options.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(options.json);
+        }
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.fetch(url, { method, headers, body, signal: AbortSignal.timeout(this.timeout) });
+            }
+            catch (error) {
+                if (attempt >= this.maxRetries)
+                    throw new PageSearchError(`Could not reach the API: ${error.message}`);
+                await sleep(500 * 2 ** attempt);
+                continue;
+            }
+            if (RETRY_STATUSES.has(response.status) && attempt < this.maxRetries) {
+                await sleep(500 * 2 ** attempt);
+                continue;
+            }
+            return parse(response);
+        }
+    }
+}
+function id(document) {
+    return typeof document === "string" ? document : document.id;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parse(response) {
+    const text = await response.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        data = undefined;
+    }
+    if (response.ok && data && typeof data === "object")
+        return data;
+    const requestId = response.headers.get("x-request-id") ?? undefined;
+    const doc = data;
+    if (doc?.object === "document" && doc.status === "failed") {
+        // An upload whose file could not be read answers with the document, failed, and why.
+        throw new PageSearchError(doc.error || `Document ${doc.id} could not be read.`, {
+            status: response.status, code: "document_failed", requestId,
+        });
+    }
+    const found = data?.error;
+    const error = found && typeof found === "object" ? found : {};
+    throw new PageSearchError(error.message || text.slice(0, 200) || response.statusText, {
+        status: response.status,
+        code: error.code,
+        requestId: error.request_id ?? requestId,
+    });
+}
+export default PageSearch;

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@pageindex/search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "JavaScript client for Page Search API by PageIndex: find the pages of a PDF that answer your questions.",
+  "license": "MIT",
+  "author": "PageIndex <support@pageindex.ai>",
+  "homepage": "https://search.pageindex.ai",
+  "repository": { "type": "git", "url": "git+https://github.com/VectifyAI/pageindex-search-js.git" },
+  "bugs": "https://github.com/VectifyAI/pageindex-search-js/issues",
+  "keywords": ["pageindex", "search", "pdf", "rag", "llm", "retrieval"],
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+      "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.4.0"
+  }
+}