@xeplr/actions 1.1.1 → 1.1.6

package/lib/builtins/db/procedure.js

@@ -0,0 +1,210 @@
+// db-procedure action — CALL a stored procedure. That is the whole job.
+//
+// It exists because "call this procedure" was previously only reachable
+// through db-move, whose shape is "read rows from somewhere and write them
+// somewhere else". That made a procedure returning nothing — a nightly
+// recalculation, a rebuild, a queue drained, a flag flipped — impossible to
+// run at all, because db-move requires a targetTable to put results in. The
+// workaround was to name a scratch table and hope the procedure returned no
+// rows, which is a costume, not a feature.
+//
+// Rows come back when there are rows. They are the OUTPUT of the action, not
+// a movement: a caller that wants them written to a table already has db-move
+// for exactly that, and db-move now calls the same builder this does (see
+// drivers/db/procedure.js) rather than keeping its own copy of how a
+// procedure is called in each dialect.
+//
+// ── returnsRows, and why it is not guesswork ─────────────────────────────
+//
+// On Postgres, "a procedure" is two different objects: a PROCEDURE (CALL, no
+// readable result) and a set-returning FUNCTION (SELECT * FROM fn(), rows).
+// Nothing about the name says which one you have, and calling the wrong form
+// is an error rather than an empty result — so the caller says. The default is
+// TRUE because a step that reads is the more common one and the more likely
+// to be built by someone who has not thought about the distinction; a
+// side-effect-only procedure is a deliberate act and can afford a checkbox.
+//
+// MSSQL's EXEC and MySQL's CALL cover both cases with one form, so the flag
+// only changes what Postgres emits.
+
+var dbDrivers = require('../../drivers/db');
+var { buildProcedureCall } = require('../../drivers/db/procedure');
+
+module.exports = {
+  name: 'db-procedure',
+  description: 'Call a stored procedure with parameters. Returns its rows when it produces any — ' +
+               'no target table, no movement. For a procedure whose rows you want written to a ' +
+               'table, use db-move with mode="procedure".',
+  requires: [],   // per-driver requires checked at runtime once dbType is known
+
+  inputSchema: [
+    // ── WHICH DATABASE, picked rather than typed ────────────────────────
+    //
+    // Same shape as db-fetch and db-push, and for the same reason: this action
+    // is meant to be SCHEDULED, and a job's inputs are fetched by the browser
+    // on every list load and snapshotted into every occurrence row. A password
+    // in there is a password everywhere, forever.
+    //
+    // So the form collects ids. @xeplr/jobs' resolveInputs swaps any
+    // *ConnectionInfoId for real credentials server-side, immediately before
+    // execute() runs, by a naming convention it applies generically
+    // (connectionInfoId → connection) — no per-action wiring.
+    { name: 'connectionInfoId', type: 'string', order: 1,
+      optionsFrom: 'connections',
+      description: 'A saved connection. Resolved to credentials server-side.' },
+    { name: 'dbInfoId',         type: 'string', order: 2,
+      optionsFrom: 'databases', dependsOn: 'connectionInfoId',
+      description: 'Which database on that connection.' },
+
+    // Filled by the host from the two ids above, or supplied literally by a
+    // caller with no host at all — a script, a test, a standalone worker, and
+    // the live probes in this repo. `system: true` keeps them out of the form
+    // either way, but they must stay DECLARED: @xeplr/schema-handler drops any
+    // field a schema does not mention, which would strip the resolved
+    // connection on its way to execute().
+    { name: 'dbType',      type: 'string', required: true, default: 'postgres', order: 3,
+      system: true, options: ['postgres', 'mysql', 'mssql'],
+      description: 'Taken from the connection when one is chosen.' },
+    { name: 'connection',  type: 'object', required: true, order: 4,
+      system: true,
+      description: 'Connection config: { host, port, user, password, database }' },
+
+    { name: 'procedure',   type: 'string', required: true, order: 5,
+      optionsFrom: 'procedures', dependsOn: 'connectionInfoId',
+      description: 'Procedure name, optionally schema-qualified ("dbo.usp_rebuild").' },
+    // ── INCREMENTAL ─────────────────────────────────────────────────────
+    //
+    // The window this run covers, handed to the procedure as two of its own
+    // parameters, because a procedure has no WHERE to filter from outside.
+    //
+    // A SCHEDULED job fills this in by itself. @xeplr/jobs' buildWindow sets
+    // `from` to the job's coveredTo — where the last SUCCESSFUL run stopped,
+    // not when it last ran — and `to` to a single pinned `now`, keeping
+    // whatever fromParam/toParam were authored here. On success it advances
+    // coveredTo to that same `to`, so a failed run leaves the coverage where
+    // it was and the next run picks up the gap by itself. Set the job's
+    // incrementalMode to "period" and name the two parameters here; nothing
+    // else is needed.
+    //
+    // Half-open, from <= x < to. The next run starts at exactly this run's
+    // `to`, so a procedure treating `to` as inclusive double-counts the
+    // boundary row every time.
+    { name: 'window',      type: 'object', order: 6, group: 'Incremental',
+      description: '{ from, to, fromParam, toParam } — the period this run covers, passed as the ' +
+                   'named parameters fromParam/toParam. Filled automatically for a job with ' +
+                   'incrementalMode "period"; name the two parameters and leave from/to empty. ' +
+                   'A window without fromParam/toParam is refused rather than silently dropped.' },
+
+    { name: 'params',      type: 'array', order: 7,
+      description: 'Parameters, as [{ name, value }] or bare values. Named entries are matched by ' +
+                   'name on postgres and mssql; MySQL has no named-argument syntax, so there they ' +
+                   'are positional and must be in the order the procedure declares them.' },
+    { name: 'returnsRows', type: 'boolean', default: true, order: 8,
+      description: 'Postgres only: true calls a set-returning FUNCTION (SELECT * FROM fn(…)), ' +
+                   'false calls a PROCEDURE (CALL proc(…)) that returns nothing. Ignored for ' +
+                   'mssql and mysql, whose one call form covers both.' },
+    { name: 'maxRows',     type: 'number', order: 9, group: 'Performance',
+      description: 'Refuse to buffer more than this many rows. Omitted = no limit. A procedure ' +
+                   'that answers with a million rows is a movement, not a step output.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+
+    var driver = dbDrivers.getDriver(input.dbType);
+    if (!driver) throw new Error('db-procedure: no driver for "' + input.dbType + '"');
+
+    // A job that names a connection but reaches here without one means the
+    // host's resolver never ran. Said plainly, because the alternative is the
+    // driver failing on an undefined host three layers down.
+    if (!input.connection) {
+      throw new Error('db-procedure: no connection. Choose a saved connection, or pass ' +
+        '`connection` and `dbType` directly. (If this job names a connectionInfoId, the host ' +
+        'has no connection resolver configured — see @xeplr/jobs init().)');
+    }
+
+    var call = buildProcedureCall({
+      driver: driver,
+      dbType: input.dbType,
+      name: input.procedure,
+      params: input.params,
+      window: input.window || null,
+      returnsRows: input.returnsRows
+    });
+
+    // The STATEMENT, never its parameters — same rule the move path follows.
+    // A procedure's arguments can carry values out of the customer's own data
+    // (a customer id, an email), and a log is not where those belong.
+    if (system.log) {
+      system.log('Calling ' + input.procedure + ' on ' + input.dbType + ' "' + connDbName(input.connection) + '"', {
+        phase: 'call',
+        event: 'procedure_started',
+        procedure: input.procedure,
+        dbType: input.dbType,
+        database: connDbName(input.connection),
+        sql: call.sql,
+        paramCount: call.params.length,
+        // The BOUNDS, which are configuration somebody chose rather than rows
+        // out of the customer's tables — and the first thing a "why did this
+        // run do nothing" question asks about. The other parameter VALUES are
+        // deliberately absent; they can carry customer data.
+        window: input.window
+          ? { from: input.window.from || null, to: input.window.to || null,
+              fromParam: input.window.fromParam || null, toParam: input.window.toParam || null }
+          : null,
+        // Said out loud because it is the one thing that silently does
+        // something other than what the author wrote — names given to a MySQL
+        // call are ignored and the order decides.
+        parametersAreNamed: call.named
+      });
+    }
+    if (system.log && input.dbType === 'mysql' && (input.params || []).some(function(p) { return p && p.name; })) {
+      system.log('MySQL has no named-argument syntax — these parameters are being passed in the ' +
+                 'order given, not by name. Check they match the procedure\'s declaration.', {
+        phase: 'call', event: 'names_ignored', dbType: 'mysql', paramCount: call.params.length });
+    }
+
+    var pool = await driver.connect(input.connection);
+    var startedAt = Date.now();
+    try {
+      var result = await driver.query(pool, call.sql, call.params);
+      // Every driver normalises to { rows } — and a call that returns nothing
+      // legitimately has none, which is a success, not an empty answer to
+      // apologise for.
+      var rows = (result && result.rows) || [];
+
+      if (input.maxRows && rows.length > input.maxRows) {
+        throw new Error('db-procedure: ' + input.procedure + ' returned ' + rows.length +
+          ' rows, over the ' + input.maxRows + ' allowed. Use db-move to write a result this size ' +
+          'to a table instead of carrying it through a step.');
+      }
+
+      if (system.log) {
+        system.log('Done — ' + input.procedure + ' returned ' + rows.length + ' row(s) in ' +
+          ((Date.now() - startedAt) / 1000).toFixed(1) + 's', {
+          phase: 'summary', event: 'procedure_done',
+          procedure: input.procedure, rows: rows.length, durationMs: Date.now() - startedAt
+        });
+      }
+
+      return { rows: rows, rowCount: rows.length, procedure: input.procedure, sql: call.sql };
+    } catch (err) {
+      if (system.log) {
+        system.log(input.procedure + ' failed: ' + err.message, {
+          phase: 'summary', event: 'procedure_failed',
+          procedure: input.procedure, reason: err.message, durationMs: Date.now() - startedAt });
+      }
+      throw err;
+    } finally {
+      // Always — a pooled connection left open holds sockets and keeps the
+      // process alive, the same trap the SMTP transport had.
+      await driver.close(pool);
+    }
+  }
+};
+
+/** The database name off a connection config — never the password. */
+function connDbName(connection) {
+  return (connection && connection.database) || '?';
+}

package/lib/builtins/db/push.js

@@ -21,9 +21,19 @@ module.exports = {
   requires: [],   // per-driver requires checked at runtime once dbType is known
 
   inputSchema: [
-    { name: 'dbType',      type: 'string',  required: true, default: 'postgres', order: 1,
-      description: 'postgres | mysql | mssql | mongo' },
-    { name: 'connection',  type: 'object',  required: true, order: 2,
+    // See db/fetch.js for why there are two routes in and why the literal
+    // one is not for the job editor. Same contract, same reasons.
+    { name: 'connectionInfoId', type: 'string', order: 1,
+      optionsFrom: 'connections',
+      description: 'A saved connection. Resolved to credentials server-side.' },
+    { name: 'dbInfoId',         type: 'string', order: 2,
+      optionsFrom: 'databases', dependsOn: 'connectionInfoId',
+      description: 'Which database on that connection.' },
+    { name: 'dbType',      type: 'string',  required: true, default: 'postgres', order: 3,
+      system: true, options: ['postgres', 'mysql', 'mssql', 'mongo'],
+      description: 'Taken from the connection when one is chosen.' },
+    { name: 'connection',  type: 'object',  required: true, order: 4,
+      system: true,
       description: 'Connection config: { host, port, user, password, database }' },
     { name: 'targetTable', type: 'string',  required: true, order: 3 },
     { name: 'primaryKeys', type: 'array',   order: 4,
@@ -32,10 +42,10 @@ module.exports = {
       description: 'Inline rows (mutually exclusive with filePath).' },
     { name: 'filePath',    type: 'string',  order: 6,
       description: 'Path to an NDJSON file (one row per line). Use for large uploads.' },
-    { name: 'movementId',  type: 'string',  order: 7,
+    { name: 'movementId',  type: 'string',  order: 7, group: 'Advanced',
       description: 'Correlation key for rollback. Defaults to system.occurrenceId or a fresh id.' },
-    { name: 'batchSize',   type: 'number',  default: 5000, order: 8 },
-    { name: 'concurrency', type: 'number',  default: 4,    order: 9 }
+    { name: 'batchSize',   type: 'number',  default: 5000, order: 8, group: 'Performance' },
+    { name: 'concurrency', type: 'number',  default: 4,    order: 9, group: 'Performance' }
   ],
 
   execute: async function(ctx) {

package/lib/builtins/email/delete.js

@@ -0,0 +1,42 @@
+// email-delete action — permanently delete one message.
+//
+// PERMANENT. This flags \Deleted and EXPUNGES: the message is gone from the
+// server, not moved to Trash, and there is nothing to undo. If what you want
+// is the server's trash folder, that is email-move with toFolder set to it —
+// which is reversible and is usually the right choice in an automated flow.
+//
+// Like every message-addressed action here, the id is folder-scoped; `folder`
+// must name where the message currently lives.
+
+var emailDrivers = require('../../drivers/email');
+var emailConfig = require('../../drivers/email/config');
+
+module.exports = {
+  name: 'email-delete',
+  description: 'Permanently delete a message (flags \\Deleted and expunges — NOT a move to Trash). ' +
+               'The message id is folder-scoped, so input.folder must name the folder it is in.',
+  requires: [],
+
+  // Which mailbox first — it is the only answer that changes what the rest of
+  // the form means. See send-email's schema for the showWhen/group split.
+  inputSchema: [
+    { name: 'useCustomConnection', type: 'boolean', default: false, order: 1,
+      description: 'Off: use the mailbox this install is already configured with. On: supply your own below.' },
+    { name: 'connection', type: 'object', order: 2,
+      showWhen: { field: 'useCustomConnection', equals: true },
+      description: '{ host, port, secure, user, password, tls? }' },
+    { name: 'messageId',  type: 'string', required: true, order: 3,
+      description: 'Message id (IMAP UID) as returned by email-read.' },
+    { name: 'folder',     type: 'string', default: 'INBOX', order: 4,
+      description: 'Folder the message is currently in — where its id is valid.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var provider = emailDrivers.getInboundProvider(input.emailType);
+    // 'system' resolves from env; 'custom' takes the step's own connection.
+    var conn = emailConfig.resolveInbound(input);
+    provider.checkRequires('email-delete', { needsParser: false });
+    return provider.delete(conn, input);
+  }
+};

package/lib/builtins/email/download-attachments.js

@@ -0,0 +1,52 @@
+// email-download-attachments action — save a message's attachments to disk,
+// optionally filtered by extension and/or filename substring.
+//
+// Each file is written with a random prefix, because attachment names collide
+// constantly ("invoice.pdf" from fifty senders) and a download that silently
+// overwrites the previous one is expensive to notice. Names are also
+// sanitized: a filename arriving from a mailbox is attacker-controlled, and
+// one containing path separators would otherwise escape the output directory.
+//
+// `saved[]` entries carry { filename, path } — exactly nodemailer's attachment
+// descriptor shape — so the output can be handed straight to email-send to
+// forward what was just downloaded.
+
+var emailDrivers = require('../../drivers/email');
+var emailConfig = require('../../drivers/email/config');
+
+module.exports = {
+  name: 'email-download-attachments',
+  description: 'Save a message\'s attachments to disk, optionally filtered by extension or ' +
+               'filename substring. Returns { count, saved[], path, skipped }.',
+  requires: [],
+
+  // Which mailbox first — it is the only answer that changes what the rest of
+  // the form means. See send-email's schema for the showWhen/group split.
+  inputSchema: [
+    { name: 'useCustomConnection', type: 'boolean', default: false, order: 1,
+      description: 'Off: use the mailbox this install is already configured with. On: supply your own below.' },
+    { name: 'connection', type: 'object', order: 2,
+      showWhen: { field: 'useCustomConnection', equals: true },
+      description: '{ host, port, secure, user, password, tls? }' },
+    { name: 'messageId',        type: 'string', required: true, order: 3,
+      description: 'Message id (IMAP UID) as returned by email-read.' },
+    { name: 'folder',           type: 'string', default: 'INBOX', order: 4,
+      description: 'Folder the message is currently in — where its id is valid.' },
+    { name: 'outDir',           type: 'string', order: 5,
+      description: 'Directory to write into. Defaults to XEPLR_ACTIONS_TMP_DIR.' },
+
+    { name: 'extension',        type: 'string', order: 6, group: 'Filters',
+      description: 'Only attachments with this extension, e.g. "pdf" or ".pdf".' },
+    { name: 'filenameContains', type: 'string', order: 7, group: 'Filters',
+      description: 'Only attachments whose filename contains this substring.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var provider = emailDrivers.getInboundProvider(input.emailType);
+    // 'system' resolves from env; 'custom' takes the step's own connection.
+    var conn = emailConfig.resolveInbound(input);
+    provider.checkRequires('email-download-attachments', { needsParser: true });
+    return provider.downloadAttachments(conn, input);
+  }
+};

package/lib/builtins/email/download-email.js

@@ -0,0 +1,45 @@
+// email-download-email action — save the whole message as an RFC-822 .eml.
+//
+// Headers, body and every attachment, byte for byte as the server holds it —
+// which is what an .eml IS, so nothing is built: the raw IMAP source streams
+// straight to disk without being parsed or buffered whole. A message carrying
+// a 40 MB attachment never becomes a 40 MB string.
+//
+// Output shape is deliberately identical to email-download-attachments
+// ({ count, saved[], path }) so a downstream step binds the same way whichever
+// produced the file.
+
+var emailDrivers = require('../../drivers/email');
+var emailConfig = require('../../drivers/email/config');
+
+module.exports = {
+  name: 'email-download-email',
+  description: 'Save an entire message to disk as a .eml (RFC-822) file, streamed. ' +
+               'Returns { count, saved[], path } like email-download-attachments.',
+  requires: [],
+
+  // Which mailbox first — it is the only answer that changes what the rest of
+  // the form means. See send-email's schema for the showWhen/group split.
+  inputSchema: [
+    { name: 'useCustomConnection', type: 'boolean', default: false, order: 1,
+      description: 'Off: use the mailbox this install is already configured with. On: supply your own below.' },
+    { name: 'connection', type: 'object', order: 2,
+      showWhen: { field: 'useCustomConnection', equals: true },
+      description: '{ host, port, secure, user, password, tls? }' },
+    { name: 'messageId',  type: 'string', required: true, order: 3,
+      description: 'Message id (IMAP UID) as returned by email-read.' },
+    { name: 'folder',     type: 'string', default: 'INBOX', order: 4,
+      description: 'Folder the message is currently in — where its id is valid.' },
+    { name: 'outDir',     type: 'string', order: 5,
+      description: 'Directory to write into. Defaults to XEPLR_ACTIONS_TMP_DIR.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var provider = emailDrivers.getInboundProvider(input.emailType);
+    // 'system' resolves from env; 'custom' takes the step's own connection.
+    var conn = emailConfig.resolveInbound(input);
+    provider.checkRequires('email-download-email', { needsParser: false });
+    return provider.downloadEmail(conn, input);
+  }
+};

package/lib/builtins/email/move.js

@@ -0,0 +1,45 @@
+// email-move action — move one message to another folder.
+//
+// `folder` (the SOURCE) is a real input, not a detail: a message is addressed
+// by IMAP UID, which is scoped to the folder it currently sits in. Moving from
+// anywhere other than INBOX without saying so targets the wrong mailbox and
+// either fails or moves something else.
+//
+// A move CHANGES the message's uid. Any further step that addresses the same
+// message (download, delete) must run BEFORE this one, or re-read to pick up
+// the new uid from the destination folder.
+
+var emailDrivers = require('../../drivers/email');
+var emailConfig = require('../../drivers/email/config');
+
+module.exports = {
+  name: 'email-move',
+  description: 'Move a message to another mailbox folder. The message id is folder-scoped, ' +
+               'so input.folder must name the folder the message is currently in.',
+  requires: [],
+
+  // Which mailbox first — it is the only answer that changes what the rest of
+  // the form means. See send-email's schema for the showWhen/group split.
+  inputSchema: [
+    { name: 'useCustomConnection', type: 'boolean', default: false, order: 1,
+      description: 'Off: use the mailbox this install is already configured with. On: supply your own below.' },
+    { name: 'connection', type: 'object', order: 2,
+      showWhen: { field: 'useCustomConnection', equals: true },
+      description: '{ host, port, secure, user, password, tls? }' },
+    { name: 'messageId',  type: 'string', required: true, order: 3,
+      description: 'Message id (IMAP UID) as returned by email-read.' },
+    { name: 'toFolder',   type: 'string', required: true, order: 4,
+      description: 'Destination folder name.' },
+    { name: 'folder',     type: 'string', default: 'INBOX', order: 5,
+      description: 'Folder the message is currently in — where its id is valid.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var provider = emailDrivers.getInboundProvider(input.emailType);
+    // 'system' resolves from env; 'custom' takes the step's own connection.
+    var conn = emailConfig.resolveInbound(input);
+    provider.checkRequires('email-move', { needsParser: false });
+    return provider.move(conn, input);
+  }
+};

package/lib/builtins/email/read.js

@@ -0,0 +1,128 @@
+// email-read action — list messages from a mailbox, newest first.
+//
+// STREAMING follows the older builtins convention (streaming_mode defaults
+// FALSE), not db-fetch's: a mailbox read is bounded by `limit` (max 1000) and
+// the normal case is a handful of messages a workflow branches on immediately.
+// Set streaming_mode:true when pulling bodies in bulk — HTML mail with inline
+// base64 images is large, and spooling keeps it off the heap and out of the
+// run record. Temp file: XEPLR_ACTIONS_TMP_DIR, same as db-fetch.
+//
+// COST CONTROL is `body`, not `limit`. body:'none' skips downloading message
+// sources entirely and fetches envelopes only — the right setting for a
+// monitor that just needs ids to feed move/download steps.
+
+var emailDrivers = require('../../drivers/email');
+var emailConfig = require('../../drivers/email/config');
+var crypto = require('crypto');
+var os = require('os');
+var path = require('path');
+var fs = require('fs');
+var fsp = require('fs/promises');
+
+module.exports = {
+  name: 'email-read',
+  description: 'List messages from a mailbox folder, newest first, with optional ' +
+               'unread/date/sender/subject filters. Returns message metadata and ' +
+               '(optionally) bodies. Routes to the provider named by input.emailType.',
+  requires: [],   // peer deps (imapflow/mailparser) checked at runtime
+
+  // Which mailbox first — it is the only answer that changes what the rest of
+  // the form means — then what to read out of it. The four narrowing filters
+  // and the two output switches are `group`ed: real inputs, but a step that
+  // just wants "the unread ones" should not have to scroll past six boxes it
+  // is leaving empty. See send-email's schema for the showWhen/group split.
+  inputSchema: [
+    { name: 'useCustomConnection', type: 'boolean', default: false, order: 1,
+      description: 'Off: use the mailbox this install is already configured with. On: supply your own below.' },
+    { name: 'connection', type: 'object', order: 2,
+      showWhen: { field: 'useCustomConnection', equals: true },
+      description: '{ host, port, secure, user, password, tls? }' },
+
+    { name: 'folder',           type: 'string',  default: 'INBOX', order: 3,
+      description: 'Mailbox folder to read from.' },
+    { name: 'unread_only',      type: 'boolean', default: false, order: 4,
+      description: 'Only messages without the \\Seen flag.' },
+    { name: 'limit',            type: 'number',  default: 50, order: 5,
+      description: 'Max messages to return, newest first (1-1000).' },
+
+    { name: 'since',            type: 'string',  order: 6, group: 'Filters',
+      description: 'ISO 8601 date — server-side IMAP SINCE filter.' },
+    { name: 'from_equals',      type: 'string',  order: 7, group: 'Filters',
+      description: 'Exact sender address match (case-insensitive).' },
+    { name: 'from_contains',    type: 'string',  order: 8, group: 'Filters',
+      description: 'Substring match on sender address.' },
+    { name: 'subject_contains', type: 'string',  order: 9, group: 'Filters',
+      description: 'Substring match on subject.' },
+
+    { name: 'body',             type: 'string',  default: 'full', order: 10, group: 'Output',
+      description: '"full" (html+text), "text" (text only), or "none" (metadata only — much faster).' },
+    { name: 'streaming_mode',   type: 'boolean', default: false, order: 11, group: 'Output',
+      description: 'true → spool messages to an NDJSON file (output.filePath). false → inline output.messages.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+
+    var provider = emailDrivers.getInboundProvider(input.emailType);
+
+    // 'system' resolves from env; 'custom' takes the step's own connection.
+
+    var conn = emailConfig.resolveInbound(input);
+    provider.checkRequires('email-read', { needsParser: (input.body || 'full') !== 'none' });
+
+    var messages = await provider.read(conn, input);
+
+    if (!input.streaming_mode) {
+      return { messages: messages, messageCount: messages.length, streaming: false };
+    }
+
+    var filePath = await resolveOutputPath(system);
+    var stats = await writeNDJSON(filePath, messages);
+    return {
+      filePath: filePath,
+      format: 'jsonl',
+      bytes: stats.bytes,
+      messageCount: stats.rows,
+      streaming: true
+    };
+  }
+};
+
+// ─── helpers ────────────────────────────────────────────────────────────
+
+async function resolveOutputPath(system) {
+  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+  await fsp.mkdir(dir, { recursive: true });
+  var base = (system.occurrenceId || crypto.randomBytes(6).toString('hex'))
+    + '_email-read_' + crypto.randomBytes(6).toString('hex') + '.jsonl';
+  return path.join(dir, base);
+}
+
+// One JSON object per line — the same NDJSON shape db-fetch emits, so the
+// existing readers work unchanged. Honors write backpressure rather than
+// queueing the whole array in memory, which is the entire point of spooling.
+async function writeNDJSON(filePath, rows) {
+  var ws = fs.createWriteStream(filePath, { encoding: 'utf8' });
+  var count = 0;
+  var bytes = 0;
+  try {
+    for (var i = 0; i < rows.length; i++) {
+      var line = JSON.stringify(rows[i]) + '\n';
+      bytes += Buffer.byteLength(line);
+      count++;
+      if (!ws.write(line)) {
+        await new Promise(function(resolve, reject) {
+          ws.once('drain', resolve);
+          ws.once('error', reject);
+        });
+      }
+    }
+  } finally {
+    await new Promise(function(resolve, reject) {
+      ws.end(resolve);
+      ws.once('error', reject);
+    });
+  }
+  return { rows: count, bytes: bytes };
+}

package/lib/builtins/file/upload.js

@@ -28,25 +28,25 @@ module.exports = {
       description: 'local | sftp | sharepoint | google' },
     { name: 'sourcePath',    type: 'string',  required: true, order: 2,
       description: 'File path (local) or key/id (remote sources)' },
-    { name: 'sourceConfig',  type: 'object',  default: {}, order: 3,
+    { name: 'sourceConfig',  type: 'object',  default: {}, order: 3, group: 'Source & format',
       description: 'Source-specific config (SFTP creds, SharePoint site, etc.)' },
 
     // FORMAT
     { name: 'format',        type: 'string',  required: true, default: 'csv', order: 4,
       description: 'csv | excel | txt | json' },
-    { name: 'formatConfig',  type: 'object',  default: {}, order: 5,
+    { name: 'formatConfig',  type: 'object',  default: {}, order: 5, group: 'Source & format',
       description: 'Format-specific options (delimiter, sheet name, etc.)' },
 
     // TARGET
     { name: 'dbType',        type: 'string',  required: true, default: 'postgres', order: 10 },
     { name: 'dbConnection',  type: 'object',  required: true, order: 11 },
     { name: 'targetTable',   type: 'string',  required: true, order: 12 },
-    { name: 'primaryKeys',   type: 'array',   order: 13 },
+    { name: 'primaryKeys',   type: 'array',   order: 13, group: 'Advanced' },
 
     // CONTROL
-    { name: 'movementId',    type: 'string',  order: 20 },
-    { name: 'batchSize',     type: 'number',  default: 5000, order: 21 },
-    { name: 'concurrency',   type: 'number',  default: 4,    order: 22 }
+    { name: 'movementId',    type: 'string',  order: 20, group: 'Advanced' },
+    { name: 'batchSize',     type: 'number',  default: 5000, order: 21, group: 'Performance' },
+    { name: 'concurrency',   type: 'number',  default: 4,    order: 22, group: 'Performance' }
   ],
 
   execute: async function(ctx) {

package/lib/builtins/index.js

@@ -27,6 +27,15 @@ module.exports = {
   dbFetch:      require('./db/fetch'),
   dbPush:       require('./db/push'),
   dbQuery:      require('./db/query'),
+  // CALLING a procedure, as opposed to moving what it returns. db-move can
+  // still read from one (mode: 'procedure') and both build the statement with
+  // drivers/db/procedure.js, so there is one answer to "how is a procedure
+  // called" rather than one per caller.
+  dbProcedure:  require('./db/procedure'),
+  // One window of rows, source DB to target DB, in a single streamed pass —
+  // fetchStream piped straight into upload() rather than staged through an
+  // NDJSON file the way dbFetch → dbPush does. See db/move.js.
+  dbMove:       require('./db/move'),
 
   // DB introspection — list tables/views/procedures, or one table's columns.
   dbListTables:     require('./db/list-tables'),
@@ -36,5 +45,19 @@ module.exports = {
 
   // File actions — factory-shaped for the same reason (meta store binding).
   fileUpload:   require('./file/upload'),
-  fileMove:     require('./file/move')
+  fileMove:     require('./file/move'),
+
+  // Email actions. Inbound routes to getInboundProvider(input.emailType)
+  // (imap today), outbound to getOutboundProvider (smtp) — see
+  // lib/drivers/email/. Peer deps (imapflow, mailparser, nodemailer) are all
+  // optional and lazy-required, so requiring this file never pulls them in.
+  //
+  // MESSAGE IDS ARE FOLDER-SCOPED. Every message-addressed action takes a
+  // `folder`, and a move CHANGES the id — so within one workflow, do the
+  // downloads and deletes first and move the message last.
+  emailRead:                require('./email/read'),
+  emailMove:                require('./email/move'),
+  emailDelete:              require('./email/delete'),
+  emailDownloadEmail:       require('./email/download-email'),
+  emailDownloadAttachments: require('./email/download-attachments')
 };