@epostak/sdk 1.0.0 → 1.1.0

package/README.md

@@ -14,16 +14,15 @@ npm install @epostak/sdk
 
 ---
 
-## Quick start
+## Quick Start
 
 ```typescript
 import { EPostak } from "@epostak/sdk";
 
 const client = new EPostak({ apiKey: "sk_live_xxxxx" });
 
-// Send an invoice
 const result = await client.documents.send({
-  receiverPeppolId: "0191:12345678",
+  receiverPeppolId: "0245:1234567890",
   invoiceNumber: "FV-2026-001",
   issueDate: "2026-04-04",
   dueDate: "2026-04-18",
@@ -36,6 +35,15 @@ console.log(result.documentId, result.messageId);
 
 ---
 
+## Peppol ID Formats (Slovakia)
+
+| Scheme | Identifier              | Format              | Example             |
+| ------ | ----------------------- | ------------------- | ------------------- |
+| `0245` | DIČ                     | `0245:XXXXXXXXXX`   | `0245:1234567890`   |
+| `9950` | IČ DPH (with SK prefix) | `9950:SKXXXXXXXXXX` | `9950:SK1234567890` |
+
+---
+
 ## Authentication
 
 | Key prefix  | Use case                                           |
@@ -43,15 +51,11 @@ console.log(result.documentId, result.messageId);
 | `sk_live_*` | Direct access — acts on behalf of your own firm    |
 | `sk_int_*`  | Integrator access — acts on behalf of client firms |
 
-Generate keys in your ePošťák firm settings or via the dashboard.
-
-### Constructor options
-
 ```typescript
 const client = new EPostak({
-  apiKey: "sk_live_xxxxx", // Required
-  baseUrl: "https://...", // Optional, defaults to https://epostak.sk/api/enterprise
-  firmId: "uuid", // Optional, required for integrator keys
+  apiKey: "sk_live_xxxxx",
+  baseUrl: "https://...", // optional, defaults to https://epostak.sk/api/enterprise
+  firmId: "uuid", // optional, required for integrator keys
 });
 ```
 
@@ -61,528 +65,222 @@ const client = new EPostak({
 
 ### Documents
 
-#### `documents.send(body)` — Send a document via Peppol
-
-**JSON mode** — structured data, UBL XML is auto-generated:
-
 ```typescript
+// Send a document (JSON mode — UBL auto-generated)
 const result = await client.documents.send({
-  receiverPeppolId: "0191:12345678",
+  receiverPeppolId: "0245:1234567890",
   receiverName: "Firma s.r.o.",
-  receiverIco: "12345678",
-  receiverCountry: "SK",
   invoiceNumber: "FV-2026-001",
   issueDate: "2026-04-04",
   dueDate: "2026-04-18",
   currency: "EUR",
-  iban: "SK1234567890123456789012",
-  items: [
-    { description: "Konzultácia", quantity: 10, unitPrice: 50, vatRate: 23 },
-  ],
+  items: [{ description: "Konzultácia", quantity: 10, unitPrice: 50, vatRate: 23 }],
 });
-// → { documentId, messageId, status: 'SENT' }
-```
 
-**XML mode** — send a pre-built UBL XML document:
-
-```typescript
+// Send pre-built UBL XML
 await client.documents.send({
-  receiverPeppolId: "0191:12345678",
-  xml: '<?xml version="1.0" encoding="UTF-8"?>...',
+  receiverPeppolId: "0245:1234567890",
+  xml: '<?xml version="1.0"?>...',
 });
-```
 
-#### `documents.get(id)` — Get a document by ID
-
-```typescript
+// Get document by ID
 const doc = await client.documents.get("doc-uuid");
-// → { id, number, status, direction, docType, issueDate, dueDate, currency,
-//     supplier, customer, lines, totals, peppolMessageId, createdAt, updatedAt }
-```
-
-#### `documents.update(id, body)` — Update a draft document
-
-Only documents with status `draft` can be updated. All fields are optional.
-
-```typescript
-const updated = await client.documents.update("doc-uuid", {
-  invoiceNumber: "FV-2026-002",
-  dueDate: "2026-05-01",
-  items: [{ description: "Vývoj", quantity: 20, unitPrice: 75, vatRate: 23 }],
-});
-```
 
-#### `documents.status(id)` — Full status with history
+// Update a draft document
+await client.documents.update("doc-uuid", { invoiceNumber: "FV-2026-002", dueDate: "2026-05-01" });
 
-```typescript
+// Status with full history
 const status = await client.documents.status("doc-uuid");
