### Install Document Management Models (npm)

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-models/README.md

Installs the TWIN Document Management Models package using npm. This is the primary step to include the models in your project.

```shell
npm install @twin.org/document-management-models
```

--------------------------------

### Install TWIN Document Management Packages (Bash)

Source: https://context7.com/twinfoundation/document-management/llms.txt

Installs the core packages for the TWIN Document Management system using npm. This includes the data models, the server-side service, and the client-side REST API consumer.

```bash
# Install models (data types and interfaces)
npm install @twin.org/document-management-models

# Install service (server-side implementation)
npm install @twin.org/document-management-service

# Install REST client (client-side implementation)
npm install @twin.org/document-management-rest-client
```

--------------------------------

### Get Document REST API Endpoint (Bash)

Source: https://context7.com/twinfoundation/document-management/llms.txt

This bash command shows how to retrieve a document using the GET /document-management/{id} REST API endpoint. It allows for including blob storage data and attestation information in the response by using query parameters.

```bash
curl -X GET "https://api.example.com/document-management/aig:123456?includeBlobStorageData=true&includeAttestation=true" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-token>"

# Response: 200 OK
# {
#   "@context": ["https://schema.org", "https://schema.twindev.org/documents/", "https://schema.twindev.org/common/"],
#   "type": "ItemList",
#   "itemListElement": [{
#     "@context": ["https://schema.twindev.org/documents/", "https://schema.twindev.org/common/", "https://schema.org"],
#     "type": "Document",
#     "id": "2721000:0",
#     "documentId": "2721000",
#     "documentIdFormat": "bol",
#     "documentCode": "unece:DocumentCodeList#705",

```

--------------------------------

### Conventional Commit Messages (Shell)

Source: https://github.com/twinfoundation/document-management/blob/next/CONTRIBUTING.md

Examples of correctly formatted commit messages following conventional commit standards. These messages help in automating changelog generation and version bumping.

```shell
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"
```

--------------------------------

### GET /documentManagementGet

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/functions/documentManagementGet.md

Retrieves a document from the auditable item graph vertex. This endpoint is used to fetch document information based on the provided component name and request details.

```APIDOC
## GET /documentManagementGet

### Description
Get the document from the auditable item graph vertex.

### Method
GET

### Endpoint
/documentManagementGet

### Parameters
#### Query Parameters
- **componentName** (string) - Required - The name of the component to use in the routes.
- **request** (IDocumentManagementGetRequest) - Required - The request object containing details for fetching the document.

### Request Example
```json
{
  "componentName": "exampleComponent",
  "request": {
    "documentId": "doc123"
  }
}
```

### Response
#### Success Response (200)
- **IDocumentManagementGetResponse** - The response object containing document details.

#### Response Example
```json
{
  "document": {
    "id": "doc123",
    "name": "Example Document",
    "content": "This is the content of the document."
  }
}
```
```

--------------------------------

### GET /document-management/{id} - Get Document

Source: https://context7.com/twinfoundation/document-management/llms.txt

Retrieves a document by its ID, with options to include blob storage data and attestation information.

```APIDOC
## GET /document-management/{id} - Get Document

### Description
Retrieves a document by its ID. Supports options to include blob storage data and attestation information.

### Method
GET

### Endpoint
/document-management/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document (e.g., `aig:123456`).

#### Query Parameters
- **includeBlobStorageData** (boolean) - Optional - Whether to include the document's blob data in the response.
- **includeAttestation** (boolean) - Optional - Whether to include attestation details in the response.

### Request Example
```bash
curl -X GET "https://api.example.com/document-management/aig:123456?includeBlobStorageData=true&includeAttestation=true" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-token>"
```

### Response
#### Success Response (200 OK)
- **@context** (array) - JSON-LD contexts.
- **type** (string) - The type of the response, typically `ItemList`.
- **itemListElement** (array) - A list containing the document details.
  - **@context** (array) - JSON-LD contexts for the document.
  - **type** (string) - The type of the item, typically `Document`.
  - **id** (string) - The document's internal ID (e.g., `2721000:0`).
  - **documentId** (string) - The user-provided document ID.
  - **documentIdFormat** (string) - The format of the document ID.
  - **documentCode** (string) - The UNECE document code.
  - **blobHash** (string) - The hash of the document's blob data (if `includeBlobStorageData` is true).

#### Error Response (404 Not Found)
- **message** (string) - Error message indicating the document was not found.

#### Error Response (401 Unauthorized)
- **message** (string) - Error message indicating unauthorized access.
```

--------------------------------

### GET /document-management

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-models/docs/reference/interfaces/IDocumentManagementGetRequest.md

