keycae-ts 1.0.0

package/README.md

@@ -0,0 +1,96 @@
+# keycae-ts 🚀
+
+Cliente SDK oficial en **TypeScript** y **JavaScript** para interactuar con la plataforma de **KeyCAE.ar** y emitir facturación electrónica oficial homologada ante **ARCA (ex AFIP)** de forma simple y resiliente.
+
+## Instalación
+
+Instala el SDK en tu proyecto Node.js/TypeScript:
+
+```bash
+npm install keycae-ts
+# O usando yarn / pnpm
+yarn add keycae-ts
+pnpm add keycae-ts
+```
+
+## Inicio Rápido (Modelo A: Delegación Directa ⭐)
+
+Esta es la forma recomendada por defecto. En minutos podés facturar sin lidiar con llaves privadas o subir archivos de certificados.
+
+```typescript
+import { KeyCaeClient } from 'keycae-ts';
+
+// 1. Inicializar el cliente con tu API Key
+const client = new KeyCaeClient('sk_test_tu_api_key_aqui');
+
+async function main() {
+  try {
+    // 2. Registrar la delegación (previamente debés adherir el servicio en el portal de ARCA al CUIT representante 20254459306)
+    console.log('Iniciando delegación directa...');
+    const delegation = await client.createDelegation({
+      cuit: '20254459306',
+      organization: 'Digital Media S.A.'
+    });
+    
+    console.log(`Estado inicial de delegación: ${delegation.status}`);
+    
+    // 3. Emitir una factura electrónica homologada (con CAE y PDF)
+    console.log('Emitiendo factura fiscal...');
+    const invoice = await client.emitInvoice({
+      cuit_emisor: '20254459306',
+      punto_de_venta: 1,
+      tipo_comprobante: 'C',
+      receptor: {
+        tipo_doc: 'DNI',
+        nro_doc: '35987654'
+      },
+      conceptos: [
+        {
+          descripcion: 'Servicios de Consultoría de Software',
+          precio: 150000.00
+        }
+      ]
+    }, 'idempotency_key_factura_42'); // Idempotency key para prevenir duplicaciones de red
+    
+    console.log('¡Factura autorizada exitosamente!');
+    console.log(`Comprobante: Nro. ${invoice.numero_factura}`);
+    console.log(`CAE Otorgado: ${invoice.cae}`);
+    console.log(`Vencimiento CAE: ${invoice.cae_vencimiento}`);
+    console.log(`PDF de Impresión: ${invoice.url_pdf}`);
+    console.log(`Código QR Fiscal: ${invoice.url_qr}`);
+    
+  } catch (error) {
+    console.error('Error durante la operación:', error);
+  }
+}
+
+main();
+```
+
+## Notificaciones en Tiempo Real (Telegram Alerts)
+
+Configurá tu bot de Telegram a través de la API para recibir alertas móviles al instante de cada comprobante emitido:
+
+```typescript
+import { KeyCaeClient } from 'keycae-ts';
+
+const client = new KeyCaeClient('sk_test_tu_api_key_aqui');
+
+async function setupAlerts() {
+  // Guardar configuración del Bot
+  await client.saveTelegramSettings({
+    telegram_bot_token: '123456789:ABCdefGhIjKlMnOpQrStUvWxYz_TOKEN',
+    telegram_chat_id: '987654321'
+  });
+  
+  // Consultar configuración actual (retorna enmascarada)
+  const settings = await client.getTelegramSettings();
+  console.log('Ajustes de alertas activos:', settings);
+}
+
+setupAlerts();
+```
+
+## Licencia
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+export interface TaxpayerResponse {
+    cuit: string;
+    nombre: string;
+    tipo_persona: string;
+    categoria_monotributo?: string;
+    es_iva_inscripto: boolean;
+    estado: string;
+}
+export interface InvoiceReceptor {
+    tipo_doc: 'DNI' | 'CUIT' | 'CUIL' | 'PASAPORTE';
+    nro_doc: string;
+}
+export interface InvoiceItem {
+    descripcion: string;
+    precio: number;
+}
+export interface InvoiceInput {
+    cuit_emisor: string;
+    punto_de_venta: number;
+    tipo_comprobante: 'A' | 'B' | 'C' | 'M';
+    receptor: InvoiceReceptor;
+    conceptos: InvoiceItem[];
+    brand_logo_url?: string;
+    brand_color?: string;
+}
+export interface InvoiceResponse {
+    id: string;
+    cuit_emisor: string;
+    punto_de_venta: number;
+    tipo_comprobante: string;
+    numero_factura: number;
+    cae: string;
+    cae_vencimiento: string;
+    url_pdf: string;
+    url_qr: string;
+    total: number;
+}
+export interface BillingStatusResponse {
+    cuit: string;
+    plan: string;
+    invoicesEmitted: number;
+    monthlyLimit: number;
+    status: string;
+    billingPeriodStart: string;
+    percentageConsumed: number;
+    overageCost: number;
+    currency: string;
+}
+export interface TelegramSettingsInput {
+    telegram_bot_token: string;
+    telegram_chat_id: string;
+}
+export interface TelegramSettingsResponse {
+    telegram_bot_token: string;
+    telegram_chat_id: string;
+    has_credentials: boolean;
+}
+export interface DelegationInput {
+    cuit: string;
+    organization: string;
+}
+export interface DelegationResponse {
+    id: string;
+    status: 'pending' | 'accepted' | 'rejected';
+    cuit: string;
+    organization: string;
+    representativeCuit: string;
+    representativeOrg: string;
+    createdAt: string;
+    acceptedAt?: string;
+}
+export interface KmsCredentialInput {
+    cuit: string;
+    organization: string;
+    common_name?: string;
+}
+export interface KmsCredentialResponse {
+    id: string;
+    cuit: string;
+    organization: string;
+    common_name: string;
+    status: string;
+    csr_pem?: string;
+    created_at: string;
+}
+export interface KmsImportInput {
+    cuit: string;
+    organization: string;
+    certificate: string;
+    private_key: string;
+}
+export declare class KeyCaeClient {
+    private apiKey;
+    private baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    /**
+     * Consultar Contribuyente en Padrón ARCA
+     */
+    getTaxpayer(cuit: string): Promise<TaxpayerResponse>;
+    /**
+     * Registrar / Iniciar Direct Delegation
+     */
+    createDelegation(data: DelegationInput): Promise<DelegationResponse>;
+    /**
+     * Consultar Estado de Delegación Directa
+     */
+    checkDelegationStatus(): Promise<DelegationResponse>;
+    /**
+     * Crear Bóveda de Claves KMS & Generar CSR
+     */
+    createCredential(data: KmsCredentialInput): Promise<KmsCredentialResponse>;
+    /**
+     * Importar Credenciales de Firma Existentes (.key y .crt)
+     */
+    importCredential(data: KmsImportInput): Promise<KmsCredentialResponse>;
+    /**
+     * Activar Bóveda KMS con Certificado ARCA (.crt)
+     */
+    activateCredential(id: string, certificatePem: string): Promise<any>;
+    /**
+     * Eliminar Bóveda de Claves KMS de forma física y segura
+     */
+    deleteCredential(id: string): Promise<any>;
+    /**
+     * Emitir Factura Electrónica Homologada (CAE)
+     */
+    emitInvoice(data: InvoiceInput, idempotencyKey?: string): Promise<InvoiceResponse>;
+    /**
+     * Descargar PDF de Factura (Retorna el Stream / ArrayBuffer)
+     */
+    getInvoicePdfBuffer(id: string): Promise<Buffer>;
+    /**
+     * Obtener Consumos y Estado del Plan (Billing)
+     */
+    getBillingStatus(): Promise<BillingStatusResponse>;
+    /**
+     * Obtener Ajustes de Telegram por Tenant
+     */
+    getTelegramSettings(): Promise<TelegramSettingsResponse>;
+    /**
+     * Guardar / Actualizar Ajustes de Telegram
+     */
+    saveTelegramSettings(data: TelegramSettingsInput): Promise<any>;
+}

