evo360-types 1.3.697 → 1.3.699

package/dist/types/evo-finops/index.d.ts

@@ -9,6 +9,7 @@ export * from "./common/nfse-fee-reimbursement";
 export * from "./providers";
 export * from "./providers/provider_fiscal_types";
 export * from "./providers/asaas/asaas_provider";
+export * from "./providers/asaas/asaas_kyc";
 export * from "./providers/inter/inter_provider";
 export * from "./dic";
 export * from "./invoices";

package/dist/types/evo-finops/index.js

@@ -26,6 +26,7 @@ __exportStar(require("./common/nfse-fee-reimbursement"), exports);
 __exportStar(require("./providers"), exports);
 __exportStar(require("./providers/provider_fiscal_types"), exports);
 __exportStar(require("./providers/asaas/asaas_provider"), exports);
+__exportStar(require("./providers/asaas/asaas_kyc"), exports);
 __exportStar(require("./providers/inter/inter_provider"), exports);
 __exportStar(require("./dic"), exports);
 __exportStar(require("./invoices"), exports);

package/dist/types/evo-finops/index.ts

@@ -11,6 +11,7 @@ export * from "./common/nfse-fee-reimbursement";
 export * from "./providers";
 export * from "./providers/provider_fiscal_types";
 export * from "./providers/asaas/asaas_provider";
+export * from "./providers/asaas/asaas_kyc";
 export * from "./providers/inter/inter_provider";
 export * from "./dic";
 export * from "./invoices";

package/dist/types/evo-finops/providers/asaas/asaas_kyc.d.ts

@@ -0,0 +1,63 @@
+import { AsaasAccessTokenStatus, AsaasAccountStatusValue, AsaasEnvironment, AsaasKycNotificationTrigger, AsaasOnboardingNextAction, IAsaasCommercialInfoExpiration } from "./asaas_provider";
+/** Tópico Pub/Sub dos pedidos de aviso de KYC (publicado pelo functions-app). */
+export declare const FINOPS_ASAAS_KYC_NOTIFY_TOPIC = "app_evo-finops_asaas-kyc_notify-requested";
+/** Gatilho do aviso: os de KYC + alerta de chave de API (destinado ao staff). */
+export type FinopsAsaasKycNotifyTrigger = AsaasKycNotificationTrigger | "access_token_alert";
+export interface IFinopsAsaasKycNotifyRecipient {
+    name?: string | null;
+    email?: string | null;
+    /** E.164 normalizado. */
+    mobile_phone?: string | null;
+}
+export interface IFinopsAsaasKycNotifyMessage {
+    tenant: string;
+    provider_id: string;
+    provider_name?: string;
+    trigger: FinopsAsaasKycNotifyTrigger;
+    /** Escopo do dedup (ex.: hash do link, data agendada). Chave = `${trigger}:${dedup_scope}`. */
+    dedup_scope: string;
+    /**
+     * Opcional: o consumidor resolve o contato administrativo da clínica
+     * (cliente do Nexus por `tenant_refs[].tenant`, leads com role `administrative`).
+     */
+    recipients?: IFinopsAsaasKycNotifyRecipient[];
+    /** Usado quando o cliente do Nexus não tem contato administrativo (vem do `holder_contact`). */
+    fallback_recipients?: IFinopsAsaasKycNotifyRecipient[];
+    /** nome, clinica, link, data_limite, motivo… */
+    variables: Record<string, string>;
+    /** ISO datetime. */
+    requested_at: string;
+}
+/** Grupo de documento pendente, resumido para a fila. */
+export interface INexKycQueuePendingGroup {
+    title?: string | null;
+    status?: string | null;
+}
+/** Resumo de `IAsaasAccessTokenMeta` exibido na fila. */
+export interface INexKycQueueAccessTokenSummary {
+    status: AsaasAccessTokenStatus;
+    projected_expiration_by_lack_of_use?: string | null;
+    last_event?: string | null;
+}
+/** feat-275 — linha da fila de KYC do Nexus (uma por provider `asaas_subaccount` não aprovado). */
+export interface INexKycQueueItem {
+    tenant: string;
+    provider_id: string;
+    provider_name?: string | null;
+    /** Ambiente do snapshot exibido. */
+    env?: AsaasEnvironment;
+    /** ISO datetime de criação do provider. */
+    created_at?: string | null;
+    general?: AsaasAccountStatusValue | null;
+    documentation?: AsaasAccountStatusValue | null;
+    commercialInfo?: AsaasAccountStatusValue | null;
+    next_action?: AsaasOnboardingNextAction | null;
+    documents_fetched_at?: string | null;
+    has_onboarding_url: boolean;
+    pending_groups: INexKycQueuePendingGroup[];
+    commercial_info_expiration?: IAsaasCommercialInfoExpiration | null;
+    access_token_meta?: INexKycQueueAccessTokenSummary | null;
+    last_error?: {
+        code?: string | null;
+    } | null;
+}

