@3sixty/document-management-models 0.0.0-stage → 0.20.0-next.1

package/dist/es/schemas/Document.json

@@ -0,0 +1,86 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.3sixty.global/documents/Document",
+    "title": "Document",
+    "description": "Interface describing a document.",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "type": "array",
+            "prefixItems": [
+                {
+                    "const": "https://schema.org"
+                },
+                {
+                    "const": "https://schema.3sixty.global/documents/"
+                },
+                {
+                    "const": "https://schema.3sixty.global/common/"
+                }
+            ],
+            "items": {
+                "$ref": "https://schema.3sixty.global/json-ld/JsonLdContextDefinitionElement"
+            },
+            "minItems": 3,
+            "description": "JSON-LD Context."
+        },
+        "type": {
+            "const": "Document",
+            "description": "JSON-LD Type."
+        },
+        "id": {
+            "type": "string",
+            "description": "The full id of the document."
+        },
+        "documentRevision": {
+            "type": "number",
+            "description": "The revision of the document as a 0 based index."
+        },
+        "blobStorageId": {
+            "type": "string",
+            "description": "The blob storage id for the document."
+        },
+        "integrity": {
+            "type": "string",
+            "description": "The integrity of the blob data."
+        },
+        "attestationId": {
+            "type": "string",
+            "description": "The attestation for the document if one was created."
+        },
+        "dateCreated": {
+            "type": "string",
+            "description": "The date/time of when the document was created."
+        },
+        "dateModified": {
+            "type": "string",
+            "description": "The date/time of when the document was modified."
+        },
+        "dateDeleted": {
+            "type": "string",
+            "description": "The date/time of when the document was deleted, as we never actually remove items."
+        },
+        "organizationIdentity": {
+            "type": "string",
+            "description": "The organization which added the document to the graph."
+        },
+        "userIdentity": {
+            "type": "string",
+            "description": "The user who added the document to the graph."
+        }
+    },
+    "required": [
+        "@context",
+        "type",
+        "id",
+        "documentRevision",
+        "blobStorageId",
+        "integrity",
+        "dateCreated"
+    ],
+    "allOf": [
+        {
+            "$ref": "https://schema.3sixty.global/documents/DocumentBase"
+        }
+    ]
+}

package/dist/es/schemas/DocumentAttestation.json

@@ -0,0 +1,60 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.3sixty.global/documents/DocumentAttestation",
+    "title": "DocumentAttestation",
+    "description": "Interface describing a document attestation.",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "type": "array",
+            "prefixItems": [
+                {
+                    "const": "https://schema.org"
+                },
+                {
+                    "const": "https://schema.3sixty.global/documents/"
+                },
+                {
+                    "const": "https://schema.3sixty.global/common/"
+                }
+            ],
+            "items": false,
+            "minItems": 3,
+            "maxItems": 3,
+            "description": "JSON-LD Context."
+        },
+        "type": {
+            "const": "DocumentAttestation",
+            "description": "JSON-LD Type."
+        },
+        "documentId": {
+            "type": "string",
+            "description": "The id of the document."
+        },
+        "documentCode": {
+            "$ref": "https://schema.3sixty.global/unece/UneceDocumentCodeList",
+            "description": "The code for the document type."
+        },
+        "documentRevision": {
+            "type": "number",
+            "description": "The revision of the document as a 0 based index."
+        },
+        "dateCreated": {
+            "type": "string",
+            "description": "The date/time of when the document was created."
+        },
+        "integrity": {
+            "type": "string",
+            "description": "The integrity of the document being attested."
+        }
+    },
+    "required": [
+        "@context",
+        "type",
+        "documentId",
+        "documentCode",
+        "documentRevision",
+        "dateCreated",
+        "integrity"
+    ]
+}

package/dist/es/schemas/DocumentBase.json

