@keysoftinc/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KEYSOFT INC (Softzone Systems)
+
+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,111 @@
+# @keysoftinc/sdk
+
+Facturación electrónica SUNAT desde TypeScript. **Sin dependencias.**
+
+```bash
+npm install @keysoftinc/sdk
+```
+
+## De cero a una factura aceptada
+
+```ts
+import { KeySoft } from '@keysoftinc/sdk'
+
+const keysoft = new KeySoft(process.env.KEYSOFT_API_KEY!)
+
+// El ambiente sale de la clave: ks_test_ es pruebas, ks_live_ es producción.
+console.log(keysoft.environment) // 'DEMO'
+
+const { document } = await keysoft.issue(
+  companyId,
+  {
+    documentType: 'FACTURA',
+    series: 'F001',
+    customer: {
+      identityType: 'RUC',
+      identityValue: '20601234567',
+      legalName: 'DISTRIBUIDORA DEL NORTE S.A.C.',
+      email: 'compras@cliente.pe', // le llega su factura al aceptarse
+    },
+    lines: [{ description: 'Servicio de consultoría', quantity: 2, unitValue: 150 }],
+  },
+  { idempotencyKey: `pedido-${pedido.id}` },
+)
+
+const { cdr } = await keysoft.send(companyId, document.id)
+console.log(cdr?.description) // "La Factura numero F001-00000001, ha sido aceptada"
+```
+
+## Idempotencia
+
+`issue()` **manda `Idempotency-Key` por defecto**. Si tu proceso reintenta por un
+timeout, sin ella emitirías **dos facturas** — y una factura de más es un problema
+fiscal, no un duplicado inocente.
+
+Pásale la tuya: el id de tu pedido es la mejor opción, porque sobrevive a un
+reinicio de tu proceso.
+
+## Los errores dicen qué hacer
+
+```ts
+import { KeySoftError } from '@keysoftinc/sdk'
+
+try {
+  await keysoft.issue(companyId, factura)
+} catch (e) {
+  if (e instanceof KeySoftError) {
+    console.error(e.code) // 'certificate_missing' — estable, programa contra él
+    console.error(e.message) // en castellano
+    console.error(e.action) // qué hacer para arreglarlo
+    if (e.retryable) await reintentar()
+  }
+}
+```
+
+## Descargar y verificar
+
+`download()` **recalcula el SHA-256 y lanza si no cuadra**. No te fíes de nosotros:
+la comprobación es el producto.
+
+```ts
+const { content } = await keysoft.download(companyId, document.id, 'xml')
+```
+
+## Boletas: el reloj de los 7 días
+
+Una boleta no se envía sola — va en el resumen diario, y **caduca a los 7 días
+calendario** sin que nadie te avise. Por eso `summaries()` te dice cuántos quedan.
+
+```ts
+const { pending, alert } = await keysoft.summaries(companyId)
+if (alert.level !== 'ok') console.warn(alert.message)
+// "Quedan 2 día(s) para informar las boletas más antiguas sin resumen."
+```
+
+## Webhooks
+
+```ts
+import { verifyWebhook } from '@keysoftinc/sdk'
+
+app.post(
+  '/hooks/keysoft',
+  express.raw({ type: 'application/json' }),
+  async (req, res) => {
+    const ok = await verifyWebhook({
+      body: req.body.toString(), // el cuerpo CRUDO
+      signature: req.get('keysoft-signature')!,
+      secret: process.env.KEYSOFT_WEBHOOK_SECRET!,
+    })
+    if (!ok) return res.status(400).end()
+
+    const { event, data } = JSON.parse(req.body.toString())
+    res.status(200).end()
+  },
+)
+```
+
+**El cuerpo tiene que ser el crudo.** Si lo parseas y lo vuelves a serializar la
+firma deja de cuadrar: es el fallo más común al integrarlo.
+
+La firma **caduca a los 5 minutos**, que es lo que impide que quien capture una
+petición válida te la reenvíe mañana.

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+/**
+ * SDK de TypeScript para la API de KeySoft (proceso P15).
+ *
+ * **Sin dependencias.** Usa `fetch`, que está en Node 18+ y en cualquier navegador,
+ * porque un SDK de facturación que arrastra medio `node_modules` es un SDK que
+ * nadie quiere meter en su servidor de producción.
+ *
+ * Lo que hace por ti y no se ve:
+ *
+ *   · Manda `Idempotency-Key` **por defecto** al emitir. Es la protección que más
+ *     falta hace y la que más se olvida.
+ *   · Convierte los errores de la API en `KeySoftError`, con el código estable y
+ *     **qué hacer** — no en un `Error: Request failed with status code 422`.
+ *   · **Comprueba el hash** de cada fichero que descargas. No te fíes de nosotros.
+ */
+export type Environment = 'DEMO' | 'PRODUCTION';
+export type DocumentType = 'FACTURA' | 'BOLETA' | 'NOTA_CREDITO' | 'NOTA_DEBITO';
+export type IdentityType = 'RUC' | 'DNI' | 'CE' | 'PASAPORTE' | 'OTROS';
+export type IgvType = 'GRAVADO_ONEROSA' | 'GRAVADO_GRATUITA' | 'EXONERADO_ONEROSA' | 'EXONERADO_GRATUITA' | 'INAFECTO_ONEROSA' | 'INAFECTO_GRATUITA' | 'EXPORTACION';
+/** Un importe. Manda cadena si te preocupa la precisión de los flotantes. */
+export type Amount = number | string;
+/**
+ * Una línea. El precio va de una de dos formas, y solo de una: `unitValue`, sin IGV,
+ * o `unitPrice`, con IGV —el del letrero—. Con `unitPrice` el total de la línea
+ * sale exacto (cantidad × precio) y el IGV, por diferencia.
+ */
+export type Line = {
+    description: string;
+    quantity: Amount;
+    unitCode?: string;
+    igvType?: IgvType;
+    discount?: Amount;
+    sku?: string;
+    sunatCode?: string;
+    /**
+     * Bolsas de plástico: suma el impuesto por bolsa (ICBPER, S/ 0.50 desde 2023)
+     * aparte del precio. En soles, bolsas enteras y con precio.
+     */
+    icbper?: boolean;
+} & ({
+    unitValue: Amount;
+    unitPrice?: never;
+} | {
+    unitPrice: Amount;
+    unitValue?: never;
+});
+export type NewDocument = {
+    documentType: DocumentType;
+    series: string;
+    customer: {
+        identityType: IdentityType;
+        identityValue: string;
+        legalName: string;
+        address?: string;
+        /** Si lo mandas, al comprador le llega su factura cuando SUNAT la acepte. */
+        email?: string;
+    };
+    lines: Line[];
+    issueDate?: string;
+    dueDate?: string;
+    currency?: 'PEN' | 'USD' | 'EUR';
+    payment?: {
+        method: 'CONTADO' | 'CREDITO';
+        installments?: {
+            amount: Amount;
+            dueDate: string;
+        }[];
+    };
+    note?: {
+        type: string;
+        reason: string;
+        affectedDocumentId: string;
+    };
+};
+export type DocumentView = {
+    id: string;
+    fullNumber: string;
+    documentType: DocumentType;
+    status: string;
+    environment: Environment;
+    issueDate: string;
+    totals: Record<string, string>;
+    sunat: {
+        code: string | null;
+        description: string | null;
+        notes: string[];
+        acceptedAt: string | null;
+    };
+};
+/**
+ * Un error de la API, con lo que hace falta para reaccionar.
+ *
+ * `code` es estable: puedes programar contra él. `action` dice qué hacer, y en la
+ * mayoría de los casos se le puede enseñar al usuario tal cual.
+ */
+export declare class KeySoftError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly action?: string;
+    readonly details?: unknown;
+    constructor(args: {
+        status: number;
+        code: string;
+        message: string;
+        action?: string;
+        details?: unknown;
+    });
+    /** ¿Reintentar tiene sentido? Un 422 no se arregla insistiendo. */
+    get retryable(): boolean;
+}
+export type KeySoftOptions = {
+    apiKey: string;
+    /** Por defecto, la API pública. */
+    baseUrl?: string;
+    /** Milisegundos. Por defecto 30 s: SUNAT puede tardar. */
+    timeoutMs?: number;
+};
+export declare class KeySoft {
+    #private;
+    constructor(options: KeySoftOptions | string);
+    /** El ambiente sale de la clave, no de una opción: `ks_live_` es producción. */
+    get environment(): Environment;
+    /**
+     * Emite un comprobante.
+     *
+     * **Manda `Idempotency-Key` por defecto.** Si tu proceso reintenta por un
+     * timeout, sin ella emitirías dos facturas — y una factura de más es un problema
+     * fiscal, no un duplicado inocente. Pasa la tuya (el id de tu pedido es ideal) o
+     * deja que genere una.
+     */
+    issue(companyId: string, document: NewDocument, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        document: DocumentView;
+        file: {
+            name: string;
+            sha256: string;
+            sizeBytes: number;
+        };
+        idempotent: boolean;
+        quota?: {
+            level: string;
+            message: string;
+        };
+    }>;
+    /** Envía a SUNAT y devuelve el CDR. Una boleta va por resumen diario. */
+    send(companyId: string, documentId: string): Promise<{
+        document: DocumentView;
+        cdr: {
+            code: string;
+            description: string;
+            notes: string[];
+            hasFiscalValidity: boolean;
+        } | null;
+        message: string;
+        action?: string;
+        alreadyResolved: boolean;
+    }>;
+    /**
+     * Descarga un fichero **y comprueba su hash**.
+     *
+     * El XML y el CDR vienen con su SHA-256 declarado; este método lo recalcula y
+     * lanza si no cuadra. **No te fíes de nosotros:** la comprobación es el producto.
+     */
+    download(companyId: string, documentId: string, kind: 'xml' | 'cdr' | 'pdf'): Promise<{
+        content: Uint8Array;
+        sha256: string | null;
+    }>;
+    /** Entrega el comprobante al comprador por correo. */
+    deliver(companyId: string, documentId: string, options?: {
+        email?: string;
+        resend?: boolean;
+    }): Promise<{
+        delivered: boolean;
+        alreadyDelivered: boolean;
+        message: string;
+    }>;
+    /** Los resúmenes y **cuántos días quedan** para informar cada día de boletas. */
+    summaries(companyId: string): Promise<{
+        summaries: unknown[];
+        pending: {
+            referenceDate: string;
+            documents: number;
+            daysLeft: number;
+            expired: boolean;
+        }[];
+        alert: {
+            level: "ok" | "urgent" | "expired";
+            message: string;
+        };
+    }>;
+    createSummary(companyId: string, referenceDate?: string): Promise<{
+        summary: {
+            id: string;
+            identifier: string;
+        };
+        documents: number;
+    }>;
+    /** Devuelve un **ticket**, no un veredicto. Las boletas siguen sin informar. */
+    sendSummary(companyId: string, summaryId: string): Promise<{
+        ticket: string | null;
+        informed: boolean;
+        message: string;
+    }>;
+    /** Consulta el ticket y propaga el resultado a cada boleta. */
+    summaryStatus(companyId: string, summaryId: string): Promise<{
+        processing: boolean;
+        informed: boolean;
+        propagatedTo: number;
+        message: string;
+    }>;
+    /** Tu consumo del mes. **`emissionBlocked` es siempre `false`.** */
+    usage(period?: string): Promise<{
+        period: string;
+        plan: {
+            id: string;
+            name: string;
+            included: number | null;
+        };
+        usage: {
+            billable: number;
+            rejected: number;
+            remaining: number;
+            overage: number;
+            overageCost: number | null;
+        };
+        emissionBlocked: false;
+        alert?: {
+            level: string;
+            message: string;
+        };
+        rules: {
+            id: string;
+            rule: string;
+            detail: string;
+        }[];
+    }>;
+}
+/**
+ * Verifica la firma de un webhook. **Esto corre en tu servidor.**
+ *
+ * La firma **caduca a los 5 minutos**, y eso es lo que impide que quien capture una
+ * petición válida te la reenvíe mañana. El HMAC va sobre `epoch.cuerpo`, así que la
+ * marca de tiempo no se puede cambiar sin romper la firma.
+ *
+ * @param body El cuerpo **crudo**, tal como llegó. Si lo parseas y lo vuelves a
+ *   serializar, la firma deja de cuadrar — es el fallo más común al integrarlo.
+ */
+export declare function verifyWebhook(args: {
+    body: string;
+    signature: string;
+    secret: string;
+    toleranceSeconds?: number;
+}): Promise<boolean>;

