@antelopejs/interface-dms-media 0.2.2 → 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
@@ -7,7 +7,7 @@
7
7
  <a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
8
8
  <a href="https://dms.antelopejs.com/docs/modules/media/extending"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
9
9
 
10
- The AntelopeJS interface to add media library fields, and the folders bound to them, to DMS pages.
10
+ The AntelopeJS interface to add media library fields, and the folders bound to them, to DMS pages, and to ship library folders and files as code.
11
11
 
12
12
  </div>
13
13
 
@@ -17,6 +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`, called once per tenant from `Hook.TENANT_BEING_PROVISIONED`: idempotent per key, the content belongs to the members once written.
20
21
  - Keeps your module independent of the implementation, [`@antelopejs/dms-media`](https://www.npmjs.com/package/@antelopejs/dms-media).
21
22
 
22
23
  ## Install
@@ -42,11 +43,32 @@ new AssetType({
42
43
  });
43
44
  ```
44
45
 
45
- The interface also exports the option and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
46
+ Ship a folder and a file with each new tenant, from the hook the DMS fires once when the tenant is created:
47
+
48
+ ```ts
49
+ import { EnsureMediaFolder, ImportMediaAsset } from "@antelopejs/interface-dms-media";
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
+ });
62
+ });
63
+ ```
64
+
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).
66
+
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`.
46
68
 
47
69
  ## Compatibility
48
70
 
49
- The implementation is `@antelopejs/dms-media >=0.4.0`. 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:
50
72
 
51
73
  <!-- docs-compat: ./package.json#peerDependencies -->
52
74
 
@@ -54,11 +76,11 @@ The implementation is `@antelopejs/dms-media >=0.4.0`. The interface declares th
54
76
  | --- | --- |
55
77
  | `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
