@veroao/node 1.0.0

package/README.md

@@ -0,0 +1,268 @@
+# @veroao/node
+
+SDK oficial Vero para Node.js - emite facturas certificadas pela AGT sem sair do teu código.
+
+## Instalação
+
+```bash
+npm install @veroao/node
+```
+
+Requer Node.js 18+ (usa `fetch` nativo, sem dependências).
+
+## Quick start
+
+```typescript
+import { createVeroClient } from '@veroao/node'
+
+const vero = createVeroClient() // lê VERO_API_KEY do ambiente
+// ou: createVeroClient({ secretKey: 'vero_test_sk_...' })
+
+const ORG_ID = process.env.VERO_ORG_ID!
+
+// 1. Garante que o cliente existe (cria ou actualiza pelo teu ID externo)
+const customer = await vero.customers.ensure(ORG_ID, {
+  externalId: 'user_123',
+  name: 'Maria Fernandes',
+  taxId: '003456789LA042',
+  phone: '923456789',
+  email: 'maria@empresa.ao',
+})
+
+// 2. Emite a factura
+const invoice = await vero.invoices.create(ORG_ID, {
+  customerId: customer.id,
+  items: [
+    {
+      description: 'Subscrição Mensal - Plano Pro',
+      quantity: 1,
+      unitPrice: 2500000, // 25 000,00 AOA em kwanzas × 100
+      taxRate: 14,
+    },
+  ],
+})
+
+console.log(invoice.number)  // "FT FT6326S62896N/1" - formato oficial AGT
+console.log(invoice.pdfUrl)  // link para descarregar o PDF (gerado na hora, não expira)
+console.log(invoice.atcud)   // código de verificação AGT
+```
+
+A submissão à AGT acontece em segundo plano - `invoice.agtStatus` começa como `pending` e passa a
+`validated` ou `rejected` alguns segundos depois. Consulta o documento novamente (`vero.invoices.get`)
+para confirmar.
+
+## Ambiente test vs live
+
+O ambiente é detectado automaticamente a partir do prefixo da chave - não precisas de configurar nada:
+
+| Chave              | Ambiente | Comportamento                                                        |
+|--------------------|----------|-----------------------------------------------------------------------|
+| `vero_test_sk_...` | test     | Documentos gerados inteiramente em local, número marcado `TESTE`, **nunca chegam à AGT**, mesmo que a organização já tenha chaves de produção configuradas |
+| `vero_live_sk_...`  | live     | Documentos certificados pela AGT em produção - valor fiscal real     |
+
+```typescript
+const vero = createVeroClient({ secretKey: 'vero_test_sk_...' })
+console.log(vero.environment) // 'test'
+```
+
+Existe também uma chave de sandbox pública e partilhada, sem necessidade de conta - pede-a a
+`GET https://api.vero.ao/v1/sandbox`.
+
+## Referência da API
+
+### `vero.customers`
+
+```typescript
+// Listar (paginado)
+const { data, meta } = await vero.customers.list(orgId, { search: 'Maria', page: 1, limit: 20 })
+
+// Obter por ID
+const customer = await vero.customers.get(orgId, customerId)
+
+// Criar
+const customer = await vero.customers.create(orgId, {
+  name: 'Empresa XYZ',
+  taxId: '5000123456',
+  phone: '923456789',
+  email: 'geral@xyz.ao',
+  addressLine1: 'Rua Amílcar Cabral, 45',
+  city: 'Luanda',
+})
+
+// Actualizar (campos parciais)
+await vero.customers.update(orgId, customerId, { email: 'novo@xyz.ao' })
+
+// Upsert pelo externalId - idempotente, seguro chamar a cada pedido
+const customer = await vero.customers.ensure(orgId, {
+  externalId: 'user_42',
+  name: 'João Baptista',
+  taxId: '123456789LA001',
+})
+```
+
+`name` e `taxId` são mutuamente opcionais - omite `name` se `isConsumidorFinal: true` ou se `taxId`
+já identifica a empresa.
+
+### `vero.invoices`
+
+```typescript
+// Emitir (idempotencyKey gerada automaticamente se omitida)
+const invoice = await vero.invoices.create(orgId, {
+  customerId: 'uuid...',
+  documentType: 'FT', // FT = Factura (a prazo), FR = Factura-Recibo (pagamento imediato)
+  items: [{ description: 'Serviço', quantity: 1, unitPrice: 100000, taxRate: 14 }],
+  idempotencyKey: 'pedido_789', // passa o teu próprio para evitar duplicados em retries
+})
+
+// Listar (paginado, filtros opcionais)
+const { data, meta } = await vero.invoices.list(orgId, { status: 'issued', documentType: 'FT', page: 1 })
+
+// Obter por ID
+const invoice = await vero.invoices.get(orgId, invoiceId)
+
+// Cancelar (não elimina - fica com status "cancelled")
+await vero.invoices.cancel(orgId, invoice.id, 'Pedido do cliente')
+
+// Enviar por email ao cliente (usa o email guardado no cliente)
+await vero.invoices.send(orgId, invoice.id)
+```
+
+`documentType: 'FR'` fica com `status: 'paid'` imediatamente (já está pago); `'FT'` fica `'issued'`
+até seres tu a marcar como pago via `vero.receipts.create`.
+
+### `vero.proformas`
+
+```typescript
+const proforma = await vero.proformas.create(orgId, {
+  customerId: 'uuid...',
+  items: [{ description: 'Orçamento', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+  validUntil: '2026-12-31',
+})
+
+// Converter em factura definitiva certificada - sem corpo, usa os dados já na proforma
+const invoice = await vero.proformas.convert(orgId, proforma.id)
+
+// Anular (só enquanto estiver em draft, não pode ser desfeito)
+await vero.proformas.cancel(orgId, proforma.id)
+```
+
+Proformas não têm valor fiscal - servem só de orçamento até seres convertidas em factura.
+
+### `vero.creditNotes`
+
+```typescript
+// Emitir nota de crédito contra uma factura - cancela a factura original
+const cn = await vero.creditNotes.create(orgId, invoice.id, 'Devolução parcial')
+
+await vero.creditNotes.send(orgId, cn.id) // por email ao cliente
+```
+
+### `vero.debitNotes`
+
+```typescript
+// Autónoma ou associada a uma factura existente - ao contrário da NC, não exige factura de origem
+const dn = await vero.debitNotes.create(orgId, {
+  customerId: customer.id,
+  items: [{ description: 'Custos administrativos', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+  invoiceId: invoice.id, // opcional - usa o número real dessa factura como referência na AGT
+})
+```
+
+### `vero.receipts`
+
+```typescript
+// Marca uma factura FT como paga e emite o recibo (documento interno, não vai à AGT)
+const receipt = await vero.receipts.create(orgId, invoice.id, { paymentMethod: 'transfer' })
+```
+
+### `vero.products`
+
+```typescript
+const product = await vero.products.create(orgId, {
+  name: 'Plano Pro',           // único campo obrigatório
+  code: 'PLAN-PRO',            // opcional
+  unitPrice: 2500000,
+  taxRate: 14,                 // default 14 se omitido
+  unitOfMeasure: 'UN',         // default 'UN' se omitido
+})
+
+const products = await vero.products.list(orgId) // devolve todos, sem paginação nem filtros
+
+await vero.products.update(orgId, product.id, { unitPrice: 2700000 })
+await vero.products.deactivate(orgId, product.id) // soft delete - fica active: false
+```
+
+### `vero.webhooks`
+
+```typescript
+const webhook = await vero.webhooks.register(orgId, {
+  url: 'https://teusite.ao/webhooks/vero',
+  events: ['invoice.issued', 'invoice.cancelled', 'proforma.converted', 'proforma.cancelled'],
+})
+console.log(webhook.secret) // segredo HMAC - só é mostrado nesta resposta, guarda-o
+
+await vero.webhooks.list(orgId)
+await vero.webhooks.delete(orgId, webhook.id)
+```
+
+O payload enviado ao teu endpoint tem a forma `{ event, orgId, timestamp, data }` - `data` é o próprio
+documento (mesma forma da resposta da API). Para eventos de factura, `data.pdfUrl` é um link **público**,
+sem necessidade de autenticação.
+
+## Tratamento de erros
+
+```typescript
+import { VeroAPIError, VeroAuthError, VeroNotFoundError, VeroRateLimitError } from '@veroao/node'
+
+try {
+  const invoice = await vero.invoices.create(orgId, input)
+} catch (err) {
+  if (err instanceof VeroAuthError) {
+    // chave inválida ou revogada
+  } else if (err instanceof VeroNotFoundError) {
+    // organização ou cliente não encontrado
+  } else if (err instanceof VeroRateLimitError) {
+    // demasiados pedidos - err.retryAfter (segundos), se o servidor o indicou
+  } else if (err instanceof VeroAPIError) {
+    console.error(err.status, err.code, err.message)
+  }
+}
+```
+
+Erros de rede e respostas 5xx são automaticamente repetidos (até `maxRetries`, default 3, com
+backoff exponencial) antes de lançarem excepção.
+
+## Configuração do cliente
+
+```typescript
+const vero = createVeroClient({
+  secretKey: 'vero_live_sk_...',
+  baseUrl: 'https://api.vero.ao',   // default
+  maxRetries: 3,                    // tentativas em erros 5xx/rede
+  timeout: 30_000,                  // ms por pedido
+})
+```
+
+## Preços em kwanzas
+
+Os valores monetários usam **kwanzas × 100** para evitar problemas de vírgula flutuante:
+
+```typescript
+unitPrice: 2_500_000  // 25 000,00 AOA
+unitPrice: 150_050    // 1 500,50 AOA
+```
+
+## Variáveis de ambiente
+
+| Variável           | Descrição                                                        |
+|--------------------|--------------------------------------------------------------------|
+| `VERO_API_KEY`      | Chave secreta da API (recomendado)                                |
+| `VERO_SECRET_KEY`   | Alias legado - usado só se `VERO_API_KEY` não estiver definida    |
+
+## O teu backend não é Node?
+
+Este pacote é só uma comodidade - por baixo é tudo pedidos HTTPS normais (`Authorization: Bearer
+vero_..._sk_...`, corpo JSON). Se o teu backend é PHP, Python, Ruby, Java, Go, ou qualquer outra
+linguagem, tens acesso a **exactamente as mesmas operações** chamando a API REST directamente com
+o cliente HTTP dessa linguagem - nada fica limitado por não usares este SDK. Exemplos completos em
+cURL, Python e PHP estão em [vero.ao/docs](https://vero.ao/docs).

package/dist/client.d.ts

@@ -0,0 +1,141 @@
+import type { VeroConfig, ListResult, Customer, CreateCustomerInput, UpdateCustomerInput, EnsureCustomerInput, ListCustomersParams, Invoice, CreateInvoiceInput, ListInvoicesParams, ProformaInvoice, CreateProformaInput, ListProformasParams, CreditNote, DebitNote, CreateDebitNoteInput, Receipt, CreateReceiptInput, Product, CreateProductInput, UpdateProductInput, Webhook, RegisterWebhookInput } from './types.js';
+declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly secretKey;
+    private readonly maxRetries;
+    private readonly timeout;
+    constructor(config: Required<VeroConfig>);
+    request<T>(method: string, path: string, body?: unknown, params?: Record<string, unknown>): Promise<T>;
+    get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+declare class CustomersResource {
+    private http;
+    constructor(http: HttpClient);
+    list(orgId: string, params?: ListCustomersParams): Promise<ListResult<Customer>>;
+    get(orgId: string, customerId: string): Promise<Customer>;
+    create(orgId: string, input: CreateCustomerInput): Promise<Customer>;
+    update(orgId: string, customerId: string, input: UpdateCustomerInput): Promise<Customer>;
+    /**
+     * Cria ou actualiza um cliente pelo externalId — upsert atómico no servidor.
+     * Ideal para sincronizar utilizadores do teu sistema sem criar duplicados.
+     *
+     * @example
+     * const customer = await vero.customers.ensure(orgId, {
+     *   externalId: 'user_123',
+     *   name: 'João Silva',
+     *   taxId: '123456789LA001',
+     * })
+     */
+    ensure(orgId: string, input: EnsureCustomerInput): Promise<Customer>;
+}
+declare class InvoicesResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Emite uma fatura certificada pela AGT.
+     * A chave de idempotência é gerada automaticamente — passa a tua própria
+     * para garantir que pedidos duplicados não criam faturas duplicadas.
+     *
+     * @example
+     * const invoice = await vero.invoices.create(orgId, {
+     *   customerId: customer.id,
+     *   items: [{ description: 'Plano Pro', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+     * })
+     */
+    create(orgId: string, input: CreateInvoiceInput): Promise<Invoice>;
+    list(orgId: string, params?: ListInvoicesParams): Promise<ListResult<Invoice>>;
+    get(orgId: string, invoiceId: string): Promise<Invoice>;
+    cancel(orgId: string, invoiceId: string, reason?: string): Promise<Invoice>;
+    /** Envia a fatura por email ao cliente */
+    send(orgId: string, invoiceId: string): Promise<void>;
+}
+declare class ProformasResource {
+    private http;
+    constructor(http: HttpClient);
+    create(orgId: string, input: CreateProformaInput): Promise<ProformaInvoice>;
+    list(orgId: string, params?: ListProformasParams): Promise<ListResult<ProformaInvoice>>;
+    get(orgId: string, proformaId: string): Promise<ProformaInvoice>;
+    /** Converte pró-forma em fatura definitiva certificada — sem corpo, usa os dados já na proforma */
+    convert(orgId: string, proformaId: string): Promise<Invoice>;
+    /** Anula a proforma (não pode ser desfeito) */
+    cancel(orgId: string, proformaId: string): Promise<void>;
+}
+declare class CreditNotesResource {
+    private http;
+    constructor(http: HttpClient);
+    /** Emite nota de crédito contra uma fatura — cancela a fatura original */
+    create(orgId: string, invoiceId: string, reason?: string): Promise<CreditNote>;
+    list(orgId: string): Promise<CreditNote[]>;
+    get(orgId: string, id: string): Promise<CreditNote>;
+    /** Envia a nota de crédito por email ao cliente */
+    send(orgId: string, id: string): Promise<void>;
+}
+declare class DebitNotesResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Emite nota de débito — autónoma ou associada a uma fatura existente.
+     * Ao contrário da nota de crédito, não exige uma fatura de origem: serve
+     * para qualquer cobrança adicional a um cliente. Se passares `invoiceId`,
+     * o Vero usa o número real dessa fatura como referência perante a AGT.
+     *
+     * @example
+     * await vero.debitNotes.create(orgId, {
+     *   customerId: customer.id,
+     *   items: [{ description: 'Custos administrativos', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+     *   invoiceId: invoice.id, // opcional
+     * })
+     */
+    create(orgId: string, input: CreateDebitNoteInput): Promise<DebitNote>;
+    list(orgId: string): Promise<DebitNote[]>;
+    get(orgId: string, id: string): Promise<DebitNote>;
+    /** Envia a nota de débito por email ao cliente */
+    send(orgId: string, id: string): Promise<void>;
+}
+declare class ReceiptsResource {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Emite recibo de pagamento para uma fatura existente.
+     * Marca a fatura como paga e gera o recibo certificado.
+     */
+    create(orgId: string, invoiceId: string, input: CreateReceiptInput): Promise<Receipt>;
+    list(orgId: string): Promise<Receipt[]>;
+    get(orgId: string, id: string): Promise<Receipt>;
+    /** Envia o recibo por email ao cliente */
+    send(orgId: string, id: string): Promise<void>;
+}
+declare class ProductsResource {
+    private http;
+    constructor(http: HttpClient);
+    /** Devolve todos os produtos activos e inactivos — este endpoint não pagina nem filtra no servidor */
+    list(orgId: string): Promise<Product[]>;
+    create(orgId: string, input: CreateProductInput): Promise<Product>;
+    update(orgId: string, productId: string, input: UpdateProductInput): Promise<Product>;
+    /** Desactiva o produto (soft delete — fica com active: false, não é removido de facto) */
+    deactivate(orgId: string, productId: string): Promise<Product>;
+}
+declare class WebhooksResource {
+    private http;
+    constructor(http: HttpClient);
+    register(orgId: string, input: RegisterWebhookInput): Promise<Webhook>;
+    list(orgId: string): Promise<Webhook[]>;
+    delete(orgId: string, webhookId: string): Promise<void>;
+}
+export declare class VeroClient {
+    /** Ambiente detectado automaticamente a partir do prefixo da chave */
+    readonly environment: 'live' | 'test';
+    readonly customers: CustomersResource;
+    readonly invoices: InvoicesResource;
+    readonly proformas: ProformasResource;
+    readonly creditNotes: CreditNotesResource;
+    readonly debitNotes: DebitNotesResource;
+    readonly receipts: ReceiptsResource;
+    readonly products: ProductsResource;
+    readonly webhooks: WebhooksResource;
+    constructor(config: VeroConfig);
+}
+export {};

package/dist/client.js

@@ -0,0 +1,322 @@
+import { randomUUID } from 'node:crypto';
+import { VeroAPIError, VeroAuthError, VeroNotFoundError, VeroRateLimitError, } from './errors.js';
+// ─── HTTP core ────────────────────────────────────────────────────────────────
+class HttpClient {
+    baseUrl;
+    secretKey;
+    maxRetries;
+    timeout;
+    constructor(config) {
+        this.baseUrl = config.baseUrl;
+        this.secretKey = config.secretKey;
+        this.maxRetries = config.maxRetries;
+        this.timeout = config.timeout;
+    }
+    async request(method, path, body, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [k, v] of Object.entries(params)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.append(k, String(v));
+            }
+        }
+        let attempt = 0;
+        while (true) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeout);
+            try {
+                const res = await fetch(url.toString(), {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.secretKey}`,
+                        'Content-Type': 'application/json',
+                    },
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timer);
+                if (res.status === 204)
+                    return undefined;
+                const data = await res.json().catch(() => ({ error: res.statusText }));
+                if (res.ok)
+                    return data;
+                // Erros com retry: 5xx (excepto 400, 401, 403, 404, 409, 422, 429)
+                if (res.status === 401)
+                    throw new VeroAuthError(data?.error);
+                if (res.status === 404)
+                    throw new VeroNotFoundError(data?.error);
+                if (res.status === 429) {
+                    const retryAfter = Number(res.headers.get('Retry-After')) || undefined;
+                    throw new VeroRateLimitError(retryAfter);
+                }
+                if (res.status >= 500 && attempt < this.maxRetries) {
+                    attempt++;
+                    await sleep(200 * 2 ** attempt); // 400ms, 800ms, 1600ms
+                    continue;
+                }
+                throw new VeroAPIError(res.status, data?.error ?? 'api_error', data?.message);
+            }
+            catch (err) {
+                clearTimeout(timer);
+                if (err instanceof VeroAPIError)
+                    throw err;
+                if (err.name === 'AbortError') {
+                    throw new VeroAPIError(408, 'request_timeout', `Timeout após ${this.timeout}ms`);
+                }
+                if (attempt < this.maxRetries) {
+                    attempt++;
+                    await sleep(200 * 2 ** attempt);
+                    continue;
+                }
+                throw new VeroAPIError(0, 'network_error', err.message);
+            }
+        }
+    }
+    get(path, params) {
+        return this.request('GET', path, undefined, params);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+    patch(path, body) {
+        return this.request('PATCH', path, body);
+    }
+    delete(path) {
+        return this.request('DELETE', path);
+    }
+}
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}
+// ─── Resources ───────────────────────────────────────────────────────────────
+class CustomersResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(orgId, params = {}) {
+        return this.http.get(`/v1/organisations/${orgId}/customers`, params);
+    }
+    get(orgId, customerId) {
+        return this.http.get(`/v1/organisations/${orgId}/customers/${customerId}`);
+    }
+    create(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/customers`, input);
+    }
+    update(orgId, customerId, input) {
+        return this.http.patch(`/v1/organisations/${orgId}/customers/${customerId}`, input);
+    }
+    /**
+     * Cria ou actualiza um cliente pelo externalId — upsert atómico no servidor.
+     * Ideal para sincronizar utilizadores do teu sistema sem criar duplicados.
+     *
+     * @example
+     * const customer = await vero.customers.ensure(orgId, {
+     *   externalId: 'user_123',
+     *   name: 'João Silva',
+     *   taxId: '123456789LA001',
+     * })
+     */
+    ensure(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/customers/ensure`, input);
+    }
+}
+class InvoicesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Emite uma fatura certificada pela AGT.
+     * A chave de idempotência é gerada automaticamente — passa a tua própria
+     * para garantir que pedidos duplicados não criam faturas duplicadas.
+     *
+     * @example
+     * const invoice = await vero.invoices.create(orgId, {
+     *   customerId: customer.id,
+     *   items: [{ description: 'Plano Pro', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+     * })
+     */
+    create(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/invoices`, {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? randomUUID(),
+        });
+    }
+    list(orgId, params = {}) {
+        return this.http.get(`/v1/organisations/${orgId}/invoices`, params);
+    }
+    get(orgId, invoiceId) {
+        return this.http.get(`/v1/organisations/${orgId}/invoices/${invoiceId}`);
+    }
+    cancel(orgId, invoiceId, reason) {
+        return this.http.post(`/v1/organisations/${orgId}/invoices/${invoiceId}/cancel`, { reason });
+    }
+    /** Envia a fatura por email ao cliente */
+    send(orgId, invoiceId) {
+        return this.http.post(`/v1/organisations/${orgId}/invoices/${invoiceId}/send`);
+    }
+}
+class ProformasResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    create(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/proformas`, input);
+    }
+    list(orgId, params = {}) {
+        return this.http.get(`/v1/organisations/${orgId}/proformas`, params);
+    }
+    get(orgId, proformaId) {
+        return this.http.get(`/v1/organisations/${orgId}/proformas/${proformaId}`);
+    }
+    /** Converte pró-forma em fatura definitiva certificada — sem corpo, usa os dados já na proforma */
+    convert(orgId, proformaId) {
+        return this.http.post(`/v1/organisations/${orgId}/proformas/${proformaId}/convert`);
+    }
+    /** Anula a proforma (não pode ser desfeito) */
+    cancel(orgId, proformaId) {
+        return this.http.delete(`/v1/organisations/${orgId}/proformas/${proformaId}`);
+    }
+}
+class CreditNotesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Emite nota de crédito contra uma fatura — cancela a fatura original */
+    create(orgId, invoiceId, reason) {
+        return this.http.post(`/v1/organisations/${orgId}/invoices/${invoiceId}/credit-note`, { reason });
+    }
+    list(orgId) {
+        return this.http.get(`/v1/organisations/${orgId}/credit-notes`);
+    }
+    get(orgId, id) {
+        return this.http.get(`/v1/organisations/${orgId}/credit-notes/${id}`);
+    }
+    /** Envia a nota de crédito por email ao cliente */
+    send(orgId, id) {
+        return this.http.post(`/v1/organisations/${orgId}/credit-notes/${id}/send`);
+    }
+}
+class DebitNotesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Emite nota de débito — autónoma ou associada a uma fatura existente.
+     * Ao contrário da nota de crédito, não exige uma fatura de origem: serve
+     * para qualquer cobrança adicional a um cliente. Se passares `invoiceId`,
+     * o Vero usa o número real dessa fatura como referência perante a AGT.
+     *
+     * @example
+     * await vero.debitNotes.create(orgId, {
+     *   customerId: customer.id,
+     *   items: [{ description: 'Custos administrativos', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+     *   invoiceId: invoice.id, // opcional
+     * })
+     */
+    create(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/debit-notes`, input);
+    }
+    list(orgId) {
+        return this.http.get(`/v1/organisations/${orgId}/debit-notes`);
+    }
+    get(orgId, id) {
+        return this.http.get(`/v1/organisations/${orgId}/debit-notes/${id}`);
+    }
+    /** Envia a nota de débito por email ao cliente */
+    send(orgId, id) {
+        return this.http.post(`/v1/organisations/${orgId}/debit-notes/${id}/send`);
+    }
+}
+class ReceiptsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Emite recibo de pagamento para uma fatura existente.
+     * Marca a fatura como paga e gera o recibo certificado.
+     */
+    create(orgId, invoiceId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/invoices/${invoiceId}/receipt`, input);
+    }
+    list(orgId) {
+        return this.http.get(`/v1/organisations/${orgId}/receipts`);
+    }
+    get(orgId, id) {
+        return this.http.get(`/v1/organisations/${orgId}/receipts/${id}`);
+    }
+    /** Envia o recibo por email ao cliente */
+    send(orgId, id) {
+        return this.http.post(`/v1/organisations/${orgId}/receipts/${id}/send`);
+    }
+}
+class ProductsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Devolve todos os produtos activos e inactivos — este endpoint não pagina nem filtra no servidor */
+    list(orgId) {
+        return this.http.get(`/v1/organisations/${orgId}/products`);
+    }
+    create(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/products`, input);
+    }
+    update(orgId, productId, input) {
+        return this.http.patch(`/v1/organisations/${orgId}/products/${productId}`, input);
+    }
+    /** Desactiva o produto (soft delete — fica com active: false, não é removido de facto) */
+    deactivate(orgId, productId) {
+        return this.http.delete(`/v1/organisations/${orgId}/products/${productId}`);
+    }
+}
+class WebhooksResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    register(orgId, input) {
+        return this.http.post(`/v1/organisations/${orgId}/webhooks`, input);
+    }
+    list(orgId) {
+        return this.http.get(`/v1/organisations/${orgId}/webhooks`);
+    }
+    delete(orgId, webhookId) {
+        return this.http.delete(`/v1/organisations/${orgId}/webhooks/${webhookId}`);
+    }
+}
+// ─── Client principal ─────────────────────────────────────────────────────────
+export class VeroClient {
+    /** Ambiente detectado automaticamente a partir do prefixo da chave */
+    environment;
+    customers;
+    invoices;
+    proformas;
+    creditNotes;
+    debitNotes;
+    receipts;
+    products;
+    webhooks;
+    constructor(config) {
+        this.environment = config.secretKey.includes('_test_') ? 'test' : 'live';
+        const http = new HttpClient({
+            secretKey: config.secretKey,
+            baseUrl: config.baseUrl ?? 'https://api.vero.ao',
+            maxRetries: config.maxRetries ?? 3,
+            timeout: config.timeout ?? 30_000,
+        });
+        this.customers = new CustomersResource(http);
+        this.invoices = new InvoicesResource(http);
+        this.proformas = new ProformasResource(http);
+        this.creditNotes = new CreditNotesResource(http);
+        this.debitNotes = new DebitNotesResource(http);
+        this.receipts = new ReceiptsResource(http);
+        this.products = new ProductsResource(http);
+        this.webhooks = new WebhooksResource(http);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class VeroError extends Error {
+    constructor(message: string);
+}
+export declare class VeroAPIError extends VeroError {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message?: string);
+}
+export declare class VeroAuthError extends VeroAPIError {
+    constructor(message?: string);
+}
+export declare class VeroNotFoundError extends VeroAPIError {
+    constructor(resource?: string);
+}
+export declare class VeroRateLimitError extends VeroAPIError {
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number);
+}

