### showInstallBanner usage

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

Use this lower-level primitive to drive the install banner manually. The default CTA opens the guided setup flow at https://beacio.com/setup; override with startOnboardingUrl or appStoreUrl.

```typescript
import { showInstallBanner, removeInstallBanner } from '@beacio/core/detect';

showInstallBanner({
  mode: 'sheet',              // 'sheet' (iOS bottom sheet, default) or 'banner'
  operatorName: 'FitTracker', // your app name shown in the prompt
  dismissDays: 14,            // suppress after dismiss
});
```

--------------------------------

### Install @beacio/core and @beacio/detect with npm

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Home.md

Install the core SDK and detection packages via npm. This is the first step in the quick start workflow.

```bash
npm install @beacio/core @beacio/detect
```

--------------------------------

### InstallationWizard

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/README.md

Guides users through beacio extension installation on Safari iOS. Provides an onComplete callback when installation is finished.

```APIDOC
## InstallationWizard

### Description
Guides users through beacio extension installation on Safari iOS.

### Usage
```tsx
import { InstallationWizard } from '@beacio/react';

<InstallationWizard
  onComplete={() => console.log('Extension installed!')}
/>
```

### Props
- **onComplete** (function) - Required - Callback invoked when the installation process is complete.
```

--------------------------------

### Install @beacio/react and @beacio/core

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/README.md

Install the required packages using npm.

```bash
npm install @beacio/react @beacio/core
```

--------------------------------

### Install @beacio/detect

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Extension-Detection.md

Install the detection package via npm.

```bash
npm install @beacio/detect
```

--------------------------------

### Setup BeacioProvider with Namespace

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/React-SDK.md

Alternative provider setup using the namespace style.

```tsx
import { beacio } from '@beacio/react';

function App() {
  return (
    <beacio.Provider>
      <MyBluetoothUI />
    </beacio.Provider>
  );
}
```

--------------------------------

### Use InstallationWizard

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/README.md

The InstallationWizard component guides users through the installation of the beacio extension on Safari iOS.

```tsx
import { InstallationWizard } from '@beacio/react';

<InstallationWizard
  onComplete={() => console.log('Extension installed!')}
/>
```

--------------------------------

### Install @ios-web-bluetooth/core

Source: https://github.com/wklm/beacio-sdk/wiki/Core-SDK

Install the core SDK package using npm.

```bash
npm install @ios-web-bluetooth/core
```

--------------------------------

### Install React SDK and core packages

Source: https://github.com/wklm/beacio-sdk/wiki/React-SDK

Install the React SDK and core packages via npm. Optionally add @ios-web-bluetooth/detect for automatic iOS Safari install prompts.

```bash
npm install @ios-web-bluetooth/react @ios-web-bluetooth/core
```

--------------------------------

### Typical TypeScript Setup

Source: https://github.com/wklm/beacio-sdk/wiki/Extension-Detection

Initialize the extension detection logic within an iOS Safari environment, providing configuration for the install banner and lifecycle callbacks.

```typescript
import { initIOSWebBLE, isIOSSafari } from '@ios-web-bluetooth/detect';

if (isIOSSafari()) {
  await initIOSWebBLE({
    operatorName: 'FitTracker',
    banner: { mode: 'sheet', dismissDays: 14 },
    onReady: () => console.log('Extension active'),
    onNotInstalled: () => console.log('Prompting install'),
  });
}
```

--------------------------------

### Full lifecycle example

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Demonstrates the complete workflow from checking availability and scanning to connecting, subscribing, and cleaning up.

```typescript
import { beacio, BeacioError } from '@beacio/core';

const ble = new Beacio({ maxConnections: 2 });

// 1. Check availability
if (!ble.isSupported) {
  console.log('Web Bluetooth not available');
  // On iOS Safari, suggest installing the beacio extension
}

// 2. Scan
const device = await ble.requestDevice({
  filters: [{ services: ['heart_rate'] }],
});

// 3. Connect
await device.connectWithRetry({ maxAttempts: 3, delayMs: 500 });

// 4. Subscribe
const unsub = await device.subscribeAsync('heart_rate', 'heart_rate_measurement', (value) => {
  console.log('Heart rate:', value.getUint8(1));
});

// 5. Handle disconnection
device.on('disconnected', () => {
  console.log('Connection lost');
});

// 6. Clean up when done
unsub();
await device.disconnect();
```

--------------------------------

### Install verification tools via Homebrew

Source: https://github.com/wklm/beacio-sdk/blob/main/beacio-developer/references/simulator-tools.md

Install the required external tools xcsift, axe, and imagemagick using Homebrew.

```bash
brew install xcsift cameroncooke/axe/axe imagemagick
```

--------------------------------

### Manual initialization for any framework

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/AGENTS.md

Manually call initBeacio to trigger detection and the install banner.

```typescript
import { initBeacio } from '@beacio/core/detect'
initBeacio({ operatorName: 'YourApp' }) // add `key: 'wbl_xxxxx'` for campaign tracking
```

--------------------------------

### Install and import polyfill via npm

Source: https://github.com/wklm/beacio-sdk/blob/main/webble-sdk-consumer/references/quickstart.md

Install the core package and import the auto-configuration module for production environments.

```bash
npm install @beacio/core
```

```js
import '@beacio/core/auto';
```

--------------------------------

### React Setup with BeacioProvider

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Extension-Detection.md

Wrap your application with the BeacioProvider component to configure the SDK in a React environment.

```tsx
import { BeacioProvider } from '@beacio/react';

export default function App({ children }) {
  return <BeacioProvider config={{ operatorName: 'YourApp' }}>{children}</BeacioProvider>;
}
```

