@veroxm/sdk 1.12.0 → 1.14.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,33 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.14.0
4
+
5
+ - Private files: `app.files` (`list`, `all`, `upload`, `get`, `delete`, `link`, `grant`) with a server key that has
6
+ "Read private files" / "Write private files", and `uploadWithGrant(uploadUrl, file)` for a browser or app with a
7
+ one-time upload link (no key). Types `StoredFile`, `StoredFilePage`, `StoredFileLink`, `FileGrant`,
8
+ `FileGrantOptions`, `StoredFileListOptions`. Needs a VeroXM server with private files (OpenAPI 2.17.0).
9
+ - The private files access log, `app.files.events({ fileId?, before?, limit? })`: who stored, read, linked, opened and
10
+ deleted each file, an open naming the link's maker and whom it was for (`link(id, { for })`; links now carry
11
+ `linkId`). Folder retention rules: `folders()`, `setFolder(folder, keepDays)`, `removeFolder(folder)`. Types
12
+ `StoredFileEvent`, `StoredFileEventPage`, `StoredFileEventOptions`, `FileFolderRule`.
13
+
14
+ ## 1.13.0
15
+
16
+ - App translations: `app.translations.get('ar')` reads a locale's whole bundle in one request: its texts (nested, or
17
+ dotted keys with `flat`), writing direction (`dir: 'rtl'`), own name ("العربية") and the project's translations
18
+ `version`. Keys not translated yet come from the default locale (`fallback: false` for only the locale's own), and
19
+ `fallback` lists them. `resource('ar')` is the bare texts as i18next loads them; `locales()` lists the project's
20
+ locales with their direction and coverage (`translated` of `total`). Pass `version` for an address that is cached for
21
+ a year. Any key of the project can read them, a browser key too. `fetchTranslations({ baseUrl, projectId, apiKey,
22
+ locale })` and `fetchTranslationLocales(...)` do the same without a `VeroXMApp`.
23
+ - `createTranslator(texts, { locale })` gives `t(key, values)` for those texts, i18next-style: `{{name}}`,
24
+ `{{user.name}}`, `$t(other.key)`, and plural forms by `count` (`items_one`, `items_other`, `items_zero`). A key with
25
+ no text gives the key itself, or the fallback you pass. Needs a VeroXM server with app translations.
26
+ - `VeroxmI18nextBackend`: an i18next backend, `i18next.use(VeroxmI18nextBackend).init({ backend: { baseUrl, projectId,
27
+ apiKey } })`. One request per language; the "translation" namespace gets the whole bundle and another namespace the
28
+ texts under its name. A language the project doesn't have loads as empty, so i18next falls back to `fallbackLng`.
29
+ `fetchTranslationResource(...)` reads the bare texts without a `VeroXMApp`.
30
+
3
31
  ## 1.12.0
4
32
 
5
33
  - Safe retries for writes: `content(slug).create()`, `update()`, `delete()` and `functions.call()` take an
package/dist/client.d.ts CHANGED
@@ -6,6 +6,8 @@ import { FunctionsResource } from './functions.js';
6
6
  import { TasksResource } from './tasks.js';
7
7
  import { ProcessesResource } from './processes.js';
8
8
  import { FormsResource } from './forms.js';
9
+ import { FilesResource } from './files.js';
10
+ import { TranslationsResource } from './translations.js';
9
11
  import { type TokenStorage } from './token-storage.js';
10
12
  export interface VeroXMAppOptions {
11
13
  /** Your VeroXM deployment's origin, e.g. "https://cms.example.com" -- no trailing /public/... needed, VeroXMApp builds that itself. */
@@ -43,6 +45,10 @@ export declare class VeroXMApp {
43
45
  readonly processes: ProcessesResource;
44
46
  /** The project's forms and responses (server keys with forms:read). */
45
47
  readonly forms: FormsResource;
48
+ /** The project's private files (server keys with files:read / files:write). */
49
+ readonly files: FilesResource;
50
+ /** The project's app translations: a locale's whole bundle in one request (any key, a browser key too). */
51
+ readonly translations: TranslationsResource;
46
52
  private readonly apiBase;
47
53
  private readonly timeoutMs;
48
54
  private readonly retries;
package/dist/client.js CHANGED
@@ -7,6 +7,8 @@ import { FunctionsResource } from './functions.js';
7
7
  import { TasksResource } from './tasks.js';
8
8
  import { ProcessesResource } from './processes.js';
9
9
  import { FormsResource } from './forms.js';
10
+ import { FilesResource } from './files.js';
11
+ import { TranslationsResource } from './translations.js';
10
12
  import { MemoryTokenStorage, BrowserLocalStorageTokenStorage } from './token-storage.js';
11
13
  function defaultTokenStorage(projectId) {
12
14
  if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
@@ -29,6 +31,8 @@ export class VeroXMApp {
29
31
  this.tasks = new TasksResource(this);
30
32
  this.processes = new ProcessesResource(this);
31
33
  this.forms = new FormsResource(this);
34
+ this.files = new FilesResource(this);
35
+ this.translations = new TranslationsResource(this);
32
36
  }
33
37
  static initializeApp(options) {
34
38
  checkTimeout(options.timeoutMs);
@@ -0,0 +1,73 @@
1
+ import type { VeroXMApp } from './client.js';
2
+ import type { operations } from './generated/api.js';
3
+ import type { Schemas } from './schemas.js';
4
+ import type { UploadableFile } from './media.js';
5
+ import type { RequestControl } from './http.js';
6
+ /** A private file: never public, read by id with a server key or through a short-lived link. */
7
+ export type StoredFile = Schemas['StoredFile'];
8
+ export type StoredFilePage = Schemas['StoredFilePage'];
9
+ export type StoredFileLink = Schemas['StoredFileLink'];
10
+ /** A one-time upload link: a browser or app POSTs one file to `uploadUrl` with `uploadWithGrant`. */
11
+ export type FileGrant = Schemas['FileGrant'];
12
+ export type FileGrantOptions = Schemas['FileGrantRequest'];
13
+ export type StoredFileListOptions = NonNullable<operations['listStoredFiles']['parameters']['query']>;
14
+ /** One access log entry: who stored, read, linked, opened or deleted a file (an open names the link and whom it was for). */
15
+ export type StoredFileEvent = Schemas['StoredFileEvent'];
16
+ export type StoredFileEventPage = Schemas['StoredFileEventPage'];
17
+ export type StoredFileEventOptions = NonNullable<operations['listFileEvents']['parameters']['query']>;
18
+ /** A folder's retention rule: its files (and its subfolders' without their own rule) kept `keepDays` at most. */
19
+ export type FileFolderRule = Schemas['FileFolderRule'];
20
+ /**
21
+ * The project's private files, for your own servers: a key with "Read private files" (`files:read`) and/or "Write private
22
+ * files" (`files:write`), signed in with `auth.signInWithApiKey`. Never use such a key in a browser: give the browser an
23
+ * upload link (`grant`) or a file link (`link`) instead.
24
+ */
25
+ export declare class FilesResource {
26
+ private readonly app;
27
+ constructor(app: VeroXMApp);
28
+ /** A page of files in a folder (`under: true` for everything under it), by id, up to 100. */
29
+ list(options?: StoredFileListOptions): Promise<StoredFilePage>;
30
+ /** Every file in a folder, page by page: `for await (const f of app.files.all({ folder: 'reports' }))`. */
31
+ all(options?: Omit<StoredFileListOptions, 'after'>): AsyncGenerator<StoredFile>;
32
+ /** Stores a file (25 MB at most). Its type is what its bytes show. `keepSeconds`: removed after that long. */
33
+ upload(file: UploadableFile, options?: {
34
+ name?: string;
35
+ folder?: string;
36
+ contentType?: string;
37
+ keepSeconds?: number;
38
+ }): Promise<StoredFile>;
39
+ get(id: string): Promise<StoredFile>;
40
+ delete(id: string): Promise<void>;
41
+ /**
42
+ * A link that opens the file with no key until it expires: 15 minutes unless asked, at most 7 days. `for` says whom
43
+ * it's for (an end user's id): the access log shows it next to every open.
44
+ */
45
+ link(id: string, options?: {
46
+ ttlSeconds?: number;
47
+ download?: boolean;
48
+ for?: string;
49
+ }): Promise<StoredFileLink>;
50
+ /** A one-time upload link for a browser or app, within `maxBytes` and `kinds`. */
51
+ grant(options?: FileGrantOptions): Promise<FileGrant>;
52
+ /** The access log, newest first, up to 100 a page: one file's with `fileId` (kept after it's removed). Kept a year. */
53
+ events(options?: StoredFileEventOptions): Promise<StoredFileEventPage>;
54
+ /** The folder retention rules. */
55
+ folders(): Promise<FileFolderRule[]>;
56
+ /**
57
+ * Sets a folder's retention rule ("" for every folder): files there are kept `keepDays` at most, and the ones already
58
+ * there older than that are removed. `shortened`: how many files now expire sooner.
59
+ */
60
+ setFolder(folder: string, keepDays: number): Promise<FileFolderRule & {
61
+ shortened: number;
62
+ }>;
63
+ /** Removes a folder's rule: its files keep the expiry they have. */
64
+ removeFolder(folder: string): Promise<{
65
+ removed: boolean;
66
+ }>;
67
+ }
68
+ /**
69
+ * Uploads one file with an upload link (`FileGrant.uploadUrl`, made by your server or a function): no key needed, so it
70
+ * runs in the browser. The link works once; a second upload, an expired link, a file too large (413) or of a kind the
71
+ * grant doesn't take (415) throws `VeroXMApiError`.
72
+ */
73
+ export declare function uploadWithGrant(uploadUrl: string, file: UploadableFile, control?: RequestControl): Promise<StoredFile>;
package/dist/files.js ADDED
@@ -0,0 +1,100 @@
1
+ import { apiError } from './errors.js';
2
+ function formOf(file) {
3
+ const form = new FormData();
4
+ if (file instanceof Blob)
5
+ form.append('file', file);
6
+ else
7
+ form.append('file', file.data instanceof Blob ? file.data : new Blob([file.data], { type: file.contentType }), file.filename);
8
+ return form;
9
+ }
10
+ /**
11
+ * The project's private files, for your own servers: a key with "Read private files" (`files:read`) and/or "Write private
12
+ * files" (`files:write`), signed in with `auth.signInWithApiKey`. Never use such a key in a browser: give the browser an
13
+ * upload link (`grant`) or a file link (`link`) instead.
14
+ */
15
+ export class FilesResource {
16
+ constructor(app) {
17
+ this.app = app;
18
+ }
19
+ /** A page of files in a folder (`under: true` for everything under it), by id, up to 100. */
20
+ async list(options = {}) {
21
+ return (await this.app.request({ path: '/storage/files', query: { folder: options.folder, under: options.under, after: options.after, limit: options.limit } }));
22
+ }
23
+ /** Every file in a folder, page by page: `for await (const f of app.files.all({ folder: 'reports' }))`. */
24
+ async *all(options = {}) {
25
+ let after;
26
+ do {
27
+ const page = await this.list({ ...options, after });
28
+ yield* page.files;
29
+ after = page.next ?? undefined;
30
+ } while (after);
31
+ }
32
+ /** Stores a file (25 MB at most). Its type is what its bytes show. `keepSeconds`: removed after that long. */
33
+ async upload(file, options = {}) {
34
+ const form = formOf(file);
35
+ if (options.name)
36
+ form.append('name', options.name);
37
+ if (options.folder)
38
+ form.append('folder', options.folder);
39
+ if (options.contentType)
40
+ form.append('contentType', options.contentType);
41
+ if (options.keepSeconds !== undefined)
42
+ form.append('keepSeconds', String(options.keepSeconds));
43
+ return (await this.app.request({ method: 'POST', path: '/storage/files', form }));
44
+ }
45
+ async get(id) {
46
+ return (await this.app.request({ path: `/storage/files/${encodeURIComponent(id)}` }));
47
+ }
48
+ async delete(id) {
49
+ await this.app.request({ method: 'DELETE', path: `/storage/files/${encodeURIComponent(id)}` });
50
+ }
51
+ /**
52
+ * A link that opens the file with no key until it expires: 15 minutes unless asked, at most 7 days. `for` says whom
53
+ * it's for (an end user's id): the access log shows it next to every open.
54
+ */
55
+ async link(id, options = {}) {
56
+ return (await this.app.request({ method: 'POST', path: `/storage/files/${encodeURIComponent(id)}/link`, json: options }));
57
+ }
58
+ /** A one-time upload link for a browser or app, within `maxBytes` and `kinds`. */
59
+ async grant(options = {}) {
60
+ return (await this.app.request({ method: 'POST', path: '/storage/grants', json: options }));
61
+ }
62
+ /** The access log, newest first, up to 100 a page: one file's with `fileId` (kept after it's removed). Kept a year. */
63
+ async events(options = {}) {
64
+ return (await this.app.request({ path: '/storage/events', query: { fileId: options.fileId, before: options.before, limit: options.limit } }));
65
+ }
66
+ /** The folder retention rules. */
67
+ async folders() {
68
+ return (await this.app.request({ path: '/storage/folders' })).folders;
69
+ }
70
+ /**
71
+ * Sets a folder's retention rule ("" for every folder): files there are kept `keepDays` at most, and the ones already
72
+ * there older than that are removed. `shortened`: how many files now expire sooner.
73
+ */
74
+ async setFolder(folder, keepDays) {
75
+ return (await this.app.request({ method: 'PUT', path: '/storage/folders', json: { folder, keepDays } }));
76
+ }
77
+ /** Removes a folder's rule: its files keep the expiry they have. */
78
+ async removeFolder(folder) {
79
+ return (await this.app.request({ method: 'DELETE', path: '/storage/folders', query: { folder } }));
80
+ }
81
+ }
82
+ /**
83
+ * Uploads one file with an upload link (`FileGrant.uploadUrl`, made by your server or a function): no key needed, so it
84
+ * runs in the browser. The link works once; a second upload, an expired link, a file too large (413) or of a kind the
85
+ * grant doesn't take (415) throws `VeroXMApiError`.
86
+ */
87
+ export async function uploadWithGrant(uploadUrl, file, control = {}) {
88
+ const res = await fetch(uploadUrl, { method: 'POST', body: formOf(file), signal: control.signal });
89
+ const text = await res.text();
90
+ let body = text;
91
+ try {
92
+ body = text ? JSON.parse(text) : null;
93
+ }
94
+ catch {
95
+ // not JSON: kept as text for the error
96
+ }
97
+ if (!res.ok)
98
+ throw apiError(res.status, body);
99
+ return body;
100
+ }