package/dist/types/evo-finops/providers/asaas/asaas_kyc.js

@@ -0,0 +1,14 @@
+"use strict";
+// ── feat-275 — KYC da subconta Asaas (BaaS) ──
+//
+// Contratos compartilhados functions-app ↔ functions-nexus:
+// - mensagem Pub/Sub que pede um aviso de KYC ao cliente (o consumidor no
+//   functions-nexus resolve o contato administrativo da clínica no cadastro do
+//   cliente do Nexus; `fallback_recipients` vem do `holder_contact` da subconta);
+// - linha da fila de KYC do Nexus.
+//
+// Runtime `lib: es6`: as constantes abaixo são só dados.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINOPS_ASAAS_KYC_NOTIFY_TOPIC = void 0;
+/** Tópico Pub/Sub dos pedidos de aviso de KYC (publicado pelo functions-app). */
+exports.FINOPS_ASAAS_KYC_NOTIFY_TOPIC = "app_evo-finops_asaas-kyc_notify-requested";

package/dist/types/evo-finops/providers/asaas/asaas_kyc.ts

@@ -0,0 +1,85 @@
+// ── feat-275 — KYC da subconta Asaas (BaaS) ──
+//
+// Contratos compartilhados functions-app ↔ functions-nexus:
+// - mensagem Pub/Sub que pede um aviso de KYC ao cliente (o consumidor no
+//   functions-nexus resolve o contato administrativo da clínica no cadastro do
+//   cliente do Nexus; `fallback_recipients` vem do `holder_contact` da subconta);
+// - linha da fila de KYC do Nexus.
+//
+// Runtime `lib: es6`: as constantes abaixo são só dados.
+
+import {
+  AsaasAccessTokenStatus,
+  AsaasAccountStatusValue,
+  AsaasEnvironment,
+  AsaasKycNotificationTrigger,
+  AsaasOnboardingNextAction,
+  IAsaasCommercialInfoExpiration,
+} from "./asaas_provider";
+
+/** Tópico Pub/Sub dos pedidos de aviso de KYC (publicado pelo functions-app). */
+export const FINOPS_ASAAS_KYC_NOTIFY_TOPIC = "app_evo-finops_asaas-kyc_notify-requested";
+
+/** Gatilho do aviso: os de KYC + alerta de chave de API (destinado ao staff). */
+export type FinopsAsaasKycNotifyTrigger = AsaasKycNotificationTrigger | "access_token_alert";
+
+export interface IFinopsAsaasKycNotifyRecipient {
+  name?: string | null;
+  email?: string | null;
+  /** E.164 normalizado. */
+  mobile_phone?: string | null;
+}
+
+export interface IFinopsAsaasKycNotifyMessage {
+  tenant: string;
+  provider_id: string;
+  provider_name?: string;
+  trigger: FinopsAsaasKycNotifyTrigger;
+  /** Escopo do dedup (ex.: hash do link, data agendada). Chave = `${trigger}:${dedup_scope}`. */
+  dedup_scope: string;
+  /**
+   * Opcional: o consumidor resolve o contato administrativo da clínica
+   * (cliente do Nexus por `tenant_refs[].tenant`, leads com role `administrative`).
+   */
+  recipients?: IFinopsAsaasKycNotifyRecipient[];
+  /** Usado quando o cliente do Nexus não tem contato administrativo (vem do `holder_contact`). */
+  fallback_recipients?: IFinopsAsaasKycNotifyRecipient[];
+  /** nome, clinica, link, data_limite, motivo… */
+  variables: Record<string, string>;
+  /** ISO datetime. */
+  requested_at: string;
+}
+
+/** Grupo de documento pendente, resumido para a fila. */
+export interface INexKycQueuePendingGroup {
+  title?: string | null;
+  status?: string | null;
+}
+
+/** Resumo de `IAsaasAccessTokenMeta` exibido na fila. */
+export interface INexKycQueueAccessTokenSummary {
+  status: AsaasAccessTokenStatus;
+  projected_expiration_by_lack_of_use?: string | null;
+  last_event?: string | null;
+}
+
+/** feat-275 — linha da fila de KYC do Nexus (uma por provider `asaas_subaccount` não aprovado). */
+export interface INexKycQueueItem {
+  tenant: string;
+  provider_id: string;
+  provider_name?: string | null;
+  /** Ambiente do snapshot exibido. */
+  env?: AsaasEnvironment;
+  /** ISO datetime de criação do provider. */
+  created_at?: string | null;
+  general?: AsaasAccountStatusValue | null;
+  documentation?: AsaasAccountStatusValue | null;
+  commercialInfo?: AsaasAccountStatusValue | null;
+  next_action?: AsaasOnboardingNextAction | null;
+  documents_fetched_at?: string | null;
+  has_onboarding_url: boolean;
+  pending_groups: INexKycQueuePendingGroup[];
+  commercial_info_expiration?: IAsaasCommercialInfoExpiration | null;
+  access_token_meta?: INexKycQueueAccessTokenSummary | null;
+  last_error?: { code?: string | null } | null;
+}