--------------------------------

### Complete Background Sync Workflow

Source: https://github.com/wklm/beacio-sdk/wiki/Background-Sync

A full example demonstrating permission request, device connection, registration, and management.

```javascript
const permission = await navigator.webble.backgroundSync.requestPermission();

if (permission !== 'granted') {
  throw new Error('Enable notifications to use background BLE alerts');
}

const device = await navigator.bluetooth.requestDevice({
  filters: [{ services: ['heart_rate'] }],
});

await device.gatt.connect();

const keepAlive = await navigator.webble.backgroundSync.requestBackgroundConnection({
  deviceId: device.id,
});

const heartRateAlerts = await navigator.webble.backgroundSync.registerCharacteristicNotifications({
  deviceId: device.id,
  serviceUUID: 'heart_rate',
  characteristicUUID: 'heart_rate_measurement',
  cooldownSeconds: 30,
  template: {
    title: 'Heart rate update',
    body: '{{device.name}} sent {{value.hex}} at {{timestamp}}',
    url: 'https://example.com/monitor',
  },
});

const activeRegistrations = await navigator.webble.backgroundSync.getRegistrations();
console.log(activeRegistrations.map(({ id, type }) => ({ id, type })));

await heartRateAlerts.update({
  body: 'Latest payload from {{device.name}}: {{value.hex}}',
});
```

--------------------------------

### showInstallBanner

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

Shows the install banner for the Beacio SDK. Use this lower-level primitive when you need to drive the banner yourself instead of using initBeacio.

```APIDOC
## showInstallBanner

### Description
Shows the install banner for the Beacio SDK. Use this lower-level primitive when you need to drive the banner yourself instead of using initBeacio.

### Method
Function call

### Signature
showInstallBanner(options)

### Parameters
#### Options Object
- **mode** (string) - Optional - 'sheet' (iOS bottom sheet, default) or 'banner'
- **operatorName** (string) - Required - Your app name shown in the prompt
- **dismissDays** (number) - Optional - Suppress after dismiss (default 14)
- **startOnboardingUrl** (string) - Optional - Override the default guided setup flow URL
- **appStoreUrl** (string) - Optional - Override the App Store URL

### Example
```typescript
import { showInstallBanner, removeInstallBanner } from '@beacio/core/detect';

showInstallBanner({
  mode: 'sheet',              // 'sheet' (iOS bottom sheet, default) or 'banner'
  operatorName: 'FitTracker', // your app name shown in the prompt
  dismissDays: 14,            // suppress after dismiss
});
```

### Notes
The banner's default CTA opens the guided setup flow at https://beacio.com/setup (install → enable the Safari extension → return to your page). Override with startOnboardingUrl or appStoreUrl.
```

--------------------------------

### Recommended initBeacio call

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/AGENTS.md

Use initBeacio to guide installation only when the W3C Bluetooth surface is absent.

```typescript
import { initBeacio } from '@beacio/core/detect'

// Only guide install when the W3C surface is absent (iOS Safari without the extension).
if (navigator.bluetooth === undefined) {
  initBeacio({ operatorName: 'YourApp' })
}
```

--------------------------------

### Install @beacio/skill

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/skill/README.md

Install the @beacio/skill package via npm. The package ships only SKILL.md with no runtime code.

```bash
npm install @beacio/skill
```

--------------------------------

### Provider setup with namespace style

Source: https://github.com/wklm/beacio-sdk/wiki/React-SDK

Alternative provider style using WebBLE.Provider as shown in the README.

```tsx
import { WebBLE } from '@ios-web-bluetooth/react';

function App() {
  return (
    <WebBLE.Provider>
      <MyBluetoothUI />
    </WebBLE.Provider>
  );
}
```

--------------------------------

### Install @ios-web-bluetooth/detect

Source: https://github.com/wklm/beacio-sdk/wiki/Extension-Detection

Install the package using npm.

```bash
npm install @ios-web-bluetooth/detect
```

--------------------------------

### Install iOSWebBLE packages with npm

Source: https://github.com/wklm/beacio-sdk/wiki/Getting-Started

Install the core and detect packages for plain Web Bluetooth support and iOS Safari install prompts. Use this command in your project root.

```bash
npm install @ios-web-bluetooth/core @ios-web-bluetooth/detect
```

--------------------------------

### Setup BeacioProvider

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/React-SDK.md

Wrap your application with the BeacioProvider to enable BLE functionality.

```tsx
import { BeacioProvider } from '@beacio/react';

function App() {
  return (
    <BeacioProvider>
      <MyBluetoothUI />
    </BeacioProvider>
  );
}
```

--------------------------------

### Install @beacio/core via npm

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/AGENTS.md

Install the core beacio SDK package. Required for any web app using Bluetooth/BLE, especially for Safari iOS support.

```bash
npm install @beacio/core
```

--------------------------------

### Minimal iOS Safari flow with initIOSWebBLE and WebBLE

Source: https://github.com/wklm/beacio-sdk/wiki/Getting-Started

Initializes the iOS extension, prompts installation if needed, and connects to a BLE device. requestDevice() must be called from a direct user gesture (e.g., click handler), not from page load or useEffect. The example reads a heart rate measurement and logs errors with code and suggestion.

