SDK Node.js per l'Italia
@corp-merch/sdk — TypeScript-first, zero dipendenze, funziona su Node 18+, Bun, Deno, Vercel e AWS Lambda.
Install e init
npm install @corp-merch/sdk. Inizializza: const cm = new CorpMerch({ apiKey: process.env.CM_KEY, country: 'IT', env: 'production' }). Il client autoload IVA 22% e instrada fatture via SdI; hub Milano di default.
Quickstart — invio ordine
const order = await cm.orders.create({ idempotencyKey: crypto.randomUUID(), buyer: { vatId: 'IT…' }, lines: [{ sku: 'TSH-001', qty: 200 }], promisedDate: '2026-07-01' }); console.log(order.id, order.estimatedIvaAmountCents). Ritorna Order tipizzato con status discriminated-union. Errori sollevati come ValidationError / RateLimitError ecc.
Verifica webhook
In una route Express/Fastify: const event = cm.webhooks.constructEvent(rawBody, req.headers['x-corp-signature'], process.env.CM_WEBHOOK_SECRET); switch (event.type) { case 'invoice.issued': … }. Solleva SignatureVerificationError su mismatch o timestamp stantio (>5 min).
FAQ
ESM o CommonJS?
Entrambi — dual package. ESM preferito (.mjs + .d.ts), CommonJS via require() funziona via package.json exports.
Funziona con Bun e Deno?
Sì — testato in CI su Bun 1.x e Deno 1.x con la stessa test suite di Node. Usa npm: specifier in Deno o import diretto in Bun.
Come si configurano i retry?
Default 3 retry su 5xx, 429 e errori network con backoff. Override via new CorpMerch({ retries: 5, retryBackoffMs: 200 }).
C'è un metodo catalog streaming?
Sì — cm.catalog.list({ country: 'IT' }) restituisce AsyncIterator; for await (const item of …) itera su tutte le pagine automaticamente (gestione cursor interna).
Source disponibile?
MIT su GitHub: github.com/corp-merch/sdk-js. PR benvenute; CLA richiesto per contributi non triviali.