56
78
  | `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
57
- | `@antelopejs/interface-dms` | `>=0.7.2 <1.0.0` |
79
+ | `@antelopejs/interface-dms` | `>=0.9.0 <1.0.0` |
58
80
 
59
81
  ## Documentation
60
82
 
61
- - [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle and permission precedence
83
+ - [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle, declared content and permission precedence
62
84
  - [Extending the media module](https://dms.antelopejs.com/docs/modules/media/extending): asset fields, folder bindings, the HTTP API and delivery URLs
63
85
  - [The asset field](https://dms.antelopejs.com/docs/modules/media/usage/asset-field)
64
86
  - [Media module guide](https://dms.antelopejs.com/docs/modules/media)
@@ -1,5 +1,4 @@
1
1
  import type { ControllerClass } from "@antelopejs/interface-api";
2
- import { RegisteringProxy } from "@antelopejs/interface-core";
3
2
  import type { AclEntry } from "./acl";
4
3
  export interface AssetPermissionMapping {
5
4
  read?: string[];
@@ -16,10 +15,8 @@ export interface AssetBindingConfig {
16
15
  permissionMapping?: AssetPermissionMapping;
17
16
  permissionsFromPage?: ControllerClass;
18
17
  acl?: AclEntry[];
18
+ subfolders?: boolean;
19
19
  field?: AssetBindingField;
20
20
  }
21
- export declare namespace internal {
22
- const RegisterAssetBinding: RegisteringProxy<(id: string, config: AssetBindingConfig) => void>;
23
- }
24
21
  export declare function RegisterAssetBinding(config: AssetBindingConfig): void;
25
22
  export declare function UnregisterAssetBinding(id: string): void;
package/dist/bindings.js CHANGED
@@ -1,17 +1,12 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.internal = void 0;
4
3
  exports.RegisterAssetBinding = RegisterAssetBinding;
5
4
  exports.UnregisterAssetBinding = UnregisterAssetBinding;
6
- const interface_core_1 = require("@antelopejs/interface-core");
7
- var internal;
8
- (function (internal) {
9
- internal.RegisterAssetBinding = new interface_core_1.RegisteringProxy();
10
- })(internal || (exports.internal = internal = {}));
5
+ const internal_1 = require("./internal");
11
6
  function RegisterAssetBinding(config) {
12
- internal.RegisterAssetBinding.register(config.id, config);
7
+ internal_1.internal.RegisterAssetBinding.register(config.id, config);
13
8
  }
14
9
  function UnregisterAssetBinding(id) {
15
- internal.RegisterAssetBinding.unregister(id);
10
+ internal_1.internal.RegisterAssetBinding.unregister(id);
16
11
  }
17
12
  //# sourceMappingURL=bindings.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":";;;AAqDA,oDAEC;AAGD,wDAEC;AA3DD,+DAA8D;AAyC9D,IAAiB,QAAQ,CAIxB;AAJD,WAAiB,QAAQ;IACV,6BAAoB,GAAG,IAAI,iCAAgB,EAErD,CAAC;AACN,CAAC,EAJgB,QAAQ,wBAAR,QAAQ,QAIxB;AAOD,SAAgB,oBAAoB,CAAC,MAA0B;IAC7D,QAAQ,CAAC,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAGD,SAAgB,sBAAsB,CAAC,EAAU;IAC/C,QAAQ,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC"}
1
+ {"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":";;AAoDA,oDAEC;AAGD,wDAEC;AAzDD,yCAAsC;AAkDtC,SAAgB,oBAAoB,CAAC,MAA0B;IAC7D,mBAAQ,CAAC,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAGD,SAAgB,sBAAsB,CAAC,EAAU;IAC/C,mBAAQ,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC"}
@@ -0,0 +1,43 @@
1
+ import type { AclEntry } from "./acl";
2
+ export type MediaFolderVisibility = "private" | "public";
3
+ export interface MediaFolderDeclaration {
4
+ key: string;
5
+ name: string;
6
+ parent?: string | MediaFolderTarget;
7
+ visibility?: MediaFolderVisibility;
8
+ acl?: AclEntry[];
9
+ tenantId: string;
10
+ }
11
+ export interface DeclaredFolderTarget {
12
+ key: string;
13
+ }
14
+ export interface BoundFolderTarget {
15
+ binding: string;
16
+ }
17
+ export type MediaFolderTarget = DeclaredFolderTarget | BoundFolderTarget;
18
+ export interface MediaBytesSource {
19
+ bytes: Uint8Array;
20
+ }
21
+ export interface MediaFileSource {
22
+ filePath: string;
23
+ }
24
+ export interface MediaLazySource {
25
+ load: () => Uint8Array | Promise<Uint8Array>;
26
+ }
27
+ export type MediaAssetSource = MediaBytesSource | MediaFileSource | MediaLazySource;
28
+ export interface MediaAssetDeclaration {
29
+ key: string;
30
+ folder: MediaFolderTarget;
31
+ name: string;
32
+ mimetype: string;
33
+ source: MediaAssetSource;
34
+ alt?: string;
35
+ tenantId: string;
36
+ }
37
+ export type MediaDeclarationStatus = "created" | "kept";
38
+ export interface MediaDeclarationResult {
39
+ status: MediaDeclarationStatus;
40
+ id: string;
41
+ }
42
+ export declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
43
+ export declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
@@ -0,0 +1,12 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.EnsureMediaFolder = EnsureMediaFolder;
4
+ exports.ImportMediaAsset = ImportMediaAsset;
5
+ const internal_1 = require("./internal");
6
+ function EnsureMediaFolder(declaration) {
7
+ return internal_1.internal.EnsureMediaFolder(declaration);
8
+ }
9
+ function ImportMediaAsset(declaration) {
10
+ return internal_1.internal.ImportMediaAsset(declaration);
11
+ }
12
+ //# sourceMappingURL=content.js.map
@@ -0,0 +1 @@
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"}
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
1
  export * from "./acl";
2
2
  export * from "./asset-type";
3
3
  export * from "./bindings";
4
+ export * from "./content";
5
+ export * from "./internal";
package/dist/index.js CHANGED
@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
17
17
  __exportStar(require("./acl"), exports);
18
18
  __exportStar(require("./asset-type"), exports);
19
19
  __exportStar(require("./bindings"), exports);
20
+ __exportStar(require("./content"), exports);
21
+ __exportStar(require("./internal"), exports);
20
22
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,+CAA6B;AAC7B,6CAA2B"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,+CAA6B;AAC7B,6CAA2B;AAC3B,4CAA0B;AAC1B,6CAA2B"}
@@ -0,0 +1,8 @@
1
+ import { RegisteringProxy } from "@antelopejs/interface-core";
2
+ import type { AssetBindingConfig } from "./bindings";
3
+ import type { MediaAssetDeclaration, MediaDeclarationResult, MediaFolderDeclaration } from "./content";
4
+ export declare namespace internal {
5
+ const RegisterAssetBinding: RegisteringProxy<(id: string, config: AssetBindingConfig) => void>;
6
+ const EnsureMediaFolder: (declaration: MediaFolderDeclaration) => Promise<MediaDeclarationResult>;
7
+ const ImportMediaAsset: (declaration: MediaAssetDeclaration) => Promise<MediaDeclarationResult>;
8
+ }
@@ -0,0 +1,11 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.internal = void 0;
4
+ const interface_core_1 = require("@antelopejs/interface-core");
5
+ var internal;
6
+ (function (internal) {
7
+ internal.RegisterAssetBinding = new interface_core_1.RegisteringProxy();
8
+ internal.EnsureMediaFolder = (0, interface_core_1.InterfaceFunction)();
9
+ internal.ImportMediaAsset = (0, interface_core_1.InterfaceFunction)();
10
+ })(internal || (exports.internal = internal = {}));
11
+ //# sourceMappingURL=internal.js.map
@@ -0,0 +1 @@
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
@@ -1,11 +1,41 @@
1
1
  ---
2
2
  title: Media interface
3
- description: Asset fields, folder binding lifecycle and permission contracts for DMS consumers.
3
+ description: Asset fields, folder binding lifecycle, declared content and permission contracts for DMS consumers.
4
4
  ---
5
5
 
6
6
  # Media interface
7
7
 
8
- `@antelopejs/interface-dms-media` exports the asset field and folder binding declarations. 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).
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
+
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.
9
39
 
10
40
  ## AssetType
11
41
 
@@ -60,6 +90,7 @@ interface AssetBindingConfig {
60
90
  permissionMapping?: AssetPermissionMapping;
61
91
  permissionsFromPage?: ControllerClass;
62
92
  acl?: AclEntry[];
93
+ subfolders?: boolean;
63
94
  field?: AssetBindingField;
64
95
  }
65
96
 
@@ -71,7 +102,9 @@ All these types and functions are available from the package root. The exported
71
102
 
72
103
  Use a stable, namespaced ID such as `articles.cover`. Registrations are keyed by ID, so reusing an ID replaces its declaration rather than creating an independent binding. Registration returns synchronously; it does not await folder creation. The calling module owns the registration: unloading it releases the declaration, and reloading the implementation replays active registrations.
73
104
 
74
- The runtime provisions each tenant separately, under a private `Content` root. A new folder uses `folderName ?? id`; an existing bound folder retains its name and gets the current ACL. `UnregisterAssetBinding` removes the declaration but leaves provisioned folders and files in place. Neither function returns an upload result or a provisioning error; provisioning/storage failures occur when runtime operations ensure the tenant's folders.
105
+ The runtime provisions each tenant separately, under a private `Content` root. A new folder uses `folderName ?? id`; an existing bound folder retains its name and gets the current ACL. `UnregisterAssetBinding` removes the declaration but leaves provisioned folders and files in place.
106
+
107
+ A bound folder is locked: it cannot be renamed, moved, deleted or re-permissioned, and by default it holds no subfolders. `subfolders: true` lets it hold them, for a layout per record such as one folder per project under the field's folder. Owners then create subfolders in the library, and backend code declares them with `EnsureMediaFolder({ parent: { binding } })`; the bound folder itself stays locked. A subfolder inherits the bound folder's ACL unless it has its own, and accepts only the types the field accepts, like the bound folder. The field's picker opens on the bound folder and browses its subfolders; its upload button still targets the bound folder. Neither function returns an upload result or a provisioning error; provisioning/storage failures occur when runtime operations ensure the tenant's folders.
75
108
 
76
109
  ## Permission precedence and tenant access
77
110
 
@@ -83,24 +116,124 @@ ACL rights imply weaker rights: `manage` ⇒ `write` ⇒ `read`. A role must exp
83
116
 
84
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.
85
118
 
86
- ## Declare a field
119
+ ## EnsureMediaFolder and ImportMediaAsset
87
120
 
88
- 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.
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.
122
+
123
+ ```ts [Contract]
124
+ import type { AclEntry } from "@antelopejs/interface-dms-media";
125
+
126
+ type MediaFolderVisibility = "private" | "public";
127
+
128
+ interface MediaFolderDeclaration {
129
+ key: string;
130
+ name: string;
131
+ parent?: string | MediaFolderTarget;
132
+ visibility?: MediaFolderVisibility;
133
+ acl?: AclEntry[];
134
+ tenantId: string;
135
+ }
136
+
137
+ interface DeclaredFolderTarget { key: string; }
138
+ interface BoundFolderTarget { binding: string; }
139
+ type MediaFolderTarget = DeclaredFolderTarget | BoundFolderTarget;
140
+
141
+ interface MediaBytesSource { bytes: Uint8Array; }
142
+ interface MediaFileSource { filePath: string; }
143
+ interface MediaLazySource { load: () => Uint8Array | Promise<Uint8Array>; }
144
+ type MediaAssetSource = MediaBytesSource | MediaFileSource | MediaLazySource;
145
+
146
+ interface MediaAssetDeclaration {
147
+ key: string;
148
+ folder: MediaFolderTarget;
149
+ name: string;
150
+ mimetype: string;
151
+ source: MediaAssetSource;
152
+ alt?: string;
153
+ tenantId: string;
154
+ }
155
+
156
+ type MediaDeclarationStatus = "created" | "kept";
157
+
158
+ interface MediaDeclarationResult {
159
+ status: MediaDeclarationStatus;
160
+ id: string;
161
+ }
162
+
163
+ declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
164
+ declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
165
+ ```
166
+
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.
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).
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.
170
+ - The source is read only when the file is created: a key declared before is `kept` without reading it.
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.
172
+ - `id` in the result is the library id of the folder or file, to store in an `AssetType` value for example.
173
+
174
+ ### Written once
175
+
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:
177
+
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.
180
+
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.
182
+
183
+ ### Validation and errors
184
+
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`:
186
+
187
+ - folder names refuse `/ \ < > : " | ? *` and control characters, stay within 255 characters and must be unique among their siblings, case and Unicode form aside;
188
+ - a `parent` or `{ key }` folder must have been declared first, and not deleted since;
189
+ - a folder cannot name itself as its parent;
190
+ - a `{ binding }` folder must have been registered, and a `{ binding }` parent must allow `subfolders`;
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;
192
+ - alt text stays within 255 characters.
193
+
194
+ ### When to call
195
+
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.
197
+
198
+ ### Tenant scope and trusted backend context
199
+
200
+ `tenantId` selects the existing DMS tenant schema instance for the folders, files and declaration registry. Parent keys and bindings resolve within that tenant, and the same declaration key can be used independently in different tenants. Both functions require a nonblank explicit tenant; neither infers it from an HTTP session or a SaaS workspace context. Surrounding whitespace is trimmed.
201
+
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`.
89
203
 
90
204
  ```ts docs-check
