@dotrly/sdk

Complete documentation for building Relay Apps with @dotrly/sdk.

Textural Tiers

The SDK now uses Textural tier naming for capability levels:

• Silk
• Satin
• Velvet
• Cashmere
• Gossamer

Silk is the enterprise-safe, minimal layer. It includes only the essentials needed to talk to the Helper securely (auth, signing, WS tokens). It deliberately excludes UI components.

Silk Usage

import { createHelperClient } from '@dotrly/sdk/silk';

When you use @dotrly/sdk/silk, you are opting into a minimal, non-UI surface area focused on helper capabilities (filesystem, git, search, terminal, ollama, projects). OS-level features such as system control, app lifecycle, system/platform config, and OTA are intentionally excluded.

Silk requires the Relay Shell runtime. It will throw if the shell is not present.

Features

• Platform Components: Keyboard avoiding views, safe area support, haptic feedback
• UI Components: Complete component library with 40+ modern components
• Modern Hooks: Device sensors, notifications, clipboard, camera access
• TypeScript: Full TypeScript support with comprehensive type definitions
• Fast: Built with modern React and optimized for performance
• Small: Tree-shakable with minimal bundle impact

Installation

Install the SDK in your Relay App project.

npm install @dotrly/sdk

Peer dependencies required:

npm install react@^19.0.0 react-dom@^19.0.0 tailwindcss@>=3

Platform & UI

Core components for handling safe areas and device capabilities.

SafeAreaProvider

Essential provider that handles notch and safe area insets. Wrap your app in this.

import { SafeAreaProvider } from '@dotrly/sdk';

export default function App() {
  return (
    <SafeAreaProvider>
      <YourApp />
    </SafeAreaProvider>
  );
}

usePlatform()

Get information about the current device environment.

import { usePlatform } from '@dotrly/sdk';

const { os, isMobile } = usePlatform();

if (isMobile) {
  // Render mobile layout
}

UI Components

Complete component library with 40+ modern components including Button, Card, Dialog, Input, Select, Tabs, etc.

import {
  Button,
  Card,
  Dialog,
  Input,
  Select,
  Tabs,
  // ... and 30+ more components
} from '@dotrly/sdk';

Notifications

Send system notifications and manage app badges. The SDK automatically uses your app's icon if available.

useNotifications()

import { useNotifications } from '@dotrly/sdk';

export function NotificationDemo() {
  const {
    requestPermission,
    sendNotification,
    setBadge,
    permission
  } = useNotifications();

  const handleNotify = async () => {
    // 1. Check/Request Permission
    if (permission !== 'granted') {
      await requestPermission();
    }

    // 2. Send Notification
    // Note: Automatically uses app icon from <link rel="icon">
    sendNotification('New Message', {
      body: 'You have a new message from Relay',
      tag: 'message-1' // Prevents duplicates
    });

    // 3. Update App Badge
    await setBadge(1);
  };
}

Clipboard

Access the system clipboard with built-in history management.

useClipboard()

import { useClipboard } from '@dotrly/sdk';

export function ClipboardDemo() {
  const {
    copyText,
    readText,
    history
  } = useClipboard();

  const handleCopy = async () => {
    await copyText('Copied from Relay!');
  };

  const handlePaste = async () => {
    const text = await readText();
    console.log('Clipboard content:', text);
  };

  // Access history
  // history = [{ type: 'text', content: '...', timestamp: 123 }, ...]
}

Geolocation

Access device location and calculate distances.

useGeolocation()

import { useGeolocation } from '@dotrly/sdk';

export function LocationDemo() {
  const {
    latitude,
    longitude,
    loading,
    error,
    getLocation
  } = useGeolocation();

  useEffect(() => {
    getLocation();
  }, []);

  if (loading) return <div>Locating...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      Position: {latitude}, {longitude}
    </div>
  );
}

Camera Access

import { useCamera } from '@dotrly/sdk';

function CameraExample() {
  const { devices, startCamera, stopCamera, capturePhoto } = useCamera();

  return (
    <div>
      <select onChange={(e) => startCamera(e.target.value)}>
        <option>Select Camera</option>
        {devices.map(device => (
          <option key={device.deviceId} value={device.deviceId}>
            {device.label}
          </option>
        ))}
      </select>
      <Button onClick={capturePhoto}>Take Photo</Button>
      <Button onClick={stopCamera}>Stop Camera</Button>
    </div>
  );
}

Platform Detection

import {
  useColorScheme,
  useSafeArea,
  useAppState,
  useStatusBar
} from '@dotrly/sdk';

function PlatformExample() {
  const colorScheme = useColorScheme();
  const safeArea = useSafeArea();
  const appState = useAppState();

  // Set status bar color based on theme
  useStatusBar(colorScheme === 'dark' ? '#000000' : '#ffffff');

  return (
    <div>
      <p>Theme: {colorScheme}</p>
      <p>App State: {appState}</p>
      <p>Safe Area Top: {safeArea.top}px</p>
    </div>
  );
}

Platform Hooks

Additional platform utilities for device interaction.

useKeyboard()

Track virtual keyboard state for mobile devices.

import { useKeyboard } from '@dotrly/sdk';

const keyboard = useKeyboard();

// Adjust layout based on keyboard state
<div style={{
  paddingBottom: keyboard.isOpen ? keyboard.height : 0
}}>
  <Input placeholder="Type here..." />
</div>

useBackHandler()

Handle back navigation with custom behavior.

import { useBackHandler } from '@dotrly/sdk';

useBackHandler(() => {
  // Return true to prevent default back behavior
  const shouldPrevent = confirm('Are you sure you want to go back?');
  return shouldPrevent;
});

Styling

The SDK uses Tailwind CSS for styling. Make sure your tailwind.config.js includes:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@dotrly/sdk/dist/**/*.{js,ts,jsx,tsx}'
  ],
  // ... rest of your config
}

API Reference

Platform Hooks

• useSafeArea() - Get device safe area insets
• useColorScheme() - Get current color scheme preference
• useStatusBar(color) - Control status bar appearance
• useBackHandler(handler) - Handle back navigation
• useAppState() - Track app foreground/background state
• useKeyboard() - Track virtual keyboard state
• usePlatform() - Get device environment information

Device Hooks

• useNotifications() - Send and schedule notifications
• useClipboard() - Read/write clipboard content
• useGeolocation() - Access device location
• useCamera() - Camera and media capture

UI Components

• 40+ components including Button, Card, Dialog, Input, Select, Tabs, etc.

Links

• Relay Platform - Learn more about Relay
• Documentation - Full API documentation
• Examples - Example apps
• Issues - Report bugs

License

MIT