@memberjunction/version-history 0.0.1 → 4.1.0

package/dist/DiffEngine.js

@@ -0,0 +1,409 @@
+import { Metadata, RunView, LogError, } from '@memberjunction/core';
+import { ENTITY_VERSION_LABEL_ITEMS, ENTITY_VERSION_LABELS, ENTITY_RECORD_CHANGES, sqlEquals, loadRecordChangeSnapshot, loadEntityById, } from './constants.js';
+/**
+ * Compares state between two version labels, or between a label and the
+ * current live state, producing a structured diff grouped by entity.
+ */
+export class DiffEngine {
+    /**
+     * Compare two version labels.
+     */
+    async DiffLabels(fromLabelId, toLabelId, contextUser) {
+        // Short-circuit: identical labels produce an empty diff
+        if (fromLabelId === toLabelId) {
+            const label = await loadEntityById(ENTITY_VERSION_LABELS, fromLabelId, contextUser);
+            const labelName = label ? label.Name : fromLabelId;
+            return {
+                FromLabelID: fromLabelId,
+                FromLabelName: labelName,
+                ToLabelID: toLabelId,
+                ToLabelName: labelName,
+                Summary: { TotalRecordsChanged: 0, TotalRecordsAdded: 0, TotalRecordsModified: 0, TotalRecordsDeleted: 0, EntitiesAffected: 0 },
+                EntityDiffs: [],
+            };
+        }
+        const [fromLabel, toLabel] = await Promise.all([
+            loadEntityById(ENTITY_VERSION_LABELS, fromLabelId, contextUser),
+            loadEntityById(ENTITY_VERSION_LABELS, toLabelId, contextUser),
+        ]);
+        if (!fromLabel)
+            throw new Error(`Version label '${fromLabelId}' not found`);
+        if (!toLabel)
+            throw new Error(`Version label '${toLabelId}' not found`);
+        const [fromIndex, toIndex] = await Promise.all([
+            this.buildSnapshotIndex(fromLabelId, contextUser),
+            this.buildSnapshotIndex(toLabelId, contextUser),
+        ]);
+        const entityDiffs = await this.computeDiffs(fromIndex, toIndex, contextUser);
+        const summary = this.computeSummary(entityDiffs);
+        return {
+            FromLabelID: fromLabelId,
+            FromLabelName: fromLabel.Name,
+            ToLabelID: toLabelId,
+            ToLabelName: toLabel.Name,
+            Summary: summary,
+            EntityDiffs: entityDiffs,
+        };
+    }
+    /**
+     * Compare a version label to the current live state.
+     *
+     * For each record in the label, we find its current latest RecordChange
+     * and compare. Records that exist in the current state but not in the
+     * label are reported as Added; records in the label but not currently
+     * existing are reported as Deleted.
+     */
+    async DiffLabelToCurrentState(labelId, contextUser) {
+        const label = await loadEntityById(ENTITY_VERSION_LABELS, labelId, contextUser);
+        if (!label)
+            throw new Error(`Version label '${labelId}' not found`);
+        const fromIndex = await this.buildSnapshotIndex(labelId, contextUser);
+        // Build a "current" index: for each record in the from index, find
+        // its most recent RecordChange
+        const currentIndex = await this.buildCurrentIndex(fromIndex, contextUser);
+        const entityDiffs = await this.computeDiffs(fromIndex, currentIndex, contextUser);
+        const summary = this.computeSummary(entityDiffs);
+        return {
+            FromLabelID: labelId,
+            FromLabelName: label.Name,
+            ToLabelID: null,
+            ToLabelName: null,
+            Summary: summary,
+            EntityDiffs: entityDiffs,
+        };
+    }
+    /**
+     * Get the snapshot of a specific record at a specific label.
+     */
+    async GetRecordSnapshotAtLabel(entityName, recordId, labelId, contextUser) {
+        const md = new Metadata();
+        const entityInfo = md.EntityByName(entityName);
+        if (!entityInfo)
+            return null;
+        const rv = new RunView();
+        const filter = [
+            sqlEquals('VersionLabelID', labelId),
+            sqlEquals('EntityID', entityInfo.ID),
+            sqlEquals('RecordID', recordId),
+        ].join(' AND ');
+        const result = await rv.RunView({
+            EntityName: ENTITY_VERSION_LABEL_ITEMS,
+            ExtraFilter: filter,
+            Fields: ['ID', 'RecordChangeID', 'EntityID', 'RecordID'],
+            MaxRows: 1,
+            ResultType: 'simple',
+        }, contextUser);
+        if (!result.Success || result.Results.length === 0)
+            return null;
+        const item = result.Results[0];
+        return this.buildSnapshotFromRecordChange(item.RecordChangeID, entityName, entityInfo.ID, recordId, contextUser);
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Build an index from VersionLabelItems: key → RecordChangeID.
+     */
+    async buildSnapshotIndex(labelId, contextUser) {
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: ENTITY_VERSION_LABEL_ITEMS,
+            ExtraFilter: sqlEquals('VersionLabelID', labelId),
+            Fields: ['ID', 'RecordChangeID', 'EntityID', 'RecordID'],
+            ResultType: 'simple',
+        }, contextUser);
+        const index = new Map();
+        if (!result.Success) {
+            LogError(`DiffEngine: Failed to load label items for ${labelId}: ${result.ErrorMessage}`);
+            return index;
+        }
+        for (const item of result.Results) {
+            const key = `${item.EntityID}::${item.RecordID}`;
+            index.set(key, item.RecordChangeID);
+        }
+        return index;
+    }
+    /**
+     * Build a "current state" index by finding the latest RecordChange for
+     * each record in the fromIndex.
+     */
+    async buildCurrentIndex(fromIndex, contextUser) {
+        const currentIndex = new Map();
+        const rv = new RunView();
+        // Group by entityId for efficient batch queries
+        const byEntity = this.groupKeysByEntity(fromIndex);
+        for (const [entityId, recordIds] of byEntity) {
+            for (const recordId of recordIds) {
+                const latestId = await this.findLatestRecordChange(rv, entityId, recordId, contextUser);
+                if (latestId) {
+                    currentIndex.set(`${entityId}::${recordId}`, latestId);
+                }
+            }
+        }
+        return currentIndex;
+    }
+    /**
+     * Group composite keys from a SnapshotIndex by entityId.
+     */
+    groupKeysByEntity(index) {
+        const byEntity = new Map();
+        for (const compositeKey of index.keys()) {
+            const [entityId, recordId] = compositeKey.split('::');
+            if (!byEntity.has(entityId))
+                byEntity.set(entityId, []);
+            byEntity.get(entityId).push(recordId);
+        }
+        return byEntity;
+    }
+    /**
+     * Find the latest RecordChange ID for a given entity + record.
+     */
+    async findLatestRecordChange(rv, entityId, recordId, contextUser) {
+        const filter = [
+            sqlEquals('EntityID', entityId),
+            sqlEquals('RecordID', recordId),
+        ].join(' AND ');
+        const result = await rv.RunView({
+            EntityName: ENTITY_RECORD_CHANGES,
+            ExtraFilter: filter,
+            OrderBy: 'ChangedAt DESC',
+            MaxRows: 1,
+            Fields: ['ID'],
+            ResultType: 'simple',
+        }, contextUser);
+        if (result.Success && result.Results.length > 0) {
+            return result.Results[0].ID;
+        }
+        return null;
+    }
+    /**
+     * Compute diffs between two snapshot indices.
+     */
+    async computeDiffs(fromIndex, toIndex, contextUser) {
+        const allKeys = new Set([...fromIndex.keys(), ...toIndex.keys()]);
+        const md = new Metadata();
+        // Group diffs by entity
+        const entityGroups = new Map();
+        for (const compositeKey of allKeys) {
+            const [entityId, recordId] = compositeKey.split('::');
+            const fromChangeId = fromIndex.get(compositeKey) ?? null;
+            const toChangeId = toIndex.get(compositeKey) ?? null;
+            const entityName = this.resolveEntityName(md, entityId);
+            if (!entityGroups.has(entityId)) {
+                entityGroups.set(entityId, { entityId, records: [] });
+            }
+            const diff = await this.diffSingleRecord(entityName, recordId, fromChangeId, toChangeId, contextUser);
+            entityGroups.get(entityId).records.push(diff);
+        }
+        return this.buildEntityDiffGroups(entityGroups, md);
+    }
+    /**
+     * Resolve an entity name from metadata by ID, with fallback.
+     */
+    resolveEntityName(md, entityId) {
+        const entityInfo = md.Entities.find(e => e.ID === entityId);
+        return entityInfo?.Name ?? `Unknown(${entityId})`;
+    }
+    /**
+     * Convert the grouped map into an array of EntityDiffGroup,
+     * filtering out groups with no actual changes.
+     */
+    buildEntityDiffGroups(entityGroups, md) {
+        const result = [];
+        for (const [entityId, group] of entityGroups) {
+            const entityName = this.resolveEntityName(md, entityId);
+            const addedCount = group.records.filter(r => r.DiffType === 'Added').length;
+            const modifiedCount = group.records.filter(r => r.DiffType === 'Modified').length;
+            const deletedCount = group.records.filter(r => r.DiffType === 'Deleted').length;
+            // Skip groups with no changes
+            if (addedCount === 0 && modifiedCount === 0 && deletedCount === 0)
+                continue;
+            result.push({
+                EntityName: entityName,
+                EntityID: entityId,
+                Records: group.records.filter(r => r.DiffType !== 'Unchanged'),
+                AddedCount: addedCount,
+                ModifiedCount: modifiedCount,
+                DeletedCount: deletedCount,
+            });
+        }
+        return result;
+    }
+    /**
+     * Diff a single record between two RecordChange snapshots.
+     */
+    async diffSingleRecord(entityName, recordId, fromChangeId, toChangeId, contextUser) {
+        // Record exists only in "to" → Added
+        if (!fromChangeId && toChangeId) {
+            return this.buildAddedDiff(entityName, recordId, toChangeId, contextUser);
+        }
+        // Record exists only in "from" → Deleted
+        if (fromChangeId && !toChangeId) {
+            return this.buildDeletedDiff(entityName, recordId, fromChangeId, contextUser);
+        }
+        // Same RecordChange ID → Unchanged
+        if (fromChangeId === toChangeId) {
+            return this.buildUnchangedDiff(entityName, recordId);
+        }
+        // Both exist but differ → compare field-by-field
+        return this.buildModifiedDiff(entityName, recordId, fromChangeId, toChangeId, contextUser);
+    }
+    /**
+     * Build a diff result for a record that was added.
+     */
+    async buildAddedDiff(entityName, recordId, toChangeId, contextUser) {
+        const toSnapshot = await loadRecordChangeSnapshot(toChangeId, contextUser);
+        return {
+            RecordID: recordId,
+            EntityName: entityName,
+            DiffType: 'Added',
+            FieldChanges: [],
+            FromSnapshot: null,
+            ToSnapshot: toSnapshot,
+        };
+    }
+    /**
+     * Build a diff result for a record that was deleted.
+     */
+    async buildDeletedDiff(entityName, recordId, fromChangeId, contextUser) {
+        const fromSnapshot = await loadRecordChangeSnapshot(fromChangeId, contextUser);
+        return {
+            RecordID: recordId,
+            EntityName: entityName,
+            DiffType: 'Deleted',
+            FieldChanges: [],
+            FromSnapshot: fromSnapshot,
+            ToSnapshot: null,
+        };
+    }
+    /**
+     * Build a diff result for an unchanged record.
+     */
+    buildUnchangedDiff(entityName, recordId) {
+        return {
+            RecordID: recordId,
+            EntityName: entityName,
+            DiffType: 'Unchanged',
+            FieldChanges: [],
+            FromSnapshot: null,
+            ToSnapshot: null,
+        };
+    }
+    /**
+     * Build a diff result for a modified record by comparing snapshots field-by-field.
+     */
+    async buildModifiedDiff(entityName, recordId, fromChangeId, toChangeId, contextUser) {
+        const [fromSnapshot, toSnapshot] = await Promise.all([
+            loadRecordChangeSnapshot(fromChangeId, contextUser),
+            loadRecordChangeSnapshot(toChangeId, contextUser),
+        ]);
+        const fieldChanges = this.compareSnapshots(fromSnapshot, toSnapshot);
+        const diffType = fieldChanges.length > 0 ? 'Modified' : 'Unchanged';
+        return {
+            RecordID: recordId,
+            EntityName: entityName,
+            DiffType: diffType,
+            FieldChanges: fieldChanges,
+            FromSnapshot: fromSnapshot,
+            ToSnapshot: toSnapshot,
+        };
+    }
+    /**
+     * Build a RecordSnapshot from a RecordChange entry, using the shared
+     * loadRecordChangeSnapshot utility and wrapping the result.
+     */
+    async buildSnapshotFromRecordChange(recordChangeId, entityName, entityId, recordId, contextUser) {
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: ENTITY_RECORD_CHANGES,
+            ExtraFilter: sqlEquals('ID', recordChangeId),
+            Fields: ['ID', 'ChangedAt'],
+            MaxRows: 1,
+            ResultType: 'simple',
+        }, contextUser);
+        if (!result.Success || result.Results.length === 0)
+            return null;
+        const changedAt = result.Results[0].ChangedAt;
+        const parsed = await loadRecordChangeSnapshot(recordChangeId, contextUser);
+        if (!parsed)
+            return null;
+        return {
+            EntityName: entityName,
+            EntityID: entityId,
+            RecordID: recordId,
+            RecordChangeID: recordChangeId,
+            ChangedAt: new Date(changedAt),
+            FullRecordJSON: parsed,
+        };
+    }
+    /**
+     * Compare two parsed JSON snapshots field-by-field.
+     */
+    compareSnapshots(fromSnapshot, toSnapshot) {
+        if (!fromSnapshot || !toSnapshot)
+            return [];
+        const changes = [];
+        const allFields = new Set([...Object.keys(fromSnapshot), ...Object.keys(toSnapshot)]);
+        for (const field of allFields) {
+            // Skip internal timestamp fields
+            if (field.startsWith('__mj_'))
+                continue;
+            const oldVal = fromSnapshot[field];
+            const newVal = toSnapshot[field];
+            if (this.valuesEqual(oldVal, newVal))
+                continue;
+            const changeType = this.classifyFieldChange(oldVal, newVal);
+            changes.push({ FieldName: field, OldValue: oldVal, NewValue: newVal, ChangeType: changeType });
+        }
+        return changes;
+    }
+    /**
+     * Classify a field change as Added, Removed, or Modified.
+     */
+    classifyFieldChange(oldVal, newVal) {
+        if (oldVal === undefined || oldVal === null)
+            return 'Added';
+        if (newVal === undefined || newVal === null)
+            return 'Removed';
+        return 'Modified';
+    }
+    /**
+     * Equality check for field values.
+     * Handles null, identity, Date instances, and falls back to string comparison.
+     */
+    valuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (a == null && b == null)
+            return true;
+        if (a == null || b == null)
+            return false;
+        // Date instance comparison
+        if (a instanceof Date && b instanceof Date) {
+            return a.getTime() === b.getTime();
+        }
+        // String comparison fallback
+        return String(a) === String(b);
+    }
+    /**
+     * Compute summary statistics from entity diffs.
+     */
+    computeSummary(entityDiffs) {
+        let added = 0;
+        let modified = 0;
+        let deleted = 0;
+        for (const group of entityDiffs) {
+            added += group.AddedCount;
+            modified += group.ModifiedCount;
+            deleted += group.DeletedCount;
+        }
+        return {
+            TotalRecordsChanged: added + modified + deleted,
+            TotalRecordsAdded: added,
+            TotalRecordsModified: modified,
+            TotalRecordsDeleted: deleted,
+            EntitiesAffected: entityDiffs.length,
+        };
+    }
+}
+//# sourceMappingURL=DiffEngine.js.map

