@xeplr/actions 1.1.1 → 1.1.6

package/lib/drivers/db/mssql.js

@@ -31,7 +31,7 @@ var TYPE_MAP = {
   string:   'NVARCHAR(MAX)',
   number:   'DECIMAL(38,10)',
   boolean:  'BIT',
-  date:     'DATETIME2',
+  date:     'DATE',
   datetime: 'DATETIME2',
   object:   'NVARCHAR(MAX)',
   array:    'NVARCHAR(MAX)'
@@ -46,9 +46,30 @@ var NATIVE_TO_LOGICAL = {
   money: 'number', smallmoney: 'number',
   bit: 'boolean',
   datetime: 'datetime', datetime2: 'datetime', smalldatetime: 'datetime',
-  date: 'datetime', time: 'datetime', datetimeoffset: 'datetime'
+  // 'date' maps to its OWN logical type — see reconcile.js.
+  date: 'date', time: 'datetime', datetimeoffset: 'datetime'
 };
 
+
+// A calendar date, as YYYY-MM-DD, with NO timezone conversion.
+//
+// toISOString() would convert to UTC first, which is exactly the bug: a Date
+// holding 2026-01-05 local becomes 2026-01-04 in UTC anywhere east of
+// Greenwich. The local getters are the right ones here precisely because a
+// business date has no instant to convert.
+function toDateOnly(v) {
+  if (v === null || v === undefined) return v;
+  if (v instanceof Date) {
+    if (isNaN(v.getTime())) return null;
+    return v.getFullYear() + '-' +
+      String(v.getMonth() + 1).padStart(2, '0') + '-' +
+      String(v.getDate()).padStart(2, '0');
+  }
+  // Already a date string — take the date part and leave the rest alone.
+  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
+  return m ? m[1] : v;
+}
+
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
 
@@ -92,7 +113,13 @@ async function query(pool, sql, params) {
   var rowCount = Array.isArray(r.rowsAffected)
     ? r.rowsAffected.reduce(function(a, b) { return a + b; }, 0)
     : rows.length;
-  return { rows: rows, rowCount: rowCount };
+  // recordset.columns is present on an EMPTY recordset too — mssql describes
+  // the result's shape independently of how many rows matched, which is
+  // exactly what a caller listing a query's columns needs. It's keyed by name
+  // with an `index`, so sort by that to keep the SELECT's own order.
+  var meta = (r.recordset && r.recordset.columns) || {};
+  var columns = Object.keys(meta).sort(function(a, b) { return meta[a].index - meta[b].index; });
+  return { rows: rows, rowCount: rowCount, columns: columns };
 }
 
 function toMssqlType(type) { return TYPE_MAP[type] || 'NVARCHAR(MAX)'; }
@@ -257,6 +284,8 @@ function coerceValue(v, type) {
       return v;                    // let SQL Server reject
 
     case 'date':
+      return toDateOnly(v);
+
     case 'datetime':
       return toMssqlDatetime(v);
 

package/lib/drivers/db/mysql.js

@@ -28,7 +28,7 @@ var TYPE_MAP = {
   string:   'LONGTEXT',
   number:   'DECIMAL(38,10)',
   boolean:  'TINYINT(1)',
-  date:     'DATETIME(6)',
+  date:     'DATE',
   datetime: 'DATETIME(6)',
   object:   'JSON',
   array:    'JSON'
@@ -41,11 +41,33 @@ var NATIVE_TO_LOGICAL = {
   int: 'number', integer: 'number', bigint: 'number', smallint: 'number',
   mediumint: 'number', tinyint: 'number', decimal: 'number', numeric: 'number',
   float: 'number', double: 'number', bit: 'boolean',
-  date: 'datetime', datetime: 'datetime', timestamp: 'datetime',
+  // 'date' maps to its OWN logical type — see reconcile.js. A DATE column
+  // created as DATETIME acquires a midnight that shifts under a timezone.
+  date: 'date', datetime: 'datetime', timestamp: 'datetime',
   time: 'datetime', year: 'datetime',
   json: 'object'
 };
 
+
+// A calendar date, as YYYY-MM-DD, with NO timezone conversion.
+//
+// toISOString() would convert to UTC first, which is exactly the bug: a Date
+// holding 2026-01-05 local becomes 2026-01-04 in UTC anywhere east of
+// Greenwich. The local getters are the right ones here precisely because a
+// business date has no instant to convert.
+function toDateOnly(v) {
+  if (v === null || v === undefined) return v;
+  if (v instanceof Date) {
+    if (isNaN(v.getTime())) return null;
+    return v.getFullYear() + '-' +
+      String(v.getMonth() + 1).padStart(2, '0') + '-' +
+      String(v.getDate()).padStart(2, '0');
+  }
+  // Already a date string — take the date part and leave the rest alone.
+  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
+  return m ? m[1] : v;
+}
+
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
 
@@ -77,13 +99,49 @@ async function close(pool) {
 }
 
 // Normalize mysql2's `[rows|ResultSetHeader, fields]` to Postgres shape.
+//
+// The second element is the field list, which mysql2 returns even for a
+// SELECT that matched nothing — so `columns` describes the result's shape
+// when there is not a single row to infer it from.
 async function query(pool, sql, params) {
   var res = await pool.query(sql, params || []);
   var out = res[0];
+  var fields = res[1];
+
+  // A CALL ANSWERS WITH MULTIPLE RESULT SETS, and that is not an edge case —
+  // it is what every stored procedure that SELECTs does. mysql2 returns
+  // `[ [rows], OkPacket ]` for one, so `out` is an array whose first element
+  // is itself an array, and `fields` is `[ [fields], undefined ]`.
+  //
+  // Read as a plain SELECT that produced: rows = [ [ {...} ], OkPacket ] — a
+  // result set wrapped in another one — and columns mapped `f.name` over that
+  // undefined second entry, which threw "Cannot read properties of undefined
+  // (reading 'name')". So a procedure returning rows failed on MySQL with an
+  // error naming nothing to do with procedures. Nothing hit it before because
+  // nothing could call one: db-move's procedure mode is only exercised against
+  // mssql/postgres in practice, and there was no other caller.
+  //
+  // THE FIRST result set is the answer. A procedure that SELECTs twice is
+  // telling the caller two things and this action's shape has room for one;
+  // taking the first is the same rule every client library applies, rather
+  // than concatenating rows of different widths into one nonsense list.
+  if (Array.isArray(out) && out.length && Array.isArray(out[0])) {
+    var rows = out[0];
+    var firstFields = (Array.isArray(fields) && fields[0]) || [];
+    return {
+      rows: rows,
+      rowCount: rows.length,
+      columns: firstFields.map(function(f) { return f.name; })
+    };
+  }
+
+  var columns = (fields || []).map(function(f) { return f.name; });
   if (Array.isArray(out)) {
-    return { rows: out, rowCount: out.length };                     // SELECT
+    return { rows: out, rowCount: out.length, columns: columns };   // SELECT
   }
-  return { rows: [], rowCount: (out && out.affectedRows) || 0 };    // DML
+  // DML, and a CALL whose procedure returns nothing at all — both answer with
+  // an OkPacket rather than a result set.
+  return { rows: [], rowCount: (out && out.affectedRows) || 0, columns: [] };
 }
 
 function toMysqlType(type) { return TYPE_MAP[type] || 'LONGTEXT'; }
@@ -215,6 +273,8 @@ function coerceValue(v, type) {
       return v;                    // let MySQL reject
 
     case 'date':
+      return toDateOnly(v);
+
     case 'datetime':
       return toMysqlDatetime(v);
 

package/lib/drivers/db/postgres.js

@@ -31,7 +31,7 @@ var TYPE_MAP = {
   string:   'TEXT',
   number:   'NUMERIC',
   boolean:  'BOOLEAN',
-  date:     'TIMESTAMPTZ',
+  date:     'DATE',
   datetime: 'TIMESTAMPTZ',
   object:   'JSONB',
   array:    'JSONB'
@@ -58,12 +58,42 @@ async function close(pool) {
   if (pool) await pool.end();
 }
 
+// `columns` is the query's OUTPUT COLUMNS, which the server describes whether
+// or not any row matched. Callers that need the shape of a result — a report
+// listing its columns, say — must not have to infer it from the first row,
+// because a query returning nothing still has columns.
+//
+// Attached to pg's own Result rather than wrapping it: callers already treat
+// this as the canonical shape the other drivers normalize TO, so replacing
+// the object risks dropping a property something else reads.
 async function query(pool, sql, params) {
-  return pool.query(sql, params || []);
+  var result = await pool.query(sql, params || []);
+  result.columns = (result.fields || []).map(function(f) { return f.name; });
+  return result;
 }
 
 function toPgType(type) { return TYPE_MAP[type] || 'TEXT'; }
 
+// A calendar date, as YYYY-MM-DD, with NO timezone conversion.
+//
+// toISOString() would convert to UTC first, which is exactly the bug: a Date
+// holding 2026-01-05 local becomes 2026-01-04 in UTC anywhere east of
+// Greenwich. The local getters are the right ones here precisely because a
+// business date has no instant to convert.
+function toDateOnly(v) {
+  if (v === null || v === undefined) return v;
+  if (v instanceof Date) {
+    if (isNaN(v.getTime())) return null;
+    return v.getFullYear() + '-' +
+      String(v.getMonth() + 1).padStart(2, '0') + '-' +
+      String(v.getDate()).padStart(2, '0');
+  }
+  // Already a date string — take the date part and leave the rest alone.
+  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
+  return m ? m[1] : v;
+}
+
+
 // Double-quote a Postgres identifier, escaping embedded quotes.
 function quoteIdent(name) {
   return '"' + String(name).replace(/"/g, '""') + '"';
@@ -193,6 +223,9 @@ function coerceValue(v, type) {
       if (typeof v === 'number')     return v !== 0;
       return v;                       // let PG reject
 
+    case 'date':
+      return toDateOnly(v);
+
     case 'datetime':
       if (v instanceof Date)         return v.toISOString();
       return v;                       // strings pass through; PG parses

package/lib/drivers/db/procedure.js

@@ -0,0 +1,222 @@
+// CALLING A STORED PROCEDURE — one implementation, three dialects.
+//
+// This is the only place in the codebase that knows how a procedure is called.
+// It lived inside db-move's procedurePlan, which was the wrong home for two
+// reasons and both of them showed:
+//
+//   1. It could only be reached by MOVING data. A procedure that returns
+//      nothing — a nightly recalculation, a flag flipped, a queue drained —
+//      had no way to be called at all, because db-move requires a target
+//      table and its whole shape is "read rows, write them somewhere".
+//   2. A second caller would have had to copy it. Dialect-specific call
+//      syntax copied twice is dialect-specific call syntax that disagrees with
+//      itself within a release.
+//
+// So the mover now asks this for its SQL like anybody else. db-procedure (the
+// action) and db-move (the mover) build the identical statement, because it is
+// the identical function.
+//
+// ── the dialects genuinely differ, and not only in spelling ──────────────
+//
+//   mssql     EXEC dbo.usp_x @region = ?, @minimum = ?
+//             Returns its result set directly, and works whether or not there
+//             is one. The only dialect where one form covers both cases.
+//
+//   mysql     CALL usp_x(?, ?)
+//             No named-argument syntax exists, so parameters are POSITIONAL
+//             and must be given in the order the procedure declares them. A
+//             caller that names them is not wrong here, it is just not helped.
+//
+//   postgres  SELECT * FROM fn(region => ?)   ← when you want the rows
+//             CALL proc(region => ?)          ← when you do not
+//             These are two different database objects. A Postgres PROCEDURE
+//             (CREATE PROCEDURE, called with CALL) returns nothing a client
+//             can read; a set-returning FUNCTION is the thing that behaves
+//             like "a procedure that gives you rows". Choosing between them is
+//             what `returnsRows` is for, and it is why db-move can only ever
+//             use the function form: it exists to move the rows.
+//
+// Parameters are always BOUND, never interpolated. A procedure name is an
+// identifier and is quoted; its arguments are values and travel as binds.
+
+/**
+ * Dialect placeholder for bind param n (0-based).
+ *
+ * Exported because the caller has to build the params array in the same order
+ * as the marks, and there is no reason for two definitions of `$1`.
+ */
+function placeholders(dbType) {
+  if (dbType === 'mysql')  return function()  { return '?'; };
+  if (dbType === 'mssql')  return function(n) { return '@p' + n; };
+  return function(n) { return '$' + (n + 1); };   // postgres
+}
+
+/**
+ * A procedure/table-function name can be schema-qualified ("dbo.usp_x") —
+ * driver.quoteIdent treats a dot as part of a single identifier and would
+ * bracket the whole string as one name ("[dbo.usp_x]"), which the database
+ * then cannot resolve at all. Table/column names elsewhere never legitimately
+ * contain a dot, which is why this is its own function rather than a change to
+ * quoteIdent itself — that one stays exactly as narrow as it always was for
+ * the callers that rely on a dot never being special.
+ */
+function quoteQualifiedIdent(driver, name) {
+  return String(name).split('.').map(function(part) { return driver.quoteIdent(part); }).join('.');
+}
+
+/**
+ * A parameter value, made safe to bind — or a clear error instead of a
+ * cryptic one from three layers down (the mssql driver's own type inference
+ * falls back to NVARCHAR for anything it doesn't recognize as a number,
+ * boolean or date, and NVARCHAR's own validation then rejects a plain object
+ * with "Validation failed for parameter 'pN'. Invalid string." — naming the
+ * placeholder, not the parameter someone actually typed, and giving no hint
+ * that the real problem is the value's shape).
+ *
+ * A numeric-looking string ('2026') is coerced to a real number rather than
+ * left for the database to implicitly convert from NVARCHAR.
+ *
+ * AN EMPTY STRING IS NULL, and that rule is load-bearing rather than tidy: a
+ * step editor renders every unset field as '', so a procedure's optional date
+ * parameter left blank arrives here as an empty string. Passing that through
+ * fails on a date or an int in all three dialects, and "" is not what the
+ * person who left the box alone meant — they meant nothing.
+ */
+function normalizeParamValue(name, value) {
+  if (value === undefined || value === '') return null;
+  if (value === null || typeof value === 'number' || typeof value === 'boolean' || value instanceof Date) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    if (/^-?\d+$/.test(value)) return parseInt(value, 10);
+    if (/^-?\d+\.\d+$/.test(value)) return parseFloat(value);
+    return value;
+  }
+  throw new Error('parameter "' + name + '" must be text, a number, or a date — got ' + typeof value + '.');
+}
+
+/**
+ * Normalise the caller's parameter list.
+ *
+ * Accepts `[{ name, value }]` or bare values, mixed. Named entries are matched
+ * by NAME where the dialect supports it, because getting a procedure's
+ * declared parameter ORDER right from outside it is easy to get wrong
+ * silently — the call succeeds and the arguments are in the wrong slots.
+ */
+function normalizeParams(params) {
+  return (params || []).map(function(p) {
+    var raw = (p && typeof p === 'object' && 'value' in p) ? p : { name: null, value: p };
+    return { name: raw.name || null, value: normalizeParamValue(raw.name || '(unnamed)', raw.value) };
+  });
+}
+
+/**
+ * A WINDOW, handed to a procedure as its own parameters.
+ *
+ * Everywhere else in this codebase a window becomes a WHERE. A procedure has
+ * no WHERE to add one to — `SELECT … FROM (EXEC p) x` is not a thing in any of
+ * the three dialects — so the only way to narrow one is to pass the edges in
+ * and let the procedure do it. Which parameters those are is knowledge only
+ * the caller has, so the caller names them.
+ *
+ * REFUSED when they are not named, rather than quietly dropping the window.
+ * Dropping it means the procedure returns everything it has, the run reports
+ * success, and an incremental job silently reprocesses its whole history every
+ * night — which costs exactly what incremental was meant to save while looking
+ * like it worked.
+ *
+ * HALF-OPEN, from <= x < to, and the procedure is expected to honour that.
+ * Jobs pins `to` once per run and starts the next run at exactly that value
+ * (see @xeplr/jobs' buildWindow and migrations/0006) — so a procedure that
+ * treats `to` as inclusive double-counts the boundary row on every run.
+ *
+ * A null edge is passed through as null rather than skipped: an unbounded
+ * lower edge is what a first incremental run legitimately has, and a
+ * procedure that receives NULL can decide what that means. Skipping the
+ * parameter instead would shift every later argument by one on MySQL, where
+ * they are positional.
+ */
+function windowParams(win) {
+  if (!win) return [];
+  if (!win.fromParam && !win.toParam) {
+    throw new Error(
+      'a window on a procedure needs window.fromParam / window.toParam — a procedure cannot ' +
+      'be filtered from outside. Give the procedure its own date parameters, or drop the window.');
+  }
+  var out = [];
+  if (win.fromParam) out.push({ name: win.fromParam, value: win.from == null ? null : win.from });
+  if (win.toParam)   out.push({ name: win.toParam,   value: win.to == null ? null : win.to });
+  return out;
+}
+
+/**
+ * Build the call.
+ *
+ * @param {object}  opts
+ * @param {object}  opts.driver      - the db driver, for quoting
+ * @param {string}  opts.dbType      - postgres | mysql | mssql
+ * @param {string}  opts.name        - procedure name, optionally schema-qualified
+ * @param {Array}   [opts.params]    - [{ name, value }] or bare values
+ * @param {object}  [opts.window]    - { from, to, fromParam, toParam } — appended
+ *                                     as two more named parameters, AFTER the
+ *                                     caller's own, which is what keeps a MySQL
+ *                                     positional call in the order the author
+ *                                     wrote it plus the window at the end.
+ * @param {boolean} [opts.returnsRows=true] - postgres only: SELECT * FROM fn()
+ *                                     when true, CALL proc() when false. The
+ *                                     other two dialects have one form each.
+ * @returns {{ sql: string, params: Array, named: boolean }}
+ *          `named` reports whether the dialect actually honoured the names —
+ *          false on MySQL, so a caller can warn rather than let somebody
+ *          believe their names did something.
+ */
+function buildProcedureCall(opts) {
+  var dbType = opts.dbType;
+  var name = opts.name;
+  if (!name) throw new Error('a procedure call needs a procedure name');
+
+  var entries = normalizeParams((opts.params || []).concat(windowParams(opts.window)));
+  var returnsRows = opts.returnsRows !== false;
+  var ph = placeholders(dbType);
+  var supportsNames = dbType === 'mssql' || dbType === 'postgres';
+
+  var marks = entries.map(function(p, i) {
+    var mark = ph(i);
+    if (!p.name || !supportsNames) return mark;
+    if (dbType === 'mssql') return '@' + p.name + ' = ' + mark;
+    return p.name + ' => ' + mark;              // postgres named-argument call
+  }).join(', ');
+
+  var quoted = quoteQualifiedIdent(opts.driver, name);
+  var sql;
+  switch (dbType) {
+    case 'mssql':
+      sql = 'EXEC ' + quoted + (marks ? ' ' + marks : '');
+      break;
+    case 'mysql':
+      sql = 'CALL ' + quoted + '(' + marks + ')';
+      break;
+    case 'postgres':
+      sql = returnsRows
+        ? 'SELECT * FROM ' + quoted + '(' + marks + ')'
+        : 'CALL ' + quoted + '(' + marks + ')';
+      break;
+    default:
+      throw new Error('calling a procedure is not supported for "' + dbType + '"');
+  }
+
+  return {
+    sql: sql,
+    params: entries.map(function(p) { return p.value; }),
+    named: supportsNames && entries.some(function(p) { return Boolean(p.name); })
+  };
+}
+
+module.exports = {
+  buildProcedureCall: buildProcedureCall,
+  windowParams: windowParams,
+  normalizeParams: normalizeParams,
+  normalizeParamValue: normalizeParamValue,
+  quoteQualifiedIdent: quoteQualifiedIdent,
+  placeholders: placeholders
+};

package/lib/drivers/email/config.js

@@ -0,0 +1,122 @@
+// WHERE AN EMAIL ACTION GETS ITS MAILBOX FROM.
+//
+// One checkbox: `useCustomConnection`.
+//
+//   OFF (default) — the mail service this install already runs. Every product
+//                   here needs email for notifications anyway, so it is always
+//                   configured; a step should not have to ask again.
+//   ON            — a connection supplied on the step, for a workflow that
+//                   talks to a mailbox the platform does not own (a client's,
+//                   a shared alias).
+//
+// Off is the default deliberately. Requiring host/user/password on every step
+// meant pasting credentials into a workflow document — visible to anyone who
+// can open the builder, duplicated per step, and stale the day the mail server
+// moves.
+
+// ── inbound (IMAP) ──────────────────────────────────────────────────────
+
+function num(v, fallback) {
+  if (v === undefined || v === null || v === '') return fallback;
+  var n = Number(v);
+  return isFinite(n) ? n : fallback;
+}
+
+function bool(v, fallback) {
+  if (v === undefined || v === null || v === '') return fallback;
+  var s = String(v).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].indexOf(s) !== -1) return true;
+  if (['0', 'false', 'no', 'off'].indexOf(s) !== -1) return false;
+  return fallback;
+}
+
+/**
+ * The install's IMAP mailbox, from env.
+ *
+ * IMAP_* wins, then SMTP_* — a mailbox is usually one account, and an install
+ * that set SMTP credentials for sending has almost always given the same ones
+ * for reading. Falling back beats making people set the same secret twice
+ * under a second name.
+ *
+ * NOTE there is no "system IMAP service" the way there is a system MAIL
+ * SENDER: @xeplr/email is outbound only. So for inbound, "system" means this
+ * env block and nothing else.
+ */
+function imapFromEnv() {
+  var env = process.env;
+  var host = env.IMAP_HOST || env.SMTP_HOST;
+  var user = env.IMAP_USER || env.SMTP_USER;
+  var password = env.IMAP_PASS || env.SMTP_PASS;
+
+  if (!host || !user || !password) {
+    var missing = [];
+    if (!host) missing.push('IMAP_HOST (or SMTP_HOST)');
+    if (!user) missing.push('IMAP_USER (or SMTP_USER)');
+    if (!password) missing.push('IMAP_PASS (or SMTP_PASS)');
+    var err = new Error(
+      'This install has no mailbox configured — missing ' + missing.join(', ') +
+      '. Set those, or tick "Provide my own connection" on the step and supply one.'
+    );
+    err.code = 'EMAIL_SYSTEM_NOT_CONFIGURED';
+    throw err;
+  }
+
+  var tls = {};
+  if (env.IMAP_TLS_REJECT_UNAUTHORIZED !== undefined) tls.rejectUnauthorized = bool(env.IMAP_TLS_REJECT_UNAUTHORIZED, undefined);
+  if (env.IMAP_TLS_SERVERNAME) tls.servername = env.IMAP_TLS_SERVERNAME;
+
+  return {
+    host: host,
+    port: num(env.IMAP_PORT, 993),
+    secure: bool(env.IMAP_SECURE, true),
+    user: user,
+    password: password,
+    connectionTimeout: num(env.IMAP_CONNECTION_TIMEOUT, undefined),
+    socketTimeout: num(env.IMAP_SOCKET_TIMEOUT, undefined),
+    tls: Object.keys(tls).length ? tls : undefined
+  };
+}
+
+/**
+ * Resolve the inbound connection an action should use.
+ *
+ * @param {object} input  the action's own input (connectionSource, connection)
+ */
+function resolveInbound(input) {
+  input = input || {};
+  if (!input.useCustomConnection) return imapFromEnv();
+  if (!input.connection || !input.connection.host) {
+    throw new Error('"Provide my own connection" is on but no connection was supplied — set { host, user, password }, or turn it off to use this install\'s mailbox.');
+  }
+  return input.connection;
+}
+
+// ── outbound (send) ─────────────────────────────────────────────────────
+
+/**
+ * Whether this action should hand off to the install's own mail sender.
+ *
+ * Outbound "system" is NOT an env block the way inbound is — it is
+ * @xeplr/utils' sendEmail, which is what @xeplr/email configures at startup
+ * and which may be pointed at SES, Azure or Brevo rather than SMTP. Rebuilding
+ * an SMTP connection out of env here would quietly ignore that and send
+ * through the wrong provider, so the system path delegates instead.
+ */
+function usesSystemSender(input) {
+  return !(input && input.useCustomConnection);
+}
+
+function resolveOutbound(input) {
+  input = input || {};
+  if (!input.connection || !input.connection.host) {
+    throw new Error('"Provide my own connection" is on but no connection was supplied — set { host, user, password, from }, or turn it off to use this install\'s email service.');
+  }
+  return input.connection;
+}
+
+module.exports = {
+  imapFromEnv: imapFromEnv,
+  resolveInbound: resolveInbound,
+  resolveOutbound: resolveOutbound,
+  usesSystemSender: usesSystemSender
+};

package/lib/drivers/email/files.js

@@ -0,0 +1,76 @@
+// Shared on-disk helpers for the email actions that write files
+// (email-download-email, email-download-attachments).
+//
+// Output goes to XEPLR_ACTIONS_TMP_DIR — the SAME directory db-fetch spools
+// NDJSON into — so every artifact an action leaves behind is swept by one
+// mechanism rather than one per action family. An explicit `outDir` input
+// still wins for the case where a later step (or another service) needs the
+// file somewhere specific.
+
+var crypto = require('crypto');
+var path   = require('path');
+var fs     = require('fs');
+var fsp    = require('fs/promises');
+var os     = require('os');
+
+// Short random prefix. Attachment names collide constantly in mail —
+// "invoice.pdf" from fifty senders — and a download that silently overwrites
+// the previous one is the kind of bug you find a quarter later in the numbers.
+function shortId() {
+  return crypto.randomBytes(5).toString('hex');
+}
+
+// Anything outside word/dot/dash becomes '_'. A filename arriving from a
+// mailbox is attacker-controlled: without this, a name like
+// "../../etc/cron.d/x" would escape the output directory entirely.
+// Capped so a pathological name can't blow the filesystem's limit.
+function sanitizeFilename(name) {
+  var out = String(name || 'attachment').replace(/[^\w.\-]+/g, '_').slice(0, 180);
+  // Stripping separators is not enough on its own: a name of "." or ".." has
+  // none left and is STILL a traversal, because path.join(dir, '..') resolves
+  // above dir. Any all-dots name gets replaced outright.
+  if (/^\.+$/.test(out)) return 'attachment';
+  return out;
+}
+
+// Explicit outDir wins; otherwise the same temp root the rest of the actions
+// use. Created recursively — a first run has no directory yet.
+async function resolveOutDir(outDir) {
+  var dir = outDir || process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+  await fsp.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+// Filter predicate for attachment selection. Both filters optional; with
+// neither, everything matches.
+//   extension        — 'pdf' or '.pdf' (case-insensitive suffix)
+//   filenameContains — case-insensitive substring
+function attachmentMatches(name, extension, filenameContains) {
+  var n = String(name || '').toLowerCase();
+  if (extension) {
+    var ext = String(extension).toLowerCase().replace(/^\./, '');
+    if (n.slice(-(ext.length + 1)) !== '.' + ext) return false;
+  }
+  if (filenameContains && n.indexOf(String(filenameContains).toLowerCase()) === -1) {
+    return false;
+  }
+  return true;
+}
+
+// On-disk name for a whole-message .eml. Prefers the subject — that is what a
+// human recognises in a folder listing — and falls back to the uid when the
+// message has none. Always prefixed, because "Re: Invoice" is not unique.
+function emlFilename(subject, uid) {
+  var base = sanitizeFilename(subject || ('message_' + uid)).replace(/\.eml$/i, '');
+  return shortId() + '_' + base + '.eml';
+}
+
+module.exports = {
+  shortId: shortId,
+  sanitizeFilename: sanitizeFilename,
+  resolveOutDir: resolveOutDir,
+  attachmentMatches: attachmentMatches,
+  emlFilename: emlFilename,
+  fs: fs,
+  path: path
+};