@zintrust/core 0.1.27 → 0.1.28

package/src/common/RemoteSignedJson.ts

@@ -0,0 +1,117 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { SignedRequest } from '@security/SignedRequest';
+
+export type RemoteSignedJsonSettings = {
+  baseUrl: string;
+  keyId: string;
+  secret: string;
+  timeoutMs: number;
+
+  missingUrlMessage: string;
+  missingCredentialsMessage: string;
+
+  messages: {
+    unauthorized: string;
+    forbidden: string;
+    rateLimited: string;
+    rejected: string;
+    error: string;
+    timedOut: string;
+  };
+};
+
+const joinUrl = (baseUrl: string, path: string): URL => {
+  const u = new URL(baseUrl);
+  const basePath = u.pathname.endsWith('/') ? u.pathname.slice(0, -1) : u.pathname;
+  const next = path.startsWith('/') ? path : `/${path}`;
+  u.pathname = `${basePath}${next}`;
+  u.search = '';
+  return u;
+};
+
+const asJson = async (resp: Response): Promise<unknown> => {
+  const text = await resp.text();
+  if (text.trim() === '') return null;
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return { message: text };
+  }
+};
+
+const requireConfigured = (settings: RemoteSignedJsonSettings): void => {
+  if (settings.baseUrl.trim() === '') {
+    throw ErrorFactory.createConfigError(settings.missingUrlMessage);
+  }
+  if (settings.keyId.trim() === '' || settings.secret.trim() === '') {
+    throw ErrorFactory.createConfigError(settings.missingCredentialsMessage);
+  }
+};
+
+const createTimeoutSignal = (timeoutMs: number): AbortSignal | undefined => {
+  if (timeoutMs <= 0) return undefined;
+  const timeout = (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal }).timeout;
+  return typeof timeout === 'function' ? timeout(timeoutMs) : undefined;
+};
+
+export const RemoteSignedJson = Object.freeze({
+  async request<T>(
+    settings: RemoteSignedJsonSettings,
+    path: string,
+    payload: Record<string, unknown>
+  ): Promise<T> {
+    requireConfigured(settings);
+
+    const url = joinUrl(settings.baseUrl, path);
+    const body = JSON.stringify(payload);
+    const signed = await SignedRequest.createHeaders({
+      method: 'POST',
+      url,
+      body,
+      keyId: settings.keyId,
+      secret: settings.secret,
+    });
+
+    try {
+      const resp = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...signed },
+        body,
+        signal: createTimeoutSignal(settings.timeoutMs),
+      });
+
+      if (!resp.ok) {
+        const details = await asJson(resp);
+
+        if (resp.status === 401) {
+          throw ErrorFactory.createUnauthorizedError(settings.messages.unauthorized, details);
+        }
+        if (resp.status === 403) {
+          throw ErrorFactory.createForbiddenError(settings.messages.forbidden, details);
+        }
+        if (resp.status === 429) {
+          throw ErrorFactory.createSecurityError(settings.messages.rateLimited, details);
+        }
+        if (resp.status >= 400 && resp.status < 500) {
+          throw ErrorFactory.createValidationError(settings.messages.rejected, details);
+        }
+
+        throw ErrorFactory.createConnectionError(settings.messages.error, {
+          status: resp.status,
+          details,
+        });
+      }
+
+      return (await asJson(resp)) as T;
+    } catch (error: unknown) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw ErrorFactory.createConnectionError(settings.messages.timedOut, {
+          timeoutMs: settings.timeoutMs,
+        });
+      }
+      throw error;
+    }
+  },
+});
+
+export default RemoteSignedJson;

package/src/common/index.ts

