@onlineapps/content-resolver 1.1.16 → 2.0.0

package/README.md

@@ -31,7 +31,8 @@ const resolver = new ContentResolver({
     port: 9000,
     accessKey: 'minioadmin',
     secretKey: 'minioadmin'
-  }
+  },
+  logger  // required - the constructor throws without a logger exposing warn()
 });
 
 // Resolve reference to content
@@ -57,7 +58,7 @@ const descriptor = await resolver.store(largeText, { workflow_id: 'wf-123' }, 'd
 const ContentResolver = require('@onlineapps/content-resolver');
 
 exports.processDocument = async (input, context = {}) => {
-  const resolver = new ContentResolver();
+  const resolver = new ContentResolver({ logger });  // logger is required
   
   // Input can be either text or reference - resolve transparently
   const resolvedInput = await resolver.resolveInput(input, ['content', 'markdown']);
@@ -80,17 +81,37 @@ exports.processDocument = async (input, context = {}) => {
 |--------|------|---------|-------------|
 | `threshold` | number | 16384 | Size threshold in bytes |
 | `storage` | Object | env-based | Storage connector config |
-| `logger` | Object | console | Logger instance |
+| `logger` | Object | **required** | Logger instance — must expose `warn()`. The constructor throws without it (`src/index.js`); there is no `console` default. |
+
+### Input contract
+
+Every method below takes one of two input sets, and **throws on anything else** —
+there is no `String(value)` coercion anywhere in the API. An object used to be
+stored and shipped as the literal bytes `[object Object]`; that path is gone.
+
+| Set | Accepted | Methods |
+|---|---|---|
+| **Content value** | a string (inline content **or** a `minio://<bucket>/<path>` / `internal://storage/<path>` reference), or a Content Descriptor (`{ _descriptor: true, type: 'inline' \| 'file' }`, or type-only) | `getAsBuffer`, `getAsString`, `getMetadata`, `normalizeToDescriptor` |
+| **Raw content** | a string or a `Buffer` | `createDescriptor`, `store` |
+
+`resolve()` is narrower still: a string only, because it promises to return one.
+
+Rejection message format: `[ContentResolver] Unsupported content value - <method>() accepts <shapes>, got <kind>. Fix: …`
 
 ### Methods
 
 #### `resolve(value): Promise<string>`
 If value is a reference (`minio://...`), downloads and returns content.
-Otherwise returns value unchanged.
+A non-reference string is returned unchanged. **Anything that is not a string throws** —
+use `getAsString()` to read a Descriptor.
 
 #### `store(content, context, filename?, content_type?): Promise<Object>`
 Stores content and returns **Content Descriptor**. If size > threshold, stores in MinIO.
 Returns Descriptor with `type: 'inline'` or `type: 'file'`.
+Content must be a string or a `Buffer`. The **empty string** `''` is content: it returns
+the documented empty inline descriptor (`filename: 'empty.txt'`, `size: 0`, no
+fingerprint). Every other falsy value — `null`, `undefined`, `0`, `false` — is a MISSING
+value and **throws** the same contract error `createDescriptor()` throws.
 
 #### `getAsBuffer(value): Promise<Buffer>`
 Unified API to get content as Buffer. Accepts:
@@ -98,17 +119,24 @@ Unified API to get content as Buffer. Accepts:
 - Storage reference (`minio://...`) → downloads and returns Buffer
 - Content Descriptor → extracts content as Buffer
 
+A raw `Buffer` is **not** accepted here — this method reads content, it does not wrap it.
+
 #### `getAsString(value): Promise<string>`
 Unified API to get content as string. Works with string, reference, or Descriptor.
 
 #### `getMetadata(value): Object`
-Get metadata (filename, content_type, size, fingerprint) from any value type.
+Get metadata (filename, content_type, size, fingerprint) from a string or a Descriptor —
+**exactly** the values `getAsBuffer()` accepts, so the two never disagree about what a
+value is. Throws on anything else.
 
 #### `createDescriptor(content, options): Promise<Object>`
-Create Content Descriptor from raw content. Automatically decides inline vs file storage.
+Create Content Descriptor from raw content — a **string or a `Buffer`**.
+Automatically decides inline vs file storage; a Buffer is always stored as a file.
 
 #### `normalizeToDescriptor(value, options): Promise<Object>`
-Normalize any value (string, reference, Buffer) to Content Descriptor.
+Normalize a string, a reference or a Descriptor to a Content Descriptor.
+A raw `Buffer` is **not** accepted (it carries no filename/content-type context) —
+pass it to `createDescriptor()` or `store()` instead.
 
 #### `createDescriptorFromFile(tempPath, options): Promise<Object>`
 Create Content Descriptor from a temp file. **Used by ApiMapper for file outputs.**
@@ -176,7 +204,7 @@ Stores large content fields as Descriptors (returns Descriptors, not plain strin
 ### Usage Example
 
 ```javascript
-const resolver = new ContentResolver();
+const resolver = new ContentResolver({ logger });  // logger is required
 
 // Work with attachments - unified API
 async function processAttachment(attachment) {

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@onlineapps/content-resolver",
-  "version": "1.1.16",
+  "version": "2.0.0",
   "description": "Automatic conversion between text content and storage references with Content Descriptor pattern",
   "main": "src/index.js",
   "scripts": {
-    "test": "jest --passWithNoTests"
+    "test": "npm run test:unit && npm run test:integration",
+    "test:unit": "jest",
+    "test:integration": "jest --config=jest.integration.config.js"
   },
   "keywords": [
     "content",
@@ -16,11 +18,10 @@
   "author": "OnlineApps",
   "license": "ISC",
   "dependencies": {
-    "@onlineapps/conn-base-storage": "1.0.9",
-    "@onlineapps/runtime-config": "1.0.2"
+    "@onlineapps/conn-base-storage": "2.0.0",
+    "@onlineapps/runtime-config": "1.0.3"
   },
-  "peerDependencies": {
-    "@onlineapps/conn-base-storage": "^1.0.0"
-  },
-  "devDependencies": {}
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
 }

package/src/index.js

@@ -23,6 +23,16 @@ const INTERNAL_REF_PATTERN = /^internal:\/\/storage\/(.+)$/;
 
 /**
  * Check if a value is a Content Descriptor
+ *
+ * A descriptor is recognised by the explicit `_descriptor` flag OR by its `type`
+ * alone. The second form is part of the contract, not a backward-compatibility
+ * shim: `emailer` treats an externally supplied `{ type: 'inline' | 'file' }`
+ * payload as canonical and forwards it to the resolver WITHOUT stamping
+ * `_descriptor` (api_biz/emailer/src/services/email.service.js:332 → :431), and
+ * its operation schema declares `attachments[].value` as an untyped object
+ * (api_biz/emailer/config/service/operations.json), so such payloads arrive from
+ * outside this codebase. Dropping type-only recognition breaks that consumer.
+ *
  * @param {*} value - Value to check
  * @returns {boolean} True if value is a Descriptor object
  */
@@ -30,10 +40,73 @@ function isDescriptor(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     return false;
   }
-  // Check explicit identifier first, then fallback to type check for backward compatibility
   return value._descriptor === true || (value.type === 'inline' || value.type === 'file');
 }
 
+/**
+ * Name a value's kind for an error message — `typeof` alone cannot tell null,
+ * an array and an object apart, and those are the three shapes that actually
+ * reach the resolver by mistake.
+ * @param {*} value
+ * @returns {string}
+ */
+function describeValue(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+/**
+ * The input contract, written down ONCE.
+ *
+ * Every public method that takes a content value takes one of these sets and
+ * throws on anything else. Before 2026-08-28 four of them silently coerced with
+ * `String(value)` instead, so the same object was a hard error in
+ * `getAsBuffer()` and the literal text `[object Object]` two lines later in
+ * `getMetadata()` (api_biz/emailer/src/services/email.service.js:431 → :434).
+ *
+ * @see ../../../../.claude/rules/architecture-principles.md §3 (No Fallbacks), §4 (Fail-Fast)
+ */
+const ACCEPTS = {
+  /** A string (inline content or a reference). Used where the return type is a string. */
+  reference:
+    `a string (inline content or a minio://<bucket>/<path> / internal://storage/<path> reference)`,
+
+  /** A string or a Content Descriptor — the set `getAsBuffer()` established. */
+  contentValue:
+    `a string (inline content or a minio://<bucket>/<path> / internal://storage/<path> reference) ` +
+    `or a Content Descriptor ({ _descriptor: true, type: 'inline' | 'file' })`,
+
+  /** Raw bytes on the way IN to storage: a string or a Buffer. */
+  rawContent: 'a string or a Buffer'
+};
+
+/** The actionable half of the message, per `architecture-principles.md` §5. */
+const FIXES = {
+  wrap: 'Fix: wrap raw data with store() or createDescriptor() before passing it.',
+  serialize: 'Fix: serialize the value yourself (e.g. JSON.stringify) or pass a Buffer.',
+  readDescriptor:
+    'Fix: read a Content Descriptor with getAsString() instead, or pass the string itself.'
+};
+
+/**
+ * Build the one rejection message this package uses — one owner, not one copy
+ * per method.
+ *
+ * @param {string} method - The public method that received the value.
+ * @param {string} accepted - One of `ACCEPTS`.
+ * @param {*} value - The rejected value.
+ * @param {string} fix - One of `FIXES`.
+ * @returns {Error}
+ */
+function unsupportedValueError(method, accepted, value, fix) {
+  return new Error(
+    `[ContentResolver] Unsupported content value - ${method}() accepts ${accepted}, got ` +
+    `${describeValue(value)}. ` +
+    `${fix}`
+  );
+}
+
 /**
  * Get content type from filename or content
  * @param {string} filename - Filename with extension
@@ -155,12 +228,20 @@ class ContentResolver {
 
   /**
    * Resolve a value - if it's a reference, download content; if it's text, return as-is
+   *
+   * Accepts a string and nothing else. The method promises to RETURN a string,
+   * so a non-string input has no correct answer; handing it back unchanged made
+   * that promise false and pushed the type error into whichever caller did
+   * string work on the result next. Both real call sites already reject a
+   * non-string themselves (api_biz/pdfgen/src/handlers/pdf.js:221 and :297).
+   *
    * @param {string} value - Text content or storage reference
    * @returns {Promise<string>} Resolved text content
+   * @throws {Error} If the value is not a string
    */
   async resolve(value) {
-    if (!value || typeof value !== 'string') {
-      return value;
+    if (typeof value !== 'string') {
+      throw unsupportedValueError('resolve', ACCEPTS.reference, value, FIXES.readDescriptor);
     }
 
     // Check if it's a reference
@@ -168,12 +249,17 @@ class ContentResolver {
       return value; // Already text content
     }
 
-    // Parse reference
+    // Parse reference.
+    //
+    // No null check: `isReference()` above and `parseReference()` read the SAME
+    // two patterns, neither with the `g` flag, so a value that passed the first
+    // cannot fail the second. The `if (!parsed)` branch that used to sit here
+    // warned and returned the raw reference as if it were content — a fallback
+    // that could never fire, and would have handed back a URI instead of a
+    // document if it had (`architecture-principles.md` §3). The invariant is
+    // asserted in tests/unit/content-resolver.test.js
+    // ('invariant — everything isReference() accepts, parseReference() parses').
     const parsed = parseReference(value);
-    if (!parsed) {
-      this.logger.warn(`[ContentResolver] Invalid reference format: ${value}`);
-      return value;
-    }
 
     // Download content
     try {
@@ -206,7 +292,14 @@ class ContentResolver {
    * @returns {Promise<Object>} Content Descriptor
    */
   async store(content, context = {}, filename = null, content_type = null) {
-    if (!content) {
+    // The EMPTY STRING is content: the caller said "store nothing", and gets the
+    // documented empty inline descriptor for it. Everything else falsy — `null`,
+    // `undefined`, `0`, `false`, `NaN` — is a MISSING value, i.e. a defect at the
+    // call site, and falls through to the one input contract this package owns
+    // (`createDescriptor()` / `ACCEPTS.rawContent`). The old `if (!content)` test
+    // could not tell the two apart and answered a mistake with a valid-looking
+    // descriptor (`architecture-principles.md` §3, §4).
+    if (content === '') {
       return {
         _descriptor: true,
         type: 'inline',
@@ -314,30 +407,63 @@ class ContentResolver {
 
   /**
    * Get content as Buffer - unified API for string, reference, or Descriptor
+   *
+   * Accepts exactly two input types, and nothing else:
+   *   - a string — either inline content or a storage reference. This is an
+   *     input type, not a leniency path: `api_monitoring` passes a bare
+   *     `minio://…` string (api/infra/api_monitoring/src/consumer/index.js:2815).
+   *   - a Content Descriptor — stamped or type-only (see `isDescriptor`).
+   *
+   * Anything else throws. It used to be coerced with `Buffer.from(String(value))`,
+   * which turned an object into the literal bytes `[object Object]` and shipped
+   * them as an email attachment or an HTTP download body — a silent fallback
+   * banned by `architecture-principles.md` §3.
+   *
    * @param {string|Object} value - String, reference, or Content Descriptor
    * @returns {Promise<Buffer>} Content as Buffer
+   * @throws {Error} If the value is not a string or a well-formed Descriptor
    */
   async getAsBuffer(value) {
-    // Plain string (backward compatibility)
     if (typeof value === 'string') {
       if (isReference(value)) {
         return await this.downloadAsBuffer(value);
       }
       return Buffer.from(value, 'utf-8');
     }
-    
-    // Content Descriptor
+
     if (isDescriptor(value)) {
       if (value.type === 'file') {
+        if (typeof value.storage_ref !== 'string' || value.storage_ref.length === 0) {
+          throw new Error(
+            `[ContentResolver] File descriptor without storage_ref - a descriptor of type 'file' requires ` +
+            `a non-empty storage_ref string (minio://<bucket>/<path> or internal://storage/<path>), got ` +
+            `${describeValue(value.storage_ref)}. ` +
+            `Fix: build the descriptor with store() or createDescriptor() instead of by hand.`
+          );
+        }
         return await this.downloadAsBuffer(value.storage_ref);
       }
-      // type === 'inline'
-      const encoding = value.encoding || 'utf-8';
-      return Buffer.from(value.content, encoding);
+
+      if (value.type === 'inline') {
+        if (typeof value.content !== 'string') {
+          throw new Error(
+            `[ContentResolver] Inline descriptor without content - a descriptor of type 'inline' requires ` +
+            `a content string, got ${describeValue(value.content)}. ` +
+            `Fix: build the descriptor with store() or createDescriptor() instead of by hand.`
+          );
+        }
+        const encoding = value.encoding || 'utf-8';
+        return Buffer.from(value.content, encoding);
+      }
+
+      throw new Error(
+        `[ContentResolver] Descriptor with unsupported type - expected type 'inline' or 'file', got ` +
+        `${describeValue(value.type)}. ` +
+        `Fix: build the descriptor with store() or createDescriptor() instead of by hand.`
+      );
     }
-    
-    // Fallback: try to convert to string
-    return Buffer.from(String(value), 'utf-8');
+
+    throw unsupportedValueError('getAsBuffer', ACCEPTS.contentValue, value, FIXES.wrap);
   }
 
   /**
@@ -352,8 +478,16 @@ class ContentResolver {
 
   /**
    * Get metadata from value - unified API
+   *
+   * Accepts exactly what `getAsBuffer()` accepts, because it is called on the
+   * SAME value one line later (api_biz/emailer/src/services/email.service.js:431
+   * → :434). While this method coerced with `String(value)`, the pair disagreed:
+   * a value `getAsBuffer()` refused was still described here as a 15-byte
+   * `content.txt` — the metadata of the text `[object Object]`.
+   *
    * @param {string|Object} value - String, reference, or Content Descriptor
    * @returns {Object} Metadata object with filename, content_type, size, fingerprint
+   * @throws {Error} If the value is not a string or a Descriptor
    */
   getMetadata(value) {
     // Plain string
@@ -375,13 +509,7 @@ class ContentResolver {
       };
     }
     
-    // Fallback
-    const str = String(value);
-    return {
-      filename: 'content.txt',
-      content_type: 'text/plain',
-      size: Buffer.byteLength(str, 'utf-8')
-    };
+    throw unsupportedValueError('getMetadata', ACCEPTS.contentValue, value, FIXES.wrap);
   }
 
   /**
@@ -393,11 +521,17 @@ class ContentResolver {
    * @param {Object} [options.context] - Workflow context
    * @param {boolean} [options.forceFile=false] - Force storage as file even if small
    * @returns {Promise<Object>} Content Descriptor
+   * @throws {Error} If the content is neither a string nor a Buffer
    */
   async createDescriptor(content, options = {}) {
     const { filename, content_type, context = {}, forceFile = false } = options;
-    
-    // Convert Buffer to string if needed
+
+    // A string or a Buffer, and nothing else. Buffer is a MEASURED input type,
+    // not a leniency path: `storeOutput()` forwards Buffers by name (:289) and
+    // `normalizeToDescriptor()` hands over the bytes it just downloaded (:577).
+    // Anything else used to be coerced with `String(content)`, which stored the
+    // eight bytes of `[object Object]` under a sha256 of themselves and reported
+    // it back as a valid descriptor.
     let contentString;
     let isBinary = false;
     if (Buffer.isBuffer(content)) {
@@ -406,7 +540,7 @@ class ContentResolver {
     } else if (typeof content === 'string') {
       contentString = content;
     } else {
-      contentString = String(content);
+      throw unsupportedValueError('createDescriptor', ACCEPTS.rawContent, content, FIXES.serialize);
     }
 
     // For binary content, always store as file
@@ -492,9 +626,18 @@ class ContentResolver {
 
   /**
    * Normalize value to Content Descriptor if needed
+   *
+   * Accepts the same set as `getAsBuffer()`: a string or a Descriptor. A Buffer
+   * is NOT in that set even though `createDescriptor()` takes one — this method
+   * only RECOGNISES a value, and a bare Buffer carries none of the
+   * filename/content-type context `createDescriptor()` takes as arguments. It
+   * used to be swallowed by `String(value)`, which quietly decoded the bytes
+   * into an inline text descriptor via `Buffer.prototype.toString`.
+   *
    * @param {string|Object} value - String, reference, or Descriptor
    * @param {Object} options - Options for descriptor creation
    * @returns {Promise<Object>} Content Descriptor
+   * @throws {Error} If the value is not a string or a Descriptor
    */
   async normalizeToDescriptor(value, options = {}) {
     // Already a Descriptor - ensure it has _descriptor flag
@@ -518,9 +661,8 @@ class ContentResolver {
       // Plain string - create descriptor
       return await this.createDescriptor(value, options);
     }
-    
-    // Fallback
-    return await this.createDescriptor(String(value), options);
+
+    throw unsupportedValueError('normalizeToDescriptor', ACCEPTS.contentValue, value, FIXES.wrap);
   }
 
   /**