@antelopejs/dms-media 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (123) hide show
  1. package/README.md +4 -3
  2. package/dist/bindings.d.ts +4 -1
  3. package/dist/bindings.js +21 -0
  4. package/dist/bindings.js.map +1 -1
  5. package/dist/db/models/index.d.ts +1 -0
  6. package/dist/db/models/index.js +1 -0
  7. package/dist/db/models/index.js.map +1 -1
  8. package/dist/db/models/mediaAssets.model.d.ts +1 -0
  9. package/dist/db/models/mediaAssets.model.js +19 -0
  10. package/dist/db/models/mediaAssets.model.js.map +1 -1
  11. package/dist/db/models/mediaDeclarations.model.d.ts +24 -0
  12. package/dist/db/models/mediaDeclarations.model.js +13 -0
  13. package/dist/db/models/mediaDeclarations.model.js.map +1 -0
  14. package/dist/db/models/mediaFolders.model.d.ts +3 -0
  15. package/dist/db/models/mediaFolders.model.js +29 -0
  16. package/dist/db/models/mediaFolders.model.js.map +1 -1
  17. package/dist/db/tables/index.d.ts +1 -0
  18. package/dist/db/tables/index.js +1 -0
  19. package/dist/db/tables/index.js.map +1 -1
  20. package/dist/db/tables/mediaDeclarations.table.d.ts +15 -0
  21. package/dist/db/tables/mediaDeclarations.table.js +65 -0
  22. package/dist/db/tables/mediaDeclarations.table.js.map +1 -0
  23. package/dist/declared/assets.d.ts +4 -0
  24. package/dist/declared/assets.js +269 -0
  25. package/dist/declared/assets.js.map +1 -0
  26. package/dist/declared/folders.d.ts +10 -0
  27. package/dist/declared/folders.js +154 -0
  28. package/dist/declared/folders.js.map +1 -0
  29. package/dist/declared/index.d.ts +5 -0
  30. package/dist/declared/index.js +22 -0
  31. package/dist/declared/index.js.map +1 -0
  32. package/dist/declared/readiness.d.ts +2 -0
  33. package/dist/declared/readiness.js +52 -0
  34. package/dist/declared/readiness.js.map +1 -0
  35. package/dist/declared/records.d.ts +46 -0
  36. package/dist/declared/records.js +94 -0
  37. package/dist/declared/records.js.map +1 -0
  38. package/dist/declared/retire.d.ts +3 -0
  39. package/dist/declared/retire.js +118 -0
  40. package/dist/declared/retire.js.map +1 -0
  41. package/dist/implementations/interface-dms-media/index.d.ts +5 -0
  42. package/dist/implementations/interface-dms-media/index.js +5 -0
  43. package/dist/implementations/interface-dms-media/index.js.map +1 -1
  44. package/dist/library/events.d.ts +2 -1
  45. package/dist/library/events.js.map +1 -1
  46. package/dist/routes/media/assets.js +19 -4
  47. package/dist/routes/media/assets.js.map +1 -1
  48. package/dist/routes/media/context.d.ts +1 -1
  49. package/dist/routes/media/context.js.map +1 -1
  50. package/dist/routes/media/dto.d.ts +1 -0
  51. package/dist/routes/media/dto.js +3 -1
  52. package/dist/routes/media/dto.js.map +1 -1
  53. package/dist/routes/media/folders.d.ts +6 -0
  54. package/dist/routes/media/folders.js +25 -13
  55. package/dist/routes/media/folders.js.map +1 -1
  56. package/dist/routes/media/upload.d.ts +1 -1
  57. package/dist/routes/media/upload.js +26 -58
  58. package/dist/routes/media/upload.js.map +1 -1
  59. package/dist/test/integration/media-declared-content.test.d.ts +1 -0
  60. package/dist/test/integration/media-declared-content.test.js +705 -0
  61. package/dist/test/integration/media-declared-content.test.js.map +1 -0
  62. package/dist/test/integration/media-declared-retire.test.d.ts +1 -0
  63. package/dist/test/integration/media-declared-retire.test.js +186 -0
  64. package/dist/test/integration/media-declared-retire.test.js.map +1 -0
  65. package/dist/test/integration/media-delivery-editing.test.js +26 -0
  66. package/dist/test/integration/media-delivery-editing.test.js.map +1 -1
  67. package/dist/test/integration/media-linked-subfolders.test.d.ts +1 -0
  68. package/dist/test/integration/media-linked-subfolders.test.js +192 -0
  69. package/dist/test/integration/media-linked-subfolders.test.js.map +1 -0
  70. package/dist/test/unit/declared.test.d.ts +1 -0
  71. package/dist/test/unit/declared.test.js +118 -0
  72. package/dist/test/unit/declared.test.js.map +1 -0
  73. package/dist/upload-checks.d.ts +18 -0
  74. package/dist/upload-checks.js +75 -0
  75. package/dist/upload-checks.js.map +1 -0
  76. package/dist/validation/declared.schema.d.ts +187 -0
  77. package/dist/validation/declared.schema.js +78 -0
  78. package/dist/validation/declared.schema.js.map +1 -0
  79. package/dist/validation/media.schema.d.ts +3 -0
  80. package/dist/validation/media.schema.js +12 -12
  81. package/dist/validation/media.schema.js.map +1 -1
  82. package/frontend-vue/app/components/dialogs/DestinationDialog.vue +1 -1
  83. package/frontend-vue/app/components/dialogs/MoveDialog.vue +2 -2
  84. package/frontend-vue/app/components/explorer/ExplorerContent.vue +1 -1
  85. package/frontend-vue/app/components/explorer/ExplorerToolbar.vue +1 -1
  86. package/frontend-vue/app/components/shared/AssetThumb.vue +3 -1
  87. package/frontend-vue/app/composables/library/explorerMenus.ts +1 -1
  88. package/frontend-vue/app/composables/library/useExplorerCommands.ts +1 -1
  89. package/frontend-vue/app/composables/library/useExplorerDrop.ts +1 -1
  90. package/frontend-vue/app/types/media.ts +3 -1
  91. package/frontend-vue/package.json +1 -1
  92. package/frontend-vue/tests/serverRender.test.ts +2 -1
  93. package/package.json +2 -2
  94. package/skills/dms-media/SKILL.md +50 -4
  95. package/src/bindings.ts +28 -0
  96. package/src/db/models/index.ts +1 -0
  97. package/src/db/models/mediaAssets.model.ts +25 -0
  98. package/src/db/models/mediaDeclarations.model.ts +19 -0
  99. package/src/db/models/mediaFolders.model.ts +44 -0
  100. package/src/db/tables/index.ts +1 -0
  101. package/src/db/tables/mediaDeclarations.table.ts +59 -0
  102. package/src/declared/assets.ts +446 -0
  103. package/src/declared/folders.ts +273 -0
  104. package/src/declared/index.ts +5 -0
  105. package/src/declared/readiness.ts +64 -0
  106. package/src/declared/records.ts +185 -0
  107. package/src/declared/retire.ts +206 -0
  108. package/src/implementations/interface-dms-media/index.ts +10 -0
  109. package/src/library/events.ts +4 -1
  110. package/src/routes/media/assets.ts +34 -5
  111. package/src/routes/media/context.ts +1 -1
  112. package/src/routes/media/dto.ts +6 -2
  113. package/src/routes/media/folders.ts +47 -21
  114. package/src/routes/media/upload.ts +50 -121
  115. package/src/test/integration/media-declared-content.test.ts +844 -0
  116. package/src/test/integration/media-declared-retire.test.ts +257 -0
  117. package/src/test/integration/media-delivery-editing.test.ts +45 -0
  118. package/src/test/integration/media-linked-subfolders.test.ts +256 -0
  119. package/src/test/unit/declared.test.ts +158 -0
  120. package/src/upload-checks.ts +126 -0
  121. package/src/validation/declared.schema.ts +104 -0
  122. package/src/validation/media.schema.ts +7 -6
  123. package/frontend-vue/pnpm-workspace.yaml +0 -2
