@encodeagent/platform-helper-util

TypeScript utility library for the EncodeAgent platform. Covers string/GUID validation, ID generation, web/URL handling, file type detection, color constants, AI cost calculation, HTML/Markdown conversion, tree data structures, authentication helpers, and structured logging.

Installation

npm install @encodeagent/platform-helper-util

Requirements

• Node.js >=20.0.0 <23.0.0
• TypeScript 5.2+

Usage

Core Utilities

import {
  isNonEmptyString,
  isGuid,
  isEmail,
  formatString,
  getTimestamp,
  readableFileSize
} from '@encodeagent/platform-helper-util';

isNonEmptyString('hello');                           // true
isGuid('550e8400-e29b-41d4-a716-446655440000');      // true
isEmail('[email protected]');                         // true
formatString('Hello {0}!', 'World');                 // 'Hello World!'
readableFileSize(1024);                              // '1.00 KB'

ID Generation

import { newGuid, newShortId, slug } from '@encodeagent/platform-helper-util';

const guid    = newGuid();    // '550e8400-e29b-41d4-a716-446655440000'
const shortId = newShortId(); // 'rJUWbIHOWM'

// slug — URL-safe identifier from arbitrary text
slug('Hello World!');                        // 'hello-world'
slug('file.name', { keepPeriod: true });     // 'file.name'
slug('my_key',   { keepUnderscore: true });  // 'my_key'

// newShortId — same special-character opts apply
newShortId({ keepUnderscore: true });  // preserves underscores from shortid output

Web & URL Utilities

import {
  isValidUrl,
  getBaseDomain,
  getRootDomainFromUrl,
  getWebLocation,
  getWebRootUrl,
  getWebQueryValue,
  setWebQueryValue,
  fixUrl
} from '@encodeagent/platform-helper-util';

isValidUrl('https://example.com');                         // truthy
getBaseDomain('sub.example.com');                          // 'example.com'
getRootDomainFromUrl('https://sub.example.com/path');      // 'example.com'
getWebQueryValue('https://example.com?page=2', 'page');    // '2'
setWebQueryValue('https://example.com?page=1', 'page', '2'); // 'https://example.com?page=2'

// fixUrl: promotes protocol-relative and root-relative URLs to absolute
fixUrl('//cdn.example.com/img.png', 'https', '');          // 'https://cdn.example.com/img.png'
fixUrl('/about', 'https', 'example.com');                  // 'https://example.com/about'

File & Content Type Detection

import {
  getFileType,
  getContentType,
  getFileExtension,
  getAcceptMIMEs,
  getAcceptExtension,
  getAcceptFileExtensions,
  fileExtensionInTheList,
  FILE_IMAGE_LIST,
  FILE_PDF_LIST
} from '@encodeagent/platform-helper-util';

getFileType('photo.jpg');          // 'Photo'
getFileType('report.pdf');         // 'Document'
getContentType('data.json');       // 'application/json'
getFileExtension('archive.tar.gz'); // 'gz'

// Accepted MIME / extension strings for <input accept="...">
getAcceptMIMEs('image');           // 'image/gif, image/jpeg, ...'
getAcceptExtension('document');    // '.pdf, .docx, .xlsx, .pptx'
getAcceptFileExtensions('image');  // '*.gif, *.jpg, ...'

fileExtensionInTheList('photo.png', FILE_IMAGE_LIST); // true

Color Utilities

import {
  getColor,
  getColorTheme,
  setColorTheme,
  hexToRgb,
  hexToRgba,
  hexToRgbString,
  hexToRgbaString,
  rgbToHex,
  isValidHex,
  isValidRGB,
  intToHex,
  BLUE,
  RED,
  COLORS
} from '@encodeagent/platform-helper-util';

// Tailwind-style palette lookup (shades: 50–950)
getColor('blue', 500);               // '#3b82f6'
getColor('unknown', 500, 'sky');     // falls back to sky-500

// Full theme object
getColorTheme('red');                // RED constant

// Hex ↔ RGB conversion
hexToRgb('#FF0000');                 // { r: 255, g: 0, b: 0 }
hexToRgba('#FF0000', 0.5);          // { r: 255, g: 0, b: 0, a: 0.5 }
hexToRgbString('#3b82f6');           // 'rgba(59,130,246)'
rgbToHex('rgb(59, 130, 246)');      // '#3b82f6'
isValidHex('#3b82f6');               // true
isValidRGB('rgba(0,0,0,0.5)');      // true

Authentication & Authorization

import {
  checkRecordPrivilege,
  hasRole,
  hasAllRoles,
  hasAnyRole,
  isOwner,
  isMember,
  checkPrivileges,
  checkPrivilege,
  checkLicenses,
  hasLicense,
  isReader,
  isAuthor
} from '@encodeagent/platform-helper-util';

const canEdit = checkRecordPrivilege(record, context, 'update');
const userHasRole = hasRole(user, 'admin');
const owned = isOwner(record, userId);

AI Services & LLM Integration

