@willwade/aac-processors 0.1.7 → 0.1.8

package/dist/browser/processors/snap/helpers.js

@@ -0,0 +1,252 @@
+import { AACSemanticCategory, AACSemanticIntent } 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
+// therefore return empty collections until image resolution is implemented.
+function collectFiles(root, matcher, maxDepth = 3) {
+    const results = new Set();
+    const stack = [{ dir: root, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        if (current.depth > maxDepth)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(current.dir, { withFileTypes: true });
+        }
+        catch (error) {
+            continue;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(current.dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push({ dir: fullPath, depth: current.depth + 1 });
+            }
+            else if (matcher(fullPath)) {
+                results.add(fullPath);
+            }
+        }
+    }
+    return Array.from(results);
+}
+/**
+ * Build a map of button IDs to resolved image entries for a specific page.
+ * Mirrors the Grid helper for consumers that expect image reference data.
+ */
+export function getPageTokenImageMap(tree, pageId) {
+    const map = new Map();
+    const page = tree.getPage(pageId);
+    if (!page)
+        return map;
+    for (const btn of page.buttons) {
+        if (btn.resolvedImageEntry)
+            map.set(btn.id, String(btn.resolvedImageEntry));
+    }
+    return map;
+}
+/**
+ * Collect all image entry paths referenced in a Snap tree.
+ * Currently empty until resolvedImageEntry is populated by the processor.
+ */
+export function getAllowedImageEntries(_tree) {
+    return new Set();
+}
+/**
+ * Read a binary asset from a Snap pageset.
+ * Not implemented yet; provided for API symmetry with other processors.
+ */
+export function openImage(_dbOrFile, _entryPath) {
+    return null;
+}
+/**
+ * Find Tobii Communicator Snap package paths
+ * Searches in %LOCALAPPDATA%\Packages for Snap-related packages
+ * @param packageNamePattern Optional pattern to filter package names (default: 'TobiiDynavox')
+ * @returns Array of Snap package path information
+ */
+export function findSnapPackages(packageNamePattern = 'TobiiDynavox') {
+    const results = [];
+    // Only works on Windows
+    if (process.platform !== 'win32') {
+        return results;
+    }
+    try {
+        const localAppData = process.env.LOCALAPPDATA;
+        if (!localAppData) {
+            return results;
+        }
+        const packagesPath = path.join(localAppData, 'Packages');
+        // Check if Packages directory exists
+        if (!fs.existsSync(packagesPath)) {
+            return results;
+        }
+        // Enumerate packages
+        const packages = fs.readdirSync(packagesPath, { withFileTypes: true });
+        for (const packageDir of packages) {
+            if (!packageDir.isDirectory())
+                continue;
+            const packageName = packageDir.name;
+            // Filter by pattern
+            if (packageName.includes(packageNamePattern)) {
+                results.push({
+                    packageName,
+                    packagePath: path.join(packagesPath, packageName),
+                });
+            }
+        }
+    }
+    catch (error) {
+        // Silently fail if directory access fails
+    }
+    return results;
+}
+/**
+ * Find the first Snap package path matching the pattern
+ * Convenience method for when you expect only one Snap installation
+ * @param packageNamePattern Optional pattern to filter package names (default: 'TobiiDynavox')
+ * @returns Path to the first matching Snap package, or null if not found
+ */
+export function findSnapPackagePath(packageNamePattern = 'TobiiDynavox') {
+    const packages = findSnapPackages(packageNamePattern);
+    return packages.length > 0 ? packages[0].packagePath : null;
+}
+/**
+ * Find Snap user directories and their vocab files (.sps/.spb)
+ * Typical path:
+ * C:\Users\{username}\AppData\Roaming\Tobii Dynavox\Snap Scene\Users\{userId}\
+ * @param packageNamePattern Optional package filter (default TobiiDynavox)
+ * @returns Array of user info with vocab paths
+ */
+export function findSnapUsers(packageNamePattern = 'TobiiDynavox') {
+    const results = [];
+    if (process.platform !== 'win32') {
+        return results;
+    }
+    const packagePath = findSnapPackagePath(packageNamePattern);
+    if (!packagePath) {
+        return results;
+    }
+    const usersRoot = path.join(packagePath, 'LocalState', 'Users');
+    if (!fs.existsSync(usersRoot)) {
+        return results;
+    }
+    const entries = fs.readdirSync(usersRoot, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.toLowerCase().startsWith('swiftkey'))
+            continue;
+        const userPath = path.join(usersRoot, entry.name);
+        const vocabPaths = collectFiles(userPath, (full) => {
+            const ext = path.extname(full).toLowerCase();
+            return ext === '.sps' || ext === '.spb';
+        }, 2);
+        results.push({
+            userId: entry.name,
+            userPath,
+            vocabPaths,
+        });
+    }
+    return results;
+}
+/**
+ * Find vocab files for a specific Snap user (or all users)
+ * @param userId Optional user identifier filter (case-sensitive directory name)
+ * @param packageNamePattern Optional package filter
+ * @returns Array of vocab file paths
+ */
+export function findSnapUserVocabularies(userId, packageNamePattern = 'TobiiDynavox') {
+    const users = findSnapUsers(packageNamePattern).filter((u) => !userId || u.userId === userId);
+    return users.flatMap((u) => u.vocabPaths);
+}
+/**
+ * Attempt to find history/analytics files for a Snap user by name
+ * Currently searches for files containing "history" under the user directory
+ * @param userId User identifier (directory name)
+ * @param packageNamePattern Optional package filter
+ * @returns Array of history file paths (may be empty if not found)
+ */
+export function findSnapUserHistory(userId, packageNamePattern = 'TobiiDynavox') {
+    const user = findSnapUsers(packageNamePattern).find((u) => u.userId === userId);
+    if (!user)
+        return [];
+    return collectFiles(user.userPath, (full) => path.basename(full).toLowerCase().includes('history'), 2);
+}
+/**
+ * Check whether TD Snap appears to be installed (Windows only)
+ */
+export function isSnapInstalled(packageNamePattern = 'TobiiDynavox') {
+    if (process.platform !== 'win32')
+        return false;
+    return Boolean(findSnapPackagePath(packageNamePattern));
+}
+/**
+ * Read Snap usage history from a pageset file (.sps/.spb)
+ */
+export function readSnapUsage(pagesetPath) {
+    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();
+    const events = new Map();
+    for (const row of rows) {
+        const buttonId = 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,
+                },
+            };
+        entry.occurrences.push({
+            timestamp: dotNetTicksToDate(BigInt(row.TickValue ?? 0)),
+            modeling: row.Modeling === 1,
+            accessMethod: row.AccessMethod ?? null,
+            type: 'button',
+            buttonId: row.ButtonId,
+            intent: AACSemanticIntent.SPEAK_TEXT,
+            category: AACSemanticCategory.COMMUNICATION,
+        });
+        events.set(buttonId, entry);
+    }
+    return Array.from(events.values());
+}
+/**
+ * Read Snap usage history for a user (all pagesets)
+ */
+export function readSnapUsageForUser(userId, packageNamePattern = 'TobiiDynavox') {
+    const users = findSnapUsers(packageNamePattern).filter((u) => !userId || u.userId === userId);
+    const pagesets = users.flatMap((u) => u.vocabPaths);
+    return pagesets.flatMap((p) => readSnapUsage(p));
+}