package/dist/index.js

@@ -0,0 +1,209 @@
+/**
+ * SDK de TypeScript para la API de KeySoft (proceso P15).
+ *
+ * **Sin dependencias.** Usa `fetch`, que está en Node 18+ y en cualquier navegador,
+ * porque un SDK de facturación que arrastra medio `node_modules` es un SDK que
+ * nadie quiere meter en su servidor de producción.
+ *
+ * Lo que hace por ti y no se ve:
+ *
+ *   · Manda `Idempotency-Key` **por defecto** al emitir. Es la protección que más
+ *     falta hace y la que más se olvida.
+ *   · Convierte los errores de la API en `KeySoftError`, con el código estable y
+ *     **qué hacer** — no en un `Error: Request failed with status code 422`.
+ *   · **Comprueba el hash** de cada fichero que descargas. No te fíes de nosotros.
+ */
+/**
+ * Un error de la API, con lo que hace falta para reaccionar.
+ *
+ * `code` es estable: puedes programar contra él. `action` dice qué hacer, y en la
+ * mayoría de los casos se le puede enseñar al usuario tal cual.
+ */
+export class KeySoftError extends Error {
+    status;
+    code;
+    action;
+    details;
+    constructor(args) {
+        super(args.message);
+        this.name = 'KeySoftError';
+        this.status = args.status;
+        this.code = args.code;
+        this.action = args.action;
+        this.details = args.details;
+    }
+    /** ¿Reintentar tiene sentido? Un 422 no se arregla insistiendo. */
+    get retryable() {
+        return this.status === 429 || this.status >= 500;
+    }
+}
+export class KeySoft {
+    #apiKey;
+    #baseUrl;
+    #timeoutMs;
+    constructor(options) {
+        const o = typeof options === 'string' ? { apiKey: options } : options;
+        this.#apiKey = o.apiKey;
+        this.#baseUrl = (o.baseUrl ?? 'https://api.keysoft.pe').replace(/\/+$/, '');
+        this.#timeoutMs = o.timeoutMs ?? 30_000;
+    }
+    /** El ambiente sale de la clave, no de una opción: `ks_live_` es producción. */
+    get environment() {
+        return this.#apiKey.startsWith('ks_live_') ? 'PRODUCTION' : 'DEMO';
+    }
+    async #request(method, path, body, headers = {}) {
+        let respuesta;
+        try {
+            respuesta = await fetch(this.#baseUrl + '/api/v1' + path, {
+                method,
+                headers: {
+                    authorization: 'Bearer ' + this.#apiKey,
+                    ...(body ? { 'content-type': 'application/json' } : {}),
+                    ...headers,
+                },
+                ...(body ? { body: JSON.stringify(body) } : {}),
+                signal: AbortSignal.timeout(this.#timeoutMs),
+            });
+        }
+        catch (cause) {
+            throw new KeySoftError({
+                status: 503,
+                code: 'network_error',
+                message: 'No se pudo contactar con KeySoft: ' +
+                    (cause instanceof Error ? cause.message : String(cause)),
+                action: 'Reintenta en unos segundos.',
+            });
+        }
+        const cuerpo = await respuesta.json().catch(() => null);
+        if (!respuesta.ok) {
+            const e = cuerpo?.error;
+            throw new KeySoftError({
+                status: respuesta.status,
+                code: e?.code ?? 'unknown_error',
+                message: e?.message ?? 'KeySoft devolvió ' + respuesta.status + '.',
+                action: e?.action,
+                details: e?.details,
+            });
+        }
+        return cuerpo;
+    }
+    // ─────────────────────────────────────────────── Comprobantes
+    /**
+     * Emite un comprobante.
+     *
+     * **Manda `Idempotency-Key` por defecto.** Si tu proceso reintenta por un
+     * timeout, sin ella emitirías dos facturas — y una factura de más es un problema
+     * fiscal, no un duplicado inocente. Pasa la tuya (el id de tu pedido es ideal) o
+     * deja que genere una.
+     */
+    async issue(companyId, document, options = {}) {
+        return this.#request('POST', '/companies/' + companyId + '/documents', document, {
+            'idempotency-key': options.idempotencyKey ?? crypto.randomUUID(),
+        });
+    }
+    /** Envía a SUNAT y devuelve el CDR. Una boleta va por resumen diario. */
+    async send(companyId, documentId) {
+        return this.#request('POST', '/companies/' + companyId + '/documents/' + documentId + '/send');
+    }
+    /**
+     * Descarga un fichero **y comprueba su hash**.
+     *
+     * El XML y el CDR vienen con su SHA-256 declarado; este método lo recalcula y
+     * lanza si no cuadra. **No te fíes de nosotros:** la comprobación es el producto.
+     */
+    async download(companyId, documentId, kind) {
+        const url = this.#baseUrl +
+            '/api/v1/companies/' +
+            companyId +
+            '/documents/' +
+            documentId +
+            '/files/' +
+            kind;
+        const respuesta = await fetch(url, {
+            headers: { authorization: 'Bearer ' + this.#apiKey },
+            signal: AbortSignal.timeout(this.#timeoutMs),
+        });
+        if (!respuesta.ok) {
+            throw new KeySoftError({
+                status: respuesta.status,
+                code: 'download_failed',
+                message: 'No se pudo descargar el ' + kind + ': ' + respuesta.status + '.',
+            });
+        }
+        const content = new Uint8Array(await respuesta.arrayBuffer());
+        const declarado = respuesta.headers.get('x-keysoft-sha256');
+        if (declarado) {
+            const digest = await crypto.subtle.digest('SHA-256', content);
+            const calculado = [...new Uint8Array(digest)]
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+            if (calculado !== declarado) {
+                throw new KeySoftError({
+                    status: 500,
+                    code: 'hash_mismatch',
+                    message: 'El ' + kind + ' descargado NO coincide con su hash declarado. No lo uses.',
+                    action: 'Vuelve a descargarlo. Si persiste, escríbenos: es un problema serio.',
+                });
+            }
+        }
+        return { content, sha256: declarado };
+    }
+    /** Entrega el comprobante al comprador por correo. */
+    async deliver(companyId, documentId, options = {}) {
+        return this.#request('POST', '/companies/' + companyId + '/documents/' + documentId + '/deliver', options);
+    }
+    // ─────────────────────────────────────────────── Boletas
+    /** Los resúmenes y **cuántos días quedan** para informar cada día de boletas. */
+    async summaries(companyId) {
+        return this.#request('GET', '/companies/' + companyId + '/summaries');
+    }
+    async createSummary(companyId, referenceDate) {
+        return this.#request('POST', '/companies/' + companyId + '/summaries', { referenceDate });
+    }
+    /** Devuelve un **ticket**, no un veredicto. Las boletas siguen sin informar. */
+    async sendSummary(companyId, summaryId) {
+        return this.#request('POST', '/companies/' + companyId + '/summaries/' + summaryId + '/send');
+    }
+    /** Consulta el ticket y propaga el resultado a cada boleta. */
+    async summaryStatus(companyId, summaryId) {
+        return this.#request('POST', '/companies/' + companyId + '/summaries/' + summaryId + '/status');
+    }
+    // ─────────────────────────────────────────────── Referencia
+    /** Tu consumo del mes. **`emissionBlocked` es siempre `false`.** */
+    async usage(period) {
+        return this.#request('GET', '/usage' + (period ? '?period=' + period : ''));
+    }
+}
+/**
+ * Verifica la firma de un webhook. **Esto corre en tu servidor.**
+ *
+ * La firma **caduca a los 5 minutos**, y eso es lo que impide que quien capture una
+ * petición válida te la reenvíe mañana. El HMAC va sobre `epoch.cuerpo`, así que la
+ * marca de tiempo no se puede cambiar sin romper la firma.
+ *
+ * @param body El cuerpo **crudo**, tal como llegó. Si lo parseas y lo vuelves a
+ *   serializar, la firma deja de cuadrar — es el fallo más común al integrarlo.
+ */
+export async function verifyWebhook(args) {
+    const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(args.signature.trim());
+    if (!m)
+        return false;
+    const ahora = Math.floor(Date.now() / 1000);
+    if (Math.abs(ahora - Number(m[1])) > (args.toleranceSeconds ?? 300))
+        return false;
+    const clave = await crypto.subtle.importKey('raw', new TextEncoder().encode(args.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const firma = await crypto.subtle.sign('HMAC', clave, new TextEncoder().encode(m[1] + '.' + args.body));
+    const esperado = [...new Uint8Array(firma)]
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    // Comparación en tiempo constante: comparar con === filtra cuántos caracteres
+    // coinciden, y eso basta para adivinar una firma a base de intentos.
+    const recibido = m[2];
+    if (esperado.length !== recibido.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < esperado.length; i++) {
+        diff |= esperado.charCodeAt(i) ^ recibido.charCodeAt(i);
+    }
+    return diff === 0;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@keysoftinc/sdk",
+  "version": "0.1.0",
+  "description": "SDK de TypeScript para la API de KeySoft — facturación electrónica SUNAT.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sunat",
+    "peru",
+    "factura-electronica",
+    "facturacion",
+    "cpe"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {},
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}