@global-torque/invest-core 0.2.2

package/src/filer/__tests__/documentFormatter.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from 'vitest';
+import type { FilerObjectTree } from '@global-torque/domain-types/filerTypes';
+import { FilerFormatter } from '../documentFormatter.ts';
+
+describe('FilerFormatter', () => {
+  it('recursively flattens root/deep documents, excludes media, and uses Other for root files', () => {
+    const tree: FilerObjectTree = {
+      entities: {
+        root: { id: 1, filename: 'root.pdf', mime: 'application/pdf', created_at: 'invalid' },
+        agreements: {
+          name: 'investment_agreements',
+          entities: {
+            nested: { name: 'Nested', entities: {
+              deep: { id: '2', filename: 'deep.pdf', mime: 'application/pdf', created_at: '2026-01-02T00:00:00Z' },
+            } },
+            media: { name: 'media', entities: {
+              nestedImage: { id: 4, filename: 'nested-image.png', mime: 'image/png' },
+            } },
+          },
+        },
+        media: { name: 'media', entities: {
+          image: { id: 3, filename: 'image.png', mime: 'image/png' },
+        } },
+      },
+    };
+    const rows = FilerFormatter.getFormattedInvestmentDocuments(
+      [{ access: 'private', tree }],
+      'https://files.example.test',
+    );
+    expect(rows.map((row) => row.name)).toEqual(['deep.pdf', 'root.pdf']);
+    expect(rows.find((row) => row.id === 1)).toMatchObject({
+      category: 'other',
+      date: '—',
+      dateTimestamp: null,
+    });
+    expect(rows.every((row) => row.url === undefined)).toBe(true);
+  });
+
+  it('uses created_at before updated_at, keeps invalid dates last, and prefers public duplicate ids', () => {
+    const privateTree: FilerObjectTree = { entities: {
+      one: { id: 1, filename: 'private.pdf', mime: 'application/pdf', created_at: '2026-02-01T00:00:00Z' },
+      two: { id: 2, filename: 'older.pdf', mime: 'application/pdf', created_at: '2025-01-01T00:00:00Z', updated_at: '2026-06-01T00:00:00Z' },
+      three: { id: 3, filename: 'invalid.pdf', mime: 'application/pdf', created_at: 'invalid' },
+    } };
+    const publicTree: FilerObjectTree = { entities: {
+      one: { id: 1, filename: 'public.pdf', mime: 'application/pdf', created_at: '2026-02-01T00:00:00Z' },
+    } };
+    const rows = FilerFormatter.getFormattedInvestmentDocuments([
+      { access: 'private', tree: privateTree },
+      { access: 'public', tree: publicTree },
+    ], 'https://files.example.test');
+
+    expect(rows.map((row) => row.name)).toEqual(['public.pdf', 'older.pdf', 'invalid.pdf']);
+    expect(rows[0]).toMatchObject({ access: 'public', key: 'public:1' });
+    expect(rows[1].dateTimestamp).toBe(Date.parse('2025-01-01T00:00:00Z'));
+    expect(rows[2].dateTimestamp).toBeNull();
+  });
+
+  it('keeps identical filenames with different ids', () => {
+    const tree: FilerObjectTree = { entities: {
+      one: { id: 1, filename: 'same.pdf', mime: 'application/pdf' },
+      two: { id: 2, filename: 'same.pdf', mime: 'application/pdf' },
+    } };
+    expect(FilerFormatter.getFormattedInvestmentDocuments(
+      [{ access: 'private', tree }],
+      'https://files.example.test',
+    )).toHaveLength(2);
+  });
+
+  it('keeps minimal leaf nodes, prefers filename over metadata name, and does not mask invalid creation dates', () => {
+    const tree: FilerObjectTree = { entities: {
+      minimal: { id: 10, name: 'Minimal document' },
+      named: {
+        id: 11,
+        name: 'Metadata label',
+        filename: 'actual-file.pdf',
+        created_at: 'invalid',
+        updated_at: '2026-07-22T00:00:00Z',
+      },
+    } };
+
+    const rows = FilerFormatter.getFormattedInvestmentDocuments(
+      [{ access: 'private', tree }],
+      'https://files.example.test',
+    );
+
+    expect(rows.map(row => row.name)).toEqual(['Minimal document', 'actual-file.pdf']);
+    expect(rows.find(row => row.id === 11)).toMatchObject({
+      date: '—',
+      dateTimestamp: null,
+    });
+  });
+
+  it('keeps empty folders out of document rows and exposes them as folder tabs', () => {
+    const tree: FilerObjectTree = { entities: {
+      tax: {
+        id: 20,
+        type: 'folder',
+        name: 'Tax documents',
+        created_at: '2026-08-13T00:00:00Z',
+      },
+      agreements: {
+        id: 21,
+        type: 'folder',
+        name: 'investment_agreements',
+        entities: {
+          agreement: {
+            id: 22,
+            type: 'file',
+            filename: 'agreement.pdf',
+            mime: 'application/pdf',
+          },
+        },
+      },
+      rootDocument: {
+        id: 23,
+        type: 'file',
+        filename: 'root.pdf',
+        mime: 'application/pdf',
+      },
+    } };
+    const sources = [{ access: 'private' as const, tree }];
+
+    const rows = FilerFormatter.getFormattedInvestmentDocuments(
+      sources,
+      'https://files.example.test',
+    );
+
+    expect(rows.map(row => row.name)).toEqual(['agreement.pdf', 'root.pdf']);
+    expect(rows.some(row => row.id === 20)).toBe(false);
+    expect(FilerFormatter.getFolderedInvestmentDocuments(sources)).toEqual([
+      'Tax documents',
+      'Investment Agreements',
+      'Other',
+    ]);
+  });
+
+  it('keeps an original document but excludes its generated thumbnail descendants', () => {
+    const tree: FilerObjectTree = { entities: {
+      other: {
+        name: 'other',
+        entities: {
+          '95430aa4bf08da89aad368bc91f70bc1272a90c0': {
+            id: 698167,
+            filename: '95430aa4bf08da89aad368bc91f70bc1272a90c0',
+            original_filename: 'Gemini_Generated_Image.png',
+            mime: 'image/png',
+            type: 'file',
+            entities: {
+              big: {
+                name: 'big',
+                entities: {
+                  thumbnail: {
+                    id: 698172,
+                    original_filename: 'Gemini_Generated_Image.png',
+                    mime: 'image/avif',
+                    type: 'file_thumbnail',
+                    meta_data: { size: 'big' },
+                  },
+                },
+              },
+              medium: {
+                name: 'medium',
+                entities: {
+                  thumbnail: {
+                    id: 698170,
+                    original_filename: 'Gemini_Generated_Image.png',
+                    mime: 'image/avif',
+                    type: 'file_thumbnail',
+                    meta_data: { size: 'medium' },
+                  },
+                },
+              },
+              small: {
+                name: 'small',
+                entities: {
+                  thumbnail: {
+                    id: 698168,
+                    original_filename: 'Gemini_Generated_Image.png',
+                    mime: 'image/avif',
+                    type: 'file_thumbnail',
+                    meta_data: { size: 'small' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    } };
+
+    const rows = FilerFormatter.getFormattedInvestmentDocuments(
+      [{ access: 'public', tree }],
+      'https://files.example.test',
+    );
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      id: 698167,
+      name: 'Gemini_Generated_Image.png',
+      category: 'other',
+      typeFormatted: 'Other',
+    });
+    expect(FilerFormatter.getFolderedInvestmentDocuments([
+      { access: 'public', tree },
+    ])).toEqual(['Other']);
+  });
+});

package/src/filer/__tests__/publicImage.test.ts

@@ -0,0 +1,42 @@
+import {
+  describe,
+  expect,
+  it,
+} from 'vitest';
+import {
+  buildPublicFilerImageSource,
+  buildPublicFilerImageSrcset,
+  buildPublicFilerImageUrl,
+  getPublicFilerWidthDescriptor,
+} from '../publicImage';
+
+describe('publicImage', () => {
+  it('builds public filer image URLs with injected config', () => {
+    expect(buildPublicFilerImageUrl(42, 'medium', {
+      filerUrl: 'https://filer.example.com',
+    })).toBe('https://filer.example.com/public/files/42?size=medium');
+  });
+
+  it('passes direct image URLs through without filer config', () => {
+    expect(buildPublicFilerImageUrl('https://cdn.example.com/image.png')).toBe('https://cdn.example.com/image.png');
+    expect(buildPublicFilerImageUrl('/fallback.svg')).toBe('/fallback.svg');
+  });
+
+  it('builds width descriptors and srcsets', () => {
+    expect(getPublicFilerWidthDescriptor('484x290')).toBe(323);
+    expect(buildPublicFilerImageSrcset(42, {
+      filerUrl: 'https://filer.example.com',
+    })).toBe([
+      'https://filer.example.com/public/files/42?size=small 207w',
+      'https://filer.example.com/public/files/42?size=medium 323w',
+      'https://filer.example.com/public/files/42?size=big 683w',
+    ].join(', '));
+  });
+
+  it('falls back when filer config or image id is unavailable', () => {
+    expect(buildPublicFilerImageUrl(42)).toBeUndefined();
+    expect(buildPublicFilerImageSource(undefined, {
+      fallbackSrc: '/fallback.svg',
+    })).toBe('/fallback.svg');
+  });
+});

package/src/filer/documentFormatter.ts

@@ -0,0 +1,195 @@
+import type {
+  FilerAccess,
+  FilerId,
+  FilerObjectTree,
+  IFilerItem,
+} from '@global-torque/domain-types/filerTypes';
+
+export interface FilerDocumentSource {
+  access: FilerAccess;
+  tree?: FilerObjectTree | null;
+}
+
+export interface IFilerItemFormatted extends IFilerItem {
+  id: FilerId;
+  key: string;
+  access: FilerAccess;
+  actionUrl: string;
+  category: string;
+  date: string;
+  dateTimestamp: number | null;
+  isNew: boolean;
+  name: string;
+  tagColor?: string;
+  typeFormatted: string;
+}
+
+const MEDIA_CATEGORY = 'media';
+const OTHER_CATEGORY = 'other';
+const INVESTMENT_AGREEMENTS_CATEGORY = 'investment-agreements';
+const TWO_DAYS_MS = 2 * 24 * 60 * 60 * 1000;
+const DATE_FORMATTER = new Intl.DateTimeFormat('en-US', {
+  year: 'numeric',
+  month: 'numeric',
+  day: 'numeric',
+});
+
+const normalizeCategory = (value: unknown): string => {
+  if (typeof value !== 'string') return OTHER_CATEGORY;
+  const normalized = value.trim().toLowerCase().replace(/_/g, '-');
+  return normalized || OTHER_CATEGORY;
+};
+
+const capitalizeCategory = (value: string): string => value
+  .split('-')
+  .filter(Boolean)
+  .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+  .join(' ');
+
+const parseDate = (value: unknown): number | null => {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+};
+
+const formatDate = (timestamp: number | null): string => (
+  timestamp === null ? '—' : DATE_FORMATTER.format(new Date(timestamp))
+);
+
+const isFileNode = (node: IFilerItem): boolean => (
+  node.id !== undefined
+  && node.type !== 'folder'
+  && (!node.entities
+    || typeof node.filename === 'string'
+    || typeof node.original_filename === 'string'
+    || typeof node.mime === 'string'
+    || node.type === 'file'
+    || node.type === 'link')
+);
+
+const isDerivedThumbnail = (node: IFilerItem): boolean => node.type === 'file_thumbnail';
+
+const categoryForNode = (node: IFilerItem, inheritedCategory: string): string => {
+  const explicit = node['object-type'] ?? node['object-name'];
+  return explicit ? normalizeCategory(explicit) : inheritedCategory;
+};
+
+const collectRootCategories = (nodes: Record<string, IFilerItem>): string[] => (
+  Object.entries(nodes).flatMap(([nodeKey, node]) => {
+    const nodeCategory = categoryForNode(node, OTHER_CATEGORY);
+    const ownCategory = normalizeCategory(
+      node['object-type'] ?? node['object-name'] ?? node.name ?? nodeKey,
+    );
+    if (
+      nodeCategory === MEDIA_CATEGORY
+      || ownCategory === MEDIA_CATEGORY
+      || isDerivedThumbnail(node)
+    ) return [];
+
+    return [isFileNode(node) ? nodeCategory : ownCategory];
+  })
+);
+
+const collectFiles = (
+  nodes: Record<string, IFilerItem>,
+  access: FilerAccess,
+  filerBaseUrl: string,
+  nowMs: number,
+  inheritedCategory = OTHER_CATEGORY,
+): IFilerItemFormatted[] => Object.entries(nodes).flatMap(([nodeKey, node]) => {
+  const nodeCategory = categoryForNode(node, inheritedCategory);
+  if (nodeCategory === MEDIA_CATEGORY || isDerivedThumbnail(node)) return [];
+
+  if (isFileNode(node)) {
+    const id = node.id!;
+    const name = String(node.original_filename ?? node.filename ?? node.name ?? 'Document');
+    const hasCreatedAt = typeof node.created_at === 'string' && node.created_at.trim().length > 0;
+    const timestamp = hasCreatedAt ? parseDate(node.created_at) : parseDate(node.updated_at);
+    const ageMs = timestamp === null ? null : nowMs - timestamp;
+    const category = nodeCategory;
+    const baseUrl = filerBaseUrl.replace(/\/+$/, '');
+
+    return [{
+      ...node,
+      id,
+      key: `${access}:${String(id)}`,
+      access,
+      actionUrl: `${baseUrl}/${access === 'public' ? 'public' : 'auth'}/files/${encodeURIComponent(String(id))}`,
+      category,
+      'object-type': category,
+      name,
+      date: formatDate(timestamp),
+      dateTimestamp: timestamp,
+      isNew: ageMs !== null && ageMs >= 0 && ageMs < TWO_DAYS_MS,
+      tagColor: FilerFormatter.getTagColorByType(category),
+      typeFormatted: capitalizeCategory(category),
+      url: undefined,
+    }];
+  }
+
+  const ownFolderCategory = normalizeCategory(
+    node['object-type'] ?? node['object-name'] ?? node.name ?? nodeKey,
+  );
+  const folderCategory = inheritedCategory === OTHER_CATEGORY
+    ? ownFolderCategory
+    : inheritedCategory;
+  if (ownFolderCategory === MEDIA_CATEGORY || folderCategory === MEDIA_CATEGORY) return [];
+
+  return node.entities
+    ? collectFiles(node.entities, access, filerBaseUrl, nowMs, folderCategory)
+    : [];
+});
+
+export class FilerFormatter {
+  static getTagColorByType(objectType?: string): string | undefined {
+    switch (normalizeCategory(objectType)) {
+      case OTHER_CATEGORY:
+        return 'is--background-purple-light';
+      case INVESTMENT_AGREEMENTS_CATEGORY:
+        return 'is--background-secondary-light';
+      case 'company':
+        return 'is--background-yellow-light';
+      case 'agreement':
+        return 'is--background-primary-light';
+      default:
+        return undefined;
+    }
+  }
+
+  static getFormattedInvestmentDocuments(
+    sources: FilerDocumentSource[],
+    filerBaseUrl: string,
+    nowMs = Date.now(),
+  ): IFilerItemFormatted[] {
+    const byCanonicalId = new Map<string, IFilerItemFormatted>();
+
+    for (const source of sources) {
+      if (!source.tree) continue;
+      for (const item of collectFiles(source.tree.entities, source.access, filerBaseUrl, nowMs)) {
+        const canonicalId = String(item.id);
+        const existing = byCanonicalId.get(canonicalId);
+        if (!existing || source.access === 'public') byCanonicalId.set(canonicalId, item);
+      }
+    }
+
+    return [...byCanonicalId.values()].sort((left, right) => {
+      const leftFirst = left.category === INVESTMENT_AGREEMENTS_CATEGORY;
+      const rightFirst = right.category === INVESTMENT_AGREEMENTS_CATEGORY;
+      if (leftFirst !== rightFirst) return leftFirst ? -1 : 1;
+      const categoryOrder = left.typeFormatted.localeCompare(right.typeFormatted);
+      if (categoryOrder !== 0) return categoryOrder;
+      if (left.dateTimestamp === null && right.dateTimestamp !== null) return 1;
+      if (left.dateTimestamp !== null && right.dateTimestamp === null) return -1;
+      return (right.dateTimestamp ?? 0) - (left.dateTimestamp ?? 0);
+    });
+  }
+
+  static getFolderedInvestmentDocuments(sources: FilerDocumentSource[]): string[] {
+    const categories = new Set<string>();
+    for (const source of sources) {
+      if (!source.tree) continue;
+      for (const category of collectRootCategories(source.tree.entities)) categories.add(category);
+    }
+    return [...categories].map(capitalizeCategory);
+  }
+}

package/src/filer/publicImage.ts

@@ -0,0 +1,120 @@
+export const PUBLIC_FILER_IMAGE_SIZE_ORDER = ['small', 'medium', 'big'] as const;
+export type PublicFilerImageSize = (typeof PUBLIC_FILER_IMAGE_SIZE_ORDER)[number];
+
+export const DEFAULT_PUBLIC_FILER_IMAGE_DIMENSIONS: Record<PublicFilerImageSize, string> = {
+  small: '311x183',
+  medium: '484x290',
+  big: '1024x614',
+};
+
+export const PUBLIC_FILER_IMAGE_WIDTH_DIVISOR = 1.5;
+
+export interface BuildPublicFilerImageUrlOptions {
+  filerUrl?: string;
+}
+
+export interface BuildPublicFilerImageSrcsetOptions extends BuildPublicFilerImageUrlOptions {
+  dimensions?: Partial<Record<PublicFilerImageSize, string>>;
+  preferredSize?: PublicFilerImageSize;
+  requestedSizes?: PublicFilerImageSize[];
+  widthDivisor?: number;
+  fallbackSrc?: string;
+}
+
+const isDirectImageUrl = (value: string) => value.startsWith('http') || value.startsWith('/');
+
+const normalizeFilerFileId = (value?: number | string | null) => {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+  }
+
+  if (typeof value === 'string') {
+    if (isDirectImageUrl(value)) {
+      return value;
+    }
+
+    const parsedValue = Number(value);
+    return Number.isFinite(parsedValue) && parsedValue > 0 ? parsedValue : undefined;
+  }
+
+  return undefined;
+};
+
+export const getPublicFilerWidthDescriptor = (
+  dimension?: string,
+  widthDivisor: number = PUBLIC_FILER_IMAGE_WIDTH_DIVISOR,
+) => {
+  if (!dimension || !Number.isFinite(widthDivisor) || widthDivisor <= 0) {
+    return undefined;
+  }
+
+  const [rawWidth] = dimension.split('x');
+  const parsedWidth = Number(rawWidth);
+  if (!Number.isFinite(parsedWidth) || parsedWidth <= 0) {
+    return undefined;
+  }
+
+  return Math.max(1, Math.round(parsedWidth / widthDivisor));
+};
+
+export const buildPublicFilerImageUrl = (
+  fileId?: number | string | null,
+  size: PublicFilerImageSize = 'medium',
+  {
+    filerUrl,
+  }: BuildPublicFilerImageUrlOptions = {},
+) => {
+  const normalizedFileId = normalizeFilerFileId(fileId);
+
+  if (!normalizedFileId) {
+    return undefined;
+  }
+
+  if (typeof normalizedFileId === 'string') {
+    return normalizedFileId;
+  }
+
+  if (!filerUrl) {
+    return undefined;
+  }
+
+  return `${filerUrl}/public/files/${normalizedFileId}?size=${size}`;
+};
+
+export const buildPublicFilerImageSrcset = (
+  fileId?: number | string | null,
+  {
+    dimensions = DEFAULT_PUBLIC_FILER_IMAGE_DIMENSIONS,
+    requestedSizes = [...PUBLIC_FILER_IMAGE_SIZE_ORDER],
+    widthDivisor = PUBLIC_FILER_IMAGE_WIDTH_DIVISOR,
+    filerUrl,
+  }: BuildPublicFilerImageSrcsetOptions = {},
+) => {
+  const normalizedFileId = normalizeFilerFileId(fileId);
+  if (!normalizedFileId || typeof normalizedFileId === 'string') {
+    return '';
+  }
+
+  return requestedSizes
+    .map((size) => {
+      const url = buildPublicFilerImageUrl(normalizedFileId, size, { filerUrl });
+      const widthDescriptor = getPublicFilerWidthDescriptor(dimensions[size], widthDivisor);
+
+      if (!url || !widthDescriptor) {
+        return null;
+      }
+
+      return `${url} ${widthDescriptor}w`;
+    })
+    .filter((entry): entry is string => Boolean(entry))
+    .join(', ');
+};
+
+export const buildPublicFilerImageSource = (
+  fileId?: number | string | null,
+  {
+    preferredSize = 'medium',
+    fallbackSrc,
+    filerUrl,
+  }: BuildPublicFilerImageSrcsetOptions = {},
+) => buildPublicFilerImageUrl(fileId, preferredSize, { filerUrl }) ?? fallbackSrc;

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

@@ -0,0 +1,78 @@
+import Ajv from 'ajv';
+import { describe, expect, it } from 'vitest';
+import { filterSchema } from '../general.ts';
+
+describe('filterSchema', () => {
+  it('projects fields without removing inline requirements or mutating the source schema', () => {
+    const schema = {
+      type: 'object',
+      required: ['legacyRoot'],
+      properties: {
+        inline: {
+          type: 'object',
+          required: ['inlineField'],
+          properties: { inlineField: { type: 'string' } },
+        },
+        referenced: { $ref: '#/$defs/Named' },
+        items: {
+          type: 'array',
+          items: {
+            type: 'object',
+            required: ['itemField'],
+            properties: { itemField: { type: 'string' } },
+          },
+        },
+        choice: { type: 'string', enum: ['selected'] },
+        omitted: { type: 'string' },
+      },
+      allOf: [{
+        required: ['choice'],
+        properties: { choice: { type: 'string' } },
+      }],
+      $defs: {
+        Named: {
+          type: 'object',
+          required: ['namedRoot'],
+          properties: {
+            nested: {
+              type: 'object',
+              required: ['namedNested'],
+              properties: { namedNested: { type: 'string' } },
+            },
+          },
+        },
+      },
+    };
+    const before = JSON.stringify(schema);
+
+    const filtered = filterSchema(schema as any, {
+      inline: {},
+      referenced: {},
+      items: [],
+      choice: 'selected',
+    }) as any;
+
+    expect(JSON.stringify(schema)).toBe(before);
+    expect(filtered.required).toBeUndefined();
+    expect(filtered.properties.omitted).toBeUndefined();
+    expect(filtered.properties.choice.enum).toBeUndefined();
+    expect(filtered.properties.inline.required).toEqual(['inlineField']);
+    expect(filtered.properties.items.items.required).toEqual(['itemField']);
+    expect(filtered.allOf[0].required).toEqual(['choice']);
+    expect(filtered.$defs.Named.required).toBeUndefined();
+    expect(filtered.$defs.Named.properties.nested.required).toEqual(['namedNested']);
+
+    const validate = new Ajv({ allErrors: true, strict: false }).compile(filtered);
+    expect(validate({
+      inline: {},
+      referenced: { nested: {} },
+      items: [{}],
+      choice: 'selected',
+    })).toBe(false);
+    expect(validate.errors).toEqual(expect.arrayContaining([
+      expect.objectContaining({ instancePath: '/inline', keyword: 'required' }),
+      expect.objectContaining({ instancePath: '/referenced/nested', keyword: 'required' }),
+      expect.objectContaining({ instancePath: '/items/0', keyword: 'required' }),
+    ]));
+  });
+});