@antelopejs/interface-dms-media 0.3.0 → 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 +18 -17
- 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 +48 -116
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -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`: idempotent per key, the content belongs to the members once written.
|
|
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
|
|
@@ -43,31 +43,32 @@ 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 values at runtime before writes. Existing users of these new APIs must pass it explicitly; older media APIs are unchanged.
|
|
65
|
+
Both declarations require `tenantId` in TypeScript and reject missing, empty or whitespace-only values at runtime before writes. Existing users of these new APIs must pass it explicitly; older media APIs are unchanged. Call them from a `Hook.TENANT_BEING_PROVISIONED` handler: see [When to call](./docs/1.index.md#when-to-call).
|
|
65
66
|
|
|
66
|
-
The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `MediaAssetDeclaration`, `MediaFolderTarget`, `MediaAssetSource`, `MediaLazySource`, `MediaDeclarationResult`, `MediaDeclarationStatus`, `
|
|
67
|
+
The interface also exports the option, declaration and ACL types: `AssetTypeOptions`, `AssetPickerComponentOptions`, `AssetBindingConfig`, `AssetPermissionMapping`, `MediaFolderDeclaration`, `MediaAssetDeclaration`, `MediaFolderTarget`, `MediaAssetSource`, `MediaLazySource`, `MediaDeclarationResult`, `MediaDeclarationStatus`, `AclEntry`, `AclSubject`, `AclSubjectKind` and `AclRight`.
|
|
67
68
|
|
|
68
69
|
## Compatibility
|
|
69
70
|
|
|
70
|
-
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:
|
|
71
72
|
|
|
72
73
|
<!-- docs-compat: ./package.json#peerDependencies -->
|
|
73
74
|
|
|
@@ -75,7 +76,7 @@ The implementation is `@antelopejs/dms-media >=0.4.0`; `EnsureMediaFolder` and `
|
|
|
75
76
|
| --- | --- |
|
|
76
77
|
| `@antelopejs/interface-api` | `>=0.0.15 <1.0.0` |
|
|
77
78
|
| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
|
|
78
|
-
| `@antelopejs/interface-dms` | `>=0.
|
|
79
|
+
| `@antelopejs/interface-dms` | `>=0.9.0 <1.0.0` |
|
|
79
80
|
|
|
80
81
|
## Documentation
|
|
81
82
|
|
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
|
@@ -7,6 +7,36 @@ description: Asset fields, folder binding lifecycle, declared content and permis
|
|
|
7
7
|
|
|
8
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
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.
|
|
39
|
+
|
|
10
40
|
## AssetType
|
|
11
41
|
|
|
12
42
|
```ts [Contract]
|
|
@@ -86,28 +116,6 @@ ACL rights imply weaker rights: `manage` ⇒ `write` ⇒ `read`. A role must exp
|
|
|
86
116
|
|
|
87
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.
|
|
88
118
|
|
|
89
|
-
## Declare a field
|
|
90
|
-
|
|
91
|
-
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.
|
|
92
|
-
|
|
93
|
-
```ts docs-check
|
|
94
|
-
import { AssetType } from "@antelopejs/interface-dms-media";
|
|
95
|
-
|
|
96
|
-
export const articleImages = new AssetType({
|
|
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
119
|
## EnsureMediaFolder and ImportMediaAsset
|
|
112
120
|
|
|
113
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.
|
|
@@ -141,98 +149,51 @@ interface MediaAssetDeclaration {
|
|
|
141
149
|
name: string;
|
|
142
150
|
mimetype: string;
|
|
143
151
|
source: MediaAssetSource;
|
|
144
|
-
version?: string;
|
|
145
152
|
alt?: string;
|
|
146
153
|
tenantId: string;
|
|
147
154
|
}
|
|
148
155
|
|
|
149
|
-
type MediaDeclarationStatus = "created" | "
|
|
156
|
+
type MediaDeclarationStatus = "created" | "kept";
|
|
150
157
|
|
|
151
158
|
interface MediaDeclarationResult {
|
|
152
159
|
status: MediaDeclarationStatus;
|
|
153
|
-
id
|
|
160
|
+
id: string;
|
|
154
161
|
}
|
|
155
162
|
|
|
156
163
|
declare function EnsureMediaFolder(declaration: MediaFolderDeclaration): Promise<MediaDeclarationResult>;
|
|
157
164
|
declare function ImportMediaAsset(declaration: MediaAssetDeclaration): Promise<MediaDeclarationResult>;
|
|
158
165
|
```
|
|
159
166
|
|
|
160
|
-
- `key` is a stable, namespaced id you choose, such as `helio.procedures`. Declarations are keyed by tenant, kind and key:
|
|
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.
|
|
161
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).
|
|
162
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.
|
|
163
|
-
- The source is read only when
|
|
170
|
+
- The source is read only when the file is created: a key declared before is `kept` without reading it.
|
|
164
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.
|
|
165
172
|
- `id` in the result is the library id of the folder or file, to store in an `AssetType` value for example.
|
|
166
173
|
|
|
167
|
-
###
|
|
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
|
-
}
|
|
199
|
-
|
|
200
|
-
type MediaRetirementStatus = "removed" | "preserved" | "deleted" | "unknown";
|
|
201
|
-
|
|
202
|
-
interface MediaRetirementResult {
|
|
203
|
-
kind: MediaContentKind;
|
|
204
|
-
key: string;
|
|
205
|
-
status: MediaRetirementStatus;
|
|
206
|
-
id?: string;
|
|
207
|
-
}
|
|
208
|
-
|
|
209
|
-
declare function RetireMediaDeclaration(retirement: MediaDeclarationRetirement): Promise<MediaRetirementResult>;
|
|
210
|
-
declare function PruneMediaDeclarations(prune: MediaDeclarationPrune): Promise<MediaRetirementResult[]>;
|
|
211
|
-
```
|
|
174
|
+
### Written once
|
|
212
175
|
|
|
213
|
-
|
|
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:
|
|
214
177
|
|
|
215
|
-
1.
|
|
216
|
-
2. The
|
|
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`).
|
|
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.
|
|
219
180
|
|
|
220
|
-
|
|
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.
|
|
221
182
|
|
|
222
183
|
### Validation and errors
|
|
223
184
|
|
|
224
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`:
|
|
225
186
|
|
|
226
187
|
- folder names refuse `/ \ < > : " | ? *` and control characters, stay within 255 characters and must be unique among their siblings, case and Unicode form aside;
|
|
227
|
-
- a `parent` or `{ key }` folder must have been declared first;
|
|
228
|
-
- a folder cannot name itself as its parent
|
|
188
|
+
- a `parent` or `{ key }` folder must have been declared first, and not deleted since;
|
|
189
|
+
- a folder cannot name itself as its parent;
|
|
229
190
|
- a `{ binding }` folder must have been registered, and a `{ binding }` parent must allow `subfolders`;
|
|
230
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;
|
|
231
192
|
- alt text stays within 255 characters.
|
|
232
193
|
|
|
233
|
-
###
|
|
194
|
+
### When to call
|
|
234
195
|
|
|
235
|
-
|
|
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.
|
|
236
197
|
|
|
237
198
|
### Tenant scope and trusted backend context
|
|
238
199
|
|
|
@@ -240,16 +201,15 @@ A call made before the runtime is loaded is queued by the interface, and the run
|
|
|
240
201
|
|
|
241
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`.
|
|
242
203
|
|
|
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.
|
|
244
|
-
|
|
245
204
|
```ts docs-check
|
|
205
|
+
import { Hook, RegisterHook } from "@antelopejs/interface-dms/hooks";
|
|
246
206
|
import {
|
|
247
207
|
EnsureMediaFolder,
|
|
248
208
|
ImportMediaAsset,
|
|
249
209
|
type MediaDeclarationResult,
|
|
250
210
|
} from "@antelopejs/interface-dms-media";
|
|
251
211
|
|
|
252
|
-
|
|
212
|
+
async function declareProcedures(tenantId: string, pdf: Uint8Array): Promise<MediaDeclarationResult[]> {
|
|
253
213
|
const root = await EnsureMediaFolder({ tenantId, key: "helio.procedures", name: "Procedures" });
|
|
254
214
|
const safety = await EnsureMediaFolder({
|
|
255
215
|
tenantId,
|
|
@@ -270,38 +230,10 @@ export async function declareProcedures(tenantId: string, pdf: Uint8Array): Prom
|
|
|
270
230
|
});
|
|
271
231
|
return [root, safety, file];
|
|
272
232
|
}
|
|
273
|
-
```
|
|
274
233
|
|
|
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
|
-
},
|
|
234
|
+
export function construct(pdf: Uint8Array): void {
|
|
235
|
+
RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
|
|
236
|
+
await declareProcedures(tenantId, pdf);
|
|
297
237
|
});
|
|
298
238
|
}
|
|
299
239
|
```
|
|
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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antelopejs/interface-dms-media",
|
|
3
|
-
"version": "0.3.
|
|
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": {}
|