@getpeppr/sdk 0.2.0 → 1.0.0

package/README.md

@@ -1,10 +1,11 @@
 # @getpeppr/sdk
 
-Send Peppol e-invoices in 5 lines of code.
+Send Peppol e-invoices in under 20 lines of code.
 
 [![npm version](https://img.shields.io/npm/v/@getpeppr/sdk.svg)](https://www.npmjs.com/package/@getpeppr/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-first-blue.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node-%3E%3D18-green.svg)](https://nodejs.org/)
 
 ```typescript
 import { Peppol } from "@getpeppr/sdk";
@@ -13,13 +14,20 @@ const peppol = new Peppol({ apiKey: "sk_live_..." });
 
 const result = await peppol.invoices.send({
   number: "INV-2026-001",
-  to: { name: "Acme Corp", peppolId: "0208:BE9876543210", country: "BE" },
+  to: {
+    name: "Acme Corp",
+    peppolId: "0208:BE9876543210",
+    street: "123 Business Ave",
+    city: "Brussels",
+    postalCode: "1000",
+    country: "BE",
+  },
   lines: [
     { description: "Consulting services", quantity: 10, unitPrice: 150, vatRate: 21 },
   ],
 });
 
-console.log(`Invoice sent! Status: ${result.status}`);
+console.log(`Invoice sent! ID: ${result.id}`);
 ```
 
 ## Installation
@@ -30,402 +38,163 @@ npm install @getpeppr/sdk
 
 ## Features
 
-- **Stripe-like developer experience** -- JSON in, Peppol out
+- **Stripe-like DX** -- JSON in, Peppol out
 - **Full Peppol BIS 3.0 compliance** -- UBL 2.1 XML generation handled for you
-- **Client-side + server-side validation** -- catch errors before they reach the network
-- **Create, send, list, acknowledge** invoices
-- **Credit notes** with automatic UBL CreditNote generation
-- **PDF and XML export** -- download invoices in any format
+- **All invoice types** -- standard (380), credit note (381), debit (383), prepayment (386), self-billed (389)
+- **Client-side + server-side validation** -- XSD and Schematron rules
 - **Peppol Directory lookup** -- verify participants before sending
-- **Events API** with async pagination
-- **Batch send** with concurrency control
 - **Webhook signature verification** -- HMAC-SHA256 with replay protection
-- **Built-in retry logic** with exponential backoff and rate limit handling
-- **TypeScript-first** with full type safety
-- **Zero dependencies**
-
-## Configuration
-
-```typescript
-import { Peppol } from "@getpeppr/sdk";
-
-const peppol = new Peppol({
-  apiKey: "sk_live_...",       // Required. Starts with sk_sandbox_ or sk_live_
-  baseUrl: "https://...",      // Custom gateway URL (default: https://api.getpeppr.dev/v1)
-  timeout: 30000,              // Request timeout in ms (default: 30s)
-  retry: {
-    maxRetries: 3,             // Max retry attempts (default: 3)
-    initialDelayMs: 500,       // Initial retry delay (default: 500ms)
-    maxDelayMs: 30000,         // Max retry delay (default: 30s)
-  },
-});
-```
-
-## Sending Invoices
-
-### Basic invoice
-
-```typescript
-const result = await peppol.invoices.send({
-  number: "INV-2026-001",
-  to: {
-    name: "Acme Corp",
-    peppolId: "0208:BE9876543210",
-    country: "BE",
-  },
-  lines: [
-    { description: "Consulting services", quantity: 10, unitPrice: 150, vatRate: 21 },
-  ],
-});
+- **Batch send** with concurrency control
+- **Built-in retry** with exponential backoff and rate limit handling
+- **Async pagination** -- iterate over all invoices, events, contacts
+- **TypeScript-first**, zero dependencies
 
-console.log(result.id);     // "inv-abc123"
-console.log(result.status); // "new" | "sent" | ...
-```
+## Quick Examples
 
-### Full invoice with all options
+### Create draft + send later
 
 ```typescript
-const result = await peppol.invoices.send({
-  // Required
-  number: "INV-2026-001",
+const draft = await peppol.invoices.create({
+  number: "INV-2026-002",
   to: {
     name: "Acme Corp",
     peppolId: "0208:BE9876543210",
-    vatNumber: "BE9876543210",
     street: "123 Business Ave",
     city: "Brussels",
     postalCode: "1000",
     country: "BE",
-    companyId: "0876543210",
-    contactName: "Jane Doe",
-    phone: "+32 2 123 4567",
-    email: "invoices@acme.be",
-  },
-  lines: [
-    {
-      description: "Consulting services",
-      quantity: 10,
-      unit: "hours",          // Human-readable: "hours", "days", "kg", or UN/ECE: "HUR", "DAY"
-      unitPrice: 150,
-      vatRate: 21,
-      vatCategory: "S",       // S=standard, Z=zero-rated, E=exempt, AE=reverse charge
-      itemId: "SRV-001",
-      allowances: [{ reason: "Loyalty discount", amount: 50 }],
-      charges: [{ reason: "Express delivery", amount: 25 }],
-    },
-  ],
-
-  // Optional
-  date: "2026-01-15",                  // Invoice date (default: today)
-  dueDate: "2026-02-15",              // Due date
-  currency: "EUR",                     // ISO 4217 (default: EUR)
-  taxCurrency: "GBP",                 // Tax reporting currency if different
-  taxCurrencyRate: 0.86,              // Exchange rate to tax currency
-  buyerReference: "PO-2026-042",      // Buyer reference (BT-10)
-  orderReference: "ORD-789",          // Purchase order number
-  note: "Thank you for your business",
-  paymentTerms: "Net 30 days",
-  paymentMeans: 30,                    // 30=credit transfer, 58=SEPA
-  paymentIban: "BE68539007547034",
-  paymentBic: "BBRUBEBB",
-  paymentReference: "+++090/9337/55493+++",
-
-  payeeParty: {                        // When payment recipient differs from seller
-    name: "Factoring Co",
-    peppolId: "0208:BE1111111111",
-    country: "BE",
   },
-
-  invoicePeriod: {                     // Billing period (common for SaaS)
-    startDate: "2026-01-01",
-    endDate: "2026-01-31",
-  },
-
-  delivery: {                          // Delivery information
-    date: "2026-01-20",
-    locationId: "LOC-001",
-    address: { street: "456 Warehouse Rd", city: "Antwerp", postalCode: "2000", country: "BE" },
-  },
-
-  allowances: [{ reason: "Volume discount", amount: 100, vatRate: 21 }],
-  charges: [{ reason: "Handling fee", amount: 25, vatRate: 21 }],
-
-  attachments: [
-    {
-      id: "ATT-001",
-      description: "Timesheet",
-      filename: "timesheet.pdf",
-      mimeType: "application/pdf",
-      content: "base64-encoded-content...",    // Or use `url` for external reference
-    },
-  ],
-});
-```
-
-### Create draft + send later
-
-```typescript
-const draft = await peppol.invoices.create({
-  number: "INV-2026-002",
-  to: { name: "Acme Corp", peppolId: "0208:BE9876543210", country: "BE" },
   lines: [{ description: "Consulting", quantity: 5, unitPrice: 200, vatRate: 21 }],
 });
 
-console.log(draft.id);     // "inv-xyz456"
-console.log(draft.status); // "new"
-
 // Send when ready
 await peppol.invoices.sendById(draft.id);
 ```
 
-### Credit notes
+### Credit note
 
 ```typescript
-const result = await peppol.invoices.send({
+const creditNote = await peppol.invoices.send({
   number: "CN-2026-001",
   isCreditNote: true,
-  invoiceReference: "INV-2026-001",  // Required: original invoice number
-  to: { name: "Acme Corp", peppolId: "0208:BE9876543210", country: "BE" },
+  invoiceReference: "INV-2026-001",
+  to: {
+    name: "Acme Corp",
+    peppolId: "0208:BE9876543210",
+    street: "123 Business Ave",
+    city: "Brussels",
+    postalCode: "1000",
+    country: "BE",
+  },
   lines: [
     { description: "Refund for consulting services", quantity: 2, unitPrice: 150, vatRate: 21 },
   ],
 });
 ```
 
-## Listing Invoices
-
-### Single page
+### Webhook verification
 
 ```typescript
-const page = await peppol.invoices.list({
-  limit: 25,
-  offset: 0,
-  type: "issued",        // "issued" | "received"
-  includeLines: true,    // Include line item details
-});
+import { webhooks } from "@getpeppr/sdk";
 
-console.log(page.data);  // InvoiceSummary[]
-console.log(page.meta);  // { totalCount, offset, limit, hasMore }
-```
-
-### Auto-paginate all invoices
-
-```typescript
-for await (const invoice of peppol.invoices.listAll({ type: "issued" })) {
-  console.log(invoice.id, invoice.number, invoice.status);
-}
-```
-
-## Invoice Status
-
-### Get current status
-
-```typescript
-const result = await peppol.invoices.getStatus("inv-abc123");
-console.log(result.status); // "sent", "accepted", etc.
-```
+app.post("/webhooks/peppol", async (req, res) => {
+  try {
+    const event = await webhooks.constructEvent(
+      req.body,                                    // Raw body string (NOT parsed JSON)
+      req.headers["getpeppr-signature"],           // Getpeppr-Signature header
+      "whsec_your_webhook_secret",                 // Your webhook secret
+    );
 
-### Wait for a specific status
+    switch (event.type) {
+      case "invoice.accepted":
+        console.log("Invoice accepted:", event.data);
+        break;
+      case "invoice.received":
+        console.log("New invoice received:", event.data);
+        break;
+    }
 
-```typescript
-const result = await peppol.invoices.waitFor("inv-abc123", "accepted", {
-  timeout: 60000,   // Max wait time in ms (default: 120s)
-  interval: 5000,   // Polling interval in ms (default: 5s)
+    res.sendStatus(200);
+  } catch (err) {
+    res.status(400).send("Webhook verification failed");
+  }
 });
 ```
 
-You can also wait for multiple statuses:
-
-```typescript
-const result = await peppol.invoices.waitFor("inv-abc123", ["accepted", "paid"]);
-```
-
-Terminal failure statuses (`error`, `refused`, `invalid`) throw immediately without waiting for timeout.
-
-### Document status lifecycle
-
-```
-new --> sent --> downloaded --> registered --> accepted --> paid --> closed
-                                           \-> refused
-                            \-> error
-```
-
-## Export PDF / XML
-
-```typescript
-import { writeFileSync } from "fs";
-
-// Export as PDF
-const pdf = await peppol.invoices.getAs("inv-abc123", "pdf");
-writeFileSync("invoice.pdf", Buffer.from(pdf));
-
-// Export as UBL XML
-const xml = await peppol.invoices.getAs("inv-abc123", "xml.ubl.invoice.bis3");
-writeFileSync("invoice.xml", Buffer.from(xml));
-
-// Available formats: "pdf" | "xml.ubl.invoice.bis3" | "xml.facturae.3.2" | "original"
-```
-
-## Acknowledge Received Invoice
+### Directory lookup
 
 ```typescript
-const result = await peppol.invoices.acknowledge("inv-abc123");
-console.log(result.status); // "accepted"
+const entry = await peppol.directory.lookup("0208:BE0123456789");
+console.log(entry.name);         // "My Company NV"
+console.log(entry.country);      // "BE"
+console.log(entry.capabilities); // ["invoice", "credit_note"]
 ```
 
-## Batch Send
+### Batch send
 
 ```typescript
-const invoices = [invoice1, invoice2, invoice3, /* ... */];
+const invoices = [invoice1, invoice2, invoice3];
 
 const result = await peppol.invoices.sendBatch(invoices, {
-  concurrency: 5,      // Max parallel requests (default: 5)
-  stopOnError: false,   // Continue on failure (default: false)
+  concurrency: 5,
+  stopOnError: false,
 });
 
 console.log(`${result.succeeded.length} sent, ${result.failed.length} failed`);
-
-for (const failure of result.failed) {
-  console.error(`Invoice #${failure.index} (${failure.input.number}): ${failure.error.message}`);
-}
 ```
 
-## Peppol Directory
-
-```typescript
-const entry = await peppol.directory.lookup("0208:BE0123456789");
-
-console.log(entry.name);         // "My Company NV"
-console.log(entry.country);      // "BE"
-console.log(entry.capabilities); // ["invoice", "credit_note"]
-```
-
-## Validation
-
-### Client-side validation (instant, offline)
+### Client-side validation
 
 ```typescript
 const result = peppol.validate({
   number: "INV-001",
-  to: { name: "Acme", peppolId: "0208:BE9876543210", country: "BE" },
+  to: {
+    name: "Acme",
+    peppolId: "0208:BE9876543210",
+    street: "123 Business Ave",
+    city: "Brussels",
+    postalCode: "1000",
+    country: "BE",
+  },
   lines: [{ description: "Item", quantity: 1, unitPrice: 100, vatRate: 21 }],
 });
 
 if (!result.valid) {
   for (const err of result.errors) {
     console.log(`${err.field}: ${err.message}`);
-    if (err.suggestion) console.log(`  Fix: ${err.suggestion}`);
   }
 }
-
-for (const warn of result.warnings) {
-  console.log(`Warning: ${warn.field}: ${warn.message}`);
-}
 ```
 
-### Server-side validation (XSD + Schematron)
+### Export PDF / XML
 
 ```typescript
-const result = await peppol.invoices.validateServer({
-  number: "INV-001",
-  to: { name: "Acme", peppolId: "0208:BE9876543210", country: "BE" },
-  lines: [{ description: "Item", quantity: 1, unitPrice: 100, vatRate: 21 }],
-});
-
-console.log(result.valid);              // true/false
-console.log(result.xsd.errors);         // XSD schema errors
-console.log(result.schematron.errors);   // Peppol business rule errors
-console.log(result.schematron.warnings); // Non-blocking warnings
-```
-
-## Events
-
-### List events
-
-```typescript
-const result = await peppol.events.list({
-  limit: 10,
-  invoiceId: "inv-abc123",    // Filter by invoice
-  dateFrom: "2026-01-01",     // Filter by date range
-  dateTo: "2026-01-31",
-});
-
-for (const event of result.data) {
-  console.log(event.name, event.text, event.createdAt);
-}
-```
+import { writeFileSync } from "fs";
 
-### Auto-paginate all events
+const pdf = await peppol.invoices.getAs("inv-abc123", "pdf");
+writeFileSync("invoice.pdf", Buffer.from(pdf));
 
-```typescript
-for await (const event of peppol.events.listAll({ invoiceId: "inv-abc123" })) {
-  console.log(event.name, event.createdAt);
-}
+const xml = await peppol.invoices.getAs("inv-abc123", "xml.ubl.invoice.bis3");
+writeFileSync("invoice.xml", Buffer.from(xml));
 ```
 
-## Webhooks
-
-Verify and parse incoming webhook payloads with HMAC-SHA256 signature verification and replay protection.
+## Configuration
 
 ```typescript
-import { Peppol, webhooks } from "@getpeppr/sdk";
-
-// Express example
-app.post("/webhooks/peppol", async (req, res) => {
-  try {
-    const event = await webhooks.constructEvent(
-      req.body,                                  // Raw body string (NOT parsed JSON)
-      req.headers["x-b2brouter-signature"],      // Signature header
-      "whsec_your_webhook_secret",               // Your webhook secret
-    );
-
-    switch (event.type) {
-      case "invoice.accepted":
-        console.log("Invoice accepted:", event.data);
-        break;
-      case "invoice.refused":
-        console.log("Invoice refused:", event.data);
-        break;
-      case "invoice.received":
-        console.log("New invoice received:", event.data);
-        break;
-    }
-
-    res.sendStatus(200);
-  } catch (err) {
-    console.error("Webhook verification failed:", err.message);
-    res.status(400).send("Webhook verification failed");
-  }
-});
-```
-
-Supported event types:
-
-| Event | Description |
-|-------|-------------|
-| `invoice.sent` | Invoice sent to Peppol network |
-| `invoice.accepted` | Recipient accepted the invoice |
-| `invoice.refused` | Recipient refused the invoice |
-| `invoice.error` | Delivery error |
-| `invoice.registered` | Invoice registered by recipient |
-| `invoice.paid` | Invoice marked as paid |
-| `invoice.closed` | Invoice closed |
-| `invoice.received` | New invoice received |
-| `creditnote.sent` | Credit note sent |
-| `creditnote.received` | Credit note received |
-
-## UBL XML Generation
-
-Generate UBL 2.1 XML without sending (useful for debugging or manual submission):
+import { Peppol } from "@getpeppr/sdk";
 
-```typescript
-const xml = peppol.toXml({
-  number: "INV-001",
-  to: { name: "Acme", peppolId: "0208:BE9876543210", country: "BE" },
-  lines: [{ description: "Item", quantity: 1, unitPrice: 100, vatRate: 21 }],
+const peppol = new Peppol({
+  apiKey: "sk_live_...",       // Required. Starts with sk_sandbox_ or sk_live_
+  baseUrl: "https://...",      // Default: https://api.getpeppr.dev/v1
+  timeout: 30000,              // Request timeout in ms (default: 30s)
+  retry: {
+    maxRetries: 3,             // Max retry attempts (default: 3)
+    initialDelayMs: 500,       // Initial retry delay (default: 500ms)
+    maxDelayMs: 30000,         // Max retry delay (default: 30s)
+  },
+  onRequest: (entry) => {},    // Optional request hook
+  onResponse: (entry) => {},   // Optional response hook
 });
-
-console.log(xml); // Full UBL 2.1 Invoice XML
 ```
 
 ## Error Handling
@@ -440,7 +209,7 @@ try {
 } catch (err) {
   if (err instanceof PeppolValidationError) {
     // Client-side validation failed
-    console.log(err.validation.errors);  // ValidationError[]
+    console.log(err.validation.errors);   // ValidationError[]
     console.log(err.validation.warnings); // ValidationWarning[]
   } else if (err instanceof PeppolApiError) {
     // API returned an error
@@ -454,9 +223,29 @@ try {
 }
 ```
 
-### Automatic retries
+Transient errors (429, 500, 502, 503, 504) are automatically retried with exponential backoff and jitter. Rate limit responses (429) respect the `Retry-After` header.
+
+## Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `invoice.sent` | Invoice sent to the Peppol network |
+| `invoice.accepted` | Recipient accepted the invoice |
+| `invoice.refused` | Recipient refused the invoice |
+| `invoice.error` | Delivery error |
+| `invoice.registered` | Invoice registered by recipient |
+| `invoice.paid` | Invoice marked as paid |
+| `invoice.closed` | Invoice closed |
+| `invoice.received` | New invoice received from the network |
+| `creditnote.sent` | Credit note sent |
+| `creditnote.received` | Credit note received |
+| `test.ping` | Test event for endpoint verification |
+
+## Links
 
-The SDK automatically retries on transient errors (429, 500, 502, 503, 504) with exponential backoff and jitter. Rate limit responses (429) respect the `Retry-After` header.
+- [Documentation](https://getpeppr.dev/docs)
+- [Website](https://getpeppr.dev)
+- [GitHub](https://github.com/zerolooplabs/getpeppr)
 
 ## License