package/dist/browser/utilities/analytics/history.js

@@ -0,0 +1,116 @@
+import { dotNetTicksToDate } from '../../utils/dotnetTicks';
+import { findGrid3Users, readAllGrid3History as readAllGrid3HistoryImpl, readGrid3History as readGrid3HistoryImpl, readGrid3HistoryForUser as readGrid3HistoryForUserImpl, } from '../../processors/gridset/helpers';
+import { findSnapUsers, readSnapUsage as readSnapUsageImpl, readSnapUsageForUser as readSnapUsageForUserImpl, } from '../../processors/snap/helpers';
+export { dotNetTicksToDate };
+const generateUuid = () => {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    // RFC4122-ish fallback for Node without crypto.randomUUID
+    const hex = '0123456789abcdef';
+    const bytes = Array.from({ length: 16 }, () => Math.floor(Math.random() * 256));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const toHex = (b) => hex[(b >> 4) & 0x0f] + hex[b & 0x0f];
+    return (toHex(bytes[0]) +
+        toHex(bytes[1]) +
+        toHex(bytes[2]) +
+        toHex(bytes[3]) +
+        '-' +
+        toHex(bytes[4]) +
+        toHex(bytes[5]) +
+        '-' +
+        toHex(bytes[6]) +
+        toHex(bytes[7]) +
+        '-' +
+        toHex(bytes[8]) +
+        toHex(bytes[9]) +
+        '-' +
+        toHex(bytes[10]) +
+        toHex(bytes[11]) +
+        toHex(bytes[12]) +
+        toHex(bytes[13]) +
+        toHex(bytes[14]) +
+        toHex(bytes[15]));
+};
+export function exportHistoryToBaton(entries, options) {
+    const exportDate = options?.exportDate instanceof Date
+        ? options.exportDate.toISOString()
+        : options?.exportDate || new Date().toISOString();
+    const anonymousUUID = options?.anonymousUUID || generateUuid();
+    const sentences = entries.map((entry) => ({
+        uuid: generateUuid(),
+        anonymousUUID,
+        content: entry.content,
+        metadata: entry.occurrences.map((occ) => ({
+            timestamp: occ.timestamp.toISOString(),
+            latitude: occ.latitude ?? null,
+            longitude: occ.longitude ?? null,
+        })),
+        source: entry.source,
+    }));
+    return {
+        version: options?.version || '1.0',
+        exportDate,
+        encryption: options?.encryption || 'none',
+        sentenceCount: sentences.length,
+        sentences,
+    };
+}
+/**
+ * Read Grid 3 phrase history from a history.sqlite database and tag entries with their source.
+ */
+export function readGrid3History(historyDbPath) {
+    return readGrid3HistoryImpl(historyDbPath).map((e) => ({
+        ...e,
+        source: 'Grid',
+    }));
+}
+/**
+ * Read Grid 3 history for a specific user/language combination.
+ */
+export function readGrid3HistoryForUser(userName, langCode) {
+    return readGrid3HistoryForUserImpl(userName, langCode).map((e) => ({
+        ...e,
+        source: 'Grid',
+    }));
+}
+/**
+ * Read every available Grid 3 history database on the machine.
+ */
+export function readAllGrid3History() {
+    return readAllGrid3HistoryImpl().map((e) => ({ ...e, source: 'Grid' }));
+}
+/**
+ * Read Snap button usage from a pageset database and tag entries with source.
+ */
+export function readSnapUsage(pagesetPath) {
+    return readSnapUsageImpl(pagesetPath).map((e) => ({ ...e, source: 'Snap' }));
+}
+/**
+ * Read Snap usage for a specific user across all discovered pagesets.
+ */
+export function readSnapUsageForUser(userId, packageNamePattern = 'TobiiDynavox') {
+    return readSnapUsageForUserImpl(userId, packageNamePattern).map((e) => ({
+        ...e,
+        source: 'Snap',
+    }));
+}
+export function listSnapUsers() {
+    return findSnapUsers();
+}
+/**
+ * List Grid 3 users on the current machine.
+ */
+export function listGrid3Users() {
+    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() {
+    const gridHistory = readAllGrid3History();
+    const snapHistory = findSnapUsers().flatMap((u) => readSnapUsageForUser(u.userId));
+    return [...gridHistory, ...snapHistory];
+}