package/dist/DiffEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiffEngine.js","sourceRoot":"","sources":["../src/DiffEngine.ts"],"names":[],"mappings":"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"}

package/dist/LabelManager.d.ts

@@ -0,0 +1,41 @@
+import { UserInfo } from '@memberjunction/core';
+import { VersionLabelEntity } from '@memberjunction/core-entities';
+import { CreateLabelParams, LabelFilter } from './types.js';
+/**
+ * Manages the lifecycle of version labels: creation, querying, archiving,
+ * and status updates. Does NOT handle snapshot capture — that is delegated
+ * to SnapshotBuilder by the VersionHistoryEngine facade.
+ */
+export declare class LabelManager {
+    /**
+     * Create a new version label and persist it. Does not capture any snapshot
+     * items — the caller (VersionHistoryEngine) handles that separately.
+     */
+    CreateLabel(params: CreateLabelParams, contextUser: UserInfo): Promise<VersionLabelEntity>;
+    /**
+     * Load a single version label by ID.
+     */
+    GetLabel(labelId: string, contextUser: UserInfo): Promise<VersionLabelEntity>;
+    /**
+     * Query version labels with optional filters.
+     */
+    GetLabels(filter: LabelFilter, contextUser: UserInfo): Promise<VersionLabelEntity[]>;
+    /**
+     * Archive a label (set status to Archived).
+     */
+    ArchiveLabel(labelId: string, contextUser: UserInfo): Promise<boolean>;
+    /**
+     * Mark a label as having been used for a restore.
+     */
+    MarkLabelRestored(labelId: string, contextUser: UserInfo): Promise<boolean>;
+    private validateCreateParams;
+    private applyEntityScope;
+    private applyRecordScope;
+    private updateLabelStatus;
+    /**
+     * Build safe SQL filter clauses from a LabelFilter.
+     * Uses escapeSqlString for all user-supplied values.
+     */
+    private buildFilterClauses;
+}
+//# sourceMappingURL=LabelManager.d.ts.map

