@i2analyze/notebook-sdk 1.9.0-dev.2 → 1.9.0-dev.3

package/lib/gen/notebook-sdk-public.d.ts

@@ -1662,6 +1662,145 @@ export declare namespace chart {
          */
         getRecordsOfType(itemType: schema.ChartItemTypeSpecifier): data.IReadOnlyCollection<records.IChartRecord>;
     }
+    /**
+     * Detailed information about the specific properties, notes, and source references that changed within a record.
+     *
+     * @remarks
+     * This interface provides granular change tracking at the property level.
+     * Empty sets indicate no changes occurred in that category.
+     *
+     * **Known Limitations:**
+     * - Only includes changes for properties that have been fetched. Changes to unfetched properties are not reported here.
+     * - Security dimension changes are not included in this interface.
+     * - If a record is reported as having changed but `recordChanges` shows empty sets for all categories, this may indicate unfetched property changes or security-only edits.
+     *
+     * @example
+     * ```typescript
+     * // Plugin code consuming recordChanges
+     * chartChangeListener((change) => {
+     *   if (change.type === 'minor' && change.recordChanges) {
+     *     change.recordChanges.forEach((recordId, changes) => {
+     *       // Check for property changes
+     *       if (changes.properties?.changed.size > 0) {
+     *         console.log('Properties changed:', changes.properties.changed);
+     *       }
+     *
+     *       // Check for note additions
+     *       if (changes.notes?.added.size > 0) {
+     *         console.log('Notes added:', changes.notes.added);
+     *       }
+     *
+     *       // Check for source reference edits
+     *       if (changes.sourceReferences?.edited.size > 0) {
+     *         console.log('Source references edited:', changes.sourceReferences.edited);
+     *       }
+     *
+     *       // Check for source reference removals
+     *       if (changes.sourceReferences?.removed.size > 0) {
+     *         console.log('Source references removed:', changes.sourceReferences.removed);
+     *       }
+     *     });
+     *   }
+     * });
+     * ```
+     *
+     * @i2since 1.9
+     */
+    export interface IRecordChanges {
+        /**
+         * Gets the property changes for this record.
+         *
+         * @remarks
+         * The property changes are categorized as follows:
+         * - Added: New properties that were set (property type IDs that were not previously set)
+         * - Removed: Properties that were removed (set to `null` or deleted)
+         * - Changed: Existing properties whose values were modified
+         *
+         * **Note:** If a property value oscillates within the same mutation (for example, A→B→A),
+         * it is still reported as "changed" since this tracks mutations, not just final state.
+         *
+         * Empty sets indicate no changes in that category.
+         *
+         * @i2since 1.9
+         */
+        readonly properties?: {
+            /**
+             * Gets the property type IDs for properties that were added to the record.
+             * @i2since 1.9
+             */
+            readonly added: data.IReadOnlyCollection<schema.PropertyTypeIdentifier>;
+            /**
+             * Gets the property type IDs for properties that were removed from the record.
+             * @i2since 1.9
+             */
+            readonly removed: data.IReadOnlyCollection<schema.PropertyTypeIdentifier>;
+            /**
+             * Gets the property type IDs for properties whose values were changed.
+             * @i2since 1.9
+             */
+            readonly changed: data.IReadOnlyCollection<schema.PropertyTypeIdentifier>;
+        };
+        /**
+         * Gets the note changes for this record.
+         *
+         * @remarks
+         * The note changes are categorized as follows:
+         * - Added: New notes that were created
+         * - Edited: Existing notes whose content was modified
+         * - Removed: Notes that were deleted
+         *
+         * Empty sets indicate no changes in that category.
+         *
+         * @i2since 1.9
+         */
+        readonly notes?: {
+            /**
+             * Gets the note IDs for notes that were added to the record.
+             * @i2since 1.9
+             */
+            readonly added: data.IReadOnlyCollection<data.NoteId>;
+            /**
+             * Gets the note IDs for notes whose content was edited.
+             * @i2since 1.9
+             */
+            readonly edited: data.IReadOnlyCollection<data.NoteId>;
+            /**
+             * Gets the note IDs for notes that were removed from the record.
+             * @i2since 1.9
+             */
+            readonly removed: data.IReadOnlyCollection<data.NoteId>;
+        };
+        /**
+         * Gets the source reference changes for this record.
+         *
+         * @remarks
+         * The source reference changes are categorized as follows:
+         * - Added: New source references that were added
+         * - Edited: Existing source references whose content was modified
+         * - Removed: Source references that were deleted
+         *
+         * Empty sets indicate no changes in that category.
+         *
+         * @i2since 1.9
+         */
+        readonly sourceReferences?: {
+            /**
+             * Gets the source reference IDs for source references that were added to the record.
+             * @i2since 1.9
+             */
+            readonly added: data.IReadOnlyCollection<data.SourceReferenceId>;
+            /**
+             * Gets the source reference IDs for source references whose content was edited.
+             * @i2since 1.9
+             */
+            readonly edited: data.IReadOnlyCollection<data.SourceReferenceId>;
+            /**
+             * Gets the source reference IDs for source references that were removed from the record.
+             * @i2since 1.9
+             */
+            readonly removed: data.IReadOnlyCollection<data.SourceReferenceId>;
+        };
+    }
     /**
      * A change that has occurred to the data in a chart.
      * @i2since 1.0
@@ -1671,14 +1810,18 @@ export declare namespace chart {
          * Gets the type of change (minor or major) made to the chart.
          *
          * @remarks
-         * When a "minor" change takes place, the change reports the detail of the affected elements and records.
-         * When a "major" change takes place, the expectation is that client code reloads the whole chart.
+         * The `type` field is always "minor" in current versions. The distinction between major and minor changes has been removed.
+         * This field will be removed in the next major release.
+         *
+         * @deprecated This field will be removed in the next major release. All changes now report detailed affected elements and records.
          * @i2since 1.0
+         *
          */
         readonly type: 'minor' | 'major';
     }
     /**
      * A major change that has occurred to the data on a chart.
+     * @deprecated Use {@link chart.IChartChange} instead. The `type` field is always "minor" and the distinction between major and minor changes has been removed. This interface will be removed in the next major release.
      * @i2since 1.0
      */
     export interface IChartChangeMajor extends IChartChangeBase {
@@ -1784,9 +1927,44 @@ export declare namespace chart {
              */
             readonly removed: data.IReadOnlyCollection<visual.ElementId>;
         };
+        /**
+         * Gets granular change details for records that changed in this chart update.
+         *
+         * @remarks
+         * This optional field provides property-level change tracking for records.
+         * When populated, it contains an entry for each record that changed, with detailed information about:
+         * - Which properties were added, removed, or changed
+         * - Which notes were added, edited, or removed
+         * - Which source references were added or removed
+         *     *
+         * **Usage Pattern:**
+         * ```typescript
+         * // New opt-in granularity
+         * change.recordChanges?.forEach((recordId, changes) => {
+         *   if (changes.properties?.changed.size > 0) {
+         *     console.log('Properties changed for', recordId);
+         *   }
+         * });
+         * ```
+         *
+         * **Known Limitations:**
+         *   Changes to unfetched properties are not reported here.
+         * - Security dimension changes are not included.
+         * - If a record appears in `records.changed` but has no corresponding entry in `recordChanges`,
+         *   or if the entry shows empty sets for all categories, this may indicate unfetched property changes
+         *   or security-only edits.
+         *
+         * @i2since 1.9
+         */
+        readonly recordChanges?: data.IKeyedReadOnlyCollection<records.AnalyzeRecordId, IRecordChanges>;
     }
     /**
      * A change to the data in a chart in i2 Notebook.
+     *
+     * @remarks
+     * Use this type for all chart change handling. The distinction between major and minor changes has been removed,
+     * and all changes now report detailed information about affected elements and records.
+     *
      * @i2since 1.0
      */
     export type IChartChange = IChartChangeMajor | IChartChangeMinor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@i2analyze/notebook-sdk",
-  "version": "1.9.0-dev.2",
+  "version": "1.9.0-dev.3",
   "description": "i2 Notebook SDK",
   "license": "MIT",
   "publishConfig": {