@global-torque/invest-core 0.2.2

package/src/form-validation/__tests__/investment.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import type { JSONSchemaType } from 'ajv/dist/types/json-schema';
+import {
+  composeInvestmentFormSchema,
+  createInvestmentAjv,
+  getReferenceType,
+  prepareInvestmentFormData,
+} from '../index.ts';
+
+describe('investment form policy', () => {
+  it('registers investment keywords per validator and keeps neutral validators isolated', () => {
+    const schema = { type: 'object', properties: { country: { type: 'string', mustBeUS: true } }, required: ['country'] } as unknown as JSONSchemaType<{ country: string }>;
+    const first = createInvestmentAjv();
+    const second = createInvestmentAjv();
+    expect(first.compile(schema)({ country: 'CA' })).toBe(false);
+    expect(second.compile(schema)({ country: 'CA' })).toBe(false);
+  });
+
+  it('does not mutate frontend or backend schemas while applying frontend precedence', () => {
+    const frontend = { type: 'object', properties: { name: { type: 'string', minLength: 2 } }, required: ['name'] } as unknown as JSONSchemaType<{ name: string }>;
+    const backend = { type: 'object', properties: { name: { type: 'string', minLength: 1, contentMediaType: 3 } }, required: ['name'] } as unknown as JSONSchemaType<{ name: string }>;
+    const beforeFrontend = JSON.stringify(frontend);
+    const beforeBackend = JSON.stringify(backend);
+    const composed = composeInvestmentFormSchema(frontend, backend);
+    expect((composed as any).properties.name.minLength).toBe(2);
+    expect((composed as any).properties.name.contentMediaType).toBeUndefined();
+    expect(JSON.stringify(frontend)).toBe(beforeFrontend);
+    expect(JSON.stringify(backend)).toBe(beforeBackend);
+  });
+
+  it('removes only backend root and named-definition requirements', () => {
+    const frontend = {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+    } as unknown as JSONSchemaType<{ name: string }>;
+    const backend = {
+      type: 'object',
+      required: ['legacyRoot'],
+      properties: {
+        details: {
+          type: 'object',
+          required: ['inlineField'],
+          properties: { inlineField: { type: 'string' } },
+        },
+      },
+      allOf: [{ required: ['composedField'] }],
+      definitions: {
+        LegacyDetails: {
+          type: 'object',
+          required: ['definitionField'],
+          properties: {
+            nested: {
+              type: 'object',
+              required: ['nestedField'],
+              properties: { nestedField: { type: 'string' } },
+            },
+          },
+        },
+      },
+      $defs: {
+        ModernDetails: {
+          type: 'object',
+          required: ['modernDefinitionField'],
+          anyOf: [{ required: ['composedDefinitionField'] }],
+        },
+      },
+    } as unknown as JSONSchemaType<{ name: string }>;
+    const beforeBackend = JSON.stringify(backend);
+
+    const composed = composeInvestmentFormSchema(frontend, backend) as any;
+
+    expect(composed.required).toBeUndefined();
+    expect(composed.definitions.LegacyDetails.required).toBeUndefined();
+    expect(composed.$defs.ModernDetails.required).toBeUndefined();
+    expect(composed.properties.details.required).toEqual(['inlineField']);
+    expect(composed.allOf[0].required).toEqual(['composedField']);
+    expect(composed.definitions.LegacyDetails.properties.nested.required).toEqual(['nestedField']);
+    expect(composed.$defs.ModernDetails.anyOf[0].required).toEqual(['composedDefinitionField']);
+    expect(JSON.stringify(backend)).toBe(beforeBackend);
+
+    const ajv = createInvestmentAjv();
+    const validate = ajv.compile(composed);
+    expect(validate({ name: 'Ada' })).toBe(false);
+    expect(validate.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({
+        keyword: 'required',
+        params: { missingProperty: 'composedField' },
+      }),
+    ]));
+    expect(validate({ name: 'Ada', composedField: true } as any)).toBe(true);
+  });
+
+  it('normalizes nested empty strings on a cloned model and preserves policy reference fallback', () => {
+    const model = { identity: { firstName: '', lastName: 'A' }, values: ['', 'x'] };
+    expect(prepareInvestmentFormData(model)).toEqual({ identity: { firstName: undefined, lastName: 'A' }, values: [undefined, 'x'] });
+    expect(model.identity.firstName).toBe('');
+    expect(getReferenceType({ $ref: '#/$defs/Entity' })).toBe('Entity');
+    expect(getReferenceType({ $ref: '#/$defs/Unknown' })).toBe('Individual');
+  });
+});