-// → { id, status, documentType, senderPeppolId, receiverPeppolId,
-//     statusHistory: [{ status, timestamp, detail }],
-//     validationResult, deliveredAt, acknowledgedAt,
-//     invoiceResponseStatus, as4MessageId, createdAt, updatedAt }
-```
 
-#### `documents.evidence(id)` — Delivery evidence
-
-```typescript
+// Delivery evidence (AS4, MLR, invoice response)
 const evidence = await client.documents.evidence("doc-uuid");
-// → { documentId, as4Receipt, mlrDocument,
-//     invoiceResponse: { status, document } | null,
-//     deliveredAt, sentAt }
-```
 
-#### `documents.pdf(id)` — Download PDF as Buffer
-
-```typescript
+// Download PDF / UBL XML
 const pdf = await client.documents.pdf("doc-uuid");
-require("fs").writeFileSync("invoice.pdf", pdf);
-```
-
-#### `documents.ubl(id)` — Download UBL XML as string
-
-```typescript
 const ubl = await client.documents.ubl("doc-uuid");
-```
-
-#### `documents.respond(id, body)` — Send invoice response
 
-Send an invoice response (accept, reject, or query) for a received document.
+// Respond to received invoice (AP=accept, RE=reject, UQ=query)
+await client.documents.respond("doc-uuid", { status: "AP", note: "Akceptované" });
 
-```typescript
-await client.documents.respond("doc-uuid", {
-  status: "AP", // 'AP' = accepted, 'RE' = rejected, 'UQ' = under query
-  note: "Faktúra akceptovaná",
-});
-// → { documentId, responseStatus, respondedAt }
-```
+// Validate without sending
+const validation = await client.documents.validate({ receiverPeppolId: "0245:1234567890", items: [...] });
 
-#### `documents.validate(body)` — Validate without sending
+// Check receiver capability
+const check = await client.documents.preflight({ receiverPeppolId: "0245:1234567890" });
 
-```typescript
-const validation = await client.documents.validate({
-  receiverPeppolId: "0191:12345678",
-  items: [{ description: "Test", quantity: 1, unitPrice: 100, vatRate: 23 }],
-});
-// → { valid: boolean, warnings: string[], ubl: string | null }
+// Convert between JSON and UBL
+const converted = await client.documents.convert({ direction: "json_to_ubl", data: { ... } });
 ```
 
-#### `documents.preflight(body)` — Check receiver capability
-
-```typescript
-const check = await client.documents.preflight({
-  receiverPeppolId: "0191:12345678",
-  documentTypeId: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
-});
-// → { receiverPeppolId, registered, supportsDocumentType, smpUrl }
-```
-
-#### `documents.convert(body)` — Convert between JSON and UBL
-
-```typescript
-// JSON → UBL
-const result = await client.documents.convert({
-  direction: 'json_to_ubl',
-  data: { invoiceNumber: 'FV-001', items: [...] },
-});
-
-// UBL → JSON
-const result = await client.documents.convert({
-  direction: 'ubl_to_json',
-  xml: '<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">...',
-});
-```
-
----
-
 ### Inbox
 
-#### `documents.inbox.list(params?)` — List received documents
-
 ```typescript
+// List received documents
 const inbox = await client.documents.inbox.list({
-  limit: 20, // 1–100, default 20
-  offset: 0,
-  status: "RECEIVED", // 'RECEIVED' | 'ACKNOWLEDGED'
-  since: "2026-04-01T00:00:00Z", // ISO 8601
+  limit: 20,
+  status: "RECEIVED",
+  since: "2026-04-01T00:00:00Z",
 });
-// → { documents: InboxDocument[], total, limit, offset }
-```
 
-#### `documents.inbox.get(id)` — Full detail with UBL XML
-
-```typescript
+// Get full detail with UBL XML payload
 const detail = await client.documents.inbox.get("doc-uuid");
-console.log(detail.document); // InboxDocument
-console.log(detail.payload); // UBL XML string or null
-```
+console.log(detail.document, detail.payload);
 
-#### `documents.inbox.acknowledge(id)` — Mark as processed
-
-```typescript
+// Acknowledge (mark as processed)
 await client.documents.inbox.acknowledge("doc-uuid");
-// → { documentId, status: 'ACKNOWLEDGED', acknowledgedAt }
-```
-
-#### `documents.inbox.listAll(params?)` — Cross-firm inbox (integrator)
-
-List received documents across all firms linked to an integrator key.
 
-```typescript
+// Cross-firm inbox (integrator only)
 const all = await client.documents.inbox.listAll({
-  limit: 50, // 1–200, default 50
-  offset: 0,
-  status: "RECEIVED",
-  since: "2026-04-01T00:00:00Z",
-  firm_id: "specific-firm-uuid", // Optional filter
+  limit: 50,
+  firm_id: "firm-uuid",
 });
