@orvello/sdk 0.1.0

package/CONTRACT_SHA256

@@ -0,0 +1 @@
+4efd4e4b669168c9cab5419fa04dd4e26a2029de2d4b10a59918e366189e1072

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niccas Williams
+
+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,262 @@
+# `@orvello/sdk`
+
+Typed, zero-dependency SDK for integrating Node and Next.js applications with **orvello** — the
+accounting, invoicing, bookkeeping, customer-company and payments platform.
+
+## Features
+
+- **End-to-End Typed**: Autogenerated DTOs, request bodies, and responses directly from the
+  orvello service contract.
+- **Contract Verification**: Built-in runtime diagnostic (`diagnoseOrvello`) to verify that the
+  orvello service you point at speaks the exact contract compiled into the SDK.
+- **Robust HTTP Engine**:
+  - Automatic unwrapping of `ApiEnvelope<T>` returning data directly.
+  - Automatic retry with exponential backoff on retriable errors (5xx, 429, network failures).
+  - Native PDF and binary blob streaming (`Blob`).
+  - `Idempotency-Key` support for safe webhooks and financial mutations.
+- **Zero Runtime Dependencies**: Uses native Fetch and WebCrypto.
+- **Flexible Auth**: Supports static API Keys, Bearer tokens, async token getters, and OAuth2
+  Client Credentials with automatic token caching.
+- **Ergonomic Accounting Helpers**: Bank account caching (`getDefaultBankAccount`), base64 receipt
+  attachments (`buildBase64Receipt`), VAT calculations (`calculateVat`), and Kleinunternehmer
+  detection (`isKleinunternehmer`).
+
+> **No baked-in endpoint.** This SDK deliberately ships without a fixed target URL. Every
+> `OrvelloClient` — and every `diagnoseOrvello` call — must be pointed at an orvello platform URL
+> explicitly (see below). Nothing quietly aims at a hidden default host.
+
+---
+
+## Installation
+
+```bash
+pnpm add @orvello/sdk
+# or
+npm install @orvello/sdk
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { createOrvelloClient, type BaseUrlProvider } from "@orvello/sdk";
+
+// Point the client at your orvello deployment explicitly.
+// baseUrl can be a plain string, a function returning a string/Promise, or come from ORVELLO_URL.
+const orvello = createOrvelloClient({
+  baseUrl: process.env.ORVELLO_URL!, // e.g. "https://your-org.orvello.example"
+  auth: {
+    clientId: process.env.ORVELLO_CLIENT_ID!,
+    clientSecret: process.env.ORVELLO_CLIENT_SECRET!,
+  },
+});
+
+// API Key / Bearer token alternative:
+// const orvello = createOrvelloClient({
+//   baseUrl: process.env.ORVELLO_URL!,
+//   auth: { apiKey: process.env.ORVELLO_API_KEY! },
+// });
+```
+
+### Environment-driven configuration
+
+`OrvelloClient` also auto-discovers its target and credentials from `ORVELLO_*` variables when no
+explicit `baseUrl`/`auth` is given:
+
+```bash
+ORVELLO_URL=https://your-org.orvello.example
+ORVELLO_OAUTH_CLIENT_ID=...
+ORVELLO_OAUTH_CLIENT_SECRET=...
+# optional
+ORVELLO_OAUTH_SCOPE=...
+# or instead of OAuth:
+ORVELLO_API_KEY=...
+```
+
+```typescript
+// No config object at all — resolves ORVELLO_URL + any ORVELLO_* credentials.
+const orvello = createOrvelloClient();
+```
+
+If neither a `baseUrl` nor `ORVELLO_URL` is present, construction throws a clear error instead of
+silently pointing at a fixed host.
+
+---
+
+## Usage Examples
+
+### 1. Invoices
+
+#### Create an Invoice
+```typescript
+const result = await orvello.invoices.create({
+  invoiceDate: "2026-09-05",
+  dueDate: "2026-09-19",
+  currency: "EUR",
+  customerName: "Acme Corp",
+  customerEmail: "accounting@acme.com",
+  issueImmediately: true,
+  generatePdf: true,
+  lineItems: [
+    { title: "Web Development Services", quantity: 1, unitPriceNet: "1500.00", taxRate: 19 },
+  ],
+});
+
+console.log("Created invoice:", result.invoice.invoiceNumber);
+console.log("PDF URL:", result.pdfUrl);
+```
+
+#### Download Invoice PDF
+```typescript
+// As a binary Blob
+const pdfBlob = await orvello.invoices.downloadPdf(result.invoice.id);
+
+// Or from a relative/direct URL
+const pdfFromUrl = await orvello.invoices.downloadPdfFromUrl(result.pdfUrl!);
+```
+
+#### Settle an Invoice (Mark as Paid & Reconcile)
+```typescript
+await orvello.invoices.updateStatus(result.invoice.id, {
+  status: "paid",
+  paymentReference: "STRIPE-PI-998877",
+});
+
+// Or use One-Shot Settlement with payment account and fee deduction:
+const settlement = await orvello.bookkeeping.payments.settleInvoice({
+  invoiceId: result.invoice.id,
+  paymentAccountId: 1, // e.g. Stripe Account
+  payoutAmount: "1735.00", // net received after Stripe fee
+  paymentDate: "2026-09-05",
+  externalRef: "stripe-charge-ch_12345",
+});
+```
+
+#### Issue a Credit Note / Cancellation
+```typescript
+// Preview first (GoBD compliant)
+const preview = await orvello.invoices.previewCreditNote(result.invoice.id, {
+  mode: "full",
+  reason: "Customer cancellation within 14 days",
+});
+
+// Issue the credit note
+const creditNote = await orvello.invoices.issueCreditNote(result.invoice.id, {
+  mode: "full",
+  reason: "Customer cancellation within 14 days",
+});
+console.log("Credit note issued:", creditNote.invoice.invoiceNumber);
+```
+
+---
+
+### 2. Bookkeeping & Expenses with Receipt Upload
+
+```typescript
+import { buildBase64Receipt } from "@orvello/sdk";
+import fs from "node:fs/promises";
+
+const fileBuffer = await fs.readFile("./receipt.pdf");
+const receipt = buildBase64Receipt(fileBuffer, "server-hosting.pdf", "application/pdf");
+
+const expense = await orvello.bookkeeping.expenses.create(
+  {
+    managingCompanyId: 1,
+    expenseDate: "2026-09-01",
+    grossAmount: "119.00",
+    netAmount: "100.00",
+    taxAmount: "19.00",
+    taxRate: "19.00",
+    paymentMethod: "bank",
+    description: "Hetzner Dedicated Server",
+    externalRef: "hetzner-inv-2026-09",
+  },
+  { receipt }
+);
+```
+
+---
+
+### 3. Payment Accounts & Default Bank Account
+
+```typescript
+// Retrieve the default bank account (cached for 5 minutes)
+const bank = await orvello.bookkeeping.getDefaultBankAccount();
+console.log(`IBAN: ${bank.iban}, BIC: ${bank.bic}, Bank: ${bank.bank}`);
+```
+
+---
+
+### 4. Managing Company Context & Kleinunternehmer Detection
+
+```typescript
+import { isKleinunternehmer } from "@orvello/sdk";
+
+const context = await orvello.managingCompanies.getCurrent();
+if (isKleinunternehmer(context)) {
+  console.log("Managing company is Kleinunternehmer (§ 19 UStG) - no VAT shown.");
+} else {
+  console.log("Standard taxation (19% VAT).");
+}
+```
+
+---
+
+### 5. Dunning / Mahnwesen
+
+```typescript
+// Get overdue invoices ready for dunning
+const suggestions = await orvello.dunning.suggestions({ limit: 10 });
+
+// Issue dunning notice
+for (const item of suggestions.items) {
+  if (item.suggestedLevel) {
+    const notice = await orvello.dunning.issue(item.invoiceId, { level: item.suggestedLevel });
+  }
+}
+```
+
+---
+
+### 6. Contract Integrity & Health Diagnostic
+
+```typescript
+import { diagnoseOrvello } from "@orvello/sdk";
+
+// Pointed at the same platform (client carries a baseUrl) — no baked-in target here either.
+const health = await diagnoseOrvello({ client: orvello });
+if (!health.ok) {
+  console.warn("orvello service problem or contract drift:", health.problems);
+} else {
+  console.log("orvello service is healthy and contract matches the SDK!");
+}
+```
+
+---
+
+## Contract Types Re-Export
+
+All generated DTOs, request types, and response types are re-exported under `@orvello/sdk/contract`:
+
+```typescript
+import type {
+  InvoicesCreateExternalBody,
+  InvoicesGetByIdExternalResponseData,
+  CustomerCompany,
+  Invoice,
+  PaymentAccount,
+} from "@orvello/sdk/contract";
+```
+
+> **A note on generated names.** The contract subpath re-exports the raw platform contract, which is
+> produced by the accounting backend itself. Some DTOs there carry the backend's internal prefixes
+> (e.g. `NodeBillUser`, `NodeBillAppPermissions`). Those are the unchanged, authoritative types of
+> the backend schema — the SDK only mirrors them. If the backend ever renames them it will flow
+> through automatically via `api:generate`/`sync:contract`; do not hand-edit them here.
+
+---
+
+## License
+
+MIT