@antelopejs/interface-dms-media 0.3.1 → 0.3.3

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
@@ -1,11 +1,11 @@
1
1
  <div align="center">
2
2
 
3
- # @antelopejs/interface-dms-media
3
+ # `@antelopejs/interface-dms-media`
4
4
 
5
- <a href="https://www.npmjs.com/package/@antelopejs/interface-dms-media"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-media?style=for-the-badge&labelColor=000000&color=000000"></a>
6
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-dms-media?style=for-the-badge&labelColor=000000&color=000000"></a>
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
- <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>
5
+ <a href="https://www.npmjs.com/package/@antelopejs/interface-dms-media"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-media?style=for-the-badge&labelColor=000000&color=000000"></a>
6
+ <a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-dms-media?style=for-the-badge&labelColor=000000&color=000000"></a>
7
+ <a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
8
+ <a href="https://dms.antelopejs.com/docs/modules/media/extending"><img data-illustration alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
9
9
 
10
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
 
@@ -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`, called once per tenant from `Hook.TENANT_BEING_PROVISIONED`: idempotent per key, the content belongs to the members once written.
20
+ - Ships folders and files from backend code with `EnsureMediaFolder` and `ImportMediaAsset`, called once per tenant from `Hook.TENANT_BEING_PROVISIONED`. Each declaration writes once per key and tenant, and the content belongs to the members from then on.
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
@@ -30,7 +30,7 @@ pnpm add @antelopejs/interface-dms-media
30
30
 
31
31
  ## Quick start
32
32
 
33
- ```ts
33
+ ```ts fragment
34
34
  import { AssetType } from "@antelopejs/interface-dms-media";
35
35
 
36
36
  new AssetType({
@@ -62,32 +62,34 @@ RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
62
62
  });
63
63
  ```
