@onlineapps/cookbook-template-helpers 1.0.15 → 2.0.1

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.
@@ -49,6 +60,15 @@ Převede file/inline descriptor na string (přes ContentResolver). File stáhne
 async function file2string(descriptor, context)
 ```
 
+### Helper context — logger
+
+Oba descriptor helpery si staví `ContentResolver`, pokud jim v kontextu nepředáš
+hotový `context.contentResolver`. V tom případě je `context.logger` **povinný** a
+musí mít všechny čtyři metody: `info()`, `warn()`, `error()`, `debug()` — přesně
+to, co vyžaduje `@onlineapps/content-resolver` a za ním `@onlineapps/conn-base-storage`.
+Chybějící logger i logger neúplný padají hned v `getContentResolver()` a hláška
+jmenuje chybějící metodu; žádný `console` fallback neexistuje.
+
 ## Usage in Cookbook
 
 Helpers jsou k dispozici při resolvování template proměnných:
@@ -91,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": "1.0.15",
+  "version": "2.0.1",
   "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": "2.0.1"
+    "@onlineapps/content-resolver": "4.0.0",
+    "@onlineapps/logger-contract": "1.1.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,6 +6,7 @@
  */
 
 const ContentResolver = require('@onlineapps/content-resolver');
+const { assertLogger } = require('@onlineapps/logger-contract');
 
 /**
  * Normalize string: remove control/unsafe chars, keep letters (incl. diacritics), numbers,
@@ -66,9 +67,17 @@ function getContentResolver(helperContext) {
     helperContext.data?.step_id ||
     null;
 
-  if (!helperContext.logger || typeof helperContext.logger.warn !== 'function') {
-    throw new Error('[cookbook-template-helpers] Helper context logger is required - Expected logger with warn() method');
-  }
+  // The logger goes straight into `ContentResolver`, which demands all four
+  // methods (content-resolver src/index.js; conn-base-storage 3.0.0 behind it).
+  // Until 2026-09-03 only `warn()` was checked here, so a three-method logger
+  // 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.
+  assertLogger(
+    'cookbook-template-helpers',
+    helperContext.logger,
+    'the resolver this helper builds writes where the service writes'
+  );
 
   return new ContentResolver({
     context: { workflow_id, step_id },
@@ -76,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>}
@@ -100,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,