@twin.org/auditable-item-graph-service 0.0.3-next.2 → 0.0.3-next.21

package/dist/types/auditableItemGraphRoutes.d.ts

@@ -1,5 +1,5 @@
 import { type ICreatedResponse, type IHttpRequestContext, type INoContentResponse, type IRestRoute, type ITag } from "@twin.org/api-models";
-import { type IAuditableItemGraphCreateRequest, type IAuditableItemGraphGetRequest, type IAuditableItemGraphGetResponse, type IAuditableItemGraphListRequest, type IAuditableItemGraphListResponse, type IAuditableItemGraphUpdateRequest } from "@twin.org/auditable-item-graph-models";
+import { type IAuditableItemGraphChangesetGetRequest, type IAuditableItemGraphChangesetGetResponse, type IAuditableItemGraphChangesetListRequest, type IAuditableItemGraphChangesetListResponse, type IAuditableItemGraphCreateRequest, type IAuditableItemGraphGetRequest, type IAuditableItemGraphGetResponse, type IAuditableItemGraphListRequest, type IAuditableItemGraphListResponse, type IAuditableItemGraphUpdateRequest, type IAuditableItemGraphUpdatePartialRequest, type IAuditableItemGraphVersionGetRequest, type IAuditableItemGraphVersionGetResponse, type IAuditableItemGraphVersionListRequest, type IAuditableItemGraphVersionListResponse } from "@twin.org/auditable-item-graph-models";
 /**
  * The tag to associate with the routes.
  */
