@beel_es/sdk 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BeeL - Facturación para Autónomos
+
+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

@@ -1,131 +1,291 @@
-# BeeL TypeScript SDK
+# BeeL Node.js SDK
 
-[![npm](https://img.shields.io/npm/v/@beel/sdk.svg)](https://www.npmjs.com/package/@beel/sdk)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)
+[![npm version](https://img.shields.io/npm/v/@beel_es/sdk.svg)](https://www.npmjs.com/package/@beel_es/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-Official TypeScript/JavaScript SDK for the [BeeL](https://beel.es) invoicing API. Fully typed.
+Official Node.js/TypeScript SDK for the [BeeL API](https://beel.es) — Spanish invoicing for self-employed professionals with VeriFactu compliance.
+
+**Node.js 18+. Single dependency ([openapi-fetch](https://openapi-ts.dev/openapi-fetch/)).**
+
+## Features
+
+- **Full TypeScript types** auto-generated from OpenAPI spec
+- **Automatic retries** with exponential backoff on 429 and 5xx
+- **Auto idempotency keys** on every POST request
+- **Typed errors** — catch `BeeLNotFoundError` instead of checking status codes
+- **PDF download** as Buffer
+- **Webhook signature verification** with HMAC-SHA256
+- **Instance-based client** — multiple API keys, no global state
+- **ESM + CommonJS**
 
 ## Installation
 
 ```bash
-npm install @beel/sdk
+npm install @beel_es/sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { BeeL } from '@beel/sdk';
+import { BeeL } from '@beel_es/sdk';
 
-// The client validates your API key on creation
-const beel = await BeeL.create('beel_sk_live_...');
+const beel = new BeeL({ apiKey: 'beel_sk_live_...' });
 
-// List invoices
-const invoices = await beel.invoices.list();
+// Address a company (NIF) explicitly — the recommended multi-NIF surface
+const company = beel.company('company-uuid');
 
-// Get a specific invoice
-const invoice = await beel.invoices.get('550e8400-e29b-41d4-a716-446655440000');
+// Create a draft invoice
+const invoice = await company.invoices.create({
+  type: 'STANDARD',
+  recipient: { customer_id: 'customer-uuid' },
+  lines: [
+    { line_type: 'NORMAL', description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 },
+  ],
+});
+
+console.log(invoice.id); // UUID assigned immediately
+
+// Issue it to assign an invoice number and trigger VeriFactu
+const issued = await company.invoices.issue(invoice.id);
+console.log(issued.invoice_number); // e.g. "A-2026/0001"
 ```
 
-## Usage
+## Companies (multi-NIF)
 
-### Invoices
+Every operation on `beel.company(companyId)` addresses the company in the URL path, so it
+works with any number of NIFs and never depends on a session focus:
 
 ```typescript
-// List with filters
-const invoices = await beel.invoices.list({
-  query: { page: 1, limit: 20, status: 'paid' }
-});
+const company = beel.company('company-uuid');
+
+// Invoices — full lifecycle
+const { invoices, pagination } = await company.invoices.list({ status: 'ISSUED' });
+await company.invoices.issue('invoice-uuid');
+await company.invoices.void('invoice-uuid', { reason: 'Billing error' });
+await company.invoices.createCorrective('invoice-uuid', { ... });
+const pdf = await company.invoices.getPdf('invoice-uuid');
+
+// Customers, products, series
+const customer = await company.customers.create({ ... });
+const product = await company.products.create({ ... });
+await company.series.ensureDefaults(); // idempotent seeding of the typed default series
+
+// Recurring invoices
+await company.recurringInvoices.create({ ... });
+await company.recurringInvoices.setStatus('rec-uuid', { status: 'PAUSED' });
+
+// Company health
+const summary = await company.fiscalSummary({ year: 2026 });
+const readiness = await company.issuingReadiness();
+```
 
-// Create
-const created = await beel.invoices.create({
-  body: {
-    customer_id: 'uuid',
-    issue_date: '2026-03-10',
-    lines: [{ description: 'Service', quantity: 1, unit_price: 100 }]
-  }
-});
+## Accounts (managed accounts, members & webhooks)
+
+For integrators managing several accounts (provisioning, gestorías, platforms):
+
+```typescript
+// List and provision managed accounts
+const { accounts } = await beel.accounts.list();
+const created = await beel.accounts.provision({ external_ref: 'client-42' });
+
+// Scope to one account
+const account = beel.account(created.account_id);
 
-// Issue, send, mark paid
-await beel.invoices.issue('invoice-id');
-await beel.invoices.sendEmail('invoice-id', { body: { to: 'client@example.com' } });
-await beel.invoices.markPaid('invoice-id', { body: { payment_date: '2026-03-10' } });
+// Companies (NIFs) under the account
+const { companies } = await account.companies.list();
+await account.companies.create({ nif: 'B12345678', ... });
 
-// Download PDF
-const pdf = await beel.invoices.downloadPdf('invoice-id');
+// Members, roles and per-company grants
+const members = await account.members.list();
+await account.members.putGrant('member-id', 'company-id', { permissions: [...] });
+
+// Invitations
+await account.invitations.create({ invited_email: 'user@example.com', account_role: 'MEMBER' });
+
+// Account-scoped webhooks
+const webhook = await account.webhooks.create({ url: 'https://...', events: ['invoice.issued'] });
+await account.webhooks.test(webhook.id);
+await account.webhooks.rotateSecret(webhook.id);
+
+// Usage & ownership
+const usage = await account.usage();
+await account.createClaimToken(); // let the end user claim the account
 ```
 
-### Customers
+## Resources (deprecated session-focus surface)
+
+> **Deprecated:** the API contract marks the whole session-focus surface (`beel.invoices`,
+> `beel.customers`, `beel.products`, `beel.series`, `beel.configuration`) as deprecated.
+> Prefer the company-scoped equivalents above. These keep working during the sunset window.
 
 ```typescript
-const customers = await beel.customers.list();
-const created = await beel.customers.create({ body: { name: 'ACME', nif: 'B12345678' } });
-await beel.customers.update('id', { body: { email: 'new@acme.com' } });
-await beel.customers.delete('id');
+// Invoices
+const { invoices, pagination } = await beel.invoices.list({ status: 'ISSUED', limit: 20 });
+const invoice = await beel.invoices.get('invoice-uuid');
+const created = await beel.invoices.create({ ... });
+const updated = await beel.invoices.update('id', { ... });
+await beel.invoices.delete('id');
+
+// Invoice lifecycle
+await beel.invoices.issue('id');
+await beel.invoices.markPaid('id');
+await beel.invoices.markSent('id');
+await beel.invoices.void('id', { reason: 'Duplicate invoice sent in error' });
+await beel.invoices.schedule('id', { scheduled_for: '2026-04-15' });
+await beel.invoices.unschedule('id');
+await beel.invoices.duplicate('id');
+await beel.invoices.createCorrective('id', { ... });
+
+// Customers
+const { customers, pagination } = await beel.customers.list({ search: 'Acme' });
+const customer = await beel.customers.create({
+  legal_name: 'Acme SL',
+  nif: 'B86561412',
+  address: { street: 'Calle Mayor', number: '1', postal_code: '28001', city: 'Madrid', province: 'Madrid', country: 'Spain', country_code: 'ES' },
+});
+
+// Products
+const { products } = await beel.products.list();
+const results = await beel.products.search('consulting');
+
+// Configuration
+const taxConfig = await beel.configuration.getTaxConfig();
+const series = await beel.series.list();
+
+// NIF validation
+const result = await beel.nif.validate('B12345678');
 ```
 
-### Products
+## Typed Errors
+
+Every API error maps to a specific error class:
 
 ```typescript
-const products = await beel.products.list();
-const results = await beel.products.search({ query: { q: 'hosting' } });
+import { BeeL, BeeLNotFoundError, BeeLValidationError } from '@beel_es/sdk';
+
+try {
+  await beel.invoices.get('nonexistent-id');
+} catch (error) {
+  if (error instanceof BeeLNotFoundError) {
+    console.log(error.message);    // "Invoice not found"
+    console.log(error.requestId);  // "abc123" (for support)
+  }
+  if (error instanceof BeeLValidationError) {
+    console.log(error.message);    // "El NIF no tiene un formato válido"
+    console.log(error.details);    // { field: "nif", invalid_value: "..." }
+  }
+}
 ```
 
-### Series
+| Error class | Status | When |
+|---|---|---|
+| `BeeLAuthError` | 401, 403 | Invalid or missing API key |
+| `BeeLNotFoundError` | 404 | Resource doesn't exist |
+| `BeeLValidationError` | 422 | Invalid data |
+| `BeeLConflictError` | 409 | Duplicate (e.g. same NIF) |
+| `BeeLRateLimitError` | 429 | Too many requests (auto-retried) |
+| `BeeLApiError` | 5xx | Server error (auto-retried) |
+
+## Automatic Retries
+
+429 and 5xx errors are retried with exponential backoff. Client errors (400, 401, 404, 422) are never retried.
 
 ```typescript
-const series = await beel.series.list();
-await beel.series.setDefault('series-id');
+const beel = new BeeL({
+  apiKey: 'beel_sk_live_...',
+  maxRetries: 5,          // default: 3
+  retryDelayMs: 1000,     // default: 500
+  maxRetryDelayMs: 60000, // default: 30000
+});
 ```
 
-### Configuration
+## PDF Download
 
 ```typescript
-const tax = await beel.config.getTaxConfiguration();
-const vf = await beel.config.getVeriFactuConfiguration();
+import fs from 'fs';
+
+const { buffer, fileName } = await beel.downloadPdf('invoice-uuid');
+fs.writeFileSync(fileName, buffer);
+// => factura_A-2026-0001.pdf
 ```
 
-## Error Handling
+## Webhooks
+
+Verify webhook signatures before processing:
 
 ```typescript
-import { BeeL, BeeLError } from '@beel/sdk';
+import express from 'express';
+import { WebhookVerifier } from '@beel_es/sdk';
 
-try {
-  const beel = await BeeL.create('invalid_key');
-} catch (e) {
-  if (e instanceof BeeLError) {
-    console.error(e.message);    // "Invalid API key..."
-    console.error(e.statusCode); // 401
+const verifier = new WebhookVerifier(process.env.BEEL_WEBHOOK_SECRET!);
+
+app.post('/webhooks/beel', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = verifier.verify(
+      req.body.toString('utf8'),
+      req.headers['beel-signature'] as string,
+    );
+
+    if (event.type === 'verifactu.status.updated') {
+      console.log(event.data.new_status); // 'ACCEPTED' | 'REJECTED'
+    }
+
+    res.status(200).send('OK');
+  } catch {
+    res.status(400).send('Invalid signature');
   }
-}
+});
 ```
 
-## Configuration
+## Builders
+
+Optional fluent builders for common operations:
 
 ```typescript
-// Production (default)
-const beel = await BeeL.create('beel_sk_live_...');
+import { InvoiceBuilder, CustomerBuilder } from '@beel_es/sdk';
+
+const customer = CustomerBuilder.create()
+  .name('Acme SL')
+  .nif('B12345678')
+  .email('contact@acme.com')
+  .address('Calle Mayor', '1', '28001', 'Madrid', 'Madrid', 'Spain')
+  .build();
+
+const invoice = InvoiceBuilder.create()
+  .forCustomer('customer-uuid')
+  .addLine('Service A', 5, 100.0)
+  .addLine('Service B', 3, 150.0)
+  .metadata({ stripe_id: 'pi_abc123' })
+  .build();
+```
 
-// Test environment
-const beel = await BeeL.create({
-  apiKey: 'beel_sk_live_...',
-  baseUrl: 'https://test.beel.es/api',
-});
+## Environments
 
-// Skip validation (for tests)
-const beel = await BeeL.create({
-  apiKey: 'beel_sk_live_...',
-  skipValidation: true,
+```typescript
+// Sandbox — no VeriFactu quota consumed, safe to test
+const sandbox = new BeeL({ apiKey: 'beel_sk_test_...' });
+
+// Production
+const prod = new BeeL({ apiKey: 'beel_sk_live_...' });
+```
+
+## Full Configuration
+
+```typescript
+const beel = new BeeL({
+  apiKey: 'beel_sk_live_...',         // Required
+  baseUrl: 'https://app.beel.es/api', // Default
+  maxRetries: 3,                       // Default
+  retryDelayMs: 500,                   // Default
+  maxRetryDelayMs: 30000,              // Default
 });
 ```
 
-## Requirements
+## Documentation
 
-- Node.js 18+ or any modern runtime with `fetch`
-- TypeScript 5.0+ (optional but recommended)
+Full API docs: [docs.beel.es](https://docs.beel.es)
 
-## Links
+## License
 
-- [API Reference](https://beel.es/api-reference)
-- [Website](https://beel.es)
-- [Support](mailto:info@beel.es)
+MIT