@wklm/detect

@wklm/detect

Detect the iOSWebBLE Safari extension on iOS. Auto-show an install banner when the extension is not found. No-op on all other platforms.

Install

npm install @wklm/detect

Usage

import { initIOSWebBLE } from '@wklm/detect';

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

For React/Next.js:

import { IOSWebBLEProvider } from '@wklm/detect/react';

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

For plain HTML (no bundler):

<script src="https://ioswebble.com/webble.js"></script>

Standalone usage (no React, no profiles)

You can use @wklm/detect with @wklm/core only -- no React, no profiles package needed. Together they are ~6KB gzipped.

import { initIOSWebBLE, isIOSSafari } from '@wklm/detect';
import { WebBLE, WebBLEError } from '@wklm/core';

// 1. On iOS Safari, detect the extension and prompt install if missing
if (isIOSSafari()) {
  await initIOSWebBLE({
    operatorName: 'MyApp',
    banner: { mode: 'sheet' },
    onReady: () => console.log('Extension ready'),
    onNotInstalled: () => {
      // Banner is shown automatically; you can also add custom handling here
      console.log('Extension not installed -- banner shown');
    },
  });
}

// 2. Scan and connect (works on iOS Safari + Chrome + Edge)
const ble = new WebBLE();
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));
  await device.disconnect();
} catch (err) {
  if (err instanceof WebBLEError) {
    console.error(err.code, err.suggestion);
  }
}

What each package provides

Package	Purpose	Size
@wklm/core	BLE scanning, connecting, GATT read/write/subscribe	~4KB gzip
@wklm/detect	iOS extension detection + install banner	~2KB gzip
@wklm/profiles	Typed BLE profiles (heart rate, battery, etc.)	Optional
@wklm/react-sdk	React hooks (useDevice, useCharacteristic)	Optional

API

• initIOSWebBLE(options) -- detect extension, show banner, fire callbacks
• isIOSSafari() -- returns true on iOS Safari
• isExtensionInstalled() -- async check for the extension marker
• showInstallBanner(options) / removeInstallBanner() -- manual banner control

initIOSWebBLE options

Option	Type	Description
key	string	Optional API key for analytics
operatorName	string	Your app name (shown in install banner)
banner.mode	'sheet' | 'bar'	Banner display style
banner.position	string	Banner position
banner.text	string	Custom banner text
banner.buttonText	string	Custom button label
banner.appStoreUrl	string	Override App Store link
banner.dismissDays	number	Days before banner re-appears after dismiss
banner.style	object	Custom CSS styles
onReady	() => void	Called when extension is detected and active
onNotInstalled	() => void	Called when extension is not found

AI agent integration

MCP server for coding agents (Claude Code, Cursor, Copilot):

npx -y @wklm/mcp

Full SDK reference for LLM context: https://ioswebble.com/llms-full.txt

Two scopes

The @wklm/* packages (core, profiles, react) are the cross-browser BLE SDK -- they work on any platform with Web Bluetooth support (Chrome, Edge, iOS Safari via the extension). The @wklm/* packages (detect, cli, mcp, skill) handle iOS-specific extension detection, install prompts, and agent tooling. Use both together for full iOS Safari coverage.