package/src/form-validation/ajv.ts

@@ -0,0 +1,109 @@
+import Ajv, { type Options } from 'ajv';
+import ajvErrors from 'ajv-errors';
+import addFormats from 'ajv-formats';
+import {
+  CHECKBOX_TRUE_ERROR_MESSAGE, CHECKBOX_TRUE_VALIDATOR_NAME,
+  ENUM_NAMES_VALIDATOR_NAME, FUTURE_DATE_ERROR_MESSAGE, FUTURE_DATE_VALIDATOR_NAME,
+  MAX_FILE_SIZE_VALIDATOR_NAME, MUST_BE_CITIZEN_ERROR_MESSAGE, MUST_BE_CITIZEN_VALIDATOR_NAME,
+  MUST_BE_US_ERROR_MESSAGE, MUST_BE_US_VALIDATOR_NAME, NOT_EMPTY_VALIDATOR_NAME,
+  NOT_ZERO_ERROR_MESSAGE, NOT_ZERO_VALIDATOR_NAME, ONLY_LETTERS_ERROR_MESSAGE,
+  ONLY_LETTERS_VALIDATOR_NAME, REQUIRED_ERROR_MESSAGE, UNDER_AGE_ERROR_MESSAGE,
+  UNDER_AGE_VALIDATOR_NAME, ZIP_REGEX_ERROR_MESSAGE, ZIP_REGEX_VALIDATOR_NAME,
+} from './constants.ts';
+
+export interface InvestmentAjvOptions {
+  /** Inject a clock for deterministic age and date validation tests. */
+  clock?: () => Date;
+}
+
+enum CitizenTypes {
+  us_citizen = 'U.S. Citizen',
+  us_resident = 'U.S. Resident',
+  us_non_resident = 'Non Resident',
+}
+
+const ONLY_LETTERS_REGEX = /^[A-Za-z\s]*[A-Za-z][A-Za-z\s]*$/;
+const ZIP_REGEX = /^\d{5}(-\d{4})?$/;
+
+export function createInvestmentAjv(
+  options: InvestmentAjvOptions = {},
+  ajvOptions: Options = {},
+): Ajv {
+  const now = options.clock ?? (() => new Date());
+  const ajv = new Ajv({ allErrors: true, allowMatchingProperties: true, $data: true, ...ajvOptions });
+
+  ajvErrors(ajv);
+  addFormats(ajv, ['date', 'time', 'float', 'email']);
+  // Backend schemas use file as an opaque string. Validation of size/content
+  // remains a host presentation concern and never weakens backend validation.
+  ajv.addFormat('file', { type: 'string', validate: () => true } as any);
+
+  const addKeywordWithMessage = (
+    keyword: string,
+    validate: (schema: unknown, data: unknown) => boolean,
+    message: string,
+  ) => {
+    ajv.addKeyword({ keyword, validate, error: { message } });
+  };
+
+  addKeywordWithMessage(
+    NOT_EMPTY_VALIDATOR_NAME,
+    (_schema, data) => data !== null && data !== undefined && typeof data === 'string' && data.trim() !== '',
+    REQUIRED_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(
+    MUST_BE_CITIZEN_VALIDATOR_NAME,
+    (_schema, data) => data === CitizenTypes.us_citizen || data === CitizenTypes.us_resident,
+    MUST_BE_CITIZEN_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(
+    MUST_BE_US_VALIDATOR_NAME,
+    (_schema, data) => {
+      const value = data as any;
+      const candidate = String(value && typeof value === 'object' && 'code' in value ? value.code : value).toLowerCase();
+      return candidate === 'us';
+    },
+    MUST_BE_US_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(CHECKBOX_TRUE_VALIDATOR_NAME, (_schema, data) => data === true, CHECKBOX_TRUE_ERROR_MESSAGE);
+  addKeywordWithMessage(
+    NOT_ZERO_VALIDATOR_NAME,
+    (schema, data) => schema ? typeof data === 'number' && data > 0 : true,
+    NOT_ZERO_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(
+    ONLY_LETTERS_VALIDATOR_NAME,
+    (_schema, data) => typeof data === 'string' && ONLY_LETTERS_REGEX.test(data),
+    ONLY_LETTERS_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(
+    ZIP_REGEX_VALIDATOR_NAME,
+    (_schema, data) => typeof data !== 'string' || data.length < 5 || ZIP_REGEX.test(data),
+    ZIP_REGEX_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(
+    UNDER_AGE_VALIDATOR_NAME,
+    (_schema, data) => {
+      const birthDate = new Date(data as any);
+      const current = now();
+      if (Number.isNaN(birthDate.getTime()) || birthDate.getTime() > current.getTime()) return true;
+      const eighteen = new Date(birthDate.getFullYear() + 18, birthDate.getMonth(), birthDate.getDate());
+      return eighteen <= current;
+    },
+    UNDER_AGE_ERROR_MESSAGE,
+  );
+  addKeywordWithMessage(
+    FUTURE_DATE_VALIDATOR_NAME,
+    (_schema, data) => {
+      const inputDate = new Date(data as any);
+      return Number.isNaN(inputDate.getTime()) || inputDate < now();
+    },
+    FUTURE_DATE_ERROR_MESSAGE,
+  );
+
+  // Legacy presentation annotations stay accepted for compatibility. They
+  // carry no file policy and do not alter server or transport validation.
+  ajv.addKeyword({ keyword: ENUM_NAMES_VALIDATOR_NAME });
+  ajv.addKeyword({ keyword: MAX_FILE_SIZE_VALIDATOR_NAME });
+  return ajv;
+}

package/src/form-validation/constants.ts

@@ -0,0 +1,22 @@
+export const PROPERTIES_KEY = 'properties';
+export const ERRORS_KEY = '__errors';
+export const NOT_EMPTY_VALIDATOR_NAME = 'notEmpty';
+export const REQUIRED_ERROR_MESSAGE = 'Please complete';
+export const MUST_BE_CITIZEN_VALIDATOR_NAME = 'mustBeCitizen';
+export const MUST_BE_CITIZEN_ERROR_MESSAGE = 'Sorry, non-resident cannot invest at this moment';
+export const ENUM_NAMES_VALIDATOR_NAME = 'enumNames';
+export const MAX_FILE_SIZE_VALIDATOR_NAME = 'maxFileSize';
+export const ONLY_LETTERS_VALIDATOR_NAME = 'onlyLetters';
+export const ONLY_LETTERS_ERROR_MESSAGE = 'Must contain only letters.';
+export const UNDER_AGE_VALIDATOR_NAME = 'underAge';
+export const UNDER_AGE_ERROR_MESSAGE = 'Must not be under 18';
+export const FUTURE_DATE_VALIDATOR_NAME = 'dateInFuture';
+export const FUTURE_DATE_ERROR_MESSAGE = 'Cannot set date in the future';
+export const ZIP_REGEX_VALIDATOR_NAME = 'zipRegex';
+export const ZIP_REGEX_ERROR_MESSAGE = 'Please enter a valid zip code.';
+export const CHECKBOX_TRUE_VALIDATOR_NAME = 'checkboxTrue';
+export const CHECKBOX_TRUE_ERROR_MESSAGE = 'Please check this box if you want to proceed';
+export const NOT_ZERO_VALIDATOR_NAME = 'numberNotZero';
+export const NOT_ZERO_ERROR_MESSAGE = 'Please complete';
+export const MUST_BE_US_VALIDATOR_NAME = 'mustBeUS';
+export const MUST_BE_US_ERROR_MESSAGE = 'Only US Residents are allowed to invest at this time.';

package/src/form-validation/general.ts

@@ -0,0 +1,114 @@
+import type { JSONSchemaType } from 'ajv/dist/types/json-schema';
+import cloneDeep from 'lodash/cloneDeep.js';
+import get from 'lodash/get.js';
+import pick from 'lodash/pick.js';
+import set from 'lodash/set.js';
+
+interface FilteredObjectElement {
+  $ref?: string;
+  enum?: Array<any>;
+  enumNames?: Array<string>;
+  items?: FilteredObjectElement;
+  minLength?: number;
+  mustBeUS?: boolean;
+  properties?: FilteredObject;
+  title?: string;
+  type?: string;
+}
+type FilteredObject = Record<string, FilteredObjectElement>;
+
+function cleanEnums(filteredObject: FilteredObject): FilteredObject {
+  Object.keys(filteredObject).forEach((key) => {
+    const element = filteredObject[key];
+    if (element.type === 'string' && element.enum) delete element.enum;
+  });
+  return filteredObject;
+}
+
+export function resolveRef(ref: string, schema: JSONSchemaType<any>) {
+  const refPath = ref.replace(/^#\//, '').split('/').map(segment => segment.replaceAll('~1', '/').replaceAll('~0', '~'));
+  return ref === '#' ? schema : get(schema, refPath);
+}
+
+export const getFilteredObject = (
+  schema: JSONSchemaType<any> | undefined,
+  formModel: Record<string, any>,
+  refPath: string = schema?.$ref || '',
+): FilteredObject => {
+  if (!schema || !formModel) return {};
+  const clonedSchema = cloneDeep(schema);
+  const resolvedObject = refPath ? resolveRef(refPath, clonedSchema) : clonedSchema;
+  if (!resolvedObject || !Object.keys(resolvedObject).length) return {};
+  delete resolvedObject.required;
+  set(clonedSchema, [], resolvedObject);
+  if (!Object.keys(formModel).length) return resolvedObject.properties;
+  return Object.entries(resolvedObject.properties ?? {}).reduce((filteredObject, [key, value]) => {
+    const schemaValue = value as FilteredObjectElement;
+    if (key in formModel) {
+      if (schemaValue.$ref) filteredObject[key] = getFilteredObject(schema, formModel[key], schemaValue.$ref) as FilteredObjectElement;
+      else if (schemaValue.type === 'array' && schemaValue.items?.$ref) filteredObject[key] = getFilteredObject(schema, formModel[key], schemaValue.items.$ref) as FilteredObjectElement;
+      else filteredObject[key] = schemaValue;
+    }
+    return filteredObject;
+  }, {} as FilteredObject);
+};
+
+export function getFieldSchema(path: string | undefined, ref: string | undefined, schema: JSONSchemaType<any>): any | undefined {
+  if (!path || !ref) return undefined;
+  const objectFromRefPath = resolveRef(ref, schema);
+  const pathSegments = path.split('.').filter(segment => Number.isNaN(Number(segment)));
+  const firstChild = pathSegments.shift();
+  const restSegments = pathSegments.join('.');
+  if (!firstChild || !objectFromRefPath?.properties) return undefined;
+  const segment0Property = objectFromRefPath.properties[firstChild];
+  if (segment0Property?.$ref) return getFieldSchema(restSegments, segment0Property.$ref, schema);
+  if (segment0Property?.type === 'array' && segment0Property.items?.$ref) return getFieldSchema(restSegments, segment0Property.items.$ref, schema);
+  return objectFromRefPath;
+}
+
+function removeRequiredFromDefinitions(schema: any) {
+  const visitSchemaRootAndDefinitions = (node: any, removeRootRequired: boolean) => {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+
+    if (removeRootRequired) delete node.required;
+
+    for (const key of ['definitions', '$defs']) {
+      const definitions = node[key];
+      if (!definitions || typeof definitions !== 'object' || Array.isArray(definitions)) continue;
+
+      for (const definition of Object.values(definitions)) {
+        visitSchemaRootAndDefinitions(definition, true);
+      }
+    }
+  };
+
+  // Backend projection may omit requirements at the schema root and at the
+  // roots of named definitions. Requirements on inline properties, items, and
+  // composition branches remain validation policy and must survive.
+  visitSchemaRootAndDefinitions(schema, true);
+  return schema;
+}
+
+export const filterSchema = (schema: JSONSchemaType<any>, formModel: any): any => {
+  if (!schema) return schema;
+  const newSchema = cloneDeep(schema);
+  const path = newSchema.$ref?.replace('#/', '')?.split('/') || [];
+  const mainDataObject: any = path.length ? get(newSchema, path.join('.')) : newSchema;
+  if (!mainDataObject?.properties) return newSchema;
+  delete mainDataObject.required;
+  set(newSchema, path, mainDataObject);
+  removeRequiredFromDefinitions(newSchema);
+  const keys = Object.keys(formModel || {});
+  set(newSchema, [...path, 'properties'], cleanEnums((keys.length ? pick(mainDataObject.properties, keys) : {}) as FilteredObject));
+  return newSchema;
+};
+
+export const undefinedEmptyProp = <T extends object>(data: T): T => {
+  const clone = cloneDeep(data) as any;
+  const visit = (value: any): any => {
+    if (Array.isArray(value)) return value.map(visit);
+    if (!value || typeof value !== 'object') return value === '' ? undefined : value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, visit(item)]));
+  };
+  return visit(clone) as T;
+};

package/src/form-validation/index.ts

@@ -0,0 +1,5 @@
+export * from './ajv.ts';
+export * from './constants.ts';
+export * from './general.ts';
+export * from './investment.ts';
+export * from './rules.ts';

package/src/form-validation/investment.ts

@@ -0,0 +1,65 @@
+import type { JSONSchemaType } from 'ajv/dist/types/json-schema';
+import cloneDeep from 'lodash/cloneDeep.js';
+import merge from 'lodash/merge.js';
+import { undefinedEmptyProp } from './general.ts';
+
+export type InvestmentSchema<T extends object = object> = JSONSchemaType<T> & Record<string, unknown>;
+
+function removeRequiredFromDefinitions(schema: any) {
+  // The backend projection is allowed to omit only schema-level requirements
+  // and requirements declared by named definitions. Inline field, item, and
+  // composition requirements remain validation policy and must survive.
+  const visitDefinitions = (node: any, includeRoot: boolean) => {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) return;
+    if (includeRoot) delete node.required;
+    for (const key of ['definitions', '$defs']) {
+      const definitions = node[key];
+      if (!definitions || typeof definitions !== 'object' || Array.isArray(definitions)) continue;
+      for (const definition of Object.values(definitions)) {
+        visitDefinitions(definition, true);
+      }
+    }
+  };
+  visitDefinitions(schema, true);
+  return schema;
+}
+
+function sanitizeContentMediaType(schema: any) {
+  const visit = (node: any) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) { node.forEach(visit); return; }
+    if ('contentMediaType' in node && typeof node.contentMediaType !== 'string') delete node.contentMediaType;
+    Object.values(node).forEach(value => {
+      if (value && typeof value === 'object') visit(value);
+    });
+  };
+  visit(schema);
+  return schema;
+}
+
+/**
+ * Compose app-owned frontend rules with backend schema metadata without
+ * mutating either input. Frontend fields take precedence while backend
+ * definitions retain compatibility with the legacy form projection.
+ */
+export function composeInvestmentFormSchema<T extends object>(
+  frontend: Readonly<JSONSchemaType<T>>,
+  backend: Readonly<JSONSchemaType<T>> | undefined,
+): JSONSchemaType<T> {
+  const frontendClone = cloneDeep(frontend);
+  if (!backend) return frontendClone;
+  const backendClone = sanitizeContentMediaType(removeRequiredFromDefinitions(cloneDeep(backend)));
+  return merge({}, backendClone, frontendClone) as JSONSchemaType<T>;
+}
+
+/** Preserve the old investment form empty-string normalization on a clone. */
+export function prepareInvestmentFormData<T extends object>(model: Readonly<T>): T {
+  return undefinedEmptyProp(model as T);
+}
+
+const REFERENCE_TYPES = new Set(['Individual', 'Entity', 'Trust', 'Sdira', 'Solo401k', 'SdiraEdit']);
+
+export function getReferenceType(schema?: { $ref?: string }): string {
+  const refType = schema?.$ref?.split('/').pop();
+  return refType && REFERENCE_TYPES.has(refType) ? refType : 'Individual';
+}

package/src/form-validation/rules.ts

@@ -0,0 +1,35 @@
+export const cityRule = { onlyLetters: true, title: 'city', type: 'string', minLength: 2 };
+export const stateRule = { onlyLetters: true, title: 'state', type: 'string', maxLength: 2, minLength: 2 };
+export const countryRule = { mustBeUS: true, title: 'country', minLength: 2 };
+export const countryRuleObject = { mustBeUS: true, title: 'country', minLength: 2 };
+export const zipRule = { title: 'zip_code', type: 'string', zipRegex: true };
+export const ssnRule = { maxLength: 9, minLength: 9, title: 'ssn', type: 'string' };
+export const phoneRule = { title: 'phone', type: 'string', minLength: 11 };
+export const address1Rule = { title: 'address1', type: 'string', minLength: 4 };
+export const address2Rule = { title: 'address2', type: 'string', minLength: 3 };
+export const dobRule = {
+  title: 'dob', type: 'string', format: 'date', underAge: true, dateInFuture: true,
+  errorMessage: { format: 'Please provide a valid date DD.MM.YYYY' },
+};
+export const middleNameRule = { title: 'middle_name', type: 'string', minLength: 2 };
+export const lastNameRule = { title: 'last_name', type: 'string', minLength: 2 };
+export const firstNameRule = { title: 'first_name', type: 'string', minLength: 2 };
+export const passwordRule = { minLength: 8, type: 'string' };
+export const codeRule = {};
+export const citizenshipRule = { mustBeCitizen: true, title: 'citizenship', type: 'string', minLength: 3 };
+export const emailRule = {
+  type: 'string', format: 'email', maxLength: 100,
+  errorMessage: { format: 'Please provide a valid email' },
+};
+export const descriptionFileRule = { minLength: 10, type: 'string' };
+export const noteFileRule = { minLength: 10, type: 'string' };
+export const accountHolderNameRule = { type: 'string', minLength: 4 };
+export const accountTypeRule = { type: 'string' };
+export const accountNumberRule = { type: 'string', minLength: 9, maxLength: 18 };
+export const routingNumbeRuler = { type: 'string', minLength: 9 };
+export const relationshipTypeRule = { type: 'string', minLength: 2 };
+export const typeProfileRule = { type: 'string', minLength: 3 };
+export const identificationTypeRule = { type: 'string', minLength: 3 };
+export const identificationNumberRule = { minLength: 3 };
+export const documentRule = { errorMessage: { minimum: 'Please provide a document' } };
+export const errorMessageRule = { required: 'Please complete' };

package/src/formatting/__tests__/buildInfo.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { formatBuildDisplay, formatBuildTimestamp } from '../buildInfo.ts';
+
+describe('buildInfo', () => {
+  it('formats build timestamps in a stable UTC label', () => {
+    expect(formatBuildTimestamp('2026-04-03T12:34:56.000Z')).toBe('Apr 3, 2026, 12:34 PM UTC');
+  });
+
+  it('falls back to the raw timestamp when parsing fails', () => {
+    expect(formatBuildTimestamp('custom-build-time')).toBe('custom-build-time');
+  });
+
+  it('formats commit labels with optional build details', () => {
+    expect(formatBuildDisplay('Commit: ', 'abc123', '2026-04-03T12:34:56.000Z'))
+      .toBe('Commit: abc123 (built at Apr 3, 2026, 12:34 PM UTC)');
+    expect(formatBuildDisplay('Commit: ', 'abc123')).toBe('Commit: abc123');
+    expect(formatBuildDisplay('Commit: ', '', '2026-04-03T12:34:56.000Z')).toBe('');
+  });
+});

package/src/formatting/__tests__/dateTime.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import {
+  formatLocalHoursMinutes,
+  formatToFullDate,
+  formatToShortMonthDateYear,
+} from '../dateTime.ts';
+
+describe('date/time formatting', () => {
+  it('formats full numeric dates with the existing en-US formatter', () => {
+    expect(formatToFullDate(new Date(2026, 3, 8))).toBe('4/8/2026');
+    expect(formatToFullDate('not-a-date')).toBe('-');
+    expect(formatToFullDate(undefined)).toBe('-');
+    expect(formatToFullDate(undefined, '')).toBe('');
+  });
+
+  it('formats short month dates for profile display', () => {
+    expect(formatToShortMonthDateYear(new Date(2026, 3, 8))).toBe('Apr 8, 2026');
+  });
+
+  it('formats local time as unpadded hours and padded minutes', () => {
+    expect(formatLocalHoursMinutes(new Date(2026, 3, 8, 9, 5))).toBe('9:05');
+    expect(formatLocalHoursMinutes(new Date(2026, 3, 8, 17, 0))).toBe('17:00');
+  });
+});

package/src/formatting/__tests__/display.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import {
+  capitalizeFirstLetter,
+  currency,
+} from '../display.ts';
+
+describe('display formatting', () => {
+  it('formats USD currency with the default two fractional digits', () => {
+    expect(currency(1234.5)).toBe('$1,234.50');
+    expect(currency(0)).toBe('$0.00');
+  });
+
+  it('uses the provided minimum fractional digits when formatting currency', () => {
+    expect(currency(12.5, 0)).toBe('$12.5');
+    expect(currency(12, 0)).toBe('$12');
+  });
+
+  it('formats missing, invalid, infinite, and negative currency values as zero', () => {
+    expect(currency(undefined)).toBe('$0.00');
+    expect(currency(Number.NaN)).toBe('$0.00');
+    expect(currency(Number.POSITIVE_INFINITY)).toBe('$0.00');
+    expect(currency(-1)).toBe('$0.00');
+  });
+
+  it('capitalizes the first character without changing the rest of the string', () => {
+    expect(capitalizeFirstLetter('wallet_update')).toBe('Wallet_update');
+    expect(capitalizeFirstLetter('already Capitalized')).toBe('Already Capitalized');
+    expect(capitalizeFirstLetter('')).toBe('');
+  });
+});

package/src/formatting/buildInfo.ts

@@ -0,0 +1,31 @@
+const buildDateTimeFormatter = new Intl.DateTimeFormat('en-US', {
+  year: 'numeric',
+  month: 'short',
+  day: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+  timeZone: 'UTC',
+  timeZoneName: 'short',
+});
+
+export function formatBuildTimestamp(buildTimestamp?: string): string {
+  if (!buildTimestamp) return '';
+
+  const parsedDate = new Date(buildTimestamp);
+  return Number.isNaN(parsedDate.getTime())
+    ? buildTimestamp
+    : buildDateTimeFormatter.format(parsedDate);
+}
+
+export function formatBuildDisplay(
+  prefix: string,
+  commitHash?: string,
+  buildTimestamp?: string,
+): string {
+  if (!commitHash) return '';
+
+  const formattedBuildTimestamp = formatBuildTimestamp(buildTimestamp);
+  return formattedBuildTimestamp
+    ? `${prefix}${commitHash} (built at ${formattedBuildTimestamp})`
+    : `${prefix}${commitHash}`;
+}

package/src/formatting/dateTime.ts

@@ -0,0 +1,43 @@
+const FULL_DATE_FORMATTER = new Intl.DateTimeFormat('en-US', {
+  year: 'numeric',
+  month: 'numeric',
+  day: 'numeric',
+});
+
+const SHORT_MONTH_DATE_YEAR_FORMATTER = new Intl.DateTimeFormat('en-US', {
+  month: 'short',
+  day: 'numeric',
+  year: 'numeric',
+});
+
+export type DateTimeInput = Date | string;
+
+const toDate = (value: DateTimeInput): Date => (
+  value instanceof Date ? value : new Date(value)
+);
+
+export const formatToFullDate = (
+  value?: DateTimeInput | null,
+  fallback = '-',
+): string => {
+  if (!value) return fallback;
+
+  const date = toDate(value);
+  if (Number.isNaN(date.getTime())) return fallback;
+
+  return FULL_DATE_FORMATTER.format(date);
+};
+
+export const formatToShortMonthDateYear = (value: DateTimeInput): string => (
+  SHORT_MONTH_DATE_YEAR_FORMATTER
+    .format(toDate(value))
+    .replace(/^[A-Z]/, (match) => match)
+);
+
+export const formatLocalHoursMinutes = (value: DateTimeInput): string => {
+  const date = toDate(value);
+  const hours = date.getHours();
+  const minutes = date.getMinutes().toString().padStart(2, '0');
+
+  return `${hours}:${minutes}`;
+};

package/src/formatting/display.ts

@@ -0,0 +1,24 @@
+const defaultCurrencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  minimumFractionDigits: 2,
+});
+
+const createCurrencyFormatter = (digits: number = 2) => new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  minimumFractionDigits: digits,
+});
+
+export function currency(val: number | undefined, digits?: number): string {
+  const formatter = digits !== undefined
+    ? createCurrencyFormatter(digits)
+    : defaultCurrencyFormatter;
+  const n = Number(val);
+  const safe = Number.isFinite(n) && n >= 0 ? n : 0;
+  return formatter.format(safe);
+}
+
+export const capitalizeFirstLetter = (str: string): string => (
+  str.charAt(0).toUpperCase() + str.slice(1)
+);

package/src/helpers/arrays.ts

@@ -0,0 +1,11 @@
+import { capitalizeFirstLetter } from './text';
+
+export function combineArraysToObjects(names: string[], values: string[]): { name: string; value: string }[] {
+  // Ensure both arrays have the same length to avoid mismatches
+  const length = Math.min(names.length, values.length);
+
+  return names.slice(0, length).map((name, index) => ({
+    name: capitalizeFirstLetter(name),
+    value: values[index],
+  }));
+}

package/src/helpers/currency.ts

@@ -0,0 +1,19 @@
+const defaultInstance = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  minimumFractionDigits: 2,
+});
+
+const instance = (digits: number = 2) => new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  minimumFractionDigits: digits,
+});
+
+export function currency(val: number | undefined, digits?: number) {
+  const formatter = digits !== undefined ? instance(digits) : defaultInstance;
+  const n = Number(val);
+  const safe = Number.isFinite(n) && n >= 0 ? n : 0;
+  return formatter.format(safe);
+}
+