@tabbr/module-cli 0.5.0 → 0.6.0

package/README.md

@@ -87,7 +87,8 @@ sandboxed, triggered on a cron schedule or on an entity's create/update - see
     "secretFieldNames": ["apiKey"],
     "triggers": [
       { "type": "CRON", "name": "pollFlights", "cronExpression": "*/5 * * * *", "handler": "pollFlights" },
-      { "type": "ENTITY_HOOK", "name": "onFlightSaved", "entity": "flight", "event": "onUpdate", "handler": "onFlightSaved" }
+      { "type": "ENTITY_HOOK", "name": "onFlightSaved", "entity": "flight", "event": "onUpdate", "handler": "onFlightSaved" },
+      { "type": "OGN_EVENT", "name": "onOgn", "handler": "onOgnEvent" }
     ]
   }
 }
@@ -119,6 +120,21 @@ export function pollFlights() {
   `onDelete`), with that entity bound under its own name (e.g. `flight`) in the handler's scope - before the save.
   `onCreated` / `onUpdated` run after it, once committed, in the background: for a handler that reads the database
   (e.g. "is this person in that list now"). A module's own writes don't trigger its handlers.
+- `"OGN_EVENT"` (module API 1.10, `"engines": { "tabbr": "^1.10" }`) runs for every start and landing OGN reports that
+  the club gets: on one of its airfields, or by one of the airplanes it follows wherever they fly - the club sets both
+  in Instellingen › Vliegtuigen › OGN. The handler gets an `OgnEvent` (`@tabbr/module-sdk/backend`):
+  `{ type: 'TAKEOFF' | 'LANDING', fieldCode, address, time, atClubField, followedAirplane, airplaneId }`. One handler
+  runs at a time, in the order the events came; keep it quick (OGN can report many in a busy hour), and make getting
+  the same event twice harmless. The club sees "krijgt de starts en landingen van OGN" when
+  it installs the module.
+
+  ```ts
+  export function onOgnEvent(event: OgnEvent) {
+    if (event.type === 'LANDING' && event.airplaneId) {
+      // e.g. close the flight of that airplane that is still in the air
+    }
+  }
+  ```
 - Needs `esbuild` installed in the workspace (`npm install -D esbuild`) - only used at publish
   time, bundled into one dependency-free `bundle.js` the server runs in a GraalVM sandbox, so
   regular npm packages can be imported in your TS but nothing Node-specific (no `fs`, no native

package/bin/tabbr-module.js

@@ -85,9 +85,12 @@ Backend part (all in ${CONFIG_FILE} under "backend", not as CLI flags):
   secretFieldNames             Names of your module's settings keys that hold secrets (masked from
                               every settings GET response once saved)
   triggers                     [{type: "CRON", name, cronExpression, handler} |
-                               {type: "ENTITY_HOOK", name, entity, event, handler} |
+                               {type: "ENTITY_HOOK", name, entity, event, handler, serializeOn?} |
                                {type: "PUBLIC", name, handler, params}  (module API 1.5:
-                               GET /api/<club>/public/module/<moduleId>/data/<name>, no login)]
+                               GET /api/<club>/public/module/<moduleId>/data/<name>, no login) |
+                               {type: "OGN_EVENT", name, handler}  (module API 1.10: the club's OGN starts/landings)]
+  publicActions                [{name, handler, rateLimit?: "10/h", verifiedEmail?: true}] - functions anyone may
+                               call without logging in: POST /api/<club>/public/custommodule/<id>/action/<name>
 
 Optional:
   --icon <name>              Menu icon name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabbr/module-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Set up, build and publish a Native Federation club module to a tabbr club.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "SystemWorks BV",

package/src/backend-build.js

@@ -46,6 +46,41 @@ function entitiesOf(config) {
   return entities;
 }
 
+/**
+ * The audiences the module declares (`"audiences"` in tabbr.config.json, module API 1.8): `{ key, name, description,
+ * criteria }` - made among the club's audiences when the module is installed. Checked just enough to fail here: keys,
+ * names, and every `{audience:<key>}` in the entities' rules declared. Tabbr checks them again (criteria about the
+ * logged-in user, audiences in a circle).
+ */
+function audiencesOf(config, entities) {
+  const audiences = config.audiences || [];
+  if (!Array.isArray(audiences)) {
+    throw new Error('"audiences" in tabbr.config.json must be an array: [{ "key": "uploaders", "name": "Fotografen", "criteria": [...] }].');
+  }
+  const keys = new Set();
+  for (const audience of audiences) {
+    if (!audience || !/^[a-z][a-zA-Z0-9]{0,39}$/.test(audience.key || '')) {
+      throw new Error(`Audience key "${audience && audience.key}" is not valid: camelCase letters and digits, starting lowercase.`);
+    }
+    if (keys.has(audience.key)) {
+      throw new Error(`Audience "${audience.key}" is declared twice.`);
+    }
+    keys.add(audience.key);
+    if (typeof audience.name !== 'string' || !audience.name.trim() || audience.name.length > 80) {
+      throw new Error(`Audience "${audience.key}" needs a name (at most 80 characters).`);
+    }
+    if (audience.criteria != null && !Array.isArray(audience.criteria)) {
+      throw new Error(`Audience "${audience.key}": "criteria" must be an array of lines ({ "andFilterValues": [...] }).`);
+    }
+  }
+  for (const match of JSON.stringify(entities).matchAll(/\{audience:([^}]*)\}/g)) {
+    if (!keys.has(match[1])) {
+      throw new Error(`A rule refers to {audience:${match[1]}}, which "audiences" in tabbr.config.json doesn't declare.`);
+    }
+  }
+  return audiences;
+}
+
 const CONTRACT_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
 
 /**
@@ -118,18 +153,19 @@ function providesOf(cwd, config) {
  * and the contracts it uses and provides - which a module can do without any backend code, so then only the manifest
  * is produced (`bundleJs` null). `files`: more files for the build's `backend/` (the TypeScript of what it provides).
  *
- * Returns `null` when the workspace has no backend part, no entities and uses or provides no contracts, so `build.js`
+ * Returns `null` when the workspace has no backend part, no entities, no audiences and uses or provides no contracts, so `build.js`
  * can skip it entirely for such a frontend-only module.
  */
 async function buildBackend(cwd, config) {
   const backendConfig = config.backend;
   const entities = entitiesOf(config);
+  const audiences = audiencesOf(config, entities);
   const uses = usesOf(config);
   const optionalUses = usesOf(config, 'optionalUses');
   const provides = providesOf(cwd, config);
   const bundleJs = backendConfig ? await bundle(cwd, backendConfig) : null;
-  if (bundleJs == null && entities.length === 0 && Object.keys(uses).length === 0 && Object.keys(optionalUses).length === 0
-    && Object.keys(provides.versions).length === 0) {
+  if (bundleJs == null && entities.length === 0 && audiences.length === 0 && Object.keys(uses).length === 0
+    && Object.keys(optionalUses).length === 0 && Object.keys(provides.versions).length === 0) {
     return null;
   }
   const settings = backendConfig || {};
@@ -138,19 +174,34 @@ async function buildBackend(cwd, config) {
     allowedHosts: [...(settings.allowedHosts || []), ...(config.local ? settings.localAllowedHosts || [] : [])],
     secretFieldNames: settings.secretFieldNames || [],
     triggers: bundleJs == null ? [] : settings.triggers || [],
+    // functions anyone may call without logging in (e.g. submitting a public form) - shown to the club when it installs
+    publicActions: bundleJs == null ? [] : settings.publicActions || [],
     entities,
     // the module gives persons roles (tabbr.access.setManagedRoles) - shown to the club when it installs the module
     manageRoles: bundleJs != null && settings.manageRoles === true,
+    // the built-in entities (besides its own) it may change - permissions.entities.write; the server refuses any other write
+    writeEntities: bundleJs != null ? writeEntitiesOf(config) : [],
     // the contracts it uses - for its frontend part as well, so the manifest is written for a frontend-only module too
     uses,
     optionalUses,
     // the contracts it provides, with their version; their TypeScript goes along as backend/contracts/<name>.d.ts
     provides: provides.versions,
+    // its own audiences (module API 1.8), made among the club's when it is installed
+    audiences,
   };
 
   return { bundleJs, manifestJson: JSON.stringify(manifest, null, 2), files: provides.files };
 }
 
+/** `permissions.entities.write`: names of entities the module may change besides its own (e.g. "person"). */
+function writeEntitiesOf(config) {
+  const write = config.permissions?.entities?.write ?? [];
+  if (!Array.isArray(write) || write.some((name) => typeof name !== 'string' || !/^[a-z][a-zA-Z0-9]{1,39}$/.test(name))) {
+    throw new Error('"permissions.entities.write" must be a list of entity names, e.g. ["person"].');
+  }
+  return [...new Set(write)];
+}
+
 /** The backend entry bundled into one script, or null when there is no entry file (and none was configured explicitly). */
 async function bundle(cwd, backendConfig) {
   const entry = backendConfig.entry || DEFAULT_ENTRY;
@@ -191,4 +242,4 @@ async function bundle(cwd, backendConfig) {
   return result.outputFiles[0].text;
 }
 
-module.exports = { buildBackend, entitiesOf, usesOf, providesOf, DEFAULT_ENTRY };
+module.exports = { buildBackend, entitiesOf, audiencesOf, usesOf, providesOf, DEFAULT_ENTRY };