KaiOS TypeScript Type Declarations

TypeScript type definitions for KaiOS. Currently supports KaiOS v2.5, the successor to Firefox OS also known as Boot2Gecko (B2G).

Overview

This package provides comprehensive TypeScript type definitions for the proprietary Web APIs available in KaiOS. These APIs give access to telephony, SMS, Bluetooth, WiFi, contacts, camera, and more.

Note: Most of these APIs are non-standard and proprietary to KaiOS platform. Many require specific permissions in your app's manifest (manifest.webapp) and are restricted to certain app types (i.e. privileged or certified).

Documentation

For more information on KaiOS development, see the KaiOS Developer Portal, KaiOS.dev blog, and BananaHackers website.

Installation

NPM

npm install --save-dev kaios-types

PNPM

pnpm add kaios-types --save-dev

Bun

bun add --development kaios-types

Usage

Option 1: Global Type Declarations (Recommended)

Add the types to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["kaios-types"]
  }
}

Or use a triple-slash directive at the top of your TypeScript files:

/// <reference types="kaios-types" />

// Now KaiOS APIs are available with full type checking
const settings = navigator.mozSettings;
settings.createLock().set({ 'wifi.enabled': true });

Option 2: Modular Imports

You can also import specific types directly:

import { MozActivity, ActivityOptions } from 'kaios-types/apps/moz-activity';
import { BluetoothManager } from 'kaios-types/bluetooth/bluetooth-manager';

const activity = new MozActivity({
  name: 'pick',
  data: { type: 'image/jpeg' }
});

API Categories

📱 Apps & Activities

• Applications - Install, manage, and launch apps
• Activities - Inter-app communication and task delegation
• Push Notifications - SimplePush for notifications
• Downloads - File download management

📡 Connectivity

• Telephony - Make and receive phone calls
• SMS/MMS - Send and receive messages
• Mobile Network - Network status, signal strength, roaming
• WiFi - Connect to networks, WiFi Direct
• Bluetooth - Full Bluetooth stack with GATT support
• NFC - Near Field Communication and secure elements
• TCP/UDP Sockets - Low-level network communication

🎬 Media & Hardware

• Camera - Photo and video capture
• FM Radio - FM tuner control
• TV - TV tuner functionality
• Volume - System volume management

💾 Data & Storage

• Contacts - Address book management
• DataStore - Inter-app data sharing
• Device Storage - File system access (sdcard, pictures, music, videos)

⚙️ System

• Settings - Read and modify system settings
• Power - Screen brightness, power off, reboot
• Alarms - Schedule app wake-ups
• Wake Locks - Prevent device sleep
• Time - Set system time
• Permissions - Manage app permissions

Examples

Send an SMS

const sms = navigator.mozMobileMessage;
const request = sms.send('+1234567890', 'Hello from KaiOS!');

request.onsuccess = () => {
  console.log('SMS sent successfully');
};

request.onerror = () => {
  console.error('Failed to send SMS:', request.error);
};

Control WiFi

const wifi = navigator.mozWifiManager;

// Enable WiFi
wifi.setWifiEnabled(true);

// Scan for networks
const request = wifi.getNetworks();
request.onsuccess = () => {
  const networks = request.result;
  networks.forEach((network) => {
    console.log(`Found network: ${network.ssid}`);
  });
};

Access Contacts

const contacts = navigator.mozContacts;

const request = contacts.find({
  filterBy: ['givenName'],
  filterValue: 'John',
  filterOp: 'contains'
});

request.onsuccess = () => {
  const cursor = request.result;
  cursor.forEach((contact) => {
    console.log(`Contact: ${contact.givenName} ${contact.familyName}`);
  });
};

Adjust Volume

const volumeManager = navigator.volumeManager;

// Increase volume
volumeManager.requestUp();

// Decrease volume
volumeManager.requestDown();

// Show volume UI
volumeManager.requestShow();

Compatibility

• KaiOS Version: 2.5
• TypeScript Version: 5.0+
• Based on: Mozilla Boot to Gecko (B2G) / Firefox OS APIs

API Documentation

For detailed API documentation and usage guidelines, see:

• API_OVERVIEW.md - Comprehensive overview of all API categories
• KaiOS Developer Portal
• KaiOS.dev Blog
• BananaHackers

License

Apache License 2.0

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.