package/dist/LabelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LabelManager.d.ts","sourceRoot":"","sources":["../src/LabelManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,QAAQ,EAAuB,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAsB,MAAM,SAAS,CAAC;AAQ7E;;;;GAIG;AACH,qBAAa,YAAY;IACrB;;;OAGG;IACU,WAAW,CAAC,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BvG;;OAEG;IACU,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQ1F;;OAEG;IACU,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAuBjG;;OAEG;IACU,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAInF;;OAEG;IACU,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAQxF,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,gBAAgB;YAMV,iBAAiB;IAgB/B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CA4B7B"}

package/dist/LabelManager.js

@@ -0,0 +1,150 @@
+import { Metadata, RunView, LogError, LogStatus } from '@memberjunction/core';
+import { ENTITY_VERSION_LABELS, sqlEquals, sqlContains, loadEntityById, } from './constants.js';
+/**
+ * Manages the lifecycle of version labels: creation, querying, archiving,
+ * and status updates. Does NOT handle snapshot capture — that is delegated
+ * to SnapshotBuilder by the VersionHistoryEngine facade.
+ */
+export class LabelManager {
+    /**
+     * Create a new version label and persist it. Does not capture any snapshot
+     * items — the caller (VersionHistoryEngine) handles that separately.
+     */
+    async CreateLabel(params, contextUser) {
+        this.validateCreateParams(params);
+        const md = new Metadata();
+        const label = await md.GetEntityObject(ENTITY_VERSION_LABELS, contextUser);
+        label.Name = params.Name;
+        label.Description = params.Description ?? null;
+        label.Scope = params.Scope ?? 'Record';
+        label.CreatedByUserID = contextUser.ID;
+        label.ExternalSystemID = params.ExternalSystemID ?? null;
+        label.ParentID = params.ParentID ?? null;
+        label.Status = 'Active';
+        this.applyEntityScope(label, params, md);
+        this.applyRecordScope(label, params);
+        const saved = await label.Save();
+        if (!saved) {
+            throw new Error(`Failed to save version label '${params.Name}'`);
+        }
+        LogStatus(`VersionHistory: Created label '${params.Name}' (${label.ID}) with scope ${label.Scope}`);
+        return label;
+    }
+    /**
+     * Load a single version label by ID.
+     */
+    async GetLabel(labelId, contextUser) {
+        const label = await loadEntityById(ENTITY_VERSION_LABELS, labelId, contextUser);
+        if (!label) {
+            throw new Error(`Version label '${labelId}' not found`);
+        }
+        return label;
+    }
+    /**
+     * Query version labels with optional filters.
+     */
+    async GetLabels(filter, contextUser) {
+        const rv = new RunView();
+        const filterParts = this.buildFilterClauses(filter);
+        const extraFilter = filterParts.length > 0 ? filterParts.join(' AND ') : '';
+        const orderBy = filter.OrderBy ?? '__mj_CreatedAt DESC';
+        const maxRows = filter.MaxResults ?? 100;
+        const result = await rv.RunView({
+            EntityName: ENTITY_VERSION_LABELS,
+            ExtraFilter: extraFilter,
+            OrderBy: orderBy,
+            MaxRows: maxRows,
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (!result.Success) {
+            LogError(`LabelManager.GetLabels failed: ${result.ErrorMessage}`);
+            return [];
+        }
+        return result.Results;
+    }
+    /**
+     * Archive a label (set status to Archived).
+     */
+    async ArchiveLabel(labelId, contextUser) {
+        return this.updateLabelStatus(labelId, 'Archived', contextUser);
+    }
+    /**
+     * Mark a label as having been used for a restore.
+     */
+    async MarkLabelRestored(labelId, contextUser) {
+        return this.updateLabelStatus(labelId, 'Restored', contextUser);
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    validateCreateParams(params) {
+        if (!params.Name || params.Name.trim().length === 0) {
+            throw new Error('Version label Name is required');
+        }
+        if (params.Scope === 'Entity' && !params.EntityName) {
+            throw new Error('Entity scope requires EntityName');
+        }
+        if (params.Scope === 'Record') {
+            if (!params.EntityName)
+                throw new Error('Record scope requires EntityName');
+            if (!params.RecordKey)
+                throw new Error('Record scope requires RecordKey');
+        }
+    }
+    applyEntityScope(label, params, md) {
+        if (params.EntityName && (params.Scope === 'Entity' || params.Scope === 'Record')) {
+            const entityInfo = md.EntityByName(params.EntityName);
+            if (!entityInfo) {
+                throw new Error(`Entity '${params.EntityName}' not found in metadata`);
+            }
+            label.EntityID = entityInfo.ID;
+        }
+    }
+    applyRecordScope(label, params) {
+        if (params.RecordKey && params.Scope === 'Record') {
+            label.RecordID = params.RecordKey.ToConcatenatedString();
+        }
+    }
+    async updateLabelStatus(labelId, status, contextUser) {
+        const label = await this.GetLabel(labelId, contextUser);
+        label.Status = status;
+        const saved = await label.Save();
+        if (!saved) {
+            LogError(`LabelManager: Failed to update label '${labelId}' to status '${status}'`);
+            return false;
+        }
+        LogStatus(`VersionHistory: Label '${label.Name}' (${labelId}) status updated to ${status}`);
+        return true;
+    }
+    /**
+     * Build safe SQL filter clauses from a LabelFilter.
+     * Uses escapeSqlString for all user-supplied values.
+     */
+    buildFilterClauses(filter) {
+        const clauses = [];
+        if (filter.Scope) {
+            clauses.push(sqlEquals('Scope', filter.Scope));
+        }
+        if (filter.Status) {
+            clauses.push(sqlEquals('Status', filter.Status));
+        }
+        if (filter.EntityName) {
+            const md = new Metadata();
+            const entityInfo = md.EntityByName(filter.EntityName);
+            if (entityInfo) {
+                clauses.push(sqlEquals('EntityID', entityInfo.ID));
+            }
+        }
+        if (filter.RecordID) {
+            clauses.push(sqlEquals('RecordID', filter.RecordID));
+        }
+        if (filter.CreatedByUserID) {
+            clauses.push(sqlEquals('CreatedByUserID', filter.CreatedByUserID));
+        }
+        if (filter.NameContains) {
+            clauses.push(sqlContains('Name', filter.NameContains));
+        }
+        return clauses;
+    }
+}
+//# sourceMappingURL=LabelManager.js.map

package/dist/LabelManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LabelManager.js","sourceRoot":"","sources":["../src/LabelManager.ts"],"names":[],"mappings":"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"}