@willwade/aac-processors 0.0.6 → 0.0.8

package/dist/processors/snap/helpers.d.ts

@@ -1,4 +1,89 @@
 import { AACTree } from '../../core/treeStructure';
+/**
+ * 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 declare function getPageTokenImageMap(tree: AACTree, pageId: string): Map<string, string>;
+/**
+ * Collect all image entry paths referenced in a Snap tree.
+ * Currently empty until resolvedImageEntry is populated by the processor.
+ */
 export declare function getAllowedImageEntries(_tree: AACTree): Set<string>;
+/**
+ * Read a binary asset from a Snap pageset.
+ * Not implemented yet; provided for API symmetry with other processors.
+ */
 export declare function openImage(_dbOrFile: string | Buffer, _entryPath: string): Buffer | null;
+/**
+ * Snap package path information
+ */
+export interface SnapPackagePath {
+    packageName: string;
+    packagePath: string;
+}
+export interface SnapUserInfo {
+    userId: string;
+    userPath: string;
+    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
+ * @param packageNamePattern Optional pattern to filter package names (default: 'TobiiDynavox')
+ * @returns Array of Snap package path information
+ */
+export declare function findSnapPackages(packageNamePattern?: string): SnapPackagePath[];
+/**
+ * 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 declare function findSnapPackagePath(packageNamePattern?: string): string | null;
+/**
+ * Find Snap user directories and their vocab files (.sps/.spb)
+ * @param packageNamePattern Optional package filter (default TobiiDynavox)
+ * @returns Array of user info with vocab paths
+ */
+export declare function findSnapUsers(packageNamePattern?: string): SnapUserInfo[];
+/**
+ * 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 declare function findSnapUserVocabularies(userId?: string, packageNamePattern?: string): string[];
+/**
+ * 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 declare function findSnapUserHistory(userId: string, packageNamePattern?: string): string[];
+/**
+ * Check whether TD Snap appears to be installed (Windows only)
+ */
+export declare function isSnapInstalled(packageNamePattern?: string): boolean;
+/**
+ * Read Snap usage history from a pageset file (.sps/.spb)
+ */
+export declare function readSnapUsage(pagesetPath: string): SnapUsageEntry[];
+/**
+ * Read Snap usage history for a user (all pagesets)
+ */
+export declare function readSnapUsageForUser(userId?: string, packageNamePattern?: string): SnapUsageEntry[];

package/dist/processors/snap/helpers.js

@@ -1,11 +1,81 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPageTokenImageMap = getPageTokenImageMap;
 exports.getAllowedImageEntries = getAllowedImageEntries;
 exports.openImage = openImage;
+exports.findSnapPackages = findSnapPackages;
+exports.findSnapPackagePath = findSnapPackagePath;
+exports.findSnapUsers = findSnapUsers;
+exports.findSnapUserVocabularies = findSnapUserVocabularies;
+exports.findSnapUserHistory = findSnapUserHistory;
+exports.isSnapInstalled = isSnapInstalled;
+exports.readSnapUsage = readSnapUsage;
+exports.readSnapUsageForUser = readSnapUsageForUser;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const dotnetTicks_1 = require("../../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.
+ */
 function getPageTokenImageMap(tree, pageId) {
     const map = new Map();
     const page = tree.getPage(pageId);
@@ -17,11 +87,198 @@ function getPageTokenImageMap(tree, pageId) {
     }
     return map;
 }
+/**
+ * Collect all image entry paths referenced in a Snap tree.
+ * Currently empty until resolvedImageEntry is populated by the processor.
+ */
 function getAllowedImageEntries(_tree) {
-    // No known image entry paths for Snap yet
     return new Set();
 }
+/**
+ * Read a binary asset from a Snap pageset.
+ * Not implemented yet; provided for API symmetry with other processors.
+ */
 function openImage(_dbOrFile, _entryPath) {
-    // Not implemented for Snap yet
     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
+ */
+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
+ */
+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)
+ * @param packageNamePattern Optional package filter (default TobiiDynavox)
+ * @returns Array of user info with vocab paths
+ */
+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
+ */
+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)
+ */
+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)
+ */
+function isSnapInstalled(packageNamePattern = 'TobiiDynavox') {
+    if (process.platform !== 'win32')
+        return false;
+    return Boolean(findSnapPackagePath(packageNamePattern));
+}
+/**
+ * Read Snap usage history from a pageset file (.sps/.spb)
+ */
+function readSnapUsage(pagesetPath) {
+    if (!fs.existsSync(pagesetPath))
+        return [];
+    const db = new better_sqlite3_1.default(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: (0, dotnetTicks_1.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)
+ */
+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/processors/snapProcessor.js

@@ -476,11 +476,33 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                         serializedMetadata = audio.metadata || null;
                         useMessageRecording = 1;
                     }
-                    insertButton.run(buttonIdCounter++, button.label || '', button.message || button.label || '', navigatePageId, elementRefId, null, null, messageRecordingId, serializedMetadata, useMessageRecording, button.style?.fontColor ? parseInt(button.style.fontColor.replace('#', ''), 16) : null, button.style?.backgroundColor
-                        ? parseInt(button.style.backgroundColor.replace('#', ''), 16)
-                        : null, button.style?.borderColor
-                        ? parseInt(button.style.borderColor.replace('#', ''), 16)
-                        : null, button.style?.borderWidth, button.style?.fontSize, button.style?.fontFamily, button.style?.fontStyle ? parseInt(button.style.fontStyle) : null);
+                    // Retry logic for SQLite operations
+                    let retries = 3;
+                    while (retries > 0) {
+                        try {
+                            insertButton.run(buttonIdCounter++, button.label || '', button.message || button.label || '', navigatePageId, elementRefId, null, null, messageRecordingId, serializedMetadata, useMessageRecording, button.style?.fontColor
+                                ? parseInt(button.style.fontColor.replace('#', ''), 16)
+                                : null, button.style?.backgroundColor
+                                ? parseInt(button.style.backgroundColor.replace('#', ''), 16)
+                                : null, button.style?.borderColor
+                                ? parseInt(button.style.borderColor.replace('#', ''), 16)
+                                : null, button.style?.borderWidth, button.style?.fontSize, button.style?.fontFamily, button.style?.fontStyle ? parseInt(button.style.fontStyle) : null);
+                            break; // Success
+                        }
+                        catch (err) {
+                            if (err.code === 'SQLITE_IOERR' && retries > 1) {
+                                retries--;
+                                // Wait a bit before retrying
+                                const now = Date.now();
+                                while (Date.now() - now < 100) {
+                                    /* busy wait */
+                                }
+                            }
+                            else {
+                                throw err;
+                            }
+                        }
+                    }
                     // Insert ElementPlacement
                     const insertPlacement = db.prepare('INSERT INTO ElementPlacement (Id, ElementReferenceId, GridPosition) VALUES (?, ?, ?)');
                     insertPlacement.run(placementIdCounter++, elementRefId, gridPosition);

package/dist/processors/touchchat/helpers.d.ts

@@ -1,4 +1,16 @@
 import { AACTree } from '../../core/treeStructure';
+/**
+ * Build a map of button IDs to resolved image entry strings for a page.
+ * Returns an empty map when no images are present.
+ */
 export declare function getPageTokenImageMap(tree: AACTree, pageId: string): Map<string, string>;
+/**
+ * Collect all referenced image entries across the tree.
+ * Currently empty until TouchChat image resolution is implemented.
+ */
 export declare function getAllowedImageEntries(_tree: AACTree): Set<string>;
+/**
+ * Read a binary asset from a .ce file.
+ * Not implemented yet; provided for API symmetry with other processors.
+ */
 export declare function openImage(_ceFile: string | Buffer, _entryPath: string): Buffer | null;

package/dist/processors/touchchat/helpers.js

@@ -6,6 +6,10 @@ exports.openImage = openImage;
 // Minimal TouchChat helpers (stubs) to align with processors/<engine>/helpers pattern
 // NOTE: TouchChat buttons currently do not populate resolvedImageEntry; these helpers
 // therefore return empty collections until image resolution is implemented.
+/**
+ * Build a map of button IDs to resolved image entry strings for a page.
+ * Returns an empty map when no images are present.
+ */
 function getPageTokenImageMap(tree, pageId) {
     const map = new Map();
     const page = tree.getPage(pageId);
@@ -17,11 +21,17 @@ function getPageTokenImageMap(tree, pageId) {
     }
     return map;
 }
+/**
+ * Collect all referenced image entries across the tree.
+ * Currently empty until TouchChat image resolution is implemented.
+ */
 function getAllowedImageEntries(_tree) {
-    // No known image entry paths for TouchChat yet
     return new Set();
 }
+/**
+ * Read a binary asset from a .ce file.
+ * Not implemented yet; provided for API symmetry with other processors.
+ */
 function openImage(_ceFile, _entryPath) {
-    // Not implemented for TouchChat yet
     return null;
 }

package/dist/utils/dotnetTicks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Number of ticks (.NET 100ns units) between 0001-01-01 and Unix epoch.
+ */
+export declare const DOTNET_EPOCH_TICKS = 621355968000000000n;
+/**
+ * Number of ticks per millisecond.
+ */
+export declare const TICKS_PER_MILLISECOND = 10000n;
+/**
+ * Convert .NET ticks (100ns since 0001-01-01) to a JavaScript Date.
+ * Accepts bigint or number and rounds down to millisecond precision.
+ */
+export declare function dotNetTicksToDate(ticks: number | bigint): Date;

package/dist/utils/dotnetTicks.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TICKS_PER_MILLISECOND = exports.DOTNET_EPOCH_TICKS = void 0;
+exports.dotNetTicksToDate = dotNetTicksToDate;
+/**
+ * Number of ticks (.NET 100ns units) between 0001-01-01 and Unix epoch.
+ */
+exports.DOTNET_EPOCH_TICKS = 621355968000000000n;
+/**
+ * Number of ticks per millisecond.
+ */
+exports.TICKS_PER_MILLISECOND = 10000n;
+/**
+ * Convert .NET ticks (100ns since 0001-01-01) to a JavaScript Date.
+ * Accepts bigint or number and rounds down to millisecond precision.
+ */
+function dotNetTicksToDate(ticks) {
+    const tickValue = BigInt(ticks);
+    const ms = Number((tickValue - exports.DOTNET_EPOCH_TICKS) / exports.TICKS_PER_MILLISECOND);
+    return new Date(ms);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,17 +17,18 @@
     "test": "test"
   },
   "scripts": {
-    "build": "rimraf dist && mkdir dist && ./node_modules/typescript/bin/tsc",
+    "build": "rimraf dist && mkdir dist && tsc",
     "build:watch": "tsc --watch",
     "clean": "rimraf dist coverage",
-    "lint": "eslint 'src/**/*.{js,ts}' 'test/**/*.{js,ts}'",
-    "lint:fix": "eslint 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' --fix",
-    "format": "prettier --write 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' '*.{js,ts,json,md}'",
-    "format:check": "prettier --check 'src/**/*.{js,ts}' 'test/**/*.{js,ts}' '*.{js,ts,json,md}'",
+    "lint": "eslint \"src/**/*.{js,ts}\" \"test/**/*.{js,ts}\"",
+    "lint:fix": "eslint \"src/**/*.{js,ts}\" \"test/**/*.{js,ts}\" --fix",
+    "format": "prettier --write \"src/**/*.{js,ts}\" \"test/**/*.{js,ts}\" \"*.{js,ts,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{js,ts}\" \"test/**/*.{js,ts}\" \"*.{js,ts,json,md}\"",
     "test": "npm run build && jest",
     "test:watch": "npm run build && jest --watch",
     "test:coverage": "npm run build && jest --coverage",
     "test:ci": "npm run build && jest --coverage --ci --watchAll=false --testTimeout=30000",
+    "docs": "typedoc",
     "coverage:report": "node scripts/coverage-analysis.js",
     "type-check": "tsc --noEmit",
     "prepublishOnly": "npm run build",
@@ -88,6 +89,7 @@
     "prettier": "^3.5.3",
     "rimraf": "^5.0.5",
     "ts-jest": "^29.1.2",
+    "typedoc": "^0.28.14",
     "typescript": "~5.5.0"
   },
   "dependencies": {

package/docs/.keep

@@ -1 +0,0 @@
-