@epostak/sdk 1.0.0 → 1.1.0

package/dist/resources/documents.js

@@ -1,5 +1,24 @@
 import { BaseResource, buildQuery } from "../utils/request.js";
+/**
+ * Resource for managing received (inbound) documents in your inbox.
+ * Provides methods to list, retrieve, and acknowledge incoming invoices.
+ */
 export class InboxResource extends BaseResource {
+    /**
+     * List documents in your inbox with optional filtering and pagination.
+     *
+     * @param params - Optional query parameters for filtering and pagination
+     * @returns Paginated list of inbox documents
+     *
+     * @example
+     * ```typescript
+     * // Get unprocessed documents
+     * const { documents, total } = await client.documents.inbox.list({
+     *   status: 'RECEIVED',
+     *   limit: 50,
+     * });
+     * ```
+     */
     list(params) {
         return this.request("GET", `/documents/inbox${buildQuery({
             offset: params?.offset,
@@ -8,12 +27,53 @@ export class InboxResource extends BaseResource {
             since: params?.since,
         })}`);
     }
+    /**
+     * Retrieve a single inbox document by ID, including the raw UBL XML payload.
+     *
+     * @param id - Document UUID
+     * @returns Document details with the UBL XML payload
+     *
+     * @example
+     * ```typescript
+     * const { document, payload } = await client.documents.inbox.get('doc-uuid');
+     * console.log(payload); // UBL XML string
+     * ```
+     */
     get(id) {
         return this.request("GET", `/documents/inbox/${encodeURIComponent(id)}`);
     }
+    /**
+     * Acknowledge (mark as processed) a received inbox document.
+     * Once acknowledged, the document moves from `RECEIVED` to `ACKNOWLEDGED` status.
+     *
+     * @param id - Document UUID to acknowledge
+     * @returns Acknowledgment confirmation with timestamp
+     *
+     * @example
+     * ```typescript
+     * const ack = await client.documents.inbox.acknowledge('doc-uuid');
+     * console.log(ack.acknowledgedAt); // "2026-04-11T12:00:00Z"
+     * ```
+     */
     acknowledge(id) {
         return this.request("POST", `/documents/inbox/${encodeURIComponent(id)}/acknowledge`);
     }
+    /**
+     * List documents across all managed firms (integrator endpoint).
+     * Only available with integrator API keys (`sk_int_*`).
+     *
+     * @param params - Optional query parameters including firm_id filter
+     * @returns Paginated list of documents across all firms
+     *
+     * @example
+     * ```typescript
+     * // Poll for new documents across all clients
+     * const { documents } = await client.documents.inbox.listAll({
+     *   since: '2026-04-01T00:00:00Z',
+     *   status: 'RECEIVED',
+     * });
+     * ```
+     */
     listAll(params) {
         return this.request("GET", `/documents/inbox/all${buildQuery({
             offset: params?.offset,
@@ -24,45 +84,249 @@ export class InboxResource extends BaseResource {
         })}`);
     }
 }