@@ -0,0 +1,29 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.3sixty.global/documents/DocumentBase",
+    "title": "DocumentBase",
+    "description": "Interface describing a document base.",
+    "type": "object",
+    "properties": {
+        "documentId": {
+            "type": "string",
+            "description": "The id of the document."
+        },
+        "documentIdFormat": {
+            "type": "string",
+            "description": "The format of the document id."
+        },
+        "documentCode": {
+            "$ref": "https://schema.3sixty.global/unece/UneceDocumentCodeList",
+            "description": "The code for the document type."
+        },
+        "annotationObject": {
+            "$ref": "https://schema.3sixty.global/json-ld/JsonLdNodeObject",
+            "description": "Additional annotation information for the document."
+        }
+    },
+    "required": [
+        "documentId",
+        "documentCode"
+    ]
+}

package/dist/es/schemas/DocumentHydrated.json

@@ -0,0 +1,25 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.3sixty.global/documents/DocumentHydrated",
+    "title": "DocumentHydrated",
+    "description": "Interface describing a hydrated document which includes additional information that can be optionally requested when retrieving a document.",
+    "type": "object",
+    "properties": {
+        "blobStorageEntry": {
+            "$ref": "https://schema.3sixty.global/blob-storage/BlobStorageEntry",
+            "description": "The additional JSON-LD for blob storage if it was requested."
+        },
+        "extractedData": {
+            "description": "The data extracted from the document using data extraction services."
+        },
+        "attestationInformation": {
+            "$ref": "https://schema.3sixty.global/attestation/AttestationInformation",
+            "description": "The additional JSON-LD for attestation storage if it was requested."
+        }
+    },
+    "allOf": [
+        {
+            "$ref": "https://schema.3sixty.global/documents/Document"
+        }
+    ]
+}

package/dist/es/schemas/DocumentList.json

@@ -0,0 +1,51 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schema.3sixty.global/documents/DocumentList",
+    "title": "DocumentList",
+    "description": "Interface describing a list of document entries.",
+    "type": "object",
+    "properties": {
+        "@context": {
+            "type": "array",
+            "prefixItems": [
+                {
+                    "const": "https://schema.org"
+                },
+                {
+                    "const": "https://schema.3sixty.global/documents/"
+                },
+                {
+                    "const": "https://schema.3sixty.global/common/"
+                }
+            ],
+            "items": {
+                "$ref": "https://schema.3sixty.global/json-ld/JsonLdContextDefinitionElement"
+            },
+            "minItems": 3,
+            "description": "JSON-LD Context."
+        },
+        "type": {
+            "const": "ItemList",
+            "description": "JSON-LD Type."
+        },
+        "itemListElement": {
+            "type": "array",
+            "items": {
+                "$ref": "https://schema.3sixty.global/documents/DocumentHydrated"
+            },
+            "description": "The list of documents."
+        },
+        "edges": {
+            "type": "array",
+            "items": {
+                "type": "string"
+            },
+            "description": "The ids of the other vertices which are connected to the document."
+        }
+    },
+    "required": [
+        "@context",
+        "type",
+        "itemListElement"
+    ]
+}

package/dist/types/compiled/validators.d.ts

@@ -0,0 +1,21 @@
+import type { ICompiledValidator } from "@3sixty/data-core";
+/**
+ * Compiled validator for the Document schema.
+ */
+export declare const CompiledDocument: ICompiledValidator;
+/**
+ * Compiled validator for the DocumentAttestation schema.
+ */
+export declare const CompiledDocumentAttestation: ICompiledValidator;
+/**
+ * Compiled validator for the DocumentBase schema.
+ */
+export declare const CompiledDocumentBase: ICompiledValidator;
+/**
+ * Compiled validator for the DocumentHydrated schema.
+ */
+export declare const CompiledDocumentHydrated: ICompiledValidator;
+/**
+ * Compiled validator for the DocumentList schema.
+ */
+export declare const CompiledDocumentList: ICompiledValidator;

