@willwade/aac-processors 0.0.7 → 0.0.9

package/README.md

@@ -58,6 +58,37 @@ npm run build
 
 ---
 
+## Using with Electron
+
+`better-sqlite3` is a native module and must be rebuilt against Electron's Node.js runtime. If you see a `NODE_MODULE_VERSION` mismatch error, rebuild after installing dependencies:
+
+```bash
+npm install
+npx electron-rebuild
+```
+
+Or add a postinstall hook so the rebuild happens automatically:
+
+```json
+{
+  "scripts": {
+    "postinstall": "electron-builder install-app-deps"
+  }
+}
+```
+
+This step is only required for Electron apps; regular Node.js consumers do not need it.
+
+---
+
+## Windows Data Paths
+
+- **Grid 3 history**: `C:\Users\Public\Documents\Smartbox\Grid 3\Users\{username}\{langCode}\Phrases\history.sqlite`
+- **Grid 3 vocabularies**: `C:\Users\Public\Documents\Smartbox\Grid 3\Users\{username}\Grid Sets\`
+- **Snap vocabularies**: `C:\Users\{username}\AppData\Roaming\Tobii Dynavox\Snap Scene\Users\{userId}\` (`.sps`/`.spb`)
+
+---
+
 ## 🔧 Quick Start
 
 ### Basic Usage (TypeScript/ES6)
@@ -404,8 +435,8 @@ processor.saveFromTree(tree, "styled-board.spb");
 | **Grid3**         | ✅ Yes     | ✅ Yes       | ✅ Yes  | ✅ Style references             |
 | **Asterics Grid** | ✅ Yes     | ✅ Yes       | ✅ Yes  | ✅ Metadata-based               |
 | **Apple Panels**  | ✅ Yes     | ✅ Size only | ❌ No   | ✅ Display weight               |
-| **Dot**           |  ❌No     | ❌ Yes       | ❌ No   | ❌ Basic only                   |
-| **OPML**          |  ❌No     | ❌ Yes       | ❌ No   | ❌ Basic only                   |
+| **Dot**           | ❌No       | ❌ Yes       | ❌ No   | ❌ Basic only                   |
+| **OPML**          | ❌No       | ❌ Yes       | ❌ No   | ❌ Basic only                   |
 | **Excel**         | ✅ Yes     | ✅ Size only | ❌ No   | ✅ Display weight               |
 
 #### Cross-Format Styling Conversion
@@ -710,7 +741,6 @@ Inspired by the Python AACProcessors project
 - [ ] **Add Symbol Tools coverage** (currently 0%) - Implement tests for PCS and ARASAAC symbol lookups to reach >70% coverage
 - [ ] **Fix property-based test failures** - Resolve TypeScript interface compatibility issues in edge case generators
 
-
 ### Medium Priority
 
 - [ ] **Performance optimization** - Optimize memory usage for very large communication boards (1000+ buttons)

package/dist/analytics/history.d.ts

@@ -0,0 +1,57 @@
+import { dotNetTicksToDate } from '../utils/dotnetTicks';
+import { Grid3UserPath } from '../processors/gridset/helpers';
+import { 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 };
+/**
+ * Read Grid 3 phrase history from a history.sqlite database and tag entries with their source.
+ */
+export declare function readGrid3History(historyDbPath: string): HistoryEntry[];
+/**
+ * Read Grid 3 history for a specific user/language combination.
+ */
+export declare function readGrid3HistoryForUser(userName: string, langCode?: string): HistoryEntry[];
+/**
+ * Read every available Grid 3 history database on the machine.
+ */
+export declare function readAllGrid3History(): HistoryEntry[];
+/**
+ * Read Snap button usage from a pageset database and tag entries with source.
+ */
+export declare function readSnapUsage(pagesetPath: string): HistoryEntry[];
+/**
+ * Read Snap usage for a specific user across all discovered pagesets.
+ */
+export declare function readSnapUsageForUser(userId?: string, packageNamePattern?: string): HistoryEntry[];
+export declare function listSnapUsers(): SnapUserInfo[];
+/**
+ * List Grid 3 users on the current machine.
+ */
+export declare function listGrid3Users(): Grid3UserPath[];
+/**
+ * Convenience helper to gather all available history across Grid 3 and Snap.
+ * Returns an empty array if no history files are present.
+ */
+export declare function collectUnifiedHistory(): HistoryEntry[];

package/dist/analytics/history.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dotNetTicksToDate = void 0;
+exports.readGrid3History = readGrid3History;
+exports.readGrid3HistoryForUser = readGrid3HistoryForUser;
+exports.readAllGrid3History = readAllGrid3History;
+exports.readSnapUsage = readSnapUsage;
+exports.readSnapUsageForUser = readSnapUsageForUser;
+exports.listSnapUsers = listSnapUsers;
+exports.listGrid3Users = listGrid3Users;
+exports.collectUnifiedHistory = collectUnifiedHistory;
+const dotnetTicks_1 = require("../utils/dotnetTicks");
+Object.defineProperty(exports, "dotNetTicksToDate", { enumerable: true, get: function () { return dotnetTicks_1.dotNetTicksToDate; } });
+const helpers_1 = require("../processors/gridset/helpers");
+const helpers_2 = require("../processors/snap/helpers");
+/**
+ * Read Grid 3 phrase history from a history.sqlite database and tag entries with their source.
+ */
+function readGrid3History(historyDbPath) {
+    return (0, helpers_1.readGrid3History)(historyDbPath).map((e) => ({
+        ...e,
+        source: 'Grid',
+    }));
+}
+/**
+ * Read Grid 3 history for a specific user/language combination.
+ */
+function readGrid3HistoryForUser(userName, langCode) {
+    return (0, helpers_1.readGrid3HistoryForUser)(userName, langCode).map((e) => ({
+        ...e,
+        source: 'Grid',
+    }));
+}
+/**
+ * Read every available Grid 3 history database on the machine.
+ */
+function readAllGrid3History() {
+    return (0, helpers_1.readAllGrid3History)().map((e) => ({ ...e, source: 'Grid' }));
+}
+/**
+ * Read Snap button usage from a pageset database and tag entries with source.
+ */
+function readSnapUsage(pagesetPath) {
+    return (0, helpers_2.readSnapUsage)(pagesetPath).map((e) => ({ ...e, source: 'Snap' }));
+}
+/**
+ * Read Snap usage for a specific user across all discovered pagesets.
+ */
+function readSnapUsageForUser(userId, packageNamePattern = 'TobiiDynavox') {
+    return (0, helpers_2.readSnapUsageForUser)(userId, packageNamePattern).map((e) => ({
+        ...e,
+        source: 'Snap',
+    }));
+}
+function listSnapUsers() {
+    return (0, helpers_2.findSnapUsers)();
+}
+/**
+ * List Grid 3 users on the current machine.
+ */
+function listGrid3Users() {
+    return (0, helpers_1.findGrid3Users)();
+}
+/**
+ * Convenience helper to gather all available history across Grid 3 and Snap.
+ * Returns an empty array if no history files are present.
+ */
+function collectUnifiedHistory() {
+    const gridHistory = readAllGrid3History();
+    const snapHistory = (0, helpers_2.findSnapUsers)().flatMap((u) => readSnapUsageForUser(u.userId));
+    return [...gridHistory, ...snapHistory];
+}

package/dist/core/analyze.d.ts

@@ -1,6 +1,16 @@
 import { AACTree } from './treeStructure';
 import { BaseProcessor, ProcessorOptions } from './baseProcessor';
+/**
+ * Resolve a processor instance by friendly format name or common extension.
+ * @param format Format key or extension (e.g., 'snap', 'obf', 'xlsx')
+ * @param options Optional processor configuration
+ */
 export declare function getProcessor(format: string, options?: ProcessorOptions): BaseProcessor;
+/**
+ * Convenience helper to load a file into an AACTree using the inferred processor.
+ * @param file Path to the source file
+ * @param format Format key or extension (passed to getProcessor)
+ */
 export declare function analyze(file: string, format: string): {
     tree: AACTree;
 };

package/dist/core/analyze.js

@@ -11,6 +11,11 @@ const snapProcessor_1 = require("../processors/snapProcessor");
 const dotProcessor_1 = require("../processors/dotProcessor");
 const excelProcessor_1 = require("../processors/excelProcessor");
 const applePanelsProcessor_1 = require("../processors/applePanelsProcessor");
+/**
+ * Resolve a processor instance by friendly format name or common extension.
+ * @param format Format key or extension (e.g., 'snap', 'obf', 'xlsx')
+ * @param options Optional processor configuration
+ */
 function getProcessor(format, options) {
     const normalizedFormat = (format || '').toLowerCase();
     switch (normalizedFormat) {
@@ -42,6 +47,11 @@ function getProcessor(format, options) {
             throw new Error('Unknown format: ' + format);
     }
 }
+/**
+ * Convenience helper to load a file into an AACTree using the inferred processor.
+ * @param file Path to the source file
+ * @param format Format key or extension (passed to getProcessor)
+ */
 function analyze(file, format) {
     const processor = getProcessor(format);
     const tree = processor.loadIntoTree(file);

package/dist/core/stringCasing.d.ts

@@ -20,6 +20,9 @@ export declare enum StringCasing {
  * @param text - The text to analyze for casing pattern
  * @returns StringCasing enum value representing the detected casing
  */
+/**
+ * Infer the dominant casing style of a string (camel, pascal, snake, kebab, title, sentence, upper, lower).
+ */
 export declare function detectCasing(text: string): StringCasing;
 /**
  * Converts text to the specified casing
@@ -27,6 +30,11 @@ export declare function detectCasing(text: string): StringCasing;
  * @param targetCasing - The desired casing format
  * @returns The text converted to the target casing
  */
+/**
+ * Convert a string into the requested casing style.
+ * @param text Input string
+ * @param targetCasing Desired casing variant
+ */
 export declare function convertCasing(text: string, targetCasing: StringCasing): string;
 /**
  * Utility function to check if text is primarily numeric or empty
@@ -34,4 +42,7 @@ export declare function convertCasing(text: string, targetCasing: StringCasing):
  * @param text - The text to check
  * @returns True if the text should be considered non-meaningful
  */
+/**
+ * Check whether a string is empty or represents a numeric value.
+ */
 export declare function isNumericOrEmpty(text: string): boolean;

package/dist/core/stringCasing.js

@@ -27,6 +27,9 @@ var StringCasing;
  * @param text - The text to analyze for casing pattern
  * @returns StringCasing enum value representing the detected casing
  */
+/**
+ * Infer the dominant casing style of a string (camel, pascal, snake, kebab, title, sentence, upper, lower).
+ */
 function detectCasing(text) {
     if (!text || text.length === 0)
         return StringCasing.LOWER;
@@ -102,6 +105,11 @@ function detectCasing(text) {
  * @param targetCasing - The desired casing format
  * @returns The text converted to the target casing
  */
+/**
+ * Convert a string into the requested casing style.
+ * @param text Input string
+ * @param targetCasing Desired casing variant
+ */
 function convertCasing(text, targetCasing) {
     if (!text || text.length === 0)
         return text;
@@ -164,6 +172,9 @@ function convertCasing(text, targetCasing) {
  * @param text - The text to check
  * @returns True if the text should be considered non-meaningful
  */
+/**
+ * Check whether a string is empty or represents a numeric value.
+ */
 function isNumericOrEmpty(text) {
     const trimmed = text.trim();
     if (trimmed.length <= 1)

package/dist/index.d.ts

@@ -2,6 +2,7 @@ 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';
 /**
  * Factory function to get the appropriate processor for a file extension

package/dist/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.listHistorySnapUsers = exports.listHistoryGrid3Users = exports.collectUnifiedHistory = void 0;
 exports.getProcessor = getProcessor;
 exports.getSupportedExtensions = getSupportedExtensions;
 exports.isExtensionSupported = isExtensionSupported;
@@ -22,6 +23,10 @@ __exportStar(require("./core/treeStructure"), exports);
 __exportStar(require("./core/baseProcessor"), exports);
 __exportStar(require("./core/stringCasing"), exports);
 __exportStar(require("./processors"), exports);
+var history_1 = require("./analytics/history");
+Object.defineProperty(exports, "collectUnifiedHistory", { enumerable: true, get: function () { return history_1.collectUnifiedHistory; } });
+Object.defineProperty(exports, "listHistoryGrid3Users", { enumerable: true, get: function () { return history_1.listGrid3Users; } });
+Object.defineProperty(exports, "listHistorySnapUsers", { enumerable: true, get: function () { return history_1.listSnapUsers; } });
 const dotProcessor_1 = require("./processors/dotProcessor");
 const excelProcessor_1 = require("./processors/excelProcessor");
 const opmlProcessor_1 = require("./processors/opmlProcessor");

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

@@ -1,6 +1,20 @@
 import { AACTree } from '../../core/treeStructure';
+/**
+ * Build a map of button IDs to resolved image entry paths for a specific page.
+ * Helpful when rewriting zip entry names or validating images referenced in a grid.
+ */
 export declare function getPageTokenImageMap(tree: AACTree, pageId: string): Map<string, string>;
+/**
+ * Collect all image entries referenced across every page in a tree.
+ * Returns normalized zip entry paths that should be preserved when pruning images.
+ */
 export declare function getAllowedImageEntries(tree: AACTree): Set<string>;
+/**
+ * Read an image entry from a gridset zip by path.
+ * @param gridsetBuffer Gridset archive contents
+ * @param entryPath Entry name inside the zip
+ * @returns Image data buffer or null if not found
+ */
 export declare function openImage(gridsetBuffer: Buffer, entryPath: string): Buffer | null;
 /**
  * Generate a random GUID for Grid3 elements
@@ -32,3 +46,86 @@ export declare function createFileMapXml(grids: Array<{
     path: string;
     dynamicFiles?: string[];
 }>): string;
+/**
+ * Grid3 user data path information
+ */
+export interface Grid3UserPath {
+    userName: string;
+    langCode: string;
+    basePath: string;
+    historyDbPath: string;
+}
+export interface Grid3VocabularyPath {
+    userName: string;
+    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
+ * @returns Path to Common Documents folder
+ */
+export declare function getCommonDocumentsPath(): string;
+/**
+ * Find all Grid3 user data paths
+ * Searches for users and language codes in the Grid3 directory structure
+ * C:\Users\Public\Documents\Smartbox\Grid 3\Users\{UserName}\{langCode}\Phrases\history.sqlite
+ * Grid set/vocabulary archives live alongside users at:
+ * C:\Users\Public\Documents\Smartbox\Grid 3\Users\{UserName}\Grid Sets\
+ * @returns Array of Grid3 user path information
+ */
+export declare function findGrid3UserPaths(): Grid3UserPath[];
+/**
+ * Find all Grid3 history database paths
+ * Convenience method that returns just the database file paths
+ * @returns Array of paths to history.sqlite files
+ */
+export declare function findGrid3HistoryDatabases(): string[];
+/**
+ * Get Grid 3 users (alias of findGrid3UserPaths for clarity)
+ */
+export declare function findGrid3Users(): Grid3UserPath[];
+/**
+ * Find Grid 3 gridset/vocabulary files for each user
+ * @param userName Optional user filter; matches case-insensitively
+ * @returns Array of user/gridset path pairs
+ */
+export declare function findGrid3Vocabularies(userName?: string): Grid3VocabularyPath[];
+/**
+ * Find a specific user's Grid 3 history database
+ * @param userName User name to search for (case-insensitive)
+ * @param langCode Optional language code filter (case-insensitive)
+ * @returns Path to history.sqlite or null if not found
+ */
+export declare function findGrid3UserHistory(userName: string, langCode?: string): string | null;
+/**
+ * Check whether Grid 3 appears to be installed (Windows only)
+ */
+export declare function isGrid3Installed(): boolean;
+/**
+ * Read history events from a Grid 3 history.sqlite database.
+ * @param historyDbPath Absolute path to the history database
+ * @returns Parsed history entries grouped by phrase
+ */
+export declare function readGrid3History(historyDbPath: string): Grid3HistoryEntry[];
+/**
+ * Convenience wrapper to load history for a specific Grid 3 user/lang combination.
+ * @param userName Grid 3 user name (case-insensitive)
+ * @param langCode Optional language code to narrow selection (case-insensitive)
+ * @returns History entries for that user/language, or empty array if none
+ */
+export declare function readGrid3HistoryForUser(userName: string, langCode?: string): Grid3HistoryEntry[];
+/**
+ * Load all available Grid 3 histories on the machine.
+ * @returns Combined history entries from every discovered history.sqlite
+ */
+export declare function readAllGrid3History(): Grid3HistoryEntry[];