@fayz-ai/plugin-financial 0.24.6 → 0.25.0

package/dist/index.js

@@ -44899,6 +44899,261 @@ END $$;
 REVOKE ALL ON FUNCTION public.financial_set_invoice_lines(uuid, jsonb, boolean) FROM PUBLIC, anon;
 GRANT EXECUTE ON FUNCTION public.financial_set_invoice_lines(uuid, jsonb, boolean) TO authenticated, service_role;
 `;
+var MIGRATION_136_A_BANK_STATEMENT_ARRIVES_FROM_THE_SERVICE = `-- ============================================================================
+-- 136 \u2014 a bank statement arrives from the integration service
+--
+-- The V2 sink of the banking module (ADR 0003): the doors through which the
+-- integration service hands this product the lines of a store's bank or
+-- credit-card statement, withdraws the ones the bank took back, reports the
+-- connection's state, and reads which lines are already here. The provider
+-- calls, the schedule and the waiting are the service's; what a line IS here
+-- is decided here.
+--
+-- A line is keyed as before: (tenant, external_source, external_id), where
+-- external_source is the statement source's provider ('openbanking:pagbank')
+-- and external_id the provider's transaction id. Lines already brought in by
+-- the V1 migration match the ones the service brings, so nothing doubles.
+--
+-- Providers revise statements for days: an Open Finance bank can drop a
+-- transaction and bring it back under a new id. A withdrawn line is marked
+-- (provider_deleted), never deleted, and comes back if the provider brings
+-- the same id again. A line already reconciled keeps its money and its date:
+-- a revision of either is recorded beside it, for a person to look at.
+--
+-- No person is behind these calls; the actor is the service, acting for the
+-- tenant it names. The functions are closed to every signed-in user and
+-- opened only to the service's role, \`fayz_integration\`, when it exists.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.financial_statement_source_get(p_tenant uuid, p_source uuid)
+RETURNS jsonb
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path TO ''
+AS $$
+  SELECT jsonb_build_object(
+    'id', s.id, 'tenantId', s.tenant_id, 'unitId', s.unit_id, 'accountId', s.account_id,
+    'provider', s.provider, 'kind', s.statement_kind, 'cardLast4', s.card_last4,
+    'accountRef', s.provider_account_hash, 'active', s.is_active,
+    'lastSyncedAt', s.last_synced_at, 'lastSyncStatus', s.last_sync_status
+  )
+  FROM public.plg_financial_account_statement_sources s
+  WHERE s.id = p_source AND s.tenant_id = p_tenant
+$$;
+
+-- Every source tied to a provider account, across tenants: how the service
+-- finds the connections the V1 migration left, to adopt them.
+CREATE OR REPLACE FUNCTION public.financial_statement_sources_linked(p_provider_prefix text)
+RETURNS SETOF jsonb
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path TO ''
+AS $$
+  SELECT jsonb_build_object(
+    'id', s.id, 'tenantId', s.tenant_id, 'unitId', s.unit_id, 'accountId', s.account_id,
+    'provider', s.provider, 'kind', s.statement_kind, 'cardLast4', s.card_last4,
+    'accountRef', s.provider_account_hash, 'active', s.is_active
+  )
+  FROM public.plg_financial_account_statement_sources s
+  WHERE s.provider LIKE p_provider_prefix || '%' AND s.provider_account_hash IS NOT NULL
+  ORDER BY s.tenant_id, s.created_at
+$$;
+
+-- Ties a source to the provider's account, once the store has authorized it.
+CREATE OR REPLACE FUNCTION public.financial_statement_source_link(p_tenant uuid, p_source uuid, p_account_ref text)
+RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path TO ''
+AS $$
+BEGIN
+  IF p_account_ref IS NULL OR btrim(p_account_ref) = '' THEN
+    RAISE EXCEPTION 'financial_statement_source_link: account ref is required' USING ERRCODE = '22023';
+  END IF;
+  UPDATE public.plg_financial_account_statement_sources
+     SET provider_account_hash = btrim(p_account_ref), updated_at = now()
+   WHERE id = p_source AND tenant_id = p_tenant;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'financial_statement_source_link: source % is not of tenant %', p_source, p_tenant USING ERRCODE = 'P0002';
+  END IF;
+END
+$$;
+
+CREATE OR REPLACE FUNCTION public.financial_statement_lines_ingest(p_tenant uuid, p_source uuid, p_lines jsonb)
+RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path TO ''
+AS $$
+DECLARE
+  v_source   public.plg_financial_account_statement_sources%ROWTYPE;
+  v_line     jsonb;
+  v_amount   numeric;
+  v_day      date;
+  v_method   text;
+  v_meta     jsonb;
+  v_existing public.plg_financial_bank_statement_lines%ROWTYPE;
+  v_inserted integer := 0;
+  v_updated  integer := 0;
+BEGIN
+  SELECT * INTO v_source FROM public.plg_financial_account_statement_sources
+   WHERE id = p_source AND tenant_id = p_tenant;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'financial_statement_lines_ingest: source % is not of tenant %', p_source, p_tenant USING ERRCODE = 'P0002';
+  END IF;
+  IF jsonb_typeof(p_lines) <> 'array' THEN
+    RAISE EXCEPTION 'financial_statement_lines_ingest: lines must be an array' USING ERRCODE = '22023';
+  END IF;
+
+  FOR v_line IN SELECT value FROM jsonb_array_elements(p_lines) LOOP
+    IF coalesce(v_line ->> 'externalId', '') = '' OR (v_line ->> 'direction') NOT IN ('credit', 'debit') THEN
+      RAISE EXCEPTION 'financial_statement_lines_ingest: a line needs externalId and direction' USING ERRCODE = '22023';
+    END IF;
+    v_amount := round((v_line ->> 'amountCents')::numeric / 100, 2);
+    v_day := (v_line ->> 'postedOn')::date;
+    IF v_amount IS NULL OR v_amount < 0 OR v_day IS NULL THEN
+      RAISE EXCEPTION 'financial_statement_lines_ingest: line % needs a positive amount and a day', v_line ->> 'externalId' USING ERRCODE = '22023';
+    END IF;
+    v_method := nullif(v_line ->> 'paymentMethod', '');
+    v_meta := jsonb_strip_nulls(jsonb_build_object(
+      'statement', jsonb_build_object('ref', v_line ->> 'statementRef', 'via', 'integration-service'),
+      'paymentMethod', v_method,
+      'currency', coalesce(v_line ->> 'currency', 'BRL'),
+      'boleto', v_line -> 'boleto',
+      'card', v_line -> 'card'
+    ));
+
+    SELECT * INTO v_existing FROM public.plg_financial_bank_statement_lines
+     WHERE tenant_id = p_tenant AND external_source = v_source.provider AND external_id = v_line ->> 'externalId';
+
+    IF NOT FOUND THEN
+      INSERT INTO public.plg_financial_bank_statement_lines (
+        tenant_id, unit_id, bank_account_id, external_source, external_id, posted_on, direction, amount,
+        description, counterparty_name, counterparty_document, document, code, category, transaction_type,
+        provider_deleted, raw_payload, metadata
+      ) VALUES (
+        p_tenant, v_source.unit_id, v_source.account_id, v_source.provider, v_line ->> 'externalId', v_day,
+        v_line ->> 'direction', v_amount,
+        nullif(v_line ->> 'description', ''), nullif(v_line #>> '{counterparty,name}', ''),
+        nullif(v_line #>> '{counterparty,document}', ''), nullif(v_line ->> 'reference', ''),
+        nullif(v_line ->> 'code', ''), nullif(v_line ->> 'category', ''),
+        coalesce(v_method, upper(v_line ->> 'direction')),
+        false, coalesce(v_line -> 'raw', '{}'::jsonb), v_meta
+      );
+      v_inserted := v_inserted + 1;
+    ELSE
+      UPDATE public.plg_financial_bank_statement_lines l SET
+        -- Money, day and direction move only while nobody has reconciled the line.
+        posted_on = CASE WHEN l.reconciled_at IS NULL THEN v_day ELSE l.posted_on END,
+        amount    = CASE WHEN l.reconciled_at IS NULL THEN v_amount ELSE l.amount END,
+        direction = CASE WHEN l.reconciled_at IS NULL THEN v_line ->> 'direction' ELSE l.direction END,
+        description = coalesce(nullif(v_line ->> 'description', ''), l.description),
+        counterparty_name = coalesce(nullif(v_line #>> '{counterparty,name}', ''), l.counterparty_name),
+        counterparty_document = coalesce(nullif(v_line #>> '{counterparty,document}', ''), l.counterparty_document),
+        document = coalesce(nullif(v_line ->> 'reference', ''), l.document),
+        code = coalesce(nullif(v_line ->> 'code', ''), l.code),
+        category = coalesce(nullif(v_line ->> 'category', ''), l.category),
+        transaction_type = coalesce(v_method, l.transaction_type),
+        provider_deleted = false,
+        raw_payload = coalesce(v_line -> 'raw', l.raw_payload),
+        metadata = (l.metadata - 'withdrawn') || v_meta
+          || CASE WHEN l.reconciled_at IS NOT NULL AND (l.amount <> v_amount OR l.posted_on <> v_day OR l.direction <> v_line ->> 'direction')
+               THEN jsonb_build_object('revisedAfterReconciliation', jsonb_build_object(
+                 'amount', v_amount, 'postedOn', v_day, 'direction', v_line ->> 'direction', 'at', now()))
+               ELSE '{}'::jsonb END,
+        updated_at = now()
+      WHERE l.id = v_existing.id;
+      v_updated := v_updated + 1;
+    END IF;
+  END LOOP;
+
+  RETURN jsonb_build_object('inserted', v_inserted, 'updated', v_updated);
+END
+$$;
+
+CREATE OR REPLACE FUNCTION public.financial_statement_lines_withdraw(p_tenant uuid, p_source uuid, p_external_ids text[], p_reason text)
+RETURNS integer
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path TO ''
+AS $$
+DECLARE
+  v_source public.plg_financial_account_statement_sources%ROWTYPE;
+  v_count  integer;
+BEGIN
+  SELECT * INTO v_source FROM public.plg_financial_account_statement_sources
+   WHERE id = p_source AND tenant_id = p_tenant;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'financial_statement_lines_withdraw: source % is not of tenant %', p_source, p_tenant USING ERRCODE = 'P0002';
+  END IF;
+  UPDATE public.plg_financial_bank_statement_lines l
+     SET provider_deleted = true,
+         metadata = l.metadata || jsonb_build_object('withdrawn', jsonb_build_object('reason', p_reason, 'at', now())),
+         updated_at = now()
+   WHERE l.tenant_id = p_tenant AND l.external_source = v_source.provider
+     AND l.bank_account_id = v_source.account_id
+     AND l.external_id = ANY (p_external_ids) AND NOT l.provider_deleted;
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END
+$$;
+
+-- The lines here for a source in a window, withdrawn ones left out: what the
+-- service compares with the provider to find the ones the bank took back.
+CREATE OR REPLACE FUNCTION public.financial_statement_lines_known(p_tenant uuid, p_source uuid, p_from date, p_to date)
+RETURNS SETOF text
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path TO ''
+AS $$
+  SELECT l.external_id
+    FROM public.plg_financial_bank_statement_lines l
+    JOIN public.plg_financial_account_statement_sources s
+      ON s.id = p_source AND s.tenant_id = p_tenant
+   WHERE l.tenant_id = p_tenant AND l.external_source = s.provider AND l.bank_account_id = s.account_id
+     AND l.posted_on BETWEEN p_from AND p_to AND NOT l.provider_deleted
+$$;
+
+CREATE OR REPLACE FUNCTION public.financial_statement_source_report(
+  p_tenant uuid, p_source uuid, p_status text, p_error text, p_details jsonb
+) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path TO ''
+AS $$
+BEGIN
+  IF p_status NOT IN ('ok', 'error', 'pending', 'revoked') THEN
+    RAISE EXCEPTION 'financial_statement_source_report: unknown status %', p_status USING ERRCODE = '22023';
+  END IF;
+  UPDATE public.plg_financial_account_statement_sources s
+     SET last_sync_status = p_status,
+         last_sync_error = CASE WHEN p_status = 'error' THEN left(p_error, 500) ELSE NULL END,
+         last_synced_at = CASE WHEN p_status = 'ok' THEN now() ELSE s.last_synced_at END,
+         metadata = s.metadata || jsonb_build_object('connection', coalesce(p_details, '{}'::jsonb)),
+         updated_at = now()
+   WHERE s.id = p_source AND s.tenant_id = p_tenant;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'financial_statement_source_report: source % is not of tenant %', p_source, p_tenant USING ERRCODE = 'P0002';
+  END IF;
+END
+$$;
+
+REVOKE ALL ON FUNCTION public.financial_statement_source_get(uuid, uuid) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.financial_statement_sources_linked(text) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.financial_statement_source_link(uuid, uuid, text) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.financial_statement_lines_ingest(uuid, uuid, jsonb) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.financial_statement_lines_withdraw(uuid, uuid, text[], text) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.financial_statement_lines_known(uuid, uuid, date, date) FROM PUBLIC, anon, authenticated;
+REVOKE ALL ON FUNCTION public.financial_statement_source_report(uuid, uuid, text, text, jsonb) FROM PUBLIC, anon, authenticated;
+
+DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'fayz_integration') THEN
+    GRANT USAGE ON SCHEMA public TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_source_get(uuid, uuid) TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_sources_linked(text) TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_source_link(uuid, uuid, text) TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_lines_ingest(uuid, uuid, jsonb) TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_lines_withdraw(uuid, uuid, text[], text) TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_lines_known(uuid, uuid, date, date) TO fayz_integration;
+    GRANT EXECUTE ON FUNCTION public.financial_statement_source_report(uuid, uuid, text, text, jsonb) TO fayz_integration;
+  END IF;
+END
+$$;
+`;
 var MIGRATIONS = [
   { id: "000_baseline", sql: MIGRATION_000_BASELINE },
   { id: "001_the_comanda_becomes_a_receivable_when_it_closes", sql: MIGRATION_001_THE_COMANDA_BECOMES_A_RECEIVABLE_WHEN_IT_CLOSES },
@@ -45035,7 +45290,8 @@ var MIGRATIONS = [
   { id: "132_the_statement_source_knows_its_provider_account", sql: MIGRATION_132_THE_STATEMENT_SOURCE_KNOWS_ITS_PROVIDER_ACCOUNT },
   { id: "133_reversing_a_payment_releases_its_bank_line", sql: MIGRATION_133_REVERSING_A_PAYMENT_RELEASES_ITS_BANK_LINE },
   { id: "134_a_bill_knows_who_filed_it", sql: MIGRATION_134_A_BILL_KNOWS_WHO_FILED_IT },
-  { id: "135_a_bill_and_its_lines_are_written_together", sql: MIGRATION_135_A_BILL_AND_ITS_LINES_ARE_WRITTEN_TOGETHER }
+  { id: "135_a_bill_and_its_lines_are_written_together", sql: MIGRATION_135_A_BILL_AND_ITS_LINES_ARE_WRITTEN_TOGETHER },
+  { id: "136_a_bank_statement_arrives_from_the_service", sql: MIGRATION_136_A_BANK_STATEMENT_ARRIVES_FROM_THE_SERVICE }
 ];
 var ACQUIRERS = ["stone", "cielo", "pagbank", "mercadopago"];
 var LOGOS = "https://assets.fayz.ai/connectors";