@antelopejs/interface-dms-media 0.3.0 → 0.3.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 +33 -30
- package/dist/content.d.ts +2 -23
- package/dist/content.js +0 -8
- package/dist/content.js.map +1 -1
- package/dist/internal.d.ts +1 -3
- package/dist/internal.js +0 -2
- package/dist/internal.js.map +1 -1
- package/docs/1.index.md +77 -141
- package/docs/tsconfig.json +9 -1
- package/package.json +11 -13
package/README.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
#
|
|
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/
|
|
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
|
|
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({
|
|
@@ -43,50 +43,53 @@ new AssetType({
|
|
|
43
43
|
});
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
Ship a folder and a file
|
|
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 {
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
|
|
54
|
-
await ImportMediaAsset({
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
|
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.
|
|
65
66
|
|
|
66
|
-
The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `
|
|
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.
|
|
67
68
|
|
|
68
69
|
## Compatibility
|
|
69
70
|
|
|
70
|
-
The
|
|
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 -->
|
|
71
74
|
|
|
72
|
-
|
|
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.12.0` |
|
|
73
80
|
|
|
74
|
-
|
|
75
|
-
| --- | --- |
|
|
76
|
-
| `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
|
|
77
|
-
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
78
|
-
| `@antelopejs/interface-dms` | `>=0.7.2 <1.0.0` |
|
|
81
|
+
<!-- antelopejs-docs-compat:end -->
|
|
79
82
|
|
|
80
83
|
## Documentation
|
|
81
84
|
|
|
82
85
|
- [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle, declared content and permission precedence
|
|
83
86
|
- [Extending the media module](https://dms.antelopejs.com/docs/modules/media/extending): asset fields, folder bindings, the HTTP API and delivery URLs
|
|
84
|
-
- [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)
|
|
85
88
|
- [Media module guide](https://dms.antelopejs.com/docs/modules/media)
|
|
86
89
|
|
|
87
90
|
## Contributing
|
|
88
91
|
|
|
89
|
-
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
|
|
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.
|
|
90
93
|
|
|
91
94
|
## License
|
|
92
95
|
|
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" | "
|
|
37
|
+
export type MediaDeclarationStatus = "created" | "kept";
|
|
39
38
|
export interface MediaDeclarationResult {
|
|
40
39
|
status: MediaDeclarationStatus;
|
|
41
|
-
id
|
|
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
|
package/dist/content.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":";;
|
|
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/internal.d.ts
CHANGED
|
@@ -1,10 +1,8 @@
|
|
|
1
1
|
import { RegisteringProxy } from "@antelopejs/interface-core";
|
|
2
2
|
import type { AssetBindingConfig } from "./bindings";
|
|
3
|
-
import type { MediaAssetDeclaration,
|
|
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
|
package/dist/internal.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":";;;AAAA,+DAGoC;
|
|
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,13 +1,36 @@
|
|
|
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
|
-
|
|
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).
|
|
7
8
|
|
|
8
|
-
|
|
9
|
+
## Declare a field
|
|
10
|
+
|
|
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.
|
|
12
|
+
|
|
13
|
+
```ts docs-check
|
|
14
|
+
import { AssetType } from "@antelopejs/interface-dms-media";
|
|
9
15
|
|
|
10
|
-
|
|
16
|
+
export const articleImages = new AssetType({
|
|
17
|
+
multiple: true,
|
|
18
|
+
max: 4,
|
|
19
|
+
mimetypes: ["image/*"],
|
|
20
|
+
binding: {
|
|
21
|
+
id: "articles.images",
|
|
22
|
+
folderName: "Article images",
|
|
23
|
+
permissionMapping: {
|
|
24
|
+
read: ["articles.page"],
|
|
25
|
+
write: ["articles.page.table.edit"],
|
|
26
|
+
},
|
|
27
|
+
},
|
|
28
|
+
});
|
|
29
|
+
```
|
|
30
|
+
|
|
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.
|
|
32
|
+
|
|
33
|
+
## `AssetType`
|
|
11
34
|
|
|
12
35
|
```ts [Contract]
|
|
13
36
|
import type { AssetBindingConfig } from "@antelopejs/interface-dms-media";
|
|
@@ -27,13 +50,13 @@ interface AssetPickerComponentOptions {
|
|
|
27
50
|
}
|
|
28
51
|
```
|
|
29
52
|
|
|
30
|
-
`new AssetType(options?: AssetTypeOptions)` returns a DMS `DataType`. With default options, validation accepts one nonempty asset
|
|
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.
|
|
31
54
|
|
|
32
|
-
`mimetypes` limits the picker to types such as `image/*` or `application/pdf`.
|
|
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.
|
|
33
56
|
|
|
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,
|
|
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.
|
|
35
58
|
|
|
36
|
-
## RegisterAssetBinding and UnregisterAssetBinding
|
|
59
|
+
## `RegisterAssetBinding` and `UnregisterAssetBinding`
|
|
37
60
|
|
|
38
61
|
```ts [Contract]
|
|
39
62
|
import type { ControllerClass } from "@antelopejs/interface-api";
|
|
@@ -70,47 +93,33 @@ declare function UnregisterAssetBinding(id: string): void;
|
|
|
70
93
|
|
|
71
94
|
All these types and functions are available from the package root. The exported `internal` proxy namespace is not a consumer API.
|
|
72
95
|
|
|
73
|
-
|
|
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.
|
|
74
99
|
|
|
75
|
-
The
|
|
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.
|
|
76
101
|
|
|
77
|
-
|
|
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.
|
|
78
103
|
|
|
79
104
|
## Permission precedence and tenant access
|
|
80
105
|
|
|
81
|
-
|
|
82
|
-
2. Otherwise, `permissionMapping.read` and `.write` take precedence independently over the page-derived permission. An explicit empty array disables fallback for that right.
|
|
83
|
-
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:
|
|
84
107
|
|
|
85
|
-
|
|
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.
|
|
86
111
|
|
|
87
|
-
|
|
112
|
+
A `read` mapping grants `read`, and a `write` mapping grants `write`.
|
|
88
113
|
|
|
89
|
-
|
|
114
|
+
### Access model
|
|
90
115
|
|
|
91
|
-
|
|
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.
|
|
92
117
|
|
|
93
|
-
|
|
94
|
-
import { AssetType } from "@antelopejs/interface-dms-media";
|
|
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.
|
|
95
119
|
|
|
96
|
-
|
|
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
|
-
## EnsureMediaFolder and ImportMediaAsset
|
|
120
|
+
## `EnsureMediaFolder` and `ImportMediaAsset`
|
|
112
121
|
|
|
113
|
-
A project ships media content
|
|
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.
|
|
114
123
|
|
|
115
124
|
```ts [Contract]
|
|
116
125
|
import type { AclEntry } from "@antelopejs/interface-dms-media";
|
|
@@ -141,115 +150,70 @@ interface MediaAssetDeclaration {
|
|
|
141
150
|
name: string;
|
|
142
151
|
mimetype: string;
|
|
143
152
|
source: MediaAssetSource;
|
|
144
|
-
version?: string;
|
|
145
153
|
alt?: string;
|
|
146
154
|
tenantId: string;
|
|
147
155
|
}
|
|
148
156
|
|
|
149
|
-
type MediaDeclarationStatus = "created" | "
|
|
157
|
+
type MediaDeclarationStatus = "created" | "kept";
|
|
150
158
|
|
|
151
159
|
interface MediaDeclarationResult {
|
|
152
160
|
status: MediaDeclarationStatus;
|
|
153
|
-
id
|
|
161
|
+
id: string;
|
|
154
162
|
}
|
|
155
163
|
|
|
156
164
|
declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
|
|
157
165
|
declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
|
|
158
166
|
```
|
|
159
167
|
|
|
160
|
-
- `key` is a stable, namespaced
|
|
161
|
-
- A folder goes at the library root, under the declared folder
|
|
162
|
-
- A file goes into a declared folder (`{ key }`) or into the folder bound to an asset field (`{ binding }
|
|
163
|
-
- The
|
|
164
|
-
- `tenantId` is required in TypeScript and at runtime.
|
|
165
|
-
- `id` in the result is the library
|
|
166
|
-
|
|
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
|
-
}
|
|
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.
|
|
199
174
|
|
|
200
|
-
|
|
175
|
+
### Written once
|
|
201
176
|
|
|
202
|
-
|
|
203
|
-
kind: MediaContentKind;
|
|
204
|
-
key: string;
|
|
205
|
-
status: MediaRetirementStatus;
|
|
206
|
-
id?: string;
|
|
207
|
-
}
|
|
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:
|
|
208
178
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
```
|
|
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.
|
|
212
181
|
|
|
213
|
-
|
|
214
|
-
|
|
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`).
|
|
219
|
-
|
|
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.
|
|
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.
|
|
221
183
|
|
|
222
184
|
### Validation and errors
|
|
223
185
|
|
|
224
|
-
Declarations follow the dashboard's rules
|
|
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:
|
|
225
187
|
|
|
226
|
-
- folder
|
|
227
|
-
-
|
|
228
|
-
-
|
|
229
|
-
-
|
|
230
|
-
-
|
|
231
|
-
-
|
|
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.
|
|
232
197
|
|
|
233
|
-
###
|
|
198
|
+
### When to call
|
|
234
199
|
|
|
235
|
-
|
|
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.
|
|
236
201
|
|
|
237
202
|
### Tenant scope and trusted backend context
|
|
238
203
|
|
|
239
|
-
`tenantId` selects the existing DMS tenant schema instance
|
|
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.
|
|
240
205
|
|
|
241
|
-
These are trusted backend APIs, not authorization endpoints. They need the media implementation, the selected tenant's database instance and reachable file storage
|
|
242
|
-
|
|
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.
|
|
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`.
|
|
244
207
|
|
|
245
208
|
```ts docs-check
|
|
209
|
+
import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
|
|
246
210
|
import {
|
|
247
211
|
EnsureMediaFolder,
|
|
248
212
|
ImportMediaAsset,
|
|
249
213
|
type MediaDeclarationResult,
|
|
250
214
|
} from "@antelopejs/interface-dms-media";
|
|
251
215
|
|
|
252
|
-
|
|
216
|
+
async function declareProcedures(tenantId: string, pdf: Uint8Array): Promise<MediaDeclarationResult[]> {
|
|
253
217
|
const root = await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
|
|
254
218
|
const safety = await EnsureMediaFolder({
|
|
255
219
|
tenantId,
|
|
@@ -270,38 +234,10 @@ export async function declareProcedures(tenantId: string, pdf: Uint8Array): Prom
|
|
|
270
234
|
});
|
|
271
235
|
return [root, safety, file];
|
|
272
236
|
}
|
|
273
|
-
```
|
|
274
237
|
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
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
|
-
},
|
|
238
|
+
export function construct(pdf: Uint8Array): void {
|
|
239
|
+
RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
|
|
240
|
+
await declareProcedures(tenantId, pdf);
|
|
297
241
|
});
|
|
298
242
|
}
|
|
299
243
|
```
|
|
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/docs/tsconfig.json
CHANGED
|
@@ -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.
|
|
3
|
+
"version": "0.3.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",
|
|
@@ -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
|
|
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
|
|
63
|
-
"@antelopejs/interface-
|
|
64
|
-
"@antelopejs/interface-
|
|
65
|
-
"@antelopejs/
|
|
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.12.0 <1.0.0",
|
|
66
|
+
"@antelopejs/tooling-configs": "^0.2.18",
|
|
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",
|
|
@@ -76,7 +74,7 @@
|
|
|
76
74
|
"peerDependencies": {
|
|
77
75
|
"@antelopejs/interface-api": ">=0.0.15 <1.0.0",
|
|
78
76
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
79
|
-
"@antelopejs/interface-dms": ">=0.
|
|
77
|
+
"@antelopejs/interface-dms": ">=0.9.0 <1.0.0"
|
|
80
78
|
},
|
|
81
79
|
"packageManager": "pnpm@10.2.0",
|
|
82
80
|
"antelopeJs": {}
|