@@ -0,0 +1,5 @@
1
+ export * from "./assets";
2
+ export * from "./folders";
3
+ export * from "./readiness";
4
+ export * from "./records";
5
+ export * from "./retire";
@@ -0,0 +1,64 @@
1
+ import { setTimeout as delay } from "node:timers/promises";
2
+ import { Schema } from "@antelopejs/interface-database";
3
+ import { TENANT_SCHEMA_NAME } from "@antelopejs/interface-dms/constants";
4
+
5
+ const POLL_INTERVAL_MS = 500;
6
+ const MAX_RETRY_DELAY_MS = 5_000;
7
+ /** How long a declaration waits for its tenant before giving up. */
8
+ const TENANT_WAIT_MS = 5 * 60_000;
9
+ /** How long a file write waits for the storage endpoint to answer. */
10
+ const STORAGE_WAIT_MS = 2 * 60_000;
11
+
12
+ const readyTenants = new Set<string>();
13
+
14
+ async function hasTenantInstance(tenantId: string): Promise<boolean> {
15
+ try {
16
+ const schema = Schema.get(TENANT_SCHEMA_NAME);
17
+ if (!schema) return false;
18
+ const instances = await schema.listInstances();
19
+ return instances.includes(tenantId);
20
+ } catch {
21
+ return false;
22
+ }
23
+ }
24
+
25
+ /**
26
+ * Waits until the tenant's tables can be queried. Polling the schema, rather
27
+ * than awaiting `Hook.DATABASE_INITIALIZED`, cannot deadlock a caller that
28
+ * declares content from its own handler of that hook: handlers run in series.
29
+ */
30
+ export async function waitForTenant(tenantId: string): Promise<void> {
31
+ if (readyTenants.has(tenantId)) return;
32
+ const deadline = Date.now() + TENANT_WAIT_MS;
33
+ while (!(await hasTenantInstance(tenantId))) {
34
+ if (Date.now() > deadline)
35
+ throw new Error(
36
+ `Media tenant '${tenantId}' was not ready after ${TENANT_WAIT_MS / 1000}s: declare content from start() or a Hook.DATABASE_INITIALIZED handler, never awaited in construct()`,
37
+ );
38
+ await delay(POLL_INTERVAL_MS);
39
+ }
40
+ readyTenants.add(tenantId);
41
+ }
42
+
43
+ /**
44
+ * Runs a storage write, retried while its endpoint does not answer: a local
45
+ * storage receives uploads on the API server, which may not listen yet when
46
+ * a module declares content at startup. Refusals are not retried.
47
+ */
48
+ export async function writeWhenReachable<T>(
49
+ write: () => Promise<T>,
50
+ ): Promise<T> {
51
+ const deadline = Date.now() + STORAGE_WAIT_MS;
52
+ let retryDelay = POLL_INTERVAL_MS;
53
+ for (;;) {
54
+ try {
55
+ return await write();
56
+ } catch (error) {
57
+ // fetch rejects with a TypeError when nothing answers.
58
+ const isUnreachable = error instanceof TypeError;
59
+ if (!isUnreachable || Date.now() > deadline) throw error;
60
+ }
61
+ await delay(retryDelay);
62
+ retryDelay = Math.min(retryDelay * 2, MAX_RETRY_DELAY_MS);
63
+ }
64
+ }
@@ -0,0 +1,185 @@
1
+ import { createHash } from "node:crypto";
2
+ import { GetModel } from "@antelopejs/interface-database-decorators";
3
+ import type { MediaDeclarationResult } from "@antelopejs/interface-dms-media";
4
+ import type { ZodError, ZodType } from "zod";
5
+ import {
6
+ MediaAssetModel,
7
+ type MediaDeclaration,
8
+ type MediaDeclarationKind,
9
+ MediaDeclarationModel,
10
+ MediaFolderModel,
11
+ } from "../db";
12
+ import type { MediaEventAuthor } from "../library/events";
13
+ import { describeDeclarationIssues } from "../validation/declared.schema";
14
+
15
+ /** Declared content is attributed to the system, not to a member. */
16
+ export const DECLARED_CONTENT_AUTHOR: MediaEventAuthor = {
17
+ _id: "dms-media:declared",
18
+ name: "System",
19
+ email: "",
20
+ };
21
+
22
+ const KIND_LABELS: Record<MediaDeclarationKind, string> = {
23
+ folder: "Media folder",
24
+ asset: "Media file",
25
+ };
26
+
27
+ /** A declaration the media module refuses, named by its kind and key. */
28
+ export class MediaDeclarationError extends Error {
29
+ constructor(kind: MediaDeclarationKind, key: string, reason: string) {
30
+ super(`${KIND_LABELS[kind]} '${key}': ${reason}`);
31
+ }
32
+ }
33
+
34
+ export interface DeclaredModels {
35
+ tenantId: string;
36
+ folderModel: MediaFolderModel;
37
+ assetModel: MediaAssetModel;
38
+ declarationModel: MediaDeclarationModel;
39
+ }
40
+
41
+ export function declaredModels(tenantId: string): DeclaredModels {
42
+ return {
43
+ tenantId,
44
+ folderModel: GetModel(MediaFolderModel, tenantId),
45
+ assetModel: GetModel(MediaAssetModel, tenantId),
46
+ declarationModel: GetModel(MediaDeclarationModel, tenantId),
47
+ };
48
+ }
49
+
50
+ /** Values a declaration compares, built with a fixed key order so equal values hash equally. */
51
+ export type HashedState = Record<string, unknown>;
52
+
53
+ export function hashState(state: HashedState): string {
54
+ return createHash("sha256").update(JSON.stringify(state)).digest("hex");
55
+ }
56
+
57
+ export function hashBytes(bytes: Uint8Array): string {
58
+ return createHash("sha256").update(bytes).digest("hex");
59
+ }
60
+
61
+ /** Validates a declaration, naming every refused field. */
62
+ export function parseDeclaration<Schema extends ZodType>(
63
+ kind: MediaDeclarationKind,
64
+ input: unknown,
65
+ schema: Schema,
66
+ ): ReturnType<Schema["parse"]> {
67
+ const parsed = schema.safeParse(input);
68
+ if (parsed.success) return parsed.data as ReturnType<Schema["parse"]>;
69
+ const key = (input as { key?: unknown } | undefined)?.key;
70
+ throw new MediaDeclarationError(
71
+ kind,
72
+ typeof key === "string" ? key : "?",
73
+ describeDeclarationIssues(parsed.error as ZodError),
74
+ );
75
+ }
76
+
77
+ const pendingDeclarations = new Map<string, Promise<unknown>>();
78
+
79
+ function lockKey(
80
+ tenantId: string,
81
+ kind: MediaDeclarationKind,
82
+ key: string,
83
+ ): string {
84
+ return JSON.stringify([tenantId, kind, key]);
85
+ }
86
+
87
+ /**
88
+ * Runs the declarations of one key one after another, so a key declared twice
89
+ * at once (a boot racing a hot reload) still creates a single row.
90
+ */
91
+ export function withDeclarationLock<T>(
92
+ tenantId: string,
93
+ kind: MediaDeclarationKind,
94
+ key: string,
95
+ work: () => Promise<T>,
96
+ ): Promise<T> {
97
+ const id = lockKey(tenantId, kind, key);
98
+ const previous = pendingDeclarations.get(id) ?? Promise.resolve();
99
+ const next = previous.catch(() => undefined).then(work);
100
+ const settled = next.catch(() => undefined);
101
+ pendingDeclarations.set(id, settled);
102
+ void settled.then(() => {
103
+ if (pendingDeclarations.get(id) === settled) pendingDeclarations.delete(id);
104
+ });
105
+ return next;
106
+ }
107
+
108
+ /** Waits for a declaration of `key` still running, such as a parent folder declared alongside. */
109
+ export async function settlePendingDeclaration(
110
+ tenantId: string,
111
+ kind: MediaDeclarationKind,
112
+ key: string,
113
+ ): Promise<void> {
114
+ await pendingDeclarations.get(lockKey(tenantId, kind, key));
115
+ }
116
+
117
+ export interface AppliedDeclaration {
118
+ kind: MediaDeclarationKind;
119
+ key: string;
120
+ targetId: string;
121
+ declaredHash: string;
122
+ appliedHash: string;
123
+ contentHash?: string;
124
+ version?: string;
125
+ }
126
+
127
+ /** Remembers what was declared and the state it left the row in. */
128
+ export async function saveDeclaration(
129
+ model: MediaDeclarationModel,
130
+ existing: MediaDeclaration | undefined,
131
+ applied: AppliedDeclaration,
132
+ ): Promise<void> {
133
+ if (existing) {
134
+ await model.update(existing._id, applied);
135
+ return;
136
+ }
137
+ await model.insert(applied);
138
+ }
139
+
140
+ interface DeletedByMember {
141
+ status: "deleted";
142
+ }
143
+
144
+ interface ChangedByMember {
145
+ status: "preserved";
146
+ id: string;
147
+ }
148
+
149
+ /** What a member did to declared content: deleted it, or changed it and so keeps it. */
150
+ export type MemberChange = DeletedByMember | ChangedByMember;
151
+
152
+ /**
153
+ * The part of the rule that needs no new declaration: a row deleted since it
154
+ * was declared stays deleted, and a row whose editable state no longer hashes
155
+ * to what the last declaration left was changed by a member and stays as they
156
+ * made it. Returns undefined when the row is still as declared.
157
+ */
158
+ export function judgeMemberChange(
159
+ record: MediaDeclaration,
160
+ row: { _id: string } | undefined,
161
+ stateHash: string | undefined,
162
+ ): MemberChange | undefined {
163
+ if (!row) return { status: "deleted" };
164
+ if (stateHash !== record.appliedHash)
165
+ return { status: "preserved", id: row._id };
166
+ return undefined;
167
+ }
168
+
169
+ /**
170
+ * The rule shared by folders and files: `judgeMemberChange`, then a
171
+ * declaration equal to the last one leaves the row unchanged. Returns
172
+ * undefined when the row may be refreshed.
173
+ */
174
+ export function judgeDeclaredRow(
175
+ record: MediaDeclaration,
176
+ row: { _id: string } | undefined,
177
+ stateHash: string | undefined,
178
+ declaredHash: string,
179
+ ): MediaDeclarationResult | undefined {
180
+ const change = judgeMemberChange(record, row, stateHash);
181
+ if (change || !row) return change;
182
+ if (record.declaredHash === declaredHash)
183
+ return { status: "unchanged", id: row._id };
184
+ return undefined;
185
+ }
@@ -0,0 +1,206 @@
1
+ import type {
2
+ MediaContentKind,
3
+ MediaDeclarationPrune,
4
+ MediaDeclarationRetirement,
5
+ MediaRetirementResult,
6
+ } from "@antelopejs/interface-dms-media";
7
+ import { cleanupAssetFiles, updateAssetMedia } from "../asset-lifecycle";
8
+ import type { MediaDeclaration, MediaFolder } from "../db";
9
+ import { recordMediaEvent } from "../library/events";
10
+ import { forgetFavorites } from "../library/favorites";
11
+ import {
12
+ declarationPruneSchema,
13
+ declarationRetirementSchema,
14
+ describeDeclarationIssues,
15
+ } from "../validation/declared.schema";
16
+ import { assetStateHash } from "./assets";
17
+ import { folderStateHash } from "./folders";
18
+ import { waitForTenant } from "./readiness";
19
+ import {
20
+ DECLARED_CONTENT_AUTHOR,
21
+ type DeclaredModels,
22
+ declaredModels,
23
+ judgeMemberChange,
24
+ parseDeclaration,
25
+ withDeclarationLock,
26
+ } from "./records";
27
+
28
+ /** A retirement's outcome before it is labelled with the kind and key. */
29
+ type RetirementOutcome = Omit<MediaRetirementResult, "kind" | "key">;
30
+
31
+ /** Deletes a declared file still as declared, the way a member's delete does. */
32
+ async function retireAsset(
33
+ models: DeclaredModels,
34
+ record: MediaDeclaration,
35
+ ): Promise<RetirementOutcome> {
36
+ const { assetModel } = models;
37
+ const stored = await assetModel.get(record.targetId);
38
+ const asset = stored && !stored.isDeleting ? stored : undefined;
39
+ const change = judgeMemberChange(
40
+ record,
41
+ asset,
42
+ asset && assetStateHash(asset),
43
+ );
44
+ if (change || !asset) return change ?? { status: "deleted" };
45
+ // Tombstoned only while untouched, so a member edit racing it wins.
46
+ const isTombstoned = await updateAssetMedia(
47
+ assetModel,
48
+ asset,
49
+ { isDeleting: true },
50
+ { preserveDetails: true },
51
+ );
52
+ if (!isTombstoned) {
53
+ const current = await assetModel.get(asset._id);
54
+ return current && !current.isDeleting
55
+ ? { status: "preserved", id: asset._id }
56
+ : { status: "deleted" };
57
+ }
58
+ await cleanupAssetFiles(assetModel, asset._id);
59
+ await forgetFavorites(models.tenantId, [asset._id]);
60
+ await recordMediaEvent(
61
+ { tenantId: models.tenantId, user: DECLARED_CONTENT_AUTHOR },
62
+ {
63
+ kind: "asset.delete",
64
+ targetName: asset.name,
65
+ folderId: asset.folderId,
66
+ assetId: asset._id,
67
+ size: asset.size,
68
+ },
69
+ );
70
+ return { status: "removed", id: asset._id };
71
+ }
72
+
73
+ async function holdsContent(
74
+ models: DeclaredModels,
75
+ folder: MediaFolder,
76
+ ): Promise<boolean> {
77
+ const [children, assets] = await Promise.all([
78
+ models.folderModel.getChildren(folder._id),
79
+ models.assetModel.getByFolder(folder._id),
80
+ ]);
81
+ return children.length > 0 || assets.length > 0;
82
+ }
83
+
84
+ /**
85
+ * Deletes a declared folder still as declared and empty. A folder holding
86
+ * anything else, members' files or folders still declared, is never deleted
87
+ * with its content: it stays, and is no longer the code's.
88
+ */
89
+ async function retireFolder(
90
+ models: DeclaredModels,
91
+ record: MediaDeclaration,
92
+ ): Promise<RetirementOutcome> {
93
+ const { folderModel } = models;
94
+ const folder = await folderModel.get(record.targetId);
95
+ const change = judgeMemberChange(
96
+ record,
97
+ folder,
98
+ folder && folderStateHash(folder),
99
+ );
100
+ if (change || !folder) return change ?? { status: "deleted" };
101
+ if (await holdsContent(models, folder))
102
+ return { status: "preserved", id: folder._id };
103
+ if (!(await folderModel.deleteDeclared(folder))) {
104
+ const current = await folderModel.get(folder._id);
105
+ return current
106
+ ? { status: "preserved", id: folder._id }
107
+ : { status: "deleted" };
108
+ }
109
+ await forgetFavorites(models.tenantId, [folder._id]);
110
+ await recordMediaEvent(
111
+ { tenantId: models.tenantId, user: DECLARED_CONTENT_AUTHOR },
112
+ {
113
+ kind: "folder.delete",
114
+ targetName: folder.name,
115
+ folderId: folder.parentId,
116
+ count: 0,
117
+ size: 0,
118
+ details: { files: 0, folders: 1 },
119
+ },
120
+ );
121
+ return { status: "removed", id: folder._id };
122
+ }
123
+
124
+ const RETIRERS: Record<
125
+ MediaContentKind,
126
+ (
127
+ models: DeclaredModels,
128
+ record: MediaDeclaration,
129
+ ) => Promise<RetirementOutcome>
130
+ > = {
131
+ asset: retireAsset,
132
+ folder: retireFolder,
133
+ };
134
+
135
+ /** Retires one declaration under its key's lock; whatever stays is the members' from now on. */
136
+ function retireKey(
137
+ models: DeclaredModels,
138
+ kind: MediaContentKind,
139
+ key: string,
140
+ ): Promise<MediaRetirementResult> {
141
+ return withDeclarationLock(models.tenantId, kind, key, async () => {
142
+ const record = await models.declarationModel.findByKey(kind, key);
143
+ if (!record) return { kind, key, status: "unknown" };
144
+ const outcome = await RETIRERS[kind](models, record);
145
+ await models.declarationModel.delete(record._id);
146
+ return { kind, key, ...outcome };
147
+ });
148
+ }
149
+
150
+ /** Implements `RetireMediaDeclaration`. */
151
+ export async function retireDeclaration(
152
+ input: MediaDeclarationRetirement,
153
+ ): Promise<MediaRetirementResult> {
154
+ const kind = (input as { kind?: unknown } | undefined)?.kind;
155
+ const retirement = parseDeclaration(
156
+ kind === "folder" ? "folder" : "asset",
157
+ input,
158
+ declarationRetirementSchema,
159
+ );
160
+ await waitForTenant(retirement.tenantId);
161
+ return retireKey(
162
+ declaredModels(retirement.tenantId),
163
+ retirement.kind,
164
+ retirement.key,
165
+ );
166
+ }
167
+
168
+ /** Files first, then folders from the deepest, so a folder is empty of its declared content when its turn comes. */
169
+ async function retirementOrder(
170
+ models: DeclaredModels,
171
+ records: MediaDeclaration[],
172
+ ): Promise<MediaDeclaration[]> {
173
+ const depths = new Map<string, number>();
174
+ for (const record of records) {
175
+ if (record.kind !== "folder") continue;
176
+ const folder = await models.folderModel.get(record.targetId);
177
+ depths.set(record._id, folder?.path.length ?? 0);
178
+ }
179
+ const assets = records.filter((record) => record.kind === "asset");
180
+ const folders = records
181
+ .filter((record) => record.kind === "folder")
182
+ .sort((a, b) => (depths.get(b._id) ?? 0) - (depths.get(a._id) ?? 0));
183
+ return [...assets, ...folders];
184
+ }
185
+
186
+ /** Implements `PruneMediaDeclarations`. */
187
+ export async function pruneDeclarations(
188
+ input: MediaDeclarationPrune,
189
+ ): Promise<MediaRetirementResult[]> {
190
+ const parsed = declarationPruneSchema.safeParse(input);
191
+ if (!parsed.success)
192
+ throw new Error(
193
+ `Media declarations prune: ${describeDeclarationIssues(parsed.error)}`,
194
+ );
195
+ const { prefix, tenantId } = parsed.data;
196
+ const keep = new Set(parsed.data.keep);
197
+ await waitForTenant(tenantId);
198
+ const models = declaredModels(tenantId);
199
+ const stale = (await models.declarationModel.getAll()).filter(
200
+ (record) => record.key.startsWith(prefix) && !keep.has(record.key),
201
+ );
202
+ const results: MediaRetirementResult[] = [];
203
+ for (const record of await retirementOrder(models, stale))
204
+ results.push(await retireKey(models, record.kind, record.key));
205
+ return results;
206
+ }
@@ -1,5 +1,11 @@
1
1
  import type { AssetBindingConfig } from "@antelopejs/interface-dms-media";
