{"_id":"@andynursa/checkpoint-capacitor","name":"@andynursa/checkpoint-capacitor","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@andynursa/checkpoint-capacitor","version":"0.1.0","description":"Checkpoint location / geofence / ingest SDK for Capacitor (iOS + Android). The SDK is a sensor; all detection logic runs server-side.","type":"module","main":"dist/index.js","module":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","clean":"rm -rf dist"},"capacitor":{"ios":{"src":"ios"},"android":{"src":"android"}},"keywords":["capacitor","geofence","location","background-location","checkpoint"],"license":"UNLICENSED","peerDependencies":{"@capacitor/core":">=7.0.0"},"devDependencies":{"@capacitor/core":"^7.4.3","typescript":"^5.8.3"},"engines":{"node":">=18"},"capacitorPlatforms":{"ios":{"minVersion":"14.0"},"android":{"minSdk":23,"compileSdk":35}},"_id":"@andynursa/checkpoint-capacitor@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-TS+eIEcXTVURLdtSPtkMVNghcrWnof75r9m8rHBTWEVhfo8GBLgkgvvaYC5gUvgDYQ7/ge/c/NDFg3z8aCGkSw==","shasum":"09f0443038e55873cd17c09c22df73f9e636a2f9","tarball":"https://registry.npmjs.org/@andynursa/checkpoint-capacitor/-/checkpoint-capacitor-0.1.0.tgz","fileCount":53,"unpackedSize":231668,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDQ1brTzfzG+9pcByRc/6onCJeFkMTDaa/s9IO8rcL30AIhAORXDASfjJSELkz0GJ22sHDxuih4YZ398GKvfSCxe+6b"}]},"_npmUser":{"name":"andynursa","email":"jake.anderson@nursa.com"},"directories":{},"maintainers":[{"name":"andynursa","email":"jake.anderson@nursa.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/checkpoint-capacitor_0.1.0_1782364583502_0.666546952242083"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-25T05:16:23.296Z","0.1.0":"2026-06-25T05:16:23.636Z","modified":"2026-06-25T05:16:23.874Z"},"maintainers":[{"name":"andynursa","email":"jake.anderson@nursa.com"}],"description":"Checkpoint location / geofence / ingest SDK for Capacitor (iOS + Android). The SDK is a sensor; all detection logic runs server-side.","keywords":["capacitor","geofence","location","background-location","checkpoint"],"license":"UNLICENSED","readme":"# @checkpoint/capacitor\n\nThe Checkpoint location / geofence / ingest SDK for Capacitor (iOS + Android).\n\nThe SDK is deliberately thin: it bootstraps with your **publishable key**,\nidentifies a subject, pulls the armed fence set, registers native region\nmonitors, and posts location fixes — including from a force-quit app woken by the\nOS. All detection logic (M-of-N confirmation, dwell, exit hysteresis) runs\n**server-side**; the SDK is a sensor, not a decision-maker.\n\n## Install\n\n```bash\nnpm install @checkpoint/capacitor && npx cap sync\n```\n\n> This repo's app currently consumes the package **from source** via a path alias\n> (`@checkpoint/capacitor` → `packages/checkpoint-capacitor/src`) and a `file:`\n> dependency — see the root `vite.config.ts`, `tsconfig.app.json`, and\n> `package.json`. No npm publish is required for the in-repo app.\n\n## Host app requirements\n\n### iOS `Info.plist`\n\nBackground location and force-quit wake-on-geofence are the whole point, so all\nthree are mandatory in the **host app's** `Info.plist`:\n\n- `NSLocationWhenInUseUsageDescription`\n- `NSLocationAlwaysAndWhenInUseUsageDescription`\n- `UIBackgroundModes: location`\n\n### iOS cold-relaunch revive (host `AppDelegate`)\n\nThe package's `GeofenceManager` engine owns the cold-relaunch revive\n(`reviveForBackgroundLaunch()`), but it must be **called from the host app's\n`AppDelegate.didFinishLaunchingWithOptions`** when `launchOptions[.location]` is\nset, so an `always + streamNow` device woken from a killed state resumes\nstreaming. This is an app-delegate concern and stays in the app:\n\n```swift\nimport CheckpointCapacitor  // the pod's module\n// ...\nif launchOptions?[.location] != nil {\n    GeofenceManager.shared.reviveForBackgroundLaunch()\n}\n```\n\n### Plugin registration\n\nOnce installed as an npm package, the native plugin auto-registers via\nCapacitor's `cap sync`-generated `packageClassList` — do **not** also register it\nmanually (`registerPluginInstance` / `registerPlugin(...)`) or you double-register\nand two instances race on `onRegionEvent`. See the repo's\n`docs/sdk-extraction-plan.md` §7 (risk R1) for the device-verification checklist\naround this flip.\n\n## Usage\n\n```ts\nimport { Checkpoint } from \"@checkpoint/capacitor\";\n\n// 1. Configure transport once. baseUrl, anonKey, and publishableKey are all\n//    required — point them at YOUR platform project (anon key is public-safe).\nCheckpoint.init({\n  publishableKey: \"pk_live_…\",\n  baseUrl: \"https://<your-project-ref>.supabase.co\",\n  anonKey: \"<your-platform-anon-key>\",\n});\n\n// 2. Read the server-resolved directive / apply a mode.\nconst directive = await Checkpoint.getTrackingDirective(\"sub_…\", { appId });\nawait Checkpoint.setTrackingMode(\"always\");   // applies to the native layer\n```\n\n### Public API surface\n\n- **Layer 1 (raw native plugin):** `NativeGeofence` + the frozen\n  `NativeGeofencePlugin` contract types (`TrackingMode`, `RegionEvent`,\n  `NativeDiagnostics`, `NativeFenceDiag`). Wrapper SDKs (RN / Flutter) bind to\n  this same native ABI.\n- **Layer 2 (facade):** `Checkpoint.{init, setTrackingMode, getTrackingMode,\n  getTrackingDirective, setDeviceTrackingMode}` + `CheckpointConfig`,\n  `CheckpointTransport`, `CHECKPOINT_API_VERSION`.\n- **Device REST hot-path:** `mintDeviceToken`, `getTrackingDirective`,\n  `setDeviceTrackingMode` (all transport-injected; never the app's Supabase\n  session client).\n- **Presence primitives (framework-agnostic):** `pullArmedFences` (with the\n  build-7 transient-empty-pull guard), `ingestFix`, `postSelfFence`,\n  `postJoinPlace`, `fetchNearbyPlaces`, `metersBetween`, `fenceSignature`,\n  `zoneFor`, `DEFAULT_DIRECTIVE`.\n- **Subject id codec:** `encodeSubjectPublicId`, `decodeSubjectPublicId`.\n- **Tracking-mode local persistence:** `readStoredMode`, `writeStoredMode`,\n  `readPendingMode`, `writePendingMode`, `clearPendingMode`, `modeKey`.\n\n## Tests\n\n```bash\nnpm run build && node --test test/pure.test.mjs test/fences.test.mjs\n```\n\nCovers the pure functions (`metersBetween`, `fenceSignature`, `zoneFor`, the\nsubject-id codec) and the build-7 transient-empty-pull guard in `pullArmedFences`.\n","readmeFilename":"README.md","_rev":"1-17d17888400964d8ca1e461685eecc75"}