-// → { documents: InboxAllDocument[], total, limit, offset }
-// Each document includes firm_id and firm_name
 ```
 
----
-
 ### Peppol
 
-#### `peppol.lookup(scheme, identifier)` — SMP participant lookup
-
 ```typescript
-const participant = await client.peppol.lookup("0191", "12345678");
-// → { peppolId, name, country, capabilities: [{ documentTypeId, processId, transportProfile }] }
-```
-
-#### `peppol.directory.search(params?)` — Business Card directory
+// SMP participant lookup
+const participant = await client.peppol.lookup("0245", "1234567890");
 
-```typescript
+// Peppol directory search
 const results = await client.peppol.directory.search({
   q: "Telekom",
   country: "SK",
-  page: 0,
-  page_size: 20,
 });
-// → { results: DirectoryEntry[], total, page, page_size }
-```
-
-#### `peppol.companyLookup(ico)` — Slovak company lookup
 
-```typescript
+// Company lookup by ICO
 const company = await client.peppol.companyLookup("12345678");
-// → { ico, name, dic, icDph, address, peppolId }
 ```
 
----
-
-### Firms (integrator keys)
-
-#### `firms.list()` — List all accessible firms
+### Firms (integrator)
 
 ```typescript
 const firms = await client.firms.list();
-// → FirmSummary[] — [{ id, name, ico, peppolId, peppolStatus }]
-```
-
-#### `firms.get(id)` — Firm detail
-
-```typescript
 const firm = await client.firms.get("firm-uuid");
-// → { id, name, ico, peppolId, peppolStatus, dic, icDph, address,
-//     peppolIdentifiers: [{ scheme, identifier }], createdAt }
-```
-
-#### `firms.documents(id, params?)` — List firm documents
-
-```typescript
 const docs = await client.firms.documents("firm-uuid", {
   limit: 20,
-  direction: "inbound", // 'inbound' | 'outbound'
+  direction: "inbound",
 });
-```
-
-#### `firms.registerPeppolId(id, peppolId)` — Register Peppol ID
-
-```typescript
 await client.firms.registerPeppolId("firm-uuid", {
-  scheme: "0191",
-  identifier: "12345678",
+  scheme: "0245",
+  identifier: "1234567890",
 });
-// → { peppolId, scheme, identifier, registeredAt }
-```
 
-#### `firms.assign(body)` — Assign firm to integrator
-
-Assign an existing ePošťák firm to this integrator by ICO. Requires `firm:manage` scope.
-
-```typescript
-const result = await client.firms.assign({ ico: "12345678" });
-// → { firm: { id, name, ico, peppol_id, peppol_status }, status: 'active' }
+// Assign firm by ICO
+await client.firms.assign({ ico: "12345678" });
+await client.firms.assignBatch({ icos: ["12345678", "87654321"] });
 ```
 
-#### `firms.assignBatch(body)` — Batch assign firms
-
-Assign up to 50 firms in a single request.
-
-```typescript
-const result = await client.firms.assignBatch({
-  icos: ["12345678", "87654321", "11223344"],
-});
-// → { results: [{ ico, firm?, status?, error?, message? }] }
-```
-
----
-
 ### Webhooks
 
-#### `webhooks.create(body)` — Register a webhook
-
 ```typescript
+// Create webhook (store secret for HMAC verification!)
 const webhook = await client.webhooks.create({
   url: "https://example.com/webhook",
   events: ["document.received", "document.sent"],
 });
-// Store webhook.secret for HMAC-SHA256 signature verification
-```
-
-#### `webhooks.list()` — List webhooks
 
-```typescript
-const webhooks = await client.webhooks.list();
-// → Webhook[]
+const list = await client.webhooks.list();
+const detail = await client.webhooks.get(webhook.id);
+await client.webhooks.update(webhook.id, { isActive: false });
+await client.webhooks.delete(webhook.id);
 ```
 
-#### `webhooks.get(id)` — Webhook detail with deliveries
-
-```typescript
-const detail = await client.webhooks.get("webhook-uuid");
-// → { ...webhook, deliveries: WebhookDelivery[] }
-```
-
-#### `webhooks.update(id, body)` — Update webhook
-
-```typescript
-await client.webhooks.update("webhook-uuid", {
-  url: "https://example.com/new-webhook",
-  events: ["document.received"],
-  isActive: true,
-});
-```
-
-#### `webhooks.delete(id)` — Delete webhook
-
-```typescript
-await client.webhooks.delete("webhook-uuid");
-```
-
----
-
 ### Webhook Pull Queue
 
-Alternative to push webhooks — poll for events.
-
-#### `webhooks.queue.pull(params?)` — Fetch pending events
-
 ```typescript
