@onlineapps/cookbook-template-helpers 1.0.1

package/README.md

@@ -0,0 +1,188 @@
+# @onlineapps/cookbook-template-helpers
+
+Template helper functions for cookbook variable resolution. Helper functions enable data transformations directly in cookbook template variables.
+
+## Installation
+
+```bash
+npm install @onlineapps/cookbook-template-helpers
+```
+
+## Overview
+
+Helper functions can be used in cookbook template variables using the syntax:
+```
+{{helper_name(argument)}}
+```
+
+Arguments can be template variables themselves:
+```
+{{helper_name(steps.step_id.output.field)}}
+```
+
+## Available Helpers
+
+### string2file
+
+Converts string content or inline descriptor to file descriptor. Uploads content to MinIO storage.
+
+**Signature:**
+```javascript
+async function string2file(input, context)
+```
+
+**Parameters:**
+- `input` (string|Object) - String content or inline descriptor
+- `context` (Object) - Workflow context (for storage access)
+
+**Returns:**
+- `Promise<Object>` - File descriptor
+
+**Examples:**
+
+```json
+{
+  "input": {
+    "file": "{{string2file(steps.markdown.output.content)}}"
+  }
+}
+```
+
+```json
+{
+  "input": {
+    "file": "{{string2file('Hello world')}}"
+  }
+}
+```
+
+### file2string
+
+Converts file descriptor to string. Downloads content from MinIO if needed.
+
+**Signature:**
+```javascript
+async function file2string(descriptor, context)
+```
+
+**Parameters:**
+- `descriptor` (Object|string) - File descriptor or string
+- `context` (Object) - Workflow context (for storage access)
+
+**Returns:**
+- `Promise<string>` - String content
+
+**Examples:**
+
+```json
+{
+  "input": {
+    "markdown": "{{file2string(steps.pdf.output.file_descriptor)}}"
+  }
+}
+```
+
+## Usage in Cookbook
+
+Helper functions are integrated into the cookbook executor. They are automatically available when resolving template variables.
+
+**Example cookbook:**
+
+```json
+{
+  "version": "2.0.0",
+  "steps": [
+    {
+      "step_id": "get_markdown",
+      "type": "task",
+      "service": "hello-service",
+      "operation": "generate-markdown",
+      "input": { "name": "Karel" }
+    },
+    {
+      "step_id": "create_pdf",
+      "type": "task",
+      "service": "pdfgen-service",
+      "operation": "md2pdf",
+      "depends_on": ["get_markdown"],
+      "input": {
+        "markdown": "{{file2string(steps.get_markdown.output.file_descriptor)}}"
+      }
+    }
+  ]
+}
+```
+
+## Integration
+
+Helper functions are passed to the cookbook executor:
+
+```javascript
+const templateHelpers = require('@onlineapps/cookbook-template-helpers');
+const { CookbookExecutor } = require('@onlineapps/cookbook-executor');
+
+const executor = new CookbookExecutor(cookbook, {
+  helpers: templateHelpers
+});
+```
+
+## Adding Custom Helpers
+
+You can combine global helpers with custom helpers:
+
+```javascript
+const templateHelpers = require('@onlineapps/cookbook-template-helpers');
+const customHelpers = require('./customHelpers');
+
+const allHelpers = {
+  ...templateHelpers,
+  ...customHelpers
+};
+
+const executor = new CookbookExecutor(cookbook, {
+  helpers: allHelpers
+});
+```
+
+## Helper Function Requirements
+
+- **Async**: All helpers must be async functions (return Promise)
+- **Context**: Helpers receive workflow context as last parameter
+- **Idempotent**: Same input should produce same output
+- **Error handling**: Should throw descriptive errors
+
+## Dependencies
+
+- `@onlineapps/conn-base-storage` - For MinIO storage operations
+
+## Environment Variables
+
+Helper functions use the following environment variables for storage access:
+
+- `MINIO_HOST` - MinIO endpoint (default: `api_shared_storage`)
+- `MINIO_PORT` - MinIO port (default: `9000`)
+- `MINIO_ACCESS_KEY` - MinIO access key (default: `minioadmin`)
+- `MINIO_SECRET_KEY` - MinIO secret key (default: `minioadmin`)
+- `MINIO_USE_SSL` - Use SSL (default: `false`)
+
+## File Descriptor Format
+
+File descriptors have the following structure:
+
+```javascript
+{
+  _descriptor: true,
+  type: 'file',  // or 'inline'
+  storage_ref: 'minio://workflow/path/to/file',  // for type='file'
+  content: '...',  // for type='inline'
+  filename: 'document.txt',
+  content_type: 'text/plain',
+  size: 1234,
+  fingerprint: 'sha256...'
+}
+```
+
+## License
+
+PROPRIETARY
+

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@onlineapps/cookbook-template-helpers",
+  "version": "1.0.1",
+  "description": "Template helper functions for cookbook variable resolution - string2file, file2string, and more",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "docs": "jsdoc2md --files src/**/*.js > API.md"
+  },
+  "keywords": [
+    "cookbook",
+    "workflow",
+    "template",
+    "helpers",
+    "functions"
+  ],
+  "author": "OnlineApps",
+  "license": "PROPRIETARY",
+  "dependencies": {
+    "@onlineapps/conn-base-storage": "^1.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/helpers/fileHelpers.js

@@ -0,0 +1,201 @@
+'use strict';
+
+/**
+ * File helper functions for cookbook template resolution
+ * Converts between string content and file descriptors
+ */
+
+const StorageConnector = require('@onlineapps/conn-base-storage');
+
+/**
+ * Get storage instance from context or create new one
+ * @private
+ * @param {Object} context - Workflow context
+ * @returns {Promise<Object>} Storage connector instance
+ */
+async function getStorageFromContext(context) {
+  // If storage is already in context, use it
+  if (context._storage) {
+    return context._storage;
+  }
+
+  // Otherwise create new storage instance
+  const storage = new StorageConnector({
+    endpoint: process.env.MINIO_HOST || 'api_shared_storage',
+    port: parseInt(process.env.MINIO_PORT || '9000', 10),
+    accessKey: process.env.MINIO_ACCESS_KEY || 'minioadmin',
+    secretKey: process.env.MINIO_SECRET_KEY || 'minioadmin',
+    useSSL: process.env.MINIO_USE_SSL === 'true'
+  });
+
+  // Cache in context for reuse
+  context._storage = storage;
+  return storage;
+}
+
+/**
+ * Convert string or inline descriptor to file descriptor
+ * Uploads content to MinIO and returns file descriptor
+ * 
+ * @param {string|Object} input - String content or inline descriptor
+ * @param {Object} context - Workflow context (for storage access)
+ * @returns {Promise<Object>} File descriptor
+ * 
+ * @example
+ * // String input
+ * const descriptor = await string2file('Hello world', context);
+ * 
+ * @example
+ * // Inline descriptor input
+ * const descriptor = await string2file({
+ *   _descriptor: true,
+ *   type: 'inline',
+ *   content: 'Hello world',
+ *   filename: 'greeting.txt'
+ * }, context);
+ */
+async function string2file(input, context) {
+  if (!input) {
+    throw new Error('[string2file] Input is required');
+  }
+
+  // Pokud už je file descriptor, vrať ho
+  if (input._descriptor && input.type === 'file') {
+    return input;
+  }
+
+  // Pokud je inline descriptor, převeď na file
+  if (input._descriptor && input.type === 'inline') {
+    const content = input.content;
+    if (typeof content !== 'string') {
+      throw new Error('[string2file] Inline descriptor content must be a string');
+    }
+
+    const storage = await getStorageFromContext(context);
+    const encoding = input.encoding || 'utf-8';
+    const buffer = Buffer.from(content, encoding);
+
+    // Upload do MinIO
+    const workflowId = context.workflow_id || context.workflowId || 'temp';
+    const stepId = context.step_id || context.stepId || 'helpers';
+    const pathPrefix = `helpers/${workflowId}/${stepId}`;
+
+    const result = await storage.uploadWithFingerprint(
+      'workflow',
+      buffer,
+      pathPrefix
+    );
+
+    return {
+      _descriptor: true,
+      type: 'file',
+      storage_ref: `minio://workflow/${result.path}`,
+      filename: input.filename || 'content.txt',
+      content_type: input.content_type || 'text/plain',
+      size: buffer.length,
+      fingerprint: result.fingerprint
+    };
+  }
+
+  // Pokud je string, vytvoř file descriptor
+  if (typeof input === 'string') {
+    const storage = await getStorageFromContext(context);
+    const buffer = Buffer.from(input, 'utf-8');
+
+    const workflowId = context.workflow_id || context.workflowId || 'temp';
+    const stepId = context.step_id || context.stepId || 'helpers';
+    const pathPrefix = `helpers/${workflowId}/${stepId}`;
+
+    const result = await storage.uploadWithFingerprint(
+      'workflow',
+      buffer,
+      pathPrefix
+    );
+
+    return {
+      _descriptor: true,
+      type: 'file',
+      storage_ref: `minio://workflow/${result.path}`,
+      filename: 'content.txt',
+      content_type: 'text/plain',
+      size: buffer.length,
+      fingerprint: result.fingerprint
+    };
+  }
+
+  throw new Error('[string2file] Invalid input - expected string or descriptor');
+}
+
+/**
+ * Convert file descriptor to string
+ * Downloads content from MinIO if needed
+ * 
+ * @param {Object|string} descriptor - File descriptor or string
+ * @param {Object} context - Workflow context (for storage access)
+ * @returns {Promise<string>} String content
+ * 
+ * @example
+ * // File descriptor input
+ * const content = await file2string({
+ *   _descriptor: true,
+ *   type: 'file',
+ *   storage_ref: 'minio://workflow/path/to/file',
+ *   fingerprint: 'abc123...'
+ * }, context);
+ * 
+ * @example
+ * // Inline descriptor input
+ * const content = await file2string({
+ *   _descriptor: true,
+ *   type: 'inline',
+ *   content: 'Hello world'
+ * }, context);
+ */
+async function file2string(descriptor, context) {
+  // Pokud není descriptor, vrať jak je (pokud je string)
+  if (!descriptor || !descriptor._descriptor) {
+    if (typeof descriptor === 'string') {
+      return descriptor;
+    }
+    return String(descriptor || '');
+  }
+
+  // Pokud je inline, vrať content
+  if (descriptor.type === 'inline') {
+    return descriptor.content || '';
+  }
+
+  // Pokud je file, stáhni z MinIO
+  if (descriptor.type === 'file') {
+    if (!descriptor.storage_ref) {
+      throw new Error('[file2string] File descriptor missing storage_ref');
+    }
+
+    const storage = await getStorageFromContext(context);
+    
+    // Parse storage_ref: minio://workflow/path/to/file
+    const match = descriptor.storage_ref.match(/^minio:\/\/([^\/]+)\/(.+)$/);
+    if (!match) {
+      throw new Error(`[file2string] Invalid storage_ref format: ${descriptor.storage_ref}`);
+    }
+
+    const [, bucket, path] = match;
+    
+    // Download with fingerprint verification
+    const content = await storage.downloadWithVerification(
+      bucket,
+      path,
+      descriptor.fingerprint
+    );
+
+    return content.toString('utf-8');
+  }
+
+  throw new Error(`[file2string] Invalid descriptor type: ${descriptor.type}`);
+}
+
+module.exports = {
+  string2file,
+  file2string
+};
+

package/src/index.js

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * @module @onlineapps/cookbook-template-helpers
+ * @description Template helper functions for cookbook variable resolution
+ * 
+ * Helper functions can be used in cookbook template variables:
+ * {{helper_name(arg)}}
+ * 
+ * Example:
+ * {{string2file(steps.markdown.output.content)}}
+ * {{file2string(steps.pdf.output.file_descriptor)}}
+ */
+
+const fileHelpers = require('./helpers/fileHelpers');
+
+module.exports = {
+  string2file: fileHelpers.string2file,
+  file2string: fileHelpers.file2string
+};
+