@xeplr/actions 2.2.1 → 2.2.3

package/README.md

@@ -26,6 +26,7 @@ Everything else is an **optional peer**, required only when an action actually u
 | `mailparser` | `email-read` (unless `body: 'none'`), `email-download-attachments` |
 | `nodemailer` (^10.0.13 — up to 10.0.5 has high-severity advisories) | `email-send` with its own connection |
 | `@xeplr/email` | `email-send` with `templateName` |
+| `@xeplr/push` | `push-send` (the host sets it up at boot: `push.init({ knex })`) |
 | `knex` | the knex meta store |
 | `mongodb`, `ssh2-sftp-client`, `exceljs` | declared, but their drivers/sources are not implemented |
 
@@ -121,7 +122,7 @@ The input is checked exactly as a run checks it.
 
 | previewed (reads, up to 5) | example only (writes or sends; never run) |
 |---|---|
-| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
+| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `push-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
 
 Neither: `db-push`, `db-move`, `http-request` (an outside system, which may change something), `spawn-program`, `file-upload`; a designer asks for an example by hand. `test/previews.test.js` checks it on a real folder, file and Postgres: five rows read and no file spooled, the real count kept, a deleting step's file still there.
 
@@ -137,6 +138,7 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `dbFetch` | `db-fetch` | Stream rows from a table (`mode: 'table'`) or SQL (`mode: 'query'`, `params`). Default `streaming_mode: true` → NDJSON file `{ filePath, format: 'jsonl', bytes, rows }`; `false` → `{ rows, rowCount }`. |
 | `dbPush` | `db-push` | Write `rows` or an NDJSON `filePath` into `targetTable` through the uploader. `primaryKeys` → upsert. |
 | `dbMove` | `db-move` | One window of rows from a source table, query or procedure into a target table in one streamed pass. See [db-move](#db-move). |
+| `dbDump` | `db-dump` | A whole database to one backup file with its own dump program: `pg_dump -Fc` (Postgres, `.dump`) or `mysqldump` (MySQL, `.sql.gz`). See [Backups](#backups-db-dump-and-s3-upload). |
 | `dbProcedure` | `db-procedure` | Call a stored procedure; returns `{ rows, rowCount, procedure, sql }`. See [db-procedure](#db-procedure). |
 | `dbListTables` | `db-list-tables` | `{ tables }` — base tables in a schema/database. |
 | `dbListViews` | `db-list-views` | `{ views }`. |
@@ -144,12 +146,14 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `dbListColumns` | `db-list-columns` | `{ columns }` — `name`, `dataType`, `udtName` and `maxLength` (characters; `-1` is SQL Server `(max)`, `null` when it has none) for one table. |
 | `fileUpload` | `file-upload` | Read a file (`sourceType`, `sourcePath`), parse it (`format`), load it into `targetTable` (`dbType`, `dbConnection`) as a New table, Append or Replace (`mode`, see [Import modes](#import-modes)). Passes `system.onProgress` (`{ rowsRead, batches, rowsWritten }`, per batch) and `system.signal` (stop) to the uploader, as `db-move` does. |
 | `sendEmail` | `email-send` | Send one message. See [Email](#email). |
+| `pushSend` | `push-send` | A push notification on people's phones and computers, even with the app closed, by `emails` and/or `userIds`: `title` (required), `body`, `url` (a page of the app a tap opens), `tag`. Returns `{ devices, sent, removed, failed }`. Through [`@xeplr/push`](https://www.npmjs.com/package/@xeplr/push), which the host sets up. |
 | `emailRead` | `email-read` | List messages, newest first, with `unread_only`, `limit` (1–1000, default 50), `since`, `from_equals`, `from_contains`, `subject_contains`, `body: 'full' \| 'text' \| 'none'`, optional NDJSON spooling. |
 | `emailMove` | `email-move` | Move a message (`messageId`, `folder`) to `toFolder`. |
 | `emailDelete` | `email-delete` | Flag `\Deleted` **and expunge** — permanent, not a move to Trash. |
 | `emailDownloadEmail` | `email-download-email` | Stream the raw message to an `.eml` file, named by `fileName`. `{ count, saved[], path, existing[] }`. |
 | `emailDownloadAttachments` | `email-download-attachments` | Save attachments, optionally filtered by `extension` / `filenameContains`, named by `fileName` (see [Saving files](#saving-files-names-and-a-name-already-taken)). `{ count, saved[], path, skipped, existing[] }`. |
 | `fileList` | `file-list` | The files in a folder, optionally matching `pattern` (`*.csv`, `Bank-2026-??.pdf`), sorted by name or date. `{ files[{ name, path, size, modifiedAt }], count }`. "Is it there?" is the exact name and `count`. See [Where files are](#where-files-are-one-data-root-a-folder-per-tenant). |
+| `s3Upload` | `s3-upload` | One file to an S3 bucket (or an S3-compatible `endpoint`), in parts, with a SHA-256 checksum. Only writes. See [Backups](#backups-db-dump-and-s3-upload). |
 | `fileRead` | `file-read` | A CSV, text, Excel, JSON or NDJSON file as rows (format from the extension). `{ rows, count, columns, truncated }`, at most `maxRows` (50,000). |
 | `fileMove` | `file-move` | Move or copy a file into a folder (made if missing) or to a new name; `ifExists` as every saving step. `{ path, name, moved, skipped }`. |
 | `fileDelete` | `file-delete` | Delete one file, **permanently** (no trash; `file-move` to a "processed" folder is the reversible one). Never a folder. `ifMissing`: `fail` (default) or `skip`. `{ path, deleted, skipped }`. |
@@ -204,6 +208,60 @@ For `mode: 'table'` the source's declared column types (`getTableSchema`) are pa
 
 Message ids are IMAP UIDs **scoped to `folder`**, and a move changes the id — download and delete before moving.
 
+## Backups: `db-dump` and `s3-upload`
+
+A database's backup is two steps: dump it to a file, then send the file away.
+
+```js
+var dumped = await runAction({ name: 'db-dump', input: {
+  dbType: 'postgres', connectionInfoId: 'main-server',   // the server's login, resolved by the host
+  database: 'shop'
+} })
+// → { filePath: '<tenant>/backups/shop-2026-11-13T02-00-05.dump', fileName, bytes, sha256, dbType, database, durationMs }
+
+await runAction({ name: 's3-upload', input: {
+  connectionInfoId: 'backup-bucket',                      // { bucket, region, accessKeyId, secretAccessKey, prefix? }
+  filePath: dumped.output.filePath, deleteAfter: true
+} })
+// → { bucket, key: 'backups/shop-2026-11-13T02-00-05.dump', bytes, etag, versionId, deleted: true }
+```
+
+**db-dump**
+
+| input | |
+|---|---|
+| `dbType` | `postgres` or `mysql`. `mssql` is refused: not supported yet. |
+| `connection` | The server's login `{ host, port, user, password }`. |
+| `database` | Required: which database on that server. |
+| `folder` | In the tenant's folder; default `backups`. |
+| `fileName` | Default `<database>-<UTC time>.dump` (Postgres) or `.sql.gz` (MySQL). A name, not a path. |
+
+- **Postgres:** `pg_dump -Fc --no-owner --no-acl` — the custom format, already compressed, restored with `pg_restore`. `pg_dump` must be **at least the server's version** (it refuses an older one, and the step says so).
+- **MySQL / MariaDB:** `mysqldump --single-transaction --quick --routines --triggers --events --databases <db>`, gzipped as it is written.
+- **No shell, ever.** The program is run with an argument list built here; the password goes in its environment (`PGPASSWORD`, `MYSQL_PWD`), never on the command line where `ps` shows it. A database, host or user starting with `-` is refused (it would be read as an option).
+- **Written under `<name>.partial`, renamed only when the program ends cleanly.** A failure removes it and fails the step with the end of what the program said, the password taken out. A program that is not installed is named ("pg_dump is not installed on this server").
+- `system.signal` stops it (the program is killed); `system.onProgress({ bytes })` every second.
+
+**s3-upload**
+
+| input | |
+|---|---|
+| `connection` | `{ bucket, region, accessKeyId, secretAccessKey, prefix?, sessionToken?, endpoint?, forcePathStyle? }`. Without `accessKeyId` the SDK's own chain is used (an EC2 role). `endpoint` for an S3-compatible store. |
+| `filePath` | The file, in the tenant's folder. |
+| `key` | Default `<prefix>/<file name>`. |
+| `deleteAfter` | `true`: the local file is deleted once it is uploaded. |
+| `contentType` | Default `application/octet-stream`. |
+
+- **Streamed in 16 MB parts** (`@aws-sdk/lib-storage`), so any size needs little memory. Every part carries a **SHA-256 checksum** — required by a bucket with Object Lock, and checked by S3.
+- **It only writes.** No list, get or head of the bucket, so the key it uses needs `s3:PutObject` and `s3:AbortMultipartUpload` (a failed upload is aborted) on the prefix, and nothing else:
+
+  ```json
+  { "Effect": "Allow", "Action": ["s3:PutObject", "s3:AbortMultipartUpload"], "Resource": "arn:aws:s3:::<bucket>/backups/*" }
+  ```
+- Peers, optional: `@aws-sdk/client-s3` and `@aws-sdk/lib-storage` (`^3`). Missing → the step says to install them.
+
+`test/backup/` checks both: the dump programs with a stand-in on `PATH` (arguments, password only in the environment, a failure leaving no file), a real `pg_dump` restored with `pg_restore --list` when Postgres is here, and the upload against an S3 stand-in (one PUT, then parts, a SHA-256 checksum, never a read).
+
 ## Data operation
 
 The step between steps. A fetch returns everything a table holds; an email

package/lib/builtins/db/dump.js

@@ -0,0 +1,199 @@
+// db-dump action — a whole database to one backup file, by the database's own
+// dump program: pg_dump (Postgres) or mysqldump (MySQL / MariaDB).
+//
+//   postgres  pg_dump -Fc --no-owner --no-acl → <db>-<when>.dump (custom
+//             format: already compressed, restored with pg_restore)
+//   mysql     mysqldump --single-transaction --quick --routines --triggers
+//             --events, gzipped here → <db>-<when>.sql.gz
+//   mssql     refused: not supported yet
+//
+// THE PROGRAM IS RUN WITH AN ARGUMENT LIST, never a shell, and only these two
+// programs, with arguments built here — nothing from the input reaches the
+// command line except the host, port, user and database, each passed as its
+// own argument. The password goes in the program's environment (PGPASSWORD,
+// MYSQL_PWD), never on the command line, where `ps` would show it.
+//
+// THE FILE is written under a temporary name and renamed only once the
+// program has finished cleanly, so a half-written dump never looks like a
+// backup. A failure removes it and fails the step with the end of what the
+// program said (stderr), the password taken out. Inside the tenant's own
+// folder (lib/dataDir.js), `backups/` unless `folder` says otherwise.
+//
+// A stop (system.signal) kills the program. system.onProgress({ bytes })
+// reports how much is written, every second or so.
+
+var fs = require('fs');
+var path = require('path');
+var zlib = require('zlib');
+var crypto = require('crypto');
+var { spawn } = require('child_process');
+var dataDir = require('../../dataDir');
+
+var PROGRAMS = {
+  postgres: { bin: 'pg_dump', ext: '.dump', gzip: false, port: 5432 },
+  mysql:    { bin: 'mysqldump', ext: '.sql.gz', gzip: true, port: 3306 }
+};
+var DEFAULT_FOLDER = 'backups';
+var STDERR_KEEP = 2048;
+var PROGRESS_MS = 1000;
+
+/** "2026-11-13T02-00-05" — a file name's time, UTC. */
+function stamp(date) {
+  return date.toISOString().slice(0, 19).replace(/:/g, '-');
+}
+
+/** A database name made safe for a file name. */
+function fileSafe(name) {
+  return String(name).replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^\.+/, '') || 'database';
+}
+
+/** The program's arguments and environment — the password only in the environment. */
+function commandFor(dbType, conn, database) {
+  var p = PROGRAMS[dbType];
+  var host = String(conn.host || 'localhost');
+  var port = String(conn.port || p.port);
+  var user = conn.user ? String(conn.user) : null;
+  var env = Object.assign({}, process.env);
+  if (dbType === 'postgres') {
+    var args = ['-Fc', '--no-owner', '--no-acl', '-h', host, '-p', port];
+    if (user) args.push('-U', user);
+    args.push('-d', database);
+    delete env.PGPASSWORD;
+    if (conn.password) env.PGPASSWORD = String(conn.password);
+    return { bin: p.bin, args: args, env: env };
+  }
+  var margs = ['--single-transaction', '--quick', '--routines', '--triggers', '--events', '-h', host, '-P', port];
+  if (user) margs.push('-u', user);
+  margs.push('--databases', database);
+  delete env.MYSQL_PWD;
+  if (conn.password) env.MYSQL_PWD = String(conn.password);
+  return { bin: p.bin, args: margs, env: env };
+}
+
+function refuse(message, code) {
+  var err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+module.exports = {
+  name: 'db-dump',
+  // It writes a file, so it is never previewed.
+  example: { filePath: '/data/app/backups/shop-2026-11-13T02-00-05.dump', fileName: 'shop-2026-11-13T02-00-05.dump', bytes: 104857600,
+    sha256: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08', dbType: 'postgres', database: 'shop', durationMs: 42000 },
+  description: 'Back up a whole database to one file with its own dump program — pg_dump (Postgres, custom format) or mysqldump (MySQL, gzipped). Returns { filePath, fileName, bytes, sha256, dbType, database, durationMs }.',
+  requires: [],   // the dump programs are checked when it runs
+
+  inputSchema: [
+    { name: 'dbType', type: 'string', required: true, order: 1,
+      description: 'postgres or mysql (SQL Server: not supported yet).' },
+    { name: 'connection', type: 'object', required: true, order: 2,
+      description: '{ host, port, user, password } — the server\'s login, a saved connection (connectionInfoId) resolved by the host.' },
+    { name: 'database', type: 'string', required: true, order: 3,
+      description: 'The database on that server to back up.' },
+    { name: 'folder', type: 'string', order: 4, group: 'File',
+      description: 'Where in this company\'s data folder the file goes. Default: backups.' },
+    { name: 'fileName', type: 'string', order: 5, group: 'File',
+      description: 'The file\'s name. Default: <database>-<UTC time>.dump (Postgres) or .sql.gz (MySQL).' }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'sha256', type: 'string' }, { name: 'dbType', type: 'string' }, { name: 'database', type: 'string' },
+    { name: 'durationMs', type: 'number' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+    var dbType = String(input.dbType || '').toLowerCase();
+    if (dbType === 'mssql') throw refuse('db-dump: SQL Server is not supported yet — postgres or mysql.', 'DB_TYPE_NOT_SUPPORTED');
+    if (!PROGRAMS[dbType]) throw refuse('db-dump: dbType must be postgres or mysql, not "' + input.dbType + '".', 'DB_TYPE_NOT_SUPPORTED');
+    var conn = input.connection || {};
+    var database = input.database;
+    if (!database) throw refuse('db-dump: say which database to back up.', 'NO_DATABASE');
+    // An argument starting with "-" would be read as an option, not a name.
+    [['database', database], ['host', conn.host], ['user', conn.user]].forEach(function(f) {
+      if (f[1] && /^-/.test(String(f[1]))) throw refuse('db-dump: the ' + f[0] + ' "' + f[1] + '" cannot start with "-".', 'BAD_ARGUMENT');
+    });
+
+    var started = Date.now();
+    var program = PROGRAMS[dbType];
+    var folder = dataDir.resolve(input.folder || DEFAULT_FOLDER, 'The backup folder');
+    fs.mkdirSync(folder, { recursive: true });
+    var name = input.fileName ? String(input.fileName) : fileSafe(database) + '-' + stamp(new Date()) + program.ext;
+    var filePath = dataDir.resolve(path.join(folder, name), 'The backup file');
+    if (path.dirname(filePath) !== fs.realpathSync(folder)) throw refuse('db-dump: fileName "' + name + '" must be a name, not a path.', 'PATH_NOT_ALLOWED');
+    var partial = filePath + '.partial';
+
+    var cmd = commandFor(dbType, conn, String(database));
+    var secret = conn.password ? String(conn.password) : null;
+    var out = fs.createWriteStream(partial);
+    var hash = crypto.createHash('sha256');
+    var bytes = 0;
+    var stderr = '';
+    var child;
+
+    var done = new Promise(function(resolve, reject) {
+      var settled = false;
+      function fail(err) { if (settled) return; settled = true; reject(err); }
+      function ok() { if (settled) return; settled = true; resolve(); }
+
+      try {
+        child = spawn(cmd.bin, cmd.args, { env: cmd.env, stdio: ['ignore', 'pipe', 'pipe'] });
+      } catch (e) {
+        fail(e);
+        return;
+      }
+      child.on('error', function(e) {
+        fail(e.code === 'ENOENT' ? refuse(cmd.bin + ' is not installed on this server (needed to back up ' + dbType + ').', 'PROGRAM_NOT_FOUND') : e);
+      });
+      child.stderr.on('data', function(d) { stderr = (stderr + d.toString()).slice(-STDERR_KEEP); });
+
+      var source = program.gzip ? child.stdout.pipe(zlib.createGzip()) : child.stdout;
+      source.on('data', function(chunk) { hash.update(chunk); bytes += chunk.length; });
+      source.on('error', fail);
+      out.on('error', fail);
+      source.pipe(out);
+
+      var exit = null;
+      var written = false;
+      function finish() {
+        if (exit === null || !written) return;
+        if (exit.code === 0) return ok();
+        var said = stderr.trim();
+        if (secret) said = said.split(secret).join('****');
+        var why = exit.signal ? 'was stopped (' + exit.signal + ')' : 'ended with code ' + exit.code;
+        fail(refuse(cmd.bin + ' ' + why + (said ? ': ' + said : ''), 'DUMP_FAILED'));
+      }
+      child.on('close', function(code, signal) { exit = { code: code, signal: signal }; finish(); });
+      out.on('finish', function() { written = true; finish(); });
+    });
+
+    var timer = system.onProgress ? setInterval(function() { system.onProgress({ bytes: bytes }); }, PROGRESS_MS) : null;
+    var onAbort = function() { if (child && child.exitCode === null) child.kill('SIGTERM'); };
+    if (system.signal) {
+      if (system.signal.aborted) onAbort();
+      else system.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    try {
+      await done;
+    } catch (err) {
+      out.destroy();
+      try { fs.unlinkSync(partial); } catch (_) {}
+      throw err;
+    } finally {
+      if (timer) clearInterval(timer);
+      if (system.signal) system.signal.removeEventListener('abort', onAbort);
+    }
+    fs.renameSync(partial, filePath);
+    if (system.onProgress) system.onProgress({ bytes: bytes });
+    return {
+      filePath: filePath, fileName: path.basename(filePath), bytes: bytes, sha256: hash.digest('hex'),
+      dbType: dbType, database: String(database), durationMs: Date.now() - started
+    };
+  },
+
+  // For tests: the command a dump runs, without running it.
+  _commandFor: commandFor
+};

package/lib/builtins/file/s3-upload.js

@@ -0,0 +1,131 @@
+// s3-upload action — one file from this company's data folder to an S3 bucket
+// (or an S3-compatible store: `endpoint`).
+//
+// Streamed in parts (@aws-sdk/lib-storage Upload), so a file of any size
+// needs no more memory than a few parts. Every part carries a SHA-256
+// checksum: a bucket with Object Lock refuses a PUT without one, and S3
+// checks the bytes it got against it.
+//
+// IT ONLY WRITES. No list, read or head of the bucket — a backup key should be
+// allowed s3:PutObject (and s3:AbortMultipartUpload, so a failed upload is
+// cleaned up) and nothing else, so a leaked key can add files and do no more.
+//
+// Peer deps, optional and lazy-required: @aws-sdk/client-s3 and
+// @aws-sdk/lib-storage.
+//
+// The connection: { bucket, region, accessKeyId, secretAccessKey, prefix?,
+// sessionToken?, endpoint?, forcePathStyle? } — a saved connection
+// (connectionInfoId) the host resolves; never typed into a step.
+
+var fs = require('fs');
+var path = require('path');
+var dataDir = require('../../dataDir');
+
+var PART_SIZE = 16 * 1024 * 1024;
+var QUEUE = 4;
+
+function refuse(message, code) {
+  var err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+function aws() {
+  try {
+    return { s3: require('@aws-sdk/client-s3'), storage: require('@aws-sdk/lib-storage') };
+  } catch (_) {
+    throw refuse("s3-upload: '@aws-sdk/client-s3' and '@aws-sdk/lib-storage' are not installed. Run: npm install @aws-sdk/client-s3 @aws-sdk/lib-storage", 'MISSING_DEPENDENCY');
+  }
+}
+
+/** The object's key: `key` as given, else <prefix>/<file name>; never starting with "/". */
+function keyFor(input, conn, filePath) {
+  if (input.key) return String(input.key).replace(/^\/+/, '');
+  var prefix = String(conn.prefix || '').replace(/^\/+|\/+$/g, '');
+  return (prefix ? prefix + '/' : '') + path.basename(filePath);
+}
+
+module.exports = {
+  name: 's3-upload',
+  // It writes, so it is never previewed.
+  example: { bucket: 'acme-backups', key: 'backups/shop/shop-2026-11-13T02-00-05.dump', bytes: 104857600, etag: '"5d41402abc4b2a76b9719d911017c592-7"', versionId: '3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY', deleted: true },
+  description: 'Upload one file from this company\'s data folder to an S3 bucket, in parts, with a SHA-256 checksum. Only writes: the key needs s3:PutObject (and s3:AbortMultipartUpload), nothing else. Returns { bucket, key, bytes, etag, versionId, deleted }.',
+  requires: [],   // @aws-sdk/client-s3 and @aws-sdk/lib-storage checked at runtime
+
+  inputSchema: [
+    { name: 'connection', type: 'object', required: true, order: 1,
+      description: '{ bucket, region, accessKeyId, secretAccessKey, prefix? } — a saved connection (connectionInfoId), resolved by the host.' },
+    { name: 'filePath', type: 'string', required: true, order: 2,
+      description: 'The file, in this company\'s data folder, e.g. {steps.dump.filePath}.' },
+    { name: 'key', type: 'string', order: 3,
+      description: 'The object\'s key in the bucket. Default: <prefix>/<file name>.' },
+    { name: 'deleteAfter', type: 'boolean', default: false, order: 4,
+      description: 'Delete the local file once it is uploaded.' },
+    { name: 'contentType', type: 'string', order: 5, group: 'Upload options',
+      description: 'Default: application/octet-stream.' }
+  ],
+  outputSchema: [
+    { name: 'bucket', type: 'string' }, { name: 'key', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'etag', type: 'string' }, { name: 'versionId', type: 'string' }, { name: 'deleted', type: 'boolean' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var system = ctx.system || {};
+    var conn = input.connection || {};
+    if (!conn.bucket) throw refuse('s3-upload: the connection names no bucket.', 'NO_BUCKET');
+    if (!conn.region && !conn.endpoint) throw refuse('s3-upload: the connection names no region.', 'NO_REGION');
+    var file = dataDir.resolve(input.filePath, 'The file to upload');
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw refuse('s3-upload: "' + input.filePath + '" is not a file that exists.', 'FILE_NOT_FOUND');
+    var bytes = fs.statSync(file).size;
+    var key = keyFor(input, conn, file);
+
+    var lib = aws();
+    var clientConfig = { region: conn.region || 'us-east-1' };
+    if (conn.accessKeyId) {
+      clientConfig.credentials = { accessKeyId: String(conn.accessKeyId), secretAccessKey: String(conn.secretAccessKey || '') };
+      if (conn.sessionToken) clientConfig.credentials.sessionToken = String(conn.sessionToken);
+    }
+    if (conn.endpoint) clientConfig.endpoint = String(conn.endpoint);
+    if (conn.forcePathStyle) clientConfig.forcePathStyle = true;
+    var client = new lib.s3.S3Client(clientConfig);
+
+    var upload = new lib.storage.Upload({
+      client: client,
+      partSize: PART_SIZE,
+      queueSize: QUEUE,
+      leavePartsOnError: false,     // a failed upload is aborted (s3:AbortMultipartUpload)
+      params: {
+        Bucket: String(conn.bucket),
+        Key: key,
+        Body: fs.createReadStream(file),
+        ContentLength: bytes,
+        ContentType: input.contentType || 'application/octet-stream',
+        ChecksumAlgorithm: 'SHA256'
+      }
+    });
+    if (system.onProgress) upload.on('httpUploadProgress', function(p) { system.onProgress({ bytes: p.loaded || 0 }); });
+    var onAbort = function() { upload.abort().catch(function() {}); };
+    if (system.signal) {
+      if (system.signal.aborted) onAbort();
+      else system.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    var res;
+    try {
+      res = await upload.done();
+    } finally {
+      if (system.signal) system.signal.removeEventListener('abort', onAbort);
+      if (client.destroy) client.destroy();
+    }
+    var deleted = false;
+    if (input.deleteAfter === true) {
+      fs.unlinkSync(file);
+      deleted = true;
+    }
+    return { bucket: String(conn.bucket), key: key, bytes: bytes, etag: (res && res.ETag) || null, versionId: (res && res.VersionId) || null, deleted: deleted };
+  },
+
+  // For tests.
+  _keyFor: keyFor
+};

package/lib/builtins/index.js

@@ -22,6 +22,8 @@ module.exports = {
   dataOperation: require('./data-operation'),
   spawnProgram: require('./spawn-program'),
   sendEmail:    require('./send-email'),
+  // A notification on people's devices (Web Push) — peer @xeplr/push.
+  pushSend:     require('./push-send'),
 
   // DB actions — factory-shaped (call fileUpload({ metaKnex }) to get a
   // registerable module) so the Knex handle for the meta store binds at
@@ -38,6 +40,9 @@ module.exports = {
   // 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'),
+  // A whole database to one backup file, by its own dump program (pg_dump,
+  // mysqldump) — run with an argument list, never a shell. See db/dump.js.
+  dbDump:       require('./db/dump'),
 
   // DB introspection — list tables/views/procedures, or one table's columns.
   dbListTables:     require('./db/list-tables'),
@@ -51,6 +56,9 @@ module.exports = {
   fileDelete:   require('./file/delete'),
   fileList:     require('./file/list'),
   fileRead:     require('./file/read'),
+  // One file to an S3 bucket, in parts, write-only. Peers: @aws-sdk/client-s3
+  // and @aws-sdk/lib-storage — optional, lazy-required.
+  s3Upload:     require('./file/s3-upload'),
 
   // Email actions. Inbound routes to getInboundProvider(input.emailType)
   // (imap today), outbound to getOutboundProvider (smtp) — see

package/lib/builtins/push-send.js

@@ -0,0 +1,58 @@
+// push-send action — a notification on people's phones and computers, even
+// with the app closed, through @xeplr/push (Web Push).
+//
+// Peer dep: `@xeplr/push`, lazy-required here, so an install that never
+// pushes does not need it. The host app sets it up once at boot —
+// push.init({ knex }) with its VAPID keys — and this step only sends.
+//
+// WHO: account ids (`userIds`) and/or emails (`emails`) — every device each of
+// them switched on, each device once. Nobody to send to is refused, rather
+// than "succeeding" with nothing sent.
+//
+// WHERE A TAP GOES: `url` is a page of the app ("/orders/{params.id}"). A full
+// address to another site is replaced by the app's home by @xeplr/push, so a
+// step can never send people off somewhere else.
+
+function asList(v) {
+  if (v === undefined || v === null || v === '') return [];
+  return (Array.isArray(v) ? v : [v]).map(function(x) { return String(x).trim(); }).filter(Boolean);
+}
+
+module.exports = {
+  name: 'push-send',
+  // It sends, so it is never previewed.
+  example: { devices: 2, sent: 2, removed: 0, failed: 0 },
+  description: 'Send a push notification to people\'s phones and computers (Web Push, through @xeplr/push) — by account id or email. A tap opens the page given.',
+  requires: [],   // @xeplr/push checked at runtime
+
+  inputSchema: [
+    { name: 'emails',  type: 'array',  order: 1,
+      description: 'Who gets it, by email. A bare string is accepted and wrapped.' },
+    { name: 'userIds', type: 'array',  order: 2,
+      description: 'Who gets it, by account id — instead of, or as well as, emails.' },
+    { name: 'title',   type: 'string', required: true, order: 3,
+      description: 'The first line, e.g. "RTO: #{params.orderNumber}". At most 120 characters.' },
+    { name: 'body',    type: 'string', order: 4,
+      description: 'Under it. At most 300 characters.' },
+    { name: 'url',     type: 'string', order: 5,
+      description: 'The page of the app a tap opens, e.g. /orders/{params.id}. Leave empty for the home page.' },
+    { name: 'tag',     type: 'string', order: 6, group: 'Message options',
+      description: 'A new notification with the same tag replaces the one shown, so repeats stack as one.' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var push;
+    try {
+      push = require('@xeplr/push');
+    } catch (_) {
+      throw new Error("push-send: '@xeplr/push' is not installed. Run: npm install @xeplr/push — and set it up at boot with push.init({ knex }).");
+    }
+    if (!push.enabled || !push.enabled()) {
+      throw new Error('push-send: push is not set up on this server — the host must call push.init() with PUSH_VAPID_PUBLIC_KEY / PUSH_VAPID_PRIVATE_KEY / PUSH_VAPID_SUBJECT (npx xeplr-push keys).');
+    }
+    var target = { emails: asList(input.emails), userIds: asList(input.userIds) };
+    if (!target.emails.length && !target.userIds.length) throw new Error('push-send: say who gets it — emails or userIds.');
+    return push.send(target, { title: input.title, body: input.body, url: input.url, tag: input.tag });
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {
@@ -39,9 +39,12 @@
     "@xeplr/schema-handler": "^1.0.0"
   },
   "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/lib-storage": "^3.0.0",
     "@duckdb/node-api": "1.5.5-r.3",
     "@xeplr/db": "^1.1.0",
     "@xeplr/email": "^1.0.0",
+    "@xeplr/push": "^1.0.0",
     "@xeplr/utils": "^1.0.0",
     "csv-parse": "^7.0.2",
     "dejavu-fonts-ttf": "^2.37.3",
@@ -61,65 +64,76 @@
     "unzipper": "^0.12.5"
   },
   "peerDependenciesMeta": {
-    "@xeplr/utils": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
       "optional": true
     },
     "@duckdb/node-api": {
       "optional": true
     },
-    "knex": {
+    "@xeplr/email": {
       "optional": true
     },
-    "pg": {
+    "@xeplr/push": {
       "optional": true
     },
-    "mysql2": {
+    "@xeplr/utils": {
       "optional": true
     },
-    "mssql": {
+    "csv-parse": {
       "optional": true
     },
-    "mongodb": {
+    "dejavu-fonts-ttf": {
       "optional": true
     },
     "exceljs": {
       "optional": true
     },
-    "unzipper": {
+    "fflate": {
       "optional": true
     },
-    "saxes": {
+    "imapflow": {
       "optional": true
     },
-    "csv-parse": {
+    "knex": {
       "optional": true
     },
-    "imapflow": {
+    "mailparser": {
       "optional": true
     },
-    "mailparser": {
+    "mongodb": {
+      "optional": true
+    },
+    "mssql": {
+      "optional": true
+    },
+    "mysql2": {
       "optional": true
     },
     "nodemailer": {
       "optional": true
     },
-    "ssh2-sftp-client": {
+    "pdfkit": {
       "optional": true
     },
-    "@xeplr/email": {
+    "pg": {
       "optional": true
     },
-    "fflate": {
+    "saxes": {
       "optional": true
     },
-    "pdfkit": {
+    "ssh2-sftp-client": {
       "optional": true
     },
-    "dejavu-fonts-ttf": {
+    "unzipper": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1168.0",
+    "@aws-sdk/lib-storage": "^3.1168.0",
     "@duckdb/node-api": "^1.5.5-r.3",
     "@xeplr/db": "^1.1.0",
     "@xeplr/utils": "^1.0.0",