@3sixty/auditable-item-graph-rest-client 0.0.0-stage → 0.20.0-next.1

package/dist/types/auditableItemGraphRestClient.d.ts

@@ -0,0 +1,143 @@
+import { BaseRestClient } from "@3sixty/api-core";
+import { type IBaseRestClientConfig } from "@3sixty/api-models";
+import type { IAuditableItemGraphChangeset, IAuditableItemGraphChangesetList, IAuditableItemGraphComponent, IAuditableItemGraphPartialVertex, IAuditableItemGraphVertex, IAuditableItemGraphVertexList, IAuditableItemGraphVertexVersionList, VerifyDepth } from "@3sixty/auditable-item-graph-models";
+import type { EntityCondition, SortDirection } from "@3sixty/entity";
+/**
+ * Client for performing auditable item graph through to REST endpoints.
+ */
+export declare class AuditableItemGraphRestClient extends BaseRestClient implements IAuditableItemGraphComponent {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of AuditableItemGraphRestClient.
+     * @param config The configuration for the client.
+     */
+    constructor(config: IBaseRestClientConfig);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Create a new graph vertex.
+     * @param vertex The vertex to create.
+     * @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 The id of the new graph item.
+     */
+    create(vertex: Omit<IAuditableItemGraphVertex, "id">): Promise<string>;
+    /**
+     * 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.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;
+        verifySignatureDepth?: VerifyDepth;
+    }): Promise<IAuditableItemGraphVertex>;
+    /**
+     * 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 changesets if 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>;
+    /**
+     * Update a graph vertex (PUT - full replacement of vertex state).
+     * The server serializes concurrent updates for the same vertex via `Mutex` on the vertex id;
+     * requests load-balanced across replicas can still race.
+     * @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 A promise that resolves when the vertex has been updated.
+     */
+    update(vertex: IAuditableItemGraphVertex): Promise<void>;
+    /**
+     * Partially update a graph vertex (PATCH - optional scalars; list fields use `{ add, remove }`).
+     * @param partial The partial vertex update (must include `id`).
+     * @returns A promise that resolves when the partial update has been applied.
+     */
+    updatePartial(partial: IAuditableItemGraphPartialVertex): Promise<void>;
+    /**
+     * Remove the notarization proof from all changesets of a graph vertex.
+     * @param id The id of the vertex.
+     * @returns A promise that resolves when the proof has been removed.
+     */
+    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.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 descending.
+     * @param properties The properties to return, if not provided defaults to id, created, aliases and object.
+     * @param cursor The cursor to request the next chunk of entities.
+     * @param limit The maximum number of entities to return, a page can contain fewer so follow
+     * the cursor until it is absent to read them all.
+     * @returns The entities, which can be partial if a limited keys list was provided.
+     */
+    query(options?: {
+        id?: string;
+        idMode?: "id" | "alias" | "both";
+        idExact?: boolean;
+        resourceTypes?: string[];
+    }, conditions?: EntityCondition<IAuditableItemGraphVertex>, orderBy?: keyof Pick<IAuditableItemGraphVertex, "dateCreated" | "dateModified">, orderByDirection?: SortDirection, properties?: (keyof IAuditableItemGraphVertex)[], cursor?: string, limit?: number): Promise<{
+        entries: IAuditableItemGraphVertexList;
+        cursor?: string;
+    }>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./auditableItemGraphRestClient.js";

package/docs/changelog.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.20.0-next.1](https://github.com/3sixtyglobal/auditable-item-graph/compare/auditable-item-graph-rest-client-v0.20.0-next.0...auditable-item-graph-rest-client-v0.20.0-next.1) (2026-10-23)
+
+
+### Features
+
+* publish packages under the [@3sixty](https://github.com/3sixty) namespace ([69a615e](https://github.com/3sixtyglobal/auditable-item-graph/commit/69a615ed9a59cc91795d1f8fd65cc778cea7e783))
+* updated ts compile ([5631c11](https://github.com/3sixtyglobal/auditable-item-graph/commit/5631c11fa969a8917e68253c50bf962c10e75814))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @3sixty/auditable-item-graph-models bumped from 0.20.0-next.0 to 0.20.0-next.1

package/docs/examples.md

@@ -0,0 +1,119 @@
+# Auditable Item Graph REST Client Examples
+
+These snippets show practical request flows for creating, reading, updating, and querying graph items through HTTP endpoints.
+
+## AuditableItemGraphRestClient
+
+```typescript
+import { AuditableItemGraphRestClient } from '@3sixty/auditable-item-graph-rest-client';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+console.log(client.className()); // AuditableItemGraphRestClient
+```
+
+```typescript
+import { VerifyDepth } from '@3sixty/auditable-item-graph-models';
+import { AuditableItemGraphRestClient } from '@3sixty/auditable-item-graph-rest-client';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+const id = await client.create({
+  annotationObject: {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    type: 'Create',
+    actor: {
+      type: 'Person',
+      id: 'acct:alex@example.org',
+      name: 'Alex'
+    },
+    object: {
+      type: 'Note',
+      content: 'Created through the REST client'
+    }
+  },
+  aliases: [{ id: 'ticket-2026-0007', aliasFormat: 'externalRef', unique: true }],
+  resources: [
+    { resourceObject: { '@context': 'https://schema.org', type: 'Thing', name: 'Asset A' } }
+  ]
+});
+
+const vertex = await client.get(id, {
+  includeDeleted: false,
+  verifySignatureDepth: VerifyDepth.Current
+});
+
+console.log(id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23
+console.log(vertex.id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23
+```
+
+```typescript
+import { VerifyDepth } from '@3sixty/auditable-item-graph-models';
+import { AuditableItemGraphRestClient } from '@3sixty/auditable-item-graph-rest-client';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+const id = 'aig:018f5a6cfd9444d58c7c2d4df1fd0a23';
+
+await client.update({
+  id,
+  aliases: [{ id: 'ticket-2026-0007', aliasFormat: 'externalRef' }],
+  resources: [
+    {
+      id: 'resource-1',
+      resourceObject: { '@context': 'https://schema.org', type: 'Thing', name: 'Asset A v2' }
+    }
+  ],
+  edges: [{ targetId: 'aig:018f5a6cfd9444d58c7c2d4df1fd0999', edgeRelationships: ['dependsOn'] }]
+});
+
+const changesetChunk = await client.getChangesets(id, undefined, 20, {
+  verifySignatureDepth: VerifyDepth.Current
+});
+
+const firstChangeset = changesetChunk.changesets.itemListElement?.[0];
+
+if (firstChangeset?.id) {
+  const changeset = await client.getChangeset(firstChangeset.id, {
+    verifySignatureDepth: VerifyDepth.Current
+  });
+
+  console.log(changeset.id); // aig:018f5a6cfd9444d58c7c2d4df1fd0a23:changeset:018f5a6cfd9444d58c7c2d4df1fd0b10
+}
+```
+
+```typescript
+import { AuditableItemGraphRestClient } from '@3sixty/auditable-item-graph-rest-client';
+import { ComparisonOperator, SortDirection } from '@3sixty/entity';
+
+const client = new AuditableItemGraphRestClient({ endpoint: 'http://localhost:8080' });
+
+const result = await client.query(
+  {
+    id: 'ticket-2026',
+    idMode: 'alias',
+    idExact: false,
+    resourceTypes: ['Thing']
+  },
+  [
+    {
+      field: 'dateCreated',
+      comparison: ComparisonOperator.GreaterThan,
+      value: '2026-01-01T00:00:00.000Z'
+    }
+  ],
+  'dateCreated',
+  SortDirection.Descending,
+  ['id', 'dateCreated', 'aliases'],
+  undefined,
+  10
+);
+
+console.log(result.entries.itemListElement?.length ?? 0); // 2
+
+try {
+  await client.removeVerifiable('aig:018f5a6cfd9444d58c7c2d4df1fd0a23');
+} catch (error) {
+  console.log(error instanceof Error ? error.message : 'Unknown error'); // Not supported on client
+}
+```