parsefy 1.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Parsefy
+
+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

@@ -0,0 +1,307 @@
+# Parsefy
+
+Official TypeScript SDK for [Parsefy](https://parsefy.io) – AI-powered document data extraction.
+
+Extract structured data from PDFs and DOCX files using Zod schemas with full TypeScript type inference.
+
+## Installation
+
+```bash
+npm install parsefy zod
+```
+
+## Quick Start
+
+```typescript
+import { Parsefy } from 'parsefy';
+import * as z from 'zod';
+
+const client = new Parsefy('pk_your_api_key');
+
+const schema = z.object({
+  invoice_number: z.string().describe('The invoice number'),
+  date: z.string().describe('Invoice date in YYYY-MM-DD format'),
+  total: z.number().describe('Total amount'),
+});
+
+const { object, error } = await client.extract({
+  file: './invoice.pdf',
+  schema,
+});
+
+if (!error && object) {
+  console.log(object.invoice_number); // Fully typed!
+}
+```
+
+## Configuration
+
+### API Key
+
+```typescript
+// Option 1: Pass API key directly
+const client = new Parsefy('pk_your_api_key');
+
+// Option 2: Use environment variable
+// Set PARSEFY_API_KEY in your environment
+const client = new Parsefy();
+
+// Option 3: Configuration object
+const client = new Parsefy({
+  apiKey: 'pk_your_api_key',
+  timeout: 120000, // 2 minutes
+});
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | `process.env.PARSEFY_API_KEY` | Your Parsefy API key |
+| `timeout` | `number` | `60000` | Request timeout in ms |
+
+## Usage
+
+### Basic Extraction
+
+```typescript
+import { Parsefy } from 'parsefy';
+import * as z from 'zod';
+
+const client = new Parsefy();
+
+const schema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+  phone: z.string().optional(),
+});
+
+const { object, metadata, error } = await client.extract({
+  file: './contact.pdf',
+  schema,
+});
+
+if (!error) {
+  console.log(object);
+} 
+```
+
+### File Input Options
+
+The SDK supports multiple file input types. **Files don't need to be on disk** – you can work entirely in memory, which is ideal for building APIs and serverless functions.
+
+| Input Type | Usage | Environment |
+|------------|-------|-------------|
+| `string` | File path | Node.js only |
+| `Buffer` | In-memory bytes | Node.js |
+| `File` | From file input or FormData | Browser, Node.js 20+, Edge |
+| `Blob` | Raw binary with MIME type | Universal |
+| `ArrayBuffer` | Wrap in `Blob` first | Universal |
+
+```typescript
+// Node.js: File path (convenience for scripts/CLI)
+const result = await client.extract({
+  file: './document.pdf',
+  schema,
+});
+
+// Node.js: Buffer (in-memory)
+import { readFileSync } from 'fs';
+const result = await client.extract({
+  file: readFileSync('./document.pdf'),
+  schema,
+});
+
+// Browser: File input
+const fileInput = document.querySelector('input[type="file"]');
+const result = await client.extract({
+  file: fileInput.files[0],
+  schema,
+});
+
+// Universal: Blob (with explicit MIME type)
+const result = await client.extract({
+  file: new Blob([arrayBuffer], { type: 'application/pdf' }),
+  schema,
+});
+```
+
+### Server-Side / API Usage
+
+When building APIs that receive file uploads, files are typically kept in memory. The SDK handles this seamlessly:
+
+**Express with Multer:**
+
+```typescript
+import express from 'express';
+import multer from 'multer';
+import { Parsefy } from 'parsefy';
+
+const upload = multer(); // Store in memory, not disk
+const client = new Parsefy();
+
+app.post('/extract', upload.single('document'), async (req, res) => {
+  const { object, error } = await client.extract({
+    file: req.file.buffer, // Buffer from multer
+    schema,
+  });
+  res.json({ data: object, error });
+});
+```
+
+**Fastify:**
+
+```typescript
+import Fastify from 'fastify';
+import multipart from '@fastify/multipart';
+import { Parsefy } from 'parsefy';
+
+const fastify = Fastify();
+await fastify.register(multipart);
+const client = new Parsefy();
+
+fastify.post('/extract', async (request) => {
+  const data = await request.file();
+  const buffer = await data.toBuffer();
+
+  const { object, error } = await client.extract({
+    file: buffer,
+    schema,
+  });
+  return { data: object, error };
+});
+```
+
+**Hono / Cloudflare Workers:**
+
+```typescript
+import { Hono } from 'hono';
+import { Parsefy } from 'parsefy';
+
+const app = new Hono();
+const client = new Parsefy();
+
+app.post('/extract', async (c) => {
+  const formData = await c.req.formData();
+  const file = formData.get('document'); // File object
+
+  const { object, error } = await client.extract({
+    file, // File from FormData works directly
+    schema,
+  });
+  return c.json({ data: object, error });
+});
+```
+
+### Complex Schemas
+
+Use `.describe()` to guide the AI extraction:
+
+```typescript
+const invoiceSchema = z.object({
+  invoice_number: z.string().describe('The invoice or receipt number'),
+  date: z.string().describe('Invoice date in YYYY-MM-DD format'),
+  vendor: z.object({
+    name: z.string().describe('Company name of the vendor'),
+    address: z.string().describe('Full address of the vendor'),
+  }),
+  line_items: z.array(z.object({
+    description: z.string().describe('Item description'),
+    quantity: z.number().describe('Number of units'),
+    unit_price: z.number().describe('Price per unit'),
+    amount: z.number().describe('Total amount for this line'),
+  })).describe('List of items on the invoice'),
+  subtotal: z.number().describe('Subtotal before tax'),
+  tax: z.number().describe('Tax amount'),
+  total: z.number().describe('Total amount due'),
+  currency: z.string().describe('3-letter currency code (USD, EUR, etc.)'),
+});
+
+const { object } = await client.extract({
+  file: './invoice.pdf',
+  schema: invoiceSchema,
+});
+```
+
+### Error Handling
+
+```typescript
+import { Parsefy, APIError, ValidationError, ParsefyError } from 'parsefy';
+
+try {
+  const { object, error, metadata } = await client.extract({
+    file: './document.pdf',
+    schema,
+  });
+
+  // Extraction-level errors (request succeeded, but extraction failed)
+  if (error) {
+    console.error(`Extraction failed: [${error.code}] ${error.message}`);
+    console.log(`Tokens used: ${metadata.inputTokens} in, ${metadata.outputTokens} out`);
+    return;
+  }
+
+  console.log('Success:', object);
+} catch (err) {
+  // HTTP/Network errors
+  if (err instanceof APIError) {
+    console.error(`API Error ${err.statusCode}: ${err.message}`);
+  } else if (err instanceof ValidationError) {
+    console.error(`Validation Error: ${err.message}`);
+  } else if (err instanceof ParsefyError) {
+    console.error(`Parsefy Error: ${err.message}`);
+  }
+}
+```
+
+## Response Format
+
+```typescript
+interface ExtractResult<T> {
+  // Extracted data matching your schema, or null if extraction failed
+  object: T | null;
+
+  // Metadata about the extraction
+  metadata: {
+    processingTimeMs: number;    // Processing time in milliseconds
+    inputTokens: number;         // Input tokens used
+    outputTokens: number;        // Output tokens generated
+    credits: number;             // Credits consumed (1 credit = 1 page)
+    fallbackTriggered: boolean;  // Whether fallback model was used
+  };
+
+  // Error details if extraction failed
+  error: {
+    code: string;    // EXTRACTION_FAILED, LLM_ERROR, PARSING_ERROR, TIMEOUT_ERROR
+    message: string;
+  } | null;
+}
+```
+
+## Error Types
+
+| Error Class | Description |
+|-------------|-------------|
+| `ParsefyError` | Base error class for all Parsefy errors |
+| `APIError` | HTTP errors (4xx/5xx responses) |
+| `ExtractionError` | Extraction failed (returned in response) |
+| `ValidationError` | Client-side validation errors |
+
+## Supported File Types
+
+- **PDF** (`.pdf`) – up to 10MB
+- **DOCX** (`.docx`) – up to 10MB
+
+## Rate Limits
+
+The API allows 1 request per second. The SDK automatically retries with exponential backoff on rate limit errors (HTTP 429).
+
+## Requirements
+
+- Node.js 18+ (for native `fetch` and `FormData`)
+- Zod 3.x (peer dependency)
+
+## License
+
+MIT © [Parsefy](https://parsefy.io)
+

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var zodToJsonSchema=require('zod-to-json-schema');var m={".pdf":"application/pdf",".docx":"application/vnd.openxmlformats-officedocument.wordprocessingml.document"},f=10*1024*1024,h="https://api.parsefy.io",g=6e4;var i=class extends Error{constructor(t,r){super(t),this.name="ParsefyError",this.code=r,typeof Error.captureStackTrace=="function"&&Error.captureStackTrace(this,this.constructor);}},c=class extends i{constructor(t,r,o){super(t),this.name="APIError",this.statusCode=r,this.response=o;}},l=class extends i{constructor(t,r,o){super(t,r),this.name="ExtractionError",this.metadata=o;}},s=class extends i{constructor(t){super(t),this.name="ValidationError";}};function d(){return typeof process<"u"&&process.versions?.node!==void 0}function T(e){return zodToJsonSchema.zodToJsonSchema(e,{$refStrategy:"none",target:"openApi3"})}function b(e){let t=e.toLowerCase().match(/\.[^.]+$/)?.[0];return t&&m[t]||null}function R(e){if(!b(e)){let r=Object.keys(m).join(", ");throw new s(`Unsupported file type. Supported types: ${r}`)}}function u(e){if(e===0)throw new s("File is empty");if(e>f){let t=f/1048576;throw new s(`File size exceeds maximum limit of ${t}MB`)}}function w(e){return {object:e.object,metadata:{processingTimeMs:e.metadata.processing_time_ms,inputTokens:e.metadata.input_tokens,outputTokens:e.metadata.output_tokens,credits:e.metadata.credits,fallbackTriggered:e.metadata.fallback_triggered},error:e.error}}function E(e,t){let r=b(t)||"application/octet-stream",o=e.buffer.slice(e.byteOffset,e.byteOffset+e.byteLength);return typeof File<"u"?new File([o],t,{type:r}):new Blob([o],{type:r})}async function _(e){if(!d())throw new s("File path strings are only supported in Node.js. Use File or Blob in the browser.");let t=await import('fs'),r=await import('path');if(!t.existsSync(e))throw new s(`File not found: ${e}`);let o=r.basename(e);R(o);let a=t.readFileSync(e);return u(a.length),{buffer:a,filename:o}}async function P(e){if(typeof e=="string"){let{buffer:t,filename:r}=await _(e);return E(t,r)}if(Buffer.isBuffer(e))return u(e.length),E(e,"document.pdf");if(e instanceof File)return R(e.name),u(e.size),e;if(e instanceof Blob)return u(e.size),e;throw new s("Invalid file input. Expected File, Blob, Buffer, or file path string.")}function F(e){return new Promise(t=>setTimeout(t,e))}function k(e,t=1e3){let r=t*Math.pow(2,e),o=Math.random()*.1*r;return Math.min(r+o,3e4)}var y=class{constructor(t){this.maxRetries=3;let r={};if(typeof t=="string"?r={apiKey:t}:t&&(r=t),this.apiKey=r.apiKey||this.getEnvApiKey(),!this.apiKey)throw new s("API key is required. Provide it in the constructor or set the PARSEFY_API_KEY environment variable.");this.baseUrl=r.baseUrl||h,this.timeout=r.timeout||g;}getEnvApiKey(){return d()&&process.env.PARSEFY_API_KEY||""}async extract(t){let{file:r,schema:o}=t,a=T(o),n=await P(r),p=new FormData;return p.append("file",n),p.append("output_schema",JSON.stringify(a)),this.makeRequestWithRetry(p)}async makeRequestWithRetry(t,r=0){try{return await this.makeRequest(t)}catch(o){if(o instanceof c&&o.statusCode===429&&r<this.maxRetries){let a=k(r);return await F(a),this.makeRequestWithRetry(t,r+1)}throw o}}async makeRequest(t){let r=`${this.baseUrl}/v1/extract`,o=new AbortController,a=setTimeout(()=>o.abort(),this.timeout);try{let n=await fetch(r,{method:"POST",headers:{Authorization:`Bearer ${this.apiKey}`},body:t,signal:o.signal});if(clearTimeout(a),!n.ok){let x=await this.parseErrorResponse(n);throw new c(x.message||`API request failed with status ${n.status}`,n.status,x)}let p=await n.json();return w(p)}catch(n){throw clearTimeout(a),n instanceof Error&&n.name==="AbortError"?new i(`Request timed out after ${this.timeout}ms`,"TIMEOUT"):n instanceof i?n:n instanceof TypeError?new i("Network error: Unable to connect to the Parsefy API","NETWORK_ERROR"):new i(`Unexpected error: ${n instanceof Error?n.message:String(n)}`,"UNKNOWN_ERROR")}}async parseErrorResponse(t){try{return await t.json()}catch{try{return {message:await t.text()||t.statusText}}catch{return {message:t.statusText}}}}};
+exports.APIError=c;exports.ExtractionError=l;exports.Parsefy=y;exports.ParsefyError=i;exports.ValidationError=s;

package/dist/index.d.cts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+
+/**
+ * Configuration options for the Parsefy client.
+ */
+interface ParsefyConfig {
+    /** API key for authentication. If not provided, reads from PARSEFY_API_KEY environment variable. */
+    apiKey?: string;
+    /** Base URL for the API. Defaults to https://api.parsefy.io */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 60000 (60 seconds). */
+    timeout?: number;
+}
+/**
+ * Options for the extract method.
+ */
+interface ExtractOptions<T extends z.ZodType> {
+    /** The document file to extract data from. Supports File, Blob, Buffer, or file path (Node.js only). */
+    file: File | Blob | Buffer | string;
+    /** Zod schema defining the structure of data to extract. */
+    schema: T;
+}
+/**
+ * Metadata about the extraction process.
+ */
+interface ExtractionMetadata {
+    /** Time taken to process the document in milliseconds. */
+    processingTimeMs: number;
+    /** Number of input tokens used. */
+    inputTokens: number;
+    /** Number of output tokens generated. */
+    outputTokens: number;
+    /** Number of credits consumed (1 credit = 1 page). */
+    credits: number;
+    /** Whether the fallback model was triggered for higher accuracy. */
+    fallbackTriggered: boolean;
+}
+/**
+ * Error response from the API.
+ */
+interface APIErrorResponse {
+    /** Error code identifying the type of error. */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/**
+ * Result of an extraction operation.
+ */
+interface ExtractResult<T> {
+    /** Extracted data matching the schema, or null if extraction failed. */
+    object: T | null;
+    /** Metadata about the extraction process. */
+    metadata: ExtractionMetadata;
+    /** Error details if extraction failed, or null on success. */
+    error: APIErrorResponse | null;
+}
+
+/**
+ * Parsefy client for extracting structured data from documents.
+ *
+ * @example
+ * ```ts
+ * import { Parsefy } from 'parsefy';
+ * import * as z from 'zod';
+ *
+ * const client = new Parsefy('pk_your_api_key');
+ *
+ * const schema = z.object({
+ *   name: z.string(),
+ *   total: z.number(),
+ * });
+ *
+ * const { object, error } = await client.extract({
+ *   file: './invoice.pdf',
+ *   schema,
+ * });
+ * ```
+ */
+declare class Parsefy {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    /**
+     * Creates a new Parsefy client.
+     *
+     * @param configOrApiKey - API key string or configuration object.
+     *   If not provided, reads from PARSEFY_API_KEY environment variable.
+     *
+     * @example
+     * ```ts
+     * // Using API key directly
+     * const client = new Parsefy('pk_your_api_key');
+     *
+     * // Using configuration object
+     * const client = new Parsefy({
+     *   apiKey: 'pk_your_api_key',
+     *   timeout: 120000,
+     * });
+     *
+     * // Using environment variable
+     * const client = new Parsefy();
+     * ```
+     */
+    constructor(configOrApiKey?: string | ParsefyConfig);
+    /**
+     * Gets the API key from environment variable.
+     */
+    private getEnvApiKey;
+    /**
+     * Extracts structured data from a document using the provided Zod schema.
+     *
+     * @param options - Extraction options including file and schema.
+     * @returns Promise resolving to the extraction result with typed data.
+     *
+     * @example
+     * ```ts
+     * const schema = z.object({
+     *   invoice_number: z.string().describe('The invoice number'),
+     *   total: z.number().describe('Total amount'),
+     * });
+     *
+     * const { object, metadata, error } = await client.extract({
+     *   file: './invoice.pdf',
+     *   schema,
+     * });
+     *
+     * if (!error && object) {
+     *   console.log(object.invoice_number); // Fully typed!
+     * }
+     * ```
+     */
+    extract<T extends z.ZodType>(options: ExtractOptions<T>): Promise<ExtractResult<z.infer<T>>>;
+    /**
+     * Makes a request with retry logic for rate limiting.
+     */
+    private makeRequestWithRetry;
+    /**
+     * Makes the actual HTTP request to the API.
+     */
+    private makeRequest;
+    /**
+     * Parses error response body safely.
+     */
+    private parseErrorResponse;
+}
+
+/**
+ * Base error class for all Parsefy errors.
+ */
+declare class ParsefyError extends Error {
+    /** Error code, if applicable. */
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown when the API returns an HTTP error (4xx/5xx).
+ */
+declare class APIError extends ParsefyError {
+    /** HTTP status code of the response. */
+    readonly statusCode: number;
+    /** Raw response body, if available. */
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error thrown when document extraction fails (returned in response.error).
+ * This is not an HTTP error - the request succeeded but extraction failed.
+ */
+declare class ExtractionError extends ParsefyError {
+    /** Metadata about the extraction attempt. */
+    readonly metadata: ExtractionMetadata;
+    constructor(message: string, code: string, metadata: ExtractionMetadata);
+}
+/**
+ * Error thrown for client-side validation failures.
+ */
+declare class ValidationError extends ParsefyError {
+    constructor(message: string);
+}
+
+export { APIError, type APIErrorResponse, type ExtractOptions, type ExtractResult, ExtractionError, type ExtractionMetadata, Parsefy, type ParsefyConfig, ParsefyError, ValidationError };

package/dist/index.d.mts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+
+/**
+ * Configuration options for the Parsefy client.
+ */
+interface ParsefyConfig {
+    /** API key for authentication. If not provided, reads from PARSEFY_API_KEY environment variable. */
+    apiKey?: string;
+    /** Base URL for the API. Defaults to https://api.parsefy.io */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 60000 (60 seconds). */
+    timeout?: number;
+}
+/**
+ * Options for the extract method.
+ */
+interface ExtractOptions<T extends z.ZodType> {
+    /** The document file to extract data from. Supports File, Blob, Buffer, or file path (Node.js only). */
+    file: File | Blob | Buffer | string;
+    /** Zod schema defining the structure of data to extract. */
+    schema: T;
+}
+/**
+ * Metadata about the extraction process.
+ */
+interface ExtractionMetadata {
+    /** Time taken to process the document in milliseconds. */
+    processingTimeMs: number;
+    /** Number of input tokens used. */
+    inputTokens: number;
+    /** Number of output tokens generated. */
+    outputTokens: number;
+    /** Number of credits consumed (1 credit = 1 page). */
+    credits: number;
+    /** Whether the fallback model was triggered for higher accuracy. */
+    fallbackTriggered: boolean;
+}
+/**
+ * Error response from the API.
+ */
+interface APIErrorResponse {
+    /** Error code identifying the type of error. */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/**
+ * Result of an extraction operation.
+ */
+interface ExtractResult<T> {
+    /** Extracted data matching the schema, or null if extraction failed. */
+    object: T | null;
+    /** Metadata about the extraction process. */
+    metadata: ExtractionMetadata;
+    /** Error details if extraction failed, or null on success. */
+    error: APIErrorResponse | null;
+}
+
+/**
+ * Parsefy client for extracting structured data from documents.
+ *
+ * @example
+ * ```ts
+ * import { Parsefy } from 'parsefy';
+ * import * as z from 'zod';
+ *
+ * const client = new Parsefy('pk_your_api_key');
+ *
+ * const schema = z.object({
+ *   name: z.string(),
+ *   total: z.number(),
+ * });
+ *
+ * const { object, error } = await client.extract({
+ *   file: './invoice.pdf',
+ *   schema,
+ * });
+ * ```
+ */
+declare class Parsefy {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    /**
+     * Creates a new Parsefy client.
+     *
+     * @param configOrApiKey - API key string or configuration object.
+     *   If not provided, reads from PARSEFY_API_KEY environment variable.
+     *
+     * @example
+     * ```ts
+     * // Using API key directly
+     * const client = new Parsefy('pk_your_api_key');
+     *
+     * // Using configuration object
+     * const client = new Parsefy({
+     *   apiKey: 'pk_your_api_key',
+     *   timeout: 120000,
+     * });
+     *
+     * // Using environment variable
+     * const client = new Parsefy();
+     * ```
+     */
+    constructor(configOrApiKey?: string | ParsefyConfig);
+    /**
+     * Gets the API key from environment variable.
+     */
+    private getEnvApiKey;
+    /**
+     * Extracts structured data from a document using the provided Zod schema.
+     *
+     * @param options - Extraction options including file and schema.
+     * @returns Promise resolving to the extraction result with typed data.
+     *
+     * @example
+     * ```ts
+     * const schema = z.object({
+     *   invoice_number: z.string().describe('The invoice number'),
+     *   total: z.number().describe('Total amount'),
+     * });
+     *
+     * const { object, metadata, error } = await client.extract({
+     *   file: './invoice.pdf',
+     *   schema,
+     * });
+     *
+     * if (!error && object) {
+     *   console.log(object.invoice_number); // Fully typed!
+     * }
+     * ```
+     */
+    extract<T extends z.ZodType>(options: ExtractOptions<T>): Promise<ExtractResult<z.infer<T>>>;
+    /**
+     * Makes a request with retry logic for rate limiting.
+     */
+    private makeRequestWithRetry;
+    /**
+     * Makes the actual HTTP request to the API.
+     */
+    private makeRequest;
+    /**
+     * Parses error response body safely.
+     */
+    private parseErrorResponse;
+}
+
+/**
+ * Base error class for all Parsefy errors.
+ */
+declare class ParsefyError extends Error {
+    /** Error code, if applicable. */
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown when the API returns an HTTP error (4xx/5xx).
+ */
+declare class APIError extends ParsefyError {
+    /** HTTP status code of the response. */
+    readonly statusCode: number;
+    /** Raw response body, if available. */
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error thrown when document extraction fails (returned in response.error).
+ * This is not an HTTP error - the request succeeded but extraction failed.
+ */
+declare class ExtractionError extends ParsefyError {
+    /** Metadata about the extraction attempt. */
+    readonly metadata: ExtractionMetadata;
+    constructor(message: string, code: string, metadata: ExtractionMetadata);
+}
+/**
+ * Error thrown for client-side validation failures.
+ */
+declare class ValidationError extends ParsefyError {
+    constructor(message: string);
+}
+
+export { APIError, type APIErrorResponse, type ExtractOptions, type ExtractResult, ExtractionError, type ExtractionMetadata, Parsefy, type ParsefyConfig, ParsefyError, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import { z } from 'zod';
+
+/**
+ * Configuration options for the Parsefy client.
+ */
+interface ParsefyConfig {
+    /** API key for authentication. If not provided, reads from PARSEFY_API_KEY environment variable. */
+    apiKey?: string;
+    /** Base URL for the API. Defaults to https://api.parsefy.io */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 60000 (60 seconds). */
+    timeout?: number;
+}
+/**
+ * Options for the extract method.
+ */
+interface ExtractOptions<T extends z.ZodType> {
+    /** The document file to extract data from. Supports File, Blob, Buffer, or file path (Node.js only). */
+    file: File | Blob | Buffer | string;
+    /** Zod schema defining the structure of data to extract. */
+    schema: T;
+}
+/**
+ * Metadata about the extraction process.
+ */
+interface ExtractionMetadata {
+    /** Time taken to process the document in milliseconds. */
+    processingTimeMs: number;
+    /** Number of input tokens used. */
+    inputTokens: number;
+    /** Number of output tokens generated. */
+    outputTokens: number;
+    /** Number of credits consumed (1 credit = 1 page). */
+    credits: number;
+    /** Whether the fallback model was triggered for higher accuracy. */
+    fallbackTriggered: boolean;
+}
+/**
+ * Error response from the API.
+ */
+interface APIErrorResponse {
+    /** Error code identifying the type of error. */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/**
+ * Result of an extraction operation.
+ */
+interface ExtractResult<T> {
+    /** Extracted data matching the schema, or null if extraction failed. */
+    object: T | null;
+    /** Metadata about the extraction process. */
+    metadata: ExtractionMetadata;
+    /** Error details if extraction failed, or null on success. */
+    error: APIErrorResponse | null;
+}
+
+/**
+ * Parsefy client for extracting structured data from documents.
+ *
+ * @example
+ * ```ts
+ * import { Parsefy } from 'parsefy';
+ * import * as z from 'zod';
+ *
+ * const client = new Parsefy('pk_your_api_key');
+ *
+ * const schema = z.object({
+ *   name: z.string(),
+ *   total: z.number(),
+ * });
+ *
+ * const { object, error } = await client.extract({
+ *   file: './invoice.pdf',
+ *   schema,
+ * });
+ * ```
+ */
+declare class Parsefy {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    /**
+     * Creates a new Parsefy client.
+     *
+     * @param configOrApiKey - API key string or configuration object.
+     *   If not provided, reads from PARSEFY_API_KEY environment variable.
+     *
+     * @example
+     * ```ts
+     * // Using API key directly
+     * const client = new Parsefy('pk_your_api_key');
+     *
+     * // Using configuration object
+     * const client = new Parsefy({
+     *   apiKey: 'pk_your_api_key',
+     *   timeout: 120000,
+     * });
+     *
+     * // Using environment variable
+     * const client = new Parsefy();
+     * ```
+     */
+    constructor(configOrApiKey?: string | ParsefyConfig);
+    /**
+     * Gets the API key from environment variable.
+     */
+    private getEnvApiKey;
+    /**
+     * Extracts structured data from a document using the provided Zod schema.
+     *
+     * @param options - Extraction options including file and schema.
+     * @returns Promise resolving to the extraction result with typed data.
+     *
+     * @example
+     * ```ts
+     * const schema = z.object({
+     *   invoice_number: z.string().describe('The invoice number'),
+     *   total: z.number().describe('Total amount'),
+     * });
+     *
+     * const { object, metadata, error } = await client.extract({
+     *   file: './invoice.pdf',
+     *   schema,
+     * });
+     *
+     * if (!error && object) {
+     *   console.log(object.invoice_number); // Fully typed!
+     * }
+     * ```
+     */
+    extract<T extends z.ZodType>(options: ExtractOptions<T>): Promise<ExtractResult<z.infer<T>>>;
+    /**
+     * Makes a request with retry logic for rate limiting.
+     */
+    private makeRequestWithRetry;
+    /**
+     * Makes the actual HTTP request to the API.
+     */
+    private makeRequest;
+    /**
+     * Parses error response body safely.
+     */
+    private parseErrorResponse;
+}
+
+/**
+ * Base error class for all Parsefy errors.
+ */
+declare class ParsefyError extends Error {
+    /** Error code, if applicable. */
+    readonly code?: string;
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown when the API returns an HTTP error (4xx/5xx).
+ */
+declare class APIError extends ParsefyError {
+    /** HTTP status code of the response. */
+    readonly statusCode: number;
+    /** Raw response body, if available. */
+    readonly response?: unknown;
+    constructor(message: string, statusCode: number, response?: unknown);
+}
+/**
+ * Error thrown when document extraction fails (returned in response.error).
+ * This is not an HTTP error - the request succeeded but extraction failed.
+ */
+declare class ExtractionError extends ParsefyError {
+    /** Metadata about the extraction attempt. */
+    readonly metadata: ExtractionMetadata;
+    constructor(message: string, code: string, metadata: ExtractionMetadata);
+}
+/**
+ * Error thrown for client-side validation failures.
+ */
+declare class ValidationError extends ParsefyError {
+    constructor(message: string);
+}
+
+export { APIError, type APIErrorResponse, type ExtractOptions, type ExtractResult, ExtractionError, type ExtractionMetadata, Parsefy, type ParsefyConfig, ParsefyError, ValidationError };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import {zodToJsonSchema}from'zod-to-json-schema';var m={".pdf":"application/pdf",".docx":"application/vnd.openxmlformats-officedocument.wordprocessingml.document"},f=10*1024*1024,h="https://api.parsefy.io",g=6e4;var i=class extends Error{constructor(t,r){super(t),this.name="ParsefyError",this.code=r,typeof Error.captureStackTrace=="function"&&Error.captureStackTrace(this,this.constructor);}},c=class extends i{constructor(t,r,o){super(t),this.name="APIError",this.statusCode=r,this.response=o;}},l=class extends i{constructor(t,r,o){super(t,r),this.name="ExtractionError",this.metadata=o;}},s=class extends i{constructor(t){super(t),this.name="ValidationError";}};function d(){return typeof process<"u"&&process.versions?.node!==void 0}function T(e){return zodToJsonSchema(e,{$refStrategy:"none",target:"openApi3"})}function b(e){let t=e.toLowerCase().match(/\.[^.]+$/)?.[0];return t&&m[t]||null}function R(e){if(!b(e)){let r=Object.keys(m).join(", ");throw new s(`Unsupported file type. Supported types: ${r}`)}}function u(e){if(e===0)throw new s("File is empty");if(e>f){let t=f/1048576;throw new s(`File size exceeds maximum limit of ${t}MB`)}}function w(e){return {object:e.object,metadata:{processingTimeMs:e.metadata.processing_time_ms,inputTokens:e.metadata.input_tokens,outputTokens:e.metadata.output_tokens,credits:e.metadata.credits,fallbackTriggered:e.metadata.fallback_triggered},error:e.error}}function E(e,t){let r=b(t)||"application/octet-stream",o=e.buffer.slice(e.byteOffset,e.byteOffset+e.byteLength);return typeof File<"u"?new File([o],t,{type:r}):new Blob([o],{type:r})}async function _(e){if(!d())throw new s("File path strings are only supported in Node.js. Use File or Blob in the browser.");let t=await import('fs'),r=await import('path');if(!t.existsSync(e))throw new s(`File not found: ${e}`);let o=r.basename(e);R(o);let a=t.readFileSync(e);return u(a.length),{buffer:a,filename:o}}async function P(e){if(typeof e=="string"){let{buffer:t,filename:r}=await _(e);return E(t,r)}if(Buffer.isBuffer(e))return u(e.length),E(e,"document.pdf");if(e instanceof File)return R(e.name),u(e.size),e;if(e instanceof Blob)return u(e.size),e;throw new s("Invalid file input. Expected File, Blob, Buffer, or file path string.")}function F(e){return new Promise(t=>setTimeout(t,e))}function k(e,t=1e3){let r=t*Math.pow(2,e),o=Math.random()*.1*r;return Math.min(r+o,3e4)}var y=class{constructor(t){this.maxRetries=3;let r={};if(typeof t=="string"?r={apiKey:t}:t&&(r=t),this.apiKey=r.apiKey||this.getEnvApiKey(),!this.apiKey)throw new s("API key is required. Provide it in the constructor or set the PARSEFY_API_KEY environment variable.");this.baseUrl=r.baseUrl||h,this.timeout=r.timeout||g;}getEnvApiKey(){return d()&&process.env.PARSEFY_API_KEY||""}async extract(t){let{file:r,schema:o}=t,a=T(o),n=await P(r),p=new FormData;return p.append("file",n),p.append("output_schema",JSON.stringify(a)),this.makeRequestWithRetry(p)}async makeRequestWithRetry(t,r=0){try{return await this.makeRequest(t)}catch(o){if(o instanceof c&&o.statusCode===429&&r<this.maxRetries){let a=k(r);return await F(a),this.makeRequestWithRetry(t,r+1)}throw o}}async makeRequest(t){let r=`${this.baseUrl}/v1/extract`,o=new AbortController,a=setTimeout(()=>o.abort(),this.timeout);try{let n=await fetch(r,{method:"POST",headers:{Authorization:`Bearer ${this.apiKey}`},body:t,signal:o.signal});if(clearTimeout(a),!n.ok){let x=await this.parseErrorResponse(n);throw new c(x.message||`API request failed with status ${n.status}`,n.status,x)}let p=await n.json();return w(p)}catch(n){throw clearTimeout(a),n instanceof Error&&n.name==="AbortError"?new i(`Request timed out after ${this.timeout}ms`,"TIMEOUT"):n instanceof i?n:n instanceof TypeError?new i("Network error: Unable to connect to the Parsefy API","NETWORK_ERROR"):new i(`Unexpected error: ${n instanceof Error?n.message:String(n)}`,"UNKNOWN_ERROR")}}async parseErrorResponse(t){try{return await t.json()}catch{try{return {message:await t.text()||t.statusText}}catch{return {message:t.statusText}}}}};
+export{c as APIError,l as ExtractionError,y as Parsefy,i as ParsefyError,s as ValidationError};

package/package.json

@@ -1,12 +1,57 @@
 {
   "name": "parsefy",
-  "version": "1.0.0",
-  "description": "High-accuracy document data extraction powered by AI",
-  "license": "ISC",
-  "author": "marceloakalopes",
-  "type": "commonjs",
-  "main": "index.js",
+  "version": "1.0.1",
+  "description": "Official TypeScript SDK for Parsefy - AI-powered document data extraction",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/parsefy/parsefy-js.git"
+  },
+  "homepage": "https://parsefy.io",
+  "bugs": {
+    "url": "https://github.com/parsefy/parsefy-js/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsup && cp dist/index.d.ts dist/index.d.cts",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "dependencies": {
+    "zod-to-json-schema": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "zod": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }

package/index.js

@@ -1 +0,0 @@
-console.log("Parsefy SDK");