sae-ts-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EskenderDev
+
+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,80 @@
+# sae-ts-sdk
+
+[![npm version](https://img.shields.io/npm/v/sae-ts-sdk)](https://www.npmjs.com/package/sae-ts-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**TypeScript/JavaScript SDK oficial para la API SAE** — Sistema de Administración de Empresa con Facturación Electrónica de Hacienda Costa Rica.
+
+## Instalación
+
+```bash
+npm install sae-ts-sdk
+```
+
+## Uso Básico
+
+```typescript
+import { SaeClient } from 'sae-ts-sdk';
+
+const client = new SaeClient('https://api.tu-sae.com');
+
+// Login
+const result = await client.login('usuario@empresa.com', 'password');
+
+// Emitir factura
+const factura = await client.emitir({
+  Emisor: { /* ... */ },
+  Receptor: { /* ... */ },
+  DetalleServicio: { /* ... */ }
+});
+```
+
+## Módulos Disponibles
+
+| Módulo | Descripción |
+|--------|-------------|
+| **Auth** | Login, registro, reset de contraseña |
+| **Hacienda** | Emitir, consultar, endosar documentos |
+| **Tenant Users** | Invitar usuarios, gestionar roles |
+| **Branches & Terminals** | Sucursales, terminales, secuencias |
+| **License Addons** | Compra/cancelación de paquetes |
+| **Reports** | IVA, libro de ventas, compras, CABYS + PDF/Excel |
+| **Developer API** | Aplicaciones registradas, módulos |
+| **Admin** | Gestión global de plataforma (solo SuperAdmin) |
+| **Webhooks** | Suscripción a eventos de Hacienda |
+
+## SignalR (Tiempo Real)
+
+```typescript
+import { SaeClient } from 'sae-ts-sdk';
+
+const client = new SaeClient('https://api.tu-sae.com');
+await client.login('usuario@empresa.com', 'password');
+
+// Conectar SignalR
+const hubUrl = 'https://api.tu-sae.com/hubs/hacienda';
+```
+
+> El SDK usa Axios para HTTP. Para SignalR en tiempo real, usa la librería `@microsoft/signalr` directamente con el endpoint `/hubs/hacienda` autenticando con el JWT obtenido en `login()`.
+
+## Variables de Entorno
+
+Para desarrollo local:
+
+```env
+PUBLIC_API_URL=https://localhost:55431
+```
+
+## Reportes
+
+```typescript
+// Reporte IVA D-104 de enero 2025
+const reporte = await client.getReport<ReporteIvaDto>('iva', 1, 2025);
+
+// Descargar como PDF
+const pdf = await client.downloadReport('iva', 'pdf', 1, 2025);
+```
+
+## Licencia
+
+MIT © [EskenderDev](https://github.com/EskenderDev)

package/dist/client/SaeClient.d.ts

@@ -0,0 +1,227 @@
+import { AxiosRequestConfig } from 'axios';
+import { GenerarDocumentoRequest, HaciendaConfigRequest, UpdateTenantRequest, MensajeEndosoRequest, CreateSettlementRequest, PurchaseAddonRequest, ReportAddonPurchaseRequest, ApproveAddonRequest, RejectAddonRequest, EnviarDocumentoSimplificadoRequest, RegisterRequest, ResetPasswordRequest, PartnerRegisterRequest, IssueLicenseRequest, LeadRegisterRequest, TenantRoleRequest, CreateOrderRequest, ReportOrderPaymentRequest, InviteUserRequest, UpdateUserRoleRequest, AcceptInviteRequest, ConfirmEmailRequest, CreateBranchRequest, UpdateBranchRequest, CreateTerminalRequest, UpdateTerminalRequest, UpdateSequenceRequest, CreateLicensePackageRequest, UpdateLicensePackageRequest, RegisterAppRequest, AdminRegisterRequest, AdminUpdateRequest, SettlementPayRequest, ValidateLicenseRequest, ActivateLicenseRequest, CreatePlatformModuleRequest, UpdatePlatformModuleRequest, CreateDeveloperModuleRequest, UpdateDeveloperModuleRequest } from '../models/requests';
+import { LoginResult, PasswordResetResponse, DocumentoResult, HaciendaEnvioResult, HaciendaConfigResponse, EnvironmentInfoResponse, TenantResponse, ProvinciaResponse, CantonResponse, DistritoResponse, EconomicActivityResponse, PagedResult, DocumentoJsonDto, CommissionSettlementDto, SalesCommissionDto, LicensePackageResponse, LicenseAddonResponse, BillingSummaryResponse, DocumentResumen, PartnerProfile, PartnerClient, PublicPlan, PermissionDto, TenantRoleDto, LicenseResponse, TenantLicense, AdminMeResponse, ImpersonateResponse, PendingApprovalDto, DashboardStatsResponse, SubscriptionOrderDto, BranchResponse, TerminalResponse, DocumentSequenceResponse, NextConsecutiveResponse, DeveloperClientResponse, RegisteredApplicationResponse, SystemSettingResponse, UnifiedPaymentResponse, AdminAuthUserResponse, GlobalStatsResponse, SaeIdentifierResponse, PlatformModuleResponse } from '../models/responses';
+import { SystemLogService } from '../services/systemLogService';
+export interface ApiClient {
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+}
+export declare class SaeClient implements ApiClient {
+    private http;
+    private baseUrl;
+    private token?;
+    private apiKey?;
+    private tenantId?;
+    private terminalKey?;
+    logs: SystemLogService;
+    constructor(baseUrl?: string, token?: string, apiKey?: string);
+    private updateHeaders;
+    setToken(token: string): void;
+    setApiKey(apiKey: string): void;
+    setTenantId(tenantId: string | undefined): void;
+    setTerminalKey(terminalKey: string | undefined): void;
+    get<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    post<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    put<T>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    delete<T>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    login(email: string, password?: string): Promise<LoginResult>;
+    adminLogin(email: string, password?: string): Promise<LoginResult>;
+    forgotPassword(email: string): Promise<PasswordResetResponse>;
+    resetPassword(token: string, newPassword: string): Promise<PasswordResetResponse>;
+    register(request: RegisterRequest): Promise<void>;
+    resendVerification(email: string): Promise<void>;
+    confirmEmail(request: ConfirmEmailRequest): Promise<void>;
+    adminForgotPassword(email: string): Promise<void>;
+    adminResetPassword(request: ResetPasswordRequest): Promise<void>;
+    adminMe(): Promise<AdminMeResponse>;
+    adminImpersonate(tenantId: string): Promise<ImpersonateResponse>;
+    adminGetPendingApprovals(): Promise<PendingApprovalDto[]>;
+    adminApproveApproval(id: string, type: number, overrideTenantId?: string): Promise<void>;
+    adminRejectApproval(id: string, type: number, reason: string): Promise<void>;
+    adminGetRedisQueues(): Promise<any>;
+    adminGetBillingSettings(): Promise<any>;
+    adminUpdateSettingsBatch(settings: Record<string, string>): Promise<void>;
+    adminGetPlans(): Promise<any[]>;
+    adminGetPlan(id: string): Promise<any>;
+    adminCreatePlan(data: any): Promise<void>;
+    adminUpdatePlan(id: string, data: any): Promise<void>;
+    adminDeletePlan(id: string): Promise<void>;
+    getCurrentTenant(): Promise<TenantResponse>;
+    updateCurrentTenant(request: UpdateTenantRequest): Promise<TenantResponse>;
+    regenerateApiKey(): Promise<{
+        apiKey: string;
+    }>;
+    getMyTenants(): Promise<TenantResponse[]>;
+    registerTenant(name: string, taxId: string): Promise<TenantResponse>;
+    getTenantBillingSettings(tenantId: string): Promise<Record<string, string>>;
+    uploadTenantLogo(formData: FormData): Promise<{
+        logoUrl: string;
+    }>;
+    deleteTenantLogo(): Promise<{
+        message: string;
+    }>;
+    getTenantUsers(): Promise<any[]>;
+    inviteTenantUser(request: InviteUserRequest): Promise<any>;
+    acceptInvitation(request: AcceptInviteRequest): Promise<any>;
+    removeTenantUser(id: string): Promise<void>;
+    updateTenantUserRole(id: string, request: UpdateUserRoleRequest): Promise<void>;
+    getRoles(): Promise<TenantRoleDto[]>;
+    getPermissions(): Promise<PermissionDto[]>;
+    createRole(request: TenantRoleRequest): Promise<TenantRoleDto>;
+    updateRole(id: string, request: TenantRoleRequest): Promise<TenantRoleDto>;
+    deleteRole(id: string): Promise<void>;
+    getProvincias(): Promise<ProvinciaResponse[]>;
+    getCantones(provinceCode: string): Promise<CantonResponse[]>;
+    getDistritos(provinceCode: string, cantonCode: string): Promise<DistritoResponse[]>;
+    getCurrencies(search?: string): Promise<any[]>;
+    getEconomicActivities(search?: string): Promise<EconomicActivityResponse[]>;
+    generarDocumento(documento: GenerarDocumentoRequest): Promise<DocumentoResult>;
+    enviarDocumento(documento: GenerarDocumentoRequest): Promise<HaciendaEnvioResult>;
+    emitir(request: EnviarDocumentoSimplificadoRequest): Promise<HaciendaEnvioResult>;
+    consultarEstado(clave: string): Promise<HaciendaEnvioResult>;
+    endosarDocumento(request: MensajeEndosoRequest): Promise<any>;
+    aceptarDocumento(request: any): Promise<any>;
+    getUsedCurrencies(): Promise<any[]>;
+    getDocumentById(id: string): Promise<DocumentoJsonDto>;
+    getDocumentXml(id: string): Promise<ArrayBuffer>;
+    getDocumentResponseXml(id: string): Promise<ArrayBuffer>;
+    getDocumentPdf(id: string): Promise<ArrayBuffer>;
+    getDocumentPdfByClave(clave: string): Promise<ArrayBuffer>;
+    buscarDocumentos(params: any): Promise<PagedResult<DocumentoJsonDto>>;
+    exportDocuments(format: 'csv' | 'excel' | 'pdf', filters: any): Promise<ArrayBuffer>;
+    getDocumentSummary(fechaDesde?: string, fechaHasta?: string): Promise<DocumentResumen>;
+    retryDocument(clave: string): Promise<void>;
+    regenerateDocument(clave: string, newConsecutive?: number): Promise<any>;
+    getNextConsecutive(sucursal: number, terminal: number, tipoDocumento: string): Promise<number>;
+    resendDocumentEmail(id: string): Promise<void>;
+    forceDocumentRejection(id: string): Promise<void>;
+    getDocumentSafetyScore(clave: string): Promise<any>;
+    getReport<T>(type: string, mes: number, anio: number): Promise<T>;
+    downloadReport(type: string, format: string, mes: number, anio: number): Promise<ArrayBuffer>;
+    getHaciendaConfig(): Promise<HaciendaConfigResponse>;
+    saveHaciendaConfig(config: HaciendaConfigRequest): Promise<HaciendaConfigResponse>;
+    getHaciendaEnvironments(): Promise<EnvironmentInfoResponse[]>;
+    getHaciendaConfigByEnvironment(environment: number | string): Promise<HaciendaConfigResponse>;
+    switchHaciendaEnvironment(environment: number | string): Promise<EnvironmentInfoResponse>;
+    getBranches(): Promise<BranchResponse[]>;
+    getBranch(id: string): Promise<BranchResponse>;
+    createBranch(request: CreateBranchRequest): Promise<BranchResponse>;
+    updateBranch(id: string, request: UpdateBranchRequest): Promise<void>;
+    deleteBranch(id: string): Promise<void>;
+    getTerminals(branchId: string): Promise<TerminalResponse[]>;
+    getTerminal(id: string): Promise<TerminalResponse>;
+    createTerminal(branchId: string, request: CreateTerminalRequest): Promise<TerminalResponse>;
+    updateTerminal(id: string, request: UpdateTerminalRequest): Promise<void>;
+    deleteTerminal(id: string): Promise<void>;
+    getTerminalSequences(terminalId: string): Promise<DocumentSequenceResponse[]>;
+    updateTerminalSequence(terminalId: string, docType: string, request: UpdateSequenceRequest): Promise<void>;
+    getNextConsecutiveManual(sucursal: number, terminal: number, tipoDocumento: string): Promise<number>;
+    getNextConsecutiveByTerminal(terminalId: string, docType: string): Promise<NextConsecutiveResponse>;
+    generateTerminalLicense(terminalId: string): Promise<TerminalResponse>;
+    getLicensePackages(systemOnly?: boolean, tenantId?: string): Promise<LicensePackageResponse[]>;
+    getLicensePackage(id: string): Promise<LicensePackageResponse>;
+    createLicensePackage(request: CreateLicensePackageRequest): Promise<LicensePackageResponse>;
+    updateLicensePackage(id: string, request: UpdateLicensePackageRequest): Promise<void>;
+    deleteLicensePackage(id: string): Promise<void>;
+    /** Updates the active modules for a specific license. Returns { activeModules, allowedModules }. */
+    updateLicenseModules(id: string, moduleCodes: string[]): Promise<{
+        activeModules: string[];
+        allowedModules: string[];
+    }>;
+    /** Gets the allowed and active modules for a specific license without modifying anything. */
+    getLicenseModules(id: string): Promise<{
+        activeModules: string[];
+        allowedModules: string[];
+    }>;
+    getDeveloperClients(): Promise<DeveloperClientResponse[]>;
+    getDeveloperApplications(): Promise<RegisteredApplicationResponse[]>;
+    registerDeveloperApplication(request: RegisterAppRequest): Promise<RegisteredApplicationResponse>;
+    deactivateDeveloperApplication(id: string): Promise<void>;
+    getSaeIdentifiers(): Promise<SaeIdentifierResponse[]>;
+    getDeveloperModules(): Promise<PlatformModuleResponse[]>;
+    createDeveloperModule(request: CreateDeveloperModuleRequest): Promise<PlatformModuleResponse>;
+    validateModuleCode(code: string): Promise<boolean>;
+    updateDeveloperModule(id: string, request: UpdateDeveloperModuleRequest): Promise<PlatformModuleResponse>;
+    deleteDeveloperModule(id: string): Promise<void>;
+    validateLicense(request: ValidateLicenseRequest): Promise<any>;
+    activateLicense(request: ActivateLicenseRequest): Promise<any>;
+    adminUpdateLicenseModules(licenseId: string, modules: string[]): Promise<void>;
+    adminGetUsers(): Promise<any[]>;
+    adminUpgradeSubscription(tenantId: string, tier: number): Promise<void>;
+    adminUpdateTenant(id: string, request: any): Promise<void>;
+    adminGetTenantConfig(id: string): Promise<any>;
+    adminGetGlobalConfig(): Promise<any>;
+    getUnifiedPaymentHistory(): Promise<UnifiedPaymentResponse[]>;
+    approveSubscriptionRequest(id: string): Promise<void>;
+    rejectSubscriptionRequest(id: string, reason: string): Promise<void>;
+    getSystemSettings(): Promise<SystemSettingResponse[]>;
+    updateSystemSetting(key: string, value: string): Promise<void>;
+    updateSystemSettingsBatch(settings: Record<string, string>): Promise<void>;
+    retryAllHaciendaDocuments(): Promise<void>;
+    getAdminUsers(): Promise<AdminAuthUserResponse[]>;
+    registerAdminUser(request: AdminRegisterRequest): Promise<AdminAuthUserResponse>;
+    updateAdminUser(id: string, request: AdminUpdateRequest): Promise<void>;
+    deleteAdminUser(id: string): Promise<void>;
+    getGlobalStats(): Promise<GlobalStatsResponse>;
+    getAdminSettlements(): Promise<CommissionSettlementDto[]>;
+    paySettlement(settlementId: string, request: SettlementPayRequest): Promise<void>;
+    getPendingApprovals(): Promise<PendingApprovalDto[]>;
+    approveApproval(id: string, type: number, overrideTenantId?: string): Promise<void>;
+    rejectApproval(id: string, type: number, reason: string): Promise<void>;
+    getPendingInvoices(): Promise<SubscriptionOrderDto[]>;
+    retryInvoice(id: string): Promise<any>;
+    adminGetPlatformModules(): Promise<PlatformModuleResponse[]>;
+    adminGetPlatformModule(id: string): Promise<PlatformModuleResponse>;
+    adminCreatePlatformModule(request: CreatePlatformModuleRequest): Promise<PlatformModuleResponse>;
+    adminUpdatePlatformModule(id: string, request: UpdatePlatformModuleRequest): Promise<PlatformModuleResponse>;
+    adminDeletePlatformModule(id: string): Promise<void>;
+    getPartnerProfile(): Promise<PartnerProfile | null>;
+    registerPartner(request: PartnerRegisterRequest): Promise<PartnerProfile>;
+    getPartnerCommissions(): Promise<SalesCommissionDto[]>;
+    getPartnerClients(): Promise<PartnerClient[]>;
+    getSubscriptionPlans(): Promise<PublicPlan[]>;
+    getSubscriptionPlanById(id: string): Promise<PublicPlan>;
+    getDashboardStats(): Promise<DashboardStatsResponse>;
+    getSubscriptionHistory(): Promise<SubscriptionOrderDto[]>;
+    createSubscriptionOrder(request: CreateOrderRequest): Promise<SubscriptionOrderDto>;
+    reportSubscriptionPayment(request: ReportOrderPaymentRequest): Promise<SubscriptionOrderDto>;
+    getAdminBillingSettings(): Promise<Record<string, string>>;
+    registerLead(request: LeadRegisterRequest): Promise<void>;
+    adminGetLeads(): Promise<any[]>;
+    getMySettlements(): Promise<CommissionSettlementDto[]>;
+    getAvailableCommissions(): Promise<SalesCommissionDto[]>;
+    createSettlement(request: CreateSettlementRequest): Promise<CommissionSettlementDto>;
+    generateSettlementInvoice(settlementId: string): Promise<CommissionSettlementDto>;
+    getAvailablePackages(): Promise<LicensePackageResponse[]>;
+    purchaseAddon(request: PurchaseAddonRequest): Promise<LicenseAddonResponse>;
+    reportAddonPurchase(request: ReportAddonPurchaseRequest): Promise<LicenseAddonResponse>;
+    getTenantAddons(): Promise<LicenseAddonResponse[]>;
+    cancelAddon(addonId: string): Promise<void>;
+    adminGetLicenseLimits(): Promise<any[]>;
+    adminGetDeveloperSettlements(): Promise<any[]>;
+    getMyDeveloperSettlements(): Promise<any[]>;
+    getDeveloperPendingCommissions(): Promise<any[]>;
+    createDeveloperSettlement(commissionIds: string[]): Promise<any>;
+    payDeveloperSettlement(id: string, reference: string, paymentMethod?: string): Promise<any>;
+    getBillingSummary(): Promise<BillingSummaryResponse>;
+    getAddonPackages(): Promise<any[]>;
+    adminGetAllAddons(status?: string): Promise<LicenseAddonResponse[]>;
+    adminGetAllPackages(): Promise<any[]>;
+    adminGetPackage(id: string): Promise<any>;
+    adminCreatePackage(data: any): Promise<void>;
+    adminUpdatePackage(id: string, data: any): Promise<void>;
+    adminDeletePackage(id: string): Promise<void>;
+    adminGetPendingAddons(): Promise<LicenseAddonResponse[]>;
+    adminApproveAddon(addonId: string, request: ApproveAddonRequest): Promise<void>;
+    adminRejectAddon(addonId: string, request: RejectAddonRequest): Promise<void>;
+    getTenantLicenses(): Promise<TenantLicense[]>;
+    adminGetAllLicenses(): Promise<LicenseResponse[]>;
+    issueLicense(tenantId: string, request: IssueLicenseRequest): Promise<LicenseResponse>;
+    revokeLicense(licenseId: string): Promise<void>;
+    getWebhooks(): Promise<any[]>;
+    createWebhook(data: any): Promise<any>;
+    deleteWebhook(id: string): Promise<void>;
+    getDocumentsJson(filters: any): Promise<any>;
+}