2
2
  import { addAssetBinding, removeAssetBinding } from "../../bindings";
3
+ import {
4
+ ensureDeclaredFolder,
5
+ importDeclaredAsset,
6
+ pruneDeclarations,
7
+ retireDeclaration,
8
+ } from "../../declared";
3
9
 
4
10
  export namespace internal {
5
11
  export const RegisterAssetBinding = {
@@ -10,4 +16,8 @@ export namespace internal {
10
16
  removeAssetBinding(id);
11
17
  },
12
18
  };
19
+ export const EnsureMediaFolder = ensureDeclaredFolder;
20
+ export const ImportMediaAsset = importDeclaredAsset;
21
+ export const RetireMediaDeclaration = retireDeclaration;
22
+ export const PruneMediaDeclarations = pruneDeclarations;
13
23
  }
@@ -35,9 +35,12 @@ export interface MediaEventInput {
35
35
  details?: MediaEventDetails;
36
36
  }
37
37
 
38
+ /** Who an event is attributed to: a member, or the system for declared content. */
39
+ export type MediaEventAuthor = Pick<User, "_id" | "name" | "email">;
40
+
38
41
  export interface MediaEventActor {
39
42
  tenantId: string;
40
- user: User;
43
+ user: MediaEventAuthor;
41
44
  }