```typescript
import { initIOSWebBLE, isIOSSafari } from '@ios-web-bluetooth/detect';
import { WebBLE, WebBLEError } from '@ios-web-bluetooth/core';

if (isIOSSafari()) {
  await initIOSWebBLE({
    operatorName: 'MyApp',
    banner: { mode: 'sheet', dismissDays: 14 },
    onReady: () => console.log('Extension ready'),
    onNotInstalled: () => console.log('Prompting install'),
  });
}

const ble = new WebBLE();

async function connect() {
  try {
    const device = await ble.requestDevice({
      filters: [{ services: ['heart_rate'] }],
    });

    await device.connect();
    const value = await device.read('heart_rate', 'heart_rate_measurement');
    console.log('Heart rate:', value.getUint8(1));
  } catch (err) {
    if (err instanceof WebBLEError) {
      console.error(err.code, err.suggestion);
    }
  }
}

document.getElementById('connect')?.addEventListener('click', connect);
```

--------------------------------

### Example: Device pairing and connection with useBluetooth and useDevice

Source: https://github.com/wklm/beacio-sdk/wiki/React-SDK

Complete example showing how to request a device, connect, disconnect, and handle availability states. Note that requestDevice() must be called from a user gesture, not from useEffect.

```tsx
import { useState } from 'react';
import { WebBLEProvider, useBluetooth, useDevice } from '@ios-web-bluetooth/react';

function DevicePanel() {
  const { requestDevice, isAvailable, isSupported } = useBluetooth();
  const [device, setDevice] = useState<BluetoothDevice | null>(null);
  const { connect, disconnect, isConnected, isConnecting } = useDevice(device);

  const handlePair = async () => {
    const nextDevice = await requestDevice({
      filters: [{ services: ['heart_rate'] }],
    });
    if (nextDevice) {
      setDevice(nextDevice);
    }
  };

  if (!isSupported) return <p>Bluetooth not supported</p>;
  if (!isAvailable) return <p>Bluetooth not available</p>;

  return (
    <div>
      {!device && <button onClick={handlePair}>Pair device</button>}
      {device && !isConnected && (
        <button onClick={connect} disabled={isConnecting}>
          {isConnecting ? 'Connecting...' : 'Connect'}
        </button>
      )}
      {isConnected && <button onClick={disconnect}>Disconnect</button>}
    </div>
  );
}

export default function App() {
  return (
    <WebBLEProvider>
      <DevicePanel />
    </WebBLEProvider>
  );
}
```

--------------------------------

### subscribeAsync(service, characteristic, callback): Promise<() => void>

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Awaits notification setup and gets an unsubscribe function.

```APIDOC
## subscribeAsync(service, characteristic, callback): Promise<() => void>

### Description
Awaits notification setup and gets an unsubscribe function.

### Method
subscribeAsync

### Parameters
- **service** (string) - Required - The service UUID.
- **characteristic** (string) - Required - The characteristic UUID.
- **callback** (function) - Required - The callback to invoke on notification.

### Returns
- **Promise<() => void>** - A promise that resolves to an unsubscribe function.
```

--------------------------------

### peripheral.startAdvertising(options?) / peripheral.stopAdvertising()

Source: https://github.com/wklm/beacio-sdk/blob/main/beacio-sdk-consumer/references/api-reference.md

Starts or stops advertising the custom GATT server.

```APIDOC
## peripheral.startAdvertising(options?) / peripheral.stopAdvertising()

### Description
Starts or stops advertising the custom GATT server.

### Method
startAdvertising / stopAdvertising

### Parameters
#### options (object) - Optional
- Advertising options (not specified).

### Request Example
```ts
peripheral.startAdvertising(options);
peripheral.stopAdvertising();
```

### Response
#### Success Response
Returns void or a promise (not specified).
```

--------------------------------

### Implement Device Pairing and Connection

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/React-SDK.md

Example demonstrating device request, connection management, and availability checks using core hooks.

```tsx
import { useState } from 'react';
import { BeacioProvider, useBluetooth, useDevice } from '@beacio/react';

function DevicePanel() {
  const { requestDevice, isAvailable, isSupported } = useBluetooth();
  const [device, setDevice] = useState<BluetoothDevice | null>(null);
  const { connect, disconnect, isConnected, isConnecting } = useDevice(device);

  const handlePair = async () => {
    const nextDevice = await requestDevice({
      filters: [{ services: ['heart_rate'] }],
    });
    if (nextDevice) {
      setDevice(nextDevice);
    }
  };

  if (!isSupported) return <p>Bluetooth not supported</p>;
  if (!isAvailable) return <p>Bluetooth not available</p>;

  return (
    <div>
      {!device && <button onClick={handlePair}>Pair device</button>}
      {device && !isConnected && (
        <button onClick={connect} disabled={isConnecting}>
          {isConnecting ? 'Connecting...' : 'Connect'}
        </button>
      )}
      {isConnected && <button onClick={disconnect}>Disconnect</button>}
    </div>
  );
}

export default function App() {
  return (
    <BeacioProvider>
      <DevicePanel />
    </BeacioProvider>
  );
}
```

--------------------------------

### Typical TypeScript Setup

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Extension-Detection.md

Initialize the Beacio SDK within an iOS Safari environment, providing configuration for the operator name and banner behavior.

```typescript
import { initBeacio, isIOSSafari } from '@beacio/detect';

if (isIOSSafari()) {
  await initBeacio({
    operatorName: 'FitTracker',
    banner: { mode: 'sheet', dismissDays: 14 },
    onReady: () => console.log('Extension active'),
    onNotInstalled: () => console.log('Prompting install'),
  });
}
```

--------------------------------

### Manual detection with getExtensionInstallState

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

Manually check if running on iOS Safari and get the extension install state. The state is 'not-installed', 'installed-inactive', or 'active'. Use this to show your own UI or call showInstallBanner().