+/**
+ * Resource for sending, receiving, and managing Peppol e-invoicing documents.
+ * This is the primary resource for document operations — sending invoices,
+ * checking delivery status, downloading PDFs, and responding to received invoices.
+ *
+ * @example
+ * ```typescript
+ * const client = new EPostak({ apiKey: 'sk_live_xxxxx' });
+ *
+ * // Send an invoice
+ * const result = await client.documents.send({
+ *   receiverPeppolId: '0245:1234567890',
+ *   items: [{ description: 'Consulting', quantity: 10, unitPrice: 100, vatRate: 23 }],
+ * });
+ *
+ * // Check delivery status
+ * const status = await client.documents.status(result.documentId);
+ * ```
+ */
 export class DocumentsResource extends BaseResource {
-    /** Access received documents */
+    /** Sub-resource for managing received (inbound) documents */
     inbox;
     constructor(config) {
         super(config);
         this.inbox = new InboxResource(config);
     }
+    /**
+     * Retrieve a single document by ID.
+     *
+     * @param id - Document UUID
+     * @returns Full document object including parties, lines, and totals
+     *
+     * @example
+     * ```typescript
+     * const doc = await client.documents.get('doc-uuid');
+     * console.log(doc.totals.withVat); // 1230.00
+     * ```
+     */
     get(id) {
         return this.request("GET", `/documents/${encodeURIComponent(id)}`);
     }
+    /**
+     * Update a draft document. Only documents that have not been sent yet can be updated.
+     * Pass `null` to clear optional fields, or omit them to leave unchanged.
+     *
+     * @param id - Document UUID of the draft to update
+     * @param body - Fields to update
+     * @returns The updated document
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.documents.update('doc-uuid', {
+     *   dueDate: '2026-05-15',
+     *   note: 'Updated payment terms',
+     * });
+     * ```
+     */
     update(id, body) {
         return this.request("PATCH", `/documents/${encodeURIComponent(id)}`, body);
     }
+    /**
+     * Send an invoice via the Peppol network. Accepts either structured JSON
+     * (the API generates UBL XML) or pre-built UBL XML.
+     *
+     * @param body - Invoice data as JSON fields or raw UBL XML
+     * @returns Document ID, Peppol message ID, and status confirmation
+     *
+     * @example
+     * ```typescript
+     * // Send using JSON (API generates UBL)
+     * const result = await client.documents.send({
+     *   receiverPeppolId: '0245:1234567890',
+     *   invoiceNumber: 'FV-2026-042',
+     *   items: [
+     *     { description: 'Web development', quantity: 40, unit: 'HUR', unitPrice: 80, vatRate: 23 },
+     *   ],
+     * });
+     *
+     * // Send using raw UBL XML
+     * const result = await client.documents.send({
+     *   receiverPeppolId: '0245:1234567890',
+     *   xml: '<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">...</Invoice>',
+     * });
+     * ```
+     */
     send(body) {
         return this.request("POST", "/documents/send", body);
     }
+    /**
+     * Get the current delivery status and full status history of a document.
+     * Use this to track whether a sent invoice was delivered, acknowledged, or failed.
+     *
+     * @param id - Document UUID
+     * @returns Status details including history timeline and delivery timestamps
+     *
+     * @example
+     * ```typescript
+     * const status = await client.documents.status('doc-uuid');
+     * console.log(status.status); // "DELIVERED"
+     * console.log(status.deliveredAt); // "2026-04-11T12:30:00Z"
+     * ```
+     */
     status(id) {
         return this.request("GET", `/documents/${encodeURIComponent(id)}/status`);
     }
+    /**
+     * Retrieve delivery evidence for a sent document, including AS4 receipts,
+     * Message Level Response (MLR), and Invoice Response from the buyer.
+     *
+     * @param id - Document UUID
+     * @returns Evidence records (AS4 receipt, MLR, Invoice Response)
+     *
+     * @example
+     * ```typescript
+     * const evidence = await client.documents.evidence('doc-uuid');
+     * if (evidence.invoiceResponse?.status === 'AP') {
+     *   console.log('Invoice was accepted by the buyer');
+     * }
+     * ```
+     */
     evidence(id) {
         return this.request("GET", `/documents/${encodeURIComponent(id)}/evidence`);
     }
+    /**
+     * Download the PDF visualization of a document.
+     *
+     * @param id - Document UUID
+     * @returns PDF file content as a Buffer
+     *
+     * @example
+     * ```typescript
+     * import { writeFileSync } from 'fs';
+     *
+     * const pdfBuffer = await client.documents.pdf('doc-uuid');
+     * writeFileSync('invoice.pdf', pdfBuffer);
+     * ```
+     */
     async pdf(id) {
         const res = await this.request("GET", `/documents/${encodeURIComponent(id)}/pdf`, undefined, { rawResponse: true });
         return Buffer.from(await res.arrayBuffer());
     }
+    /**
+     * Download the UBL XML of a document.
+     *
+     * @param id - Document UUID
+     * @returns UBL 2.1 XML content as a string
+     *
+     * @example
+     * ```typescript
+     * const xml = await client.documents.ubl('doc-uuid');
+     * console.log(xml); // "<?xml version="1.0"?><Invoice ...>...</Invoice>"
+     * ```
+     */
     async ubl(id) {
         const res = await this.request("GET", `/documents/${encodeURIComponent(id)}/ubl`, undefined, { rawResponse: true });
         return res.text();
     }
+    /**
+     * Send an Invoice Response (accept, reject, or query) for a received document.
+     * This sends a Peppol Invoice Response message back to the supplier.
+     *
+     * @param id - Document UUID of the received invoice
+     * @param body - Response status and optional note
+     * @returns Confirmation with the response status and timestamp
+     *
+     * @example
+     * ```typescript
+     * // Accept an invoice
+     * await client.documents.respond('doc-uuid', { status: 'AP' });
+     *
+     * // Reject with a reason
+     * await client.documents.respond('doc-uuid', {
+     *   status: 'RE',
+     *   note: 'Incorrect VAT rate applied',
+     * });
+     * ```
+     */
     respond(id, body) {
         return this.request("POST", `/documents/${encodeURIComponent(id)}/respond`, body);
     }
+    /**
+     * Validate a document without sending it. Checks Peppol BIS 3.0 compliance
+     * and returns warnings. For JSON input, also returns the generated UBL XML preview.
+     *
+     * @param body - Document data to validate (same format as `send()`)
+     * @returns Validation result with warnings and optional UBL preview
+     *
+     * @example
+     * ```typescript
+     * const result = await client.documents.validate({
+     *   receiverPeppolId: '0245:1234567890',
+     *   items: [{ description: 'Test', quantity: 1, unitPrice: 100, vatRate: 23 }],
+     * });
+     * if (!result.valid) {
+     *   console.error('Validation failed:', result.warnings);
+     * }
+     * ```
+     */
     validate(body) {
         return this.request("POST", "/documents/validate", body);
     }
+    /**
+     * Check if a Peppol receiver is registered and supports the target document type
+     * before sending. Use this to avoid sending to non-existent participants.
+     *
+     * @param body - Receiver Peppol ID and optional document type to check
+     * @returns Preflight result with registration and capability info
+     *
+     * @example
+     * ```typescript
+     * const check = await client.documents.preflight({
+     *   receiverPeppolId: '0245:1234567890',
+     * });
+     * if (!check.registered) {
+     *   console.error('Receiver is not on the Peppol network');
+     * }
+     * ```
+     */
     preflight(body) {
         return this.request("POST", "/documents/preflight", body);
     }
+    /**
+     * Convert between JSON and UBL XML formats without sending.
+     * Useful for previewing the UBL output or parsing received XML into structured data.
+     *
+     * @param body - Conversion request with direction and input data
+     * @returns Converted output (UBL XML string or parsed JSON object)
+     *
+     * @example
+     * ```typescript
+     * // JSON to UBL
+     * const { result: ublXml } = await client.documents.convert({
+     *   direction: 'json_to_ubl',
+     *   data: { invoiceNumber: 'FV-001', items: [...] },
+     * });
+     *
+     * // UBL to JSON
+     * const { result: parsed } = await client.documents.convert({
+     *   direction: 'ubl_to_json',
+     *   xml: '<Invoice>...</Invoice>',
+     * });
+     * ```
+     */
     convert(body) {
         return this.request("POST", "/documents/convert", body);
     }

package/dist/resources/documents.js.map

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

package/dist/resources/extract.d.ts

@@ -1,7 +1,65 @@
 import { BaseResource } from "../utils/request.js";
 import type { ExtractResult, BatchExtractResult } from "../types.js";
+/**
+ * Resource for AI-powered data extraction from PDF invoices and scanned images.
+ * Extracts structured invoice data (parties, line items, totals) and generates
+ * UBL 2.1 XML that can be sent via Peppol.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'fs';
+ *
+ * const pdf = readFileSync('invoice.pdf');
+ * const result = await client.extract.single(pdf, 'application/pdf', 'invoice.pdf');
+ * console.log(result.confidence); // 0.95
+ * console.log(result.ubl_xml); // Generated UBL XML
+ * ```
+ */
 export declare class ExtractResource extends BaseResource {
+    /**
+     * Extract structured data from a single PDF or image file.
+     * Uses AI-powered OCR to identify invoice fields, line items, parties, and totals,
+     * then generates UBL 2.1 XML from the extracted data.
+     *
+     * @param file - File content as a Buffer or Blob
+     * @param mimeType - MIME type of the file (e.g. `"application/pdf"`, `"image/png"`)
+     * @param fileName - Original file name for reference (defaults to `"document"`)
+     * @returns Extracted data, generated UBL XML, and confidence score
+     *
+     * @example
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     *
+     * const pdf = readFileSync('invoice.pdf');
+     * const result = await client.extract.single(pdf, 'application/pdf', 'invoice.pdf');
+     * if (result.confidence > 0.8) {
+     *   // Use the generated UBL to send via Peppol
+     *   await client.documents.send({
+     *     receiverPeppolId: '0245:1234567890',
+     *     xml: result.ubl_xml,
+     *   });
+     * }
+     * ```
+     */
     single(file: Buffer | Blob, mimeType: string, fileName?: string): Promise<ExtractResult>;
+    /**
+     * Extract structured data from multiple PDF or image files in a single request.
+     * Each file is processed independently — individual failures don't affect others.
+     *
+     * @param files - Array of files with their MIME types and optional file names
+     * @returns Batch result with individual outcomes per file and success/failure counts
+     *
+     * @example
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     *
+     * const result = await client.extract.batch([
+     *   { file: readFileSync('invoice1.pdf'), mimeType: 'application/pdf', fileName: 'invoice1.pdf' },
+     *   { file: readFileSync('invoice2.pdf'), mimeType: 'application/pdf', fileName: 'invoice2.pdf' },
+     * ]);
+     * console.log(`${result.successful}/${result.total} extracted successfully`);
+     * ```
+     */
     batch(files: Array<{
         file: Buffer | Blob;
         mimeType: string;

package/dist/resources/extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/resources/extract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAErE,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAO5F,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAQ/G"}
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/resources/extract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAgB,SAAQ,YAAY;IAC/C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CACJ,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAa,GACpB,OAAO,CAAC,aAAa,CAAC;IAUzB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CACH,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GACzE,OAAO,CAAC,kBAAkB,CAAC;CAW/B"}

package/dist/resources/extract.js

@@ -1,15 +1,77 @@
 import { BaseResource } from "../utils/request.js";
+/**
+ * Resource for AI-powered data extraction from PDF invoices and scanned images.
+ * Extracts structured invoice data (parties, line items, totals) and generates
+ * UBL 2.1 XML that can be sent via Peppol.
+ *
+ * @example
+ * ```typescript
+ * import { readFileSync } from 'fs';
+ *
+ * const pdf = readFileSync('invoice.pdf');
+ * const result = await client.extract.single(pdf, 'application/pdf', 'invoice.pdf');
+ * console.log(result.confidence); // 0.95
+ * console.log(result.ubl_xml); // Generated UBL XML
+ * ```
+ */
 export class ExtractResource extends BaseResource {
+    /**
+     * Extract structured data from a single PDF or image file.
+     * Uses AI-powered OCR to identify invoice fields, line items, parties, and totals,
+     * then generates UBL 2.1 XML from the extracted data.
+     *
+     * @param file - File content as a Buffer or Blob
+     * @param mimeType - MIME type of the file (e.g. `"application/pdf"`, `"image/png"`)
+     * @param fileName - Original file name for reference (defaults to `"document"`)
+     * @returns Extracted data, generated UBL XML, and confidence score
+     *
+     * @example
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     *
+     * const pdf = readFileSync('invoice.pdf');
+     * const result = await client.extract.single(pdf, 'application/pdf', 'invoice.pdf');
+     * if (result.confidence > 0.8) {
+     *   // Use the generated UBL to send via Peppol
+     *   await client.documents.send({
+     *     receiverPeppolId: '0245:1234567890',
+     *     xml: result.ubl_xml,
+     *   });
+     * }
+     * ```
+     */
     single(file, mimeType, fileName = "document") {
         const form = new FormData();
-        const blob = file instanceof Blob ? file : new Blob([new Uint8Array(file)], { type: mimeType });
+        const blob = file instanceof Blob
+            ? file
+            : new Blob([new Uint8Array(file)], { type: mimeType });
         form.append("file", blob, fileName);
         return this.request("POST", "/extract", form);
     }
+    /**
+     * Extract structured data from multiple PDF or image files in a single request.
+     * Each file is processed independently — individual failures don't affect others.
+     *
+     * @param files - Array of files with their MIME types and optional file names
+     * @returns Batch result with individual outcomes per file and success/failure counts
+     *
+     * @example
+     * ```typescript
+     * import { readFileSync } from 'fs';
+     *
+     * const result = await client.extract.batch([
+     *   { file: readFileSync('invoice1.pdf'), mimeType: 'application/pdf', fileName: 'invoice1.pdf' },
+     *   { file: readFileSync('invoice2.pdf'), mimeType: 'application/pdf', fileName: 'invoice2.pdf' },
+     * ]);
+     * console.log(`${result.successful}/${result.total} extracted successfully`);
+     * ```
+     */
     batch(files) {
         const form = new FormData();
         for (const { file, mimeType, fileName } of files) {
-            const blob = file instanceof Blob ? file : new Blob([new Uint8Array(file)], { type: mimeType });
+            const blob = file instanceof Blob
+                ? file
+                : new Blob([new Uint8Array(file)], { type: mimeType });
             form.append("files", blob, fileName ?? "document");
         }
         return this.request("POST", "/extract/batch", form);

package/dist/resources/extract.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/resources/extract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/C,MAAM,CAAC,IAAmB,EAAE,QAAgB,EAAE,QAAQ,GAAG,UAAU;QACjE,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAChG,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,KAAK,CAAC,KAA0E;QAC9E,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,KAAK,EAAE,CAAC;YACjD,MAAM,IAAI,GAAG,IAAI,YAAY,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;YAChG,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,IAAI,UAAU,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;CACF"}
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/resources/extract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CACJ,IAAmB,EACnB,QAAgB,EAChB,QAAQ,GAAG,UAAU;QAErB,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,GACR,IAAI,YAAY,IAAI;YAClB,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CACH,KAA0E;QAE1E,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC5B,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,KAAK,EAAE,CAAC;YACjD,MAAM,IAAI,GACR,IAAI,YAAY,IAAI;gBAClB,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,IAAI,UAAU,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;IACtD,CAAC;CACF"}

package/dist/resources/firms.d.ts

@@ -1,14 +1,118 @@
 import { BaseResource } from "../utils/request.js";
 import type { FirmSummary, FirmDetail, FirmDocumentsParams, InboxListResponse, PeppolIdentifierResponse, AssignFirmRequest, AssignFirmResponse, BatchAssignFirmsRequest, BatchAssignFirmsResponse } from "../types.js";
+/**
+ * Resource for managing firms (companies) associated with your account.
+ * Integrators use this to assign client firms, view their documents,
+ * and register Peppol identifiers.
+ *
+ * @example
+ * ```typescript
+ * // List all managed firms
+ * const firms = await client.firms.list();
+ *
+ * // Assign a new firm by ICO
+ * const { firm } = await client.firms.assign({ ico: '12345678' });
+ * ```
+ */
 export declare class FirmsResource extends BaseResource {
+    /**
+     * List all firms associated with the current account.
+     * For integrator keys, returns all assigned client firms.
+     *
+     * @returns Array of firm summaries
+     *
+     * @example
+     * ```typescript
+     * const firms = await client.firms.list();
+     * firms.forEach(f => console.log(f.name, f.peppolStatus));
+     * ```
+     */
     list(): Promise<FirmSummary[]>;
+    /**
+     * Get detailed information about a specific firm, including tax IDs,
+     * address, and all registered Peppol identifiers.
+     *
+     * @param id - Firm UUID
+     * @returns Detailed firm information
+     *
+     * @example
+     * ```typescript
+     * const firm = await client.firms.get('firm-uuid');
+     * console.log(firm.icDph); // "SK2020123456"
+     * ```
+     */
     get(id: string): Promise<FirmDetail>;
+    /**
+     * List documents belonging to a specific firm.
+     * Useful for integrators to view a client's document history.
+     *
+     * @param id - Firm UUID
+     * @param params - Optional pagination and direction filter
+     * @returns Paginated list of the firm's documents
+     *
+     * @example
+     * ```typescript
+     * const { documents } = await client.firms.documents('firm-uuid', {
+     *   direction: 'inbound',
+     *   limit: 100,
+     * });
+     * ```
+     */
     documents(id: string, params?: FirmDocumentsParams): Promise<InboxListResponse>;
+    /**
+     * Register a new Peppol identifier for a firm. This enables the firm
+     * to send and receive documents on the Peppol network under this identifier.
+     *
+     * @param id - Firm UUID
+     * @param peppolId - Peppol identifier with scheme and value
+     * @returns The registered identifier details
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firms.registerPeppolId('firm-uuid', {
+     *   scheme: '0245',
+     *   identifier: '1234567890',
+     * });
+     * console.log(result.peppolId); // "0245:1234567890"
+     * ```
+     */
     registerPeppolId(id: string, peppolId: {
         scheme: string;
         identifier: string;
     }): Promise<PeppolIdentifierResponse>;
+    /**
+     * Assign a firm to the integrator account by its Slovak ICO.
+     * Once assigned, you can send/receive documents on behalf of this firm.
+     *
+     * @param body - Request containing the firm's ICO (8-digit Slovak business registration number)
+     * @returns The assigned firm details and status
+     *
+     * @example
+     * ```typescript
+     * const { firm } = await client.firms.assign({ ico: '12345678' });
+     * console.log(firm.id); // Use this UUID for subsequent operations
+     * ```
+     */
     assign(body: AssignFirmRequest): Promise<AssignFirmResponse>;
+    /**
+     * Assign multiple firms at once by their Slovak ICOs.
+     * Each ICO is processed independently — individual failures don't affect others.
+     * Maximum 50 ICOs per request.
+     *
+     * @param body - Request containing an array of ICOs
+     * @returns Individual results for each ICO (success or error)
+     *
+     * @example
+     * ```typescript
+     * const { results } = await client.firms.assignBatch({
+     *   icos: ['12345678', '87654321', '11223344'],
+     * });
+     * results.forEach(r => {
+     *   if (r.error) console.error(`${r.ico}: ${r.message}`);
+     *   else console.log(`${r.ico}: ${r.status}`);
+     * });
+     * ```
+     */
     assignBatch(body: BatchAssignFirmsRequest): Promise<BatchAssignFirmsResponse>;
 }
 //# sourceMappingURL=firms.d.ts.map

package/dist/resources/firms.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"firms.d.ts","sourceRoot":"","sources":["../../src/resources/firms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EAEV,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAErB,qBAAa,aAAc,SAAQ,YAAY;IACvC,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAKpC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIpC,SAAS,CACP,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAW7B,gBAAgB,CACd,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC/C,OAAO,CAAC,wBAAwB,CAAC;IAQpC,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI5D,WAAW,CACT,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,wBAAwB,CAAC;CAGrC"}
+{"version":3,"file":"firms.d.ts","sourceRoot":"","sources":["../../src/resources/firms.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAc,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EAEV,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C;;;;;;;;;;;OAWG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAKpC;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIpC;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CACP,EAAE,EAAE,MAAM,EACV,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IAW7B;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CACd,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAC/C,OAAO,CAAC,wBAAwB,CAAC;IAQpC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CACT,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,wBAAwB,CAAC;CAGrC"}