42
45
 
43
46
  /** Uploads arrive in bursts: they are announced on a longer window than other writes. */
@@ -17,7 +17,7 @@ import { CreateReadUrl } from "@antelopejs/interface-file-storage";
17
17
  import { getMediaConfig } from "../../config";
18
18
  import { type MediaAsset, MediaAssetModel } from "../../db";
19
19
  import { ensureDerivative } from "../../derivatives";
20
- import type { MediaPresetConfig } from "../../presets";
20
+ import { type MediaPresetConfig, SVG_MIMETYPE } from "../../presets";
21
21
  import {
22
22
  assetVisibilitySchema,
23
23
  MEDIA_ERRORS,
@@ -38,11 +38,34 @@ const HTTP_NOT_FOUND = 404;
38
38
  const MAX_SEARCH_RESULTS = 100;
39
39
  const MAX_LISTING_RESULTS = 1000;
40
40
  const THUMB_PRESET_ID = "thumb";
41
+ const UNCROPPED_PRESET_ID = "preview";
42
+
43
+ /** The presets library thumbnails are rendered with: the square crop, and an uncropped size when configured. */
44
+ interface PreviewPresets {
45
+ thumb: MediaPresetConfig;
46
+ uncropped?: MediaPresetConfig;
47
+ }
48
+
49
+ /**
50
+ * Vectors are mostly logos and icons, often far wider than tall: the square
51
+ * crop of `thumb` cuts their ends off, so they get the uncropped `preview`
52
+ * size, which the explorer fits inside the tile.
53
+ */
54
+ function previewPresetOf(
55
+ asset: MediaAsset,
56
+ presets: PreviewPresets,
57
+ ): MediaPresetConfig {
58
+ const isVector = asset.mimetype === SVG_MIMETYPE;
59
+ const isUncropped = presets.uncropped && presets.uncropped.fit !== "cover";
60
+ return isVector && isUncropped && presets.uncropped
61
+ ? presets.uncropped
62
+ : presets.thumb;
63
+ }
41
64
 
42
65
  async function buildPreviewEntry(
43
66
  context: MediaRequestContext,
44
67
  assetId: string,
45
- preset: MediaPresetConfig,
68
+ presets: PreviewPresets,
46
69
  ): Promise<[string, string] | null> {
47
70
  const asset = await context.assetModel.get(assetId);
48
71
  if (
@@ -52,6 +75,7 @@ async function buildPreviewEntry(
52
75
  )
53
76
  return null;
54
77
  if (!asset.mimetype.startsWith("image/")) return null;
78
+ const preset = previewPresetOf(asset, presets);
55
79
  try {
56
80
  const derivativeKey = await ensureDerivative(
57
81
  context.assetModel,
@@ -111,10 +135,15 @@ export class MediaAssetsController extends MediaApiController {
111
135
  async previews(@JSONBody() body: unknown) {
112
136
  const { ids } = parseBody(body, previewIdsSchema);
113
137
  const context = await this.resolveContext();
114
- const thumbPreset = getMediaConfig().presets.get(THUMB_PRESET_ID);
115
- if (!thumbPreset) return { previews: {} };
138
+ const { presets } = getMediaConfig();
139
+ const thumb = presets.get(THUMB_PRESET_ID);
140
+ if (!thumb) return { previews: {} };
141
+ const previewPresets = {
142
+ thumb,
143
+ uncropped: presets.get(UNCROPPED_PRESET_ID),
144
+ };
116
145
  const entries = await Promise.all(
117
- ids.map((id) => buildPreviewEntry(context, id, thumbPreset)),
146
+ ids.map((id) => buildPreviewEntry(context, id, previewPresets)),
118
147
  );
119
148
  const previews = Object.fromEntries(
120
149
  entries.filter((entry): entry is [string, string] => entry !== null),
@@ -158,7 +158,7 @@ export function assertNotBound(folder: MediaFolder): void {
158
158
  }
159
159
 
160
160
  export function getDescendantFolders(
161
- context: MediaRequestContext,
161
+ context: Pick<MediaRequestContext, "folders">,
162
162
  folderId: string,
163
163
  ): MediaFolder[] {
164
164
  const descendants: MediaFolder[] = [];
@@ -1,4 +1,5 @@
1
1
  import { parseFolderAcl } from "../../acl";
2
+ import { feedingBinding, holdsSubfolders } from "../../bindings";
2
3
  import type { MediaAsset, MediaFolder } from "../../db";
3
4
  import type { AssetVisibility, FolderVisibility } from "../../types";
4
5
  import {
@@ -27,7 +28,9 @@ export interface MediaFolderDto {
27
28
  bound: boolean;
28
29
  binding: string | null;
29
30
  link: FolderLinkDto | null;
30
- /** Mimetype patterns the linked field accepts; null when unlinked or unrestricted. */
31
+ /** Whether new folders may go inside: false for a linked folder unless its binding allows subfolders. */
32
+ acceptsSubfolders: boolean;
33
+ /** Mimetype patterns the field the folder feeds accepts, itself or through a linked ancestor; null when unlinked or unrestricted. */
31
34
  accepts: string[] | null;
32
35
  visibility: FolderVisibility;
33
36
  hasOwnAcl: boolean;
@@ -78,7 +81,8 @@ export function buildFolderDto(
78
81
  bound: Boolean(folder.binding),
79
82
  binding: folder.binding ?? null,
80
83
  link: describeFolderLink(folder.binding),
81
- accepts: bindingAccepts(folder.binding),
84
+ acceptsSubfolders: holdsSubfolders(folder),
85
+ accepts: bindingAccepts(feedingBinding(folder, context.foldersById)),
82
86
  visibility: folder.visibility,
83
87
  hasOwnAcl: parseFolderAcl(folder) !== undefined,
84
88
  createdAt: folder.createdAt,