@beel_es/sdk 1.1.0 → 1.3.0

package/README.md

@@ -32,23 +32,155 @@ 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' });
+
+// Scheduling — one PUT sets or moves it, one DELETE clears it
+await company.invoices.schedule.set('invoice-uuid', { scheduled_for: '2026-12-01' });
+await company.invoices.schedule.clear('invoice-uuid');
+
+// Derive a new invoice from an existing one
+const copy = await company.invoices.derive({ from_invoice_id: 'invoice-uuid' });
+
+// Fiscal configuration of this NIF
+const verifactu = await company.verifactuConfiguration.get();
+await company.verifactuConfiguration.update({ enabled: true });
+const taxes = await company.taxConfiguration.get();
+
+// Company health
+const summary = await company.fiscalSummary({ year: 2026 });
+const readiness = await company.issuingReadiness();
+```
+
+Whether an invoice reaches AEAT is a fact of the **NIF**, resolved at issue time — not a
+per-invoice choice. `enabled` is the only writable field of the VeriFactu configuration.
+
+### Payment connections (Stripe per NIF)
+
+A connection links Stripe to one NIF so its charges auto-generate invoices under it. It is
+addressed by **its own UUID**, not by the provider slug — a NIF can hold several
+connections of the same provider. The slug only appears when you start an authorization.
+
+```typescript
+const { connections } = await company.paymentConnections.list();
+
+const { authorization_url } = await company.paymentConnections.authorize({
+  provider: 'stripe',
+});
+
+const events = company.paymentConnections.events(connections[0].id);
+const { events: pending } = await events.list({ needs_action: true });
+
+// Recovery levers for a charge that did not invoice
+await events.retry('event-uuid');
+const { invoice_id } = await events.draft('event-uuid'); // review before issuing
+await events.resolve('event-uuid');
+
+await company.paymentConnections.disconnect(connections[0].id);
+```
+
+## Catalogs and preferences
+
+```typescript
+const taxTypes = await beel.catalogs.taxTypes();
+const options = await beel.catalogs.invoiceCustomizationOptions();
+await beel.catalogs.updateMe({ language: 'es' }); // the language belongs to the person
+```
+
+## Any endpoint: `beel.raw`
+
+A route reaches the generated types as soon as the contract is synced, but its ergonomic
+wrapper is written by hand. `beel.raw` lets you call anything in the contract today,
+without waiting for a release:
+
+```typescript
+const { data } = await beel.raw.GET('/v1/companies/{company_id}/logo', {
+  params: { path: { company_id: 'company-uuid' } },
+});
+```
+
+It is the same client the resources use — authentication, retries and `Idempotency-Key`
+still apply — and it stays typed: a path, parameter or body the contract does not have
+will not compile. What you give up is the sugar and the naming stability of the wrappers.
+
+## 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