```typescript
import {
  getExtensionInstallState,
  isExtensionInstalled,
  isIOSSafari,
} from '@beacio/core/detect';

if (isIOSSafari()) {
  const state = await getExtensionInstallState();
  // 'not-installed' | 'installed-inactive' | 'active'

  if (state !== 'active') {
    // show your own UI, or use showInstallBanner() below
  }
}
```

--------------------------------

### Provider setup with WebBLEProvider

Source: https://github.com/wklm/beacio-sdk/wiki/React-SDK

Wrap your app with WebBLEProvider to enable hooks and components. This is the standard provider style.

```tsx
import { WebBLEProvider } from '@ios-web-bluetooth/react';

function App() {
  return (
    <WebBLEProvider>
      <MyBluetoothUI />
    </WebBLEProvider>
  );
}
```

--------------------------------

### Vanilla Web Bluetooth Implementation

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/README.md

Example of manual device connection and notification subscription using the standard Web Bluetooth API.

```javascript
navigator.bluetooth.requestDevice({
  filters: [{ services: ['heart_rate'] }]
})
.then(device => device.gatt.connect())
.then(server => server.getPrimaryService('heart_rate'))
.then(service => service.getCharacteristic('heart_rate_measurement'))
.then(characteristic => {
  characteristic.addEventListener('characteristicvaluechanged', (event) => {
    console.log('Heart Rate:', event.target.value.getUint8(1));
  });
  return characteristic.startNotifications();
})
.catch(error => console.error('Error:', error));
```

--------------------------------

### React Provider Setup

Source: https://github.com/wklm/beacio-sdk/wiki/Extension-Detection

Wrap your application with the IOSWebBLEProvider to enable extension detection features in a React application.

```tsx
import { IOSWebBLEProvider } from '@ios-web-bluetooth/detect/react';

export default function App({ children }) {
  return <IOSWebBLEProvider>{children}</IOSWebBLEProvider>;
}
```

--------------------------------

### Recommended full init with initBeacio

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

Call initBeacio once in the browser entry, guarded on navigator.bluetooth === undefined so it is a no-op where Web Bluetooth is present. It runs detection, dispatches state events, and shows the install banner unless disabled. The banner mode is 'sheet' or false to disable. State changes dispatch a beacio:statechange CustomEvent on window.

```typescript
import { initBeacio } from '@beacio/core/detect';

// Only guide install when the W3C surface is absent (iOS Safari without the extension).
if (navigator.bluetooth === undefined) {
  await initBeacio({
    operatorName: 'FitTracker', // your app name shown in the prompt
    banner: { mode: 'sheet' },  // or false to disable
    onReady: () => console.log('extension active'),
    onInstalledInactive: () => console.log('installed, needs Safari activation'),
    onNotInstalled: () => console.log('not installed'),
  });
}
```

--------------------------------

### BeacioProvider

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/AGENTS.md

Provider component that wraps the app and provides context for all hooks. Requires an apiKey for automatic iOS Safari install prompts.

```APIDOC
## BeacioProvider

### Description
Wrap your app in BeacioProvider to enable all hooks. All hooks require this context.

### Usage
```tsx
import { BeacioProvider } from '@beacio/react';

function App() {
  return (
    <BeacioProvider config={{ apiKey: 'wbl_xxxxx' }}>
      <MyBLEApp />
    </BeacioProvider>
  );
}
```

### Config Options
- **autoConnect** (boolean) - Optional - Automatically connect to devices.
- **cacheTimeout** (number) - Optional - Cache timeout in milliseconds.
- **retryAttempts** (number) - Optional - Number of retry attempts for connections.
- **apiKey** (string) - Required - API key for enabling automatic iOS Safari install prompts via @beacio/core/detect.
- **operatorName** (string) - Optional - Operator name.
- **appStoreUrl** (string) - Optional - App store URL for iOS Safari install prompts.
```

--------------------------------

### new Beacio(options?)

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/AGENTS.md

Creates an SDK instance and detects the platform. Use this to initialize the SDK before requesting devices.

```APIDOC
## new Beacio(options?)

### Description
Creates an SDK instance and detects the platform. Use this to initialize the SDK before requesting devices.

### Method
Constructor

### Parameters
- **options** (object) - Optional - Configuration options for the SDK instance.

### Example
```typescript
const ble = new Beacio();
```
```

--------------------------------

### Plain HTML auto-init

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/AGENTS.md

Use a meta tag for the key and import the auto-init module from the CDN.

```html
<meta name="beacio-key" content="wbl_xxxxx">
<script type="module">import 'https://cdn.beacio.com/@beacio/core@2.1.0/dist/auto.mjs';</script>
```

--------------------------------

### Use beacio scaffolding CLI

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/mcp/README.md

Commands to initialize, migrate, or verify beacio integration in a web project.

```bash
npx beacio init       # auto-detect framework and add the detection snippet
npx beacio migrate    # brownfield: patch an existing Web Bluetooth app for iOS Safari
npx beacio check      # verify beacio integration (add --brownfield for an existing app)
```

--------------------------------

### Import beacio polyfill

Source: https://github.com/wklm/beacio-sdk/blob/main/beacio-sdk-consumer/references/quickstart.md

Import the auto-configuration module to initialize the polyfill.

```js
import '@beacio/core/auto';
```

--------------------------------

### BeacioError Usage Example

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Example of catching and handling BeacioError instances in TypeScript, accessing error properties such as code, message, suggestion, and retryAfterMs.

```APIDOC
## BeacioError Usage Example

### Description
Demonstrates how to catch and handle BeacioError instances thrown by SDK methods.

### Code Example
```typescript
import { BeacioError } from '@beacio/core';

