### Install Auditable Item Stream Models with npm Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/README.md This command installs the auditable item stream models package using npm. It is a prerequisite for using the models in your project. Ensure you have Node.js and npm installed. ```shell npm install @twin.org/auditable-item-stream-models ``` -------------------------------- ### Git Commit Message Examples Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/CONTRIBUTING.md Provides examples of good and bad commit messages. Good messages adhere to the conventional commit format, clearly stating the type and a concise description of the change. Bad messages are vague and uninformative. ```shell # Good commit messages git commit -m "feat: add JWT token validation" git commit -m "fix: prevent endless loop in data lookup" git commit -m "docs: update installation instructions" # Bad commit messages (avoid these) git commit -m "fix stuff" git commit -m "WIP" git commit -m "changes" ``` -------------------------------- ### Install Auditable Item Stream Service (npm) Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/README.md This snippet shows how to install the auditable-item-stream-service package using npm. It is a prerequisite for using the service in your project. ```shell npm install @twin.org/auditable-item-stream-service ``` -------------------------------- ### Install Auditable Item Stream Packages Source: https://context7.com/twinfoundation/auditable-item-stream/llms.txt Installs the necessary packages for the auditable item stream system. This includes the models, service (server-side), and REST client (client-side) packages using npm. ```bash # Install models package npm install @twin.org/auditable-item-stream-models # Install service package (server-side) npm install @twin.org/auditable-item-stream-service # Install REST client (client-side) npm install @twin.org/auditable-item-stream-rest-client ``` -------------------------------- ### Get Entry Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/classes/AuditableItemStreamService.md Retrieves a specific entry from an auditable item stream. ```APIDOC ## GET /api/streams/{streamId}/entries/{entryId} ### Description Retrieves a specific entry object from the auditable item stream. ### Method GET ### Endpoint /api/streams/{streamId}/entries/{entryId} ### Parameters #### Path Parameters - **streamId** (string) - Required - The id of the stream to get. - **entryId** (string) - Required - The id of the stream entry to get. ### Response #### Success Response (200) - **entryObject** (IJsonLdNodeObject) - The stream entry object. #### Response Example ```json { "entryObject": { "@id": "some-entry-id", "@type": "SomeEntryType", "someProperty": "someValue" } } ``` #### Error Response (404) - **message** (string) - Not Found Error if the stream is not found. ``` -------------------------------- ### AuditableItemStreamService.get() Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/classes/AuditableItemStreamService.md Get a stream header with optional entries and verification. ```APIDOC ## GET /get/{id} ### Description Get a stream header without the entries. ### Method GET ### Endpoint /get/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **includeEntries** (boolean) - Optional - Whether to include the entries, defaults to false. - **includeDeleted** (boolean) - Optional - Whether to include deleted entries, defaults to false. - **verifyStream** (boolean) - Optional - Should the stream be verified, defaults to false. - **verifyEntries** (boolean) - Optional - Should the entries be verified, defaults to false. #### Request Body None ### Request Example ```json { "id": "some-stream-id", "includeEntries": true, "verifyStream": true } ``` ### Response #### Success Response (200) - **stream** (IAuditableItemStream) - The stream and entries if found. #### Response Example ```json { "stream": { "id": "some-stream-id", "created": "2023-01-01T10:00:00Z", "annotationObject": {}, "entries": [] } } ``` #### Error Response (404) - **message** (string) - Not Found error if the stream is not found. #### Error Response Example ```json { "message": "Stream with id 'some-stream-id' not found." } ``` ``` -------------------------------- ### Get Stream Entry Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamComponent.md Retrieves a specific entry from an auditable item stream. Options allow for entry verification. ```APIDOC ## GET /streams/{streamId}/entries/{entryId} ### Description Get the entry from the stream. ### Method GET ### Endpoint /streams/{streamId}/entries/{entryId} ### Parameters #### Path Parameters - **streamId** (string) - Required - The id of the stream to get. - **entryId** (string) - Required - The id of the stream entry to get. #### Query Parameters - **verifyEntry?** (boolean) - Optional - Should the entry be verified, defaults to false. ### Response #### Success Response (200) - **IAuditableItemStreamEntry** (object) - The stream entry if found. #### Response Example ```json { "id": "entry-id-456", "dateCreated": "2023-10-27T10:01:00Z", "annotationObject": { "@context": "http://schema.org", "@type": "EntryType", "content": "First entry" } } ``` #### Throws NotFoundError if the stream is not found. ``` -------------------------------- ### GET /twinfoundation/auditable-item-stream Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamListEntriesRequest.md Retrieves a list of entries from an auditable item stream. Supports filtering, sorting, and pagination. ```APIDOC ## GET /twinfoundation/auditable-item-stream ### Description Get an auditable item stream entries. This endpoint allows fetching entries with various filtering and sorting options. ### Method GET ### Endpoint /twinfoundation/auditable-item-stream ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **conditions** (string) - Optional - The conditions to filter the stream, JSON stringified IComparator[]. - **includeDeleted** (string) - Optional - Whether to include deleted entries, defaults to false. - **verifyEntries** (string) - Optional - Should the entries be verified, defaults to false. - **order** (SortDirection) - Optional - Retrieve the entries in ascending/descending time order, defaults to Ascending. - **limit** (string) - Optional - How many entries to return. - **cursor** (string) - Optional - Cursor to use for next chunk of data. #### Request Body None ### Request Example None ### Response #### Success Response (200) - **headers** (object) - Optional - The headers which can be used to determine the response data type. - **accept** (string) - The accepted content type, either "application/json" or "application/ld+json". #### Response Example ```json { "headers": { "accept": "application/json" } } ``` ``` -------------------------------- ### GET /auditable-item-stream Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/functions/auditableItemStreamGet.md Retrieves the auditable item stream for a given component. ```APIDOC ## GET /auditable-item-stream ### Description Get the stream of auditable items for a specified component. ### Method GET ### Endpoint /auditable-item-stream ### Parameters #### Query Parameters - **componentName** (string) - Required - The name of the component to use in the routes. #### Request Body This endpoint does not accept a request body. ### Response #### Success Response (200) - **stream** (Array) - The stream of auditable items. - **additional http response properties** (Object) - Additional properties from the HTTP response. #### Response Example ```json { "stream": [ { "itemId": "item-123", "timestamp": "2023-10-27T10:00:00Z", "eventType": "CREATE", "payload": { "name": "Example Item", "value": 100 } } ], "status": 200, "statusText": "OK" } ``` ``` -------------------------------- ### GET /streams Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamListRequest.md Retrieves a list of auditable item streams based on the provided query parameters. ```APIDOC ## GET /streams ### Description Retrieves a list of auditable item streams. You can filter, sort, and paginate the results using query parameters. ### Method GET ### Endpoint /streams ### Parameters #### Query Parameters - **headers** (object) - Optional - The headers which can be used to determine the response data type. - **accept** (string) - Required - The desired response data type. Accepted values: "application/json", "application/ld+json". - **query** (object) - Optional - The query parameters for filtering and sorting. - **conditions** (string) - Optional - Conditions to filter the streams, JSON stringified IComparator[]. - **orderBy** (string) - Optional - The order for the results. Accepted values: "dateCreated", "dateModified". Defaults to "dateCreated". - **orderByDirection** (SortDirection) - Optional - The direction for the order. Defaults to "desc". - **properties** (string) - Optional - A comma-separated list of properties to return. Defaults to "id,object". - **cursor** (string) - Optional - The optional cursor to get the next chunk of results. - **limit** (string) - Optional - Limit the number of entities to return. ### Request Example ```json { "headers": { "accept": "application/json" }, "query": { "conditions": "[{\"field\": \"name\", \"operator\": \"eq\", \"value\": \"example\"}]", "orderBy": "dateModified", "orderByDirection": "asc", "properties": "id,name,dateCreated", "limit": "10" } } ``` ### Response #### Success Response (200) - **streams** (array) - A list of auditable item streams. - **id** (string) - The unique identifier of the stream. - **object** (string) - The type of the object. - **dateCreated** (string) - The creation date of the stream. - **dateModified** (string) - The modification date of the stream. #### Response Example ```json { "streams": [ { "id": "stream-123", "object": "AuditableItemStream", "dateCreated": "2023-10-27T10:00:00Z", "dateModified": "2023-10-27T10:00:00Z" } ] } ``` ``` -------------------------------- ### Get Entries Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-rest-client/docs/reference/classes/AuditableItemStreamRestClient.md Retrieves a list of entries from an auditable item stream, with options for filtering, inclusion of deleted entries, verification, limiting results, pagination via cursor, and sorting. ```APIDOC ## GET /api/streams/{id}/entries ### Description Get the entries for the stream. ### Method GET ### Endpoint `/api/streams/{id}/entries` ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **options** (object) - Optional - Additional options for the get operation. - **conditions** (IComparator[]) - Optional - The conditions to filter the stream. - **includeDeleted** (boolean) - Optional - Whether to include deleted entries, defaults to false. - **verifyEntries** (boolean) - Optional - Should the entries be verified, defaults to false. - **limit** (number) - Optional - How many entries to return. - **cursor** (string) - Optional - Cursor to use for next chunk of data. - **order** (SortDirection) - Optional - Retrieve the entries in ascending/descending time order, defaults to Ascending. ### Response #### Success Response (200) - **entries** (IAuditableItemStreamEntryList) - The list of entries. - **cursor** (string) - Optional - Cursor for the next chunk of data. #### Response Example ```json { "entries": [ { "id": "entry1", "timestamp": "2023-10-27T10:00:00Z", "data": {} } ], "cursor": "nextCursorValue" } ``` #### Throws - **NotFoundError**: If the stream is not found. ``` -------------------------------- ### Get Stream Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamComponent.md Retrieves a stream header without its entries. Options allow for including entries, deleted items, and verification. ```APIDOC ## GET /streams/{id} ### Description Retrieves a stream header without the entries. Options can be provided to include entries, deleted items, and perform verification. ### Method GET ### Endpoint /streams/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **includeEntries** (boolean) - Optional - Whether to include the entries, defaults to false. - **includeDeleted** (boolean) - Optional - Whether to include deleted entries, defaults to false. - **verifyStream** (boolean) - Optional - Should the stream be verified, defaults to false. - **verifyEntries** (boolean) - Optional - Should the entries be verified, defaults to false. ### Response #### Success Response (200) - **IAuditableItemStream** (object) - The stream and entries if found. #### Response Example ```json { "id": "stream-id-123", "dateCreated": "2023-10-27T10:00:00Z", "dateModified": "2023-10-27T10:05:00Z", "annotationObject": { "@context": "http://schema.org", "@type": "SomeType", "name": "Example Stream" }, "entries": [ { "id": "entry-id-456", "dateCreated": "2023-10-27T10:01:00Z", "annotationObject": { "@context": "http://schema.org", "@type": "EntryType", "content": "First entry" } } ] } ``` #### Error Response - **NotFoundError**: If the stream is not found. ``` -------------------------------- ### Get Auditable Item Stream Entries Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamListEntryObjectsRequest.md Retrieves a list of auditable item stream entries based on provided parameters. Supports filtering, sorting, and pagination. ```APIDOC ## GET /twinfoundation/auditable-item-stream/{id} ### Description Get an auditable item stream entry objects. ### Method GET ### Endpoint /twinfoundation/auditable-item-stream/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **conditions** (string) - Optional - The conditions to filter the stream, JSON stringified IComparator[]. - **includeDeleted** (string) - Optional - Whether to include deleted entries, defaults to false. - **order** (SortDirection) - Optional - Retrieve the entries in ascending/descending time order, defaults to Ascending. - **limit** (string) - Optional - How many entries to return. - **cursor** (string) - Optional - Cursor to use for next chunk of data. ### Request Example ```json { "headers": { "accept": "application/json" }, "pathParams": { "id": "stream_id_123" }, "query": { "conditions": "[{\"field\": \"status\", \"operator\": \"eq\", \"value\": \"active\"}]", "includeDeleted": "true", "order": "Descending", "limit": "10", "cursor": "next_cursor_abc" } } ``` ### Response #### Success Response (200) - **entries** (array) - A list of auditable item stream entries. - **nextCursor** (string) - The cursor for the next page of results. #### Response Example ```json { "entries": [ { "id": "entry_1", "timestamp": "2023-10-27T10:00:00Z", "data": {}, "deleted": false }, { "id": "entry_2", "timestamp": "2023-10-27T10:05:00Z", "data": {}, "deleted": false } ], "nextCursor": "next_cursor_xyz" } ``` ``` -------------------------------- ### Get Entry Objects Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-rest-client/docs/reference/classes/AuditableItemStreamRestClient.md Retrieves a list of entry objects in JSON-LD format from an auditable item stream, with options for filtering, inclusion of deleted entries, limiting results, pagination via cursor, and sorting. ```APIDOC ## GET /api/streams/{id}/entry-objects ### Description Get the entry objects for the stream. ### Method GET ### Endpoint `/api/streams/{id}/entry-objects` ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **options** (object) - Optional - Additional options for the get operation. - **conditions** (IComparator[]) - Optional - The conditions to filter the stream. - **includeDeleted** (boolean) - Optional - Whether to include deleted entries, defaults to false. - **limit** (number) - Optional - How many entries to return. - **cursor** (string) - Optional - Cursor to use for next chunk of data. - **order** (SortDirection) - Optional - Retrieve the entries in ascending/descending time order, defaults to Ascending. ### Response #### Success Response (200) - **entries** (IAuditableItemStreamEntryObjectList) - The list of entry objects. - **cursor** (string) - Optional - Cursor for the next chunk of data. #### Response Example ```json { "entries": [ { "@context": "http://schema.org", "@type": "SomeType", "someProperty": "someValue" } ], "cursor": "nextCursorValue" } ``` #### Throws - **NotFoundError**: If the stream is not found. ``` -------------------------------- ### Get Entry from Stream Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-rest-client/docs/reference/classes/AuditableItemStreamRestClient.md Retrieves a specific entry from a stream by providing both the stream ID and the entry ID. Optional parameters allow for verification of the entry. It returns a promise that resolves with the stream entry data. ```typescript import { AuditableItemStreamRestClient } from "@twinfoundation/auditable-item-stream"; const client = new AuditableItemStreamRestClient({ /* ... config ... */ }); const entry = await client.getEntry("stream-id", "entry-id", { verifyEntry: true }); ``` -------------------------------- ### GitHub Actions for Release Management Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/CONTRIBUTING.md Illustrates the use of GitHub Actions for automating release processes. These actions handle preparing releases (prerelease and production), publishing packages to NPM, and creating GitHub releases. ```shell # Prepare Release (Prerelease/Production) # Run 'Prepare Release' GitHub Action on a specific branch # Set semver type (prerelease, major, minor, patch) # Publish Release # Run 'Publish Release' GitHub Action # Publishes packages to NPM with appropriate tag (next or latest) # Versions Prepare # Run 'Versions Prepare' on a branch to update versions ``` -------------------------------- ### NPM Scripts for Code Quality Checks Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/CONTRIBUTING.md Demonstrates common NPM scripts used for maintaining code quality. These scripts automate tasks like building the project, running tests, formatting code, and checking for linting errors, ensuring consistency and reliability. ```shell npm run dist # Builds the project npm run test # Runs all tests npm run format # Formats code npm run lint # Checks for linting errors ``` -------------------------------- ### Generate Patch File for release-please Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/release/README.md This command demonstrates how to generate a patch file for the release-please package after modifying its source code. It uses `npx patch-package` to create a patch in the specified directory, allowing the changes to be version-controlled and reapplied. ```shell npx patch-package release-please --patch-dir release ``` -------------------------------- ### Instantiate AuditableItemStreamRestClient Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-rest-client/docs/reference/classes/AuditableItemStreamRestClient.md Creates a new instance of AuditableItemStreamRestClient. This constructor requires a configuration object of type IBaseRestClientConfig. ```typescript import { AuditableItemStreamRestClient } from "@twinfoundation/auditable-item-stream"; const config = { /* ... IBaseRestClientConfig ... */ }; const client = new AuditableItemStreamRestClient(config); ``` -------------------------------- ### REST API - Get Stream with Verification Source: https://context7.com/twinfoundation/auditable-item-stream/llms.txt Retrieves an auditable item stream along with its entries and verification status via a REST GET request. It supports options to include entries and verify both the stream and its entries. The response is in JSON-LD format. ```bash curl -X GET "https://api.example.com/auditable-item-stream/ais:abc123def456...?includeEntries=true&verifyStream=true&verifyEntries=true" \ -H "Accept: application/ld+json" ``` -------------------------------- ### AuditableItemStreamService Constructor Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/classes/AuditableItemStreamService.md Creates a new instance of AuditableItemStreamService. ```APIDOC ## Constructor AuditableItemStreamService ### Description Create a new instance of AuditableItemStreamService. ### Method Constructor ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body None ### Request Example ```json { "options?": "IAuditableItemStreamServiceConstructorOptions" } ``` ### Response #### Success Response (200) Returns an instance of AuditableItemStreamService. #### Response Example ```json { "instance": "AuditableItemStreamService" } ``` ``` -------------------------------- ### AuditableItemStreamService.query() Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/classes/AuditableItemStreamService.md Query all streams with optional filtering, ordering, and pagination. ```APIDOC ## GET /query ### Description Query all the streams, will not return entries. ### Method GET ### Endpoint /query ### Parameters #### Path Parameters None #### Query Parameters - **conditions?** (IComparator[]) - Optional - Conditions to use in the query. - **orderBy?** (string) - Optional - The order for the results, defaults to created. Can be 'dateCreated' or 'dateModified'. - **orderByDirection?** (string) - Optional - The direction for the order, defaults to descending. Can be 'asc' or 'desc'. - **properties?** (string[]) - Optional - The properties to return, if not provided defaults to id, created and object. - **cursor?** (string) - Optional - The cursor to request the next chunk of entities. - **limit?** (number) - Optional - Limit the number of entities to return. ### Request Example ```json { "conditions": [], "orderBy": "dateCreated", "orderByDirection": "asc", "properties": ["id", "created"], "limit": 10 } ``` ### Response #### Success Response (200) - **entries** (IAuditableItemStreamList) - The list of streams matching the query. - **cursor?** (string) - The cursor for the next page of results. #### Response Example ```json { "entries": [ { "id": "stream-1", "created": "2023-01-01T10:00:00Z" }, { "id": "stream-2", "created": "2023-01-02T11:00:00Z" } ], "cursor": "some-cursor-string" } ``` ``` -------------------------------- ### AuditableItemStreamService.create() Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/classes/AuditableItemStreamService.md Create a new stream with optional entries. ```APIDOC ## POST /create ### Description Create a new stream. ### Method POST ### Endpoint /create ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **stream** (object) - The stream to create. - **annotationObject?** (IJsonLdNodeObject) - The object for the stream as JSON-LD. - **entries?** (object[]) - Entries to store in the stream. - **options?** (object) - Options for creating the stream. - **immutableInterval?** (number) - After how many entries do we add immutable checks, defaults to service configured value. A value of 0 will disable integrity checks, 1 will be every item, or any other integer for an interval. ### Request Example ```json { "stream": { "annotationObject": {}, "entries": [] }, "options": { "immutableInterval": 10 } } ``` ### Response #### Success Response (200) - **streamId** (string) - The id of the new stream item. #### Response Example ```json { "streamId": "some-stream-id" } ``` ``` -------------------------------- ### Get Auditable Item Stream Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamGetRequest.md Retrieves an auditable item stream based on the provided ID and query parameters. ```APIDOC ## GET /twinfoundation/auditable-item-stream ### Description Get an auditable item stream. ### Method GET ### Endpoint /twinfoundation/auditable-item-stream ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. #### Query Parameters - **includeEntries** (string) - Optional - Whether to include the entries, defaults to false. The entries will be limited to the first page of entries in date descending order. If you want to get more entries you can use the returned cursor with the get entries method. - **includeDeleted** (string) - Optional - Whether to include deleted entries, defaults to false. - **verifyStream** (string) - Optional - Should the stream be verified, defaults to false. - **verifyEntries** (string) - Optional - Should the entries be verified, defaults to false. #### Request Body None ### Request Example None ### Response #### Success Response (200) - **headers** (object) - The headers which can be used to determine the response data type. - **accept** (string) - "application/json" or "application/ld+json" - **pathParams** (object) - The parameters from the path. - **id** (string) - The id of the stream to get. - **query** (object) - The parameters from the query. - **includeEntries** (string) - Whether to include the entries, defaults to false. - **includeDeleted** (string) - Whether to include deleted entries, defaults to false. - **verifyStream** (string) - Should the stream be verified, defaults to false. - **verifyEntries** (string) - Should the entries be verified, defaults to false. #### Response Example { "headers": { "accept": "application/json" }, "pathParams": { "id": "stream-123" }, "query": { "includeEntries": "true", "includeDeleted": "false", "verifyStream": "true", "verifyEntries": "false" } } ``` -------------------------------- ### auditableItemStreamCreate() Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/functions/auditableItemStreamCreate.md Creates a new auditable item stream. This function takes the request context, component name, and stream creation request details as input and returns a promise that resolves with the creation response. ```APIDOC ## POST /auditable-item-stream ### Description Creates a new auditable item stream. ### Method POST ### Endpoint /auditable-item-stream ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **componentName** (string) - Required - The name of the component to use in the routes. - **request** (object) - Required - The request object for creating the auditable item stream. This object should conform to the `IAuditableItemStreamCreateRequest` interface. - **Example Request Body Structure (IAuditableItemStreamCreateRequest):** ```json { "streamName": "example-stream", "description": "A stream for example data" } ``` ### Request Example ```json { "httpRequestContext": { /* ... IHttpRequestContext object ... */ }, "componentName": "my-component", "request": { "streamName": "example-stream", "description": "A stream for example data" } } ``` ### Response #### Success Response (200) - **id** (string) - The unique identifier of the created auditable item stream. - **message** (string) - A confirmation message indicating successful creation. - **additional http response properties** #### Response Example ```json { "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "message": "Auditable item stream created successfully." } ``` ``` -------------------------------- ### AuditableItemStreamRestClient Usage Source: https://context7.com/twinfoundation/auditable-item-stream/llms.txt Example usage of the AuditableItemStreamRestClient for interacting with the API programmatically. ```APIDOC ## AuditableItemStreamRestClient Usage ### Description Use the REST client package to interact with a remote auditable item stream service. ### Code Example ```typescript import { AuditableItemStreamRestClient } from "@twin.org/auditable-item-stream-rest-client"; import { SortDirection } from "@twin.org/auditable-item-stream-models"; // Assuming SortDirection is exported const client = new AuditableItemStreamRestClient({ endpoint: "https://api.example.com", pathPrefix: "auditable-item-stream" }); // Create a stream const streamId = await client.create({ annotationObject: { "@context": "https://schema.org", "@type": "DataCatalog", name: "Financial Audit Log" } }); // Add entries const entryId = await client.createEntry(streamId, { "@context": "https://schema.org", "@type": "MoneyTransfer", amount: 1000, currency: "USD", dateCreated: new Date().toISOString() }); // Query with pagination let cursor: string | undefined; do { const result = await client.query( undefined, // streamId can be specified here if querying entries for a specific stream "dateCreated", SortDirection.Descending, undefined, // filter cursor, 50 ); result.entries.itemListElement?.forEach(stream => { console.log(stream.id, stream.dateCreated); }); cursor = result.cursor; } while (cursor); // Get stream with verification const verifiedStream = await client.get(streamId, { includeEntries: true, verifyStream: true, verifyEntries: true }); ``` ``` -------------------------------- ### Get Stream Entry Object Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamComponent.md Retrieves the raw JSON-LD object for a specific entry within an auditable item stream. ```APIDOC ## GET /streams/{id}/entries/{entryId}/object ### Description Get the entry object from the stream. ### Method GET ### Endpoint /streams/{id}/entries/{entryId}/object ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to get. - **entryId** (string) - Required - The id of the stream entry to get. ### Response #### Success Response (200) - **IJsonLdNodeObject** (object) - The stream entry object. #### Response Example ```json { "@context": "http://schema.org", "@type": "EntryType", "content": "First entry" } ``` #### Throws NotFoundError if the stream is not found. ``` -------------------------------- ### AuditableItemStreamService.createEntry() Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/classes/AuditableItemStreamService.md Create a new entry within a specified stream. ```APIDOC ## POST /createEntry/{streamId} ### Description Create an entry in the stream. ### Method POST ### Endpoint /createEntry/{streamId} ### Parameters #### Path Parameters - **streamId** (string) - Required - The id of the stream to update. #### Query Parameters None #### Request Body - **entryObject** (IJsonLdNodeObject) - Required - The object for the stream entry as JSON-LD. ### Request Example ```json { "streamId": "some-stream-id", "entryObject": { "@context": "http://schema.org", "@type": "Event", "name": "New Event" } } ``` ### Response #### Success Response (200) - **entryId** (string) - The id of the created entry. #### Response Example ```json { "entryId": "some-entry-id" } ``` ``` -------------------------------- ### Create Stream Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamComponent.md Creates a new auditable item stream. You can optionally provide initial entries and configuration for immutability. ```APIDOC ## POST /streams ### Description Creates a new auditable item stream. ### Method POST ### Endpoint /streams ### Parameters #### Request Body - **stream** (object) - Required - The stream to create. - **annotationObject?** (IJsonLdNodeObject) - Optional - The object for the stream as JSON-LD. - **entries?** (object[]) - Optional - Entries to store in the stream. - **options?** (object) - Optional - Options for creating the stream. - **immutableInterval?** (number) - Optional - After how many entries do we add immutable checks, defaults to service configured value. A value of 0 will disable immutable checks, 1 will be every item, or any other integer for an interval. ### Request Example ```json { "stream": { "annotationObject": { "@context": "http://schema.org", "@type": "SomeType", "name": "Example Stream" }, "entries": [ { "@context": "http://schema.org", "@type": "EntryType", "content": "First entry" } ] }, "options": { "immutableInterval": 10 } } ``` ### Response #### Success Response (200) - **string** (string) - The id of the new stream item. #### Response Example ```json "stream-id-123" ``` ``` -------------------------------- ### Entry Retrieval API Source: https://context7.com/twinfoundation/auditable-item-stream/llms.txt Get a specific entry from a stream with optional verification. ```APIDOC ## GET /streams/{streamId}/entries/{entryId} ### Description Get a specific entry from a stream with optional verification. ### Method GET ### Endpoint /streams/{streamId}/entries/{entryId} ### Parameters #### Path Parameters - **streamId** (string) - Required - The ID of the stream. - **entryId** (string) - Required - The ID of the entry. #### Query Parameters - **verifyEntry** (boolean) - Optional - Whether to verify the entry's proof. ### Response #### Success Response (200) - **@context** (string) - JSON-LD context. - **type** (string) - Type of the response, e.g., "AuditableItemStreamEntry". - **id** (string) - The ID of the entry. - **dateCreated** (string) - The creation date of the entry. - **index** (integer) - The index of the entry within the stream. - **proofId** (string) - The ID of the proof associated with the entry. - **entryObject** (object) - The JSON-LD object content of the entry. - **verification** (object) - Verification details if requested. #### Response Example ```json { "@context": [...], "type": "AuditableItemStreamEntry", "id": "ais:a1b2c3d4e5f6...:entry123...", "dateCreated": "2024-01-16T14:00:00Z", "index": 1, "proofId": "proof456...", "entryObject": { "@context": "https://schema.org", ... }, "verification": { "verified": true, "proofChain": [...] } } ``` ``` -------------------------------- ### IAuditableItemStreamServiceConfig Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-service/docs/reference/interfaces/IAuditableItemStreamServiceConfig.md Configuration for the auditable item stream service, including properties like defaultImmutableInterval. ```APIDOC ## Interface: IAuditableItemStreamServiceConfig Configuration for the auditable item stream service. ### Properties #### defaultImmutableInterval? > `optional` **defaultImmutableInterval**: `number` After how many entries do we add immutable checks, defaults to service configured value. A value of 0 will disable integrity checks, 1 will be every item, or any other integer for an interval. You can override this value on stream creation. ##### Default ```ts 10 ``` ``` -------------------------------- ### Create Stream Entry Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamComponent.md Adds a new entry to a specified auditable item stream. ```APIDOC ## POST /streams/{streamId}/entries ### Description Creates an entry in the stream. ### Method POST ### Endpoint /streams/{streamId}/entries ### Parameters #### Path Parameters - **streamId** (string) - Required - The id of the stream to create the entry in. #### Request Body - **entryObject** (IJsonLdNodeObject) - Required - The object for the stream as JSON-LD. ### Request Example ```json { "@context": "http://schema.org", "@type": "EntryType", "content": "New entry content" } ``` ### Response #### Success Response (200) - **string** (string) - The id of the created entry, if not provided. #### Response Example ```json "entry-id-789" ``` ``` -------------------------------- ### Get Class Name Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-rest-client/docs/reference/classes/AuditableItemStreamRestClient.md Returns the runtime name of the AuditableItemStreamRestClient class. This method is part of the IAuditableItemStreamComponent interface implementation. ```typescript import { AuditableItemStreamRestClient } from "@twinfoundation/auditable-item-stream"; const client = new AuditableItemStreamRestClient({ /* ... config ... */ }); const className = client.className(); // Returns "AuditableItemStreamRestClient" ``` -------------------------------- ### Query Streams Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-rest-client/docs/reference/classes/AuditableItemStreamRestClient.md Queries all streams based on specified conditions, ordering, and properties. This method does not return stream entries by default and supports pagination using a cursor. It returns a promise with a list of streams and an optional cursor for the next page. ```typescript import { AuditableItemStreamRestClient } from "@twinfoundation/auditable-item-stream"; const client = new AuditableItemStreamRestClient({ /* ... config ... */ }); const result = await client.query([ { key: "created", condition: "<", value: "2023-01-01T00:00:00Z" } // Example condition ], "dateCreated", "asc", ["id", "created"]); ``` -------------------------------- ### Get Auditable Item Stream Entry Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamGetEntryObjectRequest.md Retrieves a specific entry object from the auditable item stream using its ID and the entry's ID. ```APIDOC ## GET /twinfoundation/auditable-item-stream/{id}/{entryId} ### Description Get an entry object in the auditable item stream. ### Method GET ### Endpoint /twinfoundation/auditable-item-stream/{id}/{entryId} ### Parameters #### Path Parameters - **id** (string) - Required - The id of the stream to update the get in. - **entryId** (string) - Required - The id of the entry to update. #### Query Parameters None #### Request Body None ### Request Example None ### Response #### Success Response (200) - **headers** (object) - Optional - The headers which can be used to determine the response data type. - **accept** (string) - The accepted content type for the response. Can be "application/json" or "application/ld+json". #### Response Example ```json { "headers": { "accept": "application/json" } } ``` ``` -------------------------------- ### GET /auditable-item-stream/{streamId}/entries Source: https://context7.com/twinfoundation/auditable-item-stream/llms.txt Query entries within a specific auditable item stream with pagination. ```APIDOC ## GET /auditable-item-stream/{streamId}/entries ### Description Query entries in a stream with pagination via REST. ### Method GET ### Endpoint `/auditable-item-stream/{streamId}/entries` ### Parameters #### Path Parameters - **streamId** (string) - Required - The ID of the stream to query entries from. #### Query Parameters - **limit** (integer) - Optional - The maximum number of entries to return per page. - **order** (string) - Optional - The order of entries ('Ascending' or 'Descending'). - **verifyEntries** (boolean) - Optional - Whether to verify the integrity of the entries. - **cursor** (string) - Optional - A cursor for paginating through results. ### Request Example ```bash curl -X GET "https://api.example.com/auditable-item-stream/ais:abc123def456.../entries?limit=10&order=Ascending&verifyEntries=true" \ -H "Accept: application/ld+json" ``` ### Response #### Success Response (200 OK) - **@context** (array) - JSON-LD context. - **type** (array) - The type of the resource, typically ['ItemList', 'AuditableItemStreamEntryList']. - **itemListElement** (array) - An array of auditable item stream entries. - **Link** (header) - Provides a link to the next page of results if available (e.g., `; rel="next"`). #### Response Example ```json { "@context": [...], "type": ["ItemList", "AuditableItemStreamEntryList"], "itemListElement": [...] } ``` Link: `; rel="next"` ``` -------------------------------- ### IAuditableItemStreamEntry Interface Source: https://github.com/twinfoundation/auditable-item-stream/blob/next/packages/auditable-item-stream-models/docs/reference/interfaces/IAuditableItemStreamEntry.md Defines the structure and properties of an entry within the auditable item stream. ```APIDOC ## IAuditableItemStreamEntry Interface Interface describing an entry for the stream. ### Properties #### @context - **@context** (array) - Required - JSON-LD Context. #### type - **type** (string) - Required - JSON-LD Type. Must be "AuditableItemStreamEntry". #### id - **id** (string) - Required - The id of the entry. #### dateCreated - **dateCreated** (string) - Required - The date/time of when the entry was created. #### dateModified - **dateModified** (string) - Optional - The date/time of when the entry was modified. #### dateDeleted - **dateDeleted** (string) - Optional - The date/time of when the entry was deleted. #### userIdentity - **userIdentity** (string) - Optional - The identity of the user which added the entry to the stream. #### entryObject - **entryObject** (object) - Required - The object to associate with the entry as JSON-LD. #### index - **index** (number) - Required - The index of the entry in the stream. #### proofId - **proofId** (string) - Optional - The id of the immutable proof. #### verification - **verification** (object) - Optional - The verification of the entry. ### Request Example ```json { "@context": ["https://schema.twindev.org/ais/", "https://schema.twindev.org/common/"], "type": "AuditableItemStreamEntry", "id": "entry-123", "dateCreated": "2023-10-27T10:00:00Z", "entryObject": { "@id": "item-abc", "name": "Example Item" }, "index": 1 } ``` ### Response Example ```json { "@context": ["https://schema.twindev.org/ais/", "https://schema.twindev.org/common/"], "type": "AuditableItemStreamEntry", "id": "entry-123", "dateCreated": "2023-10-27T10:00:00Z", "dateModified": "2023-10-27T10:05:00Z", "entryObject": { "@id": "item-abc", "name": "Example Item" }, "index": 1, "userIdentity": "user-xyz", "proofId": "proof-789", "verification": { "status": "verified" } } ``` ```