@xeplr/actions 1.4.8 → 1.5.0

package/README.md

@@ -128,6 +128,7 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | `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 [File steps](#file-steps-and-the-folders-they-may-use). |
 | `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 }`. |
 | `httpRequest` | `http-request` | Call another system's API: `method`, `path`, `query`, `body`, `headers`, signing in with a saved connection. `{ status, ok, body, headers }`. See [Calling an API](#calling-an-api-http-request). |
 | `spawnProgram`, `dbQuery` | — | **Placeholders.** Empty modules with no `name` or `execute`; `register()` rejects them. |
 
@@ -284,7 +285,7 @@ await runAction({ name: 'http-request', input: {
 
 ## File steps, and the folders they may use
 
-`file-list`, `file-read` and `file-move` take a path from whoever wrote the workflow, so they work **only inside the folders the install names** (`lib/fileRoots.js`):
+`file-list`, `file-read`, `file-move` and `file-delete` take a path from whoever wrote the workflow, so they work **only inside the folders the install names** (`lib/fileRoots.js`):
 
 | | |
 |---|---|
@@ -511,7 +512,7 @@ await actions.runAction(actions.builtins.dbPush, input, { metaStore: xcfg.metaSt
 | name | required? | meaning |
 |---|---|---|
 | `XEPLR_ACTIONS_TMP_DIR` | no | Where `db-fetch` and `email-read` spool NDJSON, email downloads go (unless `outDir`), and the uploader spools batches. Default `<os.tmpdir()>/xeplr-actions`. Files are not cleaned up by `db-fetch` or `email-read`. |
-| `XEPLR_FILE_ROOTS` | for `file-list`, `file-read`, `file-move` outside the temp folder | Absolute folders, comma-separated, that file steps may use. See [File steps](#file-steps-and-the-folders-they-may-use). |
+| `XEPLR_FILE_ROOTS` | for `file-list`, `file-read`, `file-move`, `file-delete` outside the temp folder | Absolute folders, comma-separated, that file steps may use. See [File steps](#file-steps-and-the-folders-they-may-use). |
 | `XCFG_DB_NAME` | for `attachConfig` | The `xeplr_configs` database name. In `configRequiredEnv`. |
 | `XCFG_DB_CONNECTION_INFO_ENCRYPTED` | no | Encrypted server login for `attachConfig`; overrides `XEPLR_DB_CONNECTION`. |
 | `XEPLR_DB_CONNECTION` | for `attachConfig`, unless the above is set | Shared encrypted server login. |

package/lib/builtins/file/delete.js

@@ -0,0 +1,43 @@
+// file-delete action — remove one file.
+//
+// A file a workflow has finished with: the bank file read and posted, so the
+// next check of the folder does not find it again. PERMANENT — there is no
+// trash to take it back from; file-move into a "processed" folder is the one
+// that can be undone. Only inside the folders file steps may use
+// (lib/fileRoots.js), and only a file, never a folder.
+
+var fs = require('fs');
+var fileRoots = require('../../fileRoots');
+
+module.exports = {
+  name: 'file-delete',
+  description: 'Delete one file, permanently (file-move to a "processed" folder is the reversible one). Returns { path, deleted, skipped }.',
+  requires: [],
+  inputSchema: [
+    { name: 'path', type: 'string', required: true, order: 1,
+      description: 'The file, by absolute path, e.g. {item.path}.' },
+    { name: 'ifMissing', type: 'string', default: 'fail', options: ['fail', 'skip'], order: 2,
+      description: 'When there is no such file. fail: the step fails. skip: it goes on, deleted false.' }
+  ],
+  outputSchema: [
+    { name: 'path', type: 'string' }, { name: 'deleted', type: 'boolean' }, { name: 'skipped', type: 'boolean' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var file = fileRoots.allowed(input.path, 'The file to delete');
+    if (!fs.existsSync(file)) {
+      if (input.ifMissing === 'skip') return { path: file, deleted: false, skipped: true };
+      var missing = new Error('"' + input.path + '" is not a file that exists.');
+      missing.code = 'FILE_NOT_FOUND';
+      throw missing;
+    }
+    if (!fs.statSync(file).isFile()) {
+      var folder = new Error('"' + input.path + '" is a folder; file-delete removes one file.');
+      folder.code = 'NOT_A_FILE';
+      throw folder;
+    }
+    fs.unlinkSync(file);
+    return { path: file, deleted: true, skipped: false };
+  }
+};

package/lib/builtins/index.js

@@ -48,6 +48,7 @@ module.exports = {
   // File actions — factory-shaped for the same reason (meta store binding).
   fileUpload:   require('./file/upload'),
   fileMove:     require('./file/move'),
+  fileDelete:   require('./file/delete'),
   fileList:     require('./file/list'),
   fileRead:     require('./file/read'),
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {