@antelopejs/interface-dms-media 0.2.2 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +27 -5
- package/dist/bindings.d.ts +1 -4
- package/dist/bindings.js +3 -8
- package/dist/bindings.js.map +1 -1
- package/dist/content.d.ts +43 -0
- package/dist/content.js +12 -0
- package/dist/content.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/internal.d.ts +8 -0
- package/dist/internal.js +11 -0
- package/dist/internal.js.map +1 -0
- package/docs/1.index.md +152 -19
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
|
|
8
8
|
<a href="https://dms.antelopejs.com/docs/modules/media/extending"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
|
|
9
9
|
|
|
10
|
-
The AntelopeJS interface to add media library fields, and the folders bound to them, to DMS pages.
|
|
10
|
+
The AntelopeJS interface to add media library fields, and the folders bound to them, to DMS pages, and to ship library folders and files as code.
|
|
11
11
|
|
|
12
12
|
</div>
|
|
13
13
|
|
|
@@ -17,6 +17,7 @@ The AntelopeJS interface to add media library fields, and the folders bound to t
|
|
|
17
17
|
- Binds a field to a folder provisioned under the `Content` root of each tenant: `RegisterAssetBinding` and `UnregisterAssetBinding`, or `new AssetType({ binding })`.
|
|
18
18
|
- Derives the folder's rights from a page (`permissionsFromPage`), a `permissionMapping` or an explicit `acl`.
|
|
19
19
|
- Replays bindings to every new generation of the implementation, so either side can hot reload.
|
|
20
|
+
- Ships folders and files from backend code with `EnsureMediaFolder` and `ImportMediaAsset`, called once per tenant from `Hook.TENANT_BEING_PROVISIONED`: idempotent per key, the content belongs to the members once written.
|
|
20
21
|
- Keeps your module independent of the implementation, [`@antelopejs/dms-media`](https://www.npmjs.com/package/@antelopejs/dms-media).
|
|
21
22
|
|
|
22
23
|
## Install
|
|
@@ -42,11 +43,32 @@ new AssetType({
|
|
|
42
43
|
});
|
|
43
44
|
```
|
|
44
45
|
|
|
45
|
-
|
|
46
|
+
Ship a folder and a file with each new tenant, from the hook the DMS fires once when the tenant is created:
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { EnsureMediaFolder, ImportMediaAsset } from "@antelopejs/interface-dms-media";
|
|
50
|
+
import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
|
|
51
|
+
|
|
52
|
+
RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
|
|
53
|
+
await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
|
|
54
|
+
await ImportMediaAsset({
|
|
55
|
+
tenantId,
|
|
56
|
+
key: "helio.procedures.roof",
|
|
57
|
+
folder: { key: "helio.procedures" },
|
|
58
|
+
name: "Roof safety checklist.pdf",
|
|
59
|
+
mimetype: "application/pdf",
|
|
60
|
+
source: { filePath: "/srv/content/roof-safety-checklist.pdf" },
|
|
61
|
+
});
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Both declarations require `tenantId` in TypeScript and reject missing, empty or whitespace-only values at runtime before writes. Existing users of these new APIs must pass it explicitly; older media APIs are unchanged. Call them from a `Hook.TENANT_BEING_PROVISIONED` handler: see [When to call](./docs/1.index.md#when-to-call).
|
|
66
|
+
|
|
67
|
+
The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `MediaAssetDeclaration`, `MediaFolderTarget`, `MediaAssetSource`, `MediaLazySource`, `MediaDeclarationResult`, `MediaDeclarationStatus`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
|
|
46
68
|
|
|
47
69
|
## Compatibility
|
|
48
70
|
|
|
49
|
-
The
|
|
71
|
+
The 0.3 interface line requires `@antelopejs/dms-media >=0.5.0` for `EnsureMediaFolder` and `ImportMediaAsset`. Media 0.4 uses the 0.2 interface line. The interface declares these peer dependencies:
|
|
50
72
|
|
|
51
73
|
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
52
74
|
|
|
@@ -54,11 +76,11 @@ The implementation is `@antelopejs/dms-media >=0.4.0`. The interface declares th
|
|
|
54
76
|
| --- | --- |
|
|
55
77
|
| `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
|
|
56
78
|
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
57
|
-
| `@antelopejs/interface-dms` | `>=0.
|
|
79
|
+
| `@antelopejs/interface-dms` | `>=0.9.0 <1.0.0` |
|
|
58
80
|
|
|
59
81
|
## Documentation
|
|
60
82
|
|
|
61
|
-
- [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle and permission precedence
|
|
83
|
+
- [Consumer reference](./docs/1.index.md): field types, bindings, lifecycle, declared content and permission precedence
|
|
62
84
|
- [Extending the media module](https://dms.antelopejs.com/docs/modules/media/extending): asset fields, folder bindings, the HTTP API and delivery URLs
|
|
63
85
|
- [The asset field](https://dms.antelopejs.com/docs/modules/media/usage/asset-field)
|
|
64
86
|
- [Media module guide](https://dms.antelopejs.com/docs/modules/media)
|
package/dist/bindings.d.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import type { ControllerClass } from "@antelopejs/interface-api";
|
|
2
|
-
import { RegisteringProxy } from "@antelopejs/interface-core";
|
|
3
2
|
import type { AclEntry } from "./acl";
|
|
4
3
|
export interface AssetPermissionMapping {
|
|
5
4
|
read?: string[];
|
|
@@ -16,10 +15,8 @@ export interface AssetBindingConfig {
|
|
|
16
15
|
permissionMapping?: AssetPermissionMapping;
|
|
17
16
|
permissionsFromPage?: ControllerClass;
|
|
18
17
|
acl?: AclEntry[];
|
|
18
|
+
subfolders?: boolean;
|
|
19
19
|
field?: AssetBindingField;
|
|
20
20
|
}
|
|
21
|
-
export declare namespace internal {
|
|
22
|
-
const RegisterAssetBinding: RegisteringProxy<(id: string, config: AssetBindingConfig) => void>;
|
|
23
|
-
}
|
|
24
21
|
export declare function RegisterAssetBinding(config: AssetBindingConfig): void;
|
|
25
22
|
export declare function UnregisterAssetBinding(id: string): void;
|
package/dist/bindings.js
CHANGED
|
@@ -1,17 +1,12 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.internal = void 0;
|
|
4
3
|
exports.RegisterAssetBinding = RegisterAssetBinding;
|
|
5
4
|
exports.UnregisterAssetBinding = UnregisterAssetBinding;
|
|
6
|
-
const
|
|
7
|
-
var internal;
|
|
8
|
-
(function (internal) {
|
|
9
|
-
internal.RegisterAssetBinding = new interface_core_1.RegisteringProxy();
|
|
10
|
-
})(internal || (exports.internal = internal = {}));
|
|
5
|
+
const internal_1 = require("./internal");
|
|
11
6
|
function RegisterAssetBinding(config) {
|
|
12
|
-
internal.RegisterAssetBinding.register(config.id, config);
|
|
7
|
+
internal_1.internal.RegisterAssetBinding.register(config.id, config);
|
|
13
8
|
}
|
|
14
9
|
function UnregisterAssetBinding(id) {
|
|
15
|
-
internal.RegisterAssetBinding.unregister(id);
|
|
10
|
+
internal_1.internal.RegisterAssetBinding.unregister(id);
|
|
16
11
|
}
|
|
17
12
|
//# sourceMappingURL=bindings.js.map
|
package/dist/bindings.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"bindings.js","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":";;AAoDA,oDAEC;AAGD,wDAEC;AAzDD,yCAAsC;AAkDtC,SAAgB,oBAAoB,CAAC,MAA0B;IAC7D,mBAAQ,CAAC,oBAAoB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAGD,SAAgB,sBAAsB,CAAC,EAAU;IAC/C,mBAAQ,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { AclEntry } from "./acl";
|
|
2
|
+
export type MediaFolderVisibility = "private" | "public";
|
|
3
|
+
export interface MediaFolderDeclaration {
|
|
4
|
+
key: string;
|
|
5
|
+
name: string;
|
|
6
|
+
parent?: string | MediaFolderTarget;
|
|
7
|
+
visibility?: MediaFolderVisibility;
|
|
8
|
+
acl?: AclEntry[];
|
|
9
|
+
tenantId: string;
|
|
10
|
+
}
|
|
11
|
+
export interface DeclaredFolderTarget {
|
|
12
|
+
key: string;
|
|
13
|
+
}
|
|
14
|
+
export interface BoundFolderTarget {
|
|
15
|
+
binding: string;
|
|
16
|
+
}
|
|
17
|
+
export type MediaFolderTarget = DeclaredFolderTarget | BoundFolderTarget;
|
|
18
|
+
export interface MediaBytesSource {
|
|
19
|
+
bytes: Uint8Array;
|
|
20
|
+
}
|
|
21
|
+
export interface MediaFileSource {
|
|
22
|
+
filePath: string;
|
|
23
|
+
}
|
|
24
|
+
export interface MediaLazySource {
|
|
25
|
+
load: () => Uint8Array | Promise<Uint8Array>;
|
|
26
|
+
}
|
|
27
|
+
export type MediaAssetSource = MediaBytesSource | MediaFileSource | MediaLazySource;
|
|
28
|
+
export interface MediaAssetDeclaration {
|
|
29
|
+
key: string;
|
|
30
|
+
folder: MediaFolderTarget;
|
|
31
|
+
name: string;
|
|
32
|
+
mimetype: string;
|
|
33
|
+
source: MediaAssetSource;
|
|
34
|
+
alt?: string;
|
|
35
|
+
tenantId: string;
|
|
36
|
+
}
|
|
37
|
+
export type MediaDeclarationStatus = "created" | "kept";
|
|
38
|
+
export interface MediaDeclarationResult {
|
|
39
|
+
status: MediaDeclarationStatus;
|
|
40
|
+
id: string;
|
|
41
|
+
}
|
|
42
|
+
export declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
|
|
43
|
+
export declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
|
package/dist/content.js
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.EnsureMediaFolder = EnsureMediaFolder;
|
|
4
|
+
exports.ImportMediaAsset = ImportMediaAsset;
|
|
5
|
+
const internal_1 = require("./internal");
|
|
6
|
+
function EnsureMediaFolder(declaration) {
|
|
7
|
+
return internal_1.internal.EnsureMediaFolder(declaration);
|
|
8
|
+
}
|
|
9
|
+
function ImportMediaAsset(declaration) {
|
|
10
|
+
return internal_1.internal.ImportMediaAsset(declaration);
|
|
11
|
+
}
|
|
12
|
+
//# sourceMappingURL=content.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"content.js","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":";;AAuGA,8CAIC;AAaD,4CAIC;AA3HD,yCAAsC;AAsGtC,SAAgB,iBAAiB,CAC/B,WAAmC;IAEnC,OAAO,mBAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AAaD,SAAgB,gBAAgB,CAC9B,WAAkC;IAElC,OAAO,mBAAQ,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;AAChD,CAAC"}
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
|
|
|
17
17
|
__exportStar(require("./acl"), exports);
|
|
18
18
|
__exportStar(require("./asset-type"), exports);
|
|
19
19
|
__exportStar(require("./bindings"), exports);
|
|
20
|
+
__exportStar(require("./content"), exports);
|
|
21
|
+
__exportStar(require("./internal"), exports);
|
|
20
22
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,+CAA6B;AAC7B,6CAA2B"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wCAAsB;AACtB,+CAA6B;AAC7B,6CAA2B;AAC3B,4CAA0B;AAC1B,6CAA2B"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { RegisteringProxy } from "@antelopejs/interface-core";
|
|
2
|
+
import type { AssetBindingConfig } from "./bindings";
|
|
3
|
+
import type { MediaAssetDeclaration, MediaDeclarationResult, MediaFolderDeclaration } from "./content";
|
|
4
|
+
export declare namespace internal {
|
|
5
|
+
const RegisterAssetBinding: RegisteringProxy<(id: string, config: AssetBindingConfig) => void>;
|
|
6
|
+
const EnsureMediaFolder: (declaration: MediaFolderDeclaration) => Promise<MediaDeclarationResult>;
|
|
7
|
+
const ImportMediaAsset: (declaration: MediaAssetDeclaration) => Promise<MediaDeclarationResult>;
|
|
8
|
+
}
|
package/dist/internal.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.internal = void 0;
|
|
4
|
+
const interface_core_1 = require("@antelopejs/interface-core");
|
|
5
|
+
var internal;
|
|
6
|
+
(function (internal) {
|
|
7
|
+
internal.RegisterAssetBinding = new interface_core_1.RegisteringProxy();
|
|
8
|
+
internal.EnsureMediaFolder = (0, interface_core_1.InterfaceFunction)();
|
|
9
|
+
internal.ImportMediaAsset = (0, interface_core_1.InterfaceFunction)();
|
|
10
|
+
})(internal || (exports.internal = internal = {}));
|
|
11
|
+
//# sourceMappingURL=internal.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":";;;AAAA,+DAGoC;AAWpC,IAAiB,QAAQ,CAYxB;AAZD,WAAiB,QAAQ;IACV,6BAAoB,GAAG,IAAI,iCAAgB,EAErD,CAAC;IACS,0BAAiB,GAC5B,IAAA,kCAAiB,GAEd,CAAC;IACO,yBAAgB,GAC3B,IAAA,kCAAiB,GAEd,CAAC;AACR,CAAC,EAZgB,QAAQ,wBAAR,QAAQ,QAYxB"}
|
package/docs/1.index.md
CHANGED
|
@@ -1,11 +1,41 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Media interface
|
|
3
|
-
description: Asset fields, folder binding lifecycle and permission contracts for DMS consumers.
|
|
3
|
+
description: Asset fields, folder binding lifecycle, declared content and permission contracts for DMS consumers.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Media interface
|
|
7
7
|
|
|
8
|
-
`@antelopejs/interface-dms-media` exports the asset field and folder binding declarations. Load the Media runtime for the picker, uploads and provisioning. HTTP routes and delivery URLs remain in the [runtime guide](/docs/modules/media/extending#http-surface).
|
|
8
|
+
`@antelopejs/interface-dms-media` exports the asset field and folder binding declarations, and the functions that ship library folders and files as code. Load the Media runtime for the picker, uploads and provisioning. HTTP routes and delivery URLs remain in the [runtime guide](/docs/modules/media/extending#http-surface).
|
|
9
|
+
|
|
10
|
+
## Declare a field
|
|
11
|
+
|
|
12
|
+
This field stores up to four asset IDs and registers a tenant-local upload folder.
|
|
13
|
+
Place it in a DMS form. The permission IDs are application-defined and must be
|
|
14
|
+
granted by the project's role configuration.
|
|
15
|
+
|
|
16
|
+
```ts docs-check
|
|
17
|
+
import { AssetType } from "@antelopejs/interface-dms-media";
|
|
18
|
+
|
|
19
|
+
export const articleImages = new AssetType({
|
|
20
|
+
multiple: true,
|
|
21
|
+
max: 4,
|
|
22
|
+
mimetypes: ["image/*"],
|
|
23
|
+
binding: {
|
|
24
|
+
id: "articles.images",
|
|
25
|
+
folderName: "Article images",
|
|
26
|
+
permissionMapping: {
|
|
27
|
+
read: ["articles.page"],
|
|
28
|
+
write: ["articles.page.table.edit"],
|
|
29
|
+
},
|
|
30
|
+
},
|
|
31
|
+
});
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Selecting two images produces a value such as `["asset-a", "asset-b"]`, not two
|
|
35
|
+
URLs. An empty selection is `[]`. A fifth ID fails the field's shape validation,
|
|
36
|
+
but an unknown nonempty ID does not: the consuming write path still needs to
|
|
37
|
+
check asset existence, tenant ownership and type. See the
|
|
38
|
+
[picker example](/docs/modules/media/extending#add-an-asset-field) for the UI.
|
|
9
39
|
|
|
10
40
|
## AssetType
|
|
11
41
|
|
|
@@ -60,6 +90,7 @@ interface AssetBindingConfig {
|
|
|
60
90
|
permissionMapping?: AssetPermissionMapping;
|
|
61
91
|
permissionsFromPage?: ControllerClass;
|
|
62
92
|
acl?: AclEntry[];
|
|
93
|
+
subfolders?: boolean;
|
|
63
94
|
field?: AssetBindingField;
|
|
64
95
|
}
|
|
65
96
|
|
|
@@ -71,7 +102,9 @@ All these types and functions are available from the package root. The exported
|
|
|
71
102
|
|
|
72
103
|
Use a stable, namespaced ID such as `articles.cover`. Registrations are keyed by ID, so reusing an ID replaces its declaration rather than creating an independent binding. Registration returns synchronously; it does not await folder creation. The calling module owns the registration: unloading it releases the declaration, and reloading the implementation replays active registrations.
|
|
73
104
|
|
|
74
|
-
The runtime provisions each tenant separately, under a private `Content` root. A new folder uses `folderName ?? id`; an existing bound folder retains its name and gets the current ACL. `UnregisterAssetBinding` removes the declaration but leaves provisioned folders and files in place.
|
|
105
|
+
The runtime provisions each tenant separately, under a private `Content` root. A new folder uses `folderName ?? id`; an existing bound folder retains its name and gets the current ACL. `UnregisterAssetBinding` removes the declaration but leaves provisioned folders and files in place.
|
|
106
|
+
|
|
107
|
+
A bound folder is locked: it cannot be renamed, moved, deleted or re-permissioned, and by default it holds no subfolders. `subfolders: true` lets it hold them, for a layout per record such as one folder per project under the field's folder. Owners then create subfolders in the library, and backend code declares them with `EnsureMediaFolder({ parent: { binding } })`; the bound folder itself stays locked. A subfolder inherits the bound folder's ACL unless it has its own, and accepts only the types the field accepts, like the bound folder. The field's picker opens on the bound folder and browses its subfolders; its upload button still targets the bound folder. Neither function returns an upload result or a provisioning error; provisioning/storage failures occur when runtime operations ensure the tenant's folders.
|
|
75
108
|
|
|
76
109
|
## Permission precedence and tenant access
|
|
77
110
|
|
|
@@ -83,24 +116,124 @@ ACL rights imply weaker rights: `manage` ⇒ `write` ⇒ `read`. A role must exp
|
|
|
83
116
|
|
|
84
117
|
Owners hold every folder right. Uploading and changing files require folder `write`; folder structure changes require `manage`. File and folder visibility changes stay owner-only. A writable linked folder lets a member modify its files regardless of who uploaded them. The default root ACL grants no member access; configure `rootAcl` deliberately because its grants can open the rest of the library.
|
|
85
118
|
|
|
86
|
-
##
|
|
119
|
+
## EnsureMediaFolder and ImportMediaAsset
|
|
87
120
|
|
|
88
|
-
|
|
121
|
+
A project ships media content (templates, procedures, demo pictures) from its backend code with these two functions. The Media runtime creates the content itself: it validates it with the dashboard's rules, writes the bytes to its configured file storage, computes image dimensions and records the creation in the library activity. Never write the runtime's tables yourself.
|
|
122
|
+
|
|
123
|
+
```ts [Contract]
|
|
124
|
+
import type { AclEntry } from "@antelopejs/interface-dms-media";
|
|
125
|
+
|
|
126
|
+
type MediaFolderVisibility = "private" | "public";
|
|
127
|
+
|
|
128
|
+
interface MediaFolderDeclaration {
|
|
129
|
+
key: string;
|
|
130
|
+
name: string;
|
|
131
|
+
parent?: string | MediaFolderTarget;
|
|
132
|
+
visibility?: MediaFolderVisibility;
|
|
133
|
+
acl?: AclEntry[];
|
|
134
|
+
tenantId: string;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
interface DeclaredFolderTarget { key: string; }
|
|
138
|
+
interface BoundFolderTarget { binding: string; }
|
|
139
|
+
type MediaFolderTarget = DeclaredFolderTarget | BoundFolderTarget;
|
|
140
|
+
|
|
141
|
+
interface MediaBytesSource { bytes: Uint8Array; }
|
|
142
|
+
interface MediaFileSource { filePath: string; }
|
|
143
|
+
interface MediaLazySource { load: () => Uint8Array | Promise<Uint8Array>; }
|
|
144
|
+
type MediaAssetSource = MediaBytesSource | MediaFileSource | MediaLazySource;
|
|
145
|
+
|
|
146
|
+
interface MediaAssetDeclaration {
|
|
147
|
+
key: string;
|
|
148
|
+
folder: MediaFolderTarget;
|
|
149
|
+
name: string;
|
|
150
|
+
mimetype: string;
|
|
151
|
+
source: MediaAssetSource;
|
|
152
|
+
alt?: string;
|
|
153
|
+
tenantId: string;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
type MediaDeclarationStatus = "created" | "kept";
|
|
157
|
+
|
|
158
|
+
interface MediaDeclarationResult {
|
|
159
|
+
status: MediaDeclarationStatus;
|
|
160
|
+
id: string;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
|
|
164
|
+
declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
- `key` is a stable, namespaced id you choose, such as `helio.procedures`. Declarations are keyed by tenant, kind and key: each folder and file is created once.
|
|
168
|
+
- A folder goes at the library root, under the declared folder named by `parent` (its key, or `{ key }`), or under the folder bound to an asset field (`{ binding }`) when that binding sets `subfolders: true`. `visibility` defaults to `private`; without `acl` the folder inherits its parent's ACL (the `rootAcl` at the root).
|
|
169
|
+
- A file goes into a declared folder (`{ key }`) or into the folder bound to an asset field (`{ binding }`, the `id` given to `AssetType` or `RegisterAssetBinding`, which the runtime provisions first). `source` is the content in memory (`bytes`), a path on the backend's file system (`filePath`) or a function producing it (`load`). `name` is the file name shown in the library, extension included.
|
|
170
|
+
- The source is read only when the file is created: a key declared before is `kept` without reading it.
|
|
171
|
+
- `tenantId` is required in TypeScript and at runtime. Omission, an empty string or whitespace-only input rejects before database writes or source reads. There is no default fallback; passing `DEFAULT_TENANT_ID` explicitly remains valid. Existing callers of these new APIs must add their trusted tenant id; older media APIs are unchanged.
|
|
172
|
+
- `id` in the result is the library id of the folder or file, to store in an `AssetType` value for example.
|
|
173
|
+
|
|
174
|
+
### Written once
|
|
175
|
+
|
|
176
|
+
Declared content is written once, when the tenant is provisioned (see [When to call](#when-to-call)), and belongs to the tenant's members from then on. Nothing replays a declaration on a later boot, so nothing compares the library with the code nor takes content back:
|
|
177
|
+
|
|
178
|
+
1. No row was declared for the key in this tenant: the folder or file is created (`created`), and the runtime remembers its id under the key, so a later declaration can name it as a `parent` or `{ key }` folder.
|
|
179
|
+
2. The key was declared before, by an earlier or retried provisioning: nothing is written and the source is not read (`kept`). The result carries the id of the row created then.
|
|
180
|
+
|
|
181
|
+
Only creations are recorded in the activity, attributed to `System`, as `folder.create` and `asset.upload`. Use one declaration writer per tenant and key: the queue is process-local, and creation, storage, activity and declaration bookkeeping are not a single transaction.
|
|
182
|
+
|
|
183
|
+
### Validation and errors
|
|
184
|
+
|
|
185
|
+
Declarations follow the dashboard's rules and reject with an error naming the kind, the key and the reason, such as `Media folder 'helio.procedures': a folder named 'Procedures' already exists there`:
|
|
186
|
+
|
|
187
|
+
- folder names refuse `/ \ < > : " | ? *` and control characters, stay within 255 characters and must be unique among their siblings, case and Unicode form aside;
|
|
188
|
+
- a `parent` or `{ key }` folder must have been declared first, and not deleted since;
|
|
189
|
+
- a folder cannot name itself as its parent;
|
|
190
|
+
- a `{ binding }` folder must have been registered, and a `{ binding }` parent must allow `subfolders`;
|
|
191
|
+
- a file must be of an allowed type (`allowedMimetypes`, never HTML, XHTML or PHP), of a type the bound field accepts, within the storage quota and the 500 MB upload limit, and a decodable image when its mimetype says so; the stored mimetype is the decoded format's, as for an upload;
|
|
192
|
+
- alt text stays within 255 characters.
|
|
193
|
+
|
|
194
|
+
### When to call
|
|
195
|
+
|
|
196
|
+
Call them from a `Hook.TENANT_BEING_PROVISIONED` handler registered in your module's `construct()`. The DMS fires it once per tenant, when the tenant is created: for the `default` tenant on the DMS start that creates it, once every `Hook.DATABASE_INITIALIZED` handler has finished, and for each workspace a SaaS module creates. The tenant's tables exist by then, and files are written through the storage's `WriteFile`, so nothing waits. Never call them from `start()` or `DATABASE_INITIALIZED`, which run on every boot. Declare a parent before its children and a folder before its files, awaiting each call.
|
|
197
|
+
|
|
198
|
+
### Tenant scope and trusted backend context
|
|
199
|
+
|
|
200
|
+
`tenantId` selects the existing DMS tenant schema instance for the folders, files and declaration registry. Parent keys and bindings resolve within that tenant, and the same declaration key can be used independently in different tenants. Both functions require a nonblank explicit tenant; neither infers it from an HTTP session or a SaaS workspace context. Surrounding whitespace is trimmed.
|
|
201
|
+
|
|
202
|
+
These are trusted backend APIs, not authorization endpoints. They need the media implementation, the selected tenant's database instance and reachable file storage; they do not require a signed-in user, create a workspace, check payment status or decide when workspace provisioning is committed. Storage paths include the tenant id, but the storage backend and upload policy remain module configuration. Events are attributed to `System`.
|
|
89
203
|
|
|
90
204
|
```ts docs-check
|
|
91
|
-
import {
|
|
205
|
+
import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
|
|
206
|
+
import {
|
|
207
|
+
EnsureMediaFolder,
|
|
208
|
+
ImportMediaAsset,
|
|
209
|
+
type MediaDeclarationResult,
|
|
210
|
+
} from "@antelopejs/interface-dms-media";
|
|
211
|
+
|
|
212
|
+
async function declareProcedures(tenantId: string, pdf: Uint8Array): Promise<MediaDeclarationResult[]> {
|
|
213
|
+
const root = await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
|
|
214
|
+
const safety = await EnsureMediaFolder({
|
|
215
|
+
tenantId,
|
|
216
|
+
key: "helio.procedures.safety",
|
|
217
|
+
name: "Safety",
|
|
218
|
+
parent: "helio.procedures",
|
|
219
|
+
acl: [
|
|
220
|
+
{ subject: { kind: "permission", id: "projects.page" }, rights: ["read"] },
|
|
221
|
+
],
|
|
222
|
+
});
|
|
223
|
+
const file = await ImportMediaAsset({
|
|
224
|
+
tenantId,
|
|
225
|
+
key: "helio.procedures.safety.roof",
|
|
226
|
+
folder: { key: "helio.procedures.safety" },
|
|
227
|
+
name: "Roof safety checklist.pdf",
|
|
228
|
+
mimetype: "application/pdf",
|
|
229
|
+
source: { bytes: pdf },
|
|
230
|
+
});
|
|
231
|
+
return [root, safety, file];
|
|
232
|
+
}
|
|
92
233
|
|
|
93
|
-
export
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
id: "articles.images",
|
|
99
|
-
folderName: "Article images",
|
|
100
|
-
permissionMapping: {
|
|
101
|
-
read: ["articles.page"],
|
|
102
|
-
write: ["articles.page.table.edit"],
|
|
103
|
-
},
|
|
104
|
-
},
|
|
105
|
-
});
|
|
234
|
+
export function construct(pdf: Uint8Array): void {
|
|
235
|
+
RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
|
|
236
|
+
await declareProcedures(tenantId, pdf);
|
|
237
|
+
});
|
|
238
|
+
}
|
|
106
239
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-dms-media",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "AntelopeJS interface for the DMS media module: declare asset fields and the media folders bound to them from any module",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"antelopejs",
|
|
@@ -61,7 +61,7 @@
|
|
|
61
61
|
"devDependencies": {
|
|
62
62
|
"@antelopejs/interface-api": ">=0.0.15 <1.0.0",
|
|
63
63
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
64
|
-
"@antelopejs/interface-dms": ">=0.
|
|
64
|
+
"@antelopejs/interface-dms": ">=0.9.0 <1.0.0",
|
|
65
65
|
"@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
|
|
66
66
|
"@types/node": "^24.0.0",
|
|
67
67
|
"knip": "^6.34.0",
|
|
@@ -76,7 +76,7 @@
|
|
|
76
76
|
"peerDependencies": {
|
|
77
77
|
"@antelopejs/interface-api": ">=0.0.15 <1.0.0",
|
|
78
78
|
"@antelopejs/interface-core": ">=0.2.4 <1.0.0",
|
|
79
|
-
"@antelopejs/interface-dms": ">=0.
|
|
79
|
+
"@antelopejs/interface-dms": ">=0.9.0 <1.0.0"
|
|
80
80
|
},
|
|
81
81
|
"packageManager": "pnpm@10.2.0",
|
|
82
82
|
"antelopeJs": {}
|