novapsis 1.0.0 → 1.1.1

package/dist/index.d.mts

@@ -5,7 +5,7 @@
  * Universal typed client for WhatsApp Business Cloud API, Hosted Onboarding,
  * CRM, AI Agents and HMAC Webhook Verification.
  *
- * @version 1.0.0
+ * @version 1.1.1
  * @author Novapsis Technologies
  * @license MIT
  * ══════════════════════════════════════════════════════════════════════════════
@@ -107,6 +107,9 @@ interface SendTemplateOptions extends SendBaseOptions {
 interface SendMessageResult {
     message_id: string;
     recipient: string;
+    connection_id?: string;
+    phone_number_id?: string;
+    business_phone_number?: string | null;
     type: string;
     status: string;
     conversation_id: string | null;
@@ -116,27 +119,211 @@ interface WhatsAppConnection {
     display_name: string;
     phone_number: string | null;
     phone_number_id: string;
+    waba_id?: string | null;
     verified_name: string | null;
+    quality_rating?: string | null;
     status: string;
     webhook_subscribed: boolean;
+    created_at?: string;
 }
 interface WhatsAppTemplate {
     id: string;
-    name: string;
-    category: string;
+    template_name?: string;
+    display_name?: string;
+    name?: string;
+    category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION' | string;
     language: string;
-    status: string;
+    status: 'APPROVED' | 'PENDING' | 'REJECTED' | 'PAUSED' | string;
+    quality_rating?: string | null;
     components: any[];
+    meta_template_id?: string | null;
+    rejection_reason?: string | null;
+    waba_id?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+interface ListTemplatesOptions {
+    /** Filtrar por estado en Meta (ej: 'APPROVED', 'PENDING', 'REJECTED') */
+    status?: 'APPROVED' | 'PENDING' | 'REJECTED' | 'PAUSED' | string;
+    /** Filtrar por categoría oficial */
+    category?: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION' | string;
+}
+interface CreateTemplateOptions {
+    /** Nombre técnico en Meta (solo minúsculas, números y guiones bajos, ej: 'confirmacion_pedido_v1') */
+    name?: string;
+    template_name?: string;
+    /** Nombre descriptivo para el panel */
+    displayName?: string;
+    display_name?: string;
+    /** Categoría oficial de Meta */
+    category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION';
+    /** Código de idioma (por defecto: 'es') */
+    language?: string;
+    /** Componentes según especificación de Meta Graph API (HEADER, BODY, BUTTONS, etc.) */
+    components?: any[];
+    /** Texto plano del cuerpo si no se envían componentes avanzados */
+    bodyText?: string;
+    /** ID de conexión de WhatsApp (opcional si la cuenta tiene una sola activa) */
+    connectionId?: string;
+    connection_id?: string;
+    /** TTL de entrega en segundos (opcional) */
+    messageSendTtlSeconds?: number;
+}
+interface OrganizationDetails {
+    id: string;
+    name: string;
+    timezone: string;
+    tier: string;
+    created_at: string;
+    updated_at: string;
+}
+interface UpdateOrganizationOptions {
+    /** Nombre de la empresa o aplicación (cambio de nombre / settings de la app) */
+    name?: string;
+    /** Zona horaria IANA (ej: 'Europe/Madrid', 'America/Bogota', 'America/Mexico_City') */
+    timezone?: string;
+}
+interface AgentDetails {
+    id: string;
+    name: string;
+    system_prompt: string;
+    model: string;
+    mode: 'agent' | 'rag' | 'both';
+    temperature: number;
+    is_active: boolean;
+    grouping_timeout_seconds: number;
+    created_at?: string;
+    updated_at?: string;
+}
+interface CreateAgentOptions {
+    /** Nombre del agente de IA (ej: 'Asistente Ventas') */
+    name: string;
+    /** Prompt de sistema e instrucciones de comportamiento */
+    systemPrompt: string;
+    /** Modelo de IA a utilizar (por defecto: 'gemini-2.5-flash') */
+    model?: string;
+    /** Modo de operación: 'agent', 'rag' o 'both' */
+    mode?: 'agent' | 'rag' | 'both';
+    /** Creatividad (temperatura 0.0 - 1.0) */
+    temperature?: number;
+    /** Si el agente está activo respondiendo chats */
+    isActive?: boolean;
+    /** Ventana de agrupación de mensajes en segundos */
+    groupingTimeoutSeconds?: number;
+}
+interface UpdateAgentOptions {
+    /** Nuevo nombre del agente (cambio de nombre del bot) */
+    name?: string;
+    /** Nuevo prompt de sistema */
+    systemPrompt?: string;
+    /** Modelo de IA */
+    model?: string;
+    /** Modo de operación */
+    mode?: 'agent' | 'rag' | 'both';
+    /** Creatividad */
+    temperature?: number;
+    /** Estado activo o inactivo */
+    isActive?: boolean;
+    /** Ventana de agrupación en segundos */
+    groupingTimeoutSeconds?: number;
+}
+interface AgentSchedule {
+    id: string;
+    agent_id: string;
+    name: string;
+    days: number[];
+    active_from: string;
+    active_until: string;
+    is_active: boolean;
+    created_at?: string;
+    updated_at?: string;
+}
+interface SetScheduleOptions {
+    /** Días activos: 1=Lunes, 2=Martes, 3=Miércoles, 4=Jueves, 5=Viernes, 6=Sábado, 7=Domingo */
+    days: number[];
+    /** Hora de apertura en formato HH:MM (ej: '09:00') */
+    activeFrom: string;
+    /** Hora de cierre en formato HH:MM (ej: '19:00') */
+    activeUntil: string;
+    /** Nombre de la franja horaria */
+    name?: string;
+    /** Si el horario está habilitado */
+    isActive?: boolean;
+}
+interface KnowledgeDocument {
+    id: string;
+    title: string;
+    description?: string | null;
+    file_type: string;
+    total_chunks?: number;
+    created_at: string;
+    updated_at?: string;
+}
+interface AddKnowledgeOptions {
+    /** Título o tema del documento (ej: 'Políticas de garantía y devoluciones') */
+    title: string;
+    /** Contenido en texto plano a vectorizar para RAG */
+    content: string;
+    /** Descripción contextual */
+    description?: string;
+}
+interface OnboardingFeatureBullet {
+    title: string;
+    description?: string;
 }
 interface CreateOnboardingSessionOptions {
-    /** Nombre de la empresa, cliente o sede a mostrar en la pantalla de conexión */
+    /** Nombre del cliente, empresa o sede (ej: 'Clínica Dental') */
     clientName?: string;
-    /** URL de retorno a la que redirigir al usuario cuando vincule su WhatsApp */
+    /** Nombre corporativo visible */
+    companyName?: string;
+    /** URL de retorno tras conectar exitosamente con WhatsApp */
     redirectUrl?: string;
-    /** URL del logotipo de la empresa cliente para marca blanca */
+    /** URL pública del logotipo corporativo para marca blanca (PNG, SVG, JPG) */
     logoUrl?: string;
-    /** Color hexadecimal corporativo para la interfaz de conexión (ej: '#0ea5e9') */
+    /** Color de acento principal (ej: '#0ea5e9') */
     brandColor?: string;
+    /** Color de fondo general de la pantalla (ej: '#0f172a' o '#ffffff') */
+    backgroundColor?: string;
+    /** Color de fondo de la tarjeta/modal (ej: '#1e293b' o '#ffffff') */
+    cardBackgroundColor?: string;
+    /** Color del borde de la tarjeta (ej: 'rgba(255,255,255,0.1)') */
+    cardBorderColor?: string;
+    /** Color de los títulos y textos principales (ej: '#ffffff' o '#0f172a') */
+    textColor?: string;
+    /** Color de los textos secundarios y descripciones (ej: '#94a3b8') */
+    textSecondaryColor?: string;
+    /** Color de fondo del botón de acción (por defecto usa brandColor o verde WhatsApp) */
+    buttonColor?: string;
+    /** Color del texto dentro del botón de acción */
+    buttonTextColor?: string;
+    /** Color de fondo de la píldora superior */
+    badgeColor?: string;
+    /** Color del texto de la píldora superior */
+    badgeTextColor?: string;
+    /** Título principal (por defecto: 'Conecta WhatsApp Business') */
+    title?: string;
+    /** Texto explicativo debajo del título */
+    description?: string;
+    /** Texto del botón principal (por defecto: 'Conectar con WhatsApp') */
+    buttonText?: string;
+    /** Texto de la píldora superior (por defecto: 'Vinculación Oficial', o '' para ocultar) */
+    badgeText?: string;
+    /** Texto legal o footer de la tarjeta */
+    footerText?: string;
+    /** Viñetas de beneficios o false para ocultar la caja */
+    features?: OnboardingFeatureBullet[] | boolean;
+    /** Título de la pantalla de éxito tras vincular */
+    successTitle?: string;
+    /** Descripción de la pantalla de éxito */
+    successDescription?: string;
+    /** Texto del botón en la pantalla de éxito */
+    successButtonText?: string;
+    /** Si es true, oculta el badge 'Meta Tech Provider Verified' del encabezado */
+    hideMetaBadge?: boolean;
+    /** Si es true, oculta el pie de página de copyright */
+    hideFooter?: boolean;
+    /** Horas de validez de la sesión antes de expirar (por defecto: 168 = 7 días) */
+    expiresInHours?: number;
     /** Metadata personalizada para tracking en tu CRM */
     metadata?: Record<string, any>;
 }
@@ -149,6 +336,46 @@ interface OnboardingSession {
     created_at: string;
 }
 type NovapsisWebhookEvent = 'whatsapp.message_received' | 'whatsapp.message_sent' | 'whatsapp.connected' | 'conversation.started' | 'lead.completed' | 'call.completed' | 'review.received' | '*';
+interface WhatsAppMessageReceivedData {
+    conversation_id: string;
+    message_id: string;
+    external_message_id?: string | null;
+    platform: 'whatsapp' | string;
+    connection_id: string;
+    phone_number_id: string;
+    waba_id?: string | null;
+    business_phone_number: string | null;
+    business_name?: string | null;
+    connection_name?: string | null;
+    to: string | null;
+    from: string;
+    external_user_id: string;
+    external_user_name: string;
+    content: string;
+    media_type: 'image' | 'audio' | 'video' | 'document' | null;
+    media_url: string | null;
+    timestamp: string;
+}
+interface WhatsAppMessageSentData {
+    conversation_id: string;
+    message_id: string;
+    platform: 'whatsapp' | string;
+    connection_id: string;
+    phone_number_id: string;
+    waba_id?: string | null;
+    business_phone_number: string | null;
+    business_name?: string | null;
+    connection_name?: string | null;
+    from: string | null;
+    to: string;
+    external_user_id: string;
+    role: 'assistant';
+    sender_type: 'ai' | 'human';
+    content: string;
+    media_type?: string | null;
+    media_url?: string | null;
+    timestamp: string;
+}
 interface CreateWebhookSubscriptionOptions {
     /** Nombre descriptivo de la suscripción (ej: 'CRM Sincronizador') */
     name: string;
@@ -225,14 +452,14 @@ declare class WhatsAppService {
     }): Promise<any>;
     /** Obtiene la lista de líneas y números de WhatsApp conectados en la organización */
     listConnections(): Promise<WhatsAppConnection[]>;
-    /** Obtiene las plantillas oficiales de Meta aprobadas */
+    /** Lista las plantillas oficiales de Meta con filtros opcionales de estado y categoría */
+    listTemplates(options?: ListTemplatesOptions): Promise<WhatsAppTemplate[]>;
+    /** Obtiene las plantillas oficiales de Meta aprobadas (alias directo de listTemplates) */
     getTemplates(): Promise<WhatsAppTemplate[]>;
-    /** Crea una nueva plantilla para enviar a revisión a Meta */
-    createTemplate(options: {
-        name: string;
-        category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION';
-        bodyText: string;
-    }): Promise<any>;
+    /** Crea una nueva plantilla oficial de WhatsApp para someter a revisión y aprobación en Meta */
+    createTemplate(options: CreateTemplateOptions): Promise<{
+        template: WhatsAppTemplate;
+    }>;
     /** Lista las campañas masivas de WhatsApp configuradas */
     listCampaigns(): Promise<any[]>;
     /** Ejecuta una campaña masiva */
@@ -279,13 +506,44 @@ declare class ContactsService {
     /** Crea o actualiza un contacto por número de teléfono */
     upsert(options: UpsertContactOptions): Promise<Contact>;
 }
-/** Servicio para interactuar con Agentes de Inteligencia Artificial */
+/** Servicio para gestión de la organización y configuración general (Marca / Settings) */
+declare class OrganizationService {
+    private http;
+    constructor(http: HttpClient);
+    /** Obtiene la información y configuración de la organización actual */
+    get(): Promise<OrganizationDetails>;
+    /**
+     * Actualiza la configuración de la organización (cambio de nombre de la app/empresa, zona horaria)
+     */
+    update(options: UpdateOrganizationOptions): Promise<OrganizationDetails>;
+}
+/** Servicio para interactuar y configurar Agentes de Inteligencia Artificial (Headless AI) */
 declare class AIService {
     private http;
     constructor(http: HttpClient);
-    /** Lista los agentes de IA configurados con sus modelos */
-    listAgents(): Promise<any[]>;
-    /** Ejecuta una consulta contra un agente de IA con su base de conocimiento RAG */
+    /** Lista los agentes de IA configurados en la organización */
+    listAgents(): Promise<AgentDetails[]>;
+    /** Obtiene la configuración completa de un agente por su ID */
+    getAgent(agentId: string): Promise<AgentDetails>;
+    /** Crea un nuevo agente de IA para la organización */
+    createAgent(options: CreateAgentOptions): Promise<AgentDetails>;
+    /** Actualiza nombre, prompt de sistema, modelo o configuración de un agente */
+    updateAgent(agentId: string, options: UpdateAgentOptions): Promise<AgentDetails>;
+    /** Consulta el horario de atención configurado para el agente y la zona horaria */
+    getSchedule(agentId: string): Promise<{
+        schedule: AgentSchedule | null;
+        timezone: string;
+    }>;
+    /** Configura o reemplaza el horario de atención activa del agente */
+    setSchedule(agentId: string, options: SetScheduleOptions): Promise<{
+        schedule: AgentSchedule;
+        timezone: string;
+    }>;
+    /** Lista los documentos de la base de conocimiento RAG asociados al agente */
+    listKnowledge(agentId: string): Promise<KnowledgeDocument[]>;
+    /** Ingesta y vectoriza nuevo conocimiento en texto plano directamente al agente */
+    addKnowledge(agentId: string, options: AddKnowledgeOptions): Promise<KnowledgeDocument>;
+    /** Ejecuta una consulta conversacional contra el agente y su base de conocimiento RAG */
     execute(options: {
         agentId: string;
         message: string;
@@ -303,7 +561,7 @@ declare class AIService {
  * import { Novapsis } from 'novapsis';
  *
  * const client = new Novapsis({
- *   apiKey: 'nvs_live_OfnAAb6sEGztGcdbR5IKnhFpPrDJSTq7',
+ *   apiKey: 'nvs_live_sample_abcdef1234567890',
  * });
  *
  * // Enviar mensaje de texto
@@ -315,6 +573,8 @@ declare class AIService {
  */
 declare class Novapsis {
     private http;
+    /** Métodos para ajustes de la organización y cambio de nombre de la app */
+    readonly organization: OrganizationService;
     /** Métodos para envíos y operaciones de WhatsApp */
     readonly whatsapp: WhatsAppService;
     /** Métodos para onboarding hosted y vinculación B2B */
@@ -323,9 +583,9 @@ declare class Novapsis {
     readonly webhooks: WebhookService;
     /** Métodos para contactos del CRM */
     readonly contacts: ContactsService;
-    /** Métodos para Agentes de Inteligencia Artificial */
+    /** Métodos para Agentes de Inteligencia Artificial (prompts, RAG, horarios) */
     readonly ai: AIService;
     constructor(options: NovapsisClientOptions);
 }
 
-export { AIService, type APIResponse, type Contact, ContactsService, type CreateOnboardingSessionOptions, type CreateWebhookSubscriptionOptions, type InboundWebhookPayload, Novapsis, NovapsisAPIError, type NovapsisClientOptions, type NovapsisWebhookEvent, OnboardingService, type OnboardingSession, type SendAudioOptions, type SendBaseOptions, type SendContactCardOptions, type SendDocumentOptions, type SendImageOptions, type SendLocationOptions, type SendMessageResult, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, type UpsertContactOptions, WebhookService, type WebhookSubscription, type WhatsAppConnection, WhatsAppService, type WhatsAppTemplate, Novapsis as default };
+export { AIService, type APIResponse, type AddKnowledgeOptions, type AgentDetails, type AgentSchedule, type Contact, ContactsService, type CreateAgentOptions, type CreateOnboardingSessionOptions, type CreateTemplateOptions, type CreateWebhookSubscriptionOptions, type InboundWebhookPayload, type KnowledgeDocument, type ListTemplatesOptions, Novapsis, NovapsisAPIError, type NovapsisClientOptions, type NovapsisWebhookEvent, type OnboardingFeatureBullet, OnboardingService, type OnboardingSession, type OrganizationDetails, OrganizationService, type SendAudioOptions, type SendBaseOptions, type SendContactCardOptions, type SendDocumentOptions, type SendImageOptions, type SendLocationOptions, type SendMessageResult, type SendTemplateOptions, type SendTextOptions, type SendVideoOptions, type SetScheduleOptions, type UpdateAgentOptions, type UpdateOrganizationOptions, type UpsertContactOptions, WebhookService, type WebhookSubscription, type WhatsAppConnection, type WhatsAppMessageReceivedData, type WhatsAppMessageSentData, WhatsAppService, type WhatsAppTemplate, Novapsis as default };