{"_id":"@botiverse/hands-electron","name":"@botiverse/hands-electron","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@botiverse/hands-electron","version":"0.2.0","description":"Hands crash reporting for Electron apps — main + renderer, Crashpad minidumps auto-uploaded and symbolicated server-side.","license":"MIT","type":"module","exports":{"./main":{"types":"./dist/main.d.ts","import":"./dist/main.js"},"./renderer":{"types":"./dist/renderer.d.ts","import":"./dist/renderer.js"},"./preload":{"types":"./dist/preload.d.ts","import":"./dist/preload.js"}},"scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"peerDependencies":{"electron":">=22"},"devDependencies":{"typescript":"^5.9.3"},"publishConfig":{"access":"public"},"gitHead":"a8fa88dedc385a527d9795aaea4fd2e7b3ed9cfe","_id":"@botiverse/hands-electron@0.2.0","_nodeVersion":"24.16.0","_npmVersion":"9.6.6","dist":{"integrity":"sha512-jUJ+slk15x5JgTh6NTogYRl1M22S3f/PAsd7g8waUCfQie0mXHw2nQuvpZu3KvodYbYeTM5k+xehQTa9uI/vpw==","shasum":"84f2c6bf54851a10d6b4a5725a75a55dbb20a504","tarball":"https://registry.npmjs.org/@botiverse/hands-electron/-/hands-electron-0.2.0.tgz","fileCount":10,"unpackedSize":19537,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH4/4rP4JbROr7+c+aSLCO2qgeYZ9EITZ8qM0t6dRIYkAiAXPXCOW9nnsVuLiwwwfkOVvTnawF4GkER8TxzpLONCMA=="}]},"_npmUser":{"name":"lengthmin","email":"lengthmin@gmail.com"},"directories":{},"maintainers":[{"name":"tennyzhuang","email":"zty0826@gmail.com"},{"name":"richardchien","email":"stdrc@outlook.com"},{"name":"yezizp","email":"yezizp2012@gmail.com"},{"name":"lengthmin","email":"lengthmin@gmail.com"},{"name":"xxchan","email":"xxchan22f@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hands-electron_0.2.0_1783596360989_0.8237052131861029"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T11:26:00.742Z","0.2.0":"2026-07-09T11:26:01.147Z","modified":"2026-07-09T11:26:01.482Z"},"maintainers":[{"name":"tennyzhuang","email":"zty0826@gmail.com"},{"name":"richardchien","email":"stdrc@outlook.com"},{"name":"yezizp","email":"yezizp2012@gmail.com"},{"name":"lengthmin","email":"lengthmin@gmail.com"},{"name":"xxchan","email":"xxchan22f@gmail.com"}],"description":"Hands crash reporting for Electron apps — main + renderer, Crashpad minidumps auto-uploaded and symbolicated server-side.","license":"MIT","readme":"# @botiverse/hands-electron\n\nCrash reporting for Electron apps, backed by [Hands](https://quiver.oranix.io).\n\nElectron's built-in [Crashpad](https://www.electronjs.org/docs/latest/api/crash-reporter)\ncaptures native minidumps for **both the main and renderer processes** and\nuploads them straight to Hands, where they're stored as crash tickets and\nsymbolicated server-side against your uploaded Breakpad symbols. This SDK wires\nthat up, adds renderer/child-process crash listeners, and manages a crash scope\n(user / tags / extra / breadcrumbs) that rides along on the next dump.\n\nThe SDK has two entry points, like `@sentry/electron`: one for the **main**\nprocess and one for the **renderer**.\n\n## Install\n\n```bash\nnpm install @botiverse/hands-electron\n```\n\n`electron` is a peer dependency (provided by your app).\n\n## Main process\n\nCall `init()` once, before the app is ready:\n\n```ts\nimport { app } from \"electron\";\nimport * as Hands from \"@botiverse/hands-electron/main\";\n\nHands.init({\n  appSlug: \"my-desktop-app\",     // your Hands app slug\n  clientKey: \"qk_live_...\",      // public client key (safe to ship)\n  release: app.getVersion(),     // version_name (defaults to app.getVersion())\n  versionCode: 1020300,          // Hands version_code → picks the symbol set\n  environment: \"stable\",         // channel\n  extra: { deployment: \"ga\" },   // static annotations on every crash\n  onCrash: (info) => {\n    // renderer / child-process termination (incl. oom / killed, which produce\n    // no minidump) — log, show a dialog, etc.\n    console.warn(\"process gone:\", info.processType, info.reason);\n  },\n});\n\n// Attach context that rides along on the next crash:\nHands.setUser({ id: \"u_123\", email: \"a@b.com\" });\nHands.setTag(\"feature\", \"editor\");\nHands.setExtra(\"open_docs\", 3);\nHands.addBreadcrumb({ message: \"opened project\", category: \"ui\" });\n```\n\n`init()` also sends a throttled launch/install metrics ping to Hands using a\nrandom per-install device id stored under Electron `userData`. This powers\nactive-device and version-distribution analytics; it is not a true online\nheartbeat. Use `Hands.reportDevice(options)` if you need to force a metrics\nping outside the normal 24h throttle.\n\n## Renderer process\n\nRenderer crashes are captured by the main-process Crashpad automatically — the\nrenderer entry only manages scope and forwards it to main over IPC:\n\n```ts\nimport * as Hands from \"@botiverse/hands-electron/renderer\";\n\nHands.setTag(\"route\", location.pathname);\nHands.addBreadcrumb({ message: \"clicked export\" });\n```\n\nFor sandboxed renderers (`contextIsolation: true`), expose the API from your\npreload script instead:\n\n```ts\n// preload.ts\nimport { exposeHands } from \"@botiverse/hands-electron/preload\";\nexposeHands(); // → window.hands.setTag(...), window.hands.addBreadcrumb(...)\n```\n\n## Symbols (server-side symbolication)\n\nMinidumps only become readable stacks when Hands has your app's Breakpad\nsymbols for that `version_code`. In CI, generate them with\n[`dump_syms`](https://github.com/mozilla/dump_syms) and upload alongside the\nrelease:\n\n```bash\n# produce .sym files for your app + Electron framework binaries\ndump_syms path/to/MyApp > syms/MyApp.sym\n# … repeat per binary, then zip them (flat is fine — Hands reads each\n#    file's MODULE header to place it correctly) …\nzip -r symbols.zip syms/\n\nhands builds publish-electron my-desktop-app \\\n  --version-name 1.2.3 --version-code 1020300 \\\n  --installer dist/MyApp-1.2.3.exe \\\n  --symbols symbols.zip\n```\n\nOnce symbols are present, each crash ticket gets a symbolicated stack posted as\na comment. Without symbols, Hands still records the crash with module+offset\nframes.\n\n## What gets sent\n\nEvery minidump carries a Sentry-electron-style annotation set the server folds\ninto the ticket: `product_type=electron`, `version`, `version_code`,\n`environment`/`channel`, `platform`, `arch`, `process_type`,\n`electron_version`, `chrome_version`, plus any `extra` and the current\nuser/tags/breadcrumbs.\n","readmeFilename":"README.md","_rev":"1-cedbd198097976f50711e16ee0b27151"}