@noeva/etl-core 1.0.0-next.4 → 1.0.0-next.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/README.md +2 -1
  2. package/dist/chunk-BVUOUBLW.js +1 -0
  3. package/dist/chunk-CRR3Q2C7.js +2 -0
  4. package/dist/chunk-J3PBMWSP.js +2 -0
  5. package/dist/{chunk-KMUNED7K.js → chunk-LJ7DVP5F.js} +1 -1
  6. package/dist/{chunk-ZBKP2UOF.js → chunk-P6B2KLNJ.js} +2 -2
  7. package/dist/chunk-PKBSETMV.js +2 -0
  8. package/dist/chunk-QPJC4GWR.js +1 -0
  9. package/dist/chunk-RCRMQPFH.js +5 -0
  10. package/dist/chunk-RS5SGDUU.js +1 -0
  11. package/dist/chunk-RWPHH4E2.js +1 -0
  12. package/dist/chunk-SRFFKE5W.js +6 -0
  13. package/dist/chunk-WVODQB6Z.js +1 -0
  14. package/dist/chunk-XZMCC6VQ.js +1 -0
  15. package/dist/chunk-ZCYGHS7P.js +2 -0
  16. package/dist/cli.js +2 -2
  17. package/dist/connector-kit.d.ts +4 -2
  18. package/dist/connector-kit.js +1 -1
  19. package/dist/connectors/file.js +1 -1
  20. package/dist/connectors/http.js +1 -1
  21. package/dist/connectors/imap.js +1 -1
  22. package/dist/connectors/jira.js +2 -2
  23. package/dist/connectors/mail.js +1 -1
  24. package/dist/connectors/noeva.js +1 -1
  25. package/dist/connectors/oauth.js +1 -1
  26. package/dist/connectors/postgres.js +1 -1
  27. package/dist/connectors/sendgrid.js +1 -1
  28. package/dist/connectors/smtp.js +1 -1
  29. package/dist/connectors/sqlserver.js +1 -1
  30. package/dist/connectors/zoho.d.ts +304 -0
  31. package/dist/connectors/zoho.js +2 -0
  32. package/dist/etl.config.js +2 -2
  33. package/dist/guida/404.html +2 -2
  34. package/dist/guida/GUIDA_SVILUPPO.html +6 -6
  35. package/dist/guida/TECHNICAL_OVERVIEW.html +5 -5
  36. package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.js → GUIDA_SVILUPPO.md.CrN52ZDN.js} +1 -1
  37. package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.js → TECHNICAL_OVERVIEW.md.iD1gDlJY.js} +1 -1
  38. package/dist/guida/assets/{app.CzIZwOrR.js → app.BrI3mcoI.js} +1 -1
  39. package/dist/guida/assets/chunks/@localSearchIndexroot.DjrQYH6x.js +1 -0
  40. package/dist/guida/assets/chunks/{VPLocalSearchBox.Cv9o56BQ.js → VPLocalSearchBox.BlKLVNlB.js} +1 -1
  41. package/dist/guida/assets/chunks/{theme.CsUxYN72.js → theme.Cuah39Zj.js} +2 -2
  42. package/dist/guida/assets/connectors_README.md.BqI2RLCu.js +1 -0
  43. package/dist/guida/assets/connectors_README.md.BqI2RLCu.lean.js +1 -0
  44. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.js +7 -0
  45. package/dist/guida/assets/connectors_oauth.md.BeotXAWb.lean.js +1 -0
  46. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.js +17 -0
  47. package/dist/guida/assets/connectors_zoho.md.BfEzRNZk.lean.js +1 -0
  48. package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.js → conventions_node-descriptor.md.MQaGlm8a.js} +1 -1
  49. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.js → nodes_source.md.DP2i3GFv.js} +3 -3
  50. package/dist/guida/assets/{nodes_source.md.V_vlNfOz.lean.js → nodes_source.md.DP2i3GFv.lean.js} +1 -1
  51. package/dist/guida/connectors/README.html +5 -5
  52. package/dist/guida/connectors/file.html +4 -4
  53. package/dist/guida/connectors/http.html +4 -4
  54. package/dist/guida/connectors/imap.html +4 -4
  55. package/dist/guida/connectors/jira.html +4 -4
  56. package/dist/guida/connectors/noeva.html +5 -5
  57. package/dist/guida/connectors/oauth.html +6 -6
  58. package/dist/guida/connectors/postgres.html +5 -5
  59. package/dist/guida/connectors/process.html +4 -4
  60. package/dist/guida/connectors/sendgrid.html +4 -4
  61. package/dist/guida/connectors/smtp.html +4 -4
  62. package/dist/guida/connectors/sqlserver.html +5 -5
  63. package/dist/guida/connectors/zoho.html +43 -0
  64. package/dist/guida/conventions/node-columns.html +4 -4
  65. package/dist/guida/conventions/node-descriptor.html +6 -6
  66. package/dist/guida/conventions/run-report.html +4 -4
  67. package/dist/guida/conventions/run-trace.html +4 -4
  68. package/dist/guida/conventions/variabili-del-core.html +4 -4
  69. package/dist/guida/conventions/versioni-di-pipeline.html +4 -4
  70. package/dist/guida/guide/claude-code/index.html +4 -4
  71. package/dist/guida/guide/claude-code/prompt.html +5 -5
  72. package/dist/guida/guide/claude-code/strumenti.html +4 -4
  73. package/dist/guida/guide/grafo.html +4 -4
  74. package/dist/guida/guide/usare/app-desktop.html +4 -4
  75. package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
  76. package/dist/guida/guide/usare/index.html +4 -4
  77. package/dist/guida/hashmap.json +1 -1
  78. package/dist/guida/index.html +4 -4
  79. package/dist/guida/nodes/README.html +4 -4
  80. package/dist/guida/nodes/action.html +4 -4
  81. package/dist/guida/nodes/ai.html +4 -4
  82. package/dist/guida/nodes/join.html +4 -4
  83. package/dist/guida/nodes/lookup.html +4 -4
  84. package/dist/guida/nodes/pipeline.html +4 -4
  85. package/dist/guida/nodes/route.html +4 -4
  86. package/dist/guida/nodes/sink.html +4 -4
  87. package/dist/guida/nodes/source.html +6 -6
  88. package/dist/guida/nodes/task.html +4 -4
  89. package/dist/guida/nodes/transform.html +4 -4
  90. package/dist/guida/nodes/try-catch.html +4 -4
  91. package/dist/guida/nodes/union.html +4 -4
  92. package/dist/guida/pagine.json +1 -0
  93. package/dist/guida/pipelines/README.html +5 -5
  94. package/dist/guida/pipelines/crm-leads-sync.html +4 -4
  95. package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
  96. package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
  97. package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
  98. package/dist/guida/pipelines/test-posta.html +4 -4
  99. package/dist/guida/runbooks/aggiornamento-pm2.html +4 -4
  100. package/dist/guida/runbooks/deploy-ecr.html +4 -4
  101. package/dist/guida/runbooks/deployment.html +4 -4
  102. package/dist/guida/runbooks/etl-worker.html +4 -4
  103. package/dist/guida/runbooks/graph-server.html +4 -4
  104. package/dist/guida/runbooks/mask-key.html +4 -4
  105. package/dist/guida/runbooks/oauth-google-posta.html +4 -4
  106. package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
  107. package/dist/guida/runbooks/scd2-rehash.html +4 -4
  108. package/dist/guida/runbooks/sql-task-truncate-swap.html +4 -4
  109. package/dist/guida/runbooks/stato-incrementale.html +4 -4
  110. package/dist/guida/sub-pipelines/README.html +4 -4
  111. package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
  112. package/dist/index.js +1 -1
  113. package/dist/pipelines.js +1 -1
  114. package/dist/testing.js +1 -1
  115. package/kit/skills/etl-graph/references/wiring.md +4 -3
  116. package/kit/skills/new-connector/SKILL.md +1 -1
  117. package/package.json +8 -3
  118. package/dist/chunk-BFW7HTF6.js +0 -2
  119. package/dist/chunk-BPRH262Y.js +0 -2
  120. package/dist/chunk-DPWGI266.js +0 -1
  121. package/dist/chunk-H75NY6Z4.js +0 -1
  122. package/dist/chunk-HMED2UDJ.js +0 -2
  123. package/dist/chunk-MOHJWOCB.js +0 -1
  124. package/dist/chunk-MXSKD3Z4.js +0 -2
  125. package/dist/chunk-PGJWGJEB.js +0 -5
  126. package/dist/chunk-R53642SH.js +0 -1
  127. package/dist/chunk-RU6CZIDB.js +0 -1
  128. package/dist/chunk-UN3BPCPA.js +0 -1
  129. package/dist/chunk-XFHTODDW.js +0 -6
  130. package/dist/guida/assets/chunks/@localSearchIndexroot.08YFQ5n8.js +0 -1
  131. package/dist/guida/assets/connectors_README.md.ChyXSf73.js +0 -1
  132. package/dist/guida/assets/connectors_README.md.ChyXSf73.lean.js +0 -1
  133. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.js +0 -7
  134. package/dist/guida/assets/connectors_oauth.md.DUHajB0u.lean.js +0 -1
  135. /package/dist/guida/assets/{GUIDA_SVILUPPO.md.D13C7Zwu.lean.js → GUIDA_SVILUPPO.md.CrN52ZDN.lean.js} +0 -0
  136. /package/dist/guida/assets/{TECHNICAL_OVERVIEW.md.DQP0pWc8.lean.js → TECHNICAL_OVERVIEW.md.iD1gDlJY.lean.js} +0 -0
  137. /package/dist/guida/assets/{conventions_node-descriptor.md.D8Si7E2S.lean.js → conventions_node-descriptor.md.MQaGlm8a.lean.js} +0 -0