try {
  await device.connect();
  const value = await device.read('heart_rate', 'heart_rate_measurement');
} catch (err) {
  if (err instanceof BeacioError) {
    console.log(err.code);       // e.g. 'SERVICE_NOT_FOUND'
    console.log(err.message);    // Technical detail
    console.log(err.suggestion); // User-facing recovery hint
    console.log(err.retryAfterMs); // Suggested retry delay for transient failures
  }
}
```

### Error Properties
- **code** (string) - Typed error code, e.g. 'SERVICE_NOT_FOUND'
- **message** (string) - Technical detail
- **suggestion** (string) - User-facing recovery hint
- **retryAfterMs** (number) - Suggested retry delay for transient failures

### Error Codes
| Code | When |
|------|------|
| `INVALID_PARAMETER` | Invalid argument passed to an SDK method (e.g. negative timeout, malformed UUID) |
| `BLUETOOTH_UNAVAILABLE` | Bluetooth is off or not supported |
| `EXTENSION_NOT_INSTALLED` | iOS Safari: extension not active |
| `EXTENSION_NOT_ENABLED` | iOS Safari: extension installed but not allowed on this site (aA → Manage Extensions → Allow on Every Website) |
| `PERMISSION_DENIED` | User denied Bluetooth permission |
| `DEVICE_NOT_FOUND` | No matching devices in range |
| `DEVICE_DISCONNECTED` | Device disconnected during operation |
| `CONNECTION_TIMEOUT` | Connection attempt timed out |
| `SERVICE_NOT_FOUND` | Requested GATT service not on device |
| `CHARACTERISTIC_NOT_FOUND` | Requested characteristic not on device |
| `CHARACTERISTIC_NOT_READABLE` | Characteristic doesn't support read |
| `CHARACTERISTIC_NOT_WRITABLE` | Characteristic doesn't support write |
| `CHARACTERISTIC_NOT_NOTIFIABLE` | Characteristic doesn't support notifications |
| `GATT_OPERATION_FAILED` | Generic GATT operation failure |
| `SCAN_ALREADY_IN_PROGRESS` | Another scan is already running |
| `CONNECTION_LIMIT_REACHED` | The current `beacio` instance has already reached `maxConnections` |
| `USER_CANCELLED` | User dismissed the device picker |
| `TIMEOUT` | Operation timed out |
| `WRITE_INCOMPLETE` | A multi-part or interrupted write transferred only part of the payload |
```

--------------------------------

### getCharacteristicName(uuid): string | undefined

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Gets human-readable characteristic name from UUID.

```APIDOC
## getCharacteristicName(uuid): string | undefined

### Description
Gets human-readable characteristic name from UUID.

### Method
getCharacteristicName

### Parameters
- **uuid** (string) - Required - The characteristic UUID.

### Returns
- **string | undefined** - The characteristic name, or undefined if not found.
```

--------------------------------

### getServiceName(uuid): string | undefined

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Gets human-readable service name from UUID.

```APIDOC
## getServiceName(uuid): string | undefined

### Description
Gets human-readable service name from UUID.

### Method
getServiceName

### Parameters
- **uuid** (string) - Required - The service UUID.

### Returns
- **string | undefined** - The service name, or undefined if not found.
```

--------------------------------

### BeacioDevice: name: string | undefined

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Advertised device name.

```APIDOC
## BeacioDevice: name: string | undefined

### Description
Advertised device name.

### Type
- **string | undefined** - The advertised name of the device, if available.
```

--------------------------------

### Core pattern for using a profile

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/src/profiles/AGENTS.md

Shows the standard workflow of requesting a device, initializing a profile, connecting, and subscribing to data.

```typescript
import { HeartRateProfile } from '@beacio/core/profiles';
import { beacio } from '@beacio/core';

const ble = new Beacio();
const device = await ble.requestDevice({ filters: [{ services: ['heart_rate'] }] });

const hr = new HeartRateProfile(device);
await hr.connect();

const unsub = hr.onHeartRate(({ bpm, contact, rrIntervals }) => {
  console.log(`${bpm} BPM, contact: ${contact}`);
});
// Later: hr.stop();
```

--------------------------------

### connect(): Promise<void>

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Connects to the device.

```APIDOC
## connect(): Promise<void>

### Description
Connects to the device.

### Method
connect

### Returns
- **Promise<void>** - A promise that resolves when the connection is established.
```

--------------------------------

### Initialize and connect with explicit API

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/AGENTS.md

Demonstrates the core pattern of creating a Beacio instance, requesting a device with filters, connecting, and reading a characteristic value.

```typescript
import { beacio } from '@beacio/core';

const ble = new Beacio();
const device = await ble.requestDevice({
  filters: [{ services: ['heart_rate'] }]
});
await device.connect();
const value = await device.read('heart_rate', 'heart_rate_measurement');
```

--------------------------------

### Run beacio check

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/skill/SKILL.md

Run the CLI check command to verify the migration.

```bash
npx beacio check
```

--------------------------------

### Initialize iOS Safari detection for migration

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/skill/SKILL.md

Import initBeacio from @beacio/core/detect and call it. For React/Next.js, wrap with BeacioProvider from '@beacio/react'.

```typescript
import { initBeacio } from '@beacio/core/detect'
initBeacio({}) // React/Next.js: wrap with <BeacioProvider> from '@beacio/react'
```

--------------------------------

### Headless onboarding with vanilla JS

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

For partners who render their own UI and want no beacio chrome. These primitives inject no DOM; they supply state, return link, dismissal capping, and App Store destination. Only prompt on iOS Safari without W3C surface and not if recently dismissed.