package/dist/types/dataTypes/documentManagementDataTypes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Handle all the data types for document management.
+ */
+export declare class DocumentManagementDataTypes {
+    /**
+     * Register all the data types.
+     */
+    static registerTypes(): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,22 @@
+export * from "./compiled/validators.js";
+export * from "./dataTypes/documentManagementDataTypes.js";
+export * from "./models/api/IDocumentManagementCreateRequest.js";
+export * from "./models/api/IDocumentManagementGetRequest.js";
+export * from "./models/api/IDocumentManagementGetResponse.js";
+export * from "./models/api/IDocumentManagementGetRevisionRequest.js";
+export * from "./models/api/IDocumentManagementGetRevisionResponse.js";
+export * from "./models/api/IDocumentManagementQueryRequest.js";
+export * from "./models/api/IDocumentManagementQueryResponse.js";
+export * from "./models/api/IDocumentManagementRemoveRequest.js";
+export * from "./models/api/IDocumentManagementUpdatePartialRequest.js";
+export * from "./models/documentContexts.js";
+export * from "./models/documentTypes.js";
+export * from "./models/IDocument.js";
+export * from "./models/IDocumentBase.js";
+export * from "./models/IDocumentHydrated.js";
+export * from "./models/IDocumentAttestation.js";
+export * from "./models/IDocumentList.js";
+export * from "./models/IDocumentManagementComponent.js";
+export * from "./models/IDocumentManagementEdgeEntry.js";
+export * from "./models/documentManagementMetricIds.js";
+export * from "./models/documentManagementMetrics.js";

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

@@ -0,0 +1,72 @@
+import type { IJsonLdContextDefinitionElement } from "@3sixty/data-json-ld";
+import type { SchemaOrgContexts } from "@3sixty/standards-schema-org";
+import type { DocumentContexts } from "./documentContexts.js";
+import type { DocumentTypes } from "./documentTypes.js";
+import type { IDocumentBase } from "./IDocumentBase.js";
+/**
+ * Interface describing a document.
+ */
+export interface IDocument extends IDocumentBase {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof SchemaOrgContexts.Context,
+        typeof DocumentContexts.Context,
+        typeof DocumentContexts.ContextCommon,
+        ...IJsonLdContextDefinitionElement[]
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof DocumentTypes.Document;
+    /**
+     * The full id of the document.
+     */
+    id: string;
+    /**
+     * The revision of the document as a 0 based index.
+     * @json-ld type:schema:Integer
+     */
+    documentRevision: number;
+    /**
+     * The blob storage id for the document.
+     * @json-ld type:schema:identifier
+     */
+    blobStorageId: string;
+    /**
+     * The integrity of the blob data.
+     * @json-ld namespace:twin-common
+     */
+    integrity: string;
+    /**
+     * The attestation for the document if one was created.
+     * @json-ld type:schema:identifier
+     */
+    attestationId?: string;
+    /**
+     * The date/time of when the document was created.
+     * @json-ld namespace:schema
+     */
+    dateCreated: string;
+    /**
+     * The date/time of when the document was modified.
+     * @json-ld namespace:schema
+     */
+    dateModified?: string;
+    /**
+     * The date/time of when the document was deleted, as we never actually remove items.
+     * @json-ld namespace:schema
+     */
+    dateDeleted?: string;
+    /**
+     * The organization which added the document to the graph.
+     * @json-ld namespace:twin-common
+     */
+    organizationIdentity?: string;
+    /**
+     * The user who added the document to the graph.
+     * @json-ld namespace:twin-common
+     */
+    userIdentity?: string;
+}

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

@@ -0,0 +1,46 @@
+import type { SchemaOrgContexts } from "@3sixty/standards-schema-org";
+import type { UneceDocumentCodeList } from "@3sixty/standards-unece";
+import type { DocumentContexts } from "./documentContexts.js";
+import type { DocumentTypes } from "./documentTypes.js";
+/**
+ * Interface describing a document attestation.
+ */
+export interface IDocumentAttestation {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof SchemaOrgContexts.Context,
+        typeof DocumentContexts.Context,
+        typeof DocumentContexts.ContextCommon
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof DocumentTypes.DocumentAttestation;
+    /**
+     * The id of the document.
+     * @json-ld type:schema:identifier
+     */
+    documentId: string;
+    /**
+     * The code for the document type.
+     * @json-ld type:schema:identifier
+     */
+    documentCode: UneceDocumentCodeList;
+    /**
+     * The revision of the document as a 0 based index.
+     * @json-ld type:schema:Integer
+     */
+    documentRevision: number;
+    /**
+     * The date/time of when the document was created.
+     * @json-ld namespace:schema
+     */
+    dateCreated: string;
+    /**
+     * The integrity of the document being attested.
+     * @json-ld namespace:twin-common
+     */
+    integrity: string;
+}

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

@@ -0,0 +1,27 @@
+import type { IJsonLdNodeObject } from "@3sixty/data-json-ld";
+import type { UneceDocumentCodeList } from "@3sixty/standards-unece";
+/**
+ * Interface describing a document base.
+ */
+export interface IDocumentBase {
+    /**
+     * The id of the document.
+     * @json-ld type:schema:identifier
+     */
+    documentId: string;
+    /**
+     * The format of the document id.
+     * @json-ld type:schema:Text
+     */
+    documentIdFormat?: string;
+    /**
+     * The code for the document type.
+     * @json-ld type:schema:identifier
+     */
+    documentCode: UneceDocumentCodeList;
+    /**
+     * Additional annotation information for the document.
+     * @json-ld namespace:twin-common
+     */
+    annotationObject?: IJsonLdNodeObject;
+}

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

@@ -0,0 +1,23 @@
+import type { IAttestationInformation } from "@3sixty/attestation-models";
+import type { IBlobStorageEntry } from "@3sixty/blob-storage-models";
+import type { IDocument } from "./IDocument.js";
+/**
+ * Interface describing a hydrated document which includes additional information that can be optionally requested when retrieving a document.
+ */
+export interface IDocumentHydrated extends IDocument {
+    /**
+     * The additional JSON-LD for blob storage if it was requested.
+     * @json-ld id
+     */
+    blobStorageEntry?: IBlobStorageEntry;
+    /**
+     * The data extracted from the document using data extraction services.
+     * @json-ld type:json
+     */
+    extractedData?: unknown;
+    /**
+     * The additional JSON-LD for attestation storage if it was requested.
+     * @json-ld id
+     */
+    attestationInformation?: IAttestationInformation;
+}

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

@@ -0,0 +1,32 @@
+import type { IJsonLdContextDefinitionElement } from "@3sixty/data-json-ld";
+import type { SchemaOrgContexts, SchemaOrgTypes } from "@3sixty/standards-schema-org";
+import type { DocumentContexts } from "./documentContexts.js";
+import type { IDocumentHydrated } from "./IDocumentHydrated.js";
+/**
+ * Interface describing a list of document entries.
+ */
+export interface IDocumentList {
+    /**
+     * JSON-LD Context.
+     */
+    "@context": [
+        typeof SchemaOrgContexts.Context,
+        typeof DocumentContexts.Context,
+        typeof DocumentContexts.ContextCommon,
+        ...IJsonLdContextDefinitionElement[]
+    ];
+    /**
+     * JSON-LD Type.
+     */
+    type: typeof SchemaOrgTypes.ItemList;
+    /**
+     * The list of documents.
+     * @json-ld namespace:schema
+     */
+    [SchemaOrgTypes.ItemListElement]: IDocumentHydrated[];
+    /**
+     * The ids of the other vertices which are connected to the document.
+     * @json-ld container:set
+     */
+    edges?: string[];
+}

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

@@ -0,0 +1,123 @@
+import type { IAuditableItemGraphVertexList } from "@3sixty/auditable-item-graph-models";
+import type { IComponent } from "@3sixty/core";
+import type { IJsonLdNodeObject } from "@3sixty/data-json-ld";
+import type { IDocumentBase } from "./IDocumentBase.js";
+import type { IDocumentHydrated } from "./IDocumentHydrated.js";
+import type { IDocumentList } from "./IDocumentList.js";
+import type { IDocumentManagementEdgeEntry } from "./IDocumentManagementEdgeEntry.js";
+/**
+ * Interface describing a document management contract.
+ */
+export interface IDocumentManagementComponent extends IComponent {
+    /**
+     * Create a document as an auditable item graph vertex and add 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.
+     * @param document The document base properties.
+     * @param blob The data to create the document with as bytes, or an existing blob storage entry id.
+     * @param auditableItemGraphEdges The auditable item graph vertices to connect the document to.
+     * @param options Additional options for the set operation.
+     * @param options.includeAttestation Flag to create an attestation for the document, defaults to false.
+     * @param options.includeAlias Flag to add the document id as an alias to the aig vertex, defaults to true.
+     * @param options.aliasAnnotationObject Annotation object for the alias.
+     * @returns The auditable item graph vertex created for the document including its revision.
+     */
+    create(document: IDocumentBase, blob: Uint8Array | string, auditableItemGraphEdges?: IDocumentManagementEdgeEntry[], options?: {
+        includeAttestation?: boolean;
+        includeAlias?: boolean;
+        aliasAnnotationObject?: IJsonLdNodeObject;
+    }): Promise<string>;
+    /**
+     * Update a document as an auditable item graph vertex and add its content to blob storage.
+     * If the blob data is different a new revision will be created.
+     * For any other changes the current revision will be updated.
+     * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
+     * @param document The document base properties to update. annotationObject, documentIdFormat and documentCode are applied in-place to the current revision.
+     * @param blob The data to update the document with as bytes, or an existing blob storage entry id.
+     * @param auditableItemGraphEdges Explicit edge delta to apply. If undefined, existing connections
+     * are retained unchanged. Use `add` to create new connections and `remove` to disconnect existing
+     * ones by their target vertex id. To update alias metadata on an already-connected vertex, include
+     * it in `add` with the updated `aliasAnnotationObject` - AIG's alias patch is an upsert, so the
+     * alias is updated in place without creating a duplicate back-edge.
+     * @param auditableItemGraphEdges.add Connections to add; each creates a back-edge on the connected vertex.
+     * @param auditableItemGraphEdges.remove Target vertex IDs to disconnect; their back-edges are removed.
+     * @param options Additional options for the update operation.
+     * @param options.includeAttestation Set to true to start attesting the document (even if originally created without attestation), or false to remove the existing attestation. Omit (undefined) to leave attestation state unchanged.
+     * @param options.includeAlias Set to true to add the document id as an alias on the aig vertex, or false to remove it. Omit to leave alias state unchanged.
+     * @param options.aliasAnnotationObject Annotation object for the alias when adding.
+     * @returns A promise that resolves when the document has been updated.
+     */
+    updatePartial(auditableItemGraphDocumentId: string, document?: Partial<Pick<IDocumentBase, "annotationObject" | "documentIdFormat" | "documentCode">>, blob?: Uint8Array | string, auditableItemGraphEdges?: {
+        add?: IDocumentManagementEdgeEntry[];
+        remove?: string[];
+    }, options?: {
+        includeAttestation?: boolean;
+        includeAlias?: boolean;
+        aliasAnnotationObject?: IJsonLdNodeObject;
+    }): Promise<void>;
+    /**
+     * Get a document using it's auditable item graph vertex id and optional revision.
+     * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
+     * @param options Additional options for the get operation.
+     * @param options.includeBlobStorageMetadata Flag to include the blob storage metadata for the document, defaults to false.
+     * @param options.includeBlobStorageData Flag to include the blob storage data for the document, defaults to false.
+     * @param options.includeAttestation Flag to include the attestation information for the document, defaults to false.
+     * @param options.includeRemoved Flag to include deleted documents, defaults to false.
+     * @param options.includeDeletedEdges Flag to include soft-deleted edges in the response, defaults to false.
+     * @param options.extractRuleGroupId If provided will extract data from the document using the specified rule group id.
+     * @param options.extractMimeType By default extraction will auto detect the mime type of the document, this can be used to override the detection.
+     * @param cursor The cursor to get the next chunk of revisions.
+     * @param limit Limit the number of items to return, defaults to 1 so only most recent is returned.
+     * @returns The documents and revisions if requested, ordered by revision descending, cursor is set if there are more document revisions.
+     */
+    get(auditableItemGraphDocumentId: string, options?: {
+        includeBlobStorageMetadata?: boolean;
+        includeBlobStorageData?: boolean;
+        includeAttestation?: boolean;
+        includeRemoved?: boolean;
+        includeDeletedEdges?: boolean;
+        extractRuleGroupId?: string;
+        extractMimeType?: string;
+    }, cursor?: string, limit?: number): Promise<{
+        entries: IDocumentList;
+        cursor?: string;
+    }>;
+    /**
+     * 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 of the document to get.
+     * @param options Additional options for the get operation.
+     * @param options.includeBlobStorageMetadata Flag to include the blob storage metadata for the document, defaults to false.
+     * @param options.includeBlobStorageData Flag to include the blob storage data for the document, defaults to false.
+     * @param options.includeAttestation Flag to include the attestation information for the document, defaults to false.
+     * @param options.extractRuleGroupId If provided will extract data from the document using the specified rule group id.
+     * @param options.extractMimeType By default extraction will auto detect the mime type of the document, this can be used to override the detection.
+     * @returns The document for the specified revision.
+     */
+    getRevision(auditableItemGraphDocumentId: string, revision: number, options?: {
+        includeBlobStorageMetadata?: boolean;
+        includeBlobStorageData?: boolean;
+        includeAttestation?: boolean;
+        extractRuleGroupId?: string;
+        extractMimeType?: string;
+    }): Promise<IDocumentHydrated>;
+    /**
+     * Remove an auditable item graph vertex using it's id.
+     * The document dateDeleted will be set, but can still be queried with the includeRemoved flag.
+     * @param auditableItemGraphDocumentId The auditable item graph vertex id which contains the document.
+     * @param revision The revision of the document to remove.
+     * @returns A promise that resolves when the revision has been removed.
+     */
+    removeRevision(auditableItemGraphDocumentId: string, revision: number): Promise<void>;
+    /**
+     * Find all the document with a specific id.
+     * @param documentId The document id to find in the graph.
+     * @param cursor The cursor to get the next chunk of documents.
+     * @param limit The limit to get the next chunk of documents.
+     * @returns The graph vertices that contain documents referencing the specified document id.
+     */
+    query(documentId: string, cursor?: string, limit?: number): Promise<{
+        entries: IAuditableItemGraphVertexList;
+        cursor?: string;
+    }>;
+}

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

@@ -0,0 +1,18 @@
+import type { IJsonLdNodeObject } from "@3sixty/data-json-ld";
+/**
+ * A single edge entry used when connecting a document to an AIG vertex.
+ */
+export interface IDocumentManagementEdgeEntry {
+    /**
+     * The target AIG vertex id to connect to.
+     */
+    targetId: string;
+    /**
+     * Whether to add the document id as an alias on the connected vertex, defaults to false.
+     */
+    includeAlias?: boolean;
+    /**
+     * Annotation object for the alias, if includeAlias is true.
+     */
+    aliasAnnotationObject?: IJsonLdNodeObject;
+}