@emitti/node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emitti
+
+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,43 @@
+# @emitti/node
+
+SDK oficial do Emitti para Node.js (>= 18). Envelopa a API REST em métodos nativos.
+
+```bash
+npm install @emitti/node
+```
+
+```ts
+import { Emitti, webhooks } from "@emitti/node";
+
+const emitti = new Emitti({ apiKey: process.env.EMITTI_API_KEY! });
+
+const nota = await emitti.emitir({
+  prestador: { cnpj: "12345678000190", inscricao_municipal: "1122334" },
+  tomador: { razao_social: "Cliente X", cnpj: "98765432000110" },
+  servico: {
+    codigo_municipio: "3550308", codigo_servico: "01.05",
+    discriminacao: "Plano SaaS", valor_servicos: 499.9, aliquota_iss: 2,
+  },
+});
+// nota.emissao_id, nota.status === "QUEUED"
+
+await emitti.consultar(nota.emissao_id);
+await emitti.cancelar(nota.emissao_id);
+await emitti.substituir(nota.emissao_id, { /* nova nota */ });
+const xml = await emitti.baixarXml(nota.emissao_id);
+const pdf = await emitti.baixarPdf(nota.emissao_id); // Uint8Array
+```
+
+## Webhooks
+
+```ts
+// no seu handler (use o corpo CRU)
+const ok = webhooks.verificar(rawBody, req.headers["x-emitti-signature"], process.env.EMITTI_WEBHOOK_SECRET!);
+if (!ok) return res.status(400).end();
+```
+
+## Build/test (deste repo)
+
+```bash
+npm install && npm run build && npm test
+```

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+export interface EmittiOptions {
+    apiKey: string;
+    /** Default: https://api.emitti.com.br */
+    baseUrl?: string;
+}
+export interface Endereco {
+    tipo_logradouro?: string;
+    logradouro?: string;
+    numero?: string;
+    complemento?: string;
+    bairro?: string;
+    cidade_ibge?: string;
+    uf?: string;
+    cep?: string;
+}
+export interface NfseInput {
+    referencia_externa?: string;
+    prestador: {
+        cnpj: string;
+        inscricao_municipal: string;
+    };
+    tomador: {
+        razao_social?: string;
+        cnpj?: string;
+        cpf?: string;
+        email?: string;
+        endereco?: Endereco;
+    };
+    servico: {
+        codigo_municipio: string;
+        codigo_servico: string;
+        discriminacao: string;
+        valor_servicos: number;
+        aliquota_iss: number;
+        iss_retido?: boolean;
+        valor_deducoes?: number;
+    };
+}
+export interface Emissao {
+    emissao_id: string;
+    status: string;
+    referencia_externa?: string | null;
+    resultado?: Record<string, unknown> | null;
+}
+export declare class EmittiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(status: number, body: unknown);
+}
+export declare class Emitti {
+    private readonly opts;
+    private readonly base;
+    constructor(opts: EmittiOptions);
+    private req;
+    /** Emite uma NFS-e (assíncrono). Resposta 202 com o emissao_id. */
+    emitir(input: NfseInput, opts?: {
+        idempotencyKey?: string;
+    }): Promise<Emissao>;
+    /** Consulta o status de uma emissão. */
+    consultar(emissaoId: string): Promise<Emissao>;
+    /** Cancela uma NFS-e autorizada (assíncrono). */
+    cancelar(emissaoId: string): Promise<Emissao>;
+    /** Substitui uma NFS-e: emite a nova e cancela a antiga. */
+    substituir(emissaoId: string, input: NfseInput): Promise<Emissao>;
+    /** Baixa o XML autorizado (string). */
+    baixarXml(emissaoId: string): Promise<string>;
+    /** Baixa o DANFE/RPS em PDF (bytes). */
+    baixarPdf(emissaoId: string): Promise<Uint8Array>;
+}
+/** Helpers de webhook: valide a assinatura antes de confiar no payload. */
+export declare const webhooks: {
+    /** Confere o header X-Emitti-Signature (HMAC-SHA256 do corpo cru). */
+    verificar(rawBody: string | Uint8Array, signature: string, secret: string): boolean;
+};

