@xeplr/actions 2.2.1 → 2.2.2

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.
 
@@ -144,6 +145,7 @@ 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. |

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

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.2",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {
@@ -42,6 +42,7 @@
     "@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,61 +62,64 @@
     "unzipper": "^0.12.5"
   },
   "peerDependenciesMeta": {
-    "@xeplr/utils": {
-      "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
     }
   },