@twin.org/auditable-item-graph-models 0.0.3-next.2 → 0.0.3-next.20

package/dist/es/schemas/AuditableItemGraphPatchOperation.json

@@ -1,45 +1,54 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schema.twindev.org/aig/AuditableItemGraphPatchOperation",
+    "title": "AuditableItemGraphPatchOperation",
     "description": "The patch operation for JSON diffs.",
     "type": "object",
     "properties": {
         "@context": {
             "anyOf": [
                 {
-                    "type": "string",
                     "const": "https://schema.twindev.org/aig/"
                 },
                 {
                     "type": "array",
-                    "minItems": 1,
                     "prefixItems": [
                         {
-                            "type": "string",
                             "const": "https://schema.twindev.org/aig/"
                         }
                     ],
                     "items": {
                         "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
-                    }
+                    },
+                    "minItems": 1
                 }
             ],
             "description": "JSON-LD Context."
         },
         "type": {
-            "type": "string",
             "const": "AuditableItemGraphPatchOperation",
             "description": "JSON-LD Type."
         },
         "patchOperation": {
-            "type": "string",
-            "enum": [
-                "add",
-                "remove",
-                "replace",
-                "move",
-                "copy",
-                "test"
+            "anyOf": [
+                {
+                    "const": "add"
+                },
+                {
+                    "const": "remove"
+                },
+                {
+                    "const": "replace"
+                },
+                {
+                    "const": "move"
+                },
+                {
+                    "const": "copy"
+                },
+                {
+                    "const": "test"
+                }
             ],
             "description": "The operation that was performed on the item."
         },
@@ -56,10 +65,8 @@
         }
     },
     "required": [
-        "@context",
         "type",
         "patchOperation",
         "patchPath"
-    ],
-    "additionalProperties": false
+    ]
 }

package/dist/es/schemas/AuditableItemGraphResource.json

@@ -1,49 +1,31 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schema.twindev.org/aig/AuditableItemGraphResource",
+    "title": "AuditableItemGraphResource",
     "description": "Interface describing an auditable item graph vertex resource.",
     "type": "object",
     "properties": {
-        "id": {
-            "type": "string",
-            "description": "The id of the element."
-        },
-        "dateCreated": {
-            "type": "string",
-            "description": "The date/time of when the element was created."
-        },
-        "dateModified": {
-            "type": "string",
-            "description": "The date/time of when the element was modified."
-        },
-        "dateDeleted": {
-            "type": "string",
-            "description": "The date/time of when the element was deleted, as we never actually remove items."
-        },
         "@context": {
             "anyOf": [
                 {
-                    "type": "string",
                     "const": "https://schema.twindev.org/aig/"
                 },
                 {
                     "type": "array",
-                    "minItems": 1,
                     "prefixItems": [
                         {
-                            "type": "string",
                             "const": "https://schema.twindev.org/aig/"
                         }
                     ],
                     "items": {
                         "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
-                    }
+                    },
+                    "minItems": 1
                 }
             ],
             "description": "JSON-LD Context."
         },
         "type": {
-            "type": "string",
             "const": "AuditableItemGraphResource",
             "description": "JSON-LD Type."
         },
@@ -53,8 +35,11 @@
         }
     },
     "required": [
-        "@context",
         "type"
     ],
-    "additionalProperties": false
+    "allOf": [
+        {
+            "$ref": "https://schema.twindev.org/aig/AuditableItemGraphAuditedElement"
+        }
+    ]
 }

package/dist/es/schemas/AuditableItemGraphVertex.json

@@ -1,45 +1,31 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schema.twindev.org/aig/AuditableItemGraphVertex",
+    "title": "AuditableItemGraphVertex",
     "description": "Interface describing an auditable item graph vertex.",
     "type": "object",
     "properties": {
-        "id": {
-            "type": "string",
-            "description": "The id of the element."
-        },
-        "dateCreated": {
-            "type": "string",
-            "description": "The date/time of when the element was created."
-        },
-        "dateModified": {
-            "type": "string",
-            "description": "The date/time of when the element was modified."
-        },
-        "dateDeleted": {
-            "type": "string",
-            "description": "The date/time of when the element was deleted, as we never actually remove items."
-        },
         "@context": {
             "type": "array",
-            "minItems": 2,
-            "description": "JSON-LD Context.",
             "prefixItems": [
                 {
-                    "type": "string",
                     "const": "https://schema.twindev.org/aig/"
                 },
                 {
-                    "type": "string",
                     "const": "https://schema.twindev.org/common/"
                 }
             ],
             "items": {
                 "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
-            }
+            },
+            "minItems": 2,
+            "description": "JSON-LD Context."
         },
