ProofPudding TypeScript SDK

A TypeScript SDK for the ProofPudding API - Document processing and question answering.

Installation

npm install proofpudding

Quick Start

import { PuddingClient } from "proofpudding";

const client = new PuddingClient({
  accessToken: "pk_your_api_key",
});

// Upload a document
const doc = await client.documents.upload({
  filePath: "./invoice.pdf",
});

// Ask a question about it
const job = await client.jobs.create({
  documentId: doc.id,
  question: "What is the total amount due?",
});

console.log(job.result?.answer);
// → "The total amount due is $1,234.56"
console.log(job.result?.citations);
// → [{ page: 1, quote: "Total Due: $1,234.56", type: "text" }]

Streaming

Use Server-Sent Events to get real-time progress updates:

for await (const event of client.jobs.createStream({
  documentId: doc.id,
  question: "Summarize this document",
})) {
  switch (event.event) {
    case "downloading":
      console.log(`Downloading progress ${event.progress}`);
      break;
    case "processing":
      console.log(`Processing page ${event.pages_done}/${event.total_pages}`);
      break;
    case "thinking":
      console.log(`Thinking iteration ${event.iteration}`);
      break;
    case "step":
      console.log(`Step: ${event.message}`);
      break;
    case "verifying":
      console.log(
        `Verifying citation ${event.citation_index + 1}/${event.total_citations}`,
      );
      break;
    case "complete":
      console.log("Result:", event.result);
      break;
    case "error":
      console.error("Error:", event.message);
      break;
  }
}

Structured Output

Extract data into a JSON schema:

const job = await client.jobs.create({
  documentId: doc.id,
  question: "Extract the invoice details",
  config: {
    output_schema: {
      schema: {
        type: "object",
        properties: {
          vendor: { type: "string" },
          total: { type: "number" },
          currency: { type: "string" },
          line_items: {
            type: "array",
            items: {
              type: "object",
              properties: {
                description: { type: "string" },
                amount: { type: "number" },
              },
            },
          },
        },
        required: ["vendor", "total", "currency"],
      },
      strict: true,
    },
  },
});

console.log(job.result?.structured_output);
// → { vendor: "Acme Corp", total: 1234.56, currency: "USD", line_items: [...] }

Configuration

const client = new PuddingClient({
  // Required: your API key
  accessToken: "pk_your_api_key",

  // Optional: override the API base URL (default: https://api.proofpudding.com)
  baseUrl: "https://api.proofpudding.ai",

  // Optional: max retries for failed requests (default: 3)
  maxRetries: 3,

  // Optional: request timeout in milliseconds (default: 30000)
  timeout: 30_000,
});

API Reference

Health

| Method | Description | | ----------------------- | ----------------------------- | | client.health.check() | Basic health check | | client.health.ready() | Readiness check (verifies DB) |

Documents

| Method | Description | | --------------------------------------------- | -------------------------- | | client.documents.upload({ filePath }) | Upload from file path | | client.documents.upload({ file, filename }) | Upload from Buffer | | client.documents.list({ skip?, limit? }) | List documents (paginated) | | client.documents.delete(documentId) | Delete a document | | client.documents.getFormats() | Get supported file formats | | client.documents.getPreviewUrl(documentId) | Get a signed preview URL |

Jobs

| Method | Description | | ----------------------------------------------------------------------- | ------------------------------- | | client.jobs.create({ documentId, question, config?, timeout? }) | Create a job (sync) | | client.jobs.createStream({ documentId, question, config?, timeout? }) | Create a job with SSE streaming | | client.jobs.list({ documentId?, skip?, limit? }) | List jobs (paginated) |

Job Config Options

interface JobConfig {
  verify_citations?: boolean; // Default: true
  reasoning_effort?: "auto" | "low" | "high"; // Default: "auto"
  output_schema?: {
    schema: Record<string, unknown>; // JSON Schema
    strict?: boolean; // Default: true
    include_citations?: boolean;
    include_raw_answer?: boolean;
  };
}

Error Handling

All API errors are thrown as typed exceptions:

import {
  PuddingError,
  ValidationError, // 400
  AuthenticationError, // 401
  NotFoundError, // 404
  RateLimitError, // 429
  ServerError, // 500
  GatewayError, // 502
  TimeoutError, // 504
} from "proofpudding";

try {
  await client.jobs.create({ documentId: "bad-id", question: "test" });
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error("Document not found:", err.message);
  } else if (err instanceof AuthenticationError) {
    console.error("Bad API key");
  } else if (err instanceof RateLimitError) {
    console.error("Slow down!");
  }
}

Requirements

• Node.js 20+