add in history methods for grid3 and snap

Author: willwade

src/analytics/history.ts

@@ -0,0 +1,87 @@
+import { dotNetTicksToDate } from '../utils/dotnetTicks';
+import {
+  findGrid3Users,
+  Grid3UserPath,
+  readAllGrid3History as readAllGrid3HistoryImpl,
+  readGrid3History as readGrid3HistoryImpl,
+  readGrid3HistoryForUser as readGrid3HistoryForUserImpl,
+} from '../processors/gridset/helpers';
+import {
+  findSnapUsers,
+  readSnapUsage as readSnapUsageImpl,
+  readSnapUsageForUser as readSnapUsageForUserImpl,
+  SnapUserInfo,
+} from '../processors/snap/helpers';
+
+export type HistorySource = 'Grid' | 'Snap';
+
+export interface HistoryOccurrence {
+  timestamp: Date;
+  latitude?: number | null;
+  longitude?: number | null;
+  modeling?: boolean;
+  accessMethod?: number | null;
+  pageId?: string | null;
+}
+
+export interface HistoryPlatformExtras {
+  label?: string;
+  message?: string;
+  buttonId?: string;
+  contentXml?: string;
+}
+
+export interface HistoryEntry {
+  id: string;
+  source: HistorySource;
+  content: string;
+  occurrences: HistoryOccurrence[];
+  raw?: unknown;
+  platform?: HistoryPlatformExtras;
+}
+
+export { dotNetTicksToDate };
+
+export function readGrid3History(historyDbPath: string): HistoryEntry[] {
+  return readGrid3HistoryImpl(historyDbPath).map((e) => ({ ...e, source: 'Grid' }));
+}
+
+export function readGrid3HistoryForUser(userName: string, langCode?: string): HistoryEntry[] {
+  return readGrid3HistoryForUserImpl(userName, langCode).map((e) => ({ ...e, source: 'Grid' }));
+}
+
+export function readAllGrid3History(): HistoryEntry[] {
+  return readAllGrid3HistoryImpl().map((e) => ({ ...e, source: 'Grid' }));
+}
+
+export function readSnapUsage(pagesetPath: string): HistoryEntry[] {
+  return readSnapUsageImpl(pagesetPath).map((e) => ({ ...e, source: 'Snap' }));
+}
+
+export function readSnapUsageForUser(
+  userId?: string,
+  packageNamePattern = 'TobiiDynavox'
+): HistoryEntry[] {
+  return readSnapUsageForUserImpl(userId, packageNamePattern).map((e) => ({
+    ...e,
+    source: 'Snap',
+  }));
+}
+
+export function listSnapUsers(): SnapUserInfo[] {
+  return findSnapUsers();
+}
+
+export function listGrid3Users(): Grid3UserPath[] {
+  return findGrid3Users();
+}
+
+/**
+ * Convenience helper to gather all available history across Grid 3 and Snap.
+ * Returns an empty array if no history files are present.
+ */
+export function collectUnifiedHistory(): HistoryEntry[] {
+  const gridHistory = readAllGrid3History();
+  const snapHistory = findSnapUsers().flatMap((u) => readSnapUsageForUser(u.userId));
+  return [...gridHistory, ...snapHistory];
+}

src/index.ts

@@ -3,6 +3,11 @@ export * from './core/treeStructure';
 export * from './core/baseProcessor';
 export * from './core/stringCasing';
 export * from './processors';
+export {
+  collectUnifiedHistory,
+  listGrid3Users as listHistoryGrid3Users,
+  listSnapUsers as listHistorySnapUsers,
+} from './analytics/history';
 
 import { BaseProcessor } from './core/baseProcessor';
 import { DotProcessor } from './processors/dotProcessor';

src/processors/gridset/helpers.ts