-const queue = await client.webhooks.queue.pull({
-  limit: 50, // 1–100, default 20
-  event_type: "document.received", // Optional filter
-});
+// Pull pending events
+const queue = await client.webhooks.queue.pull({ limit: 50 });
 for (const item of queue.items) {
   console.log(item.id, item.type, item.payload);
+  await client.webhooks.queue.ack(item.id);
 }
-// → { items: [{ id, type, created_at, payload }], has_more: boolean }
-```
-
-#### `webhooks.queue.ack(eventId)` — Acknowledge single event
-
-```typescript
-await client.webhooks.queue.ack("event-uuid");
-// Returns void (HTTP 204)
-```
-
-#### `webhooks.queue.batchAck(eventIds)` — Batch acknowledge
-
-```typescript
-const ids = queue.items.map((e) => e.id);
-await client.webhooks.queue.batchAck(ids);
-// Returns void (HTTP 204)
-```
-
-#### `webhooks.queue.pullAll(params?)` — Cross-firm queue (integrator)
-
-Fetch events across all firms linked to an integrator key.
-
-```typescript
-const queue = await client.webhooks.queue.pullAll({
-  limit: 200, // 1–500, default 100
-  since: "2026-04-01T00:00:00Z",
-});
-for (const event of queue.events) {
-  console.log(event.firm_id, event.event, event.payload);
-}
-// → { events: [{ event_id, firm_id, event, payload, created_at }], count }
-```
 
-#### `webhooks.queue.batchAckAll(eventIds)` — Cross-firm batch ack (integrator)
+// Batch acknowledge
+await client.webhooks.queue.batchAck(queue.items.map((e) => e.id));
 
-```typescript
-const ids = queue.events.map((e) => e.event_id);
-const result = await client.webhooks.queue.batchAckAll(ids);
-console.log(result.acknowledged); // number of events acknowledged
+// Cross-firm (integrator)
+const allEvents = await client.webhooks.queue.pullAll({ limit: 200 });
+await client.webhooks.queue.batchAckAll(
+  allEvents.events.map((e) => e.event_id),
+);
 ```
 
----
-
 ### Reporting
 
-#### `reporting.statistics(params?)` — Aggregated stats
-
 ```typescript
 const stats = await client.reporting.statistics({
   from: "2026-01-01",
   to: "2026-03-31",
 });
-// → { period: { from, to },
-//     outbound: { total, delivered, failed },
-//     inbound: { total, acknowledged, pending } }
 ```
 
----
-
 ### Account
 
-#### `account.get()` — Account info
-
 ```typescript
 const account = await client.account.get();
-// → { firm: { name, ico, peppolId, peppolStatus },
-//     plan: { name, status },
-//     usage: { outbound, inbound } }
 ```
 
----
-
 ### Extract (AI OCR)
 
-Requires Enterprise plan.
-
-#### `extract.single(file, mimeType, fileName?)` — Single file
-
 ```typescript
 import { readFileSync } from "fs";
 
-const pdf = readFileSync("invoice.pdf");
+// Single file
 const result = await client.extract.single(
-  pdf,
+  readFileSync("invoice.pdf"),
   "application/pdf",
   "invoice.pdf",
 );
