apapyr 1.0.0

package/README.md

@@ -0,0 +1,63 @@
+# aPapyr Node.js SDK
+
+Extract structured data from invoices, receipts, and documents. Send a PDF or image, get clean JSON back.
+
+## Install
+
+```bash
+npm install apapyr
+```
+
+## Quick Start
+
+```javascript
+const { aPapyr } = require("apapyr");
+
+const client = new aPapyr("sk_live_your_key");
+
+// Extract data from an invoice
+const result = await client.extract("invoice.pdf");
+
+console.log(result.getField("vendor_name")); // "Acme Corp"
+console.log(result.getField("total")); // 1250.00
+console.log(result.confidence); // 0.97
+
+// Get all fields as a flat object
+console.log(result.toFlatDict());
+// { document_type: "invoice", vendor_name: "Acme Corp", total: 1250.00, ... }
+```
+
+## AI Agent Support
+
+aPapyr works natively with AI agents via MCP:
+
+```bash
+claude mcp add apapyr -- npx @apapyr/mcp-server
+```
+
+Then just ask: *"Extract the data from invoice.pdf"*
+
+## Document Types
+
+- `invoice` — vendor, total, tax, due_date, line_items
+- `receipt` — merchant, total, tax, tip, payment_method
+- `w2` — employer, wages, federal_tax, state_tax
+- `bank_statement` — bank, balances, transactions
+- `contract` — parties, dates, value, obligations
+- `auto` — automatically detects type (default)
+
+## Environment Variable
+
+```bash
+export APAPYR_API_KEY=sk_live_your_key
+```
+
+```javascript
+const client = new aPapyr(); // reads from env
+```
+
+## Links
+
+- [API Docs](https://apapyr.com/docs.html)
+- [Dashboard](https://apapyr.com/dashboard.html)
+- [Free Tool](https://apapyr.com/free-tool.html)

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "apapyr",
+  "version": "1.0.0",
+  "description": "Extract structured data from invoices, receipts, and documents. PDF/image in, JSON out.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "keywords": ["invoice", "receipt", "OCR", "document", "extraction", "PDF", "parser", "API", "AI", "MCP", "apapyr"],
+  "author": "aPapyr",
+  "license": "MIT",
+  "homepage": "https://apapyr.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apapyr/apapyr-node"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": ["src/"]
+}

package/src/index.d.ts

@@ -0,0 +1,36 @@
+export class aPapyrError extends Error {
+  statusCode?: number;
+  response?: Record<string, any>;
+  constructor(message: string, statusCode?: number, response?: Record<string, any>);
+}
+
+export class Extraction {
+  id: string;
+  status: string;
+  documentType: string;
+  confidence: number;
+  processingTimeMs: number;
+  cached: boolean;
+  fields: Record<string, { value: any; confidence: number }>;
+  lineItems: Array<Record<string, { value: any; confidence: number }>>;
+  validationWarnings: string[];
+
+  getField(name: string): any;
+  getFieldConfidence(name: string): number;
+  toDict(): Record<string, any>;
+  toFlatDict(): Record<string, any>;
+}
+
+export class aPapyr {
+  constructor(apiKey?: string, options?: { baseUrl?: string });
+
+  extract(
+    file: string | Buffer | NodeJS.ReadableStream,
+    options?: { documentType?: string; webhookUrl?: string }
+  ): Promise<Extraction>;
+
+  getExtraction(extractionId: string): Promise<Extraction>;
+  listExtractions(options?: { limit?: number; offset?: number }): Promise<any[]>;
+  getUsage(): Promise<Record<string, any>>;
+  listSchemas(): Promise<Record<string, any>>;
+}

package/src/index.js

@@ -0,0 +1,186 @@
+const fs = require("fs");
+const path = require("path");
+
+class aPapyrError extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.name = "aPapyrError";
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+}
+
+class Extraction {
+  constructor(data) {
+    this._data = data;
+    this.id = data.id;
+    this.status = data.status;
+    this.documentType = data.document_type;
+    this.confidence = data.confidence;
+    this.processingTimeMs = data.processing_time_ms;
+    this.cached = data.cached || false;
+    this.fields = (data.data && data.data.fields) || {};
+    this.lineItems = (data.data && data.data.line_items) || [];
+    this.validationWarnings = data.validation_warnings || [];
+  }
+
+  getField(name) {
+    const field = this.fields[name];
+    if (field && typeof field === "object") return field.value;
+    return field;
+  }
+
+  getFieldConfidence(name) {
+    const field = this.fields[name];
+    if (field && typeof field === "object") return field.confidence || 0;
+    return 0;
+  }
+
+  toDict() {
+    return this._data;
+  }
+
+  toFlatDict() {
+    const result = { document_type: this.documentType };
+    for (const [key, val] of Object.entries(this.fields)) {
+      result[key] = typeof val === "object" ? val.value : val;
+    }
+    return result;
+  }
+}
+
+class aPapyr {
+  /**
+   * @param {string} apiKey - Your aPapyr API key (sk_live_...)
+   * @param {object} [options]
+   * @param {string} [options.baseUrl] - API base URL
+   */
+  constructor(apiKey, options = {}) {
+    this.apiKey = apiKey || process.env.APAPYR_API_KEY;
+    if (!this.apiKey) {
+      throw new aPapyrError(
+        'API key required. Pass it as new aPapyr("sk_live_...") or set APAPYR_API_KEY env var.'
+      );
+    }
+    this.baseUrl = (options.baseUrl || "https://api.apapyr.com").replace(/\/$/, "");
+  }
+
+  /**
+   * Extract structured data from a document.
+   * @param {string|Buffer|ReadableStream} file - File path or Buffer or stream
+   * @param {object} [options]
+   * @param {string} [options.documentType='auto'] - Document type
+   * @param {string} [options.webhookUrl] - Webhook URL for async results
+   * @returns {Promise<Extraction>}
+   */
+  async extract(file, options = {}) {
+    const { documentType = "auto", webhookUrl } = options;
+
+    let fileData;
+    let fileName = "document";
+
+    if (typeof file === "string") {
+      if (!fs.existsSync(file)) {
+        throw new aPapyrError(`File not found: ${file}`);
+      }
+      fileData = fs.readFileSync(file);
+      fileName = path.basename(file);
+    } else if (Buffer.isBuffer(file)) {
+      fileData = file;
+    } else {
+      fileData = file;
+    }
+
+    const boundary = "----aPapyr" + Math.random().toString(36).slice(2);
+    const parts = [];
+
+    parts.push(
+      `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fileName}"\r\nContent-Type: application/octet-stream\r\n\r\n`
+    );
+    parts.push(fileData);
+    parts.push("\r\n");
+
+    parts.push(
+      `--${boundary}\r\nContent-Disposition: form-data; name="document_type"\r\n\r\n${documentType}\r\n`
+    );
+
+    if (webhookUrl) {
+      parts.push(
+        `--${boundary}\r\nContent-Disposition: form-data; name="webhook_url"\r\n\r\n${webhookUrl}\r\n`
+      );
+    }
+
+    parts.push(`--${boundary}--\r\n`);
+
+    const body = Buffer.concat(
+      parts.map((p) => (typeof p === "string" ? Buffer.from(p) : p))
+    );
+
+    const response = await fetch(`${this.baseUrl}/v1/extract`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": `multipart/form-data; boundary=${boundary}`,
+      },
+      body,
+    });
+
+    return this._handleResponse(response);
+  }
+
+  async getExtraction(extractionId) {
+    const response = await fetch(`${this.baseUrl}/v1/extract/${extractionId}`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    return this._handleResponse(response);
+  }
+
+  async listExtractions(options = {}) {
+    const { limit = 20, offset = 0 } = options;
+    const response = await fetch(
+      `${this.baseUrl}/v1/extractions?limit=${limit}&offset=${offset}`,
+      { headers: { Authorization: `Bearer ${this.apiKey}` } }
+    );
+    if (!response.ok) await this._raiseError(response);
+    const data = await response.json();
+    return data.extractions || [];
+  }
+
+  async getUsage() {
+    const response = await fetch(`${this.baseUrl}/v1/usage`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    if (!response.ok) await this._raiseError(response);
+    return response.json();
+  }
+
+  async listSchemas() {
+    const response = await fetch(`${this.baseUrl}/v1/schemas`, {
+      headers: { Authorization: `Bearer ${this.apiKey}` },
+    });
+    if (!response.ok) await this._raiseError(response);
+    return response.json();
+  }
+
+  async _handleResponse(response) {
+    if (!response.ok) await this._raiseError(response);
+    const data = await response.json();
+    if (data.status === "failed") {
+      throw new aPapyrError(data.error || "Extraction failed", response.status, data);
+    }
+    return new Extraction(data);
+  }
+
+  async _raiseError(response) {
+    let message;
+    try {
+      const data = await response.json();
+      message = data.detail || JSON.stringify(data);
+    } catch {
+      message = await response.text();
+    }
+    throw new aPapyrError(message, response.status);
+  }
+}
+
+module.exports = { aPapyr, Extraction, aPapyrError };