@@ -1 +0,0 @@
1
- import{_ as o,o as t,c as d,a5 as a}from"./chunks/framework.qdetmeNX.js";const g=JSON.parse('{"title":"Connettori","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/README.md","filePath":"connectors/README.md"}'),r={name:"connectors/README.md"};function i(n,e,c,s,l,p){return t(),d("div",null,[...e[0]||(e[0]=[a('<h1 id="connettori" tabindex="-1">Connettori <a class="header-anchor" href="#connettori" aria-label="Permalink to &quot;Connettori&quot;">​</a></h1><p>I connettori sono le implementazioni reali di <code>Source</code> (estrazione) e <code>Sink</code> (caricamento) verso sistemi esterni. Vivono in <code>src/connectors/&lt;sistema&gt;/</code> e si <strong>iniettano</strong> nelle pipeline (mai istanziati dentro la definizione).</p><h2 id="indice" tabindex="-1">Indice <a class="header-anchor" href="#indice" aria-label="Permalink to &quot;Indice&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Connettore</th><th>Source</th><th>Sink</th><th>Doc</th></tr></thead><tbody><tr><td>PostgreSQL</td><td>✅ streaming (cursor)</td><td>✅ upsert idempotente (ON CONFLICT), o <a href="./postgres#scd2">SCD2</a></td><td><a href="./postgres">postgres.md</a></td></tr><tr><td>SQL Server</td><td>✅ streaming (pause/resume)</td><td>✅ upsert idempotente (MERGE), o <a href="./sqlserver#scd2">SCD2</a></td><td><a href="./sqlserver">sqlserver.md</a></td></tr><tr><td>File (storage × codec)</td><td>✅ <code>fileSource</code></td><td>✅ <code>fileSink</code></td><td><a href="./file">file.md</a></td></tr><tr><td>— storage: filesystem · <strong>S3</strong> · <strong>SFTP</strong> · <strong>FTP/FTPS</strong> · memory</td><td>(vedi file.md)</td><td>(vedi file.md)</td><td><a href="./file">file.md</a></td></tr><tr><td>— codec: <strong>CSV</strong> (anche grezzo) · <strong>JSON/NDJSON</strong> · <strong>XML</strong> · <strong>XLSX</strong> · <strong>Parquet</strong></td><td>(vedi file.md)</td><td>(vedi file.md)</td><td><a href="./file">file.md</a></td></tr><tr><td>Noeva (file dei workspace)</td><td>✅ file singolo · cartella</td><td>✅ file singolo · multi-file, <code>overwrite</code>/<code>new-version</code></td><td><a href="./noeva">noeva.md</a></td></tr><tr><td>IMAP (caselle di posta)</td><td>✅ messaggi di una cartella</td><td>— (action: flag, spostamento)</td><td><a href="./imap">imap.md</a></td></tr><tr><td>SMTP (notifiche email)</td><td>— (action: invio con esito)</td><td>✅ una mail per record, isolabile</td><td><a href="./smtp">smtp.md</a></td></tr><tr><td>SendGrid (mail via API REST; <code>mailAction</code>/<code>mailSink</code> per scegliere il trasporto)</td><td>— (action: invio con esito)</td><td>✅ una mail per record, isolabile</td><td><a href="./sendgrid">sendgrid.md</a></td></tr><tr><td>HTTP (API REST)</td><td>— (lookup: <code>httpLookup</code>)</td><td>— (action: <code>httpAction</code>)</td><td><a href="./http">http.md</a></td></tr><tr><td>Jira Cloud (issue)</td><td>✅ JQL; lookup per chiave e liste</td><td>— (action: <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, <code>jiraUpsertIssue</code>, <code>jiraAddComment</code>, <code>jiraAddWorklog</code>, <code>jiraLinkIssues</code>)</td><td><a href="./jira">jira.md</a></td></tr><tr><td>OAuth2 (identità per IMAP/SMTP)</td><td>—</td><td>—</td><td><a href="./oauth">oauth.md</a></td></tr><tr><td>Processo esterno (un programma sulla macchina del worker)</td><td>—</td><td>— (action: <code>processoEsternoAction</code>)</td><td><a href="./process">process.md</a></td></tr></tbody></table><p>Noeva offre anche un nodo <code>action</code> (<code>noevaUploadAction</code>: upload con elaborazione AI, <code>fileId</code> in uscita), due resolver di <code>lookup</code> non SQL (<code>noevaElaborazioneLookup</code>, <code>noevaContenutoLookup</code>) e l&#39;estrazione AI <code>noevaAiExtract</code>, la configurazione completa di un nodo <code>ai</code> che estrae campi validati con Zod: vedi <a href="./noeva#elaborazione-ai-upload-stato-testo">noeva.md § Elaborazione AI</a>.</p><p>Oltre a Source e Sink, <strong>ogni connettore SQL</strong> fornisce un resolver del nodo <code>lookup</code>, che interroga il DB <strong>in sola lettura</strong> a metà grafo, a batch di chiavi:</p><table tabindex="0"><thead><tr><th>DBMS</th><th>Resolver</th><th>Parametri bindati</th><th>Doc</th></tr></thead><tbody><tr><td>PostgreSQL</td><td><code>postgresLookup</code></td><td><code>$1, $2, …</code></td><td><a href="./postgres#lookup--postgreslookup">postgres.md § Lookup</a></td></tr><tr><td>SQL Server</td><td><code>mssqlLookup</code></td><td><code>@k0, @k1, …</code></td><td><a href="./sqlserver#lookup--mssqllookup">sqlserver.md § Lookup</a></td></tr></tbody></table><p>Ogni connettore SQL fornisce anche un <strong>task</strong>, per il nodo <code>task</code> del grafo: statement statici in una transazione, senza flusso di record. Serve a svuotare uno staging prima del caricamento e a scambiare le tabelle dopo.</p><table tabindex="0"><thead><tr><th>DBMS</th><th>Task</th><th>Parametri bindati</th><th>Doc</th></tr></thead><tbody><tr><td>PostgreSQL</td><td><code>postgresSqlTask</code></td><td><code>@nome</code> → <code>$1, $2, …</code></td><td><a href="./postgres#task--postgressqltask">postgres.md § Task</a></td></tr><tr><td>SQL Server</td><td><code>mssqlSqlTask</code></td><td><code>@nome</code></td><td><a href="./sqlserver#task--mssqlsqltask">sqlserver.md § Task</a></td></tr></tbody></table><p>La parte comune vive in <code>src/connectors/shared/sql-task.ts</code>. Un task con <code>destructive: true</code> cancella o sostituisce dati: prima di usarlo in produzione leggi il <a href="./../runbooks/sql-task-truncate-swap">runbook</a>.</p><p>Per un&#39;<strong>API REST</strong> c&#39;è <code>httpLookup</code> (<a href="./http">http.md</a>): una richiesta per batch o una <code>GET</code> per chiave, risposta validata con Zod, credenziali dal registry <code>HTTP_INSTANCES</code>. Per <strong>scrivere</strong> sulla stessa API c&#39;è <code>httpAction</code> (<a href="./http#scritture--httpaction">http.md § Scritture</a>), un nodo <code>action</code> che prosegue con l&#39;esito della chiamata.</p><p>Per <strong>leggere Jira Cloud</strong> c&#39;è <code>jiraIssues</code> (<a href="./jira">jira.md</a>, ADR-0100): le issue di una JQL, pagina dopo pagina, con i siti nel registry <code>JIRA_INSTANCES</code> e il trasporto condiviso di <code>http</code>. Ogni campo dichiarato, per id o per nome, è una colonna normalizzata, con il testo ADF convertito da <code>adfInTesto</code> (ADR-0101). Per arricchire record che hanno già una chiave (<code>ABC-42</code>) c&#39;è <code>jiraIssueLookup</code>, un nodo <code>lookup</code> con le issue nella stessa forma; changelog, commenti e worklog completi di una issue arrivano come lista con <code>jiraChangelogLookup</code>, <code>jiraCommentsLookup</code> e <code>jiraWorklogsLookup</code> (<a href="./jira#le-liste-di-una-issue--changelog-commenti-e-worklog">jira.md § Le liste</a>). Per <strong>scriverci</strong> ci sono i nodi <code>action</code> <code>jiraCreateIssue</code>, <code>jiraUpdateIssue</code>, <code>jiraTransition</code>, che porta una issue in uno stato per nome, <code>jiraUpsertIssue</code>, che crea o aggiorna per ID esterno, <code>jiraAddComment</code> e <code>jiraAddWorklog</code>, che aggiungono commenti e worklog senza doppioni con una chiave di deduplica, e <code>jiraLinkIssues</code>, che collega due issue senza duplicare il link (<a href="./jira#scritture">jira.md § Scritture</a>, ADR-0102), con il testo in markdown convertito in ADF da <code>marklassian</code>.</p><p>Per <strong>lanciare un programma</strong> su dei file del record, con file e un riepilogo JSON in uscita, c&#39;è <code>processoEsternoAction</code> (<a href="./process">process.md</a>): un nodo <code>action</code> senza shell, con ambiente da allowlist, timeout obbligatorio e una cartella temporanea per record.</p><p>La query è la stessa sui due database — segnaposto <code>@chiavi</code>, stesso controllo di sola lettura, stessa normalizzazione delle chiavi — perché la parte comune vive in <code>src/connectors/shared/sql-lookup.ts</code>. Un nuovo connettore SQL ottiene il lookup aggiungendo solo la sintassi dei parametri e la chiamata al driver.</p><h2 id="regole-comuni" tabindex="-1">Regole comuni <a class="header-anchor" href="#regole-comuni" aria-label="Permalink to &quot;Regole comuni&quot;">​</a></h2><ul><li><strong>DI del client:</strong> il <code>Pool</code>/connessione è iniettato dal chiamante, che ne gestisce il ciclo di vita. Fanno eccezione gli storage remoti di <code>file</code> (S3, SFTP, FTP): prendono la config dell&#39;istanza e aprono e chiudono la sessione da sé (ADR-0103).</li><li><strong>Streaming:</strong> i Source restituiscono <code>AsyncIterable</code>, mai array interi.</li><li><strong>Idempotenza:</strong> i Sink usano upsert/merge/swap sulla chiave naturale.</li><li><strong>Segreti:</strong> solo in <code>.env</code> (vedi <code>.env.example</code>), mai nel codice/log.</li><li><strong>Descriptor UI:</strong> ogni Source/Sink espone un <code>descriptor</code> non sensibile (tipo + puntamenti) per la visualizzazione del nodo nel DAG — whitelist esplicita, mai segreti. Contratto e how-to: <a href="./../conventions/node-descriptor">../conventions/node-descriptor.md</a>.</li><li><strong>Errori:</strong> <code>ExtractError</code>/<code>LoadError</code>/<code>TaskError</code>/<code>ConfigError</code> da <code>src/core/errors.ts</code>. <code>ConfigError.mancanti</code> elenca in forma strutturata tutte le variabili mancanti.</li><li><strong>Variabili d&#39;ambiente:</strong> i prefissi base delle istanze sono costanti di <code>src/connectors/shared/prefissi.ts</code> (<code>PREFISSO_PG</code>, <code>PREFISSO_MSSQL</code>, <code>PREFISSO_IMAP</code>…), e il prefisso di un&#39;istanza si ricava con <code>instanceEnvPrefix</code>. Le variabili di un connettore si dichiarano in un manifest e si risolvono con <code>risolviVariabili</code>, che dà per ognuna nome e origine. Gli stessi manifest, con <code>ambienteDellaPipeline</code>, dicono a <code>etl env check</code> quali variabili legge una pipeline. Oggi lo usano i loader di IMAP, SMTP, HTTP, Jira, OAuth2, del client Noeva, Postgres, SQL Server, SendGrid e degli storage S3, SFTP e FTP (<code>MANIFEST_IMAP</code>, <code>MANIFEST_SMTP</code>, <code>MANIFEST_HTTP</code>, <code>MANIFEST_JIRA</code>, <code>MANIFEST_OAUTH</code>, <code>MANIFEST_NOEVA</code>, <code>MANIFEST_PG</code>, <code>MANIFEST_MSSQL</code>, <code>MANIFEST_SENDGRID</code>, <code>MANIFEST_S3</code>, <code>MANIFEST_SFTP</code>, <code>MANIFEST_FTP</code>); gli altri connettori migrano un tipo alla volta. La cartella locale non ha un loader suo: la indica la pipeline, che la dichiara nel proprio manifest. Vedi <a href="./../conventions/node-descriptor#variabile-e-origine-dal-manifest-mai-a-mano">node-descriptor.md</a>.</li><li><strong>Test:</strong> logica pura in unit (CI); I/O reale in <code>tests/integration/</code> (<code>pnpm run test:integration</code>).</li></ul>',16)])])}const m=o(r,[["render",i]]);export{g as __pageData,m as default};
@@ -1 +0,0 @@
1
- import{_ as o,o as t,c as d,a5 as a}from"./chunks/framework.qdetmeNX.js";const g=JSON.parse('{"title":"Connettori","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/README.md","filePath":"connectors/README.md"}'),r={name:"connectors/README.md"};function i(n,e,c,s,l,p){return t(),d("div",null,[...e[0]||(e[0]=[a("",16)])])}const m=o(r,[["render",i]]);export{g as __pageData,m as default};
@@ -1,7 +0,0 @@
1
- import{_ as t,o,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const p=JSON.parse('{"title":"OAuth2 per i connettori di posta","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/oauth.md","filePath":"connectors/oauth.md"}'),n={name:"connectors/oauth.md"};function s(d,e,r,l,c,h){return o(),i("div",null,[...e[0]||(e[0]=[a(`<h1 id="oauth2-per-i-connettori-di-posta" tabindex="-1">OAuth2 per i connettori di posta <a class="header-anchor" href="#oauth2-per-i-connettori-di-posta" aria-label="Permalink to &quot;OAuth2 per i connettori di posta&quot;">​</a></h1><p>Non è un connettore: è <strong>l&#39;identità</strong> che IMAP e SMTP usano per autenticarsi dove la password non basta più — Gmail, Google Workspace, Microsoft 365. Procedura passo passo nel runbook <a href="./../runbooks/oauth-google-posta">oauth-google-posta.md</a>.</p><h2 id="perche-esiste" tabindex="-1">Perché esiste <a class="header-anchor" href="#perche-esiste" aria-label="Permalink to &quot;Perché esiste&quot;">​</a></h2><p>I connettori sapevano già parlare XOAUTH2, ma un access token vive un&#39;ora: incollarne uno in <code>IMAP_ACCESS_TOKEN</code> è una configurazione che funziona per un&#39;ora e poi torna rossa. Questo modulo tiene il <strong>refresh token</strong> e scambia un access token nuovo quando serve.</p><h2 id="un-identita-due-connettori" tabindex="-1">Un&#39;identità, due connettori <a class="header-anchor" href="#un-identita-due-connettori" aria-label="Permalink to &quot;Un&#39;identità, due connettori&quot;">​</a></h2><p>La stessa casella Google si legge e si scrive con lo stesso consenso, quindi l&#39;identità sta in un registry suo e IMAP e SMTP la referenziano per id. Duplicare <code>CLIENT_SECRET</code> e <code>REFRESH_TOKEN</code> nei due blocchi significherebbe, prima o poi, ruotarne uno solo.</p><h2 id="variabili" tabindex="-1">Variabili <a class="header-anchor" href="#variabili" aria-label="Permalink to &quot;Variabili&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>OAUTH_CLIENT_ID</code></td><td>—</td><td>obbligatoria se il registry è usato</td></tr><tr><td><code>OAUTH_CLIENT_SECRET</code></td><td>—</td><td>obbligatoria</td></tr><tr><td><code>OAUTH_REFRESH_TOKEN</code></td><td>—</td><td>obbligatoria; ottenuto una volta sola, vedi runbook</td></tr><tr><td><code>OAUTH_TOKEN_ENDPOINT</code></td><td><code>https://oauth2.googleapis.com/token</code></td><td><strong>deve essere <code>https://</code></strong>; Microsoft 365 si configura qui</td></tr><tr><td><code>OAUTH_SCOPE</code></td><td>—</td><td>solo se il provider lo vuole al refresh; Google no</td></tr><tr><td><code>OAUTH_INSTANCES</code></td><td>—</td><td>più caselle: <code>ordini,notifiche</code> → <code>OAUTH_&lt;ID&gt;_*</code></td></tr></tbody></table><p>Chi le usa:</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Default</th><th>Note</th></tr></thead><tbody><tr><td><code>IMAP_AUTH=oauth2</code></td><td>dedotto</td><td>e <code>IMAP_PASSWORD</code> va <strong>tolta</strong></td></tr><tr><td><code>IMAP_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>quale identità rinnova il token di quella casella</td></tr><tr><td><code>SMTP_AUTH=oauth2</code></td><td>dedotto</td><td>e <code>SMTP_PASSWORD</code> va <strong>tolta</strong></td></tr><tr><td><code>SMTP_OAUTH_INSTANCE</code></td><td><code>default</code></td><td>di norma la stessa di IMAP</td></tr></tbody></table><p>Le variabili sono dichiarate in <code>MANIFEST_OAUTH</code>: un&#39;identità incompleta dà un <code>ConfigError</code> che elenca <strong>tutte</strong> le variabili mancanti.</p><h3 id="nel-piano" tabindex="-1">Nel piano <a class="header-anchor" href="#nel-piano" aria-label="Permalink to &quot;Nel piano&quot;">​</a></h3><p>Un&#39;identità OAuth2 non è un nodo. Nel piano compare nella riga <code>credenziale</code> delle caselle IMAP e dei server SMTP che la usano: <code>OAuth · identità default · impostata</code>, oppure <code>… · mancano OAUTH_CLIENT_SECRET, OAUTH_REFRESH_TOKEN</code> con origine <code>mancante</code> e la variabile che punta alla prima da impostare. Un&#39;identità che non è in <code>OAUTH_INSTANCES</code> la run non la trova, anche se le sue variabili ci sono: il piano lo dice con <code>· manca OAUTH_INSTANCES</code>. Il piano la risolve con <code>risolviIdentitaOauth(id, env)</code>, che non lancia e dei segreti restituisce solo lo stato.</p><p>Per <code>etl env check</code>, <code>identitaOauthDichiarate(caselle, env)</code> dà le sole identità che le caselle date usano davvero, cioè quelle su <code>&lt;PREFIX&gt;AUTH=oauth2</code> senza <code>&lt;PREFIX&gt;ACCESS_TOKEN</code>, da aggiungere alle istanze di <code>ambienteDellaPipeline</code>: una pipeline con caselle su password non chiede variabili <code>OAUTH_*</code>.</p><h2 id="il-registry-puo-essere-vuoto" tabindex="-1">Il registry può essere vuoto <a class="header-anchor" href="#il-registry-puo-essere-vuoto" aria-label="Permalink to &quot;Il registry può essere vuoto&quot;">​</a></h2><p>È l&#39;unico, ed è deliberato. Un <code>PG_HOST</code> mancante è una configurazione rotta; OAuth2 invece è una <strong>scelta</strong>, e la maggioranza delle installazioni continuerà con una password. Senza <code>OAUTH_INSTANCES</code> né <code>OAUTH_CLIENT_ID</code> il registry esce vuoto e i connettori non cambiano comportamento.</p><p>La tolleranza finisce lì. Un&#39;istanza <strong>dichiarata</strong> in <code>OAUTH_INSTANCES</code> e incompleta è un errore, e un <code>IMAP_OAUTH_INSTANCE</code> che nomina un id inesistente pure: ricadere in silenzio sul token statico significherebbe autenticarsi con una credenziale diversa da quella che si crede.</p><h2 id="come-si-usa-dal-codice" tabindex="-1">Come si usa dal codice <a class="header-anchor" href="#come-si-usa-dal-codice" aria-label="Permalink to &quot;Come si usa dal codice&quot;">​</a></h2><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> oauth</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> fornitoriOauth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">loadOauthRegistry</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(env));</span></span>
2
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> tokenImap</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> oauth</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(imap.auth, imap.oauthInstance);</span></span>
3
- <span class="line"></span>
4
- <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">imapSource</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(imap, {</span></span>
5
- <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // …</span></span>
6
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ...</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(tokenImap </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!==</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> undefined</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ?</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { client: { accessToken: tokenImap } } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {}),</span></span>
7
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><strong>Un risolutore per run, non per nodo.</strong> <code>fornitoriOauth</code> memoizza per id d&#39;istanza: i nodi che condividono l&#39;identità condividono la cache del token. Una pipeline di posta può toccare la stessa casella in tre punti — sorgente, sessione delle action IMAP, notifiche SMTP — e senza la memoizzazione la stessa run chiederebbe tre token invece di uno. Il guaio non è lo spreco: è che funzionerebbe, quindi nessuno se ne accorgerebbe fino al primo rate limit.</p><p>Il fornitore serializza anche le richieste: due nodi che chiedono il token insieme sulla cache fredda fanno una chiamata sola.</p><h2 id="come-tratta-le-credenziali" tabindex="-1">Come tratta le credenziali <a class="header-anchor" href="#come-tratta-le-credenziali" aria-label="Permalink to &quot;Come tratta le credenziali&quot;">​</a></h2><ul><li><strong>Niente redirect.</strong> La <code>fetch</code> verso il token endpoint usa <code>redirect: &quot;error&quot;</code>. Il default di <code>fetch</code> è seguirli, e su un <code>307</code> il body — client secret e refresh token — viene ripetuto verso l&#39;host nuovo, anche in <code>http://</code>. Il vincolo <code>https://</code> guarda solo il primo URL: da solo non basterebbe.</li><li><strong>Niente credenziali nei messaggi d&#39;errore.</strong> Il testo che arriva dal provider viene redatto (client secret e refresh token sostituiti) e troncato a 160 caratteri: più d&#39;un IdP rieccheggia il valore rifiutato, e la CLI stampa gli errori su stderr.</li><li><strong>Nessuna <code>cause</code></strong>, come in IMAP e SMTP: <code>console.error</code> segue la catena delle cause per intero.</li><li><strong>Timeout di 30 secondi</strong>, come gli altri connettori: un endpoint muto non blocca la run.</li><li>La cache del token vive <strong>in memoria, per la durata della run</strong>. Mai su disco.</li></ul><h2 id="errori" tabindex="-1">Errori <a class="header-anchor" href="#errori" aria-label="Permalink to &quot;Errori&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Messaggio</th><th>Che cosa vuol dire</th></tr></thead><tbody><tr><td><code>OAuth2: refresh token rifiutato (invalid_grant)</code></td><td>Non più valido. Su un progetto Internal la causa prima è il <strong>cambio password della casella</strong>: lo scope è un ambito Gmail. Le altre cause sono nel runbook</td></tr><tr><td><code>OAuth2: il provider ha rifiutato la richiesta (invalid_client…)</code></td><td>Client ID o secret sbagliati</td></tr><tr><td><code>OAuth2: il token endpoint non risponde</code></td><td>Rete, DNS, timeout, o un redirect rifiutato</td></tr><tr><td><code>OAuth2: risposta del provider senza access_token utilizzabile</code></td><td>Il provider ha risposto 200 con un corpo che non contiene un token</td></tr><tr><td><code>Identità OAuth2 &quot;…&quot; non configurata</code></td><td><code>IMAP_OAUTH_INSTANCE</code> o <code>SMTP_OAUTH_INSTANCE</code> nomina un id che non esiste</td></tr></tbody></table>`,25)])])}const g=t(n,[["render",s]]);export{p as __pageData,g as default};
@@ -1 +0,0 @@
1
- import{_ as t,o,c as i,a5 as a}from"./chunks/framework.qdetmeNX.js";const p=JSON.parse('{"title":"OAuth2 per i connettori di posta","description":"","frontmatter":{},"headers":[],"relativePath":"connectors/oauth.md","filePath":"connectors/oauth.md"}'),n={name:"connectors/oauth.md"};function s(d,e,r,l,c,h){return o(),i("div",null,[...e[0]||(e[0]=[a("",25)])])}const g=t(n,[["render",s]]);export{p as __pageData,g as default};