@onlineapps/cookbook-template-helpers 2.0.0 → 2.0.2

package/README.md

@@ -1,3 +1,14 @@
+> Status: current
+> Owns: the helper functions a cookbook template variable may call
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/orchestration](../../connector/conn-orch-validator/manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/cookbook-template-helpers
 
 Template helper functions for cookbook variable resolution. Helper functions enable data transformations directly in cookbook template variables.
@@ -100,7 +111,7 @@ if (typeof helperFn !== 'function') {
 balíček exportuje. Neznámý helper je tvrdá chyba, ne prázdná hodnota.
 
 Živý cookbook, který touhle cestou prochází:
-[`infra/api_doorman/cookbooks/tester-helpers.json`](../../../infra/api_doorman/cookbooks/tester-helpers.json)
+[`infra/api_doorman/static/cookbooks/tester-helpers.json`](../../../infra/api_doorman/static/cookbooks/tester-helpers.json)
 — volá `normalizeString`, `webalizeString`, `string2file` i `file2string`.
 
 ## Adding a Helper

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@onlineapps/cookbook-template-helpers",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Template helper functions for cookbook variable resolution - string2file, file2string, and more",
+  "oa": {
+    "category": "orchestration"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest",
+    "test": "npm run test:unit",
+    "test:unit": "jest tests/unit",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
-    "docs": "jsdoc2md --files src/**/*.js > API.md"
+    "docs": "jsdoc2md --files 'src/**/*.js' > API.md.tmp && mv API.md.tmp API.md || (rm -f API.md.tmp; exit 1)"
   },
   "keywords": [
     "cookbook",
@@ -19,13 +23,15 @@
   "author": "OnlineApps",
   "license": "PROPRIETARY",
   "dependencies": {
-    "@onlineapps/content-resolver": "3.0.0"
+    "@onlineapps/content-resolver": "4.0.1",
+    "@onlineapps/logger-contract": "2.0.0"
   },
   "devDependencies": {
-    "jest": "29.7.0"
+    "jest": "29.7.0",
+    "jsdoc-to-markdown": "^8.0.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=24.0.0 <25"
   },
   "files": [
     "src"

package/src/helpers/fileHelpers.js

@@ -6,10 +6,7 @@
  */
 
 const ContentResolver = require('@onlineapps/content-resolver');
-
-// The logger methods `ContentResolver` requires of the object this module hands
-// it — the order is the order the error message lists them in.
-const LOGGER_METHODS = ['info', 'warn', 'error', 'debug'];
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
  * Normalize string: remove control/unsafe chars, keep letters (incl. diacritics), numbers,
@@ -76,22 +73,11 @@ function getContentResolver(helperContext) {
   // passed this gate and failed one frame down — delayed validation, forbidden
   // by architecture-principles.md §4. Owner confirmation:
   // api/docs/governance/confirmations/connector-logger-contract.md 001.
-  if (!helperContext.logger) {
-    throw new Error(
-      '[cookbook-template-helpers] logger is required - Expected: a logger with info/warn/error/debug, '
-      + 'so the resolver this helper builds writes where the service writes. '
-      + 'Fix: pass context.logger (e.g. the logger your service already built).'
-    );
-  }
-
-  const missing = LOGGER_METHODS.filter((method) => typeof helperContext.logger[method] !== 'function');
-  if (missing.length > 0) {
-    throw new Error(
-      '[cookbook-template-helpers] logger is incomplete - Expected: info, warn, error, debug as functions; '
-      + `missing: ${missing.join(', ')}. `
-      + 'Fix: pass a logger implementing all four.'
-    );
-  }
+  assertLogger(
+    'cookbook-template-helpers',
+    helperContext.logger,
+    'the resolver this helper builds writes where the service writes'
+  );
 
   return new ContentResolver({
     context: { workflow_id, step_id },
@@ -99,8 +85,45 @@ function getContentResolver(helperContext) {
   });
 }
 
+/**
+ * The declared type of an inline descriptor's bytes, refused here if it is not
+ * one.
+ *
+ * `string2file()` turns those bytes into an object in storage, and the
+ * descriptor it returns declares that object's type. A type nobody stated
+ * therefore cannot travel on: the frame below fills the hole from the filename
+ * extension, so the object ends up carrying a guess presented as a fact
+ * (measured 2026-09-08 on the live path — `{ filename: 'payload.json' }` with no
+ * `content_type` came back `application/json`, and `content_type: null` came
+ * back `text/plain`).
+ *
+ * Required input, then: not derived and not defaulted
+ * (`architecture-principles.md` §3), and stated by whoever knows what the bytes
+ * are — the caller.
+ *
+ * @private
+ * @param {*} contentType - The `content_type` the inline descriptor carries.
+ * @throws {Error} If it is not a non-empty string.
+ */
+function assertDeclaredContentType(contentType) {
+  if (typeof contentType === 'string' && contentType.trim() !== '') {
+    return;
+  }
+
+  throw new Error(
+    '[string2file] Missing required input - "content_type" is required on an inline descriptor: '
+    + 'it is the type written to storage and it is never guessed. '
+    + 'Fix: pass content_type (e.g. text/plain, application/json).'
+  );
+}
+
 /**
  * Convert string or inline descriptor to file descriptor (uploads via ContentResolver).
+ *
+ * An inline descriptor MUST declare `content_type` (see
+ * `assertDeclaredContentType`). A raw string declares nothing, so the helper
+ * names the file itself and states the type of the file it named.
+ *
  * @param {string|Object} input
  * @param {Object} context
  * @returns {Promise<Object>}
@@ -123,6 +146,7 @@ async function string2file(input, context) {
     if (typeof content !== 'string') {
       throw new Error('[string2file] Inline descriptor content must be a string');
     }
+    assertDeclaredContentType(input.content_type);
     return await resolver.createDescriptor(content, {
       filename: input.filename,
       content_type: input.content_type,