@beel_es/sdk 1.1.0 → 1.2.0

package/README.md

@@ -32,23 +32,92 @@ import { BeeL } from '@beel_es/sdk';
 
 const beel = new BeeL({ apiKey: 'beel_sk_live_...' });
 
+// Address a company (NIF) explicitly — the recommended multi-NIF surface
+const company = beel.company('company-uuid');
+
 // Create a draft invoice
-const invoice = await beel.invoices.create({
+const invoice = await company.invoices.create({
   type: 'STANDARD',
   recipient: { customer_id: 'customer-uuid' },
   lines: [
-    { description: 'Consulting', quantity: 1, unit_price: 100, discount_percentage: 0 },
+    { 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 beel.invoices.issue(invoice.id);
+const issued = await company.invoices.issue(invoice.id);
 console.log(issued.invoice_number); // e.g. "A-2026/0001"
 ```
 
-## Resources
+## Companies (multi-NIF)
+
+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
+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();
+```
+
+## 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);
+
+// Companies (NIFs) under the account
+const { companies } = await account.companies.list();
+await account.companies.create({ nif: 'B12345678', ... });
+
+// 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
+```
+
+## 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
 // Invoices