package/dist/index.js

@@ -0,0 +1,87 @@
+/**
+ * SDK oficial do Emitti para Node.js (>= 18).
+ *
+ *   import { Emitti } from "@emitti/node";
+ *   const emitti = new Emitti({ apiKey: process.env.EMITTI_API_KEY! });
+ *   const { emissao_id } = await emitti.emitir({ ... });
+ */
+import { createHmac, timingSafeEqual } from "node:crypto";
+export class EmittiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Emitti API respondeu ${status}`);
+        this.status = status;
+        this.body = body;
+        this.name = "EmittiError";
+    }
+}
+export class Emitti {
+    opts;
+    base;
+    constructor(opts) {
+        this.opts = opts;
+        this.base = (opts.baseUrl ?? "https://api.emitti.com.br").replace(/\/$/, "");
+    }
+    async req(method, path, body, idempotencyKey) {
+        const res = await fetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.opts.apiKey}`,
+                ...(body ? { "Content-Type": "application/json" } : {}),
+                ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
+            },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            let parsed = undefined;
+            try {
+                parsed = await res.json();
+            }
+            catch {
+                /* corpo não-JSON */
+            }
+            throw new EmittiError(res.status, parsed);
+        }
+        return res;
+    }
+    /** Emite uma NFS-e (assíncrono). Resposta 202 com o emissao_id. */
+    async emitir(input, opts) {
+        return (await this.req("POST", "/v1/nfse", input, opts?.idempotencyKey)).json();
+    }
+    /** Consulta o status de uma emissão. */
+    async consultar(emissaoId) {
+        return (await this.req("GET", `/v1/nfse/${emissaoId}`)).json();
+    }
+    /** Cancela uma NFS-e autorizada (assíncrono). */
+    async cancelar(emissaoId) {
+        return (await this.req("DELETE", `/v1/nfse/${emissaoId}`)).json();
+    }
+    /** Substitui uma NFS-e: emite a nova e cancela a antiga. */
+    async substituir(emissaoId, input) {
+        return (await this.req("POST", `/v1/nfse/${emissaoId}/substituicao`, input)).json();
+    }
+    /** Baixa o XML autorizado (string). */
+    async baixarXml(emissaoId) {
+        return (await this.req("GET", `/v1/nfse/${emissaoId}/xml`)).text();
+    }
+    /** Baixa o DANFE/RPS em PDF (bytes). */
+    async baixarPdf(emissaoId) {
+        const buf = await (await this.req("GET", `/v1/nfse/${emissaoId}/pdf`)).arrayBuffer();
+        return new Uint8Array(buf);
+    }
+}
+/** Helpers de webhook: valide a assinatura antes de confiar no payload. */
+export const webhooks = {
+    /** Confere o header X-Emitti-Signature (HMAC-SHA256 do corpo cru). */
+    verificar(rawBody, signature, secret) {
+        const corpo = typeof rawBody === "string" ? Buffer.from(rawBody) : Buffer.from(rawBody);
+        const esperado = createHmac("sha256", secret).update(corpo).digest("hex");
+        try {
+            return timingSafeEqual(Buffer.from(signature), Buffer.from(esperado));
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@emitti/node",
+  "version": "0.1.0",
+  "description": "SDK oficial do Emitti para Node.js — emissão de NFS-e",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "keywords": ["emitti", "nfse", "nota-fiscal", "fiscal", "api", "sefaz"],
+  "license": "MIT",
+  "author": "Emitti",
+  "homepage": "https://docs.emitti.com.br/sdks#node",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emittibr/emitti-docs.git",
+    "directory": "sdks/node"
+  },
+  "bugs": { "url": "https://github.com/emittibr/emitti-docs/issues" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "typescript": "^5.6.2"
+  }
+}