@@ -28,13 +28,37 @@ export declare function auditableItemGraphCreate(httpRequestContext: IHttpReques
  */
 export declare function auditableItemGraphGet(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphGetRequest): Promise<IAuditableItemGraphGetResponse>;
 /**
- * Update the graph vertex.
+ * Get the graph vertex changeset list.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function auditableItemGraphChangesetList(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphChangesetListRequest): Promise<IAuditableItemGraphChangesetListResponse>;
+/**
+ * Get the graph vertex changeset.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function auditableItemGraphChangesetGet(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphChangesetGetRequest): Promise<IAuditableItemGraphChangesetGetResponse>;
+/**
+ * Update the graph vertex (PUT — full replacement of vertex state).
  * @param httpRequestContext The request context for the API.
  * @param componentName The name of the component to use in the routes.
  * @param request The request.
  * @returns The response object with additional http response properties.
  */
 export declare function auditableItemGraphUpdate(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphUpdateRequest): Promise<INoContentResponse>;
+/**
+ * Partially update the graph vertex (PATCH — optional scalars; list fields use `{ add, remove }`).
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function auditableItemGraphUpdatePartial(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphUpdatePartialRequest): Promise<INoContentResponse>;
 /**
  * Query the graph vertices.
  * @param httpRequestContext The request context for the API.
@@ -43,3 +67,19 @@ export declare function auditableItemGraphUpdate(httpRequestContext: IHttpReques
  * @returns The response object with additional http response properties.
  */
 export declare function auditableItemGraphList(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphListRequest): Promise<IAuditableItemGraphListResponse>;
+/**
+ * Get the graph vertex at a specific version.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function auditableItemGraphVersionGet(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphVersionGetRequest): Promise<IAuditableItemGraphVersionGetResponse>;
+/**
+ * Get all versions of a graph vertex.
+ * @param httpRequestContext The request context for the API.
+ * @param componentName The name of the component to use in the routes.
+ * @param request The request.
+ * @returns The response object with additional http response properties.
+ */
+export declare function auditableItemGraphVersionList(httpRequestContext: IHttpRequestContext, componentName: string, request: IAuditableItemGraphVersionListRequest): Promise<IAuditableItemGraphVersionListResponse>;

package/dist/types/auditableItemGraphService.d.ts

@@ -1,5 +1,4 @@
-import { VerifyDepth, type IAuditableItemGraphComponent, type IAuditableItemGraphVertex, type IAuditableItemGraphVertexList } from "@twin.org/auditable-item-graph-models";
-import { type IJsonLdNodeObject } from "@twin.org/data-json-ld";
+import { VerifyDepth, type IAuditableItemGraphChangeset, type IAuditableItemGraphChangesetList, type IAuditableItemGraphComponent, type IAuditableItemGraphPartialVertex, type IAuditableItemGraphVertex, type IAuditableItemGraphVertexList, type IAuditableItemGraphVertexVersionList } from "@twin.org/auditable-item-graph-models";
 import { SortDirection, type IComparator } from "@twin.org/entity";
 import type { IAuditableItemGraphServiceConstructorOptions } from "./models/IAuditableItemGraphServiceConstructorOptions.js";
 /**
@@ -28,6 +27,10 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
      * @returns The class name of the component.
      */
     className(): string;
+    /**
+     * Register all AIG metrics with the telemetry component.
+     */
+    start(): Promise<void>;
     /**
      * Create a new graph vertex.
      * @param vertex The vertex to create.
@@ -37,82 +40,96 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
      * @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 (PUT — full replacement of vertex state).
+     * Concurrent updates for the same vertex are serialized via `Mutex` on the vertex id.
+     * @param vertex The vertex to update.
+     * @returns Nothing.
+     */
+    update(vertex: IAuditableItemGraphVertex): Promise<void>;
+    /**
+     * Partially update a graph vertex (PATCH — explicit list patches; only defined properties applied).
+     * Serialized with `update` via `Mutex` on the same vertex id within this instance.
+     * @param partial The partial vertex update.
+     * @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/updated 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>;
     /**
-     * Update a graph vertex.
-     * @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.
-     * @param vertex.aliases Alternative aliases that can be used to identify the vertex.
-     * @param vertex.resources The resources attached to the vertex.
-     * @param vertex.edges The edges connected to the vertex.
-     * @returns Nothing.
+     * 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 vertex if found.
+     * @throws NotFoundError if the vertex is not found.
      */
-    update(vertex: {
-        id: string;
-        annotationObject?: IJsonLdNodeObject;
-        aliases?: {
-            id: string;
-            aliasFormat?: string;
-            annotationObject?: IJsonLdNodeObject;
-        }[];
-        resources?: {
-            id?: string;
-            resourceObject?: IJsonLdNodeObject;
-        }[];
-        edges?: {
-            id?: string;
-            targetId: string;
-            edgeRelationships: string[];
-            annotationObject?: IJsonLdNodeObject;
-        }[];
-    }): Promise<void>;
-    /**
-     * Remove the verifiable storage for an item.
+    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 vertex if found.
+     * @throws NotFoundError if the vertex 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.
      * @param options.id The optional id to look for.
      * @param options.idMode Look in id, alias or both, defaults to both.
      * @param options.idExact Find only exact matches, default to false meaning partial matching.
-     * @param options.includesResourceTypes Include vertices with specific resource types.
+     * @param options.resourceTypes Include vertices with specific resource types.
      * @param conditions Conditions to use in the query.
      * @param orderBy The order for the results, defaults to created.
      * @param orderByDirection The direction for the order, defaults to desc.
@@ -125,8 +142,17 @@ export declare class AuditableItemGraphService implements IAuditableItemGraphCom
         id?: string;
         idMode?: "id" | "alias" | "both";
         idExact?: boolean;
-        includesResourceTypes?: string[];
-    }, conditions?: IComparator[], orderBy?: keyof Pick<IAuditableItemGraphVertex, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, properties?: (keyof IAuditableItemGraphVertex)[], cursor?: string, limit?: number): Promise<IAuditableItemGraphVertexList>;
+        resourceTypes?: string[];
+    }, conditions?: IComparator[], orderBy?: keyof Pick<IAuditableItemGraphVertex, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, properties?: (keyof IAuditableItemGraphVertex)[], cursor?: string, limit?: number): Promise<{
+        entries: IAuditableItemGraphVertexList;
+        cursor?: string;
+    }>;
+    /**
+     * Verify the signature of a changeset and add the verification result to the changeset JSON-LD.
+     * @param storedChangeset The changeset to verify.
+     * @returns Whether the changeset is verified.
+     */
+    private verifyChangesetSignature;
     /**
      * Get the resource id from a resource object.
      * @param resource The resource.

package/dist/types/entities/auditableItemGraphAlias.d.ts

@@ -27,4 +27,8 @@ export declare class AuditableItemGraphAlias {
      * Object to associate with the alias as JSON-LD.
      */
     annotationObject?: IJsonLdNodeObject;
+    /**
+     * Whether the alias should be unique across the graph, meaning that no other vertex can have the same alias. Defaults to false.
+     */
+    unique?: boolean;
 }

package/dist/types/entities/auditableItemGraphChangeset.d.ts

@@ -27,4 +27,8 @@ export declare class AuditableItemGraphChangeset {
      * The immutable proof id which contains the signature for this changeset.
      */
     proofId?: string;
+    /**
+     * The version number of the vertex after this changeset was applied.
+     */
+    version?: number;
 }

package/dist/types/entities/auditableItemGraphVertex.d.ts

@@ -46,4 +46,8 @@ export declare class AuditableItemGraphVertex {
      * Edges connected to the vertex.
      */
     edges?: AuditableItemGraphEdge[];
+    /**
+     * The current version of the vertex, incremented on each changeset.
+     */
+    version?: number;
 }

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

@@ -22,6 +22,10 @@ export interface IAuditableItemGraphServiceConstructorOptions {
      * The event bus component type, defaults to no event bus.
      */
     eventBusComponentType?: string;
+    /**
+     * The component type for the optional telemetry component used for event metrics, defaults to no telemetry.
+     */
+    telemetryComponentType?: string;
     /**
      * The configuration for the service.
      */