@veroao/core 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# @veroao/core
+
+Cliente partilhado, mínimo, para os endpoints de **widget** do Vero - a base usada internamente
+pelos pacotes [`@veroao/react`](https://www.npmjs.com/package/@veroao/react) e
+[`@veroao/widget`](https://www.npmjs.com/package/@veroao/widget).
+
+> **A maioria dos integradores não precisa deste pacote directamente.** Se estás a construir no
+> browser (checkout, formulário de factura embutido), usa `@veroao/react` ou `@veroao/widget`. Se
+> estás no servidor com acesso à API completa, usa [`@veroao/node`](https://www.npmjs.com/package/@veroao/node).
+
+## Porque é que isto existe
+
+Os endpoints `/v1/widget/...` são uma superfície deliberadamente pequena e segura para expor no
+browser: só pesquisa de clientes e criação de factura, pensados para serem usados com uma
+**chave publicável** (`vero_live_pk_...`), que o servidor recusa em qualquer outra rota. Este
+pacote só fala com essas duas rotas.
+
+## Instalação
+
+```bash
+npm install @veroao/core
+```
+
+## Uso
+
+```typescript
+import { VeroAOClient } from '@veroao/core'
+
+const client = new VeroAOClient({
+  apiKey: 'vero_live_pk_...', // chave publicável - segura para o browser
+})
+
+const { data: customers } = await client.listCustomers(orgId, { search: 'Maria', limit: 8 })
+
+const invoice = await client.createInvoice(orgId, {
+  customerId: customers[0].id,
+  documentType: 'FR',
+  items: [{ description: 'Plano Pro', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+})
+
+console.log(invoice.pdfUrl) // link público de download, sem autenticação
+```
+
+## Tratamento de erros
+
+Um pedido falhado lança o corpo de erro da API directamente:
+
+```typescript
+try {
+  await client.createInvoice(orgId, input)
+} catch (err) {
+  const apiErr = err as { error: string; message?: string }
+  if (apiErr.error === 'customer_not_found') {
+    // ...
+  }
+}
+```
+
+## Referência
+
+### `new VeroAOClient(config)`
+
+| Campo         | Obrigatório | Descrição                                  |
+|---------------|:-----------:|----------------------------------------------|
+| `apiKey`      | sim         | Chave publicável (`vero_live_pk_...` / `vero_test_pk_...`) |
+| `baseUrl`     | não         | Default `https://api.vero.ao/v1`             |
+
+### `client.listCustomers(orgId, params?)`
+
+`params`: `{ search?: string; limit?: number }` - devolve `{ data: Customer[] }`.
+
+### `client.createInvoice(orgId, input)`
+
+`input`: `{ customerId, items, documentType?, notes?, idempotencyKey? }` - devolve a factura criada.
+
+## Preciso de mais do que isto
+
+Não é possível com uma chave publicável - o servidor só a aceita nestas duas rotas. Para gerir
+produtos, listar facturas existentes, emitir notas de crédito/débito, etc., usa um backend teu com
+`@veroao/node` e a chave secreta; este pacote (e o browser em geral) fala com esse backend, nunca
+directamente com o Vero para essas operações.
+
+Esse backend não precisa de ser Node - é só a opção mais directa. Qualquer linguagem (PHP,
+Python, Ruby, etc.) consegue chamar a API REST directamente com o seu próprio cliente HTTP, com
+as mesmas operações disponíveis. Exemplos em cURL, Python e PHP em [vero.ao/docs](https://vero.ao/docs).

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import type { VeroAOConfig, Customer, Invoice, CreateInvoiceInput, SearchCustomersParams } from "./types.js";
+export declare class VeroAOClient {
+    private apiKey;
+    private baseUrl;
+    constructor(config: VeroAOConfig);
+    private request;
+    listCustomers(orgId: string, params?: SearchCustomersParams): Promise<{
+        data: Customer[];
+    }>;
+    createInvoice(orgId: string, input: CreateInvoiceInput): Promise<Invoice>;
+}

package/dist/client.js

@@ -0,0 +1,36 @@
+export class VeroAOClient {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl || "https://api.vero.ao/v1";
+    }
+    async request(method, path, body, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            Object.entries(params).forEach(([k, v]) => {
+                if (v !== undefined)
+                    url.searchParams.append(k, String(v));
+            });
+        }
+        const response = await fetch(url.toString(), {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw data;
+        }
+        return data;
+    }
+    async listCustomers(orgId, params = {}) {
+        return this.request("GET", `/widget/organisations/${orgId}/customers`, undefined, params);
+    }
+    async createInvoice(orgId, input) {
+        return this.request("POST", `/widget/organisations/${orgId}/invoices`, input);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./client.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./client.js";

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+export interface VeroAOConfig {
+    apiKey: string;
+    baseUrl?: string;
+    environment?: "live" | "test";
+}
+export interface VeroAOError {
+    error: string;
+    message?: string;
+}
+export interface ListMeta {
+    total: number;
+    page: number;
+    limit: number;
+    pages: number;
+}
+export interface Customer {
+    id: string;
+    orgId: string;
+    name: string;
+    email?: string | null;
+    taxId?: string | null;
+    phone?: string | null;
+    addressLine1?: string | null;
+    addressLine2?: string | null;
+    city?: string | null;
+    province?: string | null;
+    country?: string | null;
+    externalId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Organisation {
+    id: string;
+    userId: string;
+    name: string;
+    legalName?: string;
+    taxId?: string;
+    email?: string;
+    phone?: string;
+    addressLine1?: string;
+    city?: string;
+    country?: string;
+}
+export interface InvoiceItem {
+    description: string;
+    quantity: number;
+    unitPrice: number;
+    taxRate?: number;
+}
+export interface Invoice {
+    id: string;
+    orgId: string;
+    customerId: string;
+    number?: string | null;
+    displayCode?: string | null;
+    status: "pending" | "issued" | "paid" | "failed" | "cancelled";
+    total: number;
+    subtotal: number;
+    taxAmount: number;
+    currency: string;
+    items?: InvoiceItem[];
+    pdfUrl?: string | null;
+    atcud?: string | null;
+    hash?: string | null;
+    issuedAt?: string | null;
+    createdAt: string;
+    customerSnapshot?: Record<string, unknown>;
+    orgSnapshot?: Record<string, unknown>;
+}
+export interface CreateInvoiceInput {
+    customerId: string;
+    items: InvoiceItem[];
+    notes?: string;
+    idempotencyKey?: string;
+    documentType?: "FT" | "FR";
+}
+export interface CreateCustomerDTO {
+    name: string;
+    taxId?: string;
+    email?: string;
+    phone?: string;
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    province?: string;
+    country?: string;
+    externalId?: string;
+}
+export interface SearchCustomersParams {
+    search?: string;
+    page?: number;
+    limit?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@veroao/core",
+  "version": "1.0.0",
+  "description": "Cliente partilhado e mínimo para os endpoints de widget do Vero — base do @veroao/react e @veroao/widget",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["vero-ao", "faturacao", "agt", "angola", "invoicing"],
+  "author": "Eterim Prestação de Serviços",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eadafonso/vero-sdk-core.git"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}