@cutos/core 4.0.2 → 4.0.5
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 +33 -192
- package/dist/cutos.cjs.js +181 -272
- package/dist/cutos.esm.js +180 -272
- package/package.json +3 -2
- package/types/index.d.ts +78 -19
package/README.md
CHANGED
|
@@ -17,14 +17,6 @@ Hardware Device/Driver APIs remain available as the compatibility layer, but new
|
|
|
17
17
|
- `CoreAPI` is the main entry point for connecting to CUTOS runtime.
|
|
18
18
|
- It provides Promise-first methods for reading platform, configuration, box, device, volume, proxy, and shell information.
|
|
19
19
|
|
|
20
|
-
### Capability And Provider
|
|
21
|
-
|
|
22
|
-
- `cutos.capability(name)` creates a client for calling a CUTOS capability.
|
|
23
|
-
- `cutos.provider(name)` creates a Node-side provider implementation.
|
|
24
|
-
- `Capability.call()` maps to request-response IPC.
|
|
25
|
-
- `Provider.method()` registers a method handler.
|
|
26
|
-
- `Provider.emit()` publishes events to consumers.
|
|
27
|
-
|
|
28
20
|
### IPC
|
|
29
21
|
|
|
30
22
|
- IPC is a lower-level channel API for local and cross-device communication.
|
|
@@ -52,16 +44,14 @@ Hardware Device/Driver APIs remain available as the compatibility layer, but new
|
|
|
52
44
|
|
|
53
45
|
1. [Quick Start](#quick-start)
|
|
54
46
|
2. [Platform API](#platform-api)
|
|
55
|
-
3. [
|
|
56
|
-
4. [
|
|
57
|
-
5. [
|
|
58
|
-
6. [
|
|
59
|
-
7. [
|
|
60
|
-
8. [
|
|
61
|
-
9. [
|
|
62
|
-
10. [
|
|
63
|
-
11. [Mock Dev](#mock-dev)
|
|
64
|
-
12. [Documentation](#documentation)
|
|
47
|
+
3. [IPC API](#ipc-api)
|
|
48
|
+
4. [Database API](#database-api)
|
|
49
|
+
5. [Notification API](#notification-api)
|
|
50
|
+
6. [Logger API](#logger-api)
|
|
51
|
+
7. [Error Model](#error-model)
|
|
52
|
+
8. [Capability Contract](#capability-contract)
|
|
53
|
+
9. [Mock Dev](#mock-dev)
|
|
54
|
+
10. [Documentation](#documentation)
|
|
65
55
|
|
|
66
56
|
# Quick Start
|
|
67
57
|
|
|
@@ -78,8 +68,7 @@ import {
|
|
|
78
68
|
CoreAPI,
|
|
79
69
|
CoreClass,
|
|
80
70
|
CoreSimulator,
|
|
81
|
-
CutosError
|
|
82
|
-
cutos
|
|
71
|
+
CutosError
|
|
83
72
|
} from "@cutos/core"
|
|
84
73
|
```
|
|
85
74
|
|
|
@@ -95,47 +84,12 @@ During development, connect to a target CUTOS device:
|
|
|
95
84
|
await CoreAPI.init("192.168.1.100")
|
|
96
85
|
```
|
|
97
86
|
|
|
98
|
-
## LWA: Consume A Capability
|
|
99
|
-
|
|
100
|
-
```ts
|
|
101
|
-
await CoreAPI.init("localhost")
|
|
102
|
-
|
|
103
|
-
const hello = cutos.capability("hello-device")
|
|
104
|
-
|
|
105
|
-
const result = await hello.call<
|
|
106
|
-
{ message: string },
|
|
107
|
-
{ message: string }
|
|
108
|
-
>("echo", { message: "hello" })
|
|
109
|
-
|
|
110
|
-
console.log(result.message)
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
## Node: Implement A Provider
|
|
114
|
-
|
|
115
|
-
```ts
|
|
116
|
-
await CoreAPI.init("localhost")
|
|
117
|
-
|
|
118
|
-
const provider = cutos.provider("hello-device")
|
|
119
|
-
|
|
120
|
-
provider.method<
|
|
121
|
-
{ message: string },
|
|
122
|
-
{ message: string }
|
|
123
|
-
>("echo", async params => {
|
|
124
|
-
return { message: params.message }
|
|
125
|
-
})
|
|
126
|
-
|
|
127
|
-
provider.emit("statusChanged", {
|
|
128
|
-
status: "connected",
|
|
129
|
-
message: "hello-device ready"
|
|
130
|
-
})
|
|
131
|
-
```
|
|
132
|
-
|
|
133
87
|
## Mock Dev
|
|
134
88
|
|
|
135
89
|
Use Mock Dev when developing an LWA without a local CUTOS Node.
|
|
136
90
|
|
|
137
91
|
```ts
|
|
138
|
-
import { CoreAPI,
|
|
92
|
+
import { CoreAPI, CutosMock } from "@cutos/core"
|
|
139
93
|
|
|
140
94
|
CutosMock.install({
|
|
141
95
|
capabilities: {
|
|
@@ -148,9 +102,6 @@ CutosMock.install({
|
|
|
148
102
|
})
|
|
149
103
|
|
|
150
104
|
await CoreAPI.init("mock")
|
|
151
|
-
|
|
152
|
-
const hello = cutos.capability("hello-device")
|
|
153
|
-
const result = await hello.call("echo", { message: "hello" })
|
|
154
105
|
```
|
|
155
106
|
|
|
156
107
|
For simple UI development, set the CUTOS host to `mock` and keep application code unchanged:
|
|
@@ -277,138 +228,6 @@ const pwd = await CoreAPI.shell<string>("pwd")
|
|
|
277
228
|
|
|
278
229
|
Use this API carefully. It should not be exposed to untrusted LWA code without permissions.
|
|
279
230
|
|
|
280
|
-
# Capability API
|
|
281
|
-
|
|
282
|
-
## cutos.capability
|
|
283
|
-
|
|
284
|
-
Create a capability client.
|
|
285
|
-
|
|
286
|
-
```ts
|
|
287
|
-
const capability = cutos.capability("hello-device")
|
|
288
|
-
```
|
|
289
|
-
|
|
290
|
-
`CoreAPI.capability()` is equivalent.
|
|
291
|
-
|
|
292
|
-
```ts
|
|
293
|
-
const capability = CoreAPI.capability("hello-device")
|
|
294
|
-
```
|
|
295
|
-
|
|
296
|
-
## capability.call
|
|
297
|
-
|
|
298
|
-
Call a Provider method.
|
|
299
|
-
|
|
300
|
-
```ts
|
|
301
|
-
const result = await capability.call<
|
|
302
|
-
{ message: string },
|
|
303
|
-
{ message: string }
|
|
304
|
-
>("echo", { message: "hello" })
|
|
305
|
-
```
|
|
306
|
-
|
|
307
|
-
Set a per-call timeout:
|
|
308
|
-
|
|
309
|
-
```ts
|
|
310
|
-
await capability.call(
|
|
311
|
-
"connect",
|
|
312
|
-
{ name: "demo" },
|
|
313
|
-
{ timeout: 3000 }
|
|
314
|
-
)
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
## capability.on
|
|
318
|
-
|
|
319
|
-
Subscribe to Provider events.
|
|
320
|
-
|
|
321
|
-
```ts
|
|
322
|
-
const unsubscribe = capability.on<{
|
|
323
|
-
status: "idle" | "connected" | "error"
|
|
324
|
-
message?: string
|
|
325
|
-
}>("statusChanged", data => {
|
|
326
|
-
console.log(data.status)
|
|
327
|
-
})
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
## capability.off
|
|
331
|
-
|
|
332
|
-
Remove one listener or all listeners for an event.
|
|
333
|
-
|
|
334
|
-
```ts
|
|
335
|
-
capability.off("statusChanged")
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
## capability.dispose
|
|
339
|
-
|
|
340
|
-
Clear listeners and release the underlying subscription.
|
|
341
|
-
|
|
342
|
-
```ts
|
|
343
|
-
capability.dispose()
|
|
344
|
-
```
|
|
345
|
-
|
|
346
|
-
# Provider API
|
|
347
|
-
|
|
348
|
-
## cutos.provider
|
|
349
|
-
|
|
350
|
-
Create a Provider.
|
|
351
|
-
|
|
352
|
-
```ts
|
|
353
|
-
const provider = cutos.provider("hello-device")
|
|
354
|
-
```
|
|
355
|
-
|
|
356
|
-
`CoreAPI.provider()` is equivalent.
|
|
357
|
-
|
|
358
|
-
```ts
|
|
359
|
-
const provider = CoreAPI.provider("hello-device")
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
## provider.method
|
|
363
|
-
|
|
364
|
-
Register a method handler.
|
|
365
|
-
|
|
366
|
-
```ts
|
|
367
|
-
provider.method<
|
|
368
|
-
{ message: string },
|
|
369
|
-
{ message: string }
|
|
370
|
-
>("echo", async params => {
|
|
371
|
-
return { message: params.message }
|
|
372
|
-
})
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
Use `context` when raw command information is needed.
|
|
376
|
-
|
|
377
|
-
```ts
|
|
378
|
-
provider.method<{ name: string }, { connected: boolean }>(
|
|
379
|
-
"connect",
|
|
380
|
-
async (params, context) => {
|
|
381
|
-
console.log(context.command.cmd)
|
|
382
|
-
return { connected: true }
|
|
383
|
-
}
|
|
384
|
-
)
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
Throw `CutosError` for expected business errors.
|
|
388
|
-
|
|
389
|
-
```ts
|
|
390
|
-
throw new CutosError("HELLO_DEVICE_UNAVAILABLE", "The hello device is unavailable.")
|
|
391
|
-
```
|
|
392
|
-
|
|
393
|
-
## provider.emit
|
|
394
|
-
|
|
395
|
-
Emit an event.
|
|
396
|
-
|
|
397
|
-
```ts
|
|
398
|
-
provider.emit("statusChanged", {
|
|
399
|
-
status: "connected",
|
|
400
|
-
message: "hello-device ready"
|
|
401
|
-
})
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
## provider.dispose
|
|
405
|
-
|
|
406
|
-
Clear methods and release the underlying command listener.
|
|
407
|
-
|
|
408
|
-
```ts
|
|
409
|
-
provider.dispose()
|
|
410
|
-
```
|
|
411
|
-
|
|
412
231
|
# IPC API
|
|
413
232
|
|
|
414
233
|
IPC is a lower-level channel API. Prefer Capability/Provider for product APIs.
|
|
@@ -604,13 +423,35 @@ The third argument is optional and defaults to `LWA`.
|
|
|
604
423
|
logger.info("hello-provider", "started", "Provider")
|
|
605
424
|
```
|
|
606
425
|
|
|
426
|
+
# Device Provider Base
|
|
427
|
+
|
|
428
|
+
`DeviceProviderBase` automatically registers the standard `connect`, `disconnect`, and `readDeviceInfo` Capability methods. A concrete device Provider overrides those methods and registers only its device-specific extensions:
|
|
429
|
+
|
|
430
|
+
```ts
|
|
431
|
+
class PrinterProvider extends DeviceProviderBase {
|
|
432
|
+
connect(params) {
|
|
433
|
+
// Connect hardware.
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
disconnect() {
|
|
437
|
+
// Disconnect hardware.
|
|
438
|
+
}
|
|
439
|
+
|
|
440
|
+
readDeviceInfo() {
|
|
441
|
+
return { manufacturer: "CUTOS", model: "printer" }
|
|
442
|
+
}
|
|
443
|
+
}
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
The Base implementations throw `DEVICE_CONNECT_NOT_IMPLEMENTED`, `DEVICE_DISCONNECT_NOT_IMPLEMENTED`, and `DEVICE_INFO_NOT_IMPLEMENTED`. This makes an incomplete Provider fail explicitly instead of leaving a standard method unregistered.
|
|
447
|
+
|
|
607
448
|
# Error Model
|
|
608
449
|
|
|
609
450
|
CUTOS 4.0 normalizes SDK errors to `CutosError`.
|
|
610
451
|
|
|
611
452
|
```ts
|
|
612
453
|
try {
|
|
613
|
-
await
|
|
454
|
+
await CoreAPI.getPlatform()
|
|
614
455
|
} catch (error) {
|
|
615
456
|
if (error instanceof CutosError) {
|
|
616
457
|
console.log(error.code)
|