tevrocsdk 0.1.41 → 0.1.42
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 +516 -516
- package/package.json +20 -20
- package/tevroc-sdk.esm.js +8 -63
- package/tevroc-sdk.min.js +31 -31
- package/tevroc-sdk.umd.js +8 -63
package/README.md
CHANGED
|
@@ -1,516 +1,516 @@
|
|
|
1
|
-
# Tevroc SDK
|
|
2
|
-
|
|
3
|
-
Tevroc SDK helps you work with Tevroc apps and worker APIs from JavaScript or TypeScript projects. Use it for authentication, records, custom functions, AI integrations, payments, file handling, and more.
|
|
4
|
-
|
|
5
|
-
## Install
|
|
6
|
-
|
|
7
|
-
### npm / ESM
|
|
8
|
-
```bash
|
|
9
|
-
npm install tevrocsdk
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
### Browser
|
|
13
|
-
```html
|
|
14
|
-
<script src="https://unpkg.com/tevrocsdk@latest/tevroc-sdk.min.js"></script>
|
|
15
|
-
<script>
|
|
16
|
-
const tevroc = Tevroc.createClient({
|
|
17
|
-
baseUrl: "https://your-worker.example.workers.dev"
|
|
18
|
-
});
|
|
19
|
-
</script>
|
|
20
|
-
```
|
|
21
|
-
|
|
22
|
-
## Native / desktop integration (Capacitor and Tauri)
|
|
23
|
-
|
|
24
|
-
Tevroc SDK works in web apps, but it also fits naturally into mobile and desktop shells. When you need OAuth callbacks, native file access, or deep links, the host app usually provides the platform bridge and the SDK supplies the API client.
|
|
25
|
-
|
|
26
|
-
### Capacitor (mobile)
|
|
27
|
-
- Declare the app identity and a custom URL scheme in your Capacitor config so the app can receive OAuth redirects.
|
|
28
|
-
- Add the Capacitor app and browser plugins so the SDK can use native file save, toast, and browser flows when available.
|
|
29
|
-
- Add an Android intent filter so the platform can route callback URLs back into your app.
|
|
30
|
-
- Listen for the platform event and forward the URL into your auth callback flow.
|
|
31
|
-
- For offline support, the SDK will keep using native storage when the Capacitor SQLite plugin is available and will safely fall back to localStorage in web or unsupported environments.
|
|
32
|
-
|
|
33
|
-
Typical file locations:
|
|
34
|
-
|
|
35
|
-
```text
|
|
36
|
-
project-root/
|
|
37
|
-
├── capacitor.config.ts
|
|
38
|
-
├── android/
|
|
39
|
-
│ └── app/
|
|
40
|
-
│ └── src/
|
|
41
|
-
│ └── main/
|
|
42
|
-
│ └── AndroidManifest.xml
|
|
43
|
-
└── src/
|
|
44
|
-
└── app code that handles appUrlOpen events
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
A typical setup looks like this:
|
|
48
|
-
|
|
49
|
-
File: capacitor.config.ts
|
|
50
|
-
|
|
51
|
-
```ts
|
|
52
|
-
import type { CapacitorConfig } from "@capacitor/cli";
|
|
53
|
-
|
|
54
|
-
const config: CapacitorConfig = {
|
|
55
|
-
appId: "com.example.app",
|
|
56
|
-
appName: "Example App",
|
|
57
|
-
webDir: "dist",
|
|
58
|
-
plugins: {
|
|
59
|
-
App: {
|
|
60
|
-
appUrlOpen: {
|
|
61
|
-
androidScheme: "myapp",
|
|
62
|
-
iosScheme: "myapp",
|
|
63
|
-
},
|
|
64
|
-
},
|
|
65
|
-
},
|
|
66
|
-
};
|
|
67
|
-
|
|
68
|
-
export default config;
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
File: android/app/src/main/AndroidManifest.xml
|
|
72
|
-
|
|
73
|
-
```xml
|
|
74
|
-
<manifest>
|
|
75
|
-
<uses-permission android:name="android.permission.INTERNET" />
|
|
76
|
-
<application>
|
|
77
|
-
<intent-filter>
|
|
78
|
-
<action android:name="android.intent.action.VIEW" />
|
|
79
|
-
<category android:name="android.intent.category.DEFAULT" />
|
|
80
|
-
<category android:name="android.intent.category.BROWSABLE" />
|
|
81
|
-
<data android:scheme="myapp" />
|
|
82
|
-
</intent-filter>
|
|
83
|
-
</application>
|
|
84
|
-
</manifest>
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
File: src/main.ts or your app bootstrap file
|
|
88
|
-
|
|
89
|
-
```ts
|
|
90
|
-
import { App } from "@capacitor/app";
|
|
91
|
-
|
|
92
|
-
App.addListener("appUrlOpen", ({ url }) => {
|
|
93
|
-
handleAuthCallback(url);
|
|
94
|
-
});
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
### Tauri (desktop)
|
|
98
|
-
- Register a custom protocol in your Tauri config so the desktop app can receive deep links.
|
|
99
|
-
- Add the relevant Rust plugins for deep-link handling and single-instance behavior.
|
|
100
|
-
- Emit a frontend event from the Rust side and listen for it in your app.
|
|
101
|
-
|
|
102
|
-
Typical file locations:
|
|
103
|
-
|
|
104
|
-
```text
|
|
105
|
-
project-root/
|
|
106
|
-
├── src-tauri/
|
|
107
|
-
│ ├── tauri.conf.json
|
|
108
|
-
│ ├── Cargo.toml
|
|
109
|
-
│ └── src/
|
|
110
|
-
│ └── lib.rs
|
|
111
|
-
└── src/
|
|
112
|
-
└── frontend code that listens for deep-link events
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
A typical setup looks like this:
|
|
116
|
-
|
|
117
|
-
File: src-tauri/tauri.conf.json
|
|
118
|
-
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"identifier": "com.example.desktop",
|
|
122
|
-
"plugins": {
|
|
123
|
-
"deep-link": {
|
|
124
|
-
"desktop": {
|
|
125
|
-
"schemes": ["myapp"]
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
File: src-tauri/Cargo.toml
|
|
133
|
-
|
|
134
|
-
```toml
|
|
135
|
-
[dependencies]
|
|
136
|
-
tauri = { version = "2", features = [] }
|
|
137
|
-
tauri-plugin-deep-link = "2"
|
|
138
|
-
tauri-plugin-single-instance = "2"
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
File: src-tauri/src/lib.rs
|
|
142
|
-
|
|
143
|
-
```rust
|
|
144
|
-
use tauri::{Manager, Emitter};
|
|
145
|
-
use tauri_plugin_deep_link::DeepLinkExt;
|
|
146
|
-
use serde_json::json;
|
|
147
|
-
|
|
148
|
-
#[cfg_attr(mobile, tauri::mobile_entry_point)]
|
|
149
|
-
pub fn run() {
|
|
150
|
-
let builder = tauri::Builder::default()
|
|
151
|
-
.plugin(tauri_plugin_single_instance::init(|app, argv, _cwd| {
|
|
152
|
-
if let Some(url) = argv.get(1) {
|
|
153
|
-
let _ = app.emit_to("main", "deep-link://open-url", json!(url));
|
|
154
|
-
}
|
|
155
|
-
}))
|
|
156
|
-
.plugin(tauri_plugin_deep_link::init())
|
|
157
|
-
.setup(|app| {
|
|
158
|
-
#[cfg(any(target_os = "linux", all(debug_assertions, windows)))]
|
|
159
|
-
app.deep_link().register_all()?;
|
|
160
|
-
Ok(())
|
|
161
|
-
});
|
|
162
|
-
|
|
163
|
-
builder.run(tauri::generate_context!()).expect("error while running app");
|
|
164
|
-
}
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
File: src/main.ts or your app bootstrap file
|
|
168
|
-
|
|
169
|
-
```ts
|
|
170
|
-
import { listen } from "@tauri-apps/api/event";
|
|
171
|
-
|
|
172
|
-
listen("deep-link://open-url", (event) => {
|
|
173
|
-
handleAuthCallback(event.payload as string);
|
|
174
|
-
});
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
## Setup notes for local apps and desktop shells
|
|
178
|
-
|
|
179
|
-
If you are consuming the SDK from a monorepo or local workspace, point your app dependency at the local package folder and rebuild the SDK output before launching the app:
|
|
180
|
-
|
|
181
|
-
```bash
|
|
182
|
-
npm install ../tevrocsdk
|
|
183
|
-
cd ../tevrocsdk && npm run build
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
For Tauri desktop apps, ensure the frontend can access the Tauri bridge and the Rust side exposes the PDF command. The recommended setup is:
|
|
187
|
-
|
|
188
|
-
- add the Tauri plugins for deep-link, dialog, fs, opener, and shell in your Rust app
|
|
189
|
-
- expose a command such as `open_pdf_file` from [client-flow/src-tauri/src/lib.rs](../client-flow/src-tauri/src/lib.rs)
|
|
190
|
-
- keep the base64 dependency in [client-flow/src-tauri/Cargo.toml](../client-flow/src-tauri/Cargo.toml)
|
|
191
|
-
|
|
192
|
-
For web and Capacitor apps, preview/print fall back to browser popup windows and native file save flows where available. In offline mode, the SDK keeps a local snapshot of entity data and retries sync when the network is available again.
|
|
193
|
-
|
|
194
|
-
## Added services and capabilities
|
|
195
|
-
|
|
196
|
-
Recent SDK updates include:
|
|
197
|
-
|
|
198
|
-
- PDF helpers: `tevroc.pdf.downloadPdf`, `tevroc.pdf.previewPdf`, and `tevroc.pdf.printPdf`
|
|
199
|
-
- Desktop-friendly PDF handling for Tauri, where the SDK writes a temporary PDF and opens it with the host OS viewer
|
|
200
|
-
- Offline sync support with a safe fallback when Capacitor background-task support is unavailable
|
|
201
|
-
- Native store helpers for web/localStorage fallback and native persistence in Capacitor/Tauri contexts
|
|
202
|
-
- Auth, entity, integration, payments, and file helpers that work through the same unified client object
|
|
203
|
-
|
|
204
|
-
## Create a client
|
|
205
|
-
|
|
206
|
-
Start by creating a client with your Tevroc worker URL and app details. This gives you a single object that you can use throughout your app for authentication, data access, integrations, and more.
|
|
207
|
-
|
|
208
|
-
```js
|
|
209
|
-
import { createClient } from "tevrocsdk";
|
|
210
|
-
|
|
211
|
-
const tevroc = createClient({
|
|
212
|
-
baseUrl: "https://your-worker.example.workers.dev",
|
|
213
|
-
serviceUrl: "https://services.example.com",
|
|
214
|
-
appId: "tevroc-portal",
|
|
215
|
-
appName: "Tevroc Portal",
|
|
216
|
-
});
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
You can also reuse an existing access token:
|
|
220
|
-
|
|
221
|
-
```js
|
|
222
|
-
const tevroc = createClient({
|
|
223
|
-
baseUrl: "https://your-worker.example.workers.dev",
|
|
224
|
-
token: localStorage.getItem("tevroc_access_token"),
|
|
225
|
-
appId: "tevroc-portal",
|
|
226
|
-
appName: "Tevroc Portal",
|
|
227
|
-
});
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
## Authentication
|
|
231
|
-
|
|
232
|
-
Use the authentication helpers to sign users in, keep their session active, and fetch profile information. These methods are useful for login pages, protected screens, and account management flows.
|
|
233
|
-
|
|
234
|
-
### Log in and fetch your profile
|
|
235
|
-
```js
|
|
236
|
-
const { token, user } = await tevroc.auth.login({
|
|
237
|
-
email: "ada@example.com",
|
|
238
|
-
password: "correct horse battery staple",
|
|
239
|
-
});
|
|
240
|
-
|
|
241
|
-
const me = await tevroc.auth.me();
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
### Register, log out, and reset password
|
|
245
|
-
```js
|
|
246
|
-
await tevroc.auth.register({
|
|
247
|
-
email: "ada@example.com",
|
|
248
|
-
password: "correct horse battery staple",
|
|
249
|
-
});
|
|
250
|
-
|
|
251
|
-
await tevroc.auth.logout();
|
|
252
|
-
await tevroc.auth.verifyOtp({ code: "123456" });
|
|
253
|
-
await tevroc.auth.changePassword({ oldPassword: "old", newPassword: "new" });
|
|
254
|
-
await tevroc.auth.resetPassword({ email: "ada@example.com" });
|
|
255
|
-
await tevroc.auth.loginUrl("/dashboard");
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
### Google sign-in
|
|
259
|
-
```js
|
|
260
|
-
await tevroc.auth.googleLogin({
|
|
261
|
-
appId: "tevroc-portal",
|
|
262
|
-
appName: "Tevroc Portal",
|
|
263
|
-
serviceUrl: "https://services.example.com",
|
|
264
|
-
});
|
|
265
|
-
|
|
266
|
-
tevroc.auth.onGoogleLogin((user, error) => {
|
|
267
|
-
if (error) {
|
|
268
|
-
console.error("Google login failed", error);
|
|
269
|
-
return;
|
|
270
|
-
}
|
|
271
|
-
|
|
272
|
-
console.log("Google user", user);
|
|
273
|
-
});
|
|
274
|
-
|
|
275
|
-
await tevroc.auth.loginWithGoogle({
|
|
276
|
-
accessToken: googleAccessToken,
|
|
277
|
-
});
|
|
278
|
-
|
|
279
|
-
await tevroc.auth.loginWithProvider("google", "/dashboard");
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
## Work with entities
|
|
283
|
-
|
|
284
|
-
Entities let you manage dynamic records in a simple, Base44-style way. They are ideal for CRUD screens such as projects, tasks, customers, or any custom business data.
|
|
285
|
-
|
|
286
|
-
```js
|
|
287
|
-
const created = await tevroc.entities.Project.create({
|
|
288
|
-
name: "Launch site",
|
|
289
|
-
status: "active",
|
|
290
|
-
});
|
|
291
|
-
|
|
292
|
-
const projects = await tevroc.entities.Project.list({ limit: 20 });
|
|
293
|
-
|
|
294
|
-
const filtered = await tevroc.entities.Project.query({
|
|
295
|
-
filter: { status: "active" },
|
|
296
|
-
limit: 10,
|
|
297
|
-
});
|
|
298
|
-
|
|
299
|
-
await tevroc.entities.Project.update(created.data.id, { status: "done" });
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
Common entity methods:
|
|
303
|
-
|
|
304
|
-
- `list({ limit, offset })`
|
|
305
|
-
- `get(id)`
|
|
306
|
-
- `create(record)`
|
|
307
|
-
- `update(id, patch)`
|
|
308
|
-
- `delete(id)`
|
|
309
|
-
- `query({ filter, limit })`
|
|
310
|
-
- `filter(filter, sortOrOptions, limit)`
|
|
311
|
-
- `bulkCreate(records)`
|
|
312
|
-
- `bulkUpdate(records)`
|
|
313
|
-
- `bulkDelete(ids)`
|
|
314
|
-
- `import(records)`
|
|
315
|
-
|
|
316
|
-
## Call custom functions
|
|
317
|
-
|
|
318
|
-
Use custom functions when you want to trigger server-side logic by name. This is useful for actions such as sending data to a worker route, running a calculation, or invoking a workflow.
|
|
319
|
-
|
|
320
|
-
```js
|
|
321
|
-
await tevroc.functions.invoke("ping", { hello: "world" });
|
|
322
|
-
|
|
323
|
-
// Shorthand for common functions
|
|
324
|
-
await tevroc.functions.ping({ hello: "world" });
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
## Use core integrations
|
|
328
|
-
|
|
329
|
-
Core integrations give you quick access to common AI and content features such as LLM prompts, image generation, email delivery, file uploads, and signed URLs. These helpers make it easy to add backend-powered features without writing custom plumbing.
|
|
330
|
-
|
|
331
|
-
```js
|
|
332
|
-
await tevroc.integrations.Core.InvokeLLM({
|
|
333
|
-
prompt: "Write a two-line launch checklist.",
|
|
334
|
-
});
|
|
335
|
-
|
|
336
|
-
await tevroc.integrations.Core.GenerateImage({
|
|
337
|
-
prompt: "A futuristic dashboard",
|
|
338
|
-
});
|
|
339
|
-
|
|
340
|
-
await tevroc.integrations.Core.SendEmail({
|
|
341
|
-
to: "ada@example.com",
|
|
342
|
-
subject: "Hello",
|
|
343
|
-
text: "From Tevroc",
|
|
344
|
-
});
|
|
345
|
-
|
|
346
|
-
await tevroc.integrations.Core.UploadFile(file, {
|
|
347
|
-
filename: "report.pdf",
|
|
348
|
-
contentType: "application/pdf",
|
|
349
|
-
});
|
|
350
|
-
|
|
351
|
-
await tevroc.integrations.Core.UploadPrivateFile(file, {
|
|
352
|
-
filename: "report.pdf",
|
|
353
|
-
contentType: "application/pdf",
|
|
354
|
-
});
|
|
355
|
-
|
|
356
|
-
await tevroc.integrations.Core.CreateFileSignedUrl({
|
|
357
|
-
key: "report.pdf",
|
|
358
|
-
});
|
|
359
|
-
|
|
360
|
-
await tevroc.integrations.Core.ExtractDataFromUploadedFile({
|
|
361
|
-
fileId: "123",
|
|
362
|
-
});
|
|
363
|
-
```
|
|
364
|
-
|
|
365
|
-
## Accept payments
|
|
366
|
-
|
|
367
|
-
If your app needs a checkout or payment flow, the payments helpers can start a Yoco-based payment experience and let you react to the resulting status updates.
|
|
368
|
-
|
|
369
|
-
```js
|
|
370
|
-
await tevroc.payments.create({
|
|
371
|
-
amountZAR: 50,
|
|
372
|
-
appId: "tevroc-portal",
|
|
373
|
-
mode: "web",
|
|
374
|
-
});
|
|
375
|
-
|
|
376
|
-
const unsubscribe = tevroc.payments.onstatus((status, error) => {
|
|
377
|
-
if (error) {
|
|
378
|
-
console.error("Payment listener error", error);
|
|
379
|
-
return;
|
|
380
|
-
}
|
|
381
|
-
|
|
382
|
-
console.log("Payment status:", status);
|
|
383
|
-
});
|
|
384
|
-
```
|
|
385
|
-
|
|
386
|
-
## Work with files and local app data
|
|
387
|
-
|
|
388
|
-
Use the file helpers to build links for uploaded assets and the native helpers to store lightweight app data locally across web, mobile, and desktop environments.
|
|
389
|
-
|
|
390
|
-
```js
|
|
391
|
-
const fileUrl = tevroc.files.url("reports/summary.pdf");
|
|
392
|
-
const privateFileUrl = tevroc.files.privateUrl("reports/private.pdf");
|
|
393
|
-
|
|
394
|
-
await tevroc.files.get("reports/summary.pdf");
|
|
395
|
-
await tevroc.files.getPrivate("reports/private.pdf");
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
### Native store helpers
|
|
399
|
-
```js
|
|
400
|
-
const store = tevroc.native.store;
|
|
401
|
-
const ref = store.ref("settings");
|
|
402
|
-
await store.set(ref, { theme: "dark" });
|
|
403
|
-
await store.update(ref, { lastOpened: Date.now() });
|
|
404
|
-
await store.get(ref);
|
|
405
|
-
await store.remove(ref);
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
### Google Drive and project helpers
|
|
409
|
-
```js
|
|
410
|
-
await tevroc.native.files.saveJsonToDrive("project", { ok: true }, null, "user-1");
|
|
411
|
-
await tevroc.native.files.readJsonFromDrive("file_123", "user-1");
|
|
412
|
-
await tevroc.native.files.deleteFromDrive("file_123", "user-1");
|
|
413
|
-
|
|
414
|
-
await tevroc.native.projects.upsertUser({
|
|
415
|
-
uid: "u1",
|
|
416
|
-
email: "ada@example.com",
|
|
417
|
-
displayName: "Ada",
|
|
418
|
-
photoURL: "",
|
|
419
|
-
});
|
|
420
|
-
|
|
421
|
-
await tevroc.native.projects.saveProjectMeta("u1", "p1", { title: "Launch" });
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
## Create agent conversations
|
|
425
|
-
|
|
426
|
-
Agents are useful when you want to create multi-turn conversations with a support or assistant experience. You can start a conversation, add user messages, and list the thread history from the SDK.
|
|
427
|
-
|
|
428
|
-
```js
|
|
429
|
-
const conversation = await tevroc.agents.Support.createConversation({
|
|
430
|
-
title: "Onboarding",
|
|
431
|
-
});
|
|
432
|
-
|
|
433
|
-
## Offline & sync features
|
|
434
|
-
|
|
435
|
-
The SDK distribution includes built-in offline sync support when used in apps that integrate the native helpers (Capacitor/Tauri). Key features:
|
|
436
|
-
|
|
437
|
-
- Local storage of entities using platform-native SQLite when available (Capacitor/Tauri), with `localStorage` fallback.
|
|
438
|
-
- Queued operations: `create`, `update`, and `delete` are queued while offline and applied locally immediately so the UI remains responsive.
|
|
439
|
-
- Sync engine: periodic and event-driven flush of queued operations when the app regains connectivity or resumes; emits events and stores simple conflicts detected by timestamp comparison.
|
|
440
|
-
- Conflict APIs: `client.offline.listConflicts()` and `client.offline.resolveConflict(conflictId, resolution)` let apps inspect and resolve conflicts.
|
|
441
|
-
|
|
442
|
-
Example usage:
|
|
443
|
-
|
|
444
|
-
```js
|
|
445
|
-
const client = createClient({ baseUrl: 'https://api.example', appId: 'myapp' });
|
|
446
|
-
client.offline.startAutoSync();
|
|
447
|
-
|
|
448
|
-
client.offline.on('conflict', ({ conflictId }) => {
|
|
449
|
-
console.warn('Conflict detected:', conflictId);
|
|
450
|
-
});
|
|
451
|
-
```
|
|
452
|
-
|
|
453
|
-
Notes:
|
|
454
|
-
- The SDK attempts to use `@capacitor/network`, `@capacitor/app`, and `@capacitor-community/background-task` when available. If plugins are missing it falls back to foreground sync on resume/focus.
|
|
455
|
-
- For production mobile background sync, configure OS-level background permissions and install/verify background-task plugins.
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
await tevroc.agents.Support.addMessage(conversation.data.id, {
|
|
459
|
-
role: "user",
|
|
460
|
-
content: "Help me configure my workspace",
|
|
461
|
-
});
|
|
462
|
-
|
|
463
|
-
const messages = await tevroc.agents.Support.listMessages(conversation.data.id);
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
## Connectors, logs, custom integrations, and SSO
|
|
467
|
-
|
|
468
|
-
These features help you connect external services, track app events, call custom integrations, and handle SSO flows. They are especially useful for admin dashboards, automation, and customer-facing experiences.
|
|
469
|
-
|
|
470
|
-
```js
|
|
471
|
-
await tevroc.connectors.list();
|
|
472
|
-
await tevroc.connectors.get("slack");
|
|
473
|
-
await tevroc.connectors.connect("slack", { config: { teamId: "T123" } });
|
|
474
|
-
await tevroc.connectors.disconnect("slack");
|
|
475
|
-
await tevroc.connectors.status("slack");
|
|
476
|
-
|
|
477
|
-
await tevroc.connectors.user.list();
|
|
478
|
-
await tevroc.connectors.user.refresh("abc123");
|
|
479
|
-
|
|
480
|
-
await tevroc.logs.list({ limit: 20 });
|
|
481
|
-
await tevroc.logs.create({
|
|
482
|
-
level: "info",
|
|
483
|
-
message: "User opened dashboard",
|
|
484
|
-
context: { source: "web" },
|
|
485
|
-
});
|
|
486
|
-
|
|
487
|
-
await tevroc.customIntegrations.example.echo({ ok: true });
|
|
488
|
-
await tevroc.sso.accessToken({ code: "provider-code" });
|
|
489
|
-
await tevroc.sso.callback({ code: "provider-code" });
|
|
490
|
-
```
|
|
491
|
-
|
|
492
|
-
## Make raw requests
|
|
493
|
-
|
|
494
|
-
Use `request` when you need to call a worker route that does not yet have a dedicated helper. This gives you a flexible fallback for custom endpoints while still using the same authenticated client.
|
|
495
|
-
|
|
496
|
-
```js
|
|
497
|
-
const health = await tevroc.request("/health", { auth: false });
|
|
498
|
-
```
|
|
499
|
-
|
|
500
|
-
## Handle errors
|
|
501
|
-
|
|
502
|
-
Tevroc SDK throws structured errors that make it easier to respond to failed requests. You can inspect the status code and details to guide the user experience or retry logic.
|
|
503
|
-
|
|
504
|
-
```js
|
|
505
|
-
import { TevrocError } from "tevrocsdk";
|
|
506
|
-
|
|
507
|
-
try {
|
|
508
|
-
await tevroc.auth.me();
|
|
509
|
-
} catch (error) {
|
|
510
|
-
if (error instanceof TevrocError && error.status === 401) {
|
|
511
|
-
// Ask the user to sign in again.
|
|
512
|
-
}
|
|
513
|
-
}
|
|
514
|
-
```
|
|
515
|
-
|
|
516
|
-
|
|
1
|
+
# Tevroc SDK
|
|
2
|
+
|
|
3
|
+
Tevroc SDK helps you work with Tevroc apps and worker APIs from JavaScript or TypeScript projects. Use it for authentication, records, custom functions, AI integrations, payments, file handling, and more.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
### npm / ESM
|
|
8
|
+
```bash
|
|
9
|
+
npm install tevrocsdk
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
### Browser
|
|
13
|
+
```html
|
|
14
|
+
<script src="https://unpkg.com/tevrocsdk@latest/tevroc-sdk.min.js"></script>
|
|
15
|
+
<script>
|
|
16
|
+
const tevroc = Tevroc.createClient({
|
|
17
|
+
baseUrl: "https://your-worker.example.workers.dev"
|
|
18
|
+
});
|
|
19
|
+
</script>
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Native / desktop integration (Capacitor and Tauri)
|
|
23
|
+
|
|
24
|
+
Tevroc SDK works in web apps, but it also fits naturally into mobile and desktop shells. When you need OAuth callbacks, native file access, or deep links, the host app usually provides the platform bridge and the SDK supplies the API client.
|
|
25
|
+
|
|
26
|
+
### Capacitor (mobile)
|
|
27
|
+
- Declare the app identity and a custom URL scheme in your Capacitor config so the app can receive OAuth redirects.
|
|
28
|
+
- Add the Capacitor app and browser plugins so the SDK can use native file save, toast, and browser flows when available.
|
|
29
|
+
- Add an Android intent filter so the platform can route callback URLs back into your app.
|
|
30
|
+
- Listen for the platform event and forward the URL into your auth callback flow.
|
|
31
|
+
- For offline support, the SDK will keep using native storage when the Capacitor SQLite plugin is available and will safely fall back to localStorage in web or unsupported environments.
|
|
32
|
+
|
|
33
|
+
Typical file locations:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
project-root/
|
|
37
|
+
├── capacitor.config.ts
|
|
38
|
+
├── android/
|
|
39
|
+
│ └── app/
|
|
40
|
+
│ └── src/
|
|
41
|
+
│ └── main/
|
|
42
|
+
│ └── AndroidManifest.xml
|
|
43
|
+
└── src/
|
|
44
|
+
└── app code that handles appUrlOpen events
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
A typical setup looks like this:
|
|
48
|
+
|
|
49
|
+
File: capacitor.config.ts
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
import type { CapacitorConfig } from "@capacitor/cli";
|
|
53
|
+
|
|
54
|
+
const config: CapacitorConfig = {
|
|
55
|
+
appId: "com.example.app",
|
|
56
|
+
appName: "Example App",
|
|
57
|
+
webDir: "dist",
|
|
58
|
+
plugins: {
|
|
59
|
+
App: {
|
|
60
|
+
appUrlOpen: {
|
|
61
|
+
androidScheme: "myapp",
|
|
62
|
+
iosScheme: "myapp",
|
|
63
|
+
},
|
|
64
|
+
},
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
export default config;
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
File: android/app/src/main/AndroidManifest.xml
|
|
72
|
+
|
|
73
|
+
```xml
|
|
74
|
+
<manifest>
|
|
75
|
+
<uses-permission android:name="android.permission.INTERNET" />
|
|
76
|
+
<application>
|
|
77
|
+
<intent-filter>
|
|
78
|
+
<action android:name="android.intent.action.VIEW" />
|
|
79
|
+
<category android:name="android.intent.category.DEFAULT" />
|
|
80
|
+
<category android:name="android.intent.category.BROWSABLE" />
|
|
81
|
+
<data android:scheme="myapp" />
|
|
82
|
+
</intent-filter>
|
|
83
|
+
</application>
|
|
84
|
+
</manifest>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
File: src/main.ts or your app bootstrap file
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
import { App } from "@capacitor/app";
|
|
91
|
+
|
|
92
|
+
App.addListener("appUrlOpen", ({ url }) => {
|
|
93
|
+
handleAuthCallback(url);
|
|
94
|
+
});
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Tauri (desktop)
|
|
98
|
+
- Register a custom protocol in your Tauri config so the desktop app can receive deep links.
|
|
99
|
+
- Add the relevant Rust plugins for deep-link handling and single-instance behavior.
|
|
100
|
+
- Emit a frontend event from the Rust side and listen for it in your app.
|
|
101
|
+
|
|
102
|
+
Typical file locations:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
project-root/
|
|
106
|
+
├── src-tauri/
|
|
107
|
+
│ ├── tauri.conf.json
|
|
108
|
+
│ ├── Cargo.toml
|
|
109
|
+
│ └── src/
|
|
110
|
+
│ └── lib.rs
|
|
111
|
+
└── src/
|
|
112
|
+
└── frontend code that listens for deep-link events
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
A typical setup looks like this:
|
|
116
|
+
|
|
117
|
+
File: src-tauri/tauri.conf.json
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"identifier": "com.example.desktop",
|
|
122
|
+
"plugins": {
|
|
123
|
+
"deep-link": {
|
|
124
|
+
"desktop": {
|
|
125
|
+
"schemes": ["myapp"]
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
File: src-tauri/Cargo.toml
|
|
133
|
+
|
|
134
|
+
```toml
|
|
135
|
+
[dependencies]
|
|
136
|
+
tauri = { version = "2", features = [] }
|
|
137
|
+
tauri-plugin-deep-link = "2"
|
|
138
|
+
tauri-plugin-single-instance = "2"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
File: src-tauri/src/lib.rs
|
|
142
|
+
|
|
143
|
+
```rust
|
|
144
|
+
use tauri::{Manager, Emitter};
|
|
145
|
+
use tauri_plugin_deep_link::DeepLinkExt;
|
|
146
|
+
use serde_json::json;
|
|
147
|
+
|
|
148
|
+
#[cfg_attr(mobile, tauri::mobile_entry_point)]
|
|
149
|
+
pub fn run() {
|
|
150
|
+
let builder = tauri::Builder::default()
|
|
151
|
+
.plugin(tauri_plugin_single_instance::init(|app, argv, _cwd| {
|
|
152
|
+
if let Some(url) = argv.get(1) {
|
|
153
|
+
let _ = app.emit_to("main", "deep-link://open-url", json!(url));
|
|
154
|
+
}
|
|
155
|
+
}))
|
|
156
|
+
.plugin(tauri_plugin_deep_link::init())
|
|
157
|
+
.setup(|app| {
|
|
158
|
+
#[cfg(any(target_os = "linux", all(debug_assertions, windows)))]
|
|
159
|
+
app.deep_link().register_all()?;
|
|
160
|
+
Ok(())
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
builder.run(tauri::generate_context!()).expect("error while running app");
|
|
164
|
+
}
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
File: src/main.ts or your app bootstrap file
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
import { listen } from "@tauri-apps/api/event";
|
|
171
|
+
|
|
172
|
+
listen("deep-link://open-url", (event) => {
|
|
173
|
+
handleAuthCallback(event.payload as string);
|
|
174
|
+
});
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## Setup notes for local apps and desktop shells
|
|
178
|
+
|
|
179
|
+
If you are consuming the SDK from a monorepo or local workspace, point your app dependency at the local package folder and rebuild the SDK output before launching the app:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
npm install ../tevrocsdk
|
|
183
|
+
cd ../tevrocsdk && npm run build
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
For Tauri desktop apps, ensure the frontend can access the Tauri bridge and the Rust side exposes the PDF command. The recommended setup is:
|
|
187
|
+
|
|
188
|
+
- add the Tauri plugins for deep-link, dialog, fs, opener, and shell in your Rust app
|
|
189
|
+
- expose a command such as `open_pdf_file` from [client-flow/src-tauri/src/lib.rs](../client-flow/src-tauri/src/lib.rs)
|
|
190
|
+
- keep the base64 dependency in [client-flow/src-tauri/Cargo.toml](../client-flow/src-tauri/Cargo.toml)
|
|
191
|
+
|
|
192
|
+
For web and Capacitor apps, preview/print fall back to browser popup windows and native file save flows where available. In offline mode, the SDK keeps a local snapshot of entity data and retries sync when the network is available again.
|
|
193
|
+
|
|
194
|
+
## Added services and capabilities
|
|
195
|
+
|
|
196
|
+
Recent SDK updates include:
|
|
197
|
+
|
|
198
|
+
- PDF helpers: `tevroc.pdf.downloadPdf`, `tevroc.pdf.previewPdf`, and `tevroc.pdf.printPdf`
|
|
199
|
+
- Desktop-friendly PDF handling for Tauri, where the SDK writes a temporary PDF and opens it with the host OS viewer
|
|
200
|
+
- Offline sync support with a safe fallback when Capacitor background-task support is unavailable
|
|
201
|
+
- Native store helpers for web/localStorage fallback and native persistence in Capacitor/Tauri contexts
|
|
202
|
+
- Auth, entity, integration, payments, and file helpers that work through the same unified client object
|
|
203
|
+
|
|
204
|
+
## Create a client
|
|
205
|
+
|
|
206
|
+
Start by creating a client with your Tevroc worker URL and app details. This gives you a single object that you can use throughout your app for authentication, data access, integrations, and more.
|
|
207
|
+
|
|
208
|
+
```js
|
|
209
|
+
import { createClient } from "tevrocsdk";
|
|
210
|
+
|
|
211
|
+
const tevroc = createClient({
|
|
212
|
+
baseUrl: "https://your-worker.example.workers.dev",
|
|
213
|
+
serviceUrl: "https://services.example.com",
|
|
214
|
+
appId: "tevroc-portal",
|
|
215
|
+
appName: "Tevroc Portal",
|
|
216
|
+
});
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
You can also reuse an existing access token:
|
|
220
|
+
|
|
221
|
+
```js
|
|
222
|
+
const tevroc = createClient({
|
|
223
|
+
baseUrl: "https://your-worker.example.workers.dev",
|
|
224
|
+
token: localStorage.getItem("tevroc_access_token"),
|
|
225
|
+
appId: "tevroc-portal",
|
|
226
|
+
appName: "Tevroc Portal",
|
|
227
|
+
});
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
## Authentication
|
|
231
|
+
|
|
232
|
+
Use the authentication helpers to sign users in, keep their session active, and fetch profile information. These methods are useful for login pages, protected screens, and account management flows.
|
|
233
|
+
|
|
234
|
+
### Log in and fetch your profile
|
|
235
|
+
```js
|
|
236
|
+
const { token, user } = await tevroc.auth.login({
|
|
237
|
+
email: "ada@example.com",
|
|
238
|
+
password: "correct horse battery staple",
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
const me = await tevroc.auth.me();
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Register, log out, and reset password
|
|
245
|
+
```js
|
|
246
|
+
await tevroc.auth.register({
|
|
247
|
+
email: "ada@example.com",
|
|
248
|
+
password: "correct horse battery staple",
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
await tevroc.auth.logout();
|
|
252
|
+
await tevroc.auth.verifyOtp({ code: "123456" });
|
|
253
|
+
await tevroc.auth.changePassword({ oldPassword: "old", newPassword: "new" });
|
|
254
|
+
await tevroc.auth.resetPassword({ email: "ada@example.com" });
|
|
255
|
+
await tevroc.auth.loginUrl("/dashboard");
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
### Google sign-in
|
|
259
|
+
```js
|
|
260
|
+
await tevroc.auth.googleLogin({
|
|
261
|
+
appId: "tevroc-portal",
|
|
262
|
+
appName: "Tevroc Portal",
|
|
263
|
+
serviceUrl: "https://services.example.com",
|
|
264
|
+
});
|
|
265
|
+
|
|
266
|
+
tevroc.auth.onGoogleLogin((user, error) => {
|
|
267
|
+
if (error) {
|
|
268
|
+
console.error("Google login failed", error);
|
|
269
|
+
return;
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
console.log("Google user", user);
|
|
273
|
+
});
|
|
274
|
+
|
|
275
|
+
await tevroc.auth.loginWithGoogle({
|
|
276
|
+
accessToken: googleAccessToken,
|
|
277
|
+
});
|
|
278
|
+
|
|
279
|
+
await tevroc.auth.loginWithProvider("google", "/dashboard");
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
## Work with entities
|
|
283
|
+
|
|
284
|
+
Entities let you manage dynamic records in a simple, Base44-style way. They are ideal for CRUD screens such as projects, tasks, customers, or any custom business data.
|
|
285
|
+
|
|
286
|
+
```js
|
|
287
|
+
const created = await tevroc.entities.Project.create({
|
|
288
|
+
name: "Launch site",
|
|
289
|
+
status: "active",
|
|
290
|
+
});
|
|
291
|
+
|
|
292
|
+
const projects = await tevroc.entities.Project.list({ limit: 20 });
|
|
293
|
+
|
|
294
|
+
const filtered = await tevroc.entities.Project.query({
|
|
295
|
+
filter: { status: "active" },
|
|
296
|
+
limit: 10,
|
|
297
|
+
});
|
|
298
|
+
|
|
299
|
+
await tevroc.entities.Project.update(created.data.id, { status: "done" });
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Common entity methods:
|
|
303
|
+
|
|
304
|
+
- `list({ limit, offset })`
|
|
305
|
+
- `get(id)`
|
|
306
|
+
- `create(record)`
|
|
307
|
+
- `update(id, patch)`
|
|
308
|
+
- `delete(id)`
|
|
309
|
+
- `query({ filter, limit })`
|
|
310
|
+
- `filter(filter, sortOrOptions, limit)`
|
|
311
|
+
- `bulkCreate(records)`
|
|
312
|
+
- `bulkUpdate(records)`
|
|
313
|
+
- `bulkDelete(ids)`
|
|
314
|
+
- `import(records)`
|
|
315
|
+
|
|
316
|
+
## Call custom functions
|
|
317
|
+
|
|
318
|
+
Use custom functions when you want to trigger server-side logic by name. This is useful for actions such as sending data to a worker route, running a calculation, or invoking a workflow.
|
|
319
|
+
|
|
320
|
+
```js
|
|
321
|
+
await tevroc.functions.invoke("ping", { hello: "world" });
|
|
322
|
+
|
|
323
|
+
// Shorthand for common functions
|
|
324
|
+
await tevroc.functions.ping({ hello: "world" });
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
## Use core integrations
|
|
328
|
+
|
|
329
|
+
Core integrations give you quick access to common AI and content features such as LLM prompts, image generation, email delivery, file uploads, and signed URLs. These helpers make it easy to add backend-powered features without writing custom plumbing.
|
|
330
|
+
|
|
331
|
+
```js
|
|
332
|
+
await tevroc.integrations.Core.InvokeLLM({
|
|
333
|
+
prompt: "Write a two-line launch checklist.",
|
|
334
|
+
});
|
|
335
|
+
|
|
336
|
+
await tevroc.integrations.Core.GenerateImage({
|
|
337
|
+
prompt: "A futuristic dashboard",
|
|
338
|
+
});
|
|
339
|
+
|
|
340
|
+
await tevroc.integrations.Core.SendEmail({
|
|
341
|
+
to: "ada@example.com",
|
|
342
|
+
subject: "Hello",
|
|
343
|
+
text: "From Tevroc",
|
|
344
|
+
});
|
|
345
|
+
|
|
346
|
+
await tevroc.integrations.Core.UploadFile(file, {
|
|
347
|
+
filename: "report.pdf",
|
|
348
|
+
contentType: "application/pdf",
|
|
349
|
+
});
|
|
350
|
+
|
|
351
|
+
await tevroc.integrations.Core.UploadPrivateFile(file, {
|
|
352
|
+
filename: "report.pdf",
|
|
353
|
+
contentType: "application/pdf",
|
|
354
|
+
});
|
|
355
|
+
|
|
356
|
+
await tevroc.integrations.Core.CreateFileSignedUrl({
|
|
357
|
+
key: "report.pdf",
|
|
358
|
+
});
|
|
359
|
+
|
|
360
|
+
await tevroc.integrations.Core.ExtractDataFromUploadedFile({
|
|
361
|
+
fileId: "123",
|
|
362
|
+
});
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
## Accept payments
|
|
366
|
+
|
|
367
|
+
If your app needs a checkout or payment flow, the payments helpers can start a Yoco-based payment experience and let you react to the resulting status updates.
|
|
368
|
+
|
|
369
|
+
```js
|
|
370
|
+
await tevroc.payments.create({
|
|
371
|
+
amountZAR: 50,
|
|
372
|
+
appId: "tevroc-portal",
|
|
373
|
+
mode: "web",
|
|
374
|
+
});
|
|
375
|
+
|
|
376
|
+
const unsubscribe = tevroc.payments.onstatus((status, error) => {
|
|
377
|
+
if (error) {
|
|
378
|
+
console.error("Payment listener error", error);
|
|
379
|
+
return;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
console.log("Payment status:", status);
|
|
383
|
+
});
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
## Work with files and local app data
|
|
387
|
+
|
|
388
|
+
Use the file helpers to build links for uploaded assets and the native helpers to store lightweight app data locally across web, mobile, and desktop environments.
|
|
389
|
+
|
|
390
|
+
```js
|
|
391
|
+
const fileUrl = tevroc.files.url("reports/summary.pdf");
|
|
392
|
+
const privateFileUrl = tevroc.files.privateUrl("reports/private.pdf");
|
|
393
|
+
|
|
394
|
+
await tevroc.files.get("reports/summary.pdf");
|
|
395
|
+
await tevroc.files.getPrivate("reports/private.pdf");
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
### Native store helpers
|
|
399
|
+
```js
|
|
400
|
+
const store = tevroc.native.store;
|
|
401
|
+
const ref = store.ref("settings");
|
|
402
|
+
await store.set(ref, { theme: "dark" });
|
|
403
|
+
await store.update(ref, { lastOpened: Date.now() });
|
|
404
|
+
await store.get(ref);
|
|
405
|
+
await store.remove(ref);
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### Google Drive and project helpers
|
|
409
|
+
```js
|
|
410
|
+
await tevroc.native.files.saveJsonToDrive("project", { ok: true }, null, "user-1");
|
|
411
|
+
await tevroc.native.files.readJsonFromDrive("file_123", "user-1");
|
|
412
|
+
await tevroc.native.files.deleteFromDrive("file_123", "user-1");
|
|
413
|
+
|
|
414
|
+
await tevroc.native.projects.upsertUser({
|
|
415
|
+
uid: "u1",
|
|
416
|
+
email: "ada@example.com",
|
|
417
|
+
displayName: "Ada",
|
|
418
|
+
photoURL: "",
|
|
419
|
+
});
|
|
420
|
+
|
|
421
|
+
await tevroc.native.projects.saveProjectMeta("u1", "p1", { title: "Launch" });
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
## Create agent conversations
|
|
425
|
+
|
|
426
|
+
Agents are useful when you want to create multi-turn conversations with a support or assistant experience. You can start a conversation, add user messages, and list the thread history from the SDK.
|
|
427
|
+
|
|
428
|
+
```js
|
|
429
|
+
const conversation = await tevroc.agents.Support.createConversation({
|
|
430
|
+
title: "Onboarding",
|
|
431
|
+
});
|
|
432
|
+
|
|
433
|
+
## Offline & sync features
|
|
434
|
+
|
|
435
|
+
The SDK distribution includes built-in offline sync support when used in apps that integrate the native helpers (Capacitor/Tauri). Key features:
|
|
436
|
+
|
|
437
|
+
- Local storage of entities using platform-native SQLite when available (Capacitor/Tauri), with `localStorage` fallback.
|
|
438
|
+
- Queued operations: `create`, `update`, and `delete` are queued while offline and applied locally immediately so the UI remains responsive.
|
|
439
|
+
- Sync engine: periodic and event-driven flush of queued operations when the app regains connectivity or resumes; emits events and stores simple conflicts detected by timestamp comparison.
|
|
440
|
+
- Conflict APIs: `client.offline.listConflicts()` and `client.offline.resolveConflict(conflictId, resolution)` let apps inspect and resolve conflicts.
|
|
441
|
+
|
|
442
|
+
Example usage:
|
|
443
|
+
|
|
444
|
+
```js
|
|
445
|
+
const client = createClient({ baseUrl: 'https://api.example', appId: 'myapp' });
|
|
446
|
+
client.offline.startAutoSync();
|
|
447
|
+
|
|
448
|
+
client.offline.on('conflict', ({ conflictId }) => {
|
|
449
|
+
console.warn('Conflict detected:', conflictId);
|
|
450
|
+
});
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
Notes:
|
|
454
|
+
- The SDK attempts to use `@capacitor/network`, `@capacitor/app`, and `@capacitor-community/background-task` when available. If plugins are missing it falls back to foreground sync on resume/focus.
|
|
455
|
+
- For production mobile background sync, configure OS-level background permissions and install/verify background-task plugins.
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
await tevroc.agents.Support.addMessage(conversation.data.id, {
|
|
459
|
+
role: "user",
|
|
460
|
+
content: "Help me configure my workspace",
|
|
461
|
+
});
|
|
462
|
+
|
|
463
|
+
const messages = await tevroc.agents.Support.listMessages(conversation.data.id);
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## Connectors, logs, custom integrations, and SSO
|
|
467
|
+
|
|
468
|
+
These features help you connect external services, track app events, call custom integrations, and handle SSO flows. They are especially useful for admin dashboards, automation, and customer-facing experiences.
|
|
469
|
+
|
|
470
|
+
```js
|
|
471
|
+
await tevroc.connectors.list();
|
|
472
|
+
await tevroc.connectors.get("slack");
|
|
473
|
+
await tevroc.connectors.connect("slack", { config: { teamId: "T123" } });
|
|
474
|
+
await tevroc.connectors.disconnect("slack");
|
|
475
|
+
await tevroc.connectors.status("slack");
|
|
476
|
+
|
|
477
|
+
await tevroc.connectors.user.list();
|
|
478
|
+
await tevroc.connectors.user.refresh("abc123");
|
|
479
|
+
|
|
480
|
+
await tevroc.logs.list({ limit: 20 });
|
|
481
|
+
await tevroc.logs.create({
|
|
482
|
+
level: "info",
|
|
483
|
+
message: "User opened dashboard",
|
|
484
|
+
context: { source: "web" },
|
|
485
|
+
});
|
|
486
|
+
|
|
487
|
+
await tevroc.customIntegrations.example.echo({ ok: true });
|
|
488
|
+
await tevroc.sso.accessToken({ code: "provider-code" });
|
|
489
|
+
await tevroc.sso.callback({ code: "provider-code" });
|
|
490
|
+
```
|
|
491
|
+
|
|
492
|
+
## Make raw requests
|
|
493
|
+
|
|
494
|
+
Use `request` when you need to call a worker route that does not yet have a dedicated helper. This gives you a flexible fallback for custom endpoints while still using the same authenticated client.
|
|
495
|
+
|
|
496
|
+
```js
|
|
497
|
+
const health = await tevroc.request("/health", { auth: false });
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
## Handle errors
|
|
501
|
+
|
|
502
|
+
Tevroc SDK throws structured errors that make it easier to respond to failed requests. You can inspect the status code and details to guide the user experience or retry logic.
|
|
503
|
+
|
|
504
|
+
```js
|
|
505
|
+
import { TevrocError } from "tevrocsdk";
|
|
506
|
+
|
|
507
|
+
try {
|
|
508
|
+
await tevroc.auth.me();
|
|
509
|
+
} catch (error) {
|
|
510
|
+
if (error instanceof TevrocError && error.status === 401) {
|
|
511
|
+
// Ask the user to sign in again.
|
|
512
|
+
}
|
|
513
|
+
}
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
|