@acorex-platform/module-document-management-client 0.0.21

package/types/acorex-platform-module-document-management-client-contracts.d.ts

@@ -0,0 +1,375 @@
+import { AXPMultiLanguageString, AXPFileListItem, AXPMetaData, AXPCategoryEntity } from '@acorex-platform/framework-shared/core';
+import { AXPEntityModel } from '@acorex-platform/framework-shared/entity';
+import { AXMMetaDataBuilderValue } from '@acorex-platform/module-data-management-contracts';
+
+declare const AXPDocumentManagementFeatureKeys: {
+    readonly MaxSizeStorage: "DocumentManagement:Feature:max-size-storage";
+};
+
+declare const AXPDocumentManagementMenuKeys: {
+    readonly DocumentTypes: "document-management:menu:document-types";
+    readonly TenantDrive: "document-management:drive:tenant";
+    readonly UserDrive: "document-management:drive:user";
+};
+
+/**
+ * Content & Documents capabilities used by this module.
+ * Domain capability keys for this module. Root groups live in `AXPCommonPermissionGroupKeys` (common contracts).
+ */
+declare const AXPContentDocumentsPermissionKeys: {
+    readonly Access: "ContentDocuments:Permission:Access";
+    readonly MaintainDocuments: "ContentDocuments:Permission:MaintainDocuments";
+    readonly MaintainContent: "ContentDocuments:Permission:MaintainContent";
+    readonly MaintainFormTemplates: "ContentDocuments:Permission:MaintainFormTemplates";
+    readonly Setup: "ContentDocuments:Permission:Setup";
+};
+/**
+ * @deprecated Prefer {@link AXPContentDocumentsPermissionKeys}.
+ * Legacy nested shape kept so existing imports compile during migration.
+ */
+declare const AXMPermissionsKeys: {
+    readonly DocumentManagement: {
+        readonly Management: "ContentDocuments:Permission:MaintainDocuments";
+        readonly DocumentType: {
+            readonly Management: "ContentDocuments:Permission:Setup";
+            readonly View: "ContentDocuments:Permission:Setup";
+            readonly Edit: "ContentDocuments:Permission:Setup";
+            readonly Delete: "ContentDocuments:Permission:Setup";
+            readonly Create: "ContentDocuments:Permission:Setup";
+        };
+        readonly Driver: {
+            readonly Management: "ContentDocuments:Permission:MaintainDocuments";
+            readonly View: "ContentDocuments:Permission:MaintainDocuments";
+            readonly Edit: "ContentDocuments:Permission:MaintainDocuments";
+            readonly Delete: "ContentDocuments:Permission:MaintainDocuments";
+            readonly Create: "ContentDocuments:Permission:MaintainDocuments";
+        };
+    };
+};
+
+/**
+ * Persisted setting keys for the Document Management module (`AXPSettingsService`).
+ */
+declare enum AXPDocumentManagementSettings {
+    ViewMode = "DocumentManagement:Setting:DocumentExplorer.Layout.ViewMode",
+    SortField = "DocumentManagement:Setting:DocumentExplorer.Layout.SortField",
+    SortDirection = "DocumentManagement:Setting:DocumentExplorer.Layout.SortDirection",
+    GroupByType = "DocumentManagement:Setting:DocumentExplorer.Layout.GroupByType",
+    DetailPanelOpen = "DocumentManagement:Setting:DocumentExplorer.Layout.DetailPanelOpen"
+}
+
+declare const AXMDocumentManagementCommandKeys: {
+    readonly DocumentExpirationNotifyRun: "DocumentManagement:DocumentExpiration:NotifyRun";
+};
+declare const AXM_DOCUMENT_EXPIRATION_NOTIFY_RUN_COMMAND_KEY: "DocumentManagement:DocumentExpiration:NotifyRun";
+
+declare const RootConfig: {
+    readonly config: {
+        i18n: string;
+        module: string;
+    };
+    readonly module: {
+        readonly module: string;
+        readonly name: string;
+        readonly title: `@${string}:module.title`;
+        readonly icon: "fa-light fa-books";
+    };
+    readonly entities: {
+        readonly folder: {
+            readonly name: "Folder";
+            readonly title: `@${string}:entities.folder.title`;
+            readonly titlePlural: `@${string}:entities.folder.title-plural`;
+            readonly icon: "fa-light fa-folder";
+        };
+        readonly document: {
+            readonly name: "Document";
+            readonly title: `@${string}:entities.document.title`;
+            readonly titlePlural: `@${string}:entities.document.title-plural`;
+            readonly icon: "fa-light fa-file";
+        };
+        readonly documentType: {
+            readonly name: "DocumentType";
+            readonly title: `@${string}:entities.document-type.title`;
+            readonly titlePlural: `@${string}:entities.document-type.title-plural`;
+            readonly icon: "fa-light fa-books";
+        };
+        readonly documentShortcut: {
+            readonly name: "DocumentShortcut";
+            readonly title: `@${string}:entities.document-shortcut.title`;
+            readonly titlePlural: `@${string}:entities.document-shortcut.title-plural`;
+            readonly icon: "fa-light fa-up-right-from-square";
+        };
+    };
+    readonly queries: {
+        readonly dashboard: {
+            readonly documentsKpi: `${string}:Dashboard:DocumentsKpi`;
+        };
+        readonly reports: {
+            readonly getDocumentsByType: `${string}:Reports:GetDocumentsByType`;
+            readonly getDocumentExpiration: `${string}:Reports:GetDocumentExpiration`;
+        };
+    };
+    /**
+     * Daily document expiration notifier (BackgroundJobSchedule → NotifyRun).
+     * Template ids align with AXM_TEXT_TEMPLATE_IDS in content-management contracts.
+     */
+    readonly documentExpirationNotify: {
+        readonly providerKey: "document-management";
+        readonly defaultCron: "0 0 * * *";
+        readonly expiredTemplateId: "c7100009-0001-4111-b111-090909090909";
+        readonly nearExpiryTemplateId: "c710000a-0001-4111-b111-0a0a0a0a0a0a";
+        readonly tenantRoleNames: readonly ["admin", "safety-manager"];
+    };
+};
+
+declare const AXMDocumentManagementQueryKeys: {
+    readonly Drive: {
+        readonly GetRoot: "DocumentManagement:Drive:GetRoot";
+        readonly GetContents: "DocumentManagement:Drive:GetContents";
+        readonly GetRootByEntityRef: "DocumentManagement:Drive:GetRootByEntityRef";
+    };
+    readonly Document: {
+        readonly GetPath: "DocumentManagement:Document:GetPath";
+        readonly Search: "DocumentManagement:Document:Search";
+        readonly FindMany: "DocumentManagement:Document:FindMany";
+        readonly GetExpiredCount: "DocumentManagement:Document:GetExpiredCount";
+    };
+    readonly Folder: {
+        readonly GetPath: "DocumentManagement:Folder:GetPath";
+        readonly Search: "DocumentManagement:Folder:Search";
+    };
+    readonly DocumentType: {
+        readonly GetByName: "DocumentManagement:DocumentType:GetByName";
+    };
+    readonly Metadata: {
+        readonly GetUniqueDefinitions: "DocumentManagement:Metadata:GetUniqueDefinitions";
+    };
+};
+
+type AXMDocumentExpirationStatus = 'expired' | 'near';
+/**
+ * Near-expiry window (days) shared by document badge UI and expiration reports.
+ * Documents that expire within this many days (and are not yet past) are "near".
+ */
+declare const AXM_DOCUMENT_EXPIRATION_NEAR_DAYS = 7;
+declare function toDocumentExpirationDate(value: unknown): Date | undefined;
+/**
+ * Canonical persisted value for `Document.expirationDate`.
+ * Matches `date-time-editor`: ISO string at start of local day.
+ * Seed mocks and API writes must both use this shape (never BSON `Date`).
+ */
+declare function toDocumentExpirationStorageValue(value: unknown): string | null | undefined;
+/**
+ * Local-day bounds used to query expired vs near-expiry documents.
+ * - expired: expirationDate < startOfToday
+ * - near: startOfToday <= expirationDate <= nearEndInclusive
+ */
+declare function getDocumentExpirationQueryBounds(options?: {
+    nearDays?: number;
+    now?: Date;
+}): {
+    startOfToday: Date;
+    nearEndInclusive: Date;
+};
+/**
+ * Same bounds as {@link getDocumentExpirationQueryBounds}, serialized as ISO strings.
+ *
+ * Entity storage often persists `expirationDate` as an ISO string. Passing a `Date`
+ * into Mongo `$lt` / `$gte` compares different BSON types and under-counts matches.
+ * HTTP entity queries stringify dates automatically; in-process drive/middleware
+ * queries must use these string bounds explicitly.
+ */
+declare function getDocumentExpirationQueryBoundValues(options?: {
+    nearDays?: number;
+    now?: Date;
+}): {
+    startOfToday: string;
+    nearEndInclusive: string;
+};
+/**
+ * Calendar day key (YYYY-MM-DD) for `date` in an IANA timezone.
+ */
+declare function getDocumentExpirationDateKey(date: Date, timeZone?: string): string;
+/** Add whole calendar days to a YYYY-MM-DD key (UTC noon arithmetic). */
+declare function addDaysToDocumentExpirationDateKey(dateKey: string, days: number): string;
+/** Inclusive UTC day window for a YYYY-MM-DD key (for expirationDate range queries). */
+declare function getUtcDayBoundsForDateKey(dateKey: string): {
+    start: Date;
+    endExclusive: Date;
+};
+/**
+ * Whole days from `from` to `to` (start-of-local-day). Negative means `to` is in the past.
+ */
+declare function getDocumentExpirationRemainingDays(expirationDate: Date, now?: Date): number;
+/**
+ * Classify a document expire date as expired / near / neither.
+ * Uses only `Document.expirationDate` (platform field).
+ */
+declare function classifyDocumentExpirationStatus(expirationDate: unknown, options?: {
+    nearDays?: number;
+    now?: Date;
+}): AXMDocumentExpirationStatus | null;
+
+/** Document lifecycle status (EDMS-style review workflow). */
+type AXMDocumentManagementDocumentStatus = 'draft' | 'in-review' | 'approved' | 'rejected' | 'revision-requested';
+/** Status value constants for use in code. */
+declare const AXMDocumentManagementDocumentStatusValues: {
+    Draft: "draft";
+    InReview: "in-review";
+    Approved: "approved";
+    Rejected: "rejected";
+    RevisionRequested: "revision-requested";
+};
+interface AXMDocumentDto extends AXPEntityModel<string> {
+    name: string;
+    title: string;
+    documentType: AXMDocumentDocDto;
+    parentId: string;
+    fileInfo: AXPFileListItem;
+    description?: string;
+    /** ISO string at start of local day (same as date-time-editor); `Date` accepted on write then normalized. */
+    expirationDate?: Date | string;
+    statusId?: AXMDocumentManagementDocumentStatus;
+    status?: {
+        id: AXMDocumentManagementDocumentStatus;
+        title?: string;
+    };
+    version?: number;
+    metaDataForm?: AXPMetaData;
+    /**
+     * Optional host-entity binding (same semantics as Folder.refType / Folder.refId).
+     * Stamped from the nearest ancestor folder that has a record reference.
+     */
+    refType?: string;
+    refId?: string;
+}
+interface AXMDocumentDocDto {
+    id: string;
+    name: string;
+    title: AXPMultiLanguageString;
+}
+
+/**
+ * Document Shortcut entity.
+ *
+ * Lightweight link that points to a physical document or folder so the same
+ * content can appear in multiple locations (folders, entity-bound drives)
+ * without duplicating the underlying file.
+ */
+interface AXMDocumentShortcutEntityModel extends AXPEntityModel<string> {
+    /** Folder that visually contains this shortcut. */
+    folderId: string;
+    /**
+     * Target document id this shortcut points to.
+     * Either targetDocumentId or targetFolderId must be set.
+     */
+    targetDocumentId?: string;
+    /**
+     * Target folder id this shortcut points to.
+     * Either targetDocumentId or targetFolderId must be set.
+     */
+    targetFolderId?: string;
+    /**
+     * Optional display name for the shortcut.
+     * When not provided, UI may fall back to target's name.
+     */
+    name?: string;
+    /**
+     * Optional description to show in detail panels or tooltips.
+     */
+    description?: string;
+}
+
+interface DocumentTypeFileOutput {
+    selectedItems: Array<{
+        name: string;
+        title: string;
+        icon: string;
+    }>;
+    context: {
+        [key: string]: any;
+    };
+}
+interface AXMDocumentManagementDocumentTypeEntityModel extends AXPEntityModel<string> {
+    name: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    isEncrypted: boolean;
+    enableVersioning: boolean;
+    enableExpiration: boolean;
+    requiresReview: boolean;
+    reviewFirst?: boolean;
+    /** Metadata field definitions (meta-data-builder value; used by meta-data-form-editor). */
+    metaDataList?: AXMMetaDataBuilderValue;
+    type: DocumentTypeFileOutput;
+}
+
+type AXMDocumentInheritanceType = 'Extends' | 'Inherited' | 'None';
+/**
+ * Document Management Folder - Extends category substructure for consistency with platform
+ *
+ * Inherited from AXPCategoryEntity:
+ * - id, title, description?, parentId?
+ * - childrenCount (direct subfolders count)
+ * - itemsCount? (direct documents + shortcuts count)
+ * - expiredItemsCount? (documents past expirationDate in this folder subtree)
+ * - nearExpiryItemsCount? (documents in the near-expiry window in this folder subtree)
+ * - totalChildrenCount?, totalItemsCount? (optional, for analytics)
+ *
+ * Folder-specific: color, documentTypes, inherit, size, parent, folders, documents.
+ * Optional refId/refType link this folder to an entity record (e.g. for entity-scoped drive plugin).
+ */
+interface AXMDocumentManagementFolderEntityModel extends AXPEntityModel<string>, AXPCategoryEntity<string> {
+    color: string;
+    documentTypes?: AXMDocumentManagementDocumentTypeEntityModel[];
+    inherit: AXMDocumentInheritanceType;
+    size: number;
+    /**
+     * Subtree aggregate: expired documents in this folder and nested folders (denormalized).
+     * = direct expired documents + sum(child.expiredItemsCount).
+     */
+    expiredItemsCount?: number;
+    /**
+     * Subtree aggregate: near-expiry documents in this folder and nested folders (denormalized).
+     * = direct near documents + sum(child.nearExpiryItemsCount).
+     */
+    nearExpiryItemsCount?: number;
+    /** Optional: entity type (e.g. "content-management.promotion") this folder is bound to. */
+    refType?: string;
+    /** Optional: entity record id this folder is bound to. */
+    refId?: string;
+    parent?: AXMDocumentManagementFolderEntityModel;
+    folders?: AXMDocumentManagementFolderEntityModel[];
+    documents?: AXMDocumentDto[];
+    /**
+     * Optional: shortcuts that visually live in this folder and point to documents/folders elsewhere.
+     */
+    shortcuts?: AXMDocumentShortcutEntityModel[];
+}
+interface AXMDocumentManagementFolderCreateDto {
+    title: string;
+    color: string;
+    description?: string;
+    parentId?: string;
+    documentTypes?: AXMDocumentManagementDocumentTypeEntityModel[];
+    inherit: AXMDocumentInheritanceType;
+    /** Optional; when not provided, backend may set to 0 or compute. */
+    size?: number;
+    /** Optional; used for tenant-scoped folder creation. */
+    tenantId?: string;
+    /** Optional; used for user-scoped folder creation. */
+    userId?: string;
+    /** Optional; entity type (e.g. "content-management.promotion") to bind folder to. */
+    refType?: string;
+    /** Optional; entity record id to bind folder to. */
+    refId?: string;
+}
+interface AXMDocumentManagementFolderGetDto extends AXMDocumentManagementFolderEntityModel {
+    parent?: AXMDocumentManagementFolderEntityModel;
+    folders?: AXMDocumentManagementFolderEntityModel[];
+    documents?: AXMDocumentDto[];
+    shortcuts?: AXMDocumentShortcutEntityModel[];
+}
+
+export { AXMDocumentManagementCommandKeys, AXMDocumentManagementDocumentStatusValues, AXMDocumentManagementQueryKeys, AXMPermissionsKeys, AXM_DOCUMENT_EXPIRATION_NEAR_DAYS, AXM_DOCUMENT_EXPIRATION_NOTIFY_RUN_COMMAND_KEY, AXPContentDocumentsPermissionKeys, AXPDocumentManagementFeatureKeys, AXPDocumentManagementMenuKeys, AXPDocumentManagementSettings, RootConfig, addDaysToDocumentExpirationDateKey, classifyDocumentExpirationStatus, getDocumentExpirationDateKey, getDocumentExpirationQueryBoundValues, getDocumentExpirationQueryBounds, getDocumentExpirationRemainingDays, getUtcDayBoundsForDateKey, toDocumentExpirationDate, toDocumentExpirationStorageValue };
+export type { AXMDocumentDocDto, AXMDocumentDto, AXMDocumentExpirationStatus, AXMDocumentInheritanceType, AXMDocumentManagementDocumentStatus, AXMDocumentManagementDocumentTypeEntityModel, AXMDocumentManagementFolderCreateDto, AXMDocumentManagementFolderEntityModel, AXMDocumentManagementFolderGetDto, AXMDocumentShortcutEntityModel, DocumentTypeFileOutput };