package/dist/errors.js

@@ -0,0 +1,36 @@
+export class VeroError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VeroError';
+    }
+}
+export class VeroAPIError extends VeroError {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message ?? code);
+        this.name = 'VeroAPIError';
+        this.status = status;
+        this.code = code;
+    }
+}
+export class VeroAuthError extends VeroAPIError {
+    constructor(message = 'API key inválida ou revogada') {
+        super(401, 'unauthorized', message);
+        this.name = 'VeroAuthError';
+    }
+}
+export class VeroNotFoundError extends VeroAPIError {
+    constructor(resource = 'recurso') {
+        super(404, 'not_found', `${resource} não encontrado`);
+        this.name = 'VeroNotFoundError';
+    }
+}
+export class VeroRateLimitError extends VeroAPIError {
+    retryAfter;
+    constructor(retryAfter) {
+        super(429, 'rate_limit_exceeded', 'Limite de pedidos excedido');
+        this.name = 'VeroRateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './client.js';
+import { VeroClient } from './client.js';
+import type { VeroConfig } from './types.js';
+/**
+ * Cria um cliente Vero a partir da tua chave secreta.
+ * O ambiente (test/live) é detectado automaticamente pelo prefixo da chave.
+ *
+ * @example
+ * // Variável de ambiente (recomendado)
+ * const vero = createVeroClient()
+ *
+ * // Chave explícita
+ * const vero = createVeroClient({ secretKey: 'vero_test_sk_...' })
+ */
+export declare function createVeroClient(config?: Partial<VeroConfig>): VeroClient;

package/dist/index.js

@@ -0,0 +1,25 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './client.js';
+import { VeroClient } from './client.js';
+/**
+ * Cria um cliente Vero a partir da tua chave secreta.
+ * O ambiente (test/live) é detectado automaticamente pelo prefixo da chave.
+ *
+ * @example
+ * // Variável de ambiente (recomendado)
+ * const vero = createVeroClient()
+ *
+ * // Chave explícita
+ * const vero = createVeroClient({ secretKey: 'vero_test_sk_...' })
+ */
+export function createVeroClient(config) {
+    const secretKey = config?.secretKey ??
+        process.env.VERO_API_KEY ??
+        process.env.VERO_SECRET_KEY ?? // retrocompatibilidade
+        '';
+    if (!secretKey) {
+        throw new Error('Vero: chave de API não encontrada. Define VERO_API_KEY ou passa secretKey na config.');
+    }
+    return new VeroClient({ ...config, secretKey });
+}

package/dist/types.d.ts

@@ -0,0 +1,303 @@
+export interface VeroConfig {
+    /** Chave secreta da API — vero_test_sk_... ou vero_live_sk_... */
+    secretKey: string;
+    /** Override da URL base (útil para testes locais) */
+    baseUrl?: string;
+    /** Número máximo de tentativas em falhas 5xx (default: 3) */
+    maxRetries?: number;
+    /** Timeout por pedido em ms (default: 30000) */
+    timeout?: number;
+}
+export interface ListParams {
+    page?: number;
+    limit?: number;
+}
+export interface ListResult<T> {
+    data: T[];
+    meta: {
+        total: number;
+        page: number;
+        limit: number;
+        pages: number;
+    };
+}
+export interface InvoiceItem {
+    description: string;
+    /** Quantidade de unidades */
+    quantity: number;
+    /** Preço unitário em kwanzas × 100 (ex: 10000 = 100 AOA) */
+    unitPrice: number;
+    /** Taxa IVA Angola: 0 = isento, 5 = reduzida, 14 = normal (default: 14) */
+    taxRate?: 0 | 5 | 14;
+    /** Obrigatório junto da AGT quando taxRate = 0 (máx. 4 caracteres, ex: "M19") */
+    taxExemptionCode?: string;
+    /** ID do produto do catálogo (opcional) */
+    productId?: string;
+}
+export interface Customer {
+    id: string;
+    orgId: string;
+    name: string;
+    taxId?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    addressLine1?: string | null;
+    addressLine2?: string | null;
+    city?: string | null;
+    province?: string | null;
+    country?: string | null;
+    /** ID externo do teu sistema — útil para upsert via customers.ensure() */
+    externalId?: string | null;
+    isConsumidorFinal: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateCustomerInput {
+    /** Obrigatório, a menos que taxId seja indicado ou isConsumidorFinal seja true */
+    name?: string;
+    /** Obrigatório, a menos que name seja indicado ou isConsumidorFinal seja true */
+    taxId?: string;
+    email?: string;
+    phone?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    province?: string;
+    country?: string;
+    /** ID externo do teu sistema (ex: user ID do teu e-commerce) */
+    externalId?: string;
+    /** Venda a dinheiro sem identificar o cliente — usa o NIF genérico 999999999 nas faturas */
+    isConsumidorFinal?: boolean;
+}
+export interface UpdateCustomerInput extends Partial<CreateCustomerInput> {
+}
+export interface EnsureCustomerInput extends CreateCustomerInput {
+    /** Obrigatório para upsert — identifica o cliente no teu sistema */
+    externalId: string;
+}
+export interface ListCustomersParams extends ListParams {
+    search?: string;
+}
+export type InvoiceStatus = 'pending' | 'issued' | 'paid' | 'failed' | 'cancelled';
+export type DocumentType = 'FT' | 'FR';
+/** Estado da validação junto da AGT — a submissão acontece em segundo plano */
+export type AgtStatus = 'pending' | 'validated' | 'rejected' | null;
+export interface AgtError {
+    idError?: string;
+    descriptionError?: string;
+}
+export interface Invoice {
+    id: string;
+    orgId: string;
+    customerId: string;
+    /** FT = Fatura, FR = Fatura-Recibo */
+    documentType: DocumentType;
+    /** Formato: "{tipo} {série}/{sequencial}" — ex: "FT FT6326S62896N/1" */
+    number?: string | null;
+    /** Código de exibição (sem prefixo de tipo) */
+    displayCode?: string | null;
+    status: InvoiceStatus;
+    /** Subtotal sem IVA, em kwanzas × 100 */
+    subtotal: number;
+    /** IVA total, em kwanzas × 100 */
+    taxAmount: number;
+    /** Total com IVA, em kwanzas × 100 */
+    total: number;
+    currency: string;
+    items: InvoiceItem[];
+    pdfUrl?: string | null;
+    /** Código ATCUD para verificação AGT */
+    atcud?: string | null;
+    hash?: string | null;
+    previousHash?: string | null;
+    /** Estado da validação na AGT — consulta depois de criar, a submissão é assíncrona */
+    agtStatus?: AgtStatus;
+    agtErrors?: AgtError[] | null;
+    notes?: string | null;
+    issuedAt?: string | null;
+    cancelledAt?: string | null;
+    cancelReason?: string | null;
+    createdAt: string;
+}
+export interface CreateInvoiceInput {
+    customerId: string;
+    items: InvoiceItem[];
+    /** FT = Fatura (default), FR = Fatura-Recibo */
+    documentType?: DocumentType;
+    notes?: string;
+    /** Chave de idempotência — gerada automaticamente se omitida */
+    idempotencyKey?: string;
+}
+export interface ListInvoicesParams extends ListParams {
+    status?: InvoiceStatus;
+    documentType?: DocumentType;
+}
+export type ProformaStatus = 'draft' | 'converted' | 'cancelled';
+export interface ProformaInvoice {
+    id: string;
+    orgId: string;
+    customerId: string;
+    /** Código de exibição — hex curto, não segue série AGT (proforma não tem valor fiscal) */
+    displayCode?: string | null;
+    status: ProformaStatus;
+    subtotal: number;
+    taxAmount: number;
+    total: number;
+    currency: string;
+    items: InvoiceItem[];
+    pdfUrl?: string | null;
+    /** Preenchido quando status = 'converted' */
+    convertedInvoiceId?: string | null;
+    convertedAt?: string | null;
+    notes?: string | null;
+    validUntil?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateProformaInput {
+    customerId: string;
+    items: InvoiceItem[];
+    notes?: string;
+    /** Data limite de validade (ISO 8601: "2026-12-31") */
+    validUntil?: string;
+}
+export interface ListProformasParams extends ListParams {
+    status?: ProformaStatus;
+}
+export interface CreditNote {
+    id: string;
+    orgId: string;
+    invoiceId: string;
+    customerId: string;
+    number?: string | null;
+    displayCode?: string | null;
+    status: string;
+    subtotal: number;
+    taxAmount: number;
+    total: number;
+    currency: string;
+    items: InvoiceItem[];
+    reason?: string | null;
+    pdfUrl?: string | null;
+    atcud?: string | null;
+    hash?: string | null;
+    previousHash?: string | null;
+    agtStatus?: AgtStatus;
+    agtErrors?: AgtError[] | null;
+    issuedAt?: string | null;
+    createdAt: string;
+}
+export interface DebitNote {
+    id: string;
+    orgId: string;
+    /** Preenchido quando ligada a uma fatura concreta */
+    invoiceId?: string | null;
+    /** Referência textual à fatura de origem (resolvida a partir de invoiceId, se indicado) */
+    invoiceRef?: string | null;
+    customerId: string;
+    number?: string | null;
+    displayCode?: string | null;
+    status: string;
+    subtotal: number;
+    taxAmount: number;
+    total: number;
+    currency: string;
+    items: InvoiceItem[];
+    reason?: string | null;
+    pdfUrl?: string | null;
+    atcud?: string | null;
+    hash?: string | null;
+    agtStatus?: AgtStatus;
+    agtErrors?: AgtError[] | null;
+    issuedAt?: string | null;
+    createdAt: string;
+}
+export interface CreateDebitNoteInput {
+    /** Cliente a debitar — obrigatório */
+    customerId: string;
+    /** Linhas de débito adicional */
+    items: InvoiceItem[];
+    /** Motivo do débito adicional */
+    reason?: string;
+    /**
+     * UUID de uma fatura desta organização — quando indicado, o Vero usa o número
+     * real dessa fatura como referência perante a AGT (mais seguro que invoiceRef).
+     */
+    invoiceId?: string;
+    /** Referência livre (ignorada se invoiceId for indicado) */
+    invoiceRef?: string;
+}
+export interface Receipt {
+    id: string;
+    orgId: string;
+    customerId: string;
+    invoiceId?: string | null;
+    number?: string | null;
+    displayCode?: string | null;
+    paymentMethod: 'transfer' | 'cash' | 'check';
+    subtotal: number;
+    taxAmount: number;
+    total: number;
+    currency: string;
+    items: InvoiceItem[];
+    pdfUrl?: string | null;
+    atcud?: string | null;
+    hash?: string | null;
+    /** RC é interno — nunca submetido à AGT, por isso não tem agtStatus */
+    issuedAt?: string | null;
+    createdAt: string;
+}
+export interface CreateReceiptInput {
+    /** Método de pagamento */
+    paymentMethod: 'transfer' | 'cash' | 'check';
+}
+export interface Product {
+    id: string;
+    orgId: string;
+    /** Código interno único por organização — opcional */
+    code?: string | null;
+    name: string;
+    description?: string | null;
+    /** Preço unitário em kwanzas × 100 */
+    unitPrice: number;
+    taxRate: 0 | 5 | 14;
+    /** Obrigatório quando taxRate = 0 */
+    taxExemptionCode?: string | null;
+    /** Default 'UN' */
+    unitOfMeasure: string;
+    active: boolean;
+    trackStock: boolean;
+    stockQuantity: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CreateProductInput {
+    /** Obrigatório — mínimo 1 caractere */
+    name: string;
+    code?: string;
+    description?: string;
+    unitPrice: number;
+    /** Default 14 */
+    taxRate?: 0 | 5 | 14;
+    taxExemptionCode?: string;
+    /** Default 'UN' */
+    unitOfMeasure?: string;
+    trackStock?: boolean;
+}
+export interface UpdateProductInput extends Partial<Omit<CreateProductInput, 'code'>> {
+}
+export type WebhookEvent = 'invoice.issued' | 'invoice.cancelled' | 'proforma.converted' | 'proforma.cancelled';
+export interface Webhook {
+    id: string;
+    orgId: string;
+    url: string;
+    events: WebhookEvent[];
+    active: boolean;
+    createdAt: string;
+    /** Segredo HMAC para validar X-Vero-Signature — só vem preenchido na criação, nunca mais é devolvido */
+    secret?: string;
+}
+export interface RegisterWebhookInput {
+    url: string;
+    events: WebhookEvent[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// ─── Config ───────────────────────────────────────────────────────────────────
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@veroao/node",
+  "version": "1.0.0",
+  "description": "Vero SDK for Node.js — faturação certificada AGT para Angola",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vero-ao",
+    "faturacao",
+    "agt",
+    "billing",
+    "invoicing",
+    "angola"
+  ],
+  "author": "Eterim Prestação de Serviços",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eadafonso/vero-sdk-node.git"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.0",
+    "typescript": "^5.3.3"
+  }
+}