Retrieves a document from an auditable item graph vertex. Supports various query parameters to customize the response.

```APIDOC
## GET /document-management

### Description
Retrieves a document from an auditable item graph vertex. Supports various query parameters to customize the response, such as including blob storage metadata, attestation, deleted documents, and data extraction options.

### Method
GET

### Endpoint
/document-management

### Parameters
#### Path Parameters
- **auditableItemGraphDocumentId** (string) - Required - The full id of the document to get.

#### Query Parameters
- **includeBlobStorageMetadata** (string) - Optional - Include the blob storage metadata in the response. Defaults to false.
- **includeBlobStorageData** (string) - Optional - Include the blob storage data in the response. Defaults to false.
- **includeAttestation** (string) - Optional - Include the attestation information in the response. Defaults to false.
- **includeRemoved** (string) - Optional - Include deleted documents in the response. Defaults to false.
- **extractRuleGroupId** (string) - Optional - If provided will extract data from the document using the specified rule group id.
- **extractMimeType** (string) - Optional - By default extraction will auto detect the mime type of the document, this can be used to override the detection.
- **limit** (string) - Optional - Limit the number of items to return, defaults to 1 so only most recent is returned.
- **cursor** (string) - Optional - The cursor to get the next chunk of revisions.

#### Headers
- **accept** (string) - Required - The headers which can be used to determine the response data type. Accepted values: "application/json", "application/ld+json".

### Response
#### Success Response (200)
- **document** (object) - The retrieved document data.
- **metadata** (object) - Metadata related to the document, if requested.

#### Response Example
```json
{
  "document": {},
  "metadata": {}
}
```
```

--------------------------------

### GET /document-management - Query Documents

Source: https://context7.com/twinfoundation/document-management/llms.txt

Queries documents based on specified criteria, such as document ID and a limit for the number of results.

```APIDOC
## GET /document-management

### Description
Queries documents based on provided filters. Allows for pagination and filtering by document ID.

### Method
GET

### Endpoint
`/document-management`

### Parameters
#### Query Parameters
- **documentId** (string) - Optional - Filters documents by their ID.
- **limit** (integer) - Optional - Specifies the maximum number of documents to return.

### Request Example
```bash
curl -X GET "https://api.example.com/document-management?documentId=2721000&limit=10" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-token>"
```

### Response
#### Success Response (200)
- **@context** (array) - Context information for the JSON-LD response.
- **type** (array) - The type of the returned resource, typically ['ItemList', 'AuditableItemGraphVertexList'].
- **itemListElement** (array) - A list of document items matching the query.
  - Each item in the list is an object representing a document with properties like 'id', 'type', 'dateCreated', 'aliases', and 'resources'.

#### Response Example
```json
{
  "@context": ["https://schema.org", "https://schema.twindev.org/aig/"],
  "type": ["ItemList", "AuditableItemGraphVertexList"],
  "itemListElement": [
    {
      "@context": ["https://schema.twindev.org/aig/", "https://schema.twindev.org/common/"],
      "id": "aig:c7c7c7...",
      "type": "AuditableItemGraphVertex",
      "dateCreated": "2024-08-22T04:13:20.000Z",
      "aliases": [{ "id": "2721000", "type": "AuditableItemGraphAlias" }],
      "resources": [{ "type": "AuditableItemGraphResource", "resourceObject": { ... } }]
    }
  ]
}
```
```

--------------------------------

### Get Documents

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-models/docs/reference/interfaces/IDocumentManagementQueryRequest.md

Retrieves a list of documents from an auditable item graph vertex. Supports filtering by document ID, cursor for pagination, and limit for the number of results.