91
- import { AssetType } from "@antelopejs/interface-dms-media";
205
+ import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
206
+ import {
207
+ EnsureMediaFolder,
208
+ ImportMediaAsset,
209
+ type MediaDeclarationResult,
210
+ } from "@antelopejs/interface-dms-media";
211
+
212
+ async function declareProcedures(tenantId: string, pdf: Uint8Array): Promise<MediaDeclarationResult[]> {
213
+ const root = await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
214
+ const safety = await EnsureMediaFolder({
215
+ tenantId,
216
+ key: "helio.procedures.safety",
217
+ name: "Safety",
218
+ parent: "helio.procedures",
219
+ acl: [
220
+ { subject: { kind: "permission", id: "projects.page" }, rights: ["read"] },
221
+ ],
222
+ });
223
+ const file = await ImportMediaAsset({
224
+ tenantId,
225
+ key: "helio.procedures.safety.roof",
226
+ folder: { key: "helio.procedures.safety" },
227
+ name: "Roof safety checklist.pdf",
228
+ mimetype: "application/pdf",
229
+ source: { bytes: pdf },
230
+ });
231
+ return [root, safety, file];
232
+ }
92
233
 
93
- export const articleImages = new AssetType({
94
- multiple: true,
95
- max: 4,
96
- mimetypes: ["image/*"],
97
- binding: {
98
- id: "articles.images",
99
- folderName: "Article images",
100
- permissionMapping: {
101
- read: ["articles.page"],
102
- write: ["articles.page.table.edit"],
103
- },
104
- },
105
- });
234
+ export function construct(pdf: Uint8Array): void {
235
+ RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
236
+ await declareProcedures(tenantId, pdf);
237
+ });
238
+ }
106
239
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-dms-media",
3
- "version": "0.2.2",
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": {}