@emitia/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro / Propiter <pro.pedro0413@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# @emitia/node
+
+Official Node.js / TypeScript SDK for the [Emitia API](https://docs.emitia.co) — electronic invoicing for Colombia (DIAN), Stripe-style.
+
+**Requirements**: Node.js >= 20, ESM project (`"type": "module"` in package.json).
+
+The SDK ships with a single dependency — `zod` — used **only** to derive the published TypeScript types. It is never imported at runtime: execution runs on native `fetch` with nothing else loaded.
+
+---
+
+## Installation
+
+```bash
+npm install @emitia/node
+# or
+pnpm add @emitia/node
+```
+
+---
+
+## Quickstart
+
+```typescript
+import { Emitia } from '@emitia/node';
+
+const emitia = new Emitia('sk_test_your_key_here');
+
+// List invoices
+const invoices = await emitia.invoices.list({ limit: 10 });
+console.log(invoices.data);
+```
+
+### Create an invoice
+
+```typescript
+const invoice = await emitia.invoices.create({
+  customer_id: 'cust_01HX...',
+  numbering_resolution_id: 'res_01HX...',
+  issue_date: '2024-06-01',
+  currency: 'COP',
+  lines: [
+    {
+      description: 'Servicio de desarrollo',
+      quantity: '1.00',
+      unit_price: '5000000.00',
+      tax_rate: '0.19',
+    },
+  ],
+});
+
+console.log(invoice.id);  // inv_01HX...
+console.log(invoice.status);  // 'processing'
+```
+
+### Typed error handling
+
+All non-2xx responses throw a typed subclass of `EmitiaError`:
+
+```typescript
+import { Emitia, NotFoundError, ValidationError, DianRejectedError } from '@emitia/node';
+
+try {
+  await emitia.invoices.retrieve('inv_nonexistent');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.error('Invoice not found:', err.code);
+  } else if (err instanceof ValidationError) {
+    console.error('Validation failed:', err.details);
+  } else if (err instanceof DianRejectedError) {
+    console.error('DIAN rejected the document:', err.message);
+  }
+}
+```
+
+Error classes: `AuthenticationError`, `PermissionError`, `NotFoundError`, `ValidationError`, `RateLimitError`, `IdempotencyError`, `DianRejectedError`, `DianUnavailableError`, `CertificateError`, `NumberingError`, `ApiError`.
+
+All errors expose: `.type`, `.code`, `.message`, `.requestId`, `.statusCode`, `.docUrl?`, `.details?`.
+
+### Verify a webhook signature
+
+`constructEvent` is a static export — no Emitia instance or API key needed:
+
+```typescript
+import { constructEvent, SignatureVerificationError } from '@emitia/node';
+
+// In your HTTP handler (Express, Fastify, Hono, etc.)
+// IMPORTANT: pass the RAW request body (string or Buffer) — do NOT parse JSON first.
+app.post('/webhooks/emitia', (req, res) => {
+  const signature = req.headers['emitia-signature'] as string;
+  const secret = process.env.WEBHOOK_SIGNING_SECRET!;
+
+  try {
+    const event = constructEvent(req.rawBody, signature, secret);
+
+    switch (event.type) {
+      case 'invoice.accepted':
+        // Handle accepted invoice
+        break;
+      case 'invoice.rejected_by_dian':
+        // Handle rejection
+        break;
+    }
+
+    res.status(200).send({ received: true });
+  } catch (err) {
+    if (err instanceof SignatureVerificationError) {
+      // err.reason: 'no_signature' | 'timestamp_out_of_tolerance' | 'signature_mismatch'
+      res.status(400).send({ error: err.message });
+      return;
+    }
+    throw err;
+  }
+});
+```
+
+**Security**: `constructEvent` uses `crypto.timingSafeEqual` for HMAC comparison and rejects events older than 5 minutes (configurable via `toleranceSec` parameter) to prevent replay attacks.
+
+---
+
+## API Reference
+
+### `new Emitia(apiKey, opts?)`
+
+| Option | Type | Default |
+|---|---|---|
+| `baseURL` | `string` | `https://api.emitia.co` |
+| `timeout` | `number` (ms) | `30000` |
+| `maxRetries` | `number` | `2` |
+
+Throws synchronously if `apiKey` does not start with `sk_test_` or `sk_live_`.
+
+### Resource namespaces
+
+| Namespace | Description |
+|---|---|
+| `emitia.account` | Tenant account info |
+| `emitia.balance` | Account balance |
+| `emitia.catalogs` | DIAN catalogs (municipios, etc.) |
+| `emitia.certificates` | Digital signing certificates |
+| `emitia.customers` | Customers / billing entities |
+| `emitia.invoices` | Electronic invoices (FE) |
+| `emitia.creditNotes` | Credit notes (NC) |
+| `emitia.debitNotes` | Debit notes (ND) |
+| `emitia.numberingResolutions` | DIAN numbering resolutions |
+| `emitia.test` | Test utilities (sandbox only) |
+
+### `constructEvent(payload, signatureHeader, secret, toleranceSec?)`
+
+Static function. Verifies the `Emitia-Signature` header and returns the parsed event.
+
+| Parameter | Type | Default |
+|---|---|---|
+| `payload` | `string \| Buffer` | — |
+| `signatureHeader` | `string` | — |
+| `secret` | `string` | — |
+| `toleranceSec` | `number` | `300` |
+
+Returns `EmitiaEvent`: `{ id, type, api_version, created, data }`.
+
+Throws `SignatureVerificationError` on failure. Check `.reason` for the specific cause.
+
+---
+
+## Links
+
+- [API Documentation](https://docs.emitia.co)
+- [Error codes](https://docs.emitia.co/errors)
+- [Webhook events](https://docs.emitia.co/webhooks)