-        "type": {
+        "id": {
             "type": "string",
+            "description": "The id of the element."
+        },
+        "type": {
             "const": "AuditableItemGraphVertex",
             "description": "JSON-LD Type."
         },
@@ -72,16 +58,13 @@
             },
             "description": "Edges connected to the vertex."
         },
-        "changesets": {
-            "type": "array",
-            "items": {
-                "$ref": "https://schema.twindev.org/aig/AuditableItemGraphChangeset"
-            },
-            "description": "Changesets for the vertex."
-        },
         "verified": {
             "type": "boolean",
             "description": "Is the vertex verified, will only be populated when verification is requested."
+        },
+        "version": {
+            "type": "number",
+            "description": "The version of the vertex, populated only when getting a specific version.\nMaps to https://schema.org/version."
         }
     },
     "required": [
@@ -89,5 +72,25 @@
         "id",
         "type"
     ],
-    "additionalProperties": false
+    "allOf": [
+        {
+            "description": "Interface describing the base properties for auditable elements.",
+            "type": "object",
+            "properties": {
+                "dateCreated": {
+                    "type": "string",
+                    "description": "The date/time of when the element was created."
+                },
+                "dateModified": {
+                    "type": "string",
+                    "description": "The date/time of when the element was modified."
+                },
+                "dateDeleted": {
+                    "type": "string",
+                    "description": "The date/time of when the element was deleted, as we never actually remove items."
+                }
+            },
+            "$comment": "Inlined utility base type AuditableItemGraphAuditedElement so utility transformations can operate on concrete properties instead of a $ref."
+        }
+    ]
 }

package/dist/es/schemas/AuditableItemGraphVertexList.json

@@ -1,41 +1,39 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schema.twindev.org/aig/AuditableItemGraphVertexList",
+    "title": "AuditableItemGraphVertexList",
     "description": "Interface describing an auditable item graph vertex list.",
     "type": "object",
     "properties": {
         "@context": {
             "type": "array",
-            "minItems": 2,
-            "description": "JSON-LD Context.",
             "prefixItems": [
                 {
-                    "type": "string",
                     "const": "https://schema.org"
                 },
                 {
-                    "type": "string",
                     "const": "https://schema.twindev.org/aig/"
                 }
             ],
             "items": {
                 "$ref": "https://schema.twindev.org/json-ld/JsonLdContextDefinitionElement"
-            }
+            },
+            "minItems": 2,
+            "description": "JSON-LD Context."
         },
         "type": {
             "type": "array",
-            "items": {
-                "allOf": [
-                    {
-                        "type": "string",
-                        "const": "ItemList"
-                    },
-                    {
-                        "type": "string",
-                        "const": "AuditableItemGraphVertexList"
-                    }
-                ]
-            },
+            "prefixItems": [
+                {
+                    "const": "ItemList"
+                },
+                {
+                    "const": "AuditableItemGraphVertexList"
+                }
+            ],
+            "items": false,
+            "minItems": 2,
+            "maxItems": 2,
             "description": "JSON-LD Type."
         },
         "itemListElement": {
@@ -44,16 +42,11 @@
                 "$ref": "https://schema.twindev.org/aig/AuditableItemGraphVertex"
             },
             "description": "The list of vertices."
-        },
-        "nextItem": {
-            "type": "string",
-            "description": "The cursor to get the next chunk of vertices."
         }
     },
     "required": [
         "@context",
         "type",
         "itemListElement"
-    ],
-    "additionalProperties": false
+    ]
 }

package/dist/types/index.d.ts

@@ -1,11 +1,22 @@
 export * from "./dataTypes/auditableItemGraphDataTypes.js";
+export * from "./models/api/IAuditableItemGraphChangesetGetRequest.js";
+export * from "./models/api/IAuditableItemGraphChangesetGetResponse.js";
+export * from "./models/api/IAuditableItemGraphChangesetListRequest.js";
+export * from "./models/api/IAuditableItemGraphChangesetListResponse.js";
 export * from "./models/api/IAuditableItemGraphCreateRequest.js";
 export * from "./models/api/IAuditableItemGraphGetRequest.js";
 export * from "./models/api/IAuditableItemGraphGetResponse.js";
 export * from "./models/api/IAuditableItemGraphListRequest.js";
 export * from "./models/api/IAuditableItemGraphListResponse.js";
 export * from "./models/api/IAuditableItemGraphUpdateRequest.js";
