@veroao/react 1.0.0

package/README.md

@@ -0,0 +1,124 @@
+# @veroao/react
+
+SDK React para o Vero - integra pesquisa de clientes e emissão de factura directamente no teu
+checkout, usando uma chave segura para o browser.
+
+## Instalação
+
+```bash
+npm install @veroao/react
+```
+
+`react` e `react-dom` (>=18) são peer dependencies - usa as que já tens no projecto.
+
+## Chave publicável - segura para o browser
+
+Este SDK foi desenhado para correr no cliente (browser), por isso usa uma **chave publicável**
+(`vero_live_pk_...` / `vero_test_pk_...`), diferente da chave secreta usada no
+[`@veroao/node`](https://www.npmjs.com/package/@veroao/node). Cria-a no dashboard, em
+Chaves de API, escolhendo o tipo "Publicável".
+
+Mesmo que alguém veja esta chave no código-fonte da página, o servidor só a aceita nos endpoints
+de widget (pesquisar clientes, emitir factura) - nunca dá acesso à tua conta completa.
+
+## Quick start
+
+```tsx
+import { VeroAOProvider, useVeroAO } from '@veroao/react'
+
+function App() {
+  return (
+    <VeroAOProvider config={{ apiKey: 'vero_live_pk_...' }}>
+      <CheckoutButton />
+    </VeroAOProvider>
+  )
+}
+
+function CheckoutButton() {
+  const { client } = useVeroAO()
+
+  const handleCreateInvoice = async () => {
+    const { data: customers } = await client.listCustomers(orgId, { search: 'Maria' })
+
+    const invoice = await client.createInvoice(orgId, {
+      customerId: customers[0].id,
+      documentType: 'FR',
+      items: [{ description: 'Plano Pro', quantity: 1, unitPrice: 500000, taxRate: 14 }],
+    })
+
+    window.open(invoice.pdfUrl!, '_blank') // link público, sem autenticação
+  }
+
+  return <button onClick={handleCreateInvoice}>Emitir factura</button>
+}
+```
+
+## Configuração do Provider
+
+```tsx
+<VeroAOProvider config={{
+  apiKey: 'vero_live_pk_...',
+  baseUrl: 'https://api.custom.ao/v1', // opcional - útil para testes locais
+  environment: 'live',                  // opcional, default 'test'
+}}>
+  {children}
+</VeroAOProvider>
+```
+
+## `useVeroAO()`
+
+Devolve `{ client, isLoading, error }`. `client` expõe:
+
+- `client.listCustomers(orgId, { search?, limit? })` → `{ data: Customer[] }`
+- `client.createInvoice(orgId, { customerId, items, documentType?, notes?, idempotencyKey? })` → `Invoice`
+
+## Tratamento de erros
+
+```tsx
+try {
+  await client.createInvoice(orgId, input)
+} catch (err) {
+  const apiErr = err as { error: string; message?: string }
+  if (apiErr.error === 'customer_not_found') {
+    // cliente não encontrado nesta organização
+  }
+}
+```
+
+## Preços em kwanzas
+
+Os valores monetários usam **kwanzas × 100**: `unitPrice: 500000` equivale a 5 000,00 AOA.
+
+## Preciso de mais do que isto - criar produtos, listar facturas, notas de crédito...
+
+Este SDK só sabe fazer as duas coisas acima, **de propósito**: a chave publicável que usa é
+restrita pelo servidor a essas rotas, para ser segura no browser. Não existe forma de "desbloquear"
+mais operações com uma chave publicável - nem gerir produtos, nem listar facturas existentes, nem
+emitir notas de crédito/débito, nem apagar clientes.
+
+Se precisas de qualquer uma dessas operações a partir de uma aplicação React, o padrão correcto é:
+
+```
+React (browser)  →  o TEU backend  →  Vero (com @veroao/node + chave secreta)
+```
+
+Ou seja, cria uma rota de API tua (Next.js API route, Express, etc.) que use
+[`@veroao/node`](https://www.npmjs.com/package/@veroao/node) com a chave secreta, e chama essa
+rota a partir do React - nunca a API do Vero directamente para essas operações.
+
+```typescript
+// app/api/products/route.ts (exemplo Next.js)
+import { createVeroClient } from '@veroao/node'
+
+const vero = createVeroClient() // VERO_API_KEY - chave secreta, só no servidor
+
+export async function POST(req: Request) {
+  const body = await req.json()
+  const product = await vero.products.create(ORG_ID, body)
+  return Response.json(product)
+}
+```
+
+O backend não precisa de ser Node - é só o exemplo mais directo. Se for PHP, Python, Ruby, etc.,
+chama a API REST directamente com o cliente HTTP dessa linguagem; tens as mesmas operações
+disponíveis. Exemplos em cURL, Python e PHP em [vero.ao/docs](https://vero.ao/docs).

package/dist/VeroAOProvider.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from "react";
+import { VeroAOClient } from "./client.js";
+import type { VeroAOConfig } from "./types.js";
+export interface VeroAOContextValue {
+    client: VeroAOClient;
+    isLoading: boolean;
+    error: Error | null;
+}
+export interface VeroAOProviderProps {
+    config: VeroAOConfig;
+    children: ReactNode;
+}
+export declare function VeroAOProvider({ config, children }: VeroAOProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useVeroAO(): VeroAOContextValue;

package/dist/VeroAOProvider.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { VeroAOClient } from "./client.js";
+const VeroAOContext = createContext(null);
+export function VeroAOProvider({ config, children }) {
+    const client = useMemo(() => new VeroAOClient(config), [config]);
+    return (_jsx(VeroAOContext.Provider, { value: { client, isLoading: false, error: null }, children: children }));
+}
+export function useVeroAO() {
+    const context = useContext(VeroAOContext);
+    if (!context) {
+        throw new Error("useVeroAO must be used within a VeroAOProvider");
+    }
+    return context;
+}

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import type { VeroAOConfig, Customer, Invoice, CreateInvoiceInput, SearchCustomersParams } from "./types.js";
+export declare class VeroAOClient {
+    private apiKey;
+    private environment;
+    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,38 @@
+export class VeroAOClient {
+    apiKey;
+    environment;
+    baseUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.environment = config.environment ?? "test";
+        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,3 @@
+export * from "./VeroAOProvider.js";
+export * from "./client.js";
+export * from "./types.js";

package/dist/index.js

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

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+export interface VeroAOConfig {
+    apiKey: string;
+    /** Override da URL base (útil para testes locais) */
+    baseUrl?: string;
+    environment?: "live" | "test";
+}
+export interface VeroAOError {
+    /** Código de erro da API — ex: "customer_not_found", "unauthorized" */
+    error: string;
+    message?: string;
+}
+export interface Customer {
+    id: string;
+    orgId: string;
+    name: string;
+    taxId?: string | null;
+    email?: string | null;
+    phone?: string | null;
+}
+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;
+    pdfUrl?: string | null;
+    atcud?: string | null;
+    issuedAt?: string | null;
+    createdAt: string;
+}
+export interface CreateInvoiceInput {
+    customerId: string;
+    items: InvoiceItem[];
+    notes?: string;
+    idempotencyKey?: string;
+    documentType?: "FT" | "FR";
+}
+export interface SearchCustomersParams {
+    search?: string;
+    limit?: number;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@veroao/react",
+  "version": "1.0.0",
+  "description": "Vero-AO SDK for React — faturação certificada AGT em aplicações React",
+  "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", "angola", "invoicing", "react"],
+  "author": "Eterim Prestação de Serviços",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eadafonso/vero-sdk-react.git"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.3.3"
+  }
+}