SDK Node.js para Portugal
@corp-merch/sdk — TypeScript-first, zero dependências, funciona em Node 18+, Bun, Deno, Vercel e AWS Lambda.
Instalação e init
npm install @corp-merch/sdk. Inicialize: const cm = new CorpMerch({ apiKey: process.env.CM_KEY, country: 'PT', env: 'production' }). O cliente autoload IVA 23% e encaminha faturas via Portal das Finanças (AT); hub Lisboa por defeito.
Quickstart — submeter encomenda
const order = await cm.orders.create({ idempotencyKey: crypto.randomUUID(), buyer: { vatId: 'PT…' }, lines: [{ sku: 'TSH-001', qty: 200 }], promisedDate: '2026-07-01' }); console.log(order.id, order.estimatedIvaAmountCents). Devolve Order tipado com status discriminated-union. Erros lançados como ValidationError / RateLimitError etc.
Verificação webhook
Numa rota Express/Fastify: const event = cm.webhooks.constructEvent(rawBody, req.headers['x-corp-signature'], process.env.CM_WEBHOOK_SECRET); switch (event.type) { case 'invoice.issued': … }. Lança SignatureVerificationError em mismatch ou timestamp velho (>5 min).
FAQ
ESM ou CommonJS?
Ambos — dual package. ESM preferido (.mjs + .d.ts), CommonJS via require() funciona via package.json exports.
Funciona com Bun e Deno?
Sim — testado em CI em Bun 1.x e Deno 1.x com a mesma test suite que Node. Use npm: specifier em Deno ou import direto em Bun.
Como se configuram retries?
3 retries por defeito em 5xx, 429 e erros de rede com backoff. Override via new CorpMerch({ retries: 5, retryBackoffMs: 200 }).
Existe método catalog streaming?
Sim — cm.catalog.list({ country: 'PT' }) devolve AsyncIterator; for await (const item of …) itera todas as páginas automaticamente.
Source disponível?
MIT no GitHub: github.com/corp-merch/sdk-js. PRs bem-vindos; CLA exigido para contribuições não triviais.