@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 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. [Capability API](#capability-api)
56
- 4. [Provider API](#provider-api)
57
- 5. [IPC API](#ipc-api)
58
- 6. [Database API](#database-api)
59
- 7. [Notification API](#notification-api)
60
- 8. [Logger API](#logger-api)
61
- 9. [Error Model](#error-model)
62
- 10. [Capability Contract](#capability-contract)
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, cutos, CutosMock } from "@cutos/core"
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 cutos.capability("hello-device").call("connect", { name: "demo" })
454
+ await CoreAPI.getPlatform()
614
455
  } catch (error) {
615
456
  if (error instanceof CutosError) {
616
457
  console.log(error.code)