@antelopejs/interface-dms-media 0.3.0 → 0.3.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.
package/README.md CHANGED
@@ -17,7 +17,7 @@ The AntelopeJS interface to add media library fields, and the folders bound to t
17
17
  - Binds a field to a folder provisioned under the `Content` root of each tenant: `RegisterAssetBinding` and `UnregisterAssetBinding`, or `new AssetType({ binding })`.
18
18
  - Derives the folder's rights from a page (`permissionsFromPage`), a `permissionMapping` or an explicit `acl`.
19
19
  - Replays bindings to every new generation of the implementation, so either side can hot reload.
20
- - Ships folders and files from backend code with `EnsureMediaFolder` and `ImportMediaAsset`: idempotent per key, they never undo what members changed since. `RetireMediaDeclaration` and `PruneMediaDeclarations` take back what the code stopped declaring, unless members changed it.
20
+ - Ships folders and files from backend code with `EnsureMediaFolder` and `ImportMediaAsset`, called once per tenant from `Hook.TENANT_BEING_PROVISIONED`: idempotent per key, the content belongs to the members once written.
21
21
  - Keeps your module independent of the implementation, [`@antelopejs/dms-media`](https://www.npmjs.com/package/@antelopejs/dms-media).
22
22
 
23
23
  ## Install
@@ -43,31 +43,32 @@ new AssetType({
43
43
  });
44
44
  ```
45
45
 
46
- Ship a folder and a file for an explicitly selected tenant. This example intentionally selects the default tenant; for SaaS use the trusted tenant from your application's durable `created` consumer, not a process-global implicit fallback:
46
+ Ship a folder and a file with each new tenant, from the hook the DMS fires once when the tenant is created:
47
47
 
48
48
  ```ts
49
49
  import { EnsureMediaFolder, ImportMediaAsset } from "@antelopejs/interface-dms-media";
50
- import { DEFAULT_TENANT_ID } from "@antelopejs/interface-dms/constants";
51
-
52
- const tenantId = DEFAULT_TENANT_ID;
53
- await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
54
- await ImportMediaAsset({
55
- tenantId,
56
- key: "helio.procedures.roof",
57
- folder: { key: "helio.procedures" },
58
- name: "Roof safety checklist.pdf",
59
- mimetype: "application/pdf",
60
- source: { filePath: "/srv/content/roof-safety-checklist.pdf" },
50
+ import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
51
+
52
+ RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
53
+ await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
54
+ await ImportMediaAsset({
55
+ tenantId,
56
+ key: "helio.procedures.roof",
57
+ folder: { key: "helio.procedures" },
58
+ name: "Roof safety checklist.pdf",
59
+ mimetype: "application/pdf",
60
+ source: { filePath: "/srv/content/roof-safety-checklist.pdf" },
61
+ });
61
62
  });
62
63
  ```
63
64
 
64
- Both declarations require `tenantId` in TypeScript and reject missing, empty or whitespace-only values at runtime before writes. Existing users of these new APIs must pass it explicitly; older media APIs are unchanged. A tenant id does not establish authorization or completed provisioning. See the [application-owned lifecycle and backfill guidance](./docs/1.index.md#new-saas-tenants-application-owned-durable-lifecycle) for at-least-once delivery, durable receipts and deployment refreshes.
65
+ Both declarations require `tenantId` in TypeScript and reject missing, empty or whitespace-only values at runtime before writes. Existing users of these new APIs must pass it explicitly; older media APIs are unchanged. Call them from a `Hook.TENANT_BEING_PROVISIONED` handler: see [When to call](./docs/1.index.md#when-to-call).
65
66
 
66
- The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `MediaAssetDeclaration`, `MediaFolderTarget`, `MediaAssetSource`, `MediaLazySource`, `MediaDeclarationResult`, `MediaDeclarationStatus`, `MediaContentKind`, `MediaDeclarationRetirement`, `MediaDeclarationPrune`, `MediaRetirementResult`, `MediaRetirementStatus`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
67
+ The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `MediaAssetDeclaration`, `MediaFolderTarget`, `MediaAssetSource`, `MediaLazySource`, `MediaDeclarationResult`, `MediaDeclarationStatus`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
67
68
 
68
69
  ## Compatibility
69
70
 
70
- The implementation is `@antelopejs/dms-media >=0.4.0`; `EnsureMediaFolder` and `ImportMediaAsset` need the first `@antelopejs/dms-media` release built on this interface's 0.3 line. The interface declares these peer dependencies:
71
+ The 0.3 interface line requires `@antelopejs/dms-media >=0.5.0` for `EnsureMediaFolder` and `ImportMediaAsset`. Media 0.4 uses the 0.2 interface line. The interface declares these peer dependencies:
71
72
 
72
73
  <!-- docs-compat: ./package.json#peerDependencies -->
73
74
 
@@ -75,7 +76,7 @@ The implementation is `@antelopejs/dms-media >=0.4.0`; `EnsureMediaFolder` and `
75
76
  | --- | --- |
76
77
  | `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
77
78
  | `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
78
- | `@antelopejs/interface-dms` | `>=0.7.2 <1.0.0` |
79
+ | `@antelopejs/interface-dms` | `>=0.9.0 <1.0.0` |
79
80
 
80
81
  ## Documentation
81
82
 
package/dist/content.d.ts CHANGED
@@ -31,34 +31,13 @@ export interface MediaAssetDeclaration {
31
31
  name: string;
32
32
  mimetype: string;
33
33
  source: MediaAssetSource;
34
- version?: string;
35
34
  alt?: string;
36
35
  tenantId: string;
37
36
  }
38
- export type MediaDeclarationStatus = "created" | "updated" | "unchanged" | "preserved" | "deleted";
37
+ export type MediaDeclarationStatus = "created" | "kept";
39
38
  export interface MediaDeclarationResult {
40
39
  status: MediaDeclarationStatus;
41
- id?: string;
40
+ id: string;
42
41
  }
43
42
  export declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
44
43
  export declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
45
- export type MediaContentKind = "folder" | "asset";
46
- export interface MediaDeclarationRetirement {
47
- kind: MediaContentKind;
48
- key: string;
49
- tenantId: string;
50
- }
51
- export interface MediaDeclarationPrune {
52
- prefix: string;
53
- keep: string[];
54
- tenantId: string;
55
- }
56
- export type MediaRetirementStatus = "removed" | "preserved" | "deleted" | "unknown";
57
- export interface MediaRetirementResult {
58
- kind: MediaContentKind;
59
- key: string;
60
- status: MediaRetirementStatus;
61
- id?: string;
62
- }
63
- export declare function RetireMediaDeclaration(retirement: MediaDeclarationRetirement): Promise<MediaRetirementResult>;
64
- export declare function PruneMediaDeclarations(prune: MediaDeclarationPrune): Promise<MediaRetirementResult[]>;
package/dist/content.js CHANGED
@@ -2,8 +2,6 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.EnsureMediaFolder = EnsureMediaFolder;
4
4
  exports.ImportMediaAsset = ImportMediaAsset;
5
- exports.RetireMediaDeclaration = RetireMediaDeclaration;
6
- exports.PruneMediaDeclarations = PruneMediaDeclarations;
7
5
  const internal_1 = require("./internal");
8
6
  function EnsureMediaFolder(declaration) {
9
7
  return internal_1.internal.EnsureMediaFolder(declaration);
@@ -11,10 +9,4 @@ function EnsureMediaFolder(declaration) {
11
9
  function ImportMediaAsset(declaration) {
12
10
  return internal_1.internal.ImportMediaAsset(declaration);
13
11
  }
14
- function RetireMediaDeclaration(retirement) {
15
- return internal_1.internal.RetireMediaDeclaration(retirement);
16
- }
17
- function PruneMediaDeclarations(prune) {
18
- return internal_1.internal.PruneMediaDeclarations(prune);
19
- }
20
12
  //# sourceMappingURL=content.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":";;AA2HA,8CAIC;AAkBD,4CAIC;AA+DD,wDAIC;AASD,wDAIC;AApOD,yCAAsC;AA0HtC,SAAgB,iBAAiB,CAC/B,WAAmC;IAEnC,OAAO,mBAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AAkBD,SAAgB,gBAAgB,CAC9B,WAAkC;IAElC,OAAO,mBAAQ,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC;AA+DD,SAAgB,sBAAsB,CACpC,UAAsC;IAEtC,OAAO,mBAAQ,CAAC,sBAAsB,CAAC,UAAU,CAAC,CAAC;AACrD,CAAC;AASD,SAAgB,sBAAsB,CACpC,KAA4B;IAE5B,OAAO,mBAAQ,CAAC,sBAAsB,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}
1
+ {"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":";;AAuGA,8CAIC;AAaD,4CAIC;AA3HD,yCAAsC;AAsGtC,SAAgB,iBAAiB,CAC/B,WAAmC;IAEnC,OAAO,mBAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AAaD,SAAgB,gBAAgB,CAC9B,WAAkC;IAElC,OAAO,mBAAQ,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC"}
@@ -1,10 +1,8 @@
1
1
  import { RegisteringProxy } from "@antelopejs/interface-core";
2
2
  import type { AssetBindingConfig } from "./bindings";
3
- import type { MediaAssetDeclaration, MediaDeclarationPrune, MediaDeclarationResult, MediaDeclarationRetirement, MediaFolderDeclaration, MediaRetirementResult } from "./content";
3
+ import type { MediaAssetDeclaration, MediaDeclarationResult, MediaFolderDeclaration } from "./content";
4
4
  export declare namespace internal {
5
5
  const RegisterAssetBinding: RegisteringProxy<(id: string, config: AssetBindingConfig) => void>;
6
6
  const EnsureMediaFolder: (declaration: MediaFolderDeclaration) => Promise<MediaDeclarationResult>;
7
7
  const ImportMediaAsset: (declaration: MediaAssetDeclaration) => Promise<MediaDeclarationResult>;
8
- const RetireMediaDeclaration: (retirement: MediaDeclarationRetirement) => Promise<MediaRetirementResult>;
9
- const PruneMediaDeclarations: (prune: MediaDeclarationPrune) => Promise<MediaRetirementResult[]>;
10
8
  }
package/dist/internal.js CHANGED
@@ -7,7 +7,5 @@ var internal;
7
7
  internal.RegisterAssetBinding = new interface_core_1.RegisteringProxy();
8
8
  internal.EnsureMediaFolder = (0, interface_core_1.InterfaceFunction)();
9
9
  internal.ImportMediaAsset = (0, interface_core_1.InterfaceFunction)();
10
- internal.RetireMediaDeclaration = (0, interface_core_1.InterfaceFunction)();
11
- internal.PruneMediaDeclarations = (0, interface_core_1.InterfaceFunction)();
12
10
  })(internal || (exports.internal = internal = {}));
13
11
  //# sourceMappingURL=internal.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":";;;AAAA,+DAGoC;AAcpC,IAAiB,QAAQ,CAoBxB;AApBD,WAAiB,QAAQ;IACV,6BAAoB,GAAG,IAAI,iCAAgB,EAErD,CAAC;IACS,0BAAiB,GAC5B,IAAA,kCAAiB,GAEd,CAAC;IACO,yBAAgB,GAC3B,IAAA,kCAAiB,GAEd,CAAC;IACO,+BAAsB,GACjC,IAAA,kCAAiB,GAEd,CAAC;IACO,+BAAsB,GACjC,IAAA,kCAAiB,GAEd,CAAC;AACR,CAAC,EApBgB,QAAQ,wBAAR,QAAQ,QAoBxB"}
1
+ {"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":";;;AAAA,+DAGoC;AAWpC,IAAiB,QAAQ,CAYxB;AAZD,WAAiB,QAAQ;IACV,6BAAoB,GAAG,IAAI,iCAAgB,EAErD,CAAC;IACS,0BAAiB,GAC5B,IAAA,kCAAiB,GAEd,CAAC;IACO,yBAAgB,GAC3B,IAAA,kCAAiB,GAEd,CAAC;AACR,CAAC,EAZgB,QAAQ,wBAAR,QAAQ,QAYxB"}
package/docs/1.index.md CHANGED
@@ -7,6 +7,36 @@ description: Asset fields, folder binding lifecycle, declared content and permis
7
7
 
8
8
  `@antelopejs/interface-dms-media` exports the asset field and folder binding declarations, and the functions that ship library folders and files as code. Load the Media runtime for the picker, uploads and provisioning. HTTP routes and delivery URLs remain in the [runtime guide](/docs/modules/media/extending#http-surface).
9
9
 
10
+ ## Declare a field
11
+
12
+ This field stores up to four asset IDs and registers a tenant-local upload folder.
13
+ Place it in a DMS form. The permission IDs are application-defined and must be
14
+ granted by the project's role configuration.
15
+
16
+ ```ts docs-check
17
+ import { AssetType } from "@antelopejs/interface-dms-media";
18
+
19
+ export const articleImages = new AssetType({
20
+ multiple: true,
21
+ max: 4,
22
+ mimetypes: ["image/*"],
23
+ binding: {
24
+ id: "articles.images",
25
+ folderName: "Article images",
26
+ permissionMapping: {
27
+ read: ["articles.page"],
28
+ write: ["articles.page.table.edit"],
29
+ },
30
+ },
31
+ });
32
+ ```
33
+
34
+ Selecting two images produces a value such as `["asset-a", "asset-b"]`, not two
35
+ URLs. An empty selection is `[]`. A fifth ID fails the field's shape validation,
36
+ but an unknown nonempty ID does not: the consuming write path still needs to
37
+ check asset existence, tenant ownership and type. See the
38
+ [picker example](/docs/modules/media/extending#add-an-asset-field) for the UI.
39
+
10
40
  ## AssetType
11
41
 
12
42
  ```ts [Contract]
@@ -86,28 +116,6 @@ ACL rights imply weaker rights: `manage` ⇒ `write` ⇒ `read`. A role must exp
86
116
 
87
117
  Owners hold every folder right. Uploading and changing files require folder `write`; folder structure changes require `manage`. File and folder visibility changes stay owner-only. A writable linked folder lets a member modify its files regardless of who uploaded them. The default root ACL grants no member access; configure `rootAcl` deliberately because its grants can open the rest of the library.
88
118
 
89
- ## Declare a field
90
-
91
- This field stores up to four asset IDs and registers a tenant-local upload folder. The permission IDs are application-defined and must be granted by the project's role configuration.
92
-
93
- ```ts docs-check
94
- import { AssetType } from "@antelopejs/interface-dms-media";
95
-
96
- export const articleImages = new AssetType({
97
- multiple: true,
98
- max: 4,
99
- mimetypes: ["image/*"],
100
- binding: {
101
- id: "articles.images",
102
- folderName: "Article images",
103
- permissionMapping: {
104
- read: ["articles.page"],
105
- write: ["articles.page.table.edit"],
106
- },
107
- },
108
- });
109
- ```
110
-
111
119
  ## EnsureMediaFolder and ImportMediaAsset
112
120
 
113
121
  A project ships media content (templates, procedures, demo pictures) from its backend code with these two functions. The Media runtime creates the content itself: it validates it with the dashboard's rules, writes the bytes to its configured file storage, computes image dimensions and records the creation in the library activity. Never write the runtime's tables yourself.
@@ -141,98 +149,51 @@ interface MediaAssetDeclaration {
141
149
  name: string;
142
150
  mimetype: string;
143
151
  source: MediaAssetSource;
144
- version?: string;
145
152
  alt?: string;
146
153
  tenantId: string;
147
154
  }
148
155
 
149
- type MediaDeclarationStatus = "created" | "updated" | "unchanged" | "preserved" | "deleted";
156
+ type MediaDeclarationStatus = "created" | "kept";
150
157
 
151
158
  interface MediaDeclarationResult {
152
159
  status: MediaDeclarationStatus;
153
- id?: string;
160
+ id: string;
154
161
  }
155
162
 
156
163
  declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
157
164
  declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
158
165
  ```
159
166
 
160
- - `key` is a stable, namespaced id you choose, such as `helio.procedures`. Declarations are keyed by tenant, kind and key: calling them on every boot or hot reload creates each folder and file once.
167
+ - `key` is a stable, namespaced id you choose, such as `helio.procedures`. Declarations are keyed by tenant, kind and key: each folder and file is created once.
161
168
  - A folder goes at the library root, under the declared folder named by `parent` (its key, or `{ key }`), or under the folder bound to an asset field (`{ binding }`) when that binding sets `subfolders: true`. `visibility` defaults to `private`; without `acl` the folder inherits its parent's ACL (the `rootAcl` at the root).
162
169
  - A file goes into a declared folder (`{ key }`) or into the folder bound to an asset field (`{ binding }`, the `id` given to `AssetType` or `RegisterAssetBinding`, which the runtime provisions first). `source` is the content in memory (`bytes`), a path on the backend's file system (`filePath`) or a function producing it (`load`). `name` is the file name shown in the library, extension included.
163
- - The source is read only when a decision needs the bytes: never for a file a member changed or deleted, and not for an unchanged file whose `version` matches. `version` is an opaque string you change whenever the bytes change, such as a hash of what they are generated from: while it equals the version of the key's last declaration, the runtime reuses the content hash it recorded then instead of reading `source`. Pair it with `load` to skip generating content on every boot or hot reload. A new version whose bytes turn out identical is `unchanged` and remembered, so the next call does not read them again. Without `version`, every call reads the source to compare it.
170
+ - The source is read only when the file is created: a key declared before is `kept` without reading it.
164
171
  - `tenantId` is required in TypeScript and at runtime. Omission, an empty string or whitespace-only input rejects before database writes or source reads. There is no default fallback; passing `DEFAULT_TENANT_ID` explicitly remains valid. Existing callers of these new APIs must add their trusted tenant id; older media APIs are unchanged.
165
172
  - `id` in the result is the library id of the folder or file, to store in an `AssetType` value for example.
166
173
 
167
- ### The refresh rule
168
-
169
- For each key, the runtime remembers the last declaration it applied and a hash of the row's editable state right after applying it: a folder's name, parent, visibility and ACL; a file's name, folder, alt text, visibility and stored content. On each call:
170
-
171
- 1. No row was ever declared for the key: the folder or file is created (`created`).
172
- 2. The row was deleted since, by a member or with its folder: it is not created again (`deleted`). A file whose declared folder was deleted before it was ever imported is `deleted` too.
173
- 3. The row's current state no longer hashes to what the last declaration left: someone changed it, so it is left as is, whatever the new declaration says (`preserved`).
174
- 4. The declaration equals the last one applied: nothing is written (`unchanged`). A file's content counts as equal when its bytes hash the same, or when its `version` equals the last one without the bytes being read.
175
- 5. Otherwise the row still holds exactly what was declared, and is refreshed to the new declaration (`updated`): a new name, place, visibility, ACL or alt text, or new bytes, which replace the stored file and its generated sizes the way an image edit does.
176
-
177
- Refreshes compare the observed editable state in the database write itself. A member edit that wins that race is `preserved`, or `deleted` if the row was removed. File metadata and replacement bytes are published together; a rejected replacement does not become the live file. An edit made after a successful refresh remains a member edit on the next declaration, rather than becoming the declaration's baseline.
178
-
179
- Only creations are recorded in the activity, attributed to `System`, as `folder.create` and `asset.upload`; refreshes are not.
180
-
181
- The comparison is of state, not edit history: restoring exactly the last applied state makes the row eligible for refresh again. Removing a declaration from code does not delete its row: retire it (below). Use one declaration writer per tenant and key: the queue is process-local, and creation, storage, activity and declaration bookkeeping are not a single transaction. Folder moves and descendant path rewrites are also separate writes; this API is not a transaction across a whole folder tree.
182
-
183
- ### Retiring content the code no longer declares
184
-
185
- ```ts [Contract]
186
- type MediaContentKind = "folder" | "asset";
187
-
188
- interface MediaDeclarationRetirement {
189
- kind: MediaContentKind;
190
- key: string;
191
- tenantId: string;
192
- }
193
-
194
- interface MediaDeclarationPrune {
195
- prefix: string;
196
- keep: string[];
197
- tenantId: string;
198
- }
199
-
200
- type MediaRetirementStatus = "removed" | "preserved" | "deleted" | "unknown";
201
-
202
- interface MediaRetirementResult {
203
- kind: MediaContentKind;
204
- key: string;
205
- status: MediaRetirementStatus;
206
- id?: string;
207
- }
208
-
209
- declare function RetireMediaDeclaration(retirement: MediaDeclarationRetirement): Promise<MediaRetirementResult>;
210
- declare function PruneMediaDeclarations(prune: MediaDeclarationPrune): Promise<MediaRetirementResult[]>;
211
- ```
174
+ ### Written once
212
175
 
213
- `RetireMediaDeclaration` takes back one declaration, by the kind and key it was made with. `PruneMediaDeclarations` retires every declaration whose key starts with `prefix` and is not listed in `keep` (keys of folders and files alike): call it after the declarations of the current code, with the keys they used, and whatever an earlier version shipped and this one dropped is taken back. It retires files first, then folders from the deepest, and returns one result per retired declaration. The rule follows the refresh rule:
176
+ Declared content is written once, when the tenant is provisioned (see [When to call](#when-to-call)), and belongs to the tenant's members from then on. Nothing replays a declaration on a later boot, so nothing compares the library with the code nor takes content back:
214
177
 
215
- 1. Nothing is declared under the kind and key, never or no longer: nothing happens (`unknown`).
216
- 2. The row was deleted since: `deleted`.
217
- 3. The row's state no longer hashes to what the last declaration left, or the folder holds anything (members' files and folders, or declared content not retired yet): it stays as it is (`preserved`).
218
- 4. Otherwise the row still holds exactly what was declared: it is deleted like a member's delete, its stored files with it, and recorded as `asset.delete` or `folder.delete` by `System` (`removed`).
178
+ 1. No row was declared for the key in this tenant: the folder or file is created (`created`), and the runtime remembers its id under the key, so a later declaration can name it as a `parent` or `{ key }` folder.
179
+ 2. The key was declared before, by an earlier or retried provisioning: nothing is written and the source is not read (`kept`). The result carries the id of the row created then.
219
180
 
220
- In every case but `unknown` the declaration is forgotten: a preserved folder or file now belongs to the members, and declaring the key again creates new content. Retiring is never a cascade: a folder is removed only once empty, so keep in `keep` the folders the code still imports into. The delete is conditional on the observed state in the database write, so a member edit racing it wins. Only one module should own a prefix; `prefix` is required and nonblank.
181
+ Only creations are recorded in the activity, attributed to `System`, as `folder.create` and `asset.upload`. Use one declaration writer per tenant and key: the queue is process-local, and creation, storage, activity and declaration bookkeeping are not a single transaction.
221
182
 
222
183
  ### Validation and errors
223
184
 
224
185
  Declarations follow the dashboard's rules and reject with an error naming the kind, the key and the reason, such as `Media folder 'helio.procedures': a folder named 'Procedures' already exists there`:
225
186
 
226
187
  - folder names refuse `/ \ < > : " | ? *` and control characters, stay within 255 characters and must be unique among their siblings, case and Unicode form aside;
227
- - a `parent` or `{ key }` folder must have been declared first;
228
- - a folder cannot name itself as its parent or move under one of its descendants; these declarations reject without changing the hierarchy;
188
+ - a `parent` or `{ key }` folder must have been declared first, and not deleted since;
189
+ - a folder cannot name itself as its parent;
229
190
  - a `{ binding }` folder must have been registered, and a `{ binding }` parent must allow `subfolders`;
230
191
  - a file must be of an allowed type (`allowedMimetypes`, never HTML, XHTML or PHP), of a type the bound field accepts, within the storage quota and the 500 MB upload limit, and a decodable image when its mimetype says so; the stored mimetype is the decoded format's, as for an upload;
231
192
  - alt text stays within 255 characters.
232
193
 
233
- ### Calling them at startup
194
+ ### When to call
234
195
 
235
- A call made before the runtime is loaded is queued by the interface, and the runtime waits for the explicitly selected tenant's tables (up to 5 minutes) and for the file storage to answer (up to 2 minutes; `@antelopejs/file-storage-local` receives files on the API server, which may not listen yet). This is technical readiness, not proof that SaaS provisioning is committed. Do not await them in `construct()`: the database only becomes ready once every module is constructed. Declare a parent before its children and a folder before its files, awaiting each call. Reserve `start()` for registration or explicitly scoped global work; use the application lifecycle below for new SaaS tenants.
196
+ Call them from a `Hook.TENANT_BEING_PROVISIONED` handler registered in your module's `construct()`. The DMS fires it once per tenant, when the tenant is created: for the `default` tenant on the DMS start that creates it, once every `Hook.DATABASE_INITIALIZED` handler has finished, and for each workspace a SaaS module creates. The tenant's tables exist by then, and files are written through the storage's `WriteFile`, so nothing waits. Never call them from `start()` or `DATABASE_INITIALIZED`, which run on every boot. Declare a parent before its children and a folder before its files, awaiting each call.
236
197
 
237
198
  ### Tenant scope and trusted backend context
238
199
 
@@ -240,16 +201,15 @@ A call made before the runtime is loaded is queued by the interface, and the run
240
201
 
241
202
  These are trusted backend APIs, not authorization endpoints. They need the media implementation, the selected tenant's database instance and reachable file storage; they do not require a signed-in user, create a workspace, check payment status or decide when workspace provisioning is committed. Storage paths include the tenant id, but the storage backend and upload policy remain module configuration. Events are attributed to `System`.
242
203
 
243
- `start()` runs for the process, not once per tenant. The routine below receives its trusted tenant from the application; it does not initialize every existing or future workspace. A required tenant id proves neither authorization nor completed provisioning.
244
-
245
204
  ```ts docs-check
205
+ import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
246
206
  import {
247
207
  EnsureMediaFolder,
248
208
  ImportMediaAsset,
249
209
  type MediaDeclarationResult,
250
210
  } from "@antelopejs/interface-dms-media";
251
211
 
252
- export async function declareProcedures(tenantId: string, pdf: Uint8Array): Promise<MediaDeclarationResult[]> {
212
+ async function declareProcedures(tenantId: string, pdf: Uint8Array): Promise<MediaDeclarationResult[]> {
253
213
  const root = await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
254
214
  const safety = await EnsureMediaFolder({
255
215
  tenantId,
@@ -270,38 +230,10 @@ export async function declareProcedures(tenantId: string, pdf: Uint8Array): Prom
270
230
  });
271
231
  return [root, safety, file];
272
232
  }
273
- ```
274
233
 
275
- ### New SaaS tenants: application-owned durable lifecycle
276
-
277
- For resources needed after payment, register an application consumer through `RegisterWorkspaceLifecycleConsumer` from `@antelopejs/interface-dms-saas/workspace-lifecycle`, with `transitions: ["created"]`. Register it synchronously in `construct()` before startup reconciliation begins: module `start()` functions may run concurrently. Do not await media declarations in `construct()`; they run later inside `consume`. The existing SaaS `created` transition follows preparation and payment and is delivered at least once. Media neither depends on SaaS at runtime nor registers this consumer itself.
278
-
279
- The following is an **integration skeleton**, not a runnable persistence implementation. Replace the fail-closed body with the application's durable operation handling before enabling it:
280
-
281
- ```ts
282
- import { RegisterWorkspaceLifecycleConsumer } from "@antelopejs/interface-dms-saas/workspace-lifecycle";
283
-
284
- export function construct(): void {
285
- RegisterWorkspaceLifecycleConsumer({
286
- name: "app.media-content",
287
- transitions: ["created"],
288
- async consume({ tenantId, operationId }) {
289
- // Deduplicate operationId in durable application storage, scoped to this
290
- // consumer and tenantId; replay the stored receipt for a completed operation.
291
- // Otherwise call declareProcedures(tenantId, pdf), inspecting its results.
292
- // Durably link the resulting resources to the operation before returning
293
- // { receiptId: persistedReceiptId }. Recover incomplete attempts on retry.
294
- // Concurrent deliveries need application-level serialization/uniqueness.
295
- throw new Error(`Implement durable receipt handling for ${tenantId}/${operationId}`);
296
- },
234
+ export function construct(pdf: Uint8Array): void {
235
+ RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
236
+ await declareProcedures(tenantId, pdf);
297
237
  });
298
238
  }
299
239
  ```
300
-
301
- The application supplies the content and durable storage, handles `preserved` and `deleted` according to its business contract, and returns `{ receiptId, ... }` only after resource links and completion are durable. Retain the declaration results needed to link resources; `deleted` has no resource id. Do not acknowledge errors, or mint a receipt before linking resources. Idempotent declarations do not make every effect exactly-once: database, storage, activity and declaration records are separate writes, and media's key queue is process-local. Recovery and coordination across workers remain application responsibilities.
302
-
303
- `TENANT_BEING_PROVISIONED` is different: it runs before payment, is awaited in series, can reject tenant creation, and has neither automatic hook replay nor automatic compensation for consumer effects. It is not a substitute for durable `created`. These recommendations do not change the application's provisioning policy or move existing hooks.
304
-
305
- ### Existing tenants: deployment refresh and backfill
306
-
307
- A new-tenant `created` consumer does not update all existing tenants when content changes at deployment. Run a separately controlled refresh/backfill over the application's trusted tenant inventory. For each tenant, check `IsWorkspaceProvisioningCommitted(tenantId)` through the SaaS interface before declaring content. If the result is false, skip it; if inventory or commitment lookup fails, stop or retry without writing (fail closed). Never replace a missing tenant with `DEFAULT_TENANT_ID`. Coordinate this writer with lifecycle deliveries, use stable keys, and retain progress/errors for retries. An explicitly selected default tenant remains suitable for intentional single-tenant/global content, not as an implicit SaaS fallback.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-dms-media",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "AntelopeJS interface for the DMS media module: declare asset fields and the media folders bound to them from any module",
5
5
  "keywords": [
6
6
  "antelopejs",
@@ -61,7 +61,7 @@
61
61
  "devDependencies": {
62
62
  "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
63
63
  "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
64
- "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
64
+ "@antelopejs/interface-dms": ">=0.9.0 <1.0.0",
65
65
  "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
66
66
  "@types/node": "^24.0.0",
67
67
  "knip": "^6.34.0",
@@ -76,7 +76,7 @@
76
76
  "peerDependencies": {
77
77
  "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
78
78
  "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
79
- "@antelopejs/interface-dms": ">=0.7.2 <1.0.0"
79
+ "@antelopejs/interface-dms": ">=0.9.0 <1.0.0"
80
80
  },
81
81
  "packageManager": "pnpm@10.2.0",
82
82
  "antelopeJs": {}