import {
  getAiService,
  getAiServices,
  getAiModel,
  getAiModels,
  getAiPlatform,
  getAiProvider,
  getDefaultAiService,
  getLLMRequest,
  getLLMParameters,
  getLLMPrompt,
  calculateCost
} from '@encodeagent/platform-helper-util';

const service    = getAiService('gpt-4');
const request    = getLLMRequest({ ... });
const cost       = calculateCost({ service, inputQuantity: 1000, outputQuantity: 200 });

Record & Data Management

import {
  getRecordDisplay,
  convertRecordForCreate,
  getContextFromRecord,
  applyRecordSlug,
  getRecordSlug,
  getRecordAbstract,
  getRecordPageMetadata,
  fromOtherOrganization,
  isFavorite
} from '@encodeagent/platform-helper-util';

const display     = getRecordDisplay(record, entity);
const createReady = convertRecordForCreate(record);
const context     = getContextFromRecord(record);

HTML & Markdown Processing

import {
  markdownToHtml,
  htmlToMarkdown,
  normalizeHtmlForMarkdown,
  cleanHtml,
  beautifyHtml,
  removeHtmlAttributes,
  removeHtmlComments,
  removeHtmlElements
} from '@encodeagent/platform-helper-util';

const html     = markdownToHtml('# Hello World');
const markdown = htmlToMarkdown('<h1>Hello World</h1>');

Web Content Processing

import { processWebPage, getMetadata, getRSSFeed } from '@encodeagent/platform-helper-util';

const result = await processWebPage(url, settings);
const meta   = await getMetadata(url);
const feed   = await getRSSFeed(feedUrl);

Tree Operations

import {
  getTreeItem,
  insertTreeItem,
  removeTreeItem,
  replaceTreeItem,
  updateTreeItem,
  updateAllTreeItems,
  getTreeItemPath,
  getTreeItemHavingPropValue,
  getTreeItemAndChildrenIds
} from '@encodeagent/platform-helper-util';

// Find a node by predicate
const item = getTreeItem(tree, (n) => n.id === targetId);

// Insert relative to a known node
const updated = insertTreeItem(tree, parentId, newItem, 'children');

// Remove a node by ID
const pruned = removeTreeItem(tree, itemId);

Caching

import {
  getCache,
  setCache,
  removeCache,
  getCacheByGroupId,
  setCacheByGroupId,
  removeCacheByGroupId,
  resetCacheByGroupId
} from '@encodeagent/platform-helper-util';

setCache('myKey', data);
const cached = getCache('myKey');
removeCache('myKey');

Object Property Access

import {
  getPropValueOfObject,
  getIntValueOfObject,
  getFloatValueOfObject,
  getBooleanValueOfObject,
  getArrayPropValueOfObject,
  getBooleanPropValue,
  getObjectPropValue
} from '@encodeagent/platform-helper-util';

// Supports dot-notation for nested paths
getPropValueOfObject(obj, 'user.address.city');

// Type-coercing accessors with optional defaults
getIntValueOfObject(obj, 'count', 0);
getBooleanValueOfObject(obj, 'enabled', false);

Logging

import { logger, createLogger, LogLevel, Logger } from '@encodeagent/platform-helper-util';
import type { ILoggerConfig } from '@encodeagent/platform-helper-util';

// Default logger (INFO level)
logger.info('Starting up');
logger.warn('Low memory');
logger.error('Something failed');

// Custom logger
const log = createLogger({ level: 'debug' });
log.debug('Detailed trace', { payload });
log.setLevel('warn');

API Helpers

import {
  sendApiSuccess,
  sendApiError,
  sendValidationError,
  validateContentType,
  getPostData,
  getHeaderData,
  getApiRequestInfo
} from '@encodeagent/platform-helper-util';

Key Types

import type {
  IContext,
  IError,
  IService,
  ICost,
  ICostItem,
  ISurcharge,
  ICostKey,
  TKeyOwner,
  IRecord,
  ILLMRequest,
  ILLMMessage,
  IAiModel,
  TAiModelPlatform,
  ILoggerConfig,
  TWebLocation,
  TColor,
  TRGB,
  TRGBA,
  TFileInfo
} from '@encodeagent/platform-helper-util';

Constants

import {
  GUID_EMPTY,
  DEFAULT_PASSWORD_RULE,
  COUNTRIES,
  LANGUAGES,
  GENDERS,
  SURCHARGE,
  CREDIT_EXCHANGE_RATE,
  ERROR_HTTP_LIST,
  // Color palettes
  BLUE, RED, GREEN, GRAY, SLATE, ZINC, COLORS
} from '@encodeagent/platform-helper-util';

Development

npm install
npm run build          # compile TypeScript → dist/
npm run build:watch    # watch mode
npm test               # run Jest
npm run test:watch
npm run lint
npm run lint:fix
npm run format         # auto-format all source files with Prettier
npm run format:check   # CI check — exits 1 if any file needs formatting
npm run clean          # remove dist/

Publishing

# Automated (recommended): clean → test → build → version bump → publish
sh run-publish.sh

# Manual
npm run prepublishOnly
npm publish

License

UNLICENSED — PrimeObjects Software Inc. All rights reserved.