@getpeppr/sdk 0.1.0

package/README.md

@@ -0,0 +1,463 @@
+# @getpeppr/sdk
+
+Send Peppol e-invoices in 5 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/)
+
+```typescript
+import { Peppol } from "@getpeppr/sdk";
+
+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" },
+  lines: [
+    { description: "Consulting services", quantity: 10, unitPrice: 150, vatRate: 21 },
+  ],
+});
+
+console.log(`Invoice sent! Status: ${result.status}`);
+```
+
+## Installation
+
+```bash
+npm install @getpeppr/sdk
+```
+
+## Features
+
+- **Stripe-like developer experience** -- 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
+- **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 },
+  ],
+});
+
+console.log(result.id);     // "inv-abc123"
+console.log(result.status); // "new" | "sent" | ...
+```
+
+### Full invoice with all options
+
+```typescript
+const result = await peppol.invoices.send({
+  // Required
+  number: "INV-2026-001",
+  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
+
+```typescript
+const result = 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" },
+  lines: [
+    { description: "Refund for consulting services", quantity: 2, unitPrice: 150, vatRate: 21 },
+  ],
+});
+```
+
+## Listing Invoices
+
+### Single page
+
+```typescript
+const page = await peppol.invoices.list({
+  limit: 25,
+  offset: 0,
+  type: "issued",        // "issued" | "received"
+  includeLines: true,    // Include line item details
+});
+
+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.
+```
+
+### Wait for a specific status
+
+```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)
+});
+```
+
+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
+
+```typescript
+const result = await peppol.invoices.acknowledge("inv-abc123");
+console.log(result.status); // "accepted"
+```
+
+## Batch Send
+
+```typescript
+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)
+});
+
+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)
+
+```typescript
+const result = peppol.validate({
+  number: "INV-001",
+  to: { name: "Acme", peppolId: "0208:BE9876543210", 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)
+
+```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);
+}
+```
+
+### Auto-paginate all events
+
+```typescript
+for await (const event of peppol.events.listAll({ invoiceId: "inv-abc123" })) {
+  console.log(event.name, event.createdAt);
+}
+```
+
+## Webhooks
+
+Verify and parse incoming webhook payloads with HMAC-SHA256 signature verification and replay protection.
+
+```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):
+
+```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 }],
+});
+
+console.log(xml); // Full UBL 2.1 Invoice XML
+```
+
+## Error Handling
+
+The SDK provides three error classes for precise error handling:
+
+```typescript
+import { Peppol, PeppolError, PeppolValidationError, PeppolApiError } from "@getpeppr/sdk";
+
+try {
+  await peppol.invoices.send(input);
+} catch (err) {
+  if (err instanceof PeppolValidationError) {
+    // Client-side validation failed
+    console.log(err.validation.errors);  // ValidationError[]
+    console.log(err.validation.warnings); // ValidationWarning[]
+  } else if (err instanceof PeppolApiError) {
+    // API returned an error
+    console.log(err.statusCode);    // HTTP status code
+    console.log(err.responseBody);  // Raw response body
+    console.log(err.retryAfterMs);  // Retry-After delay (on 429)
+  } else if (err instanceof PeppolError) {
+    // General SDK error (invalid config, timeout, etc.)
+    console.log(err.message);
+  }
+}
+```
+
+### Automatic retries
+
+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.
+
+## License
+
+MIT