@antelopejs/interface-dms-media 0.2.0 → 0.2.2
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 +48 -36
- package/docs/1.index.md +106 -0
- package/docs/tsconfig.json +10 -0
- package/package.json +15 -9
package/README.md
CHANGED
|
@@ -1,37 +1,33 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
1
3
|
# @antelopejs/interface-dms-media
|
|
2
4
|
|
|
3
|
-
<
|
|
4
|
-
<a href="
|
|
5
|
-
<a href="
|
|
6
|
-
<a href="https://
|
|
7
|
-
|
|
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>
|
|
9
|
+
|
|
10
|
+
The AntelopeJS interface to add media library fields, and the folders bound to them, to DMS pages.
|
|
11
|
+
|
|
8
12
|
</div>
|
|
9
13
|
|
|
10
|
-
|
|
11
|
-
declare asset fields, and the media folders bound to them, from any module.
|
|
14
|
+
## What it does
|
|
12
15
|
|
|
13
|
-
-
|
|
14
|
-
|
|
15
|
-
-
|
|
16
|
-
|
|
16
|
+
- Adds an `AssetType` form field that references library assets by id (one id, or an array with `multiple`) and opens the library as a picker.
|
|
17
|
+
- Binds a field to a folder provisioned under the `Content` root of each tenant: `RegisterAssetBinding` and `UnregisterAssetBinding`, or `new AssetType({ binding })`.
|
|
18
|
+
- Derives the folder's rights from a page (`permissionsFromPage`), a `permissionMapping` or an explicit `acl`.
|
|
19
|
+
- Replays bindings to every new generation of the implementation, so either side can hot reload.
|
|
20
|
+
- Keeps your module independent of the implementation, [`@antelopejs/dms-media`](https://www.npmjs.com/package/@antelopejs/dms-media).
|
|
17
21
|
|
|
18
|
-
##
|
|
22
|
+
## Install
|
|
19
23
|
|
|
20
|
-
|
|
21
|
-
an array with `multiple`). Registers the `asset` data type; its widget is the
|
|
22
|
-
`dms-media-asset-picker` component the module ships.
|
|
23
|
-
- `RegisterAssetBinding(config)` / `UnregisterAssetBinding(id)` — declare or
|
|
24
|
-
withdraw a folder binding. `new AssetType({ binding })` registers its binding
|
|
25
|
-
itself. The implementer provisions the bound folder under the `Content` root
|
|
26
|
-
of each tenant, with an ACL derived from `permissionMapping`,
|
|
27
|
-
`permissionsFromPage` or an explicit `acl`.
|
|
28
|
-
- Types: `AssetTypeOptions`, `AssetPickerComponentOptions`,
|
|
29
|
-
`AssetBindingConfig`, `AssetPermissionMapping`, `AclEntry`, `AclSubject`,
|
|
30
|
-
`AclSubjectKind`, `AclRight`.
|
|
24
|
+
Add the interface to the `dependencies` of the module that declares asset fields:
|
|
31
25
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
26
|
+
```bash
|
|
27
|
+
pnpm add @antelopejs/interface-dms-media
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Quick start
|
|
35
31
|
|
|
36
32
|
```ts
|
|
37
33
|
import { AssetType } from "@antelopejs/interface-dms-media";
|
|
@@ -46,15 +42,31 @@ new AssetType({
|
|
|
46
42
|
});
|
|
47
43
|
```
|
|
48
44
|
|
|
49
|
-
|
|
45
|
+
The interface also exports the option and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
|
|
50
46
|
|
|
51
|
-
|
|
52
|
-
next to the module that implements it.
|
|
47
|
+
## Compatibility
|
|
53
48
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
49
|
+
The implementation is `@antelopejs/dms-media >=0.4.0`. The interface declares these peer dependencies:
|
|
50
|
+
|
|
51
|
+
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
52
|
+
|
|
53
|
+
| Package | Range |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
|
|
56
|
+
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
57
|
+
| `@antelopejs/interface-dms` | `>=0.7.2 <1.0.0` |
|
|
58
|
+
|
|
59
|
+
## Documentation
|
|
60
|
+
|
|
61
|
+
- [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle and permission precedence
|
|
62
|
+
- [Extending the media module](https://dms.antelopejs.com/docs/modules/media/extending): asset fields, folder bindings, the HTTP API and delivery URLs
|
|
63
|
+
- [The asset field](https://dms.antelopejs.com/docs/modules/media/usage/asset-field)
|
|
64
|
+
- [Media module guide](https://dms.antelopejs.com/docs/modules/media)
|
|
65
|
+
|
|
66
|
+
## Contributing
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
## License
|
|
71
|
+
|
|
72
|
+
[Apache-2.0](./LICENSE)
|
package/docs/1.index.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Media interface
|
|
3
|
+
description: Asset fields, folder binding lifecycle and permission contracts for DMS consumers.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Media interface
|
|
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).
|
|
9
|
+
|
|
10
|
+
## AssetType
|
|
11
|
+
|
|
12
|
+
```ts [Contract]
|
|
13
|
+
import type { AssetBindingConfig } from "@antelopejs/interface-dms-media";
|
|
14
|
+
|
|
15
|
+
interface AssetTypeOptions extends Record<string, unknown> {
|
|
16
|
+
multiple?: boolean;
|
|
17
|
+
max?: number;
|
|
18
|
+
mimetypes?: string[];
|
|
19
|
+
binding?: AssetBindingConfig;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
interface AssetPickerComponentOptions {
|
|
23
|
+
multiple?: boolean;
|
|
24
|
+
max?: number;
|
|
25
|
+
mimetypes?: string[];
|
|
26
|
+
bindingId?: string;
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`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.
|
|
31
|
+
|
|
32
|
+
`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.
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
36
|
+
## RegisterAssetBinding and UnregisterAssetBinding
|
|
37
|
+
|
|
38
|
+
```ts [Contract]
|
|
39
|
+
import type { ControllerClass } from "@antelopejs/interface-api";
|
|
40
|
+
|
|
41
|
+
type AclRight = "read" | "write" | "manage";
|
|
42
|
+
type AclSubjectKind = "permission" | "role";
|
|
43
|
+
interface AclSubject { kind: AclSubjectKind; id: string; }
|
|
44
|
+
interface AclEntry { subject: AclSubject; rights: AclRight[]; }
|
|
45
|
+
|
|
46
|
+
interface AssetPermissionMapping {
|
|
47
|
+
read?: string[];
|
|
48
|
+
write?: string[];
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
interface AssetBindingField {
|
|
52
|
+
multiple?: boolean;
|
|
53
|
+
max?: number;
|
|
54
|
+
mimetypes?: string[];
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
interface AssetBindingConfig {
|
|
58
|
+
id: string;
|
|
59
|
+
folderName?: string;
|
|
60
|
+
permissionMapping?: AssetPermissionMapping;
|
|
61
|
+
permissionsFromPage?: ControllerClass;
|
|
62
|
+
acl?: AclEntry[];
|
|
63
|
+
field?: AssetBindingField;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
declare function RegisterAssetBinding(config: AssetBindingConfig): void;
|
|
67
|
+
declare function UnregisterAssetBinding(id: string): void;
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
All these types and functions are available from the package root. The exported `internal` proxy namespace is not a consumer API.
|
|
71
|
+
|
|
72
|
+
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
|
+
|
|
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.
|
|
75
|
+
|
|
76
|
+
## Permission precedence and tenant access
|
|
77
|
+
|
|
78
|
+
1. An explicit `acl`, including `[]`, replaces all derived entries.
|
|
79
|
+
2. Otherwise, `permissionMapping.read` and `.write` take precedence independently over the page-derived permission. An explicit empty array disables fallback for that right.
|
|
80
|
+
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.
|
|
81
|
+
|
|
82
|
+
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.
|
|
83
|
+
|
|
84
|
+
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
|
+
|
|
86
|
+
## Declare a field
|
|
87
|
+
|
|
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.
|
|
89
|
+
|
|
90
|
+
```ts docs-check
|
|
91
|
+
import { AssetType } from "@antelopejs/interface-dms-media";
|
|
92
|
+
|
|
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
|
+
});
|
|
106
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-dms-media",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.2",
|
|
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",
|
|
@@ -9,13 +9,19 @@
|
|
|
9
9
|
"interface",
|
|
10
10
|
"media"
|
|
11
11
|
],
|
|
12
|
+
"homepage": "https://dms.antelopejs.com/docs/modules/media/extending",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/AntelopeJS/dms-media/issues"
|
|
15
|
+
},
|
|
12
16
|
"license": "Apache-2.0",
|
|
13
17
|
"repository": {
|
|
14
18
|
"type": "git",
|
|
15
|
-
"url": "git+https://github.com/AntelopeJS/dms-media.git"
|
|
19
|
+
"url": "git+https://github.com/AntelopeJS/dms-media.git",
|
|
20
|
+
"directory": "packages/interface-dms-media"
|
|
16
21
|
},
|
|
17
22
|
"files": [
|
|
18
23
|
"LICENSE",
|
|
24
|
+
"docs",
|
|
19
25
|
"dist",
|
|
20
26
|
"!dist/.tsbuildinfo"
|
|
21
27
|
],
|
|
@@ -53,10 +59,10 @@
|
|
|
53
59
|
"zod": "~3.24.2"
|
|
54
60
|
},
|
|
55
61
|
"devDependencies": {
|
|
56
|
-
"@antelopejs/interface-api": ">=0.0.
|
|
57
|
-
"@antelopejs/interface-core": ">=0.
|
|
58
|
-
"@antelopejs/interface-dms": ">=0.
|
|
59
|
-
"@antelopejs/tooling-configs": ">=0.0.
|
|
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.7.2 <1.0.0",
|
|
65
|
+
"@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
|
|
60
66
|
"@types/node": "^24.0.0",
|
|
61
67
|
"knip": "^6.34.0",
|
|
62
68
|
"oxfmt": "^0.66.0",
|
|
@@ -68,9 +74,9 @@
|
|
|
68
74
|
"typescript": "^6.0.3"
|
|
69
75
|
},
|
|
70
76
|
"peerDependencies": {
|
|
71
|
-
"@antelopejs/interface-api": ">=0.0.
|
|
72
|
-
"@antelopejs/interface-core": ">=0.
|
|
73
|
-
"@antelopejs/interface-dms": ">=0.
|
|
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.7.2 <1.0.0"
|
|
74
80
|
},
|
|
75
81
|
"packageManager": "pnpm@10.2.0",
|
|
76
82
|
"antelopeJs": {}
|