@rnzeus/heimdall-sdk 0.0.0-stage → 0.2.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.
Files changed (223) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +210 -2
  3. package/dist/core/cloud/client.d.ts +44 -0
  4. package/dist/core/cloud/client.js +65 -0
  5. package/dist/core/cloud/index.d.ts +4 -0
  6. package/dist/core/cloud/index.js +4 -0
  7. package/dist/core/cloud/link-device.d.ts +14 -0
  8. package/dist/core/cloud/link-device.js +28 -0
  9. package/dist/core/cloud/state.d.ts +10 -0
  10. package/dist/core/cloud/state.js +21 -0
  11. package/dist/core/cloud/storage.d.ts +7 -0
  12. package/dist/core/cloud/storage.js +31 -0
  13. package/dist/core/connection/channel/generate.d.ts +10 -0
  14. package/dist/core/connection/channel/generate.js +22 -0
  15. package/dist/core/connection/channel/index.d.ts +4 -0
  16. package/dist/core/connection/channel/index.js +4 -0
  17. package/dist/core/connection/channel/parse.d.ts +9 -0
  18. package/dist/core/connection/channel/parse.js +27 -0
  19. package/dist/core/connection/channel/sanitize.d.ts +9 -0
  20. package/dist/core/connection/channel/sanitize.js +15 -0
  21. package/dist/core/connection/channel/types.d.ts +9 -0
  22. package/dist/core/connection/channel/types.js +1 -0
  23. package/dist/core/connection/index.d.ts +7 -0
  24. package/dist/core/connection/index.js +7 -0
  25. package/dist/core/connection/lifecycle/connect.d.ts +2 -0
  26. package/dist/core/connection/lifecycle/connect.js +46 -0
  27. package/dist/core/connection/lifecycle/destroy.d.ts +1 -0
  28. package/dist/core/connection/lifecycle/destroy.js +12 -0
  29. package/dist/core/connection/lifecycle/disconnect.d.ts +1 -0
  30. package/dist/core/connection/lifecycle/disconnect.js +10 -0
  31. package/dist/core/connection/lifecycle/early-events.d.ts +2 -0
  32. package/dist/core/connection/lifecycle/early-events.js +18 -0
  33. package/dist/core/connection/lifecycle/index.d.ts +5 -0
  34. package/dist/core/connection/lifecycle/index.js +5 -0
  35. package/dist/core/connection/lifecycle/keep-alive.d.ts +5 -0
  36. package/dist/core/connection/lifecycle/keep-alive.js +40 -0
  37. package/dist/core/connection/prompt/index.d.ts +1 -0
  38. package/dist/core/connection/prompt/index.js +1 -0
  39. package/dist/core/connection/prompt/prompt-state.d.ts +12 -0
  40. package/dist/core/connection/prompt/prompt-state.js +30 -0
  41. package/dist/core/connection/resolver/cloud.d.ts +4 -0
  42. package/dist/core/connection/resolver/cloud.js +29 -0
  43. package/dist/core/connection/resolver/index.d.ts +3 -0
  44. package/dist/core/connection/resolver/index.js +3 -0
  45. package/dist/core/connection/resolver/manual.d.ts +2 -0
  46. package/dist/core/connection/resolver/manual.js +3 -0
  47. package/dist/core/connection/resolver/types.d.ts +9 -0
  48. package/dist/core/connection/resolver/types.js +1 -0
  49. package/dist/core/connection/sdk-enabled.d.ts +3 -0
  50. package/dist/core/connection/sdk-enabled.js +10 -0
  51. package/dist/core/connection/session/clear-last-connection.d.ts +1 -0
  52. package/dist/core/connection/session/clear-last-connection.js +11 -0
  53. package/dist/core/connection/session/client-id.d.ts +3 -0
  54. package/dist/core/connection/session/client-id.js +25 -0
  55. package/dist/core/connection/session/constants.d.ts +14 -0
  56. package/dist/core/connection/session/constants.js +21 -0
  57. package/dist/core/connection/session/create-session.d.ts +3 -0
  58. package/dist/core/connection/session/create-session.js +21 -0
  59. package/dist/core/connection/session/index.d.ts +6 -0
  60. package/dist/core/connection/session/index.js +6 -0
  61. package/dist/core/connection/session/load-last-connection.d.ts +2 -0
  62. package/dist/core/connection/session/load-last-connection.js +16 -0
  63. package/dist/core/connection/session/state.d.ts +7 -0
  64. package/dist/core/connection/session/state.js +23 -0
  65. package/dist/core/connection/session/types.d.ts +12 -0
  66. package/dist/core/connection/session/types.js +1 -0
  67. package/dist/core/connection/socket/connect-socket.d.ts +3 -0
  68. package/dist/core/connection/socket/connect-socket.js +110 -0
  69. package/dist/core/connection/socket/constants.d.ts +4 -0
  70. package/dist/core/connection/socket/constants.js +4 -0
  71. package/dist/core/connection/socket/destroy-socket.d.ts +1 -0
  72. package/dist/core/connection/socket/destroy-socket.js +4 -0
  73. package/dist/core/connection/socket/disconnect-socket.d.ts +1 -0
  74. package/dist/core/connection/socket/disconnect-socket.js +26 -0
  75. package/dist/core/connection/socket/early-buffer.d.ts +7 -0
  76. package/dist/core/connection/socket/early-buffer.js +26 -0
  77. package/dist/core/connection/socket/flush-early-events.d.ts +1 -0
  78. package/dist/core/connection/socket/flush-early-events.js +18 -0
  79. package/dist/core/connection/socket/handle-socket-lost.d.ts +1 -0
  80. package/dist/core/connection/socket/handle-socket-lost.js +24 -0
  81. package/dist/core/connection/socket/index.d.ts +6 -0
  82. package/dist/core/connection/socket/index.js +6 -0
  83. package/dist/core/connection/socket/normalize-socket-error.d.ts +1 -0
  84. package/dist/core/connection/socket/normalize-socket-error.js +13 -0
  85. package/dist/core/connection/socket/send-event.d.ts +3 -0
  86. package/dist/core/connection/socket/send-event.js +45 -0
  87. package/dist/core/connection/socket/state.d.ts +8 -0
  88. package/dist/core/connection/socket/state.js +35 -0
  89. package/dist/core/console/index.d.ts +2 -0
  90. package/dist/core/console/index.js +2 -0
  91. package/dist/core/console/patch-console.d.ts +1 -0
  92. package/dist/core/console/patch-console.js +64 -0
  93. package/dist/core/console/restore-console.d.ts +1 -0
  94. package/dist/core/console/restore-console.js +28 -0
  95. package/dist/core/console/send-console-event.d.ts +8 -0
  96. package/dist/core/console/send-console-event.js +95 -0
  97. package/dist/core/console/state.d.ts +19 -0
  98. package/dist/core/console/state.js +25 -0
  99. package/dist/core/mmkv/index.d.ts +0 -0
  100. package/dist/core/mmkv/index.js +2 -0
  101. package/dist/core/network/get-interceptor.d.ts +11 -0
  102. package/dist/core/network/get-interceptor.js +19 -0
  103. package/dist/core/network/headers.d.ts +6 -0
  104. package/dist/core/network/headers.js +46 -0
  105. package/dist/core/network/index.d.ts +2 -0
  106. package/dist/core/network/index.js +2 -0
  107. package/dist/core/network/patch-xhr.d.ts +2 -0
  108. package/dist/core/network/patch-xhr.js +40 -0
  109. package/dist/core/network/restore-xhr.d.ts +1 -0
  110. package/dist/core/network/restore-xhr.js +40 -0
  111. package/dist/core/network/rn-blob.d.ts +1 -0
  112. package/dist/core/network/rn-blob.js +15 -0
  113. package/dist/core/network/should-skip.d.ts +2 -0
  114. package/dist/core/network/should-skip.js +30 -0
  115. package/dist/core/network/state.d.ts +5 -0
  116. package/dist/core/network/state.js +14 -0
  117. package/dist/core/network/xhr-callbacks.d.ts +12 -0
  118. package/dist/core/network/xhr-callbacks.js +169 -0
  119. package/dist/core/network/xhr-runtime-state.d.ts +4 -0
  120. package/dist/core/network/xhr-runtime-state.js +15 -0
  121. package/dist/core/network/xhr-types.d.ts +33 -0
  122. package/dist/core/network/xhr-types.js +1 -0
  123. package/dist/core/public.d.ts +2 -0
  124. package/dist/core/public.js +1 -0
  125. package/dist/core/react-query/index.d.ts +0 -0
  126. package/dist/core/react-query/index.js +2 -0
  127. package/dist/core/system/dev-server.d.ts +6 -0
  128. package/dist/core/system/dev-server.js +37 -0
  129. package/dist/core/system/device-info.d.ts +3 -0
  130. package/dist/core/system/device-info.js +46 -0
  131. package/dist/core/system/index.d.ts +2 -0
  132. package/dist/core/system/index.js +2 -0
  133. package/dist/core/websocket/index.d.ts +2 -0
  134. package/dist/core/websocket/index.js +2 -0
  135. package/dist/core/websocket/patch-websocket.d.ts +2 -0
  136. package/dist/core/websocket/patch-websocket.js +247 -0
  137. package/dist/core/websocket/restore-websocket.d.ts +1 -0
  138. package/dist/core/websocket/restore-websocket.js +16 -0
  139. package/dist/core/websocket/should-skip.d.ts +2 -0
  140. package/dist/core/websocket/should-skip.js +22 -0
  141. package/dist/core/websocket/state.d.ts +9 -0
  142. package/dist/core/websocket/state.js +21 -0
  143. package/dist/core/zustand/index.d.ts +1 -0
  144. package/dist/core/zustand/index.js +1 -0
  145. package/dist/index.d.ts +3 -0
  146. package/dist/index.js +3 -0
  147. package/dist/public/copy-button/component.d.ts +9 -0
  148. package/dist/public/copy-button/component.js +13 -0
  149. package/dist/public/copy-button/index.d.ts +1 -0
  150. package/dist/public/copy-button/index.js +1 -0
  151. package/dist/public/copy-button/styles.d.ts +64 -0
  152. package/dist/public/copy-button/styles.js +52 -0
  153. package/dist/public/index.d.ts +1 -0
  154. package/dist/public/index.js +1 -0
  155. package/dist/public/prompt/component.d.ts +7 -0
  156. package/dist/public/prompt/component.js +56 -0
  157. package/dist/public/prompt/index.d.ts +1 -0
  158. package/dist/public/prompt/index.js +1 -0
  159. package/dist/public/prompt/prompt-mode.d.ts +3 -0
  160. package/dist/public/prompt/prompt-mode.js +19 -0
  161. package/dist/public/prompt/styles.d.ts +23 -0
  162. package/dist/public/prompt/styles.js +23 -0
  163. package/dist/public/prompt/theme.d.ts +16 -0
  164. package/dist/public/prompt/theme.js +32 -0
  165. package/dist/public/prompt/types.d.ts +12 -0
  166. package/dist/public/prompt/types.js +1 -0
  167. package/dist/public/prompt/ui/action-button.d.ts +11 -0
  168. package/dist/public/prompt/ui/action-button.js +23 -0
  169. package/dist/public/prompt/ui/footer.d.ts +7 -0
  170. package/dist/public/prompt/ui/footer.js +13 -0
  171. package/dist/public/prompt/ui/header.d.ts +10 -0
  172. package/dist/public/prompt/ui/header.js +17 -0
  173. package/dist/public/prompt/ui/report-link.d.ts +8 -0
  174. package/dist/public/prompt/ui/report-link.js +19 -0
  175. package/dist/public/prompt/use-connect-awaiter.d.ts +11 -0
  176. package/dist/public/prompt/use-connect-awaiter.js +45 -0
  177. package/dist/public/prompt/use-prompt-animation.d.ts +17 -0
  178. package/dist/public/prompt/use-prompt-animation.js +53 -0
  179. package/dist/public/prompt/use-prompt-ui.d.ts +3 -0
  180. package/dist/public/prompt/use-prompt-ui.js +99 -0
  181. package/dist/public/prompt/use-prompt.d.ts +11 -0
  182. package/dist/public/prompt/use-prompt.js +43 -0
  183. package/dist/public/prompt/views/cloud-view.d.ts +13 -0
  184. package/dist/public/prompt/views/cloud-view.js +19 -0
  185. package/dist/public/prompt/views/connected-view.d.ts +14 -0
  186. package/dist/public/prompt/views/connected-view.js +9 -0
  187. package/dist/public/prompt/views/manual-view.d.ts +16 -0
  188. package/dist/public/prompt/views/manual-view.js +21 -0
  189. package/dist/public/prompt/views/styles.d.ts +44 -0
  190. package/dist/public/prompt/views/styles.js +23 -0
  191. package/dist/public/prompt/views/use-cloud-view.d.ts +15 -0
  192. package/dist/public/prompt/views/use-cloud-view.js +103 -0
  193. package/dist/public/public.d.ts +1 -0
  194. package/dist/public/public.js +1 -0
  195. package/dist/types/index.d.ts +2 -0
  196. package/dist/types/index.js +2 -0
  197. package/dist/types/options.d.ts +30 -0
  198. package/dist/types/options.js +1 -0
  199. package/dist/types/protocol.d.ts +1 -0
  200. package/dist/types/protocol.js +1 -0
  201. package/dist/types/public.d.ts +1 -0
  202. package/dist/types/public.js +1 -0
  203. package/dist/utils/body-snippet.d.ts +19 -0
  204. package/dist/utils/body-snippet.js +186 -0
  205. package/dist/utils/debug-log.d.ts +26 -0
  206. package/dist/utils/debug-log.js +44 -0
  207. package/dist/utils/generate-random-id.d.ts +1 -0
  208. package/dist/utils/generate-random-id.js +8 -0
  209. package/dist/utils/index.d.ts +5 -0
  210. package/dist/utils/index.js +5 -0
  211. package/dist/utils/parse-url.d.ts +5 -0
  212. package/dist/utils/parse-url.js +32 -0
  213. package/dist/utils/safe-serialize.d.ts +6 -0
  214. package/dist/utils/safe-serialize.js +77 -0
  215. package/dist/version.d.ts +1 -0
  216. package/dist/version.js +1 -0
  217. package/dist/zustand/index.d.ts +1 -0
  218. package/dist/zustand/index.js +1 -0
  219. package/dist/zustand/middleware.d.ts +18 -0
  220. package/dist/zustand/middleware.js +77 -0
  221. package/package.json +88 -4
  222. package/zustand/index.d.ts +1 -0
  223. package/zustand/index.js +1 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025-2026 Volodymyr Dudkevych
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,211 @@
1
- # Temporary Holding Version
1
+ # Heimdall 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
+ React Native client for **Heimdall** — a desktop debug inspector for dev and stage builds. The SDK streams what your app is doing to the Heimdall desktop app over your local network:
4
+
5
+ - **Network** — every XHR / `fetch` request with headers, bodies, status and timing
6
+ - **WebSocket** — open, messages in both directions, close
7
+ - **Zustand** — state snapshots per store, with the action that caused them
8
+ - **Console** — `console.*`, uncaught JS errors and unhandled promise rejections
9
+ - **App and device info** — version, build, environment, OS, model
10
+
11
+ ![Heimdall desktop app: network inspector](https://heimdall.rnzeus.dev/readme/network.png)
12
+
13
+ It is built for development and stage builds only and is off by default in production.
14
+
15
+ ## Requirements
16
+
17
+ | Package | Version | |
18
+ |---|---|---|
19
+ | `react-native` | `>=0.72` | |
20
+ | `react` | `>=18` | |
21
+ | `react-native-tcp-socket` | `>=6` | transport |
22
+ | `react-native-mmkv` | `>=3` | remembers the last connection |
23
+ | `zustand` | `>=3` | optional, only for the Zustand middleware |
24
+
25
+ `react-native-tcp-socket` and `react-native-mmkv` are native modules. With Expo you need a [development build](https://docs.expo.dev/develop/development-builds/introduction/) — Expo Go will not work.
26
+
27
+ ## Install
28
+
29
+ ```sh
30
+ yarn add @rnzeus/heimdall-sdk react-native-tcp-socket react-native-mmkv
31
+ cd ios && pod install
32
+ ```
33
+
34
+ You also need the Heimdall desktop app for macOS or Windows — [download it here](https://heimdall.rnzeus.dev/download).
35
+
36
+ ## Quick start
37
+
38
+ **1. Configure once, as early as possible** (for example in `index.js`):
39
+
40
+ ```ts
41
+ import { configureConnectPrompt } from "@rnzeus/heimdall-sdk";
42
+ import { Platform } from "react-native";
43
+
44
+ configureConnectPrompt({
45
+ host: Platform.select({ android: "10.0.2.2", default: "127.0.0.1" }),
46
+ port: 35678,
47
+ appId: "com.example.app",
48
+ captureEarlyEvents: true,
49
+ keepAlive: true,
50
+ });
51
+ ```
52
+
53
+ **2. Mount the connect prompt** at the root of your app:
54
+
55
+ ```tsx
56
+ import { HeimdallConnectPrompt } from "@rnzeus/heimdall-sdk";
57
+
58
+ export function App() {
59
+ return (
60
+ <>
61
+ <RootNavigator />
62
+ <HeimdallConnectPrompt />
63
+ </>
64
+ );
65
+ }
66
+ ```
67
+
68
+ **3. Open it** from anywhere — a dev menu item, a hidden gesture, a button:
69
+
70
+ ```ts
71
+ import { showSDKConnectPrompt } from "@rnzeus/heimdall-sdk";
72
+
73
+ showSDKConnectPrompt();
74
+ ```
75
+
76
+ **4. Connect.** Start the server in Heimdall, copy the channel it shows (`heimdall://…`) into the prompt and connect.
77
+
78
+ Host to use:
79
+
80
+ | Where the app runs | Host |
81
+ |---|---|
82
+ | iOS simulator | `127.0.0.1` |
83
+ | Android emulator | `10.0.2.2` |
84
+ | Real device | LAN IP of the machine running Heimdall |
85
+
86
+ On a real iOS device the first connection triggers the Local Network permission dialog, so `NSLocalNetworkUsageDescription` must be set in `Info.plist`.
87
+
88
+ ## Zustand
89
+
90
+ Wrap a store creator with the middleware and give the store a name:
91
+
92
+ ```ts
93
+ import { create } from "zustand";
94
+ import { heimdallZustand } from "@rnzeus/heimdall-sdk/zustand";
95
+
96
+ export const useCart = create(
97
+ heimdallZustand("cart", (set) => ({
98
+ items: [],
99
+ add: (item) => set((state) => ({ items: [...state.items, item] })),
100
+ }))
101
+ );
102
+ ```
103
+
104
+ Heimdall receives a snapshot on every change, tagged with the name of the store action that triggered it, and highlights what changed. When the SDK is disabled the middleware returns your creator untouched.
105
+
106
+ ![Zustand inspector: changed fields highlighted](https://heimdall.rnzeus.dev/readme/zustand.png)
107
+
108
+ ## Recorded sessions
109
+
110
+ Heimdall can record everything it receives and save it as a single `.edda` file. A tester attaches the file to a bug report; a developer opens it and sees the network, WebSocket, state and console events on one timeline, exactly as they happened.
111
+
112
+ ![A recorded session opened on the timeline](https://heimdall.rnzeus.dev/readme/session.png)
113
+
114
+ Tokens, cookies and passwords can be masked on export, so the file is safe to pass around.
115
+
116
+ ![Export dialog with masking of sensitive data](https://heimdall.rnzeus.dev/readme/export.png)
117
+
118
+ Recording and playback live in the desktop app — nothing extra is needed in your code.
119
+
120
+ ## Without the prompt
121
+
122
+ ```ts
123
+ import { connect, disconnect } from "@rnzeus/heimdall-sdk";
124
+
125
+ connect({ host: "127.0.0.1", port: 35678, channel: "heimdall://my-app-x7k2p9" });
126
+
127
+ disconnect();
128
+ ```
129
+
130
+ ## Options
131
+
132
+ `configureConnectPrompt` takes everything below except `channel`; `connect` takes all of it.
133
+
134
+ | Option | Type | Default | |
135
+ |---|---|---|---|
136
+ | `host` | `string` | — | where Heimdall is running |
137
+ | `port` | `number` | — | Heimdall listens on `35678` by default |
138
+ | `channel` | `string` | — | `heimdall://…` channel shown in Heimdall |
139
+ | `enabled` | `boolean` | `__DEV__` | set `true` explicitly to use the SDK in a stage build |
140
+ | `platform` | `"ios" \| "android" \| "macos" \| "windows" \| "other"` | — | |
141
+ | `deviceName` | `string` | — | name shown in Heimdall |
142
+ | `appId` | `string` | — | bundle id or any identifier |
143
+ | `app` | `{ version?, build?, environment? }` | — | app details shown in Heimdall |
144
+ | `allowedHosts` | `(string \| RegExp)[]` | — | capture only these hosts |
145
+ | `ignoreUrls` | `(string \| RegExp)[]` | — | skip by full URL or path |
146
+ | `captureEarlyEvents` | `boolean` | `false` | buffer events that happen before the connection is up |
147
+ | `keepAlive` | `boolean` | `false` | reconnect to the last channel on app start |
148
+ | `captureConsole` | `boolean` | `true` | console, uncaught errors, unhandled rejections |
149
+ | `cloud` | `{ url: string }` | — | optional, see [Connecting without typing an address](#connecting-without-typing-an-address) |
150
+
151
+ `<HeimdallConnectPrompt />` accepts `onCopyToClipboard?: (text: string) => void` to plug in your clipboard library.
152
+
153
+ ## Connecting without typing an address
154
+
155
+ By default you copy the host and the channel into the prompt by hand. Heimdall Cloud removes that step for testers: a device is linked to an account once, and after that the app finds the desktop on its own.
156
+
157
+ ```ts
158
+ configureConnectPrompt({
159
+ // ...
160
+ cloud: { url: "https://heimdall.rnzeus.dev" },
161
+ });
162
+ ```
163
+
164
+ With `cloud` set, the prompt gets a second mode:
165
+
166
+ 1. **Find me** opens a browser page where the tester signs in and picks (or creates) a device. This is done once per device.
167
+ 2. In the desktop app the tester signs in to the same account and starts the server for that device.
168
+ 3. **Connect** in the prompt asks the cloud where that desktop is and connects to it directly.
169
+
170
+ The cloud only stores accounts, devices and the current address of the desktop. Captured traffic never goes through it. Without `cloud` the prompt works in manual mode only.
171
+
172
+ ## Production safety
173
+
174
+ - `enabled` defaults to `__DEV__`. In a release build the SDK does nothing unless you pass `enabled: true`.
175
+ - When disabled there are no patches, no sockets and no subscriptions.
176
+ - Patches are transparent: original behaviour and return values are preserved, and SDK errors never reach your app.
177
+ - Payloads are capped: JSON bodies at 500 KB, text at 200 KB, everything else at 50 KB, console messages at 8 KB.
178
+
179
+ ## Your data
180
+
181
+ - Events go **directly** from the app to the Heimdall desktop app over TCP on your network. Nothing is sent to us or to any third party.
182
+ - Headers and bodies are sent **as they are**, including auth tokens. Use the SDK in dev and stage builds, and narrow the capture with `allowedHosts` / `ignoreUrls` where needed.
183
+ - `cloud` is optional and never sees captured traffic — see [Connecting without typing an address](#connecting-without-typing-an-address).
184
+
185
+ ## Testing with Jest
186
+
187
+ The SDK ships as ES modules, and Jest does not transform `node_modules` by default. Add the package to `transformIgnorePatterns`:
188
+
189
+ ```js
190
+ // jest.config.js
191
+ module.exports = {
192
+ preset: "react-native",
193
+ transformIgnorePatterns: [
194
+ "node_modules/(?!((jest-)?react-native|@react-native(-community)?|@rnzeus/heimdall-sdk)/)",
195
+ ],
196
+ };
197
+ ```
198
+
199
+ `react-native-tcp-socket` is a native module, so mock it in your Jest setup file:
200
+
201
+ ```js
202
+ jest.mock("react-native-tcp-socket", () => ({ createConnection: jest.fn() }));
203
+ ```
204
+
205
+ ## Example app
206
+
207
+ [`example/`](./example) is a minimal React Native app with ready-made network, WebSocket, Zustand and console scenarios.
208
+
209
+ ## License
210
+
211
+ MIT
@@ -0,0 +1,44 @@
1
+ export declare class CloudUnauthorizedError extends Error {
2
+ constructor();
3
+ }
4
+ export type CloudClaim = {
5
+ code: string;
6
+ url: string;
7
+ expiresAt: number;
8
+ };
9
+ export type CloudClaimStatus = {
10
+ status: "pending";
11
+ } | {
12
+ status: "expired";
13
+ } | {
14
+ status: "approved";
15
+ token: string;
16
+ device: {
17
+ id: string;
18
+ name: string;
19
+ };
20
+ };
21
+ export type CloudConnection = {
22
+ host: string;
23
+ addresses: string[];
24
+ port: number;
25
+ channel: string;
26
+ hostName: string;
27
+ };
28
+ export declare function createClaim({ baseUrl, appId, platform, }: {
29
+ baseUrl: string;
30
+ appId?: string;
31
+ platform?: string;
32
+ }): Promise<CloudClaim>;
33
+ export declare function pollClaim({ baseUrl, code, }: {
34
+ baseUrl: string;
35
+ code: string;
36
+ }): Promise<CloudClaimStatus>;
37
+ export declare function fetchConnection({ baseUrl, token, }: {
38
+ baseUrl: string;
39
+ token: string;
40
+ }): Promise<CloudConnection | null>;
41
+ export declare function unlinkDevice({ baseUrl, token, }: {
42
+ baseUrl: string;
43
+ token: string;
44
+ }): Promise<void>;
@@ -0,0 +1,65 @@
1
+ const REQUEST_TIMEOUT_MS = 10000;
2
+ export class CloudUnauthorizedError extends Error {
3
+ constructor() {
4
+ super("Device is not linked anymore");
5
+ }
6
+ }
7
+ async function request({ baseUrl, path, method = "GET", token, body, }) {
8
+ const controller = new AbortController();
9
+ const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
10
+ try {
11
+ const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1${path}`, {
12
+ method,
13
+ headers: {
14
+ ...(body ? { "Content-Type": "application/json" } : {}),
15
+ ...(token ? { Authorization: `Bearer ${token}` } : {}),
16
+ },
17
+ body: body ? JSON.stringify(body) : undefined,
18
+ signal: controller.signal,
19
+ });
20
+ const text = await response.text();
21
+ return { status: response.status, data: text ? JSON.parse(text) : null };
22
+ }
23
+ finally {
24
+ clearTimeout(timeout);
25
+ }
26
+ }
27
+ export async function createClaim({ baseUrl, appId, platform, }) {
28
+ const { status, data } = await request({
29
+ baseUrl,
30
+ path: "/claims",
31
+ method: "POST",
32
+ body: { appId, platform },
33
+ });
34
+ if (status !== 201)
35
+ throw new Error(`Cloud error ${status}`);
36
+ return data;
37
+ }
38
+ export async function pollClaim({ baseUrl, code, }) {
39
+ const { status, data } = await request({
40
+ baseUrl,
41
+ path: `/claims/${encodeURIComponent(code)}`,
42
+ });
43
+ if (status === 410)
44
+ return { status: "expired" };
45
+ if (status !== 200)
46
+ throw new Error(`Cloud error ${status}`);
47
+ return data;
48
+ }
49
+ export async function fetchConnection({ baseUrl, token, }) {
50
+ const { status, data } = await request({
51
+ baseUrl,
52
+ path: "/device/connection",
53
+ token,
54
+ });
55
+ if (status === 204)
56
+ return null;
57
+ if (status === 401)
58
+ throw new CloudUnauthorizedError();
59
+ if (status !== 200)
60
+ throw new Error(`Cloud error ${status}`);
61
+ return data;
62
+ }
63
+ export async function unlinkDevice({ baseUrl, token, }) {
64
+ await request({ baseUrl, path: "/device", method: "DELETE", token });
65
+ }
@@ -0,0 +1,4 @@
1
+ export * from "./client";
2
+ export * from "./storage";
3
+ export * from "./link-device";
4
+ export * from "./state";
@@ -0,0 +1,4 @@
1
+ export * from "./client.js";
2
+ export * from "./storage.js";
3
+ export * from "./link-device.js";
4
+ export * from "./state.js";
@@ -0,0 +1,14 @@
1
+ export type LinkDeviceResult = {
2
+ status: "linked";
3
+ deviceName: string;
4
+ } | {
5
+ status: "expired";
6
+ } | {
7
+ status: "cancelled";
8
+ };
9
+ export declare function linkDevice({ baseUrl, appId, platform, isCancelled, }: {
10
+ baseUrl: string;
11
+ appId?: string;
12
+ platform?: string;
13
+ isCancelled: () => boolean;
14
+ }): Promise<LinkDeviceResult>;
@@ -0,0 +1,28 @@
1
+ import { Linking } from "react-native";
2
+ import { createClaim, pollClaim } from "./client.js";
3
+ import { saveCloudDevice } from "./storage.js";
4
+ const POLL_INTERVAL_MS = 2000;
5
+ const delay = (ms) => new Promise((resolve) => setTimeout(() => resolve(), ms));
6
+ export async function linkDevice({ baseUrl, appId, platform, isCancelled, }) {
7
+ const claim = await createClaim({ baseUrl, appId, platform });
8
+ await Linking.openURL(claim.url);
9
+ while (Date.now() < claim.expiresAt) {
10
+ await delay(POLL_INTERVAL_MS);
11
+ if (isCancelled())
12
+ return { status: "cancelled" };
13
+ let result;
14
+ try {
15
+ result = await pollClaim({ baseUrl, code: claim.code });
16
+ }
17
+ catch {
18
+ continue;
19
+ }
20
+ if (result.status === "expired")
21
+ return { status: "expired" };
22
+ if (result.status === "approved") {
23
+ saveCloudDevice({ token: result.token, name: result.device.name });
24
+ return { status: "linked", deviceName: result.device.name };
25
+ }
26
+ }
27
+ return { status: "expired" };
28
+ }
@@ -0,0 +1,10 @@
1
+ type CloudTarget = {
2
+ channel: string;
3
+ hostName?: string;
4
+ };
5
+ export declare function setLastCloudTarget(target: CloudTarget | null): void;
6
+ export declare function getCloudHostName(channel: string | null): string | null;
7
+ /** SDK's own cloud requests are never reported to Heimdall. */
8
+ export declare function registerCloudUrl(url: string | undefined): void;
9
+ export declare function isCloudHost(host: string): boolean;
10
+ export {};
@@ -0,0 +1,21 @@
1
+ import { parseUrl } from "../../utils/index.js";
2
+ let lastCloudTarget = null;
3
+ export function setLastCloudTarget(target) {
4
+ lastCloudTarget = target;
5
+ }
6
+ export function getCloudHostName(channel) {
7
+ var _a;
8
+ if (!channel || (lastCloudTarget === null || lastCloudTarget === void 0 ? void 0 : lastCloudTarget.channel) !== channel)
9
+ return null;
10
+ return (_a = lastCloudTarget.hostName) !== null && _a !== void 0 ? _a : null;
11
+ }
12
+ const cloudHosts = new Set();
13
+ /** SDK's own cloud requests are never reported to Heimdall. */
14
+ export function registerCloudUrl(url) {
15
+ const host = url ? parseUrl(url).host : "";
16
+ if (host)
17
+ cloudHosts.add(host);
18
+ }
19
+ export function isCloudHost(host) {
20
+ return cloudHosts.has(host);
21
+ }
@@ -0,0 +1,7 @@
1
+ export type CloudDevice = {
2
+ token: string;
3
+ name: string;
4
+ };
5
+ export declare function loadCloudDevice(): CloudDevice | null;
6
+ export declare function saveCloudDevice({ token, name }: CloudDevice): void;
7
+ export declare function clearCloudDevice(): void;
@@ -0,0 +1,31 @@
1
+ import { SESSION_STORAGE } from "../connection/session/constants.js";
2
+ const KEY_TOKEN = "cloudDeviceToken";
3
+ const KEY_DEVICE_NAME = "cloudDeviceName";
4
+ export function loadCloudDevice() {
5
+ try {
6
+ const token = SESSION_STORAGE.getString(KEY_TOKEN);
7
+ const name = SESSION_STORAGE.getString(KEY_DEVICE_NAME);
8
+ return token ? { token, name: name !== null && name !== void 0 ? name : "This device" } : null;
9
+ }
10
+ catch {
11
+ return null;
12
+ }
13
+ }
14
+ export function saveCloudDevice({ token, name }) {
15
+ try {
16
+ SESSION_STORAGE.set(KEY_TOKEN, token);
17
+ SESSION_STORAGE.set(KEY_DEVICE_NAME, name);
18
+ }
19
+ catch {
20
+ // ignore
21
+ }
22
+ }
23
+ export function clearCloudDevice() {
24
+ try {
25
+ SESSION_STORAGE.delete(KEY_TOKEN);
26
+ SESSION_STORAGE.delete(KEY_DEVICE_NAME);
27
+ }
28
+ catch {
29
+ // ignore
30
+ }
31
+ }
@@ -0,0 +1,10 @@
1
+ import { type Channel } from "./types";
2
+ /**
3
+ * Generate a random short ID (default length = 6).
4
+ */
5
+ export declare function generateShortId(length?: number): string;
6
+ /**
7
+ * Generate a full Channel identifier:
8
+ * heimdall://<slug>-<shortId>
9
+ */
10
+ export declare function generateChannelId(rawSlug?: string): Channel;
@@ -0,0 +1,22 @@
1
+ import { CHANNEL_SCHEME } from "./types.js";
2
+ import { sanitizeChannelSlug } from "./sanitize.js";
3
+ /**
4
+ * Generate a random short ID (default length = 6).
5
+ */
6
+ export function generateShortId(length = 6) {
7
+ const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
8
+ let out = "";
9
+ for (let i = 0; i < length; i++) {
10
+ out += chars[Math.floor(Math.random() * chars.length)];
11
+ }
12
+ return out;
13
+ }
14
+ /**
15
+ * Generate a full Channel identifier:
16
+ * heimdall://<slug>-<shortId>
17
+ */
18
+ export function generateChannelId(rawSlug) {
19
+ const slug = sanitizeChannelSlug(rawSlug !== null && rawSlug !== void 0 ? rawSlug : "session");
20
+ const shortId = generateShortId();
21
+ return `${CHANNEL_SCHEME}${slug}-${shortId}`;
22
+ }
@@ -0,0 +1,4 @@
1
+ export * from "./generate";
2
+ export * from "./sanitize";
3
+ export * from "./parse";
4
+ export * from "./types";
@@ -0,0 +1,4 @@
1
+ export * from "./generate.js";
2
+ export * from "./sanitize.js";
3
+ export * from "./parse.js";
4
+ export * from "./types.js";
@@ -0,0 +1,9 @@
1
+ import { type Channel, type ChannelParts } from "./types";
2
+ /**
3
+ * Check if value looks like a Heimdall Channel
4
+ */
5
+ export declare function isChannel(value: string): value is Channel;
6
+ /**
7
+ * Parse Heimdall Channel into {scheme, slug, shortId}
8
+ */
9
+ export declare function parseChannel(value: string): ChannelParts | null;
@@ -0,0 +1,27 @@
1
+ import { CHANNEL_SCHEME } from "./types.js";
2
+ /**
3
+ * Check if value looks like a Heimdall Channel
4
+ */
5
+ export function isChannel(value) {
6
+ return value.startsWith(CHANNEL_SCHEME);
7
+ }
8
+ /**
9
+ * Parse Heimdall Channel into {scheme, slug, shortId}
10
+ */
11
+ export function parseChannel(value) {
12
+ if (!isChannel(value))
13
+ return null;
14
+ const raw = value.slice(CHANNEL_SCHEME.length);
15
+ const lastDash = raw.lastIndexOf("-");
16
+ if (lastDash <= 0)
17
+ return null;
18
+ const slug = raw.slice(0, lastDash);
19
+ const shortId = raw.slice(lastDash + 1);
20
+ if (!slug || !shortId)
21
+ return null;
22
+ return {
23
+ scheme: CHANNEL_SCHEME,
24
+ slug,
25
+ shortId,
26
+ };
27
+ }
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Normalize slug for channel:
3
+ * - lowercase
4
+ * - remove invalid chars
5
+ * - collapse "-"
6
+ * - trim edges
7
+ * - max length 32
8
+ */
9
+ export declare function sanitizeChannelSlug(input: string): string;
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Normalize slug for channel:
3
+ * - lowercase
4
+ * - remove invalid chars
5
+ * - collapse "-"
6
+ * - trim edges
7
+ * - max length 32
8
+ */
9
+ export function sanitizeChannelSlug(input) {
10
+ const lower = input.trim().toLowerCase();
11
+ const replaced = lower.replace(/[^a-z0-9-]+/g, "-");
12
+ const collapsed = replaced.replace(/-+/g, "-");
13
+ const trimmed = collapsed.replace(/^-+|-+$/g, "");
14
+ return trimmed.slice(0, 32) || "session";
15
+ }
@@ -0,0 +1,9 @@
1
+ export declare const CHANNEL_SCHEME = "heimdall://";
2
+ export type Channel = string & {
3
+ readonly __brand: "HeimdallChannel";
4
+ };
5
+ export type ChannelParts = {
6
+ scheme: "heimdall://";
7
+ slug: string;
8
+ shortId: string;
9
+ };
@@ -0,0 +1 @@
1
+ export const CHANNEL_SCHEME = "heimdall://";
@@ -0,0 +1,7 @@
1
+ export * from "./sdk-enabled";
2
+ export * from "./socket";
3
+ export * from "./lifecycle";
4
+ export * from "./session";
5
+ export * from "./prompt";
6
+ export * from "./channel";
7
+ export * from "./resolver";
@@ -0,0 +1,7 @@
1
+ export * from "./sdk-enabled.js";
2
+ export * from "./socket/index.js";
3
+ export * from "./lifecycle/index.js";
4
+ export * from "./session/index.js";
5
+ export * from "./prompt/index.js";
6
+ export * from "./channel/index.js";
7
+ export * from "./resolver/index.js";
@@ -0,0 +1,2 @@
1
+ import type { HeimdallConnectOptions } from "../../../types";
2
+ export declare function connect(options: HeimdallConnectOptions): void;
@@ -0,0 +1,46 @@
1
+ import { patchXHR } from "../../network/index.js";
2
+ import { patchWebSocket } from "../../websocket/index.js";
3
+ import { patchConsole } from "../../console/index.js";
4
+ import { resolveEnabled, setSdkEnabled } from "../sdk-enabled.js";
5
+ import { createSession, setCurrentSession } from "../session/index.js";
6
+ import { connectSocket } from "../socket/index.js";
7
+ import { registerCloudUrl } from "../../cloud/state.js";
8
+ export function connect(options) {
9
+ var _a;
10
+ const enabled = resolveEnabled(options.enabled);
11
+ if (!enabled) {
12
+ setSdkEnabled(false);
13
+ return;
14
+ }
15
+ setSdkEnabled(true);
16
+ registerCloudUrl((_a = options.cloud) === null || _a === void 0 ? void 0 : _a.url);
17
+ const session = createSession(options);
18
+ setCurrentSession(session);
19
+ try {
20
+ connectSocket(session);
21
+ }
22
+ catch {
23
+ setCurrentSession(null);
24
+ setSdkEnabled(false);
25
+ return;
26
+ }
27
+ const patched = patchXHR({
28
+ allowedHosts: options.allowedHosts,
29
+ ignoreUrls: options.ignoreUrls,
30
+ });
31
+ if (!patched) {
32
+ if (__DEV__) {
33
+ console.warn("[Heimdall] XHRInterceptor not available — network logs disabled.");
34
+ }
35
+ else {
36
+ // ignore, feature-specific logging
37
+ }
38
+ }
39
+ patchWebSocket({
40
+ allowedHosts: options.allowedHosts,
41
+ ignoreUrls: options.ignoreUrls,
42
+ });
43
+ if (options.captureConsole !== false) {
44
+ patchConsole();
45
+ }
46
+ }