@fayz-ai/plugin-banking-br 0.9.1 → 0.10.1

package/README.md

@@ -23,13 +23,36 @@ Addon scope: it contributes a connector into its host (`plugin-financial`) and
 surfaces under **Financial → settings → Integrations**. No left-nav entry of its own.
 
 ## What it owns
-- **DB**: `public.bank_integrations` (connection + credentials) and
-  `public.bank_integration_sync_log` (run audit). See `src/schema/` + `src/migrations/`.
-- **Edge function** (deployed by the app): `supabase/functions/plugbank-sync` — calls
-  the PlugBank API, normalizes lines, imports into `public.plg_financial_movements`
-  tagged `external_source='plugbank'` (idempotent via the financial
-  `uq_financial_movements_external` index).
-- **UI**: connect/test/save, fetch a statement, import selected lines, view history.
+- **DB**: none of its own — the connection is a `plg_connections` row and the
+  history is `plg_sync_runs` (migration `003_onto_connections`). The legacy
+  `bank_integrations` / `bank_integration_sync_log` tables still stand on the
+  live pool (with a plaintext `api_token`) until FAY-1360 retires them.
+- **RPC**: `plugbank_import_movements(p_payload jsonb)` — the door the import
+  passes through. Takes the tenant from the integration row, never from the
+  request body, and is idempotent on the financial plugin's
+  `uq_plg_financial_movements_external` index.
+- **Edge function** (declared in `functions[]`, deployed by the app):
+  `plugbank-sync` — calls the PlugBank API, normalizes lines, imports through the
+  RPC into `public.plg_financial_movements` tagged `external_source='plugbank'`.
+- **Fact**: `financial.movement.imported`, emitted by a trigger on the ledger so
+  it exists whoever wrote the row.
+- **UI**: connect/disconnect, fetch a statement, import selected lines, run history.
+
+## Where the credential lives
+
+**Today (verified 2026-08-12): still in the pool.** The live pool's
+`bank_integrations.api_token` holds the PlugBank token in plaintext — migration
+`002`, which drops the `api_token` / `cnpj` columns `001` created, is in this
+repo but unapplied there, and the deployed `plugbank-sync` (v6) still reads the
+column. The destination is the Fayz platform's encrypted store, redeemed by the
+edge function per call — that move is FAY-1360, and the redeem path it needs is
+FAY-1389. The reason the columns must go: `bank_integrations` is read from the
+browser under tenant RLS, so any member of the tenant can read them — and a pool
+is one Supabase project serving N tenants, so anything there holding
+`service_role` reads every tenant's at once.
+
+If a pool ever stored those values, **rotate them**. `DROP COLUMN` is a catalog
+change; the old bytes leave the heap only at the next table rewrite.
 
 ## How it composes with the SDK
 - Depends on `@fayz-ai/plugin-financial`. Imported lines are reconciled in
@@ -39,11 +62,16 @@ surfaces under **Financial → settings → Integrations**. No left-nav entry of
   `matched_movement_id`) live in the SDK financial migration `007_reconciliation.sql`.
 
 ## Deploy
-1. Apply the SDK financial migration `007_reconciliation.sql` and this plugin's
-   `src/migrations/001_openbanking.sql`.
+1. Apply the SDK financial migration `007_reconciliation.sql`, the core
+   `027_domain_events.sql` (it ships `plg_emit_event`), then this plugin's
+   `001_openbanking.sql` and `002_credential_and_facts.sql`.
 2. `supabase functions deploy plugbank-sync` with secrets
    `PLUGBANK_BASE_URL`, plus the standard `SUPABASE_URL` / `SUPABASE_SERVICE_ROLE_KEY`.
+   The per-tenant token is **not** a function secret: a secret is per-pool and a
+   pool serves N tenants with N different bank accounts.
 3. Register `createOpenBankingPlugin()` in the app config and enable the
    financial `reconciliation` module.
-4. (Optional, "runs in backend") schedule a daily `import_transactions` via
-   `pg_cron` + `pg_net` to the function for hands-off sync.
+
+The period picker in the import panel is deliberate, not a missing feature —
+whoever reconciles wants to choose the window. Scheduled pulls belong to the Fayz
+SCHEDULE worker (FAY-1347), which owns the clock for every connector.

package/dist/connectors/connectorDef.d.ts

@@ -1,3 +1,3 @@
-import type { ConnectorDefinition } from '@fayz-ai/core';
+import { type ConnectorDefinition } from '@fayz-ai/core';
 export declare const openBankingConnector: ConnectorDefinition;
 //# sourceMappingURL=connectorDef.d.ts.map

