{"_id":"@abennouna/capacitor-compass-accuracy","name":"@abennouna/capacitor-compass-accuracy","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@abennouna/capacitor-compass-accuracy","version":"0.0.1","description":"A Capacitor plugin for Android to monitor the accuracy of the device compass.","main":"dist/plugin.cjs.js","module":"dist/esm/index.js","types":"dist/esm/index.d.ts","unpkg":"dist/plugin.js","author":{"name":"Abdelaziz Bennouna","url":"tellibus"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/abennouna/capacitor-compass-accuracy.git"},"bugs":{"url":"https://github.com/abennouna/capacitor-compass-accuracy/issues"},"keywords":["capacitor","plugin","native","compass","accuracy","android"],"scripts":{"verify":"npm run verify:ios && npm run verify:android && npm run verify:web","verify:ios":"xcodebuild -scheme AbennounaCapacitorCompassAccuracy -destination generic/platform=iOS","verify:android":"cd android && ./gradlew clean build test && cd ..","verify:web":"npm run build","lint":"npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint","fmt":"npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format","eslint":"eslint . --ext ts","prettier":"prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java","swiftlint":"node-swiftlint","docgen":"docgen --api CompassAccuracyPlugin --output-readme README.md --output-json dist/docs.json","build":"npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs","clean":"rimraf ./dist","watch":"tsc --watch","prepublishOnly":"npm run build"},"devDependencies":{"@capacitor/android":"^8.0.0","@capacitor/core":"^8.0.0","@capacitor/docgen":"^0.3.1","@capacitor/ios":"^8.0.0","@ionic/eslint-config":"^0.4.0","@ionic/prettier-config":"^4.0.0","@ionic/swiftlint-config":"^2.0.0","eslint":"^8.57.1","prettier":"^3.6.2","prettier-plugin-java":"^2.7.7","rimraf":"^6.1.0","rollup":"^4.53.2","swiftlint":"^2.0.0","typescript":"^5.9.3"},"peerDependencies":{"@capacitor/core":">=8.0.0"},"overrides":{"lodash@>=4.0.0 <4.17.23":"4.17.23","lodash-es@>=4.0.0 <4.17.23":"4.17.23"},"prettier":"@ionic/prettier-config","swiftlint":"@ionic/swiftlint-config","eslintConfig":{"extends":"@ionic/eslint-config/recommended"},"capacitor":{"ios":{"src":"ios"},"android":{"src":"android"}},"gitHead":"3427352a40828192aeef40dc67560b710f6138a5","_id":"@abennouna/capacitor-compass-accuracy@0.0.1","homepage":"https://github.com/abennouna/capacitor-compass-accuracy#readme","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-fS2f6hHjdnacHKtfhGgUucBEwllZ76mSO/5OC0cUSbnsnxfD8nwTzr3WV5P64c1vKmRyIPnkTioe+pLB84fn8A==","shasum":"d66d86b7414b96bdd7b0e834fe40d7ce31682c8d","tarball":"https://registry.npmjs.org/@abennouna/capacitor-compass-accuracy/-/capacitor-compass-accuracy-0.0.1.tgz","fileCount":25,"unpackedSize":53566,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFSNNLXK1Kt7J9vHYcn7uKUFu3NF8OhTVLUuW0oD+aaTAiEA/AtDrcfuQQ70SB52bRzvExdT1So3YTD+7CJpLW4bo1k="}]},"_npmUser":{"name":"abennouna","email":"abennouna@gmail.com"},"directories":{},"maintainers":[{"name":"abennouna","email":"abennouna@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/capacitor-compass-accuracy_0.0.1_1769796476367_0.5847808068172531"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-30T18:07:56.293Z","0.0.1":"2026-01-30T18:07:56.511Z","modified":"2026-01-30T18:07:56.733Z"},"maintainers":[{"name":"abennouna","email":"abennouna@gmail.com"}],"description":"A Capacitor plugin for Android to monitor the accuracy of the device compass.","homepage":"https://github.com/abennouna/capacitor-compass-accuracy#readme","keywords":["capacitor","plugin","native","compass","accuracy","android"],"repository":{"type":"git","url":"git+https://github.com/abennouna/capacitor-compass-accuracy.git"},"author":{"name":"Abdelaziz Bennouna","url":"tellibus"},"bugs":{"url":"https://github.com/abennouna/capacitor-compass-accuracy/issues"},"license":"MIT","readme":"# @abennouna/capacitor-compass-accuracy\n\nA Capacitor plugin for Android to monitor the accuracy of the device compass.\n\nThis is a port of the [cordova-plugin-compass-accuracy](https://github.com/dpa99c/cordova-plugin-compass-accuracy) plugin to Capacitor.\n\n## Platform Support\n\n- ✅ **Android**: Full support (reports sensor accuracy changes)\n- ⚠️ **iOS**: Not needed - iOS automatically calibrates the compass using the motion coprocessor since iPhone 5S and iOS 13\n- ⚠️ **Web**: Not supported - compass accuracy monitoring is not available on web\n\n## Installation\n\n```bash\nnpm install @abennouna/capacitor-compass-accuracy\nnpx cap sync\n```\n\n## API\n\n### Interfaces\n\n#### `AccuracyLevel`\n\nEnum indicating the required or current accuracy of the device compass:\n\n- `HIGH` - High accuracy (less than 5 degrees of error)\n- `MEDIUM` - Medium accuracy (less than 10 degrees of error)\n- `LOW` - Low accuracy (less than 15 degrees of error)\n- `UNRELIABLE` - Unreliable accuracy (more than 15 degrees of error)\n- `UNKNOWN` - Unknown accuracy value\n\n#### `ResultType`\n\nEnum indicating the type of result being returned:\n\n- `STARTED` - Monitor has been started and the current accuracy is being returned\n- `ACCURACY_CHANGED` - Accuracy has changed and the new accuracy is being returned\n\n#### `AccuracyChangeResult`\n\n```typescript\ninterface AccuracyChangeResult {\n  type: ResultType;\n  currentAccuracy: AccuracyLevel;\n  requiredAccuracy: AccuracyLevel;\n  previousAccuracy?: AccuracyLevel;\n  isInaccurate?: boolean;\n}\n```\n\n### Methods\n\n#### `startMonitoring(options, callback)`\n\nStarts monitoring the accuracy of the device compass for the required accuracy level.\n\n- This plugin does not show any native UI. Your app is responsible for reacting to insufficient accuracy.\n- The callback will be invoked when monitoring starts and whenever accuracy changes\n\n```typescript\nimport { CompassAccuracy, AccuracyLevel } from '@abennouna/capacitor-compass-accuracy';\n\nconst callbackId = await CompassAccuracy.startMonitoring(\n  { requiredAccuracy: AccuracyLevel.HIGH },\n  (result, error) => {\n    if (error) {\n      console.error('Error:', error);\n      return;\n    }\n    \n    if (result) {\n      console.log('Type:', result.type);\n      console.log('Current Accuracy:', result.currentAccuracy);\n      console.log('Required Accuracy:', result.requiredAccuracy);\n    }\n  }\n);\n```\n\n**Parameters:**\n- `options`: `StartMonitoringOptions` - Configuration options\n  - `requiredAccuracy`: `AccuracyLevel` (optional) - Required accuracy level (defaults to HIGH)\n- `callback`: `(result, error) => void` - Callback function that receives accuracy updates\n\n**Returns:** `Promise<string>` - Callback ID for the monitoring session\n\n#### `stopMonitoring()`\n\nStops monitoring the accuracy of the device compass.\n\n```typescript\nawait CompassAccuracy.stopMonitoring();\n```\n\n**Returns:** `Promise<void>`\n\n#### `getCurrentAccuracy()`\n\nGets the current accuracy of the device compass.\n\n```typescript\nconst result = await CompassAccuracy.getCurrentAccuracy();\nconsole.log('Current Accuracy:', result.currentAccuracy);\n```\n\n**Returns:** `Promise<{ currentAccuracy: AccuracyLevel }>`\n\n#### `simulateAccuracyChange(options)`\n\nSimulates a change in compass accuracy. This method is intended for testing only.\n\n```typescript\nawait CompassAccuracy.simulateAccuracyChange({ \n  accuracy: AccuracyLevel.LOW \n});\n```\n\n**Parameters:**\n- `options`: `{ accuracy: AccuracyLevel }` - The simulated accuracy level\n\n**Returns:** `Promise<void>`\n\n## Usage Example\n\n```typescript\nimport { CompassAccuracy, AccuracyLevel, ResultType } from '@abennouna/capacitor-compass-accuracy';\n\n// Start monitoring with high accuracy requirement\nconst startMonitoring = async () => {\n  try {\n    const callbackId = await CompassAccuracy.startMonitoring(\n      { requiredAccuracy: AccuracyLevel.HIGH },\n      (result, error) => {\n        if (error) {\n          console.error('Monitoring error:', error);\n          return;\n        }\n\n        if (result) {\n          const action = result.type === ResultType.STARTED ? 'started as' : 'changed to';\n          console.log(`Compass accuracy ${action}: ${result.currentAccuracy}`);\n          console.log(`Required accuracy: ${result.requiredAccuracy}`);\n          \n          // Handle insufficient accuracy in your app (UI/UX is out of scope of this plugin)\n        }\n      }\n    );\n    \n    console.log('Monitoring started with callback ID:', callbackId);\n  } catch (error) {\n    console.error('Failed to start monitoring:', error);\n  }\n};\n\n// Stop monitoring\nconst stopMonitoring = async () => {\n  try {\n    await CompassAccuracy.stopMonitoring();\n    console.log('Monitoring stopped');\n  } catch (error) {\n    console.error('Failed to stop monitoring:', error);\n  }\n};\n\n// Get current accuracy without starting monitoring\nconst checkAccuracy = async () => {\n  try {\n    const result = await CompassAccuracy.getCurrentAccuracy();\n    console.log('Current compass accuracy:', result.currentAccuracy);\n  } catch (error) {\n    console.error('Failed to get accuracy:', error);\n  }\n};\n```\n\n## How It Works\n\nThe plugin monitors the Android magnetometer sensor's accuracy events and reports changes back to JavaScript.\n\nThe plugin does not show any native UI. Your app is responsible for deciding how to react when accuracy is insufficient.\n\n## Differences from Cordova Plugin\n\nThis Capacitor plugin maintains API compatibility with the original Cordova plugin, with these differences:\n\n- Uses Capacitor's plugin architecture instead of Cordova's\n- Written in TypeScript for better type safety\n- Uses modern Promise-based APIs while maintaining callback support for monitoring\n- Simplified installation process (no plugin.xml)\n\n## License\n\nMIT License\n\nCopyright (c) 2026 Abdelaziz Bennouna (Tellibus)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","readmeFilename":"README.md","_rev":"1-2aa243a6d490a562f9650d68e0d95ced"}