+export * from "./models/api/IAuditableItemGraphUpdatePartialRequest.js";
+export * from "./models/api/IAuditableItemGraphVersionGetRequest.js";
+export * from "./models/api/IAuditableItemGraphVersionGetResponse.js";
+export * from "./models/api/IAuditableItemGraphVersionListRequest.js";
+export * from "./models/api/IAuditableItemGraphVersionListResponse.js";
 export * from "./models/auditableItemGraphContexts.js";
+export * from "./models/auditableItemGraphMetricIds.js";
+export * from "./models/auditableItemGraphMetrics.js";
 export * from "./models/auditableItemGraphTopics.js";
 export * from "./models/auditableItemGraphTypes.js";
 export * from "./models/eventBus/IAuditableItemGraphEventBusVertexCreated.js";
@@ -13,10 +24,14 @@ export * from "./models/eventBus/IAuditableItemGraphEventBusVertexUpdated.js";
 export * from "./models/IAuditableItemGraphAlias.js";
 export * from "./models/IAuditableItemGraphAuditedElement.js";
 export * from "./models/IAuditableItemGraphChangeset.js";
+export * from "./models/IAuditableItemGraphChangesetList.js";
 export * from "./models/IAuditableItemGraphComponent.js";
 export * from "./models/IAuditableItemGraphEdge.js";
 export * from "./models/IAuditableItemGraphPatchOperation.js";
+export * from "./models/IAuditableItemGraphListPatch.js";
+export * from "./models/IAuditableItemGraphPartialVertex.js";
 export * from "./models/IAuditableItemGraphResource.js";
 export * from "./models/IAuditableItemGraphVertex.js";
 export * from "./models/IAuditableItemGraphVertexList.js";
+export * from "./models/IAuditableItemGraphVertexVersionList.js";
 export * from "./models/verifyDepth.js";

package/dist/types/models/IAuditableItemGraphAlias.d.ts

@@ -9,7 +9,7 @@ export interface IAuditableItemGraphAlias extends IAuditableItemGraphAuditedElem
     /**
      * JSON-LD Context.
      */
-    "@context": typeof AuditableItemGraphContexts.Namespace | [typeof AuditableItemGraphContexts.Namespace, ...IJsonLdContextDefinitionElement[]];
+    "@context"?: typeof AuditableItemGraphContexts.Context | [typeof AuditableItemGraphContexts.Context, ...IJsonLdContextDefinitionElement[]];
     /**
      * The id of the element.
      */
@@ -20,10 +20,17 @@ export interface IAuditableItemGraphAlias extends IAuditableItemGraphAuditedElem
     type: typeof AuditableItemGraphTypes.Alias;
     /**
      * The JSON-LD annotation object for the alias.
+     * @json-ld namespace:twin-common
      */
     annotationObject?: IJsonLdNodeObject;
     /**
      * The format of the id in the alias.
+     * @json-ld type:sch:Text
      */
     aliasFormat?: string;
+    /**
+     * Whether the alias should be unique across the graph, meaning that no other vertex can have the same alias. Defaults to false.
+     * @json-ld type:sch:Boolean
+     */
+    unique?: boolean;
 }

package/dist/types/models/IAuditableItemGraphAuditedElement.d.ts

@@ -8,14 +8,17 @@ export interface IAuditableItemGraphAuditedElement {
     id?: string;
     /**
      * The date/time of when the element was created.
+     * @json-ld namespace:sch
      */
     dateCreated?: string;
     /**
      * The date/time of when the element was modified.
+     * @json-ld namespace:sch
      */
     dateModified?: string;
     /**
      * The date/time of when the element was deleted, as we never actually remove items.
+     * @json-ld namespace:sch
      */
     dateDeleted?: string;
 }

package/dist/types/models/IAuditableItemGraphChangeset.d.ts