64
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).
65
+ Both declarations require `tenantId` in TypeScript, and reject a missing, empty or whitespace-only value at runtime before any write. They do not check that the caller may act on that tenant. Call them from a `Hook.TENANT_BEING_PROVISIONED` handler, as [When to call](./docs/1.index.md#when-to-call) explains.
66
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`.
67
+ The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetBindingField`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `MediaFolderVisibility`, `MediaAssetDeclaration`, `MediaFolderTarget`, `DeclaredFolderTarget`, `BoundFolderTarget`, `MediaAssetSource`, `MediaBytesSource`, `MediaFileSource`, `MediaLazySource`, `MediaDeclarationResult`, `MediaDeclarationStatus`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`. It exports the constants `ASSET_DATA_TYPE_ID` and `ASSET_PICKER_COMPONENT` too, and an `internal` namespace that only the implementation uses.
68
68
 
69
69
  ## Compatibility
70
70
 
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
+ The interface needs a `@antelopejs/dms-media` release that implements this version of it. The compatibility block of the [module README](../dms-media/README.md#compatibility) lists the interface range that each module release supports. The interface declares these peer dependencies:
72
+
73
+ <!-- antelopejs-docs-compat:start -->
72
74
 
73
- <!-- docs-compat: ./package.json#peerDependencies -->
75
+ | Package | Supported | Tested with |
76
+ | ---------------------------- | ----------------- | ----------- |
77
+ | `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` | `0.3.0` |
78
+ | `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | `0.4.0` |
79
+ | `@antelopejs/interface-dms` | `>=0.9.0 <1.0.0` | `0.13.0` |
74
80
 
75
- | Package | Range |
76
- | --- | --- |
77
- | `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
78
- | `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
79
- | `@antelopejs/interface-dms` | `>=0.9.0 <1.0.0` |
81
+ <!-- antelopejs-docs-compat:end -->
80
82
 
81
83
  ## Documentation
82
84
 
83
85
  - [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle, declared content and permission precedence
84
86
  - [Extending the media module](https://dms.antelopejs.com/docs/modules/media/extending): asset fields, folder bindings, the HTTP API and delivery URLs
85
- - [The asset field](https://dms.antelopejs.com/docs/modules/media/usage/asset-field)
87
+ - [The asset field](https://dms.antelopejs.com/docs/modules/media/usage/library#asset-field)
86
88
  - [Media module guide](https://dms.antelopejs.com/docs/modules/media)
87
89
 
88
90
  ## Contributing
89
91
 
90
- This package lives in the [`AntelopeJS/dms-media`](https://github.com/AntelopeJS/dms-media) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-media/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-media#contributing) for the development commands; `pnpm check:exports` checks, after a build, that the exports map matches `dist`. Release this package before the module that implements it.
92
+ This package lives in the [`AntelopeJS/dms-media`](https://github.com/AntelopeJS/dms-media) pnpm workspace, next to the module that implements it. Read [CONTRIBUTING.md](https://github.com/AntelopeJS/dms-media/blob/main/CONTRIBUTING.md) and the [repository README](https://github.com/AntelopeJS/dms-media#contributing) for the development commands. After a build, `pnpm check:exports` checks that the exports map matches `dist`. Release this package before the module that implements it.
91
93
 
92
94
  ## License
93
95
 
package/docs/1.index.md CHANGED
@@ -1,17 +1,14 @@
1
1
  ---
2
2
  title: Media interface
3
3
  description: Asset fields, folder binding lifecycle, declared content and permission contracts for DMS consumers.
4
+ mode: reference
4
5
  ---
5
6
 
6
- # Media interface
7
-
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).
7
+ `@antelopejs/interface-dms-media` exports the asset field and folder binding declarations, and the functions that ship library folders and files as code. The Media runtime (`@antelopejs/dms-media`) implements them and provides the picker, the uploads and the provisioning. The HTTP routes and the delivery URLs are in the [runtime guide](/docs/modules/media/extending#http-surface).
9
8
 
10
9
  ## Declare a field
11
10
 
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.
11
+ This field goes in a DMS form. It stores up to four asset IDs and registers an upload folder in each tenant. The permission IDs belong to the application, and a role of the project grants them.
15
12
 
16
13
  ```ts docs-check
17
14
  import { AssetType } from "@antelopejs/interface-dms-media";
@@ -31,13 +28,9 @@ export const articleImages = new AssetType({
31
28
  });
32
29
  ```
33
30
 
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.
31
+ Selecting two images produces a value such as `["asset-a", "asset-b"]`, never two URLs. An empty selection is `[]`. A fifth ID fails the field's shape validation. An unknown nonempty ID passes it, so the write path that consumes the value checks that the asset exists, belongs to the tenant and has the right type. The [picker example](/docs/modules/media/extending#add-an-asset-field) shows the UI.
39
32
 
40
- ## AssetType
33
+ ## `AssetType`
41
34
 
42
35
  ```ts [Contract]
43
36
  import type { AssetBindingConfig } from "@antelopejs/interface-dms-media";
@@ -57,13 +50,13 @@ interface AssetPickerComponentOptions {
57
50
  }
58
51
  ```
59
52
 
60
- `new AssetType(options?: AssetTypeOptions)` returns a DMS `DataType`. With default options, validation accepts one nonempty asset-ID string. `multiple: true` accepts an array of nonempty strings, including an empty array; `max` caps its length only in multiple mode. `getValidation()` returns a Zod schema: it validates that shape, not asset existence, ownership or MIME type.
53
+ `new AssetType(options?: AssetTypeOptions)` returns a DMS `DataType`. With the default options, validation accepts one nonempty asset ID string. `multiple: true` accepts an array of nonempty strings, the empty array included. `max` caps the array length, and only in multiple mode. `getValidation()` returns a Zod schema that checks this shape. It does not check that the asset exists, who owns it or its MIME type.
61
54
 
62
- `mimetypes` limits the picker to types such as `image/*` or `application/pdf`. Bound-folder uploads also enforce the binding's MIME types server-side, alongside the runtime upload policy. Do not treat the form schema or client-side filtering as an authorization check.
55
+ `mimetypes` limits the picker to types such as `image/*` or `application/pdf`. The server also refuses an upload into a bound folder, or into one of its subfolders, whose type the binding's field does not accept. The runtime upload policy applies on top. Neither the form schema nor the filtering in the client is an authorization check.
63
56
 
64
- Constructing a field with `binding` registers that binding and fills its `field` metadata from `multiple`, `max` and `mimetypes`. The picker receives `AssetPickerComponentOptions` with the binding's ID, not its ACL. The exported constants are `ASSET_DATA_TYPE_ID = "asset"` and `ASSET_PICKER_COMPONENT = "dms-media-asset-picker"`; importing the field module registers the data type.
57
+ Constructing a field with `binding` registers that binding and fills its `field` metadata from `multiple`, `max` and `mimetypes`. The picker receives `AssetPickerComponentOptions` with the binding's ID, never its ACL. The package exports two constants, `ASSET_DATA_TYPE_ID = "asset"` and `ASSET_PICKER_COMPONENT = "dms-media-asset-picker"`. Importing the package registers the data type.
65
58
 
66
- ## RegisterAssetBinding and UnregisterAssetBinding
59
+ ## `RegisterAssetBinding` and `UnregisterAssetBinding`
67
60
 
68
61
  ```ts [Contract]
69
62
  import type { ControllerClass } from "@antelopejs/interface-api";
@@ -100,25 +93,33 @@ declare function UnregisterAssetBinding(id: string): void;
100
93
 
101
94
  All these types and functions are available from the package root. The exported `internal` proxy namespace is not a consumer API.
102
95
 
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.
96
+ A binding ID is stable and namespaced, such as `articles.cover`. The runtime keys registrations by ID, so a second registration with the same ID replaces the first one. It does not create a second binding. Registration returns at once and does not wait for any folder. The calling module owns the registration. Unloading that module releases it, and a reloaded implementation receives every active registration again.
97
+
98
+ The runtime provisions each tenant separately, under a private `Content` root, the first time a request or a declaration reads that tenant's folders after a registration changes. A new folder is named `folderName`, or the binding `id` when `folderName` is absent. An existing bound folder keeps its name and takes the current ACL. `UnregisterAssetBinding` removes the registration and leaves the provisioned folders and files in place.
104
99
 
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.
100
+ A bound folder is locked. The library refuses to rename, move or delete it, and its ACL always comes from the binding. 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 the 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. The field's picker opens on the bound folder and browses its subfolders. Its upload button always targets the bound folder.
106
101
 
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.
102
+ Neither function returns an upload result or a provisioning error. A provisioning or storage failure surfaces later, in the runtime operation that provisions the tenant's folders.
108
103
 
109
104
  ## Permission precedence and tenant access
110
105
 
111
- 1. An explicit `acl`, including `[]`, replaces all derived entries.
112
- 2. Otherwise, `permissionMapping.read` and `.write` take precedence independently over the page-derived permission. An explicit empty array disables fallback for that right.
113
- 3. Missing mappings fall back to the effective permission of `permissionsFromPage`, resolved lazily at provisioning time so a field can reference its enclosing page class.
106
+ A binding's ACL comes from the first rule that applies:
107
+
108
+ 1. An explicit `acl`, `[]` included, replaces every derived entry.
109
+ 2. Otherwise, `permissionMapping.read` and `permissionMapping.write` each take precedence over the permission derived from the page, one right at a time. An explicit empty array turns off the fallback for that right.
110
+ 3. A right with no mapping falls back to the effective permission of `permissionsFromPage`. The runtime resolves it at provisioning time, so a field can name the page class that contains it.
111
+
112
+ A `read` mapping grants `read`, and a `write` mapping grants `write`.
113
+
114
+ ### Access model
114
115
 
115
- ACL rights imply weaker rights: `manage` ⇒ `write` ⇒ `read`. A role must explicitly grant the page permission; `memberAccess` or `publicAccess` alone does not grant a folder right. The runtime's Media administration pages remain owner-only. Members reach accessible files through asset fields on project pages, not by receiving a Media page permission.
116
+ A right includes the weaker rights. `manage` includes `write` and `read`, and `write` includes `read`. A role grants the page permission explicitly. A page that a member holds only through `memberAccess` or `publicAccess` grants no folder right. The runtime's Media administration pages stay owner-only. Members reach the files they may access through asset fields on the project's pages, never through a Media page permission.
116
117
 
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.
118
+ Owners hold every folder right. Uploading and changing files need the folder's `write` right. Changing the folder structure needs `manage`. Changing the visibility of a file or a folder is reserved to owners, and so is moving a file to a folder that changes its effective visibility. A member with `write` on a linked folder can change any of its files, whoever uploaded them. The default root ACL (`rootAcl`) grants members nothing. A folder without an ACL of its own takes its parent's rights, and a folder at the root takes those of `rootAcl`. A grant in `rootAcl` therefore reaches every folder whose ancestors set no ACL either, and can open the rest of the library.
118
119
 
119
- ## EnsureMediaFolder and ImportMediaAsset
120
+ ## `EnsureMediaFolder` and `ImportMediaAsset`
120
121
 
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
+ A project ships media content, such as templates, procedures and demo pictures, from its backend code with these two functions. The Media runtime creates the content itself. It checks the declaration with the dashboard's rules, writes the bytes to its configured file storage, computes the image dimensions and records the creation in the library activity. The runtime's tables are not part of the contract, and no module writes them directly.
122
123
 
123
124
  ```ts [Contract]
124
125
  import type { AclEntry } from "@antelopejs/interface-dms-media";
@@ -164,42 +165,45 @@ declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise
164
165
  declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
165
166
  ```
166
167
 
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.
168
+ - `key` is a stable, namespaced ID that the caller chooses, such as `helio.procedures`. The runtime trims it and accepts 1 to 255 characters. It keys declarations by tenant, kind and key, so it creates each folder and each file once.
169
+ - A folder goes at the library root, under the declared folder that `parent` names (by its key, as a string or as `{ 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, or `rootAcl` at the root.
170
+ - A file goes into a declared folder (`{ key }`) or into the folder bound to an asset field (`{ binding }`). The binding is the `id` given to `AssetType` or `RegisterAssetBinding`, and the runtime provisions its folder first. `source` is the content in memory (`bytes`), a path on the backend's file system (`filePath`) or a function that produces it (`load`). `name` is the file name shown in the library, extension included.
171
+ - The runtime reads the source only when it creates the file. A key declared before returns `kept`, and the runtime does not read its source.
172
+ - `tenantId` is required in TypeScript and at runtime. An omitted, empty or whitespace-only value rejects before any database write or source read. There is no default. Passing `DEFAULT_TENANT_ID` explicitly is valid.
173
+ - `id` in the result is the library ID of the folder or file. An `AssetType` value can store it, for example.
173
174
 
174
175
  ### Written once
175
176
 
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
+ Declared content is written once, when the tenant is provisioned (see [When to call](#when-to-call)). From then on it belongs to the tenant's members. Nothing replays a declaration on a later boot, so nothing compares the library with the code or takes content back. A declaration has one of two outcomes:
177
178
 
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.
179
+ 1. No declaration of the key exists in this tenant. The runtime creates the folder or file and returns `created`. It remembers the new ID under the key, so a later declaration can name the folder as a `parent` or a `{ key }` target.
180
+ 2. An earlier or retried provisioning declared the key. The runtime writes nothing, does not read the source and returns `kept`, with the ID of the row created then.
180
181
 
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
+ The activity records only creations, as `folder.create` and `asset.upload`, attributed to `System`. The queue that orders the declarations of one key is local to the process. Creation, storage, activity and declaration bookkeeping are not one transaction. One declaration writer per tenant and key is therefore the supported setup.
182
183
 
183
184
  ### Validation and errors
184
185
 
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
+ Declarations follow the dashboard's rules. A refused declaration rejects with an error that names the kind, the key and the reason, such as `Media folder 'helio.procedures': a folder named 'Procedures' already exists there`. The rules are these:
186
187
 
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.
188
+ - A folder name refuses `/ \ < > : " | ? *` and control characters, has at most 255 characters and is unique among its siblings, ignoring case and Unicode form.
189
+ - A file name refuses `/`, `\` and control characters and has at most 255 characters.
190
+ - A `parent` or `{ key }` folder must be declared first and not deleted since.
191
+ - A folder cannot name itself as its parent.
192
+ - A `{ binding }` folder must be registered, and a `{ binding }` parent must allow `subfolders`.
193
+ - Each `acl` entry grants at least one right.
194
+ - A file is not empty and has at most 500 MiB. Its type is allowed by `allowedMimetypes` and is never HTML, XHTML or PHP. The bound field accepts its type, and it fits within the storage quota.
195
+ - A file whose mimetype names an image format that the runtime decodes must decode. The runtime stores the decoded format's mimetype, as it does for an upload.
196
+ - Alt text has at most 255 characters.
193
197
 
194
198
  ### When to call
195
199
 
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.
200
+ The functions belong in a `Hook.TENANT_BEING_PROVISIONED` handler registered in the module's `construct()`. The DMS fires that hook once per tenant, when the tenant is created. For the `default` tenant, it fires on the DMS start that creates the tenant, once every `Hook.DATABASE_INITIALIZED` handler has finished. For a workspace, the SaaS module fires it when it creates the workspace. The tenant's tables exist by then, and the runtime writes files through the storage's `WriteFile`, so nothing waits. `start()` and `DATABASE_INITIALIZED` handlers run on every boot, so they are the wrong place for these calls. A parent is declared before its children and a folder before its files, each call awaited.
197
201
 
198
202
  ### Tenant scope and trusted backend context
199
203
 
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.
204
+ `tenantId` selects the existing DMS tenant schema instance that holds the folders, the files and the declaration registry. Parent keys and bindings resolve within that tenant, and different tenants can use the same declaration key independently. Both functions require an explicit tenant that is not blank. Neither infers it from an HTTP session or a SaaS workspace context. The runtime trims surrounding whitespace.
201
205
 
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`.
206
+ 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 a payment status or decide when the provisioning of a workspace is committed. Storage paths include the tenant ID, and the storage backend and the upload policy stay module configuration. The activity attributes the events to `System`.
203
207
 
204
208
  ```ts docs-check
205
209
  import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
@@ -2,9 +2,17 @@
2
2
  "extends": "../tsconfig.json",
3
3
  "compilerOptions": {
4
4
  "rootDir": "..",
5
+ "module": "esnext",
6
+ "moduleResolution": "bundler",
7
+ "noUnusedLocals": false,
8
+ "noUnusedParameters": false,
5
9
  "composite": false,
6
10
  "incremental": false,
7
- "noEmit": true
11
+ "noEmit": true,
12
+ "paths": {
13
+ "@antelopejs/interface-dms-media": ["../src/index.ts"],
14
+ "@antelopejs/interface-dms-media/*": ["../src/*"]
15
+ }
8
16
  },
9
17
  "include": ["../src/**/*.ts", "./**/*.ts"]
10
18
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-dms-media",
3
- "version": "0.3.1",
3
+ "version": "0.3.3",
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",
@@ -45,11 +45,8 @@
45
45
  },
46
46
  "scripts": {
47
47
  "build": "rimraf dist && tsc",
48
- "lint": "oxlint && oxfmt --check .",
49
- "lint:fix": "oxlint --fix --max-warnings=1000000 && oxfmt .",
50
- "format": "oxfmt .",
51
48
  "typecheck": "tsc --noEmit",
52
- "release": "pnpm run lint && pnpm run build && pnpm run check:exports && release-it",
49
+ "release": "pnpm run build && pnpm --dir ../.. run lint && pnpm run check:exports && release-it",
53
50
  "prepack": "pnpm run build",
54
51
  "check:exports": "node scripts/check-exports.mjs",
55
52
  "knip": "knip --dependencies",
@@ -59,15 +56,16 @@
59
56
  "zod": "~3.24.2"
60
57
  },
61
58
  "devDependencies": {
62
- "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
63
- "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
64
- "@antelopejs/interface-dms": ">=0.9.0 <1.0.0",
65
- "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
59
+ "@antelopejs/interface-api": ">=0.3.0 <1.0.0",
60
+ "@antelopejs/interface-api-util": ">=0.3.0 <1.0.0",
61
+ "@antelopejs/interface-core": ">=0.4.0 <1.0.0",
62
+ "@antelopejs/interface-data-api": ">=0.6.1 <1.0.0",
63
+ "@antelopejs/interface-database": ">=0.3.0 <1.0.0",
64
+ "@antelopejs/interface-database-decorators": ">=0.2.0 <1.0.0",
65
+ "@antelopejs/interface-dms": ">=0.13.0 <1.0.0",
66
+ "@antelopejs/tooling-configs": "^0.3.3",
66
67
  "@types/node": "^24.0.0",
67
68
  "knip": "^6.34.0",
68
- "oxfmt": "^0.66.0",
69
- "oxlint": "1.81.0",
70
- "oxlint-tsgolint": "^7.0.2001",
71
69
  "release-it": "^19.2.4",
72
70
  "release-it-changelogen": "^0.1.0",
73
71
  "rimraf": "^6.1.3",