@epekta/armarius-astro 0.0.0-stage → 0.1.0

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.
@@ -0,0 +1,255 @@
1
+ import { readFile, stat } from 'node:fs/promises';
2
+ import { dirname, extname, isAbsolute, resolve } from 'node:path';
3
+ import { httpOrigin } from '../options.js';
4
+ import { FILE_PICKER_TYPE, isRelation, keyFieldError, normalizeKey, parseImportFile, relationColumn, RELATIONSHIP_TYPE, valueShapeError, } from './format.js';
5
+ import { FILE_TYPES, readAllRecords, readCrudFields, redactSecrets, WebserviceSession } from './webservice.js';
6
+ export const IMPORT_SYNOPSIS = 'armarius-astro import <file> [--dry-run]';
7
+ /** Images go up one by one: a delay of its own, longer than a build's read. */
8
+ const IMPORT_TIMEOUT_MS = 30_000;
9
+ const IMPORT_RETRIES = 3;
10
+ function parseArguments(args) {
11
+ const positional = args.filter(arg => !arg.startsWith('--'));
12
+ const options = args.filter(arg => arg.startsWith('--'));
13
+ if (positional.length !== 1 || options.some(option => option !== '--dry-run'))
14
+ return null;
15
+ return { file: positional[0], dryRun: options.includes('--dry-run') };
16
+ }
17
+ /** Two relations to one CRUD may match on two columns: each pair gets its own index. */
18
+ function relationIndexKey(crud, column) {
19
+ return `${crud}\u0000${column}`;
20
+ }
21
+ /** Records of a CRUD by the normalized value of one column; a value shared by two records keeps both ids. */
22
+ function indexBy(records, column) {
23
+ const index = new Map();
24
+ for (const record of records) {
25
+ const value = normalizeKey(record[column]);
26
+ if (value === '')
27
+ continue;
28
+ index.set(value, [...(index.get(value) ?? []), record.id]);
29
+ }
30
+ return index;
31
+ }
32
+ async function isReadableFile(path) {
33
+ try {
34
+ return (await stat(path)).isFile();
35
+ }
36
+ catch {
37
+ return false;
38
+ }
39
+ }
40
+ /** Checks every record against the CRUD, its relations and the files on disk; nothing is written. */
41
+ async function planRecords(input, baseDirectory, fields, existing, relations) {
42
+ const keyCounts = new Map();
43
+ for (const record of input.records) {
44
+ const key = normalizeKey(record[input.key]);
45
+ keyCounts.set(key, (keyCounts.get(key) ?? 0) + 1);
46
+ }
47
+ const planned = [];
48
+ for (const [index, record] of input.records.entries()) {
49
+ const keyValue = record[input.key];
50
+ const key = normalizeKey(keyValue);
51
+ const label = key === '' ? `record ${index + 1}` : String(record[input.key]);
52
+ const errors = [];
53
+ const body = {};
54
+ const files = new Map();
55
+ if (typeof keyValue !== 'string' && typeof keyValue !== 'number')
56
+ errors.push(`${input.key}: the key must be a string or a number`);
57
+ else if (key === '')
58
+ errors.push(`${input.key}: the key is empty`);
59
+ else if ((keyCounts.get(key) ?? 0) > 1)
60
+ errors.push(`${input.key}: the key is in the file more than once`);
61
+ for (const field of fields.values()) {
62
+ if (field.required && (record[field.slug] === undefined || record[field.slug] === null)) {
63
+ errors.push(`${field.slug}: required`);
64
+ }
65
+ }
66
+ for (const [slug, value] of Object.entries(record)) {
67
+ const field = fields.get(slug);
68
+ if (field === undefined) {
69
+ errors.push(`${slug}: unknown field`);
70
+ continue;
71
+ }
72
+ const shapeError = valueShapeError(field, value);
73
+ if (shapeError !== null) {
74
+ errors.push(shapeError);
75
+ continue;
76
+ }
77
+ if (field.type === RELATIONSHIP_TYPE && isRelation(value)) {
78
+ const ids = relations.get(relationIndexKey(value.crud, relationColumn(field)))?.get(normalizeKey(value.name)) ?? [];
79
+ if (ids.length === 0)
80
+ errors.push(`${slug}: no record "${value.name}" in ${value.crud}`);
81
+ else if (ids.length > 1)
82
+ errors.push(`${slug}: ${ids.length} records "${value.name}" in ${value.crud}`);
83
+ else
84
+ body[slug] = ids[0];
85
+ continue;
86
+ }
87
+ if (field.type === FILE_PICKER_TYPE) {
88
+ const fileValues = (Array.isArray(value) ? value : [value]);
89
+ const paths = fileValues.map(fileValue => resolve(baseDirectory, fileValue.file));
90
+ for (const [position, path] of paths.entries()) {
91
+ const { file } = fileValues[position];
92
+ if (isAbsolute(file))
93
+ errors.push(`${slug}: ${file} is not relative to the input file`);
94
+ else if (FILE_TYPES[extname(file).toLowerCase()] === undefined)
95
+ errors.push(`${slug}: ${file} is not a file type the import sends`);
96
+ else if (!await isReadableFile(path))
97
+ errors.push(`${slug}: no file ${file}`);
98
+ }
99
+ files.set(slug, Array.isArray(value) ? paths : paths[0]);
100
+ continue;
101
+ }
102
+ body[slug] = value;
103
+ }
104
+ if (errors.length > 0)
105
+ planned.push({ label, status: 'error', errors });
106
+ else if (existing.has(key))
107
+ planned.push({ label, status: 'exists', id: existing.get(key)?.[0] });
108
+ else
109
+ planned.push({ label, status: 'create', body, files });
110
+ }
111
+ return planned;
112
+ }
113
+ async function createRecord(session, crud, planned) {
114
+ const body = { ...planned.body };
115
+ for (const [slug, paths] of planned.files) {
116
+ if (Array.isArray(paths)) {
117
+ const serverIds = [];
118
+ for (const path of paths)
119
+ serverIds.push({ serverId: await session.upload(path) });
120
+ body[slug] = serverIds;
121
+ }
122
+ else {
123
+ // A single file is sent as the bare serverId: an object there fails after a 201.
124
+ body[slug] = await session.upload(paths);
125
+ }
126
+ }
127
+ return session.create(crud, body, [...planned.files.keys()]);
128
+ }
129
+ function isSafeOrigin(origin) {
130
+ const { protocol, hostname } = new URL(origin);
131
+ return protocol === 'https:' || ['localhost', '127.0.0.1', '[::1]'].includes(hostname) || /\.(test|localhost)$/.test(hostname);
132
+ }
133
+ function errorMessage(error) {
134
+ return error instanceof Error ? error.message : String(error);
135
+ }
136
+ /**
137
+ * `armarius-astro import <file> [--dry-run]`: creates the records of an `armarius-import/v1` file through
138
+ * the webservice of Armarius (`ARMARIUS_API_URL`, key in `ARMARIUS_API_KEY`). A record whose key exists is
139
+ * skipped, never updated. Ends with 1 on any error, 0 otherwise.
140
+ */
141
+ export async function runImport(args, root, print, env = process.env) {
142
+ const parsed = parseArguments(args);
143
+ if (parsed === null) {
144
+ print(`Usage: ${IMPORT_SYNOPSIS}`);
145
+ return 1;
146
+ }
147
+ const { dryRun } = parsed;
148
+ const apiKey = env.ARMARIUS_API_KEY ?? '';
149
+ // Every line goes through here: the key never reaches an output, whatever echoes it.
150
+ let session = null;
151
+ const say = (line) => print(session?.redact(line) ?? redactSecrets(line, [[apiKey, '<key>']]));
152
+ const prefix = dryRun ? 'armarius-astro import --dry-run' : 'armarius-astro import';
153
+ let settings;
154
+ try {
155
+ settings = { apiOrigin: httpOrigin(env.ARMARIUS_API_URL ?? '', 'ARMARIUS_API_URL'), timeoutMs: IMPORT_TIMEOUT_MS, retries: IMPORT_RETRIES };
156
+ }
157
+ catch (error) {
158
+ say(errorMessage(error));
159
+ return 1;
160
+ }
161
+ if (!dryRun && apiKey.trim() === '') {
162
+ say(`${prefix}: ARMARIUS_API_KEY is empty.`);
163
+ return 1;
164
+ }
165
+ if (!dryRun && !isSafeOrigin(settings.apiOrigin)) {
166
+ say(`${prefix}: ARMARIUS_API_URL must use https outside a local machine, or the key travels in clear.`);
167
+ return 1;
168
+ }
169
+ const path = resolve(root, parsed.file);
170
+ let input;
171
+ try {
172
+ input = parseImportFile(await readFile(path, 'utf8'));
173
+ }
174
+ catch (error) {
175
+ say(`${prefix}: ${parsed.file}: ${errorMessage(error)}.`);
176
+ return 1;
177
+ }
178
+ let planned;
179
+ try {
180
+ const fields = new Map((await readCrudFields(settings, input.crud)).map(field => [field.slug, field]));
181
+ const keyError = keyFieldError(fields.get(input.key), input.key, input.crud);
182
+ if (keyError !== null) {
183
+ say(`${prefix}: ${keyError}.`);
184
+ return 1;
185
+ }
186
+ const existing = indexBy(await readAllRecords(settings, input.crud), input.key);
187
+ const relations = new Map();
188
+ for (const field of fields.values()) {
189
+ const targetCrud = field.relationship?.crud_slug;
190
+ if (field.type !== RELATIONSHIP_TYPE || targetCrud === undefined)
191
+ continue;
192
+ const indexKey = relationIndexKey(targetCrud, relationColumn(field));
193
+ if (relations.has(indexKey) || !input.records.some(record => isRelation(record[field.slug])))
194
+ continue;
195
+ relations.set(indexKey, indexBy(await readAllRecords(settings, targetCrud), relationColumn(field)));
196
+ }
197
+ planned = await planRecords(input, dirname(path), fields, existing, relations);
198
+ }
199
+ catch (error) {
200
+ say(`${prefix}: ${errorMessage(error)}.`);
201
+ return 1;
202
+ }
203
+ const errorCount = planned.filter(record => record.status === 'error').length;
204
+ if (dryRun || errorCount > 0) {
205
+ for (const record of planned) {
206
+ if (record.status === 'create')
207
+ say(`create ${record.label}`);
208
+ else if (record.status === 'exists')
209
+ say(`exists ${record.label} (#${String(record.id)})`);
210
+ else
211
+ say(`error ${record.label}: ${record.errors.join('; ')}`);
212
+ }
213
+ const toCreate = planned.filter(record => record.status === 'create').length;
214
+ say(`${prefix}: ${toCreate} to create, ${planned.length - toCreate - errorCount} existing, ${errorCount} in error${dryRun ? '' : '; nothing written'}.`);
215
+ return errorCount > 0 ? 1 : 0;
216
+ }
217
+ session = new WebserviceSession(settings, apiKey);
218
+ const toCreate = planned.filter(record => record.status === 'create');
219
+ try {
220
+ if (toCreate.length > 0)
221
+ await session.open(toCreate.some(record => record.files.size > 0));
222
+ }
223
+ catch (error) {
224
+ say(`${prefix}: ${errorMessage(error)}; nothing created.`);
225
+ return 1;
226
+ }
227
+ let created = 0;
228
+ let failed = 0;
229
+ for (const record of planned) {
230
+ if (record.status === 'exists') {
231
+ say(`skipped ${record.label} (#${String(record.id)} exists)`);
232
+ continue;
233
+ }
234
+ if (record.status !== 'create')
235
+ continue;
236
+ try {
237
+ const { id, failedFiles } = await createRecord(session, input.crud, record);
238
+ if (failedFiles.length > 0) {
239
+ failed++;
240
+ say(`failed ${record.label}: created as #${String(id)}, but ${failedFiles.join('; ')}; fix it in the admin`);
241
+ }
242
+ else {
243
+ created++;
244
+ say(`created ${record.label} (#${String(id)})`);
245
+ }
246
+ }
247
+ catch (error) {
248
+ failed++;
249
+ say(`failed ${record.label}: ${errorMessage(error)}`);
250
+ }
251
+ }
252
+ const skipped = planned.filter(record => record.status === 'exists').length;
253
+ say(`${prefix}: ${created} created, ${skipped} skipped, ${failed} failed.`);
254
+ return failed > 0 ? 1 : 0;
255
+ }
@@ -0,0 +1,53 @@
1
+ declare const IMPORT_FORMAT = "armarius-import/v1";
2
+ /** A record of another CRUD, named by the value of the column the relation shows (`name` most often). */
3
+ export interface RelationValue {
4
+ crud: string;
5
+ name: string;
6
+ }
7
+ /** A file, by its path relative to the input file. */
8
+ export interface FileValue {
9
+ file: string;
10
+ }
11
+ /** `armarius-import/v1`: the records of one CRUD, each identified by the value of its `key` field. */
12
+ export interface ImportFile {
13
+ format: typeof IMPORT_FORMAT;
14
+ crud: string;
15
+ key: string;
16
+ records: Record<string, unknown>[];
17
+ }
18
+ /** A field of the target CRUD, as `GET /webservice/resources/{crud}/details` describes it. */
19
+ export interface CrudField {
20
+ slug: string;
21
+ type: number;
22
+ required: boolean;
23
+ has_multiple_choices: boolean;
24
+ is_translatable: boolean;
25
+ is_private: boolean;
26
+ /** `crud_slug` is absent for a relation to a model other than a CRUD; a null column means `name`. */
27
+ relationship?: {
28
+ crud_slug?: string;
29
+ target_column?: string | null;
30
+ };
31
+ }
32
+ /** Field types of Armarius (`FieldTypeEnum`) the import treats apart. */
33
+ export declare const FILE_PICKER_TYPE = 13;
34
+ export declare const RELATIONSHIP_TYPE = 23;
35
+ export declare class ArmariusImportError extends Error {
36
+ name: string;
37
+ }
38
+ export declare function isRelation(value: unknown): value is RelationValue;
39
+ export declare function isFile(value: unknown): value is FileValue;
40
+ /**
41
+ * The form a key or a relation's name is compared in: Unicode NFC, outer spaces trimmed, inner runs of
42
+ * spaces made one, lower case. The same on both sides, so that a relaunch finds what the first run created.
43
+ */
44
+ export declare function normalizeKey(value: unknown): string;
45
+ /** Why a field cannot identify a record on a relaunch; `null` when it can. */
46
+ export declare function keyFieldError(field: CrudField | undefined, key: string, crud: string): string | null;
47
+ /** The column a relation is matched on, `name` when the field names none. */
48
+ export declare function relationColumn(field: CrudField): string;
49
+ /** Reads `armarius-import/v1`; throws on anything but its shape. The values are checked against the CRUD later. */
50
+ export declare function parseImportFile(text: string): ImportFile;
51
+ /** What is wrong with one value for its field, the files and relations not looked up yet; `null` when its shape fits. */
52
+ export declare function valueShapeError(field: CrudField, value: unknown): string | null;
53
+ export {};
@@ -0,0 +1,94 @@
1
+ const IMPORT_FORMAT = 'armarius-import/v1';
2
+ /** Field types of Armarius (`FieldTypeEnum`) the import treats apart. */
3
+ export const FILE_PICKER_TYPE = 13;
4
+ export const RELATIONSHIP_TYPE = 23;
5
+ /** ILLUSTRATION, GALLERY, PDF and LINK_OR_FILE: file fields the import does not send. */
6
+ const OTHER_FILE_TYPES = new Set([15, 21, 22, 34]);
7
+ /** TEXT, NUMBER, EMAIL, PHONE, URL and INLINE_TEXT: the listing serves them as they were sent. */
8
+ const KEY_TYPES = new Set([1, 2, 3, 16, 26, 35]);
9
+ export class ArmariusImportError extends Error {
10
+ name = 'ArmariusImportError';
11
+ }
12
+ function isPlainObject(value) {
13
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
14
+ }
15
+ function isNonBlankString(value) {
16
+ return typeof value === 'string' && value.trim() !== '';
17
+ }
18
+ export function isRelation(value) {
19
+ return isPlainObject(value) && Object.keys(value).length === 2 && isNonBlankString(value.crud) && isNonBlankString(value.name);
20
+ }
21
+ export function isFile(value) {
22
+ return isPlainObject(value) && Object.keys(value).length === 1 && isNonBlankString(value.file);
23
+ }
24
+ /**
25
+ * The form a key or a relation's name is compared in: Unicode NFC, outer spaces trimmed, inner runs of
26
+ * spaces made one, lower case. The same on both sides, so that a relaunch finds what the first run created.
27
+ */
28
+ export function normalizeKey(value) {
29
+ if (value === null || value === undefined)
30
+ return '';
31
+ return String(value).normalize('NFC').trim().replace(/\s+/g, ' ').toLowerCase();
32
+ }
33
+ /** Why a field cannot identify a record on a relaunch; `null` when it can. */
34
+ export function keyFieldError(field, key, crud) {
35
+ if (field?.is_private === true)
36
+ return `"${key}" is a private field of ${crud}: the public listing cannot show which records exist`;
37
+ if (field === undefined || !KEY_TYPES.has(field.type) || field.is_translatable)
38
+ return `"${key}" is not a plain text or number field of ${crud}`;
39
+ return null;
40
+ }
41
+ /** The column a relation is matched on, `name` when the field names none. */
42
+ export function relationColumn(field) {
43
+ return field.relationship?.target_column || 'name';
44
+ }
45
+ /** Reads `armarius-import/v1`; throws on anything but its shape. The values are checked against the CRUD later. */
46
+ export function parseImportFile(text) {
47
+ let parsed;
48
+ try {
49
+ parsed = JSON.parse(text);
50
+ }
51
+ catch (error) {
52
+ throw new ArmariusImportError(`not JSON (${error instanceof Error ? error.message : String(error)})`);
53
+ }
54
+ if (!isPlainObject(parsed))
55
+ throw new ArmariusImportError('not a JSON object');
56
+ if (parsed.format !== IMPORT_FORMAT)
57
+ throw new ArmariusImportError(`"format" is not "${IMPORT_FORMAT}"`);
58
+ if (!isNonBlankString(parsed.crud))
59
+ throw new ArmariusImportError('"crud" is missing');
60
+ if (!isNonBlankString(parsed.key))
61
+ throw new ArmariusImportError('"key" is missing');
62
+ if (!Array.isArray(parsed.records) || !parsed.records.every(isPlainObject)) {
63
+ throw new ArmariusImportError('"records" is not a list of objects');
64
+ }
65
+ return { format: IMPORT_FORMAT, crud: parsed.crud, key: parsed.key, records: parsed.records };
66
+ }
67
+ /** What is wrong with one value for its field, the files and relations not looked up yet; `null` when its shape fits. */
68
+ export function valueShapeError(field, value) {
69
+ if (field.type === RELATIONSHIP_TYPE) {
70
+ if (field.relationship?.crud_slug === undefined)
71
+ return `${field.slug}: a relation to a model other than a CRUD is not supported`;
72
+ if (field.has_multiple_choices)
73
+ return `${field.slug}: a relation to several records is not supported`;
74
+ if (!isRelation(value))
75
+ return `${field.slug}: expected { "crud": "...", "name": "..." }`;
76
+ if (value.crud !== field.relationship?.crud_slug) {
77
+ return `${field.slug}: relation to "${value.crud}", the field relates to "${field.relationship?.crud_slug}"`;
78
+ }
79
+ return null;
80
+ }
81
+ if (field.type === FILE_PICKER_TYPE) {
82
+ if (field.has_multiple_choices) {
83
+ return Array.isArray(value) && value.every(isFile) ? null : `${field.slug}: expected a list of { "file": "..." }`;
84
+ }
85
+ return isFile(value) ? null : `${field.slug}: expected { "file": "..." }`;
86
+ }
87
+ if (OTHER_FILE_TYPES.has(field.type))
88
+ return `${field.slug}: this kind of file field is not supported`;
89
+ if (value === null || ['string', 'number', 'boolean'].includes(typeof value))
90
+ return null;
91
+ if (field.is_translatable && isPlainObject(value) && Object.values(value).every(text => typeof text === 'string'))
92
+ return null;
93
+ return `${field.slug}: expected a string, a number, a boolean or null`;
94
+ }
@@ -0,0 +1,47 @@
1
+ import type { CrudRecord } from '../routes.js';
2
+ import type { CrudField } from './format.js';
3
+ export interface ImportSettings {
4
+ apiOrigin: string;
5
+ timeoutMs: number;
6
+ /** Attempts after the first one: on 429 for every request, also on 5xx and silence for a read. */
7
+ retries: number;
8
+ }
9
+ /** The types the import sends, by extension; any other file is refused before a write. */
10
+ export declare const FILE_TYPES: Record<string, string>;
11
+ /** Replaces each non-blank secret by its label; a blank one would replace every space. */
12
+ export declare function redactSecrets(text: string, secrets: [secret: string, label: string][]): string;
13
+ /** The fields of a CRUD the webservice exposes, by its public description. */
14
+ export declare function readCrudFields(settings: ImportSettings, crud: string): Promise<CrudField[]>;
15
+ /**
16
+ * Every record of a CRUD a guest may read, page by page from the public listing; fails when the pages do
17
+ * not add up to the total, since a record missed here would be created a second time.
18
+ */
19
+ export declare function readAllRecords(settings: ImportSettings, crud: string): Promise<CrudRecord[]>;
20
+ /**
21
+ * The webservice, under one API key: a token for the run, the session cookies Filepond asks for, the
22
+ * uploads and the creations. The key and the token never leave the requests: `redact` hides them anywhere.
23
+ */
24
+ export declare class WebserviceSession {
25
+ private readonly settings;
26
+ private readonly apiKey;
27
+ private accessToken;
28
+ private readonly cookies;
29
+ constructor(settings: ImportSettings, apiKey: string);
30
+ redact(text: string): string;
31
+ /** Gets the run's token, and the session Filepond asks for when files are to be sent; a refusal ends the run. */
32
+ open(withFiles: boolean): Promise<void>;
33
+ private token;
34
+ private keepCookies;
35
+ /** Filepond sits behind the session's CSRF check: the token alone is refused with 419. */
36
+ private sessionHeaders;
37
+ upload(path: string): Promise<string>;
38
+ /**
39
+ * Creates a record. Armarius answers 201 even when a single file failed: the failure is only in
40
+ * `data.<field>.status`, so each file field of the body is read back. `pending` is expected: a worker
41
+ * processes a single file.
42
+ */
43
+ create(crud: string, body: Record<string, unknown>, fileFields: string[]): Promise<{
44
+ id: unknown;
45
+ failedFiles: string[];
46
+ }>;
47
+ }
@@ -0,0 +1,218 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { basename, extname } from 'node:path';
3
+ import { ArmariusApiError } from '../api.js';
4
+ const MAX_RETRY_AFTER_MS = 60_000;
5
+ const RETRY_DELAY_MS = 1_000;
6
+ /** The most the public listing serves per page (422 above). */
7
+ const RECORDS_PER_PAGE = 100;
8
+ /** The types the import sends, by extension; any other file is refused before a write. */
9
+ export const FILE_TYPES = {
10
+ '.jpg': 'image/jpeg',
11
+ '.jpeg': 'image/jpeg',
12
+ '.png': 'image/png',
13
+ '.webp': 'image/webp',
14
+ '.gif': 'image/gif',
15
+ '.svg': 'image/svg+xml',
16
+ '.pdf': 'application/pdf',
17
+ '.mp4': 'video/mp4',
18
+ };
19
+ function retryDelay(response, attempt) {
20
+ const header = response?.headers.get('retry-after');
21
+ if (header !== null && header !== undefined && /^\d+$/.test(header.trim())) {
22
+ return Math.min(Number(header.trim()) * 1000, MAX_RETRY_AFTER_MS);
23
+ }
24
+ return RETRY_DELAY_MS * attempt;
25
+ }
26
+ async function refusalDetail(response, redact) {
27
+ const text = redact(await response.text().catch(() => ''));
28
+ try {
29
+ const body = JSON.parse(text);
30
+ if (typeof body.message === 'string' && body.message !== '')
31
+ return body.message.slice(0, 200);
32
+ }
33
+ catch {
34
+ // Not JSON: the start of the body says enough.
35
+ }
36
+ return text.replace(/\s+/g, ' ').trim().slice(0, 200);
37
+ }
38
+ /** Replaces each non-blank secret by its label; a blank one would replace every space. */
39
+ export function redactSecrets(text, secrets) {
40
+ return secrets
41
+ .filter(([secret]) => secret.trim() !== '')
42
+ .reduce((redacted, [secret, label]) => redacted.split(secret).join(label), text);
43
+ }
44
+ /** One request to Armarius, tried again on 429 (after its `Retry-After`) and, for a read, on 5xx and silence. */
45
+ async function send(settings, path, options = {}) {
46
+ const { method = 'GET', query = {}, headers = {}, body, read = false, redact = (text) => text } = options;
47
+ const url = new URL(path, settings.apiOrigin);
48
+ for (const [name, value] of Object.entries(query))
49
+ url.searchParams.set(name, value);
50
+ const label = `${method} ${url.pathname}`;
51
+ let lastFailure = '';
52
+ let lastResponse = null;
53
+ for (let attempt = 0; attempt <= settings.retries; attempt++) {
54
+ if (attempt > 0)
55
+ await new Promise(resolve => setTimeout(resolve, retryDelay(lastResponse, attempt)));
56
+ lastResponse = null;
57
+ let response;
58
+ try {
59
+ // A redirected write would carry the key or the token elsewhere, or turn into a GET.
60
+ response = await fetch(url, { method, headers, body, redirect: read ? 'follow' : 'manual', signal: AbortSignal.timeout(settings.timeoutMs) });
61
+ }
62
+ catch (error) {
63
+ lastFailure = error instanceof Error && error.name === 'TimeoutError'
64
+ ? `no answer within ${settings.timeoutMs} ms`
65
+ : String(error instanceof Error ? error.message : error);
66
+ // A write without an answer may have been done: never sent twice.
67
+ if (!read) {
68
+ lastFailure += '; it may have been carried out: run the import again to check';
69
+ break;
70
+ }
71
+ continue;
72
+ }
73
+ if (response.ok)
74
+ return response;
75
+ lastResponse = response;
76
+ lastFailure = `HTTP ${response.status}`;
77
+ const detail = await refusalDetail(response, redact);
78
+ if (detail !== '')
79
+ lastFailure += `: ${detail}`;
80
+ if (response.status !== 429 && !(read && response.status >= 500))
81
+ break;
82
+ }
83
+ throw new ArmariusApiError(`${label} failed (${lastFailure})`);
84
+ }
85
+ async function readJson(settings, path, query = {}) {
86
+ const response = await send(settings, path, { query, headers: { Accept: 'application/json' }, read: true });
87
+ return await response.json();
88
+ }
89
+ /** The fields of a CRUD the webservice exposes, by its public description. */
90
+ export async function readCrudFields(settings, crud) {
91
+ const body = await readJson(settings, `/webservice/resources/${encodeURIComponent(crud)}/details`);
92
+ const fields = body.resource?.form_fields?.fields;
93
+ if (!Array.isArray(fields))
94
+ throw new ArmariusApiError(`the description of "${crud}" lists no fields`);
95
+ return fields;
96
+ }
97
+ /**
98
+ * Every record of a CRUD a guest may read, page by page from the public listing; fails when the pages do
99
+ * not add up to the total, since a record missed here would be created a second time.
100
+ */
101
+ export async function readAllRecords(settings, crud) {
102
+ const path = `/api/cruds/from-slug/${encodeURIComponent(crud)}/items`;
103
+ const records = new Map();
104
+ let total = 0;
105
+ for (let page = 1, lastPage = 1; page <= lastPage; page++) {
106
+ const body = await readJson(settings, path, { per_page: String(RECORDS_PER_PAGE), page: String(page) });
107
+ if (!Array.isArray(body.data) || typeof body.meta?.last_page !== 'number' || typeof body.meta.total !== 'number') {
108
+ throw new ArmariusApiError(`GET ${path} did not answer a page of records`);
109
+ }
110
+ for (const record of body.data)
111
+ records.set(String(record.id), record);
112
+ lastPage = body.meta.last_page;
113
+ total = body.meta.total;
114
+ }
115
+ if (records.size !== total) {
116
+ throw new ArmariusApiError(`GET ${path} served ${records.size} records out of ${total}, records changed while it read them; run the import again`);
117
+ }
118
+ return [...records.values()];
119
+ }
120
+ /**
121
+ * The webservice, under one API key: a token for the run, the session cookies Filepond asks for, the
122
+ * uploads and the creations. The key and the token never leave the requests: `redact` hides them anywhere.
123
+ */
124
+ export class WebserviceSession {
125
+ settings;
126
+ apiKey;
127
+ accessToken = null;
128
+ cookies = new Map();
129
+ constructor(settings, apiKey) {
130
+ this.settings = settings;
131
+ this.apiKey = apiKey;
132
+ }
133
+ redact(text) {
134
+ return redactSecrets(text, [[this.apiKey, '<key>'], [this.accessToken ?? '', '<token>']]);
135
+ }
136
+ /** Gets the run's token, and the session Filepond asks for when files are to be sent; a refusal ends the run. */
137
+ async open(withFiles) {
138
+ await this.token();
139
+ if (withFiles)
140
+ await this.sessionHeaders();
141
+ }
142
+ async token() {
143
+ if (this.accessToken !== null)
144
+ return this.accessToken;
145
+ const response = await send(this.settings, '/webservice/token', {
146
+ redact: text => this.redact(text),
147
+ method: 'POST',
148
+ headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
149
+ body: JSON.stringify({ api_key: this.apiKey }),
150
+ });
151
+ const body = await response.json();
152
+ if (typeof body.access_token !== 'string' || body.access_token === '') {
153
+ throw new ArmariusApiError('POST /webservice/token answered no access_token');
154
+ }
155
+ this.accessToken = body.access_token;
156
+ return this.accessToken;
157
+ }
158
+ keepCookies(response) {
159
+ for (const line of response.headers.getSetCookie()) {
160
+ const pair = line.split(';', 1)[0];
161
+ const separator = pair.indexOf('=');
162
+ if (separator > 0)
163
+ this.cookies.set(pair.slice(0, separator).trim(), pair.slice(separator + 1).trim());
164
+ }
165
+ }
166
+ /** Filepond sits behind the session's CSRF check: the token alone is refused with 419. */
167
+ async sessionHeaders() {
168
+ if (!this.cookies.has('XSRF-TOKEN')) {
169
+ this.keepCookies(await send(this.settings, '/sanctum/csrf-cookie', { headers: { Accept: 'application/json' }, read: true }));
170
+ }
171
+ const xsrf = this.cookies.get('XSRF-TOKEN');
172
+ if (xsrf === undefined)
173
+ throw new ArmariusApiError('GET /sanctum/csrf-cookie set no XSRF-TOKEN cookie');
174
+ return {
175
+ Cookie: [...this.cookies].map(([name, value]) => `${name}=${value}`).join('; '),
176
+ 'X-XSRF-TOKEN': decodeURIComponent(xsrf),
177
+ };
178
+ }
179
+ async upload(path) {
180
+ const token = await this.token();
181
+ const headers = await this.sessionHeaders();
182
+ const form = new FormData();
183
+ const type = FILE_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
184
+ form.append('file', new Blob([await readFile(path)], { type }), basename(path));
185
+ const response = await send(this.settings, '/api/filepond', {
186
+ redact: text => this.redact(text),
187
+ method: 'POST',
188
+ headers: { ...headers, Authorization: `Bearer ${token}`, Accept: 'application/json' },
189
+ body: form,
190
+ });
191
+ this.keepCookies(response);
192
+ const serverId = (await response.text()).trim();
193
+ if (serverId === '')
194
+ throw new ArmariusApiError('POST /api/filepond answered no serverId');
195
+ return serverId;
196
+ }
197
+ /**
198
+ * Creates a record. Armarius answers 201 even when a single file failed: the failure is only in
199
+ * `data.<field>.status`, so each file field of the body is read back. `pending` is expected: a worker
200
+ * processes a single file.
201
+ */
202
+ async create(crud, body, fileFields) {
203
+ const token = await this.token();
204
+ const response = await send(this.settings, `/webservice/resources/${encodeURIComponent(crud)}`, {
205
+ redact: text => this.redact(text),
206
+ method: 'POST',
207
+ headers: { Authorization: `Bearer ${token}`, Accept: 'application/json', 'Content-Type': 'application/json' },
208
+ body: JSON.stringify(body),
209
+ });
210
+ const { data } = await response.json();
211
+ const failedFiles = fileFields.flatMap((slug) => {
212
+ const answers = [data?.[slug]].flat();
213
+ const failed = answers.find(answer => answer?.status === 'failed');
214
+ return failed === undefined ? [] : [`${slug} failed${typeof failed?.error === 'string' ? ` (${failed.error})` : ''}`];
215
+ });
216
+ return { id: data?.id, failedFiles };
217
+ }
218
+ }
@@ -0,0 +1,6 @@
1
+ export { armarius, armarius as default } from './integration.js';
2
+ export { armariusPaths, getMenu, getPageSeo, getRecords, getSetting } from './readers.js';
3
+ export type { ArmariusStaticPath, Menu, MenuItem, PageSeo } from './readers.js';
4
+ export type { ArmariusOptions, ArmariusPage } from './options.js';
5
+ export type { GlideParams } from './images.js';
6
+ export type { CrudRecord } from './routes.js';