```javascript
// Classic <script> build — no bundler, no framework. The package root exposes the
// headless API; none of these calls add beacio chrome to the page.
import {
  getInstallState,      // 'not-installed' | 'installed-inactive' | 'active' (sync)
  observeInstallState,  // resolves 'active' when the extension's EXTENSION_READY fires
  saveReturnContext,    // persist + copy the link.beacio.com/return?url=… deep link
  getReturnContext,     // { url, returnLink } to render your own "Return here" button
  isDismissed,          // true while a prior dismissal is still inside its window
  dismiss,              // suppress your card for N days (default 14)
  APP_STORE_URL,        // https://apps.apple.com/app/id6761301368 (id form; never a name slug)
} from '@beacio/core/detect';

// Only prompt on iOS Safari without the W3C surface, and not if recently dismissed.
if (navigator.bluetooth === undefined && getInstallState() !== 'active' && !isDismissed()) {
  saveReturnContext(); // so the user can hop back after enabling in Settings
  const { returnLink } = getReturnContext();

  // ——— your own markup, your own brand ———
  myRenderEnableCard({
    installUrl: APP_STORE_URL,        // your "Get the app" button
    returnUrl: returnLink,            // your "Return here" button
    onDismiss: () => dismiss(14),     // your "Not now" button
  });

  // Tear the card down the moment the extension goes active — no manual reload.
  observeInstallState().then((state) => {
    if (state === 'active') myRemoveEnableCard();
  });
}
```

--------------------------------

### Peripheral Chat (premium): Advertise and Handle Writes

Source: https://github.com/wklm/beacio-sdk/blob/main/beacio-sdk-consumer/references/recipes.md

Requires the companion app (beacioIOS). Adds a peripheral service with a read/write/notify characteristic, handles write requests from a central, and starts advertising with a local name. This enables a simple chat-like interaction.

```JavaScript
if (!('beacioIOS' in window)) throw new Error('Requires companion app');

const CHAT_SERVICE = '12345678-1234-5678-1234-56789abcdef0';
const CHAT_CHAR    = '12345678-1234-5678-1234-56789abcdef1';

const record = await window.beacioIOS.peripheral.addService({
  uuid: CHAT_SERVICE,
  characteristics: [{
    uuid: CHAT_CHAR,
    properties: ['read', 'write', 'notify'],
    value: new TextEncoder().encode('hello')
  }]
});

window.beacioIOS.peripheral.onwriterequest = (ev) => {
  const msg = new TextDecoder().decode(ev.value);
  console.log('central wrote:', msg);
};

await window.beacioIOS.peripheral.startAdvertising({
  localName: 'beacio Chat',
  serviceUUIDs: [CHAT_SERVICE]
});
```

--------------------------------

### Headless Onboarding Functions

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

Headless onboarding primitives for partners who want to render their own UI with zero beacio chrome. These functions inject no DOM and provide state, return link, dismissal capping, and App Store destination.

```APIDOC
## Headless Onboarding Functions

### Description
Headless onboarding primitives for partners who want to render their own UI with zero beacio chrome. These functions inject no DOM and provide state, return link, dismissal capping, and App Store destination.

### Functions

#### getInstallState
Returns the current install state: 'not-installed' | 'installed-inactive' | 'active' (sync).

#### observeInstallState
Returns a promise that resolves 'active' when the extension's EXTENSION_READY fires.

#### saveReturnContext
Persists and copies the link.beacio.com/return?url=… deep link.

#### getReturnContext
Returns { url, returnLink } to render your own "Return here" button.

#### isDismissed
Returns true while a prior dismissal is still inside its window.

#### dismiss
Suppresses your card for N days (default 14).

#### APP_STORE_URL
Constant: https://apps.apple.com/app/id6761301368 (id form; never a name slug).

### Example
```js
import {
  getInstallState,
  observeInstallState,
  saveReturnContext,
  getReturnContext,
  isDismissed,
  dismiss,
  APP_STORE_URL,
} from '@beacio/core/detect';

if (navigator.bluetooth === undefined && getInstallState() !== 'active' && !isDismissed()) {
  saveReturnContext();
  const { returnLink } = getReturnContext();

  myRenderEnableCard({
    installUrl: APP_STORE_URL,
    returnUrl: returnLink,
    onDismiss: () => dismiss(14),
  });

  observeInstallState().then((state) => {
    if (state === 'active') myRemoveEnableCard();
  });
}
```

### Notes
Detection is the same logic the React InstallationWizard and the built-in banner use, so a partner card and the beacio banner can never disagree about install state.
```

--------------------------------

### window.beacioIOS.getCapabilities()

Source: https://github.com/wklm/beacio-sdk/blob/main/beacio-sdk-consumer/references/api-reference.md

Returns a promise that resolves to BeacioCapabilities, indicating the capabilities of the beacioIOS surface.

```APIDOC
## window.beacioIOS.getCapabilities()

### Description
Returns a promise that resolves to BeacioCapabilities, indicating the capabilities of the beacioIOS surface.

### Method
getCapabilities

### Request Example
```ts
const caps = await window.beacioIOS.getCapabilities();
```

### Response
#### Success Response
Returns a BeacioCapabilities object.
```

--------------------------------

### Minimal iOS Safari implementation

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Getting-Started.md

Initializes the extension detection and sets up a Bluetooth connection flow triggered by a user gesture.