package/dist/index.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyCaeClient = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+class KeyCaeClient {
+    constructor(apiKey, baseUrl = 'https://api.keycae.ar') {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+    }
+    async request(method, path, body, idempotencyKey) {
+        const headers = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json'
+        };
+        if (idempotencyKey) {
+            headers['Idempotency-Key'] = idempotencyKey;
+        }
+        const response = await (0, node_fetch_1.default)(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined
+        });
+        if (!response.ok) {
+            let errorDetails = '';
+            try {
+                errorDetails = await response.text();
+            }
+            catch (e) { }
+            throw new Error(`KeyCAE API Error (${response.status}): ${errorDetails || response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Consultar Contribuyente en Padrón ARCA
+     */
+    async getTaxpayer(cuit) {
+        return this.request('GET', `/v1/taxpayers/${cuit}`);
+    }
+    /**
+     * Registrar / Iniciar Direct Delegation
+     */
+    async createDelegation(data) {
+        return this.request('POST', '/v1/delegations', data);
+    }
+    /**
+     * Consultar Estado de Delegación Directa
+     */
+    async checkDelegationStatus() {
+        return this.request('GET', '/v1/delegations/status');
+    }
+    /**
+     * Crear Bóveda de Claves KMS & Generar CSR
+     */
+    async createCredential(data) {
+        return this.request('POST', '/v1/credentials', data);
+    }
+    /**
+     * Importar Credenciales de Firma Existentes (.key y .crt)
+     */
+    async importCredential(data) {
+        return this.request('POST', '/v1/credentials/import', data);
+    }
+    /**
+     * Activar Bóveda KMS con Certificado ARCA (.crt)
+     */
+    async activateCredential(id, certificatePem) {
+        return this.request('POST', `/v1/credentials/${id}/certificate`, { certificate: certificatePem });
+    }
+    /**
+     * Eliminar Bóveda de Claves KMS de forma física y segura
+     */
+    async deleteCredential(id) {
+        return this.request('DELETE', `/v1/credentials/${id}`);
+    }
+    /**
+     * Emitir Factura Electrónica Homologada (CAE)
+     */
+    async emitInvoice(data, idempotencyKey) {
+        return this.request('POST', '/v1/invoices', data, idempotencyKey);
+    }
+    /**
+     * Descargar PDF de Factura (Retorna el Stream / ArrayBuffer)
+     */
+    async getInvoicePdfBuffer(id) {
+        const response = await (0, node_fetch_1.default)(`${this.baseUrl}/v1/invoices/${id}/pdf`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`
+            }
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch PDF (${response.status})`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    }
+    /**
+     * Obtener Consumos y Estado del Plan (Billing)
+     */
+    async getBillingStatus() {
+        return this.request('GET', '/v1/billing/status');
+    }
+    /**
+     * Obtener Ajustes de Telegram por Tenant
+     */
+    async getTelegramSettings() {
+        return this.request('GET', '/v1/settings/telegram');
+    }
+    /**
+     * Guardar / Actualizar Ajustes de Telegram
+     */
+    async saveTelegramSettings(data) {
+        return this.request('POST', '/v1/settings/telegram', data);
+    }
+}
+exports.KeyCaeClient = KeyCaeClient;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "keycae-ts",
+  "version": "1.0.0",
+  "description": "Official TypeScript & JavaScript SDK client for KeyCAE.ar impositive compliance API (ARCA)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "arca",
+    "afip",
+    "factura-electronica",
+    "compliance",
+    "sdk",
+    "client",
+    "keycae",
+    "argentina"
+  ],
+  "author": "KeyCAE Community",
+  "license": "MIT",
+  "dependencies": {
+    "node-fetch": "^2.6.9"
+  },
+  "devDependencies": {
+    "@types/node": "^18.15.11",
+    "@types/node-fetch": "^2.6.3",
+    "typescript": "^5.0.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+import fetch from 'node-fetch';
+
+export interface TaxpayerResponse {
+  cuit: string;
+  nombre: string;
+  tipo_persona: string;
+  categoria_monotributo?: string;
+  es_iva_inscripto: boolean;
+  estado: string;
+}
+
+export interface InvoiceReceptor {
+  tipo_doc: 'DNI' | 'CUIT' | 'CUIL' | 'PASAPORTE';
+  nro_doc: string;
+}
+
+export interface InvoiceItem {
+  descripcion: string;
+  precio: number;
+}
+
+export interface InvoiceInput {
+  cuit_emisor: string;
+  punto_de_venta: number;
+  tipo_comprobante: 'A' | 'B' | 'C' | 'M';
+  receptor: InvoiceReceptor;
+  conceptos: InvoiceItem[];
+  brand_logo_url?: string;
+  brand_color?: string;
+}
+
+export interface InvoiceResponse {
+  id: string;
+  cuit_emisor: string;
+  punto_de_venta: number;
+  tipo_comprobante: string;
+  numero_factura: number;
+  cae: string;
+  cae_vencimiento: string;
+  url_pdf: string;
+  url_qr: string;
+  total: number;
+}
+
+export interface BillingStatusResponse {
+  cuit: string;
+  plan: string;
+  invoicesEmitted: number;
+  monthlyLimit: number;
+  status: string;
+  billingPeriodStart: string;
+  percentageConsumed: number;
+  overageCost: number;
+  currency: string;
+}
+
+export interface TelegramSettingsInput {
+  telegram_bot_token: string;
+  telegram_chat_id: string;
+}
+
+export interface TelegramSettingsResponse {
+  telegram_bot_token: string;
+  telegram_chat_id: string;
+  has_credentials: boolean;
+}
+
+export interface DelegationInput {
+  cuit: string;
+  organization: string;
+}
+
+export interface DelegationResponse {
+  id: string;
+  status: 'pending' | 'accepted' | 'rejected';
+  cuit: string;
+  organization: string;
+  representativeCuit: string;
+  representativeOrg: string;
+  createdAt: string;
+  acceptedAt?: string;
+}
+
+export interface KmsCredentialInput {
+  cuit: string;
+  organization: string;
+  common_name?: string;
+}
+
+export interface KmsCredentialResponse {
+  id: string;
+  cuit: string;
+  organization: string;
+  common_name: string;
+  status: string;
+  csr_pem?: string;
+  created_at: string;
+}
+
+export interface KmsImportInput {
+  cuit: string;
+  organization: string;
+  certificate: string;
+  private_key: string;
+}
+
+export class KeyCaeClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(apiKey: string, baseUrl: string = 'https://api.keycae.ar') {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: any,
+    idempotencyKey?: string
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      'Authorization': `Bearer ${this.apiKey}`,
+      'Content-Type': 'application/json'
+    };
+
+    if (idempotencyKey) {
+      headers['Idempotency-Key'] = idempotencyKey;
+    }
+
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined
+    });
+
+    if (!response.ok) {
+      let errorDetails = '';
+      try {
+        errorDetails = await response.text();
+      } catch (e) {}
+      throw new Error(`KeyCAE API Error (${response.status}): ${errorDetails || response.statusText}`);
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Consultar Contribuyente en Padrón ARCA
+   */
+  async getTaxpayer(cuit: string): Promise<TaxpayerResponse> {
+    return this.request<TaxpayerResponse>('GET', `/v1/taxpayers/${cuit}`);
+  }
+
+  /**
+   * Registrar / Iniciar Direct Delegation
+   */
+  async createDelegation(data: DelegationInput): Promise<DelegationResponse> {
+    return this.request<DelegationResponse>('POST', '/v1/delegations', data);
+  }
+
+  /**
+   * Consultar Estado de Delegación Directa
+   */
+  async checkDelegationStatus(): Promise<DelegationResponse> {
+    return this.request<DelegationResponse>('GET', '/v1/delegations/status');
+  }
+
+  /**
+   * Crear Bóveda de Claves KMS & Generar CSR
+   */
+  async createCredential(data: KmsCredentialInput): Promise<KmsCredentialResponse> {
+    return this.request<KmsCredentialResponse>('POST', '/v1/credentials', data);
+  }
+
+  /**
+   * Importar Credenciales de Firma Existentes (.key y .crt)
+   */
+  async importCredential(data: KmsImportInput): Promise<KmsCredentialResponse> {
+    return this.request<KmsCredentialResponse>('POST', '/v1/credentials/import', data);
+  }
+
+  /**
+   * Activar Bóveda KMS con Certificado ARCA (.crt)
+   */
+  async activateCredential(id: string, certificatePem: string): Promise<any> {
+    return this.request<any>('POST', `/v1/credentials/${id}/certificate`, { certificate: certificatePem });
+  }
+
+  /**
+   * Eliminar Bóveda de Claves KMS de forma física y segura
+   */
+  async deleteCredential(id: string): Promise<any> {
+    return this.request<any>('DELETE', `/v1/credentials/${id}`);
+  }
+
+  /**
+   * Emitir Factura Electrónica Homologada (CAE)
+   */
+  async emitInvoice(data: InvoiceInput, idempotencyKey?: string): Promise<InvoiceResponse> {
+    return this.request<InvoiceResponse>('POST', '/v1/invoices', data, idempotencyKey);
+  }
+
+  /**
+   * Descargar PDF de Factura (Retorna el Stream / ArrayBuffer)
+   */
+  async getInvoicePdfBuffer(id: string): Promise<Buffer> {
+    const response = await fetch(`${this.baseUrl}/v1/invoices/${id}/pdf`, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`
+      }
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch PDF (${response.status})`);
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    return Buffer.from(arrayBuffer);
+  }
+
+  /**
+   * Obtener Consumos y Estado del Plan (Billing)
+   */
+  async getBillingStatus(): Promise<BillingStatusResponse> {
+    return this.request<BillingStatusResponse>('GET', '/v1/billing/status');
+  }
+
+  /**
+   * Obtener Ajustes de Telegram por Tenant
+   */
+  async getTelegramSettings(): Promise<TelegramSettingsResponse> {
+    return this.request<TelegramSettingsResponse>('GET', '/v1/settings/telegram');
+  }
+
+  /**
+   * Guardar / Actualizar Ajustes de Telegram
+   */
+  async saveTelegramSettings(data: TelegramSettingsInput): Promise<any> {
+    return this.request<any>('POST', '/v1/settings/telegram', data);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["es6", "dom"],
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}