package/dist/types/evo-finops/providers/asaas/asaas_provider.d.ts

@@ -99,9 +99,27 @@ export interface IAsaasSubaccountInput {
 /** Valores do status cadastral devolvidos pelo Asaas em GET /v3/myAccount/status. */
 export type AsaasAccountStatusValue = "APPROVED" | "AWAITING_APPROVAL" | "PENDING" | "REJECTED" | "EXPIRING_SOON" | "EXPIRED";
 /** O que originou a escrita do snapshot cadastral. */
-export type AsaasOnboardingSource = "manual_refresh" | "webhook" | "provider_create" | "scheduled_refresh";
+export type AsaasOnboardingSource = "manual_refresh" | "webhook" | "provider_create" | "scheduled_refresh"
+/** feat-275 — rebusca de documentos disparada por webhook ACCOUNT_STATUS_*. */
+ | "webhook_refetch"
+/** feat-275 — refresh inline no gate de emissão (subconta sem snapshot). */
+ | "gate_refresh"
+/** feat-275 — upload de documento pela nossa tela. */
+ | "document_upload"
+/** feat-275 — atualização/confirmação dos dados comerciais pela nossa tela. */
+ | "commercial_info_update"
+/** feat-275 — troca/registro de chave de API da subconta. */
+ | "key_rotation";
 /** Próxima ação que o dono da conta precisa executar para destravar a subconta. */
-export type AsaasOnboardingNextAction = "approved" | "rejected" | "awaiting_analysis" | "open_onboarding_link" | "send_documents_external" | "fix_commercial_info" | "pending_bank_account" | "unknown";
+export type AsaasOnboardingNextAction = "approved" | "rejected" | "awaiting_analysis" | "open_onboarding_link"
+/** Legado: permanece para snapshots antigos; o mapper da feat-275 deixa de emiti-lo. */
+ | "send_documents_external" | "fix_commercial_info" | "pending_bank_account"
+/** feat-275 — grupo sem onboarding_url: upload pela nossa tela. */
+ | "upload_documents"
+/** feat-275 — confirmação anual dos dados comerciais (EXPIRING_SOON / EXPIRED). */
+ | "confirm_commercial_info"
+/** feat-275 — subconta recém-criada; o Asaas ainda não gerou os documentos. */
+ | "awaiting_link" | "unknown";
 /** Snapshot de GET /v3/myAccount/status. Sobrescrito inteiro a cada leitura/evento. */
 export interface IAsaasAccountStatusSnapshot {
     fetched_at: string;
@@ -134,6 +152,10 @@ export interface IAsaasOnboardingDocumentGroup {
         id?: string;
         status?: string;
     }>;
+    /** feat-275 — quando fizemos o último upload deste grupo (metadado; nunca o arquivo). */
+    last_upload_at?: string | null;
+    /** feat-275 — userId de quem fez o último upload. */
+    last_upload_by?: string | null;
 }
 /** Snapshot de GET /v3/myAccount/documents + próxima ação derivada. */
 export interface IAsaasOnboardingSnapshot {
@@ -142,6 +164,61 @@ export interface IAsaasOnboardingSnapshot {
     document_groups: IAsaasOnboardingDocumentGroup[];
     next_action: AsaasOnboardingNextAction;
 }
+/**
+ * feat-275 — confirmação anual dos dados comerciais.
+ * Com `is_expired` o Asaas responde 403 em tudo, exceto GET/POST /myAccount/commercialInfo.
+ */
+export interface IAsaasCommercialInfoExpiration {
+    is_expired: boolean;
+    /** YYYY-MM-DD (`additionalInfo.scheduledDate` do evento EXPIRING_SOON). */
+    scheduled_date?: string | null;
+    updated_at: string;
+    source: "provider_create" | "webhook" | "commercial_info_fetch" | "commercial_info_update";
+}
+/** feat-275 — contato de negócio do titular da subconta (LGPD: só nome, e-mail e celular). */
+export interface IAsaasHolderContact {
+    name?: string | null;
+    email?: string | null;
+    /** E.164 normalizado. */
+    mobile_phone?: string | null;
+    source: "provider_create" | "commercial_info";
+    updated_at: string;
+}
+/** feat-275 — gatilhos de aviso de KYC ao cliente. */
+export type AsaasKycNotificationTrigger = "link_available" | "link_renewed" | "rejected" | "commercial_info_expiring" | "commercial_info_expired";
+/** feat-275 — estado de dedup dos avisos de KYC. */
+export interface IAsaasKycNotificationState {
+    /** chave = `${trigger}:${scope}` (ex.: `link_available:3f9a...`); valor = quando foi publicado. */
+    sent?: Record<string, {
+        at: string;
+        trigger: AsaasKycNotificationTrigger;
+    }>;
+    /** sha256(url).slice(0,16) — nunca a URL. */
+    last_link_hash?: string | null;
+}
+/** feat-275 — estado da chave de API da subconta. */
+export type AsaasAccessTokenStatus = "active" | "disabled" | "expired" | "deleted" | "invalid" | "unknown";
+/**
+ * feat-275 — metadado da chave de API (nunca o valor). Alimentado por eventos ACCESS_TOKEN_*
+ * e pela checagem diária (`GET /myAccount/status` com a chave da subconta).
+ */
+export interface IAsaasAccessTokenMeta {
+    asaas_access_token_id?: string | null;
+    name?: string | null;
+    status: AsaasAccessTokenStatus;
+    enabled?: boolean | null;
+    /** MANUAL | LACK_OF_USE */
+    disable_reason?: string | null;
+    expiration_date?: string | null;
+    /** A chave BaaS expira após 6 meses SEM USO; data projetada pelo Asaas. */
+    projected_expiration_by_lack_of_use?: string | null;
+    /** ACCESS_TOKEN_* */
+    last_event?: string | null;
+    last_event_at?: string | null;
+    rotated_at?: string | null;
+    /** loginId do staff. */
+    rotated_by?: string | null;
+}
 export interface IAsaasEnvAuthConfig {
     enabled: boolean;
     base_url?: string;
@@ -152,6 +229,14 @@ export interface IAsaasEnvAuthConfig {
     account_scope?: IAsaasAccountScope;
     account_status?: IAsaasAccountStatusSnapshot;
     onboarding?: IAsaasOnboardingSnapshot;
+    /** feat-275 — confirmação anual dos dados comerciais. */
+    commercial_info_expiration?: IAsaasCommercialInfoExpiration;
+    /** feat-275 — contato do titular (fallback de destinatário dos avisos de KYC). */
+    holder_contact?: IAsaasHolderContact;
+    /** feat-275 — dedup dos avisos de KYC. */
+    kyc_notifications?: IAsaasKycNotificationState;
+    /** feat-275 — estado da chave de API (nunca o valor). */
+    access_token_meta?: IAsaasAccessTokenMeta;
     subaccount_input?: IAsaasSubaccountInput;
     operational?: {
         rate_limit_max_per_minute?: number;

package/dist/types/evo-finops/providers/asaas/asaas_provider.ts

@@ -145,7 +145,17 @@ export type AsaasOnboardingSource =
   | "manual_refresh"
   | "webhook"
   | "provider_create"
-  | "scheduled_refresh";
+  | "scheduled_refresh"
+  /** feat-275 — rebusca de documentos disparada por webhook ACCOUNT_STATUS_*. */
+  | "webhook_refetch"
+  /** feat-275 — refresh inline no gate de emissão (subconta sem snapshot). */
+  | "gate_refresh"
+  /** feat-275 — upload de documento pela nossa tela. */
+  | "document_upload"
+  /** feat-275 — atualização/confirmação dos dados comerciais pela nossa tela. */
+  | "commercial_info_update"
+  /** feat-275 — troca/registro de chave de API da subconta. */
+  | "key_rotation";
 
 /** Próxima ação que o dono da conta precisa executar para destravar a subconta. */
 export type AsaasOnboardingNextAction =
@@ -153,9 +163,16 @@ export type AsaasOnboardingNextAction =
   | "rejected"
   | "awaiting_analysis"
   | "open_onboarding_link"
+  /** Legado: permanece para snapshots antigos; o mapper da feat-275 deixa de emiti-lo. */
   | "send_documents_external"
   | "fix_commercial_info"
   | "pending_bank_account"
+  /** feat-275 — grupo sem onboarding_url: upload pela nossa tela. */
+  | "upload_documents"
+  /** feat-275 — confirmação anual dos dados comerciais (EXPIRING_SOON / EXPIRED). */
+  | "confirm_commercial_info"
+  /** feat-275 — subconta recém-criada; o Asaas ainda não gerou os documentos. */
+  | "awaiting_link"
   | "unknown";
 
 /** Snapshot de GET /v3/myAccount/status. Sobrescrito inteiro a cada leitura/evento. */
@@ -185,6 +202,10 @@ export interface IAsaasOnboardingDocumentGroup {
   onboarding_url?: string | null;
   responsible?: { name?: string | null; type?: string | null };
   documents?: Array<{ id?: string; status?: string }>;
+  /** feat-275 — quando fizemos o último upload deste grupo (metadado; nunca o arquivo). */
+  last_upload_at?: string | null;
+  /** feat-275 — userId de quem fez o último upload. */
+  last_upload_by?: string | null;
 }
 
 /** Snapshot de GET /v3/myAccount/documents + próxima ação derivada. */
@@ -195,6 +216,79 @@ export interface IAsaasOnboardingSnapshot {
   next_action: AsaasOnboardingNextAction;
 }
 
+/**
+ * feat-275 — confirmação anual dos dados comerciais.
+ * Com `is_expired` o Asaas responde 403 em tudo, exceto GET/POST /myAccount/commercialInfo.
+ */
+export interface IAsaasCommercialInfoExpiration {
+  is_expired: boolean;
+  /** YYYY-MM-DD (`additionalInfo.scheduledDate` do evento EXPIRING_SOON). */
+  scheduled_date?: string | null;
+  updated_at: string;
+  source:
+    | "provider_create"
+    | "webhook"
+    | "commercial_info_fetch"
+    | "commercial_info_update";
+}
+
+/** feat-275 — contato de negócio do titular da subconta (LGPD: só nome, e-mail e celular). */
+export interface IAsaasHolderContact {
+  name?: string | null;
+  email?: string | null;
+  /** E.164 normalizado. */
+  mobile_phone?: string | null;
+  source: "provider_create" | "commercial_info";
+  updated_at: string;
+}
+
+/** feat-275 — gatilhos de aviso de KYC ao cliente. */
+export type AsaasKycNotificationTrigger =
+  | "link_available"
+  | "link_renewed"
+  | "rejected"
+  | "commercial_info_expiring"
+  | "commercial_info_expired";
+
+/** feat-275 — estado de dedup dos avisos de KYC. */
+export interface IAsaasKycNotificationState {
+  /** chave = `${trigger}:${scope}` (ex.: `link_available:3f9a...`); valor = quando foi publicado. */
+  sent?: Record<string, { at: string; trigger: AsaasKycNotificationTrigger }>;
+  /** sha256(url).slice(0,16) — nunca a URL. */
+  last_link_hash?: string | null;
+}
+
+/** feat-275 — estado da chave de API da subconta. */
+export type AsaasAccessTokenStatus =
+  | "active"
+  | "disabled"
+  | "expired"
+  | "deleted"
+  | "invalid"
+  | "unknown";
+
+/**
+ * feat-275 — metadado da chave de API (nunca o valor). Alimentado por eventos ACCESS_TOKEN_*
+ * e pela checagem diária (`GET /myAccount/status` com a chave da subconta).
+ */
+export interface IAsaasAccessTokenMeta {
+  asaas_access_token_id?: string | null;
+  name?: string | null;
+  status: AsaasAccessTokenStatus;
+  enabled?: boolean | null;
+  /** MANUAL | LACK_OF_USE */
+  disable_reason?: string | null;
+  expiration_date?: string | null;
+  /** A chave BaaS expira após 6 meses SEM USO; data projetada pelo Asaas. */
+  projected_expiration_by_lack_of_use?: string | null;
+  /** ACCESS_TOKEN_* */
+  last_event?: string | null;
+  last_event_at?: string | null;
+  rotated_at?: string | null;
+  /** loginId do staff. */
+  rotated_by?: string | null;
+}
+
 export interface IAsaasEnvAuthConfig {
   enabled: boolean;
 
@@ -218,6 +312,18 @@ export interface IAsaasEnvAuthConfig {
   // Documentos pendentes e próxima ação de ativação.
   onboarding?: IAsaasOnboardingSnapshot;
 
+  /** feat-275 — confirmação anual dos dados comerciais. */
+  commercial_info_expiration?: IAsaasCommercialInfoExpiration;
+
+  /** feat-275 — contato do titular (fallback de destinatário dos avisos de KYC). */
+  holder_contact?: IAsaasHolderContact;
+
+  /** feat-275 — dedup dos avisos de KYC. */
+  kyc_notifications?: IAsaasKycNotificationState;
+
+  /** feat-275 — estado da chave de API (nunca o valor). */
+  access_token_meta?: IAsaasAccessTokenMeta;
+
   // Input data used only when creating subaccounts (not persisted).
   subaccount_input?: IAsaasSubaccountInput;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.697",
+  "version": "1.3.699",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",