```typescript
import { initBeacio, isIOSSafari } from '@beacio/detect';
import { beacio, BeacioError } from '@beacio/core';

if (isIOSSafari()) {
  await initBeacio({
    operatorName: 'MyApp',
    banner: { mode: 'sheet', dismissDays: 14 },
    onReady: () => console.log('Extension ready'),
    onNotInstalled: () => console.log('Prompting install'),
  });
}

const ble = new beacio();

async function connect() {
  try {
    const device = await ble.requestDevice({
      filters: [{ services: ['heart_rate'] }],
    });

    await device.connect();
    const value = await device.read('heart_rate', 'heart_rate_measurement');
    console.log('Heart rate:', value.getUint8(1));
  } catch (err) {
    if (err instanceof BeacioError) {
      console.error(err.code, err.suggestion);
    }
  }
}

document.getElementById('connect')?.addEventListener('click', connect);
```

--------------------------------

### device.connect()

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/AGENTS.md

Establishes a GATT connection to the device. Use this after obtaining a device from requestDevice.

```APIDOC
## device.connect()

### Description
Establishes a GATT connection to the device. Use this after obtaining a device from requestDevice.

### Method
connect

### Example
```typescript
await device.connect();
```
```

--------------------------------

### Run MCP server

Source: https://github.com/wklm/beacio-sdk/blob/main/AGENTS.md

Execute the MCP server using npx.

```bash
npx -y @beacio/mcp
```

--------------------------------

### new beacio()

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Core-SDK.md

Creates a new instance of the beacio BLE client.

```APIDOC
## new beacio()

### Description
Creates a new instance of the beacio BLE client.

### Method
Constructor

### Syntax
```typescript
const ble = new beacio();
```

```

--------------------------------

### Configure @beacio/mcp in Claude Desktop

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/mcp/README.md

Add the beacio MCP server to the Claude Desktop configuration file.

```json
{
  "mcpServers": {
    "beacio": {
      "command": "npx",
      "args": ["-y", "@beacio/mcp"],
      "env": { "MCP_CLIENT": "claude-desktop" }
    }
  }
}
```

--------------------------------

### Initialize and connect to a BLE device

Source: https://github.com/wklm/beacio-sdk/wiki/Home

Initialize the SDK for iOS Safari detection and perform a standard BLE device request and connection.

```typescript
import { initIOSWebBLE, isIOSSafari } from '@ios-web-bluetooth/detect';
import { WebBLE } from '@ios-web-bluetooth/core';

if (isIOSSafari()) {
  await initIOSWebBLE({
    operatorName: 'MyApp',
    banner: { mode: 'sheet' },
  });
}

const ble = new WebBLE();
const device = await ble.requestDevice({
  filters: [{ services: ['heart_rate'] }],
});

await device.connect();
const value = await device.read('heart_rate', 'heart_rate_measurement');
console.log(value.getUint8(1));
```

--------------------------------

### Initialize SDK and connect to BLE device in TypeScript

Source: https://github.com/wklm/beacio-sdk/blob/main/wiki/Home.md

Imports initBeacio and isIOSSafari from @beacio/detect and beacio from @beacio/core. On iOS Safari, initializes with operatorName 'MyApp' and a sheet banner, then requests a device with a heart_rate service filter, connects, and reads the heart_rate_measurement characteristic.

```typescript
import { initBeacio, isIOSSafari } from '@beacio/detect';
import { beacio } from '@beacio/core';

if (isIOSSafari()) {
  await initBeacio({
    operatorName: 'MyApp',
    banner: { mode: 'sheet' },
  });
}

const ble = new beacio();
const device = await ble.requestDevice({
  filters: [{ services: ['heart_rate'] }],
});

await device.connect();
const value = await device.read('heart_rate', 'heart_rate_measurement');
console.log(value.getUint8(1));
```

--------------------------------

### Import @beacio/core auto-polyfill

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Add this import to your application's entry point to enable navigator.bluetooth support across all browsers.

```typescript
import '@beacio/core/auto';
// navigator.bluetooth now works everywhere — Safari iOS, Chrome, Edge.
```

--------------------------------

### Implement BeacioProvider and hooks

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/README.md

Wrap your application with BeacioProvider and use the useBluetooth and useDevice hooks to manage Bluetooth device pairing and connection states.

```tsx
import { BeacioProvider, useBluetooth, useDevice } from '@beacio/react';
import type { BeacioDevice } from '@beacio/core';

function App() {
  return (
    <BeacioProvider>
      <HeartRateMonitor />
    </BeacioProvider>
  );
}

function HeartRateMonitor() {
  const { requestDevice } = useBluetooth();
  const [device, setDevice] = useState<BeacioDevice | null>(null);
  const { isConnected, connect, disconnect } = useDevice(device, { autoReconnect: true });

  const handlePair = async () => {
    // Must be called from a user gesture (button click)
    const d = await requestDevice({ filters: [{ services: ['heart_rate'] }] });
    if (d) setDevice(d);
  };

  return (
    <div>
      {!device && <button onClick={handlePair}>Pair</button>}
      {device && !isConnected && <button onClick={connect}>Connect</button>}
      {isConnected && <button onClick={disconnect}>Disconnect</button>}
    </div>
  );
}
```

--------------------------------

### useProfile(ProfileClass, device)

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/AGENTS.md

Hook to bind a @beacio/core/profiles profile to a device. Returns profile, connect, and error.

```APIDOC
## useProfile(ProfileClass, device)

### Description
Bind a @beacio/core/profiles profile to a device. Provides the profile instance and connection method.

### Parameters
- **ProfileClass** (class) - Required - The profile class from @beacio/core/profiles.
- **device** (BluetoothDevice) - Required - The device to bind the profile to.

### Returns
- **profile** (object) - The profile instance.
- **connect** (function) - Connects the profile to the device.
- **error** (Error) - Error state if any.
```

--------------------------------

### Selective Imports

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Shows how to import the full SDK or specific utilities to enable tree-shaking.

