@veroxm/sdk 1.13.0 → 1.15.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 +20 -0
- package/dist/client.d.ts +13 -0
- package/dist/client.js +11 -1
- package/dist/embed.d.ts +24 -2
- package/dist/embed.js +44 -1
- package/dist/errors.d.ts +7 -0
- package/dist/errors.js +4 -2
- package/dist/files.d.ts +73 -0
- package/dist/files.js +100 -0
- package/dist/generated/api.d.ts +3620 -1801
- package/dist/http.d.ts +2 -0
- package/dist/http.js +18 -1
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/push.d.ts +32 -0
- package/dist/push.js +26 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.15.0
|
|
4
|
+
|
|
5
|
+
- Form embeds for targeted surveys: `openOn: { on: 'exit' }` opens a popup or toast when the visitor looks like leaving
|
|
6
|
+
(the pointer leaves through the top of the window; on touch screens, a quick scroll back up after reading a screen
|
|
7
|
+
or more), also as `data-open-on="exit"`. `survey` passes a survey card's token to the form, so the response is linked
|
|
8
|
+
to its survey, test and variant (VeroXM's script tag does this for you), and `onOpen` says when it opened.
|
|
9
|
+
|
|
10
|
+
## 1.14.0
|
|
11
|
+
|
|
12
|
+
- Push notifications: `app.push.register(device)`, `unregister(token)`, and for server keys `send(message, { idempotencyKey })` and `status(pushId)` (`PushResource`, types `PushDevice`, `PushDeviceRegistered`, `PushMessageInput`, `PushStatus`).
|
|
13
|
+
- Errors in the user's language: `initializeApp({ ..., locale: 'ar' })` and `app.setLocale()` send `X-VeroXM-Locale` (else the browser's Accept-Language); `VeroXMApiError.userMessage` has the words to show, and `fieldErrors` what to show under each field of an entry that didn't validate.
|
|
14
|
+
- Private files: `app.files` (`list`, `all`, `upload`, `get`, `delete`, `link`, `grant`) with a server key that has
|
|
15
|
+
"Read private files" / "Write private files", and `uploadWithGrant(uploadUrl, file)` for a browser or app with a
|
|
16
|
+
one-time upload link (no key). Types `StoredFile`, `StoredFilePage`, `StoredFileLink`, `FileGrant`,
|
|
17
|
+
`FileGrantOptions`, `StoredFileListOptions`. Needs a VeroXM server with private files (OpenAPI 2.17.0).
|
|
18
|
+
- The private files access log, `app.files.events({ fileId?, before?, limit? })`: who stored, read, linked, opened and
|
|
19
|
+
deleted each file, an open naming the link's maker and whom it was for (`link(id, { for })`; links now carry
|
|
20
|
+
`linkId`). Folder retention rules: `folders()`, `setFolder(folder, keepDays)`, `removeFolder(folder)`. Types
|
|
21
|
+
`StoredFileEvent`, `StoredFileEventPage`, `StoredFileEventOptions`, `FileFolderRule`.
|
|
22
|
+
|
|
3
23
|
## 1.13.0
|
|
4
24
|
|
|
5
25
|
- App translations: `app.translations.get('ar')` reads a locale's whole bundle in one request: its texts (nested, or
|
package/dist/client.d.ts
CHANGED
|
@@ -6,7 +6,9 @@ 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';
|
|
9
10
|
import { TranslationsResource } from './translations.js';
|
|
11
|
+
import { PushResource } from './push.js';
|
|
10
12
|
import { type TokenStorage } from './token-storage.js';
|
|
11
13
|
export interface VeroXMAppOptions {
|
|
12
14
|
/** Your VeroXM deployment's origin, e.g. "https://cms.example.com" -- no trailing /public/... needed, VeroXMApp builds that itself. */
|
|
@@ -28,6 +30,11 @@ export interface VeroXMAppOptions {
|
|
|
28
30
|
* Default: 0. A function answering GET runs again on a retry, so keep those safe to repeat.
|
|
29
31
|
*/
|
|
30
32
|
retries?: number;
|
|
33
|
+
/**
|
|
34
|
+
* The language error answers are worded in for your users (`VeroXMApiError.userMessage`), such as "ar". Default: the
|
|
35
|
+
* browser's own languages (Accept-Language), else English. Change it with `app.setLocale()`.
|
|
36
|
+
*/
|
|
37
|
+
locale?: string;
|
|
31
38
|
}
|
|
32
39
|
/**
|
|
33
40
|
* The SDK's entry point -- one `initializeApp()` call, Firebase-style,
|
|
@@ -44,13 +51,19 @@ export declare class VeroXMApp {
|
|
|
44
51
|
readonly processes: ProcessesResource;
|
|
45
52
|
/** The project's forms and responses (server keys with forms:read). */
|
|
46
53
|
readonly forms: FormsResource;
|
|
54
|
+
/** The project's private files (server keys with files:read / files:write). */
|
|
55
|
+
readonly files: FilesResource;
|
|
47
56
|
/** The project's app translations: a locale's whole bundle in one request (any key, a browser key too). */
|
|
48
57
|
readonly translations: TranslationsResource;
|
|
58
|
+
/** Push notifications: register this device (any key, or signed in), or send (server keys with push:send). */
|
|
59
|
+
readonly push: PushResource;
|
|
49
60
|
private readonly apiBase;
|
|
50
61
|
private readonly timeoutMs;
|
|
51
62
|
private readonly retries;
|
|
52
63
|
private constructor();
|
|
53
64
|
static initializeApp(options: VeroXMAppOptions): VeroXMApp;
|
|
65
|
+
/** The language error answers are worded in from now on (`VeroXMApiError.userMessage`); null: the browser's own. */
|
|
66
|
+
setLocale(locale: string | null): void;
|
|
54
67
|
/** Typed access to one content collection's entries (list/get/create/update/delete/search). */
|
|
55
68
|
content<T = Record<string, unknown>>(collectionSlug: string): ContentResource<T>;
|
|
56
69
|
/** This project's media library (list/upload/updateCaption/delete). */
|
package/dist/client.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { checkRetries, checkTimeout, rawRequest } from './http.js';
|
|
1
|
+
import { checkRetries, checkTimeout, rawRequest, setRequestLocale } from './http.js';
|
|
2
2
|
import { VeroXMApiError } from './errors.js';
|
|
3
3
|
import { VeroXMAuth } from './auth.js';
|
|
4
4
|
import { ContentResource } from './content.js';
|
|
@@ -7,7 +7,9 @@ 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';
|
|
10
11
|
import { TranslationsResource } from './translations.js';
|
|
12
|
+
import { PushResource } from './push.js';
|
|
11
13
|
import { MemoryTokenStorage, BrowserLocalStorageTokenStorage } from './token-storage.js';
|
|
12
14
|
function defaultTokenStorage(projectId) {
|
|
13
15
|
if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
|
|
@@ -30,18 +32,26 @@ export class VeroXMApp {
|
|
|
30
32
|
this.tasks = new TasksResource(this);
|
|
31
33
|
this.processes = new ProcessesResource(this);
|
|
32
34
|
this.forms = new FormsResource(this);
|
|
35
|
+
this.files = new FilesResource(this);
|
|
33
36
|
this.translations = new TranslationsResource(this);
|
|
37
|
+
this.push = new PushResource(this);
|
|
34
38
|
}
|
|
35
39
|
static initializeApp(options) {
|
|
36
40
|
checkTimeout(options.timeoutMs);
|
|
37
41
|
checkRetries(options.retries);
|
|
38
42
|
const base = options.baseUrl.replace(/\/$/, '');
|
|
39
43
|
const apiBase = `${base}/public/v2/projects/${options.projectId}`;
|
|
44
|
+
if (options.locale !== undefined)
|
|
45
|
+
setRequestLocale(apiBase, options.locale);
|
|
40
46
|
return new VeroXMApp(apiBase, options.tokenStorage ?? defaultTokenStorage(options.projectId), options.pendingStore, {
|
|
41
47
|
timeoutMs: options.timeoutMs,
|
|
42
48
|
retries: options.retries,
|
|
43
49
|
});
|
|
44
50
|
}
|
|
51
|
+
/** The language error answers are worded in from now on (`VeroXMApiError.userMessage`); null: the browser's own. */
|
|
52
|
+
setLocale(locale) {
|
|
53
|
+
setRequestLocale(this.apiBase, locale);
|
|
54
|
+
}
|
|
45
55
|
/** Typed access to one content collection's entries (list/get/create/update/delete/search). */
|
|
46
56
|
content(collectionSlug) {
|
|
47
57
|
return new ContentResource(this, collectionSlug);
|
package/dist/embed.d.ts
CHANGED
|
@@ -1,7 +1,12 @@
|
|
|
1
1
|
export type FormEmbedMode = 'inline' | 'popup' | 'fullpage' | 'toast';
|
|
2
2
|
export interface FormEmbedOpenTrigger {
|
|
3
|
-
/**
|
|
4
|
-
|
|
3
|
+
/**
|
|
4
|
+
* When a popup or toast opens by itself: on page load, after `delaySeconds`, once the visitor has scrolled
|
|
5
|
+
* `scrollPercent` of the page, or when they look like leaving (`exit`: the pointer leaves through the top of the
|
|
6
|
+
* window; on touch screens, a quick scroll back up after reading a screen or more). Default: manual (call `open()`,
|
|
7
|
+
* or use `trigger`). `exit` since 1.15.0.
|
|
8
|
+
*/
|
|
9
|
+
on?: 'load' | 'delay' | 'scroll' | 'exit' | 'manual';
|
|
5
10
|
delaySeconds?: number;
|
|
6
11
|
scrollPercent?: number;
|
|
7
12
|
}
|
|
@@ -36,12 +41,23 @@ export interface FormEmbedOptions {
|
|
|
36
41
|
autoCloseSeconds?: number;
|
|
37
42
|
/** The iframe's accessible name (default "Form"). */
|
|
38
43
|
title?: string;
|
|
44
|
+
/**
|
|
45
|
+
* A survey card's token (VeroXM's script tag passes it for targeted surveys): sent with the response, so it is linked
|
|
46
|
+
* to its survey, test and variant.
|
|
47
|
+
* @since 1.15.0
|
|
48
|
+
*/
|
|
49
|
+
survey?: string;
|
|
39
50
|
/**
|
|
40
51
|
* Forms that need signing in: the signed-in person's access token for this project (from @veroxm/sdk's
|
|
41
52
|
* `app.auth.getAccessToken()`). Called when the form asks; return null if nobody is signed in.
|
|
42
53
|
*/
|
|
43
54
|
getToken?: () => string | null | undefined | Promise<string | null | undefined>;
|
|
44
55
|
onReady?: () => void;
|
|
56
|
+
/**
|
|
57
|
+
* The popup or toast opened (by itself or with `open()`).
|
|
58
|
+
* @since 1.15.0
|
|
59
|
+
*/
|
|
60
|
+
onOpen?: () => void;
|
|
45
61
|
/** The first answer. */
|
|
46
62
|
onStarted?: () => void;
|
|
47
63
|
/** The form was sent. */
|
|
@@ -73,6 +89,12 @@ export interface FormEmbed {
|
|
|
73
89
|
/** Remove everything this embed added to the page. */
|
|
74
90
|
destroy(): void;
|
|
75
91
|
}
|
|
92
|
+
/**
|
|
93
|
+
* Calls `fire` once when the visitor looks like leaving: the pointer leaves through the top of the window (towards the
|
|
94
|
+
* tabs and address bar), or, on touch screens, a quick scroll back up (40% of the screen within half a second) after
|
|
95
|
+
* reading at least one screen. Returns a function that stops listening.
|
|
96
|
+
*/
|
|
97
|
+
export declare function onExitIntent(fire: () => void): () => void;
|
|
76
98
|
/**
|
|
77
99
|
* Shows a VeroXM form in the page. Returns a handle to open, close or remove it.
|
|
78
100
|
*
|
package/dist/embed.js
CHANGED
|
@@ -65,6 +65,43 @@ function storageSet(key, value) {
|
|
|
65
65
|
// Storage blocked: the toast just shows again next time.
|
|
66
66
|
}
|
|
67
67
|
}
|
|
68
|
+
/**
|
|
69
|
+
* Calls `fire` once when the visitor looks like leaving: the pointer leaves through the top of the window (towards the
|
|
70
|
+
* tabs and address bar), or, on touch screens, a quick scroll back up (40% of the screen within half a second) after
|
|
71
|
+
* reading at least one screen. Returns a function that stops listening.
|
|
72
|
+
*/
|
|
73
|
+
export function onExitIntent(fire) {
|
|
74
|
+
let done = false;
|
|
75
|
+
let deepest = 0;
|
|
76
|
+
let mark = { y: window.scrollY, t: Date.now() };
|
|
77
|
+
const stop = () => {
|
|
78
|
+
document.removeEventListener('mouseout', onOut);
|
|
79
|
+
window.removeEventListener('scroll', onScroll);
|
|
80
|
+
};
|
|
81
|
+
const go = () => {
|
|
82
|
+
if (done)
|
|
83
|
+
return;
|
|
84
|
+
done = true;
|
|
85
|
+
stop();
|
|
86
|
+
fire();
|
|
87
|
+
};
|
|
88
|
+
const onOut = (e) => {
|
|
89
|
+
if (!e.relatedTarget && e.clientY <= 0)
|
|
90
|
+
go();
|
|
91
|
+
};
|
|
92
|
+
const onScroll = () => {
|
|
93
|
+
const y = window.scrollY;
|
|
94
|
+
const now = Date.now();
|
|
95
|
+
deepest = Math.max(deepest, y);
|
|
96
|
+
if (now - mark.t > 500 || y > mark.y)
|
|
97
|
+
mark = { y, t: now };
|
|
98
|
+
else if (deepest >= window.innerHeight && mark.y - y >= window.innerHeight * 0.4)
|
|
99
|
+
go();
|
|
100
|
+
};
|
|
101
|
+
document.addEventListener('mouseout', onOut);
|
|
102
|
+
window.addEventListener('scroll', onScroll, { passive: true });
|
|
103
|
+
return stop;
|
|
104
|
+
}
|
|
68
105
|
/**
|
|
69
106
|
* Shows a VeroXM form in the page. Returns a handle to open, close or remove it.
|
|
70
107
|
*
|
|
@@ -100,6 +137,8 @@ export function embedForm(options) {
|
|
|
100
137
|
url.searchParams.set('vx_page', window.location.href.slice(0, 1500));
|
|
101
138
|
if (document.referrer)
|
|
102
139
|
url.searchParams.set('vx_ref', document.referrer.slice(0, 500));
|
|
140
|
+
if (options.survey)
|
|
141
|
+
url.searchParams.set('vx_survey', options.survey);
|
|
103
142
|
const iframe = el('iframe', 'vxe-frame');
|
|
104
143
|
iframe.title = options.title ?? 'Form';
|
|
105
144
|
iframe.allow = 'clipboard-write';
|
|
@@ -223,6 +262,7 @@ export function embedForm(options) {
|
|
|
223
262
|
shell?.classList.add('vxe-in');
|
|
224
263
|
iframe.focus();
|
|
225
264
|
});
|
|
265
|
+
options.onOpen?.();
|
|
226
266
|
},
|
|
227
267
|
close() {
|
|
228
268
|
if (closeTimer)
|
|
@@ -289,6 +329,9 @@ export function embedForm(options) {
|
|
|
289
329
|
cleanups.push(() => window.removeEventListener('scroll', onScroll));
|
|
290
330
|
onScroll();
|
|
291
331
|
}
|
|
332
|
+
else if (auto === 'exit') {
|
|
333
|
+
cleanups.push(onExitIntent(() => handle.open()));
|
|
334
|
+
}
|
|
292
335
|
}
|
|
293
336
|
return handle;
|
|
294
337
|
}
|
|
@@ -328,7 +371,7 @@ export function embedFormsFromPage(baseUrl, root = document) {
|
|
|
328
371
|
autoHeight: d.autoHeight === 'true',
|
|
329
372
|
size: d.size === 'small' || d.size === 'large' ? d.size : undefined,
|
|
330
373
|
position: d.position === 'bottom-left' ? 'bottom-left' : undefined,
|
|
331
|
-
openOn: { on: ['load', 'delay', 'scroll', 'manual'].find((o) => o === d.openOn) ?? 'manual', delaySeconds: num(d.delay), scrollPercent: num(d.scroll) },
|
|
374
|
+
openOn: { on: ['load', 'delay', 'scroll', 'exit', 'manual'].find((o) => o === d.openOn) ?? 'manual', delaySeconds: num(d.delay), scrollPercent: num(d.scroll) },
|
|
332
375
|
trigger: (mode === 'popup' || mode === 'toast') && node.tagName !== 'SCRIPT' ? node : undefined,
|
|
333
376
|
rememberDismissDays: num(d.rememberDays),
|
|
334
377
|
autoCloseSeconds: num(d.autoClose),
|
package/dist/errors.d.ts
CHANGED
|
@@ -15,6 +15,13 @@ export declare class VeroXMApiError extends Error {
|
|
|
15
15
|
* `sign_up_closed`, `too_many_attempts`, `access_denied`, `function_limit`.
|
|
16
16
|
*/
|
|
17
17
|
readonly code: string | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* The words to show your app's user, in their language (the app's `locale`, else the browser's): the project's own
|
|
20
|
+
* (app translations, `errors.<code>`) or VeroXM's English and Arabic. `message` stays the developer's English.
|
|
21
|
+
*/
|
|
22
|
+
readonly userMessage: string | undefined;
|
|
23
|
+
/** For an entry that didn't validate (`code` "validation_failed"): by field, what to show under it. */
|
|
24
|
+
readonly fieldErrors: Record<string, string> | undefined;
|
|
18
25
|
constructor(status: number, body: unknown);
|
|
19
26
|
private static messageFrom;
|
|
20
27
|
}
|
package/dist/errors.js
CHANGED
|
@@ -13,8 +13,10 @@ export class VeroXMApiError extends Error {
|
|
|
13
13
|
this.name = 'VeroXMApiError';
|
|
14
14
|
this.status = status;
|
|
15
15
|
this.body = body;
|
|
16
|
-
const
|
|
17
|
-
this.code = typeof
|
|
16
|
+
const b = body && typeof body === 'object' ? body : {};
|
|
17
|
+
this.code = typeof b.code === 'string' ? b.code : undefined;
|
|
18
|
+
this.userMessage = typeof b.userMessage === 'string' ? b.userMessage : undefined;
|
|
19
|
+
this.fieldErrors = b.fieldErrors && typeof b.fieldErrors === 'object' && !Array.isArray(b.fieldErrors) ? b.fieldErrors : undefined;
|
|
18
20
|
}
|
|
19
21
|
static messageFrom(status, body) {
|
|
20
22
|
if (body && typeof body === 'object') {
|
package/dist/files.d.ts
ADDED
|
@@ -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
|
+
}
|