@@ -10,9 +10,9 @@ export interface IAuditableItemGraphChangeset {
     /**
      * JSON-LD Context.
      */
-    "@context": [
-        typeof AuditableItemGraphContexts.Namespace,
-        typeof AuditableItemGraphContexts.NamespaceCommon,
+    "@context"?: [
+        typeof AuditableItemGraphContexts.Context,
+        typeof AuditableItemGraphContexts.ContextCommon,
         ...IJsonLdContextDefinitionElement[]
     ];
     /**
@@ -25,22 +25,33 @@ export interface IAuditableItemGraphChangeset {
     id: string;
     /**
      * The date/time of when the changeset was created.
+     * @json-ld namespace:sch
      */
     dateCreated: string;
     /**
      * The user identity that created the changes.
+     * @json-ld namespace:twin-common
      */
     userIdentity?: string;
     /**
      * The patches in the changeset.
+     * @json-ld container:set
      */
     patches: IAuditableItemGraphPatchOperation[];
     /**
      * The immutable proof id which contains the signature for this changeset.
+     * @json-ld type:sch:identifier
      */
     proofId?: string;
     /**
      * The verification for the changeset.
+     * @json-ld id
      */
     verification?: IImmutableProofVerification;
+    /**
+     * The version number of the vertex after this changeset was applied.
+     * Maps to https://schema.org/version.
+     * @json-ld namespace:sch
+     */
+    version?: number;
 }

package/dist/types/models/IAuditableItemGraphChangesetList.d.ts

@@ -0,0 +1,27 @@
+import type { IJsonLdContextDefinitionElement } from "@twin.org/data-json-ld";
+import type { SchemaOrgContexts, SchemaOrgTypes } from "@twin.org/standards-schema-org";
+import type { AuditableItemGraphContexts } from "./auditableItemGraphContexts.js";
+import type { AuditableItemGraphTypes } from "./auditableItemGraphTypes.js";
+import type { IAuditableItemGraphChangeset } from "./IAuditableItemGraphChangeset.js";
+/**
+ * Interface describing an auditable item graph changeset list.
+ */
+export interface IAuditableItemGraphChangesetList {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof SchemaOrgContexts.Context,
+        typeof AuditableItemGraphContexts.Context,
+        ...IJsonLdContextDefinitionElement[]
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: [typeof SchemaOrgTypes.ItemList, typeof AuditableItemGraphTypes.ChangesetList];
+    /**
+     * The list of changesets.
+     * @json-ld namespace:sch
+     */
+    [SchemaOrgTypes.ItemListElement]: IAuditableItemGraphChangeset[];
+}

package/dist/types/models/IAuditableItemGraphComponent.d.ts

@@ -1,8 +1,11 @@
 import type { IComponent } from "@twin.org/core";
-import type { IJsonLdNodeObject } from "@twin.org/data-json-ld";
 import type { IComparator, SortDirection } from "@twin.org/entity";
+import type { IAuditableItemGraphChangeset } from "./IAuditableItemGraphChangeset.js";
+import type { IAuditableItemGraphChangesetList } from "./IAuditableItemGraphChangesetList.js";
+import type { IAuditableItemGraphPartialVertex } from "./IAuditableItemGraphPartialVertex.js";
 import type { IAuditableItemGraphVertex } from "./IAuditableItemGraphVertex.js";
 import type { IAuditableItemGraphVertexList } from "./IAuditableItemGraphVertexList.js";
+import type { IAuditableItemGraphVertexVersionList } from "./IAuditableItemGraphVertexVersionList.js";
 import type { VerifyDepth } from "./verifyDepth.js";
 /**
  * Interface describing an auditable item graph contract.
@@ -17,26 +20,11 @@ export interface IAuditableItemGraphComponent extends IComponent {
      * @param vertex.edges The edges connected to the vertex.
      * @returns The id of the new graph item.
      */
-    create(vertex: {
-        annotationObject?: IJsonLdNodeObject;
-        aliases?: {
-            id: string;
-            aliasFormat?: string;
-            unique?: boolean;
-            annotationObject?: IJsonLdNodeObject;
-        }[];
-        resources?: {
-            id?: string;
-            resourceObject?: IJsonLdNodeObject;
-        }[];
-        edges?: {
-            targetId: string;
-            edgeRelationships: string[];
-            annotationObject?: IJsonLdNodeObject;
-        }[];
-    }): Promise<string>;
+    create(vertex: Omit<IAuditableItemGraphVertex, "id">): Promise<string>;
     /**
-     * Update a graph vertex.
+     * Update a graph vertex (PUT — full replacement of vertex state).
+     * Concurrent updates for the same vertex are serialized via `Mutex` on the vertex id.
+     * Multi-replica deployments are not coordinated.
      * @param vertex The vertex to update.
      * @param vertex.id The id of the vertex to update.
      * @param vertex.annotationObject The annotation object for the vertex as JSON-LD.
@@ -45,48 +33,83 @@ export interface IAuditableItemGraphComponent extends IComponent {
      * @param vertex.edges The edges connected to the vertex.
      * @returns Nothing.
      */
-    update(vertex: {
-        id: string;
-        annotationObject?: IJsonLdNodeObject;
-        aliases?: {
-            id: string;
-            aliasFormat?: string;
-            unique?: boolean;
-            annotationObject?: IJsonLdNodeObject;
-        }[];
-        resources?: {
-            id?: string;
-            resourceObject?: IJsonLdNodeObject;
-        }[];
-        edges?: {
-            id?: string;
-            targetId: string;
-            edgeRelationships: string[];
-            annotationObject?: IJsonLdNodeObject;
-        }[];
-    }): Promise<void>;
+    update(vertex: IAuditableItemGraphVertex): Promise<void>;
+    /**
+     * Partially update a graph vertex (PATCH); only properties that are not undefined are applied.
+     * Sub-lists use explicit `{ add, remove }` patch objects. Serialized with `update()` via `Mutex`
+     * on the same vertex id.
+     * @param partial The partial vertex update (must include `id`).
+     * @returns Nothing.
+     */
+    updatePartial(partial: IAuditableItemGraphPartialVertex): Promise<void>;
     /**
      * Get a graph vertex.
      * @param id The id of the vertex to get.
      * @param options Additional options for the get operation.
      * @param options.includeDeleted Whether to include deleted aliases, resource, edges, defaults to false.
-     * @param options.includeChangesets Whether to include the changesets of the vertex, defaults to false.
      * @param options.verifySignatureDepth How many signatures to verify, defaults to "none".
      * @returns The vertex if found.
      * @throws NotFoundError if the vertex is not found.
      */
     get(id: string, options?: {
         includeDeleted?: boolean;
-        includeChangesets?: boolean;
         verifySignatureDepth?: VerifyDepth;
     }): Promise<IAuditableItemGraphVertex>;
     /**
-     * Remove the verifiable storage for an item.
-     * @param id The id of the vertex to remove the storage from.
+     * Get a graph vertex changeset list.
+     * @param id The id of the vertex to get.
+     * @param cursor The optional cursor to get next chunk.
+     * @param limit Limit the number of entities to return.
+     * @param options Additional options for the get operation.
+     * @param options.verifySignatureDepth How many signatures to verify, defaults to "none".
+     * @returns The changeset if found.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    getChangesets(id: string, cursor?: string, limit?: number, options?: {
+        verifySignatureDepth?: VerifyDepth;
+    }): Promise<{
+        changesets: IAuditableItemGraphChangesetList;
+        cursor?: string;
+    }>;
+    /**
+     * Get a graph vertex changeset.
+     * @param id The id of the vertex to get.
+     * @param options Additional options for the get operation.
+     * @param options.verifySignatureDepth How many signatures to verify, defaults to "none".
+     * @returns The changeset if found.
+     * @throws NotFoundError if the vertex or changeset is not found.
+     */
+    getChangeset(id: string, options?: {
+        verifySignatureDepth?: VerifyDepth;
+    }): Promise<IAuditableItemGraphChangeset>;
+    /**
+     * Get a graph vertex at a specific version.
+     * @param id The id of the vertex.
+     * @param version The version number to retrieve.
+     * @returns The vertex reconstructed at that version.
+     * @throws NotFoundError if the vertex or version is not found.
+     */
+    getVersion(id: string, version: number): Promise<IAuditableItemGraphVertex>;
+    /**
+     * Get all versions of a graph vertex.
+     * @param id The id of the vertex.
+     * @param options Additional options for the operation.
+     * @param options.after Only return versions created after this ISO 8601 timestamp (exclusive).
+     * @param options.before Only return versions created before this ISO 8601 timestamp (exclusive).
+     * @returns The list of vertex versions.
+     * @throws NotFoundError if the vertex is not found.
+     */
+    getVersions(id: string, options?: {
+        after?: string;
+        before?: string;
+    }): Promise<IAuditableItemGraphVertexVersionList>;
+    /**
+     * Remove the proof for an item.
+     * @param id The id of the vertex to remove the proof from.
      * @returns Nothing.
      * @throws NotFoundError if the vertex is not found.
      */
-    removeVerifiable(id: string): Promise<void>;
+    removeProof(id: string): Promise<void>;
     /**
      * Query the graph for vertices.
      * @param options The query options.
@@ -107,5 +130,8 @@ export interface IAuditableItemGraphComponent extends IComponent {
         idMode?: "id" | "alias" | "both";
         idExact?: boolean;
         resourceTypes?: string[];
-    }, conditions?: IComparator[], orderBy?: keyof Pick<IAuditableItemGraphVertex, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, properties?: (keyof IAuditableItemGraphVertex)[], cursor?: string, limit?: number): Promise<IAuditableItemGraphVertexList>;
+    }, conditions?: IComparator[], orderBy?: keyof Pick<IAuditableItemGraphVertex, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, properties?: (keyof IAuditableItemGraphVertex)[], cursor?: string, limit?: number): Promise<{
+        entries: IAuditableItemGraphVertexList;
+        cursor?: string;
+    }>;
 }