@adatechnology/meta-whatsapp-module 0.2.0-rc.13 → 0.2.0-rc.15

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
 import * as _adatechnology_meta_whatsapp_contracts from '@adatechnology/meta-whatsapp-contracts';
-import { SessionState, SessionMode, ConversationSummary, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, MessageDirection, MessageSender, MessageStatus, RealtimeNotifierInterface, ChannelAdapterInterface, ObjectStorageInterface, FlowActionKind, FlowActionHandler, ConversationSession, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
+import { SessionState, SessionMode, ConversationSummary, CacheInterface, FlowGraphData, FlowGraphSummary, LiveFlowPosition, WhatsAppSettings, MessageDirection, MessageSender, MessageStatus, RealtimeNotifierInterface, ChannelAdapterInterface, ObjectStorageInterface, FlowActionKind, FlowActionHandler, ConversationSession, MetaWhatsAppHooks, SubjectResolverInterface, CatalogPort } from '@adatechnology/meta-whatsapp-contracts';
 import { WhatsAppMessageProvider } from '@adatechnology/meta-whatsapp-provider';
 
 type MetaWhatsAppDatabase = PgDatabase<PgQueryResultHKT, any, any>;
@@ -1000,6 +1000,257 @@ declare const flowGraphs: drizzle_orm_pg_core.PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
+/**
+ * Biblioteca de mídia do bot: arquivos que um nó `action` de `send_media` dispara ao chegar nele.
+ *
+ * Tabela separada de `documents` de propósito, e não por simetria: `documents` é o acervo DE UMA
+ * CONVERSA (tem `sessionId` obrigatório) e tem índice único em (companyId, uploadId), porque lá o
+ * mesmo binário chegando duas vezes é reentrega de job. Aqui é o oposto — o mesmo arquivo é
+ * enviado para todo cliente que passar pelo nó, então aquele único bloquearia o segundo envio.
+ *
+ * Sem FK para `flow_graphs.id`: o vínculo natural é (companyId, flowKey), que é justamente o
+ * índice único de lá. `nodeId` não tem como ser FK — nós vivem dentro do jsonb `nodes` — então
+ * apagar um nó no editor deixa a linha órfã; quem lista sempre parte de um nó existente, e a
+ * limpeza é passo de aplicação ao salvar o grafo.
+ */
+declare const flowMedia: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "flow_media";
+    schema: "meta_whatsapp";
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        companyId: drizzle_orm_pg_core.PgColumn<{
+            name: "company_id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        flowKey: drizzle_orm_pg_core.PgColumn<{
+            name: "flow_key";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        nodeId: drizzle_orm_pg_core.PgColumn<{
+            name: "node_id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        uploadId: drizzle_orm_pg_core.PgColumn<{
+            name: "upload_id";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 256;
+        }>;
+        filename: drizzle_orm_pg_core.PgColumn<{
+            name: "filename";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 512;
+        }>;
+        mimeType: drizzle_orm_pg_core.PgColumn<{
+            name: "mime_type";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 128;
+        }>;
+        sizeBytes: drizzle_orm_pg_core.PgColumn<{
+            name: "size_bytes";
+            tableName: "flow_media";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        caption: drizzle_orm_pg_core.PgColumn<{
+            name: "caption";
+            tableName: "flow_media";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sortOrder: drizzle_orm_pg_core.PgColumn<{
+            name: "sort_order";
+            tableName: "flow_media";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        active: drizzle_orm_pg_core.PgColumn<{
+            name: "active";
+            tableName: "flow_media";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "flow_media";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "flow_media";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 declare const settings: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "settings";
     schema: "meta_whatsapp";
@@ -1159,6 +1410,8 @@ type FlowGraphRow = typeof flowGraphs.$inferSelect;
 type NewFlowGraphRow = typeof flowGraphs.$inferInsert;
 type DocumentRow = typeof documents.$inferSelect;
 type NewDocumentRow = typeof documents.$inferInsert;
+type FlowMediaRow = typeof flowMedia.$inferSelect;
+type NewFlowMediaRow = typeof flowMedia.$inferInsert;
 
 interface ListConversationsFilters {
     page?: number;
@@ -1231,6 +1484,29 @@ declare class SessionRepository {
     } | null>;
 }
 
+declare const DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS = 300;
+/**
+ * Cache de leitura dos grafos de fluxo, com invalidação na publicação.
+ *
+ * TTL **e** invalidação explícita, e não um dos dois: só TTL deixaria o cliente andando no grafo
+ * antigo até a chave expirar, logo depois de alguém corrigir o fluxo no editor; só invalidação
+ * deixaria cache envenenado para sempre se um `delete` se perdesse (Redis reiniciando, deploy no
+ * meio da escrita).
+ *
+ * Toda operação é tolerante a falha por decisão de projeto: cache é aceleração, não dependência.
+ * Redis fora do ar tem que degradar para leitura no banco — que é exatamente o comportamento de
+ * quem não configura cache nenhum — em vez de derrubar a conversa do cliente.
+ */
+declare class FlowGraphCache {
+    private readonly provider;
+    private readonly ttlSeconds;
+    constructor(provider: CacheInterface, ttlSeconds?: number);
+    private keyFor;
+    read(companyId: string, flowKey: string): Promise<FlowGraphData | undefined>;
+    write(companyId: string, graph: FlowGraphData): Promise<void>;
+    invalidate(companyId: string, flowKey: string): Promise<void>;
+}
+
 declare class InvalidFlowGraphError extends Error {
     readonly validationMessage: string;
     constructor(key: string, validationMessage: string);
@@ -1240,7 +1516,8 @@ declare class OptimisticLockError extends Error {
 }
 declare class FlowGraphRepository {
     private readonly db;
-    constructor(db: MetaWhatsAppDatabase);
+    private readonly cache?;
+    constructor(db: MetaWhatsAppDatabase, cache?: FlowGraphCache | undefined);
     get(companyId: string, key: string): Promise<FlowGraphData | undefined>;
     list(companyId: string): Promise<FlowGraphSummary[]>;
     private assertValidNodes;
@@ -1757,6 +2034,57 @@ declare class FlowInterpreter {
     }): Promise<FlowRunResult>;
 }
 
+type FlowMediaLocation = {
+    companyId: string;
+    flowKey: string;
+    nodeId: string;
+};
+type AttachFlowMediaParams = FlowMediaLocation & {
+    uploadId: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    caption?: string;
+    sortOrder?: number;
+};
+type UpdateFlowMediaParams = {
+    companyId: string;
+    id: string;
+    caption?: string | null;
+    sortOrder?: number;
+    active?: boolean;
+};
+declare class FlowMediaRepository {
+    private readonly db;
+    constructor(db: MetaWhatsAppDatabase);
+    private locationFilter;
+    listActive(location: FlowMediaLocation): Promise<FlowMediaRow[]>;
+    listAll(location: FlowMediaLocation): Promise<FlowMediaRow[]>;
+    /**
+     * Anexa um arquivo já existente no storage ao nó.
+     *
+     * `onConflictDoUpdate` em vez de deixar estourar: reanexar o mesmo arquivo é clique repetido no
+     * editor, e o esperado ali é atualizar a legenda/ordem — não um erro de índice único na cara de
+     * quem está montando o fluxo.
+     */
+    attach(params: AttachFlowMediaParams): Promise<FlowMediaRow>;
+    update(params: UpdateFlowMediaParams): Promise<FlowMediaRow | undefined>;
+    /**
+     * Desanexa do nó. Não toca no storage de propósito: o mesmo `uploadId` pode estar anexado a
+     * outro nó ou a outro fluxo, e apagar o binário aqui quebraria os demais. Quem apaga objeto é o
+     * host, que é dono da biblioteca de arquivos.
+     */
+    detach(params: {
+        companyId: string;
+        id: string;
+    }): Promise<void>;
+    detachRemovedNodes(params: {
+        companyId: string;
+        flowKey: string;
+        existingNodeIds: string[];
+    }): Promise<void>;
+}
+
 interface NonceStoreInterface {
     setIfAbsent(key: string, ttlSeconds: number): Promise<boolean>;
 }
@@ -1841,9 +2169,13 @@ interface MetaWhatsAppModuleConfig {
 }
 interface MetaWhatsAppModuleFeatures {
     flowEngine?: boolean;
+    flowGraphCache?: boolean | {
+        ttlSeconds?: number;
+    };
 }
 interface MetaWhatsAppModuleProviders {
     objectStorage?: ObjectStorageInterface;
+    cache?: CacheInterface;
     realtime?: RealtimeNotifierInterface;
     subjectResolver?: SubjectResolverInterface;
     catalog?: CatalogPort;
@@ -1895,6 +2227,7 @@ declare function createMetaWhatsAppModule(params: CreateMetaWhatsAppModuleParams
         delete: DeleteFlowGraphUseCase;
         livePositions: GetLiveFlowPositionsUseCase;
         repository: FlowGraphRepository;
+        mediaRepository: FlowMediaRepository;
     } | undefined;
     catalog: CatalogPort | undefined;
 };
@@ -1978,4 +2311,31 @@ declare function redeemSseTicket(store: TicketStoreInterface, ticket: string): P
     whatsappNumber: string;
 } | null>;
 
-export { type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type NewDocumentRow, type NewFlowGraphRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, WEBHOOK_NONCE_TTL_SECONDS, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, documents, extractMediaDescriptor, flowGraphs, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, runMetaWhatsAppMigrations, sessions, settings, verifyWebhookChallenge, verifyWebhookSignature };
+type CreateSendMediaActionParams = {
+    flowMediaRepository: FlowMediaRepository;
+    objectStorage: ObjectStorageInterface & {
+        getObject: NonNullable<ObjectStorageInterface['getObject']>;
+    };
+    logMessage: LogMessageUseCase;
+    startState: SessionState;
+    onError?: (error: unknown, details: {
+        flowKey: string;
+        nodeId: string;
+        uploadId: string;
+    }) => void;
+};
+/**
+ * Action `send_media`: ao passar pelo nó, envia os arquivos que a biblioteca tem anexados a ele.
+ *
+ * É a única action built-in que o módulo implementa de ponta a ponta — as outras
+ * (`handoff`, `send_product_list`) dependem de regra de negócio do produto. Esta não: "mandar
+ * estes arquivos ao chegar aqui" é comportamento de canal, e replicá-la em cada host seria
+ * copiar o mesmo código com os mesmos bugs.
+ *
+ * O nó não guarda os arquivos em `actionParams` de propósito. Se guardasse, trocar o material
+ * exigiria editar e republicar o grafo — e o ponto todo é o contrário: quem cuida do conteúdo
+ * troca o arquivo na biblioteca e o fluxo continua igual.
+ */
+declare function createSendMediaAction(params: CreateSendMediaActionParams): FlowActionHandler;
+
+export { type AttachFlowMediaParams, type CompanyDocumentView, type CompanyDocumentsPage, type ConversationDocumentView, type ConversationDocumentsPage, type CreateFlowGraphParams, CreateFlowGraphUseCase, type CreateMetaWhatsAppModuleParams, type CreateSendMediaActionParams, DEFAULT_FLOW_GRAPH_CACHE_TTL_SECONDS, type DeleteConversationParams, type DeleteConversationResult, DeleteConversationUseCase, DeleteFlowGraphUseCase, DocumentRepository, type DocumentRow, type DrizzleMigrateFunction, type ExportConversationParams, type ExportConversationResult, ExportConversationUseCase, FlowGraphCache, FlowGraphRepository, type FlowGraphRow, FlowInterpreter, type FlowMediaLocation, FlowMediaRepository, type FlowMediaRow, type FlowRunResult, type FlowStepInput, type FlowStepResult, GetFlowGraphUseCase, GetLiveFlowPositionsUseCase, type IngestInboundMediaParams, type IngestInboundMediaResult, IngestInboundMediaUseCase, type InsertMessageParams, InvalidFlowGraphError, type LinkDocumentParams, type ListCompanyDocumentsParams, ListCompanyDocumentsUseCase, type ListConversationDocumentsParams, ListConversationDocumentsUseCase, type ListConversationsFilters, type ListConversationsParams, ListConversationsUseCase, type ListDocumentsParams, type ListDocumentsResult, ListFlowGraphsUseCase, type ListMessagesParams, ListMessagesUseCase, type LogMessageParams, LogMessageUseCase, META_WHATSAPP_MIGRATIONS_TABLE, type MessageModerator, MessageRepository, type MessageRow, type MetaWhatsAppDatabase, type MetaWhatsAppModule, type MetaWhatsAppModuleConfig, type MetaWhatsAppModuleFeatures, type MetaWhatsAppModuleProviders, type NewDocumentRow, type NewFlowGraphRow, type NewFlowMediaRow, type NewMessageRow, type NewSessionRow, type NewSettingsRow, type NonceStoreInterface, OptimisticLockError, type PurgeExpiredDocumentsParams, type PurgeExpiredDocumentsResult, PurgeExpiredDocumentsUseCase, type RealtimeRelay, type ReceiveWebhookParams, type ReceiveWebhookResult, ReceiveWebhookUseCase, type ReleaseConversationParams, ReleaseConversationUseCase, type ListMessagesParams$1 as RepositoryListMessagesParams, type RunMetaWhatsAppMigrationsParams, type SaveFlowGraphParams, SaveFlowGraphUseCase, type SendMediaParams, SendMessageUseCase, type SendTemplateParams, type SendTextParams, SessionRepository, type SessionRow, SettingsRepository, type SettingsRow, SseHub, type SseListener, type TakeoverConversationParams, TakeoverConversationUseCase, type TicketStoreInterface, type UpdateFlowMediaParams, WEBHOOK_NONCE_TTL_SECONDS, WhatsAppChannelAdapter, claimWebhookDelivery, createMetaWhatsAppModule, createSendMediaAction, documents, extractMediaDescriptor, flowGraphs, flowMedia, issueSseTicket, messages, metaWhatsAppMigrationsFolder, metaWhatsAppSchema, redeemSseTicket, runMetaWhatsAppMigrations, sessions, settings, verifyWebhookChallenge, verifyWebhookSignature };