package/dist/connectors/connectorDef.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connectorDef.d.ts","sourceRoot":"","sources":["../../src/connectors/connectorDef.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAoHxD,eAAO,MAAM,oBAAoB,EAAE,mBAkBlC,CAAA"}
+{"version":3,"file":"connectorDef.d.ts","sourceRoot":"","sources":["../../src/connectors/connectorDef.tsx"],"names":[],"mappings":"AAgBA,OAAO,EAA2C,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAiIjG,eAAO,MAAM,oBAAoB,EAAE,mBAsGlC,CAAA"}

package/dist/data/supabase.d.ts

@@ -1,12 +1,18 @@
-import type { BankIntegration, SaveIntegrationInput, SyncLogEntry, TestConnectionResult, FetchStatementResult, ImportResult, BankLine } from '../types';
+import type { ConnectionConfig, SyncRun } from '@fayz-ai/core';
+import type { BankIntegration, SaveIntegrationInput, BankSyncRun, FetchStatementResult, ImportResult, BankLine } from '../types';
+export declare const PLUGBANK_CONNECTOR_ID = "plugbank";
+export declare function toIntegration(connection: ConnectionConfig): BankIntegration;
+/**
+ * The audit row, read as the connector contract's SyncRun. The three facts a
+ * MANUAL statement import has and a generic run does not — the period the
+ * operator picked, and the duplicates a re-import of that period produces by
+ * design — live in `stats`, which is the column that exists for exactly this.
+ */
+export declare function toSyncRun(run: SyncRun): BankSyncRun;
 export interface OpenBankingProvider {
     getIntegration(bankAccountId?: string): Promise<BankIntegration | null>;
-    saveIntegration(input: SaveIntegrationInput): Promise<BankIntegration>;
-    testConnection(input: {
-        apiToken: string;
-        cnpj: string;
-        environment?: string;
-    }): Promise<TestConnectionResult>;
+    saveIntegration(input?: SaveIntegrationInput): Promise<BankIntegration>;
+    disconnect(bankAccountId?: string): Promise<void>;
     fetchStatement(input: {
         integrationId: string;
         from: string;
@@ -19,7 +25,7 @@ export interface OpenBankingProvider {
         to: string;
         lines: BankLine[];
     }): Promise<ImportResult>;
-    getSyncLog(integrationId: string): Promise<SyncLogEntry[]>;
+    getSyncRuns(bankAccountId?: string): Promise<BankSyncRun[]>;
 }
 export declare function createOpenBankingProvider(): OpenBankingProvider;
 //# sourceMappingURL=supabase.d.ts.map

package/dist/data/supabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/data/supabase.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,eAAe,EAAE,oBAAoB,EAAE,YAAY,EACnD,oBAAoB,EAAE,oBAAoB,EAAE,YAAY,EAAE,QAAQ,EACnE,MAAM,UAAU,CAAA;AAuBjB,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IACvE,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACtE,cAAc,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAC9G,cAAc,CAAC,KAAK,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACzG,kBAAkB,CAAC,KAAK,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAChJ,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;CAC3D;AAED,wBAAgB,yBAAyB,IAAI,mBAAmB,CAwF/D"}
+{"version":3,"file":"supabase.d.ts","sourceRoot":"","sources":["../../src/data/supabase.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,gBAAgB,EAAmB,OAAO,EAAE,MAAM,eAAe,CAAA;AAC/E,OAAO,KAAK,EACV,eAAe,EAAE,oBAAoB,EAAE,WAAW,EAClD,oBAAoB,EAAE,YAAY,EAAE,QAAQ,EAC7C,MAAM,UAAU,CAAA;AAIjB,eAAO,MAAM,qBAAqB,aAAa,CAAA;AAwB/C,wBAAgB,aAAa,CAAC,UAAU,EAAE,gBAAgB,GAAG,eAAe,CAW3E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAuBnD;AAED,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAA;IACvE,eAAe,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACvE,UAAU,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,cAAc,CAAC,KAAK,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACzG,kBAAkB,CAAC,KAAK,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAChJ,WAAW,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;CAC5D;AAED,wBAAgB,yBAAyB,IAAI,mBAAmB,CA2D/D"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { PluginManifest } from '@fayz-ai/core';
 export { createOpenBankingProvider } from './data/supabase';
 export { openBankingConnector } from './connectors/connectorDef';
+export { buildBankingDomainEvents, MOVEMENT_IMPORTED_FIELDS } from './lib/banking-events';
 export * from './schema';
 export * from './types';
 export declare function createOpenBankingPlugin(): PluginManifest;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAGnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AAKvB,wBAAgB,uBAAuB,IAAI,cAAc,CAaxD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAKnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAA;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA;AACzF,cAAc,UAAU,CAAA;AACxB,cAAc,SAAS,CAAA;AAKvB,wBAAgB,uBAAuB,IAAI,cAAc,CAqFxD"}