@@ -4,6 +4,8 @@ import { AACTree, AACPage, AACButton } from '../../core/treeStructure';
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
+import Database from 'better-sqlite3';
+import { dotNetTicksToDate } from '../../utils/dotnetTicks';
 
 function normalizeZipPath(p: string): string {
   const unified = p.replace(/\\/g, '/');
@@ -144,6 +146,17 @@ export interface Grid3VocabularyPath {
   gridsetPath: string;
 }
 
+export interface Grid3HistoryEntry {
+  id: string;
+  content: string;
+  occurrences: Array<{
+    timestamp: Date;
+    latitude?: number | null;
+    longitude?: number | null;
+  }>;
+  rawXml?: string;
+}
+
 /**
  * Get the Windows Common Documents folder path from registry
  * Falls back to default path if registry access fails
@@ -314,3 +327,81 @@ export function findGrid3UserHistory(userName: string, langCode?: string): strin
 
   return match?.historyDbPath ?? null;
 }
+
+function parseGrid3ContentXml(xmlContent: string): string {
+  const regex = /<r>(?:<!\[CDATA\[)?(.*?)(?:\]\]>)?<\/r>/gis;
+  const parts: string[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(xmlContent)) !== null) {
+    parts.push(match[1]);
+  }
+  if (parts.length > 0) {
+    return parts.join('');
+  }
+  return xmlContent.replace(/<[^>]+>/g, '').trim();
+}
+
+export function readGrid3History(historyDbPath: string): Grid3HistoryEntry[] {
+  if (!fs.existsSync(historyDbPath)) return [];
+
+  const db = new Database(historyDbPath, { readonly: true });
+  const rows = db
+    .prepare(
+      `
+      SELECT p.Id as PhraseId,
+             p.Text as TextValue,
+             p.Content as ContentXml,
+             ph.Timestamp as TickValue,
+             ph.Latitude as Latitude,
+             ph.Longitude as Longitude
+      FROM PhraseHistory ph
+      INNER JOIN Phrases p ON p.Id = ph.PhraseId
+      WHERE ph.Timestamp <> 0
+      ORDER BY ph.Timestamp ASC
+    `
+    )
+    .all() as Array<{
+    PhraseId: number;
+    TextValue?: string;
+    ContentXml?: string;
+    TickValue?: number | bigint;
+    Latitude?: number;
+    Longitude?: number;
+  }>;
+
+  const events = new Map<number, Grid3HistoryEntry>();
+
+  for (const row of rows) {
+    const phraseId: number = row.PhraseId;
+    const contentText = parseGrid3ContentXml(String(row.ContentXml ?? row.TextValue ?? ''));
+    const entry =
+      events.get(phraseId) ??
+      ({
+        id: `grid:${phraseId}`,
+        content: contentText,
+        occurrences: [],
+        rawXml: row.ContentXml,
+      } as Grid3HistoryEntry);
+
+    entry.occurrences.push({
+      timestamp: dotNetTicksToDate(BigInt(row.TickValue ?? 0)),
+      latitude: row.Latitude ?? null,
+      longitude: row.Longitude ?? null,
+    });
+
+    events.set(phraseId, entry);
+  }
+
+  return Array.from(events.values());
+}
+
+export function readGrid3HistoryForUser(userName: string, langCode?: string): Grid3HistoryEntry[] {
+  const dbPath = findGrid3UserHistory(userName, langCode);
+  if (!dbPath) return [];
+  return readGrid3History(dbPath);
+}
+
+export function readAllGrid3History(): Grid3HistoryEntry[] {
+  const paths = findGrid3HistoryDatabases();
+  return paths.flatMap((p) => readGrid3History(p));
+}

src/processors/index.ts

@@ -22,8 +22,12 @@ export {
   findGrid3Users,
   findGrid3Vocabularies,
   findGrid3UserHistory,
+  readGrid3History,
+  readGrid3HistoryForUser,
+  readAllGrid3History,
   type Grid3UserPath,
   type Grid3VocabularyPath,
+  type Grid3HistoryEntry,
 } from './gridset/helpers';
 export {
   getPageTokenImageMap as getGridsetPageTokenImageMap,
@@ -38,6 +42,9 @@ export {
   findGrid3Users as findGridsetUsers,
   findGrid3Vocabularies as findGridsetVocabularies,
   findGrid3UserHistory as findGridsetUserHistory,
+  readGrid3History as readGridsetHistory,
+  readGrid3HistoryForUser as readGridsetHistoryForUser,
+  readAllGrid3History as readAllGridsetHistory,
 } from './gridset/helpers';
 export { resolveGrid3CellImage } from './gridset/resolver';
 
@@ -85,8 +92,11 @@ export {
   findSnapUsers,
   findSnapUserVocabularies,
   findSnapUserHistory,
+  readSnapUsage,
+  readSnapUsageForUser,
   type SnapPackagePath,
   type SnapUserInfo,
+  type SnapUsageEntry,
 } from './snap/helpers';
 
 // TouchChat helpers (stubs)

src/processors/snap/helpers.ts

@@ -1,6 +1,8 @@
 import { AACTree } from '../../core/treeStructure';
 import * as fs from 'fs';
 import * as path from 'path';
+import Database from 'better-sqlite3';
+import { dotNetTicksToDate } from '../../utils/dotnetTicks';
 
 // Minimal Snap helpers (stubs) to align with processors/<engine>/helpers pattern
 // NOTE: Snap buttons currently do not populate resolvedImageEntry; these helpers
@@ -73,6 +75,21 @@ export interface SnapUserInfo {
   vocabPaths: string[];
 }
 
+export interface SnapUsageEntry {
+  id: string;
+  content: string;
+  occurrences: Array<{
+    timestamp: Date;
+    modeling?: boolean;
+    accessMethod?: number | null;
+  }>;
+  platform?: {
+    label?: string;
+    message?: string;
+    buttonId?: string;
+  };
+}
+
 /**
  * Find Tobii Communicator Snap package paths
  * Searches in %LOCALAPPDATA%\Packages for Snap-related packages
@@ -212,3 +229,88 @@ export function findSnapUserHistory(userId: string, packageNamePattern = 'TobiiD
     2
   );
 }
+
+/**
+ * Read Snap usage history from a pageset file (.sps/.spb)
+ */
+export function readSnapUsage(pagesetPath: string): SnapUsageEntry[] {
+  if (!fs.existsSync(pagesetPath)) return [];
+
+  const db = new Database(pagesetPath, { readonly: true });
+
+  const tableCheck = db
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('ButtonUsage','Button')"
+    )
+    .all();
+  if (tableCheck.length < 2) return [];
+
+  const rows = db
+    .prepare(
+      `
+      SELECT
+        bu.ButtonUniqueId as ButtonId,
+        bu.Timestamp as TickValue,
+        bu.Modeling as Modeling,
+        bu.AccessMethod as AccessMethod,
+        b.Label as Label,
+        b.Message as Message
+      FROM ButtonUsage bu
+      LEFT JOIN Button b ON bu.ButtonUniqueId = b.UniqueId
+      WHERE bu.Timestamp IS NOT NULL
+      ORDER BY bu.Timestamp ASC
+    `
+    )
+    .all() as Array<{
+    ButtonId?: string;
+    TickValue?: number | bigint;
+    Modeling?: number;
+    AccessMethod?: number;
+    Label?: string;
+    Message?: string;
+  }>;
+
+  const events = new Map<string, SnapUsageEntry>();
+
+  for (const row of rows) {
+    const buttonId: string = row.ButtonId ?? 'unknown';
+    const label = row.Label ?? undefined;
+    const message = row.Message ?? undefined;
+    const content = message || label || '';
+
+    const entry =
+      events.get(buttonId) ??
+      ({
+        id: `snap:${buttonId}`,
+        content,
+        occurrences: [],
+        platform: {
+          label,
+          message,
+          buttonId,
+        },
+      } as SnapUsageEntry);
+
+    entry.occurrences.push({
+      timestamp: dotNetTicksToDate(BigInt(row.TickValue ?? 0)),
+      modeling: row.Modeling === 1,
+      accessMethod: row.AccessMethod ?? null,
+    });
+
+    events.set(buttonId, entry);
+  }
+
+  return Array.from(events.values());
+}
+
+/**
+ * Read Snap usage history for a user (all pagesets)
+ */
+export function readSnapUsageForUser(
+  userId?: string,
+  packageNamePattern = 'TobiiDynavox'
+): SnapUsageEntry[] {
+  const users = findSnapUsers(packageNamePattern).filter((u) => !userId || u.userId === userId);
+  const pagesets = users.flatMap((u) => u.vocabPaths);
+  return pagesets.flatMap((p) => readSnapUsage(p));
+}

src/utils/dotnetTicks.ts

@@ -0,0 +1,8 @@
+export const DOTNET_EPOCH_TICKS = 621355968000000000n;
+export const TICKS_PER_MILLISECOND = 10000n;
+
+export function dotNetTicksToDate(ticks: number | bigint): Date {
+  const tickValue = BigInt(ticks);
+  const ms = Number((tickValue - DOTNET_EPOCH_TICKS) / TICKS_PER_MILLISECOND);
+  return new Date(ms);
+}