```APIDOC
## GET /documents

### Description
Retrieves a list of documents from an auditable item graph vertex. Supports filtering by document ID, cursor for pagination, and limit for the number of results.

### Method
GET

### Endpoint
/documents

### Parameters
#### Query Parameters
- **documentId** (string) - Required - The id of the document id we are trying to find.
- **cursor** (string) - Optional - The cursor to get the next chunk of documents.
- **limit** (string) - Optional - The number of documents to return.

#### Request Body
None

### Response
#### Success Response (200)
- **documents** (array) - A list of document objects.
  - **id** (string) - The unique identifier of the document.
  - **name** (string) - The name of the document.
  - **createdAt** (string) - The creation timestamp of the document.

#### Response Example
```json
{
  "documents": [
    {
      "id": "doc-123",
      "name": "Project Proposal",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Get Class Name - DocumentManagementService

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/classes/DocumentManagementService.md

Returns the runtime class name of the component. This method implements the `className` method from the `IDocumentManagementComponent` interface.

```typescript
className(): string
```

--------------------------------

### Get Document - DocumentManagementService

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/classes/DocumentManagementService.md

Retrieves a document using its auditable item graph vertex ID and optional revision. Supports options to include blob storage metadata, data, attestation, removed documents, and data extraction based on rule group ID or MIME type. Returns documents and revisions, ordered descending by revision, with a cursor for pagination.

```typescript
get(
  auditableItemGraphDocumentId: string,
  options?: {
    includeBlobStorageMetadata?: boolean;
    includeBlobStorageData?: boolean;
    includeAttestation?: boolean;
    includeRemoved?: boolean;
    extractRuleGroupId?: string;
    extractMimeType?: string;
  },
  cursor?: string,
  limit?: number
): Promise<{ entries: IDocumentList; cursor?: string }>
```

--------------------------------

### Get Specific Document Revision (API)

Source: https://context7.com/twinfoundation/document-management/llms.txt

Retrieves a specific revision of a document using its ID and revision number. Requires an 'Accept' header for JSON-LD and an 'Authorization' header with a JWT token.

```bash
curl -X GET "https://api.example.com/document-management/aig:123456/1" \
  -H "Accept: application/ld+json" \
  -H "Authorization: Bearer <jwt-token>"
```

--------------------------------

### Versions Prepare Action (GitHub Actions)

Source: https://github.com/twinfoundation/document-management/blob/next/CONTRIBUTING.md

Shows how to use a GitHub Action to prepare version updates, typically used for merging release branches into main or updating the next branch after a production release.

```yaml
# Example for preparing main branch from next
- name: Versions Prepare
  uses: twinfoundation/actions/versions@v1
  with:
    target_branch: "main"
    type: "production"

# Example for updating next branch after production release
- name: Versions Prepare
  uses: twinfoundation/actions/versions@v1
  with:
    target_branch: "next"
```

--------------------------------

### GET /document-management/{id}/{revision} - Get Specific Revision

Source: https://context7.com/twinfoundation/document-management/llms.txt

Retrieves a specific revision of a document. Requires the document ID and the revision number.

```APIDOC
## GET /document-management/{id}/{revision}

### Description
Retrieves a specific revision of a document using its ID and revision number.

### Method
GET

### Endpoint
`/document-management/{id}/{revision}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document.
- **revision** (integer) - Required - The specific revision number of the document to retrieve.

### Request Example
```bash
curl -X GET "https://api.example.com/document-management/aig:123456/1" \
  -H "Accept: application/ld+json" \
  -H "Authorization: Bearer <jwt-token>"
```

### Response
#### Success Response (200)
- **@context** (array) - Context information for the JSON-LD response.
- **type** (string) - The type of the returned resource, typically 'Document'.
- **id** (string) - The unique identifier of the document.
- **documentId** (string) - The document's primary identifier.
- **documentRevision** (integer) - The revision number of the document.
- **blobHash** (string) - The hash of the document's content.
- **dateCreated** (string) - The timestamp when the document revision was created.

#### Response Example
```json
{
  "@context": ["https://schema.twindev.org/documents/", "https://schema.twindev.org/common/", "https://schema.org"],
  "type": "Document",
  "id": "2721000:1",
  "documentId": "2721000",
  "documentRevision": 1,
  "blobHash": "sha256:abcdef...",
  "dateCreated": "2024-01-02T00:00:00Z"
}
```
```

--------------------------------

### Prepare Release Action (GitHub Actions)

Source: https://github.com/twinfoundation/document-management/blob/next/CONTRIBUTING.md

Illustrates the usage of a GitHub Action to prepare a prerelease or production release. This involves setting the semantic versioning type and potentially creating a pull request for review.

```yaml
# Example for prerelease on 'next' branch
- name: Prepare Release
  uses: twinfoundation/actions/release@v1
  with:
    semver_type: "prerelease"

# Example for production release on 'main' branch
- name: Prepare Release
  uses: twinfoundation/actions/release@v1
  with:
    semver_type: "major" # or "minor", "patch"
```

--------------------------------

### Publish Release Action (GitHub Actions)

Source: https://github.com/twinfoundation/document-management/blob/next/CONTRIBUTING.md

Demonstrates the use of a GitHub Action to publish packages to NPM and create GitHub releases. This action is typically run after a release has been prepared and merged.

```yaml
# Example for publishing prerelease to 'next' tag
- name: Publish Release
  uses: twinfoundation/actions/publish@v1
  with:
    npm_tag: "next"

# Example for publishing production to 'latest' tag
- name: Publish Release
  uses: twinfoundation/actions/publish@v1
  with:
    npm_tag: "latest"
```

--------------------------------

### Create Document REST API Endpoint (Bash)

Source: https://context7.com/twinfoundation/document-management/llms.txt

This bash command demonstrates how to create a document using the POST /document-management REST API endpoint. It includes the necessary headers for content type and authorization, and a JSON payload with document details and optional attestation flag.

```bash
curl -X POST "https://api.example.com/document-management" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{
    "documentId": "2721000",
    "documentIdFormat": "bol",
    "documentCode": "unece:DocumentCodeList#705",
    "blob": "SGVsbG8gV29ybGQ=",
    "annotationObject": {
      "@context": "https://schema.org",
      "@type": "DigitalDocument",
      "name": "myfile.pdf"
    },
    "createAttestation": true
  }'

# Response: 201 Created
# Headers: { "location": "aig:123456" }

```

--------------------------------

### POST /documentManagementCreate

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/functions/documentManagementCreate.md

Creates a document as an auditable item graph vertex. This endpoint allows for the creation of new documents within the system.

```APIDOC
## POST /documentManagementCreate

### Description
Creates a document as an auditable item graph vertex.

### Method
POST

### Endpoint
/documentManagementCreate

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **httpRequestContext** (IHttpRequestContext) - Required - The request context for the API.
- **componentName** (string) - Required - The name of the component to use in the routes.
- **request** (IDocumentManagementCreateRequest) - Required - The request payload for creating the document.

### Request Example
```json
{
  "httpRequestContext": { ... },
  "componentName": "exampleComponent",
  "request": { ... }
}
```

### Response
#### Success Response (200)
- **ICreatedResponse** (object) - The response object with additional http response properties.

#### Response Example
```json
{
  "id": "doc-123",
  "message": "Document created successfully"
}
```
```

--------------------------------

### Create Document

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-models/docs/reference/interfaces/IDocumentManagementCreateRequest.md

Creates a new document as an auditable item graph vertex. This endpoint allows for detailed configuration of the document, including its ID, format, code, content, and relationships.

```APIDOC
## POST /twinfoundation/document-management

### Description
Creates a new document as an auditable item graph vertex. This endpoint allows for detailed configuration of the document, including its ID, format, code, content, and relationships.

### Method
POST

### Endpoint
/twinfoundation/document-management

### Parameters
#### Request Body
- **documentId** (string) - Required - The document id to create.
- **documentIdFormat** (string | undefined) - Optional - The format of the document identifier.
- **documentCode** (UneceDocumentCodeList) - Required - The code for the document type.
- **blob** (string) - Required - The data to create the document with, in base64.
- **annotationObject** (IJsonLdNodeObject) - Optional - Additional information to associate with the document.
- **auditableItemGraphEdges** (object[]) - Optional - The auditable item graph vertices to connect the document to.
- **createAttestation** (boolean) - Optional - Flag to create an attestation for the document, defaults to false.
- **addAlias** (boolean) - Optional - Flag to add the document id as an alias to the aig vertex, defaults to true.
- **aliasAnnotationObject** (IJsonLdNodeObject) - Optional - Annotation object for the alias.

### Request Example
```json
{
  "documentId": "doc-123",
  "documentIdFormat": "UUID",
  "documentCode": "INV",
  "blob": "SGVsbG8gV29ybGQ=",
  "annotationObject": {
    "@context": "http://schema.org",
    "@type": "Document",
    "name": "Sample Document"
  },
  "auditableItemGraphEdges": [
    {
      "from": "vertex-abc",
      "to": "vertex-xyz",
      "label": "related_to"
    }
  ],
  "createAttestation": true,
  "addAlias": false,
  "aliasAnnotationObject": {
    "@context": "http://schema.org",
    "@type": "Alias",
    "name": "Document Alias"
  }
}
```

### Response
#### Success Response (200)
- **documentId** (string) - The ID of the created document.
- **status** (string) - The status of the document creation process.

#### Response Example
```json
{
  "documentId": "doc-123",
  "status": "created"
}
```
```

--------------------------------

### Generate Patch for release-please (Shell)

Source: https://github.com/twinfoundation/document-management/blob/next/release/README.md

This shell command uses `patch-package` to create a patch file for the `release-please` package after modifications have been made. The `--patch-dir release` flag specifies the directory where the patch will be saved.

```shell
npx patch-package release-please --patch-dir release
```

--------------------------------

### IDocumentManagementGetRevisionResponse

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-models/docs/reference/interfaces/IDocumentManagementGetRevisionResponse.md

Response structure for retrieving a document revision. It includes optional headers and the document body.

```APIDOC
## Response Structure: IDocumentManagementGetRevisionResponse

### Description
Response to get a document revision from an auditable item graph vertex.

### Properties

#### headers (optional)

> `optional` **headers**: `object`

The headers which can be used to determine the response data type.

##### content-type

> **content-type**: `"application/json"` | `"application/ld+json"`

#### body

> **body**: [`IDocument`](IDocument.md)

The body parameters.
```

--------------------------------

### GET /twinfoundation/document-management/documents/{auditableItemGraphDocumentId}/revisions/{revision}

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-models/docs/reference/interfaces/IDocumentManagementGetRevisionRequest.md

Retrieves a specific revision of a document from the auditable item graph. Supports various query parameters for including metadata, blob data, attestation, and extraction rules.

```APIDOC
## GET /twinfoundation/document-management/documents/{auditableItemGraphDocumentId}/revisions/{revision}

### Description
Retrieves a specific revision of a document from the auditable item graph. This endpoint allows for detailed control over the returned data through various query parameters.

### Method
GET

### Endpoint
/twinfoundation/document-management/documents/{auditableItemGraphDocumentId}/revisions/{revision}

### Parameters
#### Path Parameters
- **auditableItemGraphDocumentId** (string) - Required - The full id of the document to get.
- **revision** (string) - Required - The revision of the document to get.

#### Query Parameters
- **includeBlobStorageMetadata** (string) - Optional - Include the blob storage metadata in the response. Defaults to `false`.
- **includeBlobStorageData** (string) - Optional - Include the blob storage data in the response. Defaults to `false`.
- **includeAttestation** (string) - Optional - Include the attestation information in the response. Defaults to `false`.
- **extractRuleGroupId** (string) - Optional - If provided will extract data from the document using the specified rule group id.
- **extractMimeType** (string) - Optional - By default extraction will auto detect the mime type of the document, this can be used to override the detection.

### Request Example
```json
{
  "headers": {
    "accept": "application/json"
  }
}
```

### Response
#### Success Response (200)
- **documentRevision** (object) - The retrieved document revision data.
- **metadata** (object) - Blob storage metadata (if requested).
- **blobData** (string) - The document's blob data (if requested).
- **attestation** (object) - Attestation information (if requested).

#### Response Example
```json
{
  "documentRevision": {
    "id": "doc-123",
    "revision": "rev-456",
    "content": "Document content here..."
  },
  "metadata": {
    "size": 1024,
    "contentType": "application/pdf"
  }
}
```
```

--------------------------------

### Create Document - DocumentManagementService

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/classes/DocumentManagementService.md

Stores a document as an auditable item graph vertex and adds its content to blob storage. Creates a new revision if the document ID exists and blob data differs, otherwise updates the current revision. Requires document ID, format, code, and blob data. Optional parameters include annotations, edges, and creation flags.

```typescript
create(
  documentId: string,
  documentIdFormat: string | undefined,
  documentCode: UneceDocumentCodeList,
  blob: Uint8Array,
  annotationObject?: IJsonLdNodeObject,
  auditableItemGraphEdges?: object[],
  options?: {
    createAttestation?: boolean;
    addAlias?: boolean;
    aliasAnnotationObject?: IJsonLdNodeObject;
  }
): Promise<string>
```

--------------------------------

### Get Document Revision

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/classes/DocumentManagementService.md

Retrieves a specific revision of a document using its auditable item graph vertex ID and revision number. Optional parameters allow for including blob storage metadata, blob storage data, attestation information, and specifying extraction rules.

```APIDOC
## GET /document-management/revisions/{auditableItemGraphDocumentId}/{revision}

### Description
Get a document revision using its auditable item graph vertex id and revision number.

### Method
GET

### Endpoint
/document-management/revisions/{auditableItemGraphDocumentId}/{revision}

### Parameters
#### Path Parameters
- **auditableItemGraphDocumentId** (string) - Required - The auditable item graph vertex id which contains the document.
- **revision** (number) - Required - The revision id for the document.

#### Query Parameters
- **includeBlobStorageMetadata** (boolean) - Optional - Flag to include the blob storage metadata for the document, defaults to false.
- **includeBlobStorageData** (boolean) - Optional - Flag to include the blob storage data for the document, defaults to false.
- **includeAttestation** (boolean) - Optional - Flag to include the attestation information for the document, defaults to false.
- **extractRuleGroupId** (string) - Optional - If provided will extract data from the document using the specified rule group id.
- **extractMimeType** (string) - Optional - By default extraction will auto detect the mime type of the document, this can be used to override the detection.

### Response
#### Success Response (200)
- **IDocument** (object) - The documents and revisions if requested, ordered by revision descending, cursor is set if there are more document revisions.

#### Response Example
```json
{
  "id": "doc-123",
  "revision": 1,
  "content": "Document content here...",
  "blobStorageMetadata": {
    "size": 1024,
    "contentType": "text/plain"
  }
}
```
```

--------------------------------

### Implement Document Management REST Client (TypeScript)

Source: https://context7.com/twinfoundation/document-management/llms.txt

The DocumentManagementRestClient provides a client for consuming document management REST APIs, implementing the IDocumentManagementComponent interface for consistent usage. It allows for creating, retrieving, updating, and fetching all revisions of documents.

```typescript
import { DocumentManagementRestClient } from "@twin.org/document-management-rest-client";
import { UneceDocumentCodeList } from "@twin.org/standards-unece";

// Create REST client
const client = new DocumentManagementRestClient({
  endpoint: "https://api.example.com",
  headers: {
    Authorization: "Bearer <jwt-token>"
  }
});

// Create a document
const fileContent = new TextEncoder().encode("Hello World");
const vertexId = await client.create(
  "DOC-2024-001",
  "invoice",
  UneceDocumentCodeList.CommercialInvoice,
  fileContent,
  {
    "@context": "https://schema.org",
    "@type": "DigitalDocument",
    name: "invoice-001.txt"
  }
);

// Get document with blob data
const result = await client.get(vertexId, {
  includeBlobStorageData: true,
  includeAttestation: true
});

console.log("Document:", result.entries.itemListElement[0]);
// Output: { documentId: "DOC-2024-001", documentRevision: 0, blobHash: "sha256:..", ... }

// Update document (creates new revision if blob changes)
const updatedContent = new TextEncoder().encode("Updated content");
await client.update(vertexId, updatedContent);

// Get all revisions
const allRevisions = await client.get(vertexId, {}, undefined, 100);
console.log("Total revisions:", allRevisions.entries.itemListElement.length);

```

--------------------------------

### Get Document Revision

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-rest-client/docs/reference/classes/DocumentManagementRestClient.md

Retrieves a specific revision of a document using its auditable item graph vertex ID and revision number. Optional parameters allow for including blob storage metadata, blob storage data, attestation information, and specifying extraction rules or MIME types.

```typescript
/**
 * Get a document revision using it's auditable item graph vertex id.
 * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
 * @param revision The revision id for the document.
 * @param options Additional options for the get operation.
 * @returns The documents and revisions if requested, ordered by revision descending, cursor is set if there are more document revisions.
 */
async getRevision(auditableItemGraphDocumentId: string, revision: number, options?: {
  includeBlobStorageMetadata?: boolean;
  includeBlobStorageData?: boolean;
  includeAttestation?: boolean;
  extractRuleGroupId?: string;
  extractMimeType?: string;
}): Promise<IDocument> {
  // Implementation details...
  return null;
}
```

--------------------------------

### POST /document-management - Create Document

Source: https://context7.com/twinfoundation/document-management/llms.txt

Creates a new document within the document management system. Supports JSON and JSON-LD content types.

```APIDOC
## POST /document-management - Create Document

### Description
Creates a new document within the document management system. Supports JSON and JSON-LD content types.

### Method
POST

### Endpoint
/document-management

### Parameters
#### Query Parameters
- **createAttestation** (boolean) - Optional - Whether to create an attestation for the document.

#### Request Body
- **documentId** (string) - Required - The unique identifier for the document.
- **documentIdFormat** (string) - Required - The format of the document ID.
- **documentCode** (string) - Required - The UNECE document code (e.g., `unece:DocumentCodeList#705`).
- **blob** (string) - Required - The base64 encoded content of the document.
- **annotationObject** (object) - Optional - JSON-LD object containing metadata about the document.
  - **@context** (string) - Required - The JSON-LD context.
  - **@type** (string) - Required - The type of the digital document.
  - **name** (string) - Required - The name of the document file.
  - **description** (string) - Optional - A description of the document.

### Request Example
```bash
curl -X POST "https://api.example.com/document-management" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt-token>" \
  -d '{ 
    "documentId": "2721000",
    "documentIdFormat": "bol",
    "documentCode": "unece:DocumentCodeList#705",
    "blob": "SGVsbG8gV29ybGQ=",
    "annotationObject": {
      "@context": "https://schema.org",
      "@type": "DigitalDocument",
      "name": "myfile.pdf"
    },
    "createAttestation": true
  }'
```

### Response
#### Success Response (201 Created)
- **Headers**
  - **location** (string) - The URL of the created document (e.g., `aig:123456`).

#### Error Response (400 Bad Request)
- **message** (string) - Error message describing the issue.

#### Error Response (401 Unauthorized)
- **message** (string) - Error message indicating unauthorized access.
```

--------------------------------

### DocumentManagementService - Server-Side Implementation

Source: https://context7.com/twinfoundation/document-management/llms.txt

Provides the server-side implementation for document management operations, integrating with various components like auditable item graph, blob storage, attestation, and data processing.

```APIDOC
## DocumentManagementService - Server-Side Implementation

### Description
Provides the server-side implementation for document management operations. It integrates with auditable item graph, blob storage, attestation, and data processing components.

### Usage
```typescript
import { DocumentManagementService } from "@twin.org/document-management-service";
import { ComponentFactory } from "@twin.org/core";
import { UneceDocumentCodeList } from "@twin.org/standards-unece";

// Register required components first (auditable-item-graph, blob-storage, attestation, data-processing)
// Then create the service
const documentService = new DocumentManagementService({
  auditableItemGraphComponentType: "auditable-item-graph",
  blobStorageComponentType: "blob-storage",
  attestationComponentType: "attestation",
  dataProcessingComponentType: "data-processing"
});

// Register the service in ComponentFactory
ComponentFactory.register("document-management", () => documentService);

// Create a document with attestation
const pdfContent = new Uint8Array([/* PDF binary data */]);
const vertexId = await documentService.create(
  "BOL-2024-001",                              // documentId
  "bol",                                        // documentIdFormat
  UneceDocumentCodeList.BillOfLading,          // documentCode (705)
  pdfContent,                                   // blob data
  {                                             // annotationObject (JSON-LD)
    "@context": "https://schema.org",
    "@type": "DigitalDocument",
    name: "bill-of-lading-2024-001.pdf",
    description: "Bill of Lading for shipment"
  },
  undefined,                                    // auditableItemGraphEdges
  { createAttestation: true, addAlias: true }  // options
);

console.log("Created document vertex:", vertexId);
// Output: "aig:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70"
```
```

--------------------------------

### Document Creation API

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-rest-client/docs/reference/classes/DocumentManagementRestClient.md

Stores a document as an auditable item graph vertex and adds its content to blob storage. Creates a new revision if the document ID already exists and the blob data is different, otherwise updates the current revision.

```APIDOC
## POST /documents

### Description
Stores a document as an auditable item graph vertex and adds its content to blob storage. If the document id already exists and the blob data is different a new revision will be created. For any other changes the current revision will be updated.

### Method
POST

### Endpoint
/documents

### Parameters
#### Query Parameters
- **documentId** (string) - Required - The document id to create.
- **documentIdFormat** (string) - Optional - The format of the document identifier.
- **documentCode** (UneceDocumentCodeList) - Required - The code for the document type.

#### Request Body
- **blob** (Uint8Array) - Required - The data to create the document with.
- **annotationObject** (IJsonLdNodeObject) - Optional - Additional information to associate with the document.
- **auditableItemGraphEdges** (object[]) - Optional - The auditable item graph vertices to connect the document to.
- **options** (object) - Optional - Additional options for the set operation.
  - **createAttestation** (boolean) - Optional - Flag to create an attestation for the document, defaults to false.
  - **addAlias** (boolean) - Optional - Flag to add the document id as an alias to the aig vertex, defaults to true.
  - **aliasAnnotationObject** (IJsonLdNodeObject) - Optional - Annotation object for the alias.

### Request Example
```json
{
  "documentId": "doc123",
  "documentIdFormat": "UUID",
  "documentCode": "INV",
  "blob": "base64EncodedData",
  "annotationObject": {
    "@context": "http://schema.org",
    "@type": "Document",
    "name": "Invoice"
  },
  "auditableItemGraphEdges": [
    {
      "id": "vertex1",
      "label": "relatedTo"
    }
  ],
  "options": {
    "createAttestation": true,
    "addAlias": true
  }
}
```

### Response
#### Success Response (200)
- **auditableItemGraphVertex** (string) - The auditable item graph vertex created for the document including its revision.

#### Response Example
```json
{
  "auditableItemGraphVertex": "vertex456"
}
```
```

--------------------------------

### Implement Document Management Service (TypeScript)

Source: https://context7.com/twinfoundation/document-management/llms.txt

The server-side DocumentManagementService class handles document operations by integrating with auditable item graph, blob storage, attestation, and data processing components. It requires registration of these components before service instantiation and registration within the ComponentFactory.

```typescript
import { DocumentManagementService } from "@twin.org/document-management-service";
import { ComponentFactory } from "@twin.org/core";
import { UneceDocumentCodeList } from "@twin.org/standards-unece";

// Register required components first (auditable-item-graph, blob-storage, attestation, data-processing)
// Then create the service
const documentService = new DocumentManagementService({
  auditableItemGraphComponentType: "auditable-item-graph",
  blobStorageComponentType: "blob-storage",
  attestationComponentType: "attestation",
  dataProcessingComponentType: "data-processing"
});

// Register the service in ComponentFactory
ComponentFactory.register("document-management", () => documentService);

// Create a document with attestation
const pdfContent = new Uint8Array([/* PDF binary data */]);
const vertexId = await documentService.create(
  "BOL-2024-001",                              // documentId
  "bol",                                        // documentIdFormat
  UneceDocumentCodeList.BillOfLading,          // documentCode (705)
  pdfContent,                                   // blob data
  {
    "@context": "https://schema.org",
    "@type": "DigitalDocument",
    name: "bill-of-lading-2024-001.pdf",
    description: "Bill of Lading for shipment"
  },                                            // annotationObject (JSON-LD)
  undefined,                                    // auditableItemGraphEdges
  { createAttestation: true, addAlias: true }  // options
);

console.log("Created document vertex:", vertexId);
// Output: "aig:c57d94b088f4c6d2cb32ded014813d0c786aa00134c8ee22f84b1e2545602a70"

```

--------------------------------

### DocumentManagementRestClient - Client-Side Implementation

Source: https://context7.com/twinfoundation/document-management/llms.txt

Provides a client for consuming document management REST APIs, implementing the same `IDocumentManagementComponent` interface for consistent usage patterns.

```APIDOC
## DocumentManagementRestClient - Client-Side Implementation

### Description
Provides a client for consuming document management REST APIs. It implements the same `IDocumentManagementComponent` interface for consistent usage patterns.

### Usage
```typescript
import { DocumentManagementRestClient } from "@twin.org/document-management-rest-client";
import { UneceDocumentCodeList } from "@twin.org/standards-unece";

// Create REST client
const client = new DocumentManagementRestClient({
  endpoint: "https://api.example.com",
  headers: {
    Authorization: "Bearer <jwt-token>"
  }
});

// Create a document
const fileContent = new TextEncoder().encode("Hello World");
const vertexId = await client.create(
  "DOC-2024-001",
  "invoice",
  UneceDocumentCodeList.CommercialInvoice,
  fileContent,
  {
    "@context": "https://schema.org",
    "@type": "DigitalDocument",
    name: "invoice-001.txt"
  }
);

// Get document with blob data
const result = await client.get(vertexId, {
  includeBlobStorageData: true,
  includeAttestation: true
});

console.log("Document:", result.entries.itemListElement[0]);
// Output: { documentId: "DOC-2024-001", documentRevision: 0, blobHash: "sha256: sooner", ... }

// Update document (creates new revision if blob changes)
const updatedContent = new TextEncoder().encode("Updated content");
await client.update(vertexId, updatedContent);

// Get all revisions
const allRevisions = await client.get(vertexId, {}, undefined, 100);
console.log("Total revisions:", allRevisions.entries.itemListElement.length);
```
```

--------------------------------

### Query Documents (API)

Source: https://context7.com/twinfoundation/document-management/llms.txt

Queries documents based on provided parameters like documentId and limit. Requires an 'Accept' header for JSON and an 'Authorization' header with a JWT token.

```bash
curl -X GET "https://api.example.com/document-management?documentId=2721000&limit=10" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt-token>"
```

--------------------------------

### Document Management Route Generation

Source: https://github.com/twinfoundation/document-management/blob/next/packages/document-management-service/docs/reference/functions/generateRestRoutesDocumentManagement.md

Generates REST routes for the document management system. This function allows for customization of the base route name and the component name used within the routes.

```APIDOC
## generateRestRoutesDocumentManagement()

### Description
Generates REST routes for the document management system. This function allows for customization of the base route name and the component name used within the routes.

### Method
N/A (This is a function description, not a direct HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
// This is a function call, not a request body
generateRestRoutesDocumentManagement('documents', 'DocumentComponent');
```

### Response
#### Success Response (200)
- **routes** (IRestRoute<any, any>[]) - An array of IRestRoute objects representing the generated routes.

#### Response Example
```json
[
  {
    "path": "/documents",
    "component": "DocumentComponent",
    "children": [
      // ... other nested routes
    ]
  }
]
```
```