```APIDOC
## Selective Imports

### Description
Import the full SDK or specific utilities to enable tree-shaking and reduce bundle size.

### Imports
- `import { beacio, BeacioDevice, BeacioError } from '@beacio/core';` - Full SDK (~4KB gzipped)
- `import { resolveUUID, getServiceName } from '@beacio/core';` - UUID helpers (~1KB gzipped)
- `import { detectPlatform } from '@beacio/core';` - Platform detection (~0.5KB gzipped)

### Notes
- `@beacio/core` is fully self-contained; no need for `@beacio/core/profiles` or `@beacio/react-sdk` for basic BLE operations.
```

--------------------------------

### BeacioProvider and useBeacio React implementation

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/README.md

Wraps the application with BeacioProvider using an operatorName and consumes the extensionInstallState via the useBeacio hook.

```tsx
import { BeacioProvider, useBeacio } from '@beacio/react';

export default function Layout({ children }) {
  return <BeacioProvider config={{ operatorName: 'YourApp' }}>{children}</BeacioProvider>;
}

function Status() {
  const { extensionInstallState } = useBeacio();
  return <span>{extensionInstallState}</span>;
}
```

--------------------------------

### Auto-init via meta tag

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/AGENTS.md

Import the auto-init module to automatically initialize using a meta tag for the key.

```typescript
// Set key via meta tag: <meta name="beacio-key" content="wbl_xxxxx">
import '@beacio/core/auto'
```

--------------------------------

### Importing profiles from the root barrel

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/src/profiles/AGENTS.md

Demonstrates how to import profiles directly from the root package.

```typescript
import { HeartRateProfile, parseHeartRate } from '@beacio/core';
```

--------------------------------

### on('disconnected' | 'queue-overflow' | 'subscription-lost' | 'reconnected', listener): void

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Listens for device lifecycle events.

```APIDOC
## on('disconnected' | 'queue-overflow' | 'subscription-lost' | 'reconnected', listener): void

### Description
Listens for device lifecycle events.

### Method
on

### Parameters
- **event** (string) - Required - The event name: 'disconnected', 'queue-overflow', 'subscription-lost', or 'reconnected'.
- **listener** (function) - Required - The event listener.

### Returns
- **void** - No return value.
```

--------------------------------

### BeacioError: suggestion: string

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Human-readable recovery hint.

```APIDOC
## BeacioError: suggestion: string

### Description
Human-readable recovery hint.

### Type
- **string** - The recovery suggestion.
```

--------------------------------

### Publishing Commands for Maintainers

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/react-sdk/README.md

Commands used to build the package, verify tarball contents, and publish to npm. Use the beta tag for prerelease versions.

```bash
npm run build          # tsup: ESM + CJS + type declarations
npm pack --dry-run     # verify tarball contents
npm publish --access public            # production release
npm publish --access public --tag beta # prerelease
```

--------------------------------

### Scan and connect with beacio

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/skill/SKILL.md

Create a Beacio instance, request a device with a heart_rate service filter, and connect.

```typescript
import { beacio } from '@beacio/core'

const ble = new Beacio()
const device = await ble.requestDevice({
  filters: [{ services: ['heart_rate'] }]
})
await device.connect()
```

--------------------------------

### ble.requestDevice(options?)

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/AGENTS.md

Opens the device picker and returns a BeacioDevice. Use this to select a Bluetooth device to connect to.

```APIDOC
## ble.requestDevice(options?)

### Description
Opens the device picker and returns a BeacioDevice. Use this to select a Bluetooth device to connect to.

### Method
requestDevice

### Parameters
- **options** (object) - Optional - Options for device filtering, e.g., filters with services.

### Returns
- **BeacioDevice** - The selected device wrapper.

### Example
```typescript
const device = await ble.requestDevice({ filters: [{ services: ['heart_rate'] }] });
```
```

--------------------------------

### Auto-polyfill navigator.bluetooth with @beacio/core/auto

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/AGENTS.md

Import the auto entry point to enable navigator.bluetooth on Safari iOS. No-op on browsers with native support like Chrome/Edge.

```typescript
import '@beacio/core/auto';
// navigator.bluetooth now works on Safari iOS. No-op on Chrome/Edge (native support).
```

--------------------------------

### connectWithRetry(options?): Promise<void>

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/README.md

Connects with retry/backoff using SDK retry metadata.

```APIDOC
## connectWithRetry(options?): Promise<void>

### Description
Connects with retry/backoff using SDK retry metadata.

### Method
connectWithRetry

### Parameters
- **options** (object) - Optional - Options for the retry behavior.

### Returns
- **Promise<void>** - A promise that resolves when the connection is established.
```

--------------------------------

### Background Sync Namespace

Source: https://github.com/wklm/beacio-sdk/wiki/Background-Sync

The entry point for the background sync functionality.

```typescript
navigator.webble.backgroundSync
```

--------------------------------

### backgroundSync.requestBackgroundConnection(options)

Source: https://github.com/wklm/beacio-sdk/blob/main/webble-sdk-consumer/references/api-reference.md

Requests a background connection. Returns a promise resolving to a BackgroundRegistration.

```APIDOC
## backgroundSync.requestBackgroundConnection(options)

### Description
Requests a background connection.

### Method
requestBackgroundConnection

### Parameters
- **options** (object) - Required - Options for the background connection.

### Response
Returns a Promise<BackgroundRegistration>.
```

--------------------------------

### Initialize beacio detection

Source: https://github.com/wklm/beacio-sdk/blob/main/packages/core/detect/SKILL.md

Use this snippet to initialize the beacio detection module, which is required for iOS Safari extension detection.

```typescript
import { initBeacio } from '@beacio/core/detect'
initBeacio({})
```