-// → { extraction: {...}, ubl_xml: string, confidence: number, file_name: string }
-```
-
-Supported MIME types: `application/pdf`, `image/jpeg`, `image/png`, `image/webp`. Max 20 MB.
-
-#### `extract.batch(files)` — Batch extraction (server-side)
 
-Up to 10 files per request. Processed server-side in a single call.
-
-```typescript
-const result = await client.extract.batch([
+// Batch (up to 10 files, server-side)
+const batch = await client.extract.batch([
   { file: pdfBuffer, mimeType: "application/pdf", fileName: "inv1.pdf" },
-  { file: imageBuffer, mimeType: "image/png", fileName: "inv2.png" },
+  { file: imgBuffer, mimeType: "image/png", fileName: "inv2.png" },
 ]);
-// → { batch_id, total, successful, failed,
-//     results: [{ file_name, extraction?, ubl_xml?, confidence?, error? }] }
 ```
 
 ---
 
 ## Integrator Mode
 
-Use `sk_int_*` keys to act on behalf of client firms. Integrator keys unlock multi-tenant endpoints.
-
 ```typescript
-// Option 1: pass firmId in constructor
-const client = new EPostak({ apiKey: 'sk_int_xxxxx', firmId: 'client-firm-uuid' });
-
-// Option 2: scope at call time with withFirm()
-const base = new EPostak({ apiKey: 'sk_int_xxxxx' });
-const clientA = base.withFirm('firm-uuid-a');
-const clientB = base.withFirm('firm-uuid-b');
+// Option 1: firmId in constructor
+const client = new EPostak({
+  apiKey: "sk_int_xxxxx",
+  firmId: "client-firm-uuid",
+});
 
-await clientA.documents.send({ ... });
-await clientB.documents.inbox.list();
+// Option 2: withFirm() for switching
+const base = new EPostak({ apiKey: "sk_int_xxxxx" });
+const clientA = base.withFirm("firm-uuid-a");
+const clientB = base.withFirm("firm-uuid-b");
 ```
 
-### Integrator-only endpoints
-
-These endpoints require an integrator key (`sk_int_*`) and operate across all linked firms:
-
-| Method                            | Description                            |
-| --------------------------------- | -------------------------------------- |
-| `firms.assign({ ico })`           | Link a firm to the integrator          |
-| `firms.assignBatch({ icos })`     | Batch link firms (max 50)              |
-| `documents.inbox.listAll()`       | Cross-firm inbox with `firm_id` filter |
-| `webhooks.queue.pullAll()`        | Cross-firm event queue                 |
-| `webhooks.queue.batchAckAll(ids)` | Cross-firm batch acknowledge           |
-
 ---
 
 ## Error Handling
 
-All errors are thrown as `EPostakError`:
-
 ```typescript
-import { EPostak, EPostakError } from '@epostak/sdk';
+import { EPostak, EPostakError } from "@epostak/sdk";
 
 try {
   await client.documents.send({ ... });
 } catch (err) {
   if (err instanceof EPostakError) {
-    console.error(err.status);   // HTTP status code (0 for network errors)
-    console.error(err.code);     // Machine-readable code, e.g. 'VALIDATION_FAILED'
-    console.error(err.message);  // Human-readable message
-    console.error(err.details);  // Validation details (for 422 errors)
+    console.error(err.status);   // HTTP status (0 for network errors)
+    console.error(err.code);     // e.g. 'VALIDATION_ERROR'
+    console.error(err.message);  // Human-readable
+    console.error(err.details);  // Validation details (422)
   }
 }
 ```
 
-### Common error codes
-
-| Status | Code                   | Meaning                                          |
-| ------ | ---------------------- | ------------------------------------------------ |
-| 400    | `BAD_REQUEST`          | Invalid request body or parameters               |
-| 401    | `UNAUTHORIZED`         | Missing or invalid API key                       |
-| 403    | `FORBIDDEN`            | Insufficient permissions or wrong plan           |
-| 404    | `NOT_FOUND`            | Resource not found                               |
-| 409    | `CONFLICT`             | Duplicate operation (e.g. firm already assigned) |
-| 422    | `UNPROCESSABLE_ENTITY` | Validation failed (check `err.details`)          |
-| 429    | `RATE_LIMITED`         | Too many requests                                |
-| 503    | `SERVICE_UNAVAILABLE`  | Extraction service not configured                |
-
----
-
-## TypeScript Support
-
-The SDK is written in TypeScript with strict mode. All request params and response shapes are fully typed:
-
-```typescript
-import type {
-  SendDocumentJsonRequest,
-  InboxDocument,
-  InboxAllDocument,
-  PeppolParticipant,
-  Webhook,
-  WebhookQueueItem,
-  Statistics,
-  Account,
-  ExtractResult,
-  BatchExtractResult,
-} from "@epostak/sdk";
-```
-
 ---
 
-## Full API Endpoint Map
+## Full Endpoint Map
 
-| SDK Method                         | HTTP   | Path                                 |
+| Method                             | HTTP   | Path                                 |
 | ---------------------------------- | ------ | ------------------------------------ |
 | `documents.get(id)`                | GET    | `/documents/{id}`                    |
 | `documents.update(id, body)`       | PATCH  | `/documents/{id}`                    |
@@ -623,10 +321,10 @@ import type {
 | `extract.single(file, mime)`       | POST   | `/extract`                           |
 | `extract.batch(files)`             | POST   | `/extract/batch`                     |
 
-All paths are relative to `https://epostak.sk/api/enterprise`.
+All paths relative to `https://epostak.sk/api/enterprise`.
 
 ---
 
-## Full API Documentation
+## License
 
-https://epostak.sk/api/docs/enterprise
+MIT