One typed client, in the browser or on the API.

Start in the browser, ship against the API.

@safe-edge/sdk has one method per operation in the contracts' operations table, so inputs and results are typed from the contract.

createSafeEdgeClient takes a transport. memory runs the Safe Edge core in the page on the labelled Elmina seed; http calls the v1 API. A screen written against the shared SafeEdgeClient type runs on either.

import { createSafeEdgeClient, elminaSeed } from '@safe-edge/sdk'

const demo = createSafeEdgeClient({ transport: 'memory', userId: 'usr_manager' })
const segments = await demo.listSegments()
const s1 = await demo.getSegment({ params: { id: elminaSeed.story.s1.segmentId } })
const open = await demo.listFindings({ query: { status: 'open' } })

import { createSafeEdgeClient } from '@safe-edge/sdk'

const token = '<your bearer token>'
const api = createSafeEdgeClient({ transport: 'http', baseUrl: 'http://localhost:3000/v1', token })
const expiring = await api.listPasses({ query: { state: 'expiring', expiresWithinDays: 30 } })

Every seeded record carries simulated: true and source: 'fixture'. Show the label on screen.

A v1 REST API, described in OpenAPI 3.1.

JSON under /v1, generated from the Zod contracts in packages/contracts: 65 operations, each with the roles allowed to call it.

• Bearer tokens carry a role. Demo tokens work only in demo mode; the API rejects them.
• Every write accepts an Idempotency-Key header. A retry with the key within 24 hours replays the first answer. The SDK sends a fresh key on every write; pass your own to retry safely.
• A refused action returns 403 with the policy rule that blocked it.
• Responses are checked against the contract on the client too.

In the OpenAPI document, x-safe-edge-roles lists the roles allowed and x-safe-edge-agent-scope names the scope an agent token needs; when it is absent, agents are refused.

import { SafeEdgeDeniedError } from '@safe-edge/sdk'

try {
  await demo.as('usr_agent').submitWorkOrder({
    params: { id: 'wo_1' },
    body: { installerUserId: 'usr_installer', dueAt: '2026-10-21T08:00:00.000Z' }
  })
} catch (error) {
  if (error instanceof SafeEdgeDeniedError) console.log(error.rule) // 'agents_draft_only'
  else throw error
}

Roles for people, scopes for the agent.

The server checks the role, or the agent's scope, on every request.

Policy lives in the core, so the server and the in-browser demo enforce the same rules. The person who records a repair cannot accept it, and only an accepted re-test by a reviewer makes a pass valid. See what the agent can and cannot do.

Thirteen events, as CloudEvents 1.0.

Every state change the loop cares about is an event with source safe-edge://townships/{id} and subject segments/{id}.

Payloads carry IDs and simulated, never images. Consumers fetch records and evidence through the API. The AsyncAPI document is in packages/contracts.

Signed webhooks, or a live stream.

An integrator registers a webhook for the event types it needs. A screen can read the same events as server-sent events from GET /v1/events.

• Deliveries are signed per Standard Webhooks: every one carries webhook-id, webhook-timestamp and webhook-signature, a base64 HMAC-SHA256 of the ID, the timestamp and the raw body.
• The signing secret (whsec_…) appears only in the registration's response.
• A webhook's origin must be on the API's allowlist, SAFE_EDGE_WEBHOOK_ORIGINS, checked at registration and again before every delivery.
• Network errors, timeouts, 408, 429 and 5xx are retried; each webhook keeps its latest 20 failures.
• The stream has no replay: events from before it opened are not sent.

const hook = await api.registerWebhook({
  body: { url: 'https://example.com/safe-edge', eventTypes: ['edge.pass.suspended.v1', 'edge.pass.issued.v1'] }
})
// hook.secret signs every delivery; this response is the only place it appears

const events = await api.streamEvents() // subscribed once this resolves
for await (const event of events) console.log(event.type, event.subject)

No vendor lock-in for drones or work orders.

Provider adapters keep the core independent of any drone vendor or work-order system.

An MCP server for AI assistants.

Claude Code or Claude Desktop can read, propose and draft through the MCP server, with the same narrow scopes as the built-in agent.

The server runs over stdio and calls the v1 API with the agent's token, so the API enforces every scope and state rule. It reads the API's address and the token from your environment; the token has no default.

{
  "mcpServers": {
    "safe-edge": {
      "type": "stdio",
      "command": "bun",
      "args": ["apps/mcp/src/index.ts"],
      "env": {
        "SAFE_EDGE_API_URL": "${SAFE_EDGE_API_URL:-http://localhost:3000/v1}",
        "SAFE_EDGE_AGENT_TOKEN": "${SAFE_EDGE_AGENT_TOKEN}"
      }
    }
  }
}

The eight tools, and what none of them can do, are on the agent page.