Sanctuary Edge SDK (@adriftdev/sanctuary-edge-sdk)

A powerful, zero-configuration networking SDK for Sanctuary OS that abstracts complex network failovers between the Cloud and localized Edge clusters.

Designed specifically for drone operators and field UIs, the SDK will automatically reroute fetch requests and WebSocket connections to a localized Edge gateway if the main internet/cloud connection drops.

Features

• Transparent Network Interceptor: Wraps native fetch API. You call api.fetch('/drones') and the SDK decides whether to route it to the Cloud or local Edge server.
• Resilient WebSockets: The createEdgeSocket proxy automatically handles reconnects, failovers, and re-subscribes to topics if the socket drops.
• SolidJS Integration: Ships with first-class primitives (EdgeProvider, useEdge, useEdgeSocket) making your UI seamlessly reactive to connection changes.
• Offline Caching: Includes a Service Worker script that caches the UI bundle, allowing the dashboard to reload even during complete internet outages.

Installation

npm install @adriftdev/sanctuary-edge-sdk
# or
pnpm add @adriftdev/sanctuary-edge-sdk

Quick Start (SolidJS)

1. Setup the Provider

Wrap your application in the EdgeProvider. You'll supply the primary Cloud URL and an array of local Edge backup URLs.

// index.tsx
import { render } from 'solid-js/web';
import { EdgeProvider } from '@adriftdev/sanctuary-edge-sdk';
import App from './App';

render(() => (
  <EdgeProvider
    primaryUrl="https://cloud.sanctuary-os.com"
    clusterUrls={[
      "http://192.168.1.50:8080", // Edge Node 1 (Command Vehicle)
      "http://192.168.1.51:8080"  // Edge Node 2 (Backup)
    ]}
    onStatusChange={(status) => console.log('Network Status:', status)}
  >
    <App />
  </EdgeProvider>
), document.getElementById('root')!);

2. Making REST API Calls

Inside your components, use the useEdge() hook to access the auto-failing-over API.

// App.tsx
import { createResource, Show } from 'solid-js';
import { useEdge } from '@adriftdev/sanctuary-edge-sdk';

export default function App() {
  const { api, connection } = useEdge();

  // The SDK automatically routes this to the working cluster
  const fetchDrones = async () => {
    const response = await api.fetch('/api/v1/drones/status');
    return response.json();
  };

  const [drones] = createResource(fetchDrones);

  return (
    <div>
      <header class={connection() === 'EDGE' ? 'bg-orange-500' : 'bg-green-500'}>
        Status: {connection()} {/* will output CLOUD, EDGE, or OFFLINE */}
      </header>
      
      <Show when={drones()}>
        <ul>
          {drones().map(drone => <li>{drone.id}: {drone.battery}%</li>)}
        </ul>
      </Show>
    </div>
  );
}

3. Using Resilient WebSockets

If your app uses streaming telemetry (e.g. Valkey Pub/Sub over WebSockets), the SDK provides a robust Socket proxy.

Define your socket endpoints and hook outside the component tree (or context) to keep the connection alive across routes.

// telemetry.ts
import { createEdgeSocket } from '@adriftdev/sanctuary-edge-sdk';

// Will try Cloud first, then fallback to Edge automatically
export const useTelemetry = createEdgeSocket([
    "wss://cloud.sanctuary-os.com/valkey",
    "ws://192.168.1.50:8080/valkey"
]);

Then use the hook inside your components:

// DroneMap.tsx
import { createEffect } from 'solid-js';
import { useTelemetry } from './telemetry';

export default function DroneMap() {
    const { data, connected, subscribe, unsubscribe } = useTelemetry();

    createEffect(() => {
        subscribe('drone:location'); // Translates to {"type": "sub", "topic": "drone:location"}
        
        return () => unsubscribe('drone:location');
    });

    return (
        <div>
            <h2>WebSocket Status: {connected() ? '🟢 LIVE' : '🔴 RECONNECTING'}</h2>
            
            {/* data is a reactive store keyed by topic */}
            <p>Latest Location: {JSON.stringify(data['drone:location'])}</p>
        </div>
    );
}

4. Enabling the Offline Service Worker

To ensure your UI bundle loads even when you disconnect from the internet and refresh the page, register the Service Worker in your index.html or entry file.

The SDK distributes the worker logic. Depending on your bundler (like Vite), you can import the worker script directly or serve it statically.

For Vite, create a sw.js in your public folder and import the SDK's worker:

// public/sw.js
importScripts('/node_modules/@adriftdev/sanctuary-edge-sdk/dist/ServiceWorker.js');

Then register it in your index.tsx:

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js').then(() => {
    console.log('Sanctuary Offline Caching enabled.');
  });
}