@antelopejs/interface-dms-media 0.2.1 → 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 CHANGED
@@ -1,37 +1,33 @@
1
+ <div align="center">
2
+
1
3
  # @antelopejs/interface-dms-media
2
4
 
3
- <div align="center">
4
- <a href="https://www.npmjs.com/package/@antelopejs/interface-dms-media"><img alt="NPM version" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-media.svg?style=for-the-badge&labelColor=000000"></a>
5
- <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge&labelColor=000000"></a>
6
- <a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
7
- <a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
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
- AntelopeJS interface for the DMS media module (`@antelopejs/dms-media`):
11
- declare asset fields, and the media folders bound to them, from any module.
14
+ ## What it does
12
15
 
13
- - **Implemented by** `@antelopejs/dms-media` (declared in its
14
- `antelopeJs.implements`).
15
- - **Consumed by** modules that declare `AssetType` fields on their DMS pages.
16
- Declare this package in `dependencies`.
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
- ## Surface
22
+ ## Install
19
23
 
20
- - `AssetType` — form field referencing media library assets by id (one id, or
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
- A binding registration belongs to the module that makes it: it is released
33
- when that module is destroyed and replayed to every new generation of the
34
- implementer, so either side can hot reload without losing it.
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
- ## Development
45
+ The interface also exports the option and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
50
46
 
51
- Lives in the [`dms-media`](https://github.com/AntelopeJS/dms-media) workspace,
52
- next to the module that implements it.
47
+ ## Compatibility
53
48
 
54
- ```bash
55
- pnpm build
56
- pnpm lint
57
- pnpm typecheck
58
- pnpm knip
59
- pnpm check:exports # after build: the exports map matches dist
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)
@@ -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
+ ```
@@ -0,0 +1,10 @@
1
+ {
2
+ "extends": "../tsconfig.json",
3
+ "compilerOptions": {
4
+ "rootDir": "..",
5
+ "composite": false,
6
+ "incremental": false,
7
+ "noEmit": true
8
+ },
9
+ "include": ["../src/**/*.ts", "./**/*.ts"]
10
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@antelopejs/interface-dms-media",
3
- "version": "0.2.1",
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.14 <1.0.0",
57
- "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
58
- "@antelopejs/interface-dms": ">=0.6.0 <1.0.0",
59
- "@antelopejs/tooling-configs": ">=0.0.7 <1.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.14 <1.0.0",
72
- "@antelopejs/interface-core": ">=0.1.1 <1.0.0",
73
- "@antelopejs/interface-dms": ">=0.5.12 <1.0.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": {}