@bikefinder/staff-sdk 0.0.0-stage → 0.8.2

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
@@ -1,3 +1,68 @@
1
- # Temporary Holding Version
1
+ # @bikefinder/staff-sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Typed staff HTTP and WebSocket client for the [API](../../README.md). Version 0.5
4
+ uses native oRPC contracts, Zod validation and async iterators. Customer apps use
5
+ [@bikefinder/sdk](../sdk/README.md). MCP invokes application workflows directly.
6
+
7
+ ```ts
8
+ import { createBikeFinderStaffClient, ORPCError } from "@bikefinder/staff-sdk";
9
+
10
+ const client = createBikeFinderStaffClient({
11
+ baseUrl: "https://api.prod.bikefinder.com",
12
+ accessToken: () => session.getAccessToken(),
13
+ onReconnect: () => restartActiveViews(),
14
+ });
15
+ const diagnostics = await client.api.gcp.diagnostics.get({ deviceId });
16
+ const controller = new AbortController();
17
+ for await (const reading of await client.api.aws.observations.events(
18
+ { serialNumber },
19
+ { signal: controller.signal },
20
+ )) {
21
+ if (reading.type === "battery.displayedLevel")
22
+ updateBattery(reading.value.percent);
23
+ }
24
+ controller.abort();
25
+ client.dispose();
26
+ ```
27
+
28
+ Ordinary procedures use authenticated HTTP under `/rpc/staff`. Event iterators
29
+ share one API Gateway WebSocket connection admitted using a fresh, single-use
30
+ HTTP ticket. Access tokens never appear in the WebSocket URL or frames. The
31
+ application owns Auth0 login and refresh; `accessToken` supplies current credentials.
32
+ HTTP requests omit cookies, disable caching and refuse redirects.
33
+
34
+ Each procedure accepts optional `{ signal }` as its second argument. Full
35
+ reconnects end existing subscriptions: explicitly resubscribe in `onReconnect`.
36
+ Events are not replayed, and writes are never automatically retried. Keep a
37
+ command's original `idempotencyKey` when retrying an uncertain submission.
38
+ `dispose()` cancels pending work and closes the shared socket.
39
+ Disposal is idempotent and emits one `closed` state; its intentional cancellation
40
+ does not call `onConnectionError`.
41
+
42
+ Overview and diagnostics are separate typed resources. Observations retain their
43
+ original `id`, measurement and receipt timestamps. Current selections use
44
+ `{ type, subject }`; paginated requests use `after` and responses `nextAfter`.
45
+ DTOs are explicit public projections with no storage-document envelope. Native
46
+ `ORPCError` failures preserve `code`, `status` and `data`.
47
+
48
+ Command and observation metadata ship with the SDK. Runtime validators are
49
+ exported from `@bikefinder/staff-sdk/schemas`; no schema bootstrap request is
50
+ required. Staff tools must still obtain the tracker's command catalog to check
51
+ its authoritative identity and availability before enabling writes.
52
+
53
+ Photo procedures return typed, short-lived download
54
+ references with storage URLs. Download file bytes over HTTP. WebSockets carry
55
+ metadata and events. Customer photo uploads use the customer SDK's staged-upload
56
+ helper; staff battery firmware uses its typed file procedure.
57
+
58
+ Version 0.8 accepts added response fields while validating known fields and
59
+ keeping request inputs strict. Tracker reading summaries use explicit availability
60
+ states, and presentation-data problems appear in `readIssues`. Declared error
61
+ data includes typed recovery instructions and references to existing operation
62
+ journals. Preserve the original operation identifier when recovering uncertain
63
+ writes. Realtime frames are limited to 32 KiB after encoding; use smaller
64
+ selections/pages or HTTP for larger resources.
65
+
66
+ Version 0.8.2 uses the canonical API contracts directly for HTTP and WebSocket
67
+ responses. Deploy the API's availability-state contract before updating Hub;
68
+ retired nullable response formats are rejected rather than translated.