@@ -0,0 +1,380 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import * as fs from '@node-singletons/fs';
+import * as path from '@node-singletons/path';
+import { fileURLToPath } from '@node-singletons/url';
+
+export { AwsSigV4 } from '@common/AwsSigV4';
+
+// Mutable FileChecker used to abstract FS checks for easier testing/mocking
+export const FileChecker = {
+  exists(filePath: string): boolean {
+    try {
+      return fs.existsSync(filePath);
+    } catch {
+      return false;
+    }
+  },
+};
+
+/**
+ * Common utilities - Sealed namespace for immutability
+ */
+export const CommonUtils = Object.freeze({
+  /**
+   * Resolve npm executable path from Node.js installation
+   */
+  resolveNpmPath(): string {
+    const nodeBinDir = path.dirname(process.execPath);
+    const candidates =
+      process.platform === 'win32'
+        ? [path.join(nodeBinDir, 'npm.cmd'), path.join(nodeBinDir, 'npm.exe')]
+        : [path.join(nodeBinDir, 'npm')];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+
+    throw ErrorFactory.createGeneralError(
+      'Unable to locate npm executable. Ensure Node.js (with npm) is installed in the standard location.'
+    );
+  },
+
+  /**
+   * RUNTIME UTILITIES
+   */
+
+  /**
+   * Async delay helper. No-ops when timers are unavailable.
+   */
+  async delay(ms: number): Promise<void> {
+    if (ms <= 0) return;
+    await new Promise<void>((resolve) => {
+      if (typeof globalThis.setTimeout !== 'function') {
+        resolve();
+        return;
+      }
+      globalThis.setTimeout(() => resolve(), ms);
+    });
+  },
+
+  /**
+   * Resolve an ESM `import.meta.url` to a filesystem path.
+   */
+  esmFilePath(metaUrl: string | URL): string {
+    return fileURLToPath(metaUrl);
+  },
+
+  /**
+   * Resolve an ESM `import.meta.url` to a filesystem directory.
+   */
+  esmDirname(metaUrl: string | URL): string {
+    return path.dirname(this.esmFilePath(metaUrl));
+  },
+
+  /**
+   * STRING UTILITIES
+   */
+
+  /**
+   * Convert string to camelCase
+   */
+  camelCase(str: string): string {
+    return (
+      str
+        // First convert PascalCase/camelCase to snake_case format for splitting
+        .replaceAll(/([a-z])([A-Z])/g, '$1_$2')
+        .split(/[\s_-]+/)
+        .map((word, index) => {
+          if (index === 0) {
+            return word.charAt(0).toLowerCase() + word.slice(1).toLowerCase();
+          }
+          return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+        })
+        .join('')
+    );
+  },
+
+  /**
+   * Convert string to snake_case
+   */
+  toSnakeCase(str: string): string {
+    return str
+      .replaceAll(/([a-z])([A-Z])/g, '$1_$2')
+      .replaceAll(/([A-Z])/g, '_$1')
+      .replaceAll(/(\d)([A-Z])/g, '$1_$2')
+      .toLowerCase()
+      .replace(/^_/, '')
+      .replaceAll(/__+/g, '_');
+  },
+
+  /**
+   * Convert string to PascalCase
+   */
+  toPascalCase(str: string): string {
+    return str
+      .replaceAll(/([a-z])([A-Z])/g, '$1_$2') // Add underscore before capital letters in camelCase
+      .split(/[\s_-]+/)
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+  },
+
+  /**
+   * FILE SYSTEM UTILITIES
+   */
+
+  /**
+   * Check if file exists
+   */
+  fileExists(filePath: string): boolean {
+    return FileChecker.exists(filePath);
+  },
+
+  /**
+   * Ensure directory exists, create if missing
+   */
+  ensureDir(dirPath: string): void {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true });
+    }
+  },
+
+  /**
+   * Best-effort variant of ensureDir() that never throws.
+   */
+  ensureDirSafe(dirPath: string): void {
+    try {
+      this.ensureDir(dirPath);
+    } catch {
+      // best-effort
+    }
+  },
+
+  /**
+   * Read file contents as string
+   */
+  readFile(filePath: string): string {
+    try {
+      return fs.readFileSync(filePath, 'utf-8');
+    } catch (error) {
+      throw ErrorFactory.createGeneralError(
+        `Failed to read file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  },
+
+  /**
+   * Read file contents as string (async)
+   */
+  async readFileAsync(filePath: string): Promise<string> {
+    try {
+      const fsPromises = await import('@node-singletons/fs').then((m) => m.fsPromises);
+      return await fsPromises.readFile(filePath, 'utf-8');
+    } catch (error) {
+      throw ErrorFactory.createGeneralError(
+        `Failed to read file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  },
+
+  /**
+   * Write file with optional directory creation
+   */
+  writeFile(filePath: string, content: string, createDir = true): void {
+    try {
+      if (createDir) {
+        const dir = path.dirname(filePath);
+        this.ensureDir(dir);
+      }
+      fs.writeFileSync(filePath, content, 'utf-8');
+    } catch (error) {
+      throw ErrorFactory.createGeneralError(
+        `Failed to write file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  },
+
+  /**
+   * Write file with optional directory creation (async)
+   */
+  async writeFileAsync(filePath: string, content: string, createDir = true): Promise<void> {
+    try {
+      const fsPromises = await import('@node-singletons/fs').then((m) => m.fsPromises);
+      if (createDir) {
+        const dir = path.dirname(filePath);
+        await fsPromises.mkdir(dir, { recursive: true });
+      }
+      await fsPromises.writeFile(filePath, content, 'utf-8');
+    } catch (error) {
+      throw ErrorFactory.createGeneralError(
+        `Failed to write file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  },
+
+  /**
+   * Delete file if it exists
+   */
+  deleteFile(filePath: string): void {
+    try {
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    } catch (error) {
+      throw ErrorFactory.createGeneralError(
+        `Failed to delete file: ${filePath}. ${error instanceof Error ? error.message : 'Unknown error'}`
+      );
+    }
+  },
+
+  /**
+   * TIMESTAMP UTILITIES
+   */
+
+  /**
+   * Get current timestamp in ISO format
+   */
+  getCurrentTimestamp(): string {
+    return new Date().toISOString();
+  },
+
+  /**
+   * Format timestamp for filenames (YYYY-MM-DDTHH-MM-SS-SSSZ)
+   */
+  formatTimestamp(date: Date = new Date()): string {
+    return date.toISOString().replaceAll(/[:.]/g, '-');
+  },
+
+  /**
+   * Parse ISO timestamp string to Date
+   */
+  parseTimestamp(timestamp: string): Date {
+    try {
+      const date = new Date(timestamp);
+      if (date.toString() === 'Invalid Date') {
+        throw ErrorFactory.createGeneralError('Invalid date');
+      }
+      return date;
+    } catch (error) {
+      throw ErrorFactory.createGeneralError(`Failed to parse timestamp: ${timestamp}`, error);
+    }
+  },
+
+  /**
+   * VALIDATION UTILITIES
+   */
+
+  /**
+   * Extract error message from unknown error type
+   */
+  extractErrorMessage(error: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+    if (typeof error === 'string') {
+      return error;
+    }
+    if (error !== undefined && error !== null && typeof error === 'object' && 'message' in error) {
+      return String((error as { message: unknown }).message);
+    }
+    return 'Unknown error occurred';
+  },
+
+  /**
+   * Validate options object and throw if invalid
+   */
+  validateOptions(
+    options: Record<string, unknown>,
+    requiredFields: string[],
+    context: string
+  ): void {
+    const missingFields = requiredFields.filter(
+      (field) => options[field] === undefined || options[field] === null
+    );
+    if (missingFields.length > 0) {
+      throw ErrorFactory.createGeneralError(
+        `${context}: Missing required options: ${missingFields.join(', ')}`
+      );
+    }
+  },
+
+  /**
+   * Check if value is valid (not null, undefined, or empty string)
+   */
+  isValid(value: unknown): boolean {
+    return value !== null && value !== undefined && value !== '';
+  },
+
+  /**
+   * Ensure value is string, throw otherwise
+   */
+  ensureString(value: unknown, fieldName: string): string {
+    if (typeof value !== 'string') {
+      throw ErrorFactory.createGeneralError(`${fieldName} must be a string, got ${typeof value}`);
+    }
+    return value;
+  },
+
+  /**
+   * Ensure value is object, throw otherwise
+   */
+  ensureObject(value: unknown, fieldName: string): Record<string, unknown> {
+    if (typeof value !== 'object' || value === null) {
+      throw ErrorFactory.createGeneralError(`${fieldName} must be an object, got ${typeof value}`);
+    }
+    return value as Record<string, unknown>;
+  },
+
+  /**
+   * Resolve preferred package manager.
+   * If `preferred` is provided, the first value is returned. Otherwise we detect by lock files.
+   */
+  resolvePackageManager(preferred?: string[]): string {
+    if (Array.isArray(preferred) && preferred.length > 0) {
+      return preferred[0];
+    }
+
+    try {
+      if (this.fileExists('pnpm-lock.yaml')) return 'pnpm';
+      if (this.fileExists('yarn.lock')) return 'yarn';
+      if (this.fileExists('package-lock.json')) return 'npm';
+    } catch {
+      // ignore FS errors and fall through to default
+    }
+
+    // Default to npm
+    return 'npm';
+  },
+});
+
+// Re-export for backward compatibility
+export const resolveNpmPath = (): string => CommonUtils.resolveNpmPath();
+
+export const delay = async (ms: number): Promise<void> => CommonUtils.delay(ms);
+
+export const esmFilePath = (metaUrl: string | URL): string => CommonUtils.esmFilePath(metaUrl);
+export const esmDirname = (metaUrl: string | URL): string => CommonUtils.esmDirname(metaUrl);
+
+export const resolvePackageManager = (preferred?: string[]): string => {
+  return CommonUtils.resolvePackageManager(preferred);
+};
+
+export const extractErrorMessage = (error: unknown): string =>
+  CommonUtils.extractErrorMessage(error);
+
+// Some call sites historically treated non-Error throws (e.g. string) as unknown.
+// Keep that behavior available as a shared helper.
+export const extractErrorMessageStrict = (error: unknown): string => {
+  if (error instanceof Error) return error.message;
+  if (error !== undefined && error !== null && typeof error === 'object' && 'message' in error) {
+    return String((error as { message: unknown }).message);
+  }
+  return 'Unknown error';
+};
+
+// Convenience named exports to make specific helpers testable and import-friendly
+export const fileExists = (filePath: string): boolean => CommonUtils.fileExists(filePath);
+export const ensureDir = (dirPath: string): void => CommonUtils.ensureDir(dirPath);
+export const ensureDirSafe = (dirPath: string): void => CommonUtils.ensureDirSafe(dirPath);
+export const readFile = (filePath: string): string => CommonUtils.readFile(filePath);
+export const writeFile = (filePath: string, content: string, createDir = true): void =>
+  CommonUtils.writeFile(filePath, content, createDir);

package/src/common/utility.ts

@@ -0,0 +1,140 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { randomBytes } from '@node-singletons/crypto';
+
+export const generateUuid = (): string => {
+  if (typeof globalThis?.crypto?.randomUUID === 'function') return globalThis.crypto.randomUUID();
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`; // NOSONAR
+};
+
+export function generateSecureJobId(
+  errMsg: string = 'Secure crypto API not available to generate a job id.'
+): string {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID();
+  }
+
+  if (typeof globalThis.crypto?.getRandomValues === 'function') {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return bytesToHex(bytes);
+  }
+
+  // Node fallback for environments without Web Crypto
+  try {
+    return randomBytes(16).toString('hex');
+  } catch (error) {
+    throw ErrorFactory.createTryCatchError(
+      errMsg || 'Secure crypto API not available to generate a job id.',
+      error
+    );
+  }
+}
+
+export const getString = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+function bytesToHex(bytes: Uint8Array): string {
+  let out = '';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+
+export function isEmpty(value: unknown): boolean {
+  return (
+    value === null ||
+    value === undefined ||
+    value === false ||
+    value === 0 ||
+    value === '' ||
+    value === '0'
+  );
+}
+
+export function toStr(value: unknown): string {
+  return String(value ?? '');
+}
+
+export function stripSpaces(value: unknown): string {
+  return toStr(value).replaceAll(' ', '');
+}
+
+export function sanitize(value: unknown, pattern: RegExp, stripSpace = false): string {
+  const input = stripSpace ? stripSpaces(value) : toStr(value);
+  return input.replace(pattern, '');
+}
+
+export function isNumericString(value: string): boolean {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  const n = Number(trimmed);
+  return Number.isFinite(n);
+}
+
+export function toPlusDecimal(num: unknown, dec = 8): number {
+  if (isEmpty(num)) return 0;
+
+  const numStr = toStr(num);
+  const hasDot = numStr.includes('.');
+  const hasExponent = /e/i.test(numStr);
+
+  const normalized = hasExponent ? Number(numStr).toFixed(dec + 1) : numStr;
+
+  const valueNew = hasDot
+    ? (() => {
+        const [whole, frac = ''] = normalized.split('.');
+        return Number.parseFloat(`${whole}.${frac.slice(0, dec)}`);
+      })()
+    : Number.parseFloat(normalized);
+
+  if (valueNew < 0 && String(valueNew).startsWith('-')) {
+    return 0;
+  }
+
+  return valueNew;
+}
+
+export function toMinusDecimal(num: unknown, dec = 8): number {
+  if (isEmpty(num)) return 0;
+
+  const numStr = toStr(num);
+  const hasDot = numStr.includes('.');
+  const hasExponent = /e/i.test(numStr);
+
+  const normalized = hasExponent ? Number(numStr).toFixed(dec + 1) : numStr;
+
+  if (hasDot) {
+    const [whole, frac = ''] = normalized.split('.');
+    return Number.parseFloat(`${whole}.${frac.slice(0, dec)}`);
+  }
+
+  return Number.parseFloat(normalized);
+}
+
+export const nowIso = (): string => new Date().toISOString();
+
+export interface UtilitiesType {
+  generateUuid: () => string;
+  getString: (value: unknown) => string;
+  generateSecureJobId: (errMsg?: string) => string;
+  isEmpty: (value: unknown) => boolean;
+  toStr: (value: unknown) => string;
+  stripSpaces: (value: unknown) => string;
+  sanitize: (value: unknown, pattern: RegExp, stripSpace?: boolean) => string;
+  isNumericString: (value: string) => boolean;
+  toPlusDecimal: (num: unknown, dec?: number) => number;
+  toMinusDecimal: (num: unknown, dec?: number) => number;
+  nowIso: () => string;
+}
+
+export const Utilities = Object.freeze({
+  generateUuid,
+  getString,
+  generateSecureJobId,
+  isEmpty,
+  toStr,
+  stripSpaces,
+  sanitize,
+  isNumericString,
+  toPlusDecimal,
+  toMinusDecimal,
+  nowIso,
+});