Site Mills API Reference

Overview

Handler code runs inside the Site Mills Sandbox Runtime. Browser code calls those handlers through generated API wrappers or the backend bridge. Realtime and room APIs are separate websocket-based channels for low-latency interactions.

Sandbox Runtime SDK (Handler Context)

The handler context is available as the first argument in backend routes: export async function myRoute(ctx, params).

export async function listOrders(ctx, params) {
  const limit = Math.min(Number(params?.limit ?? 20), 100);

  const orders = await ctx.db
    .collection('orders')
    .find({})
    .sort({ createdAt: -1 })
    .limit(limit);

  await ctx.metrics.track('orders_listed', {
    limit: String(limit),
    userId: ctx.user?.id ?? 'anonymous'
  });

  return { orders };
}

Complete Sandbox Runtime API Surface

This matrix is based on the runtime bootstrap + integration manifest currently wired in the Site Mills Sandbox Runtime. It covers core ctx APIs plus all registered integration namespaces.

Integration namespace rows are generated during build from integration manifests and provider sources to prevent docs drift.

AI Workflows (ctx.ai)

AI workflows are asynchronous. You enqueue work from your handler and receive results in a callback route.

export async function summarizeTicket(ctx, params) {
  const job = await ctx.ai.oneShot({
    prompt: `Summarize this ticket in 5 bullets: ${params.ticketText}`,
    callbackRoute: 'handleTicketSummary',
    model: 'gemini-3-flash-lite',
    callbackContext: { ticketId: params.ticketId },
    fileIds: params.attachmentFileIds || []
  });

  return { queued: true, workflowId: job.workflowId };
}

Queue Workflows (ctx.queue)

Queue workflows let handlers offload async work to the runtime message queue. Messages are retried with backoff, can be explicitly acked/no-acked by the handler result, and move to dead-letter state when retries are exhausted or a handler requests terminal no-ack.

export async function queueOrderReceipt(ctx, params) {
  const queued = await ctx.queue.enqueue({
    queueName: 'orders.receipts',
    handlerRoute: 'handlers/queue_handlers.processOrderReceipt',
    payload: {
      orderId: params.orderId,
      email: params.email
    },
    maxRetries: 3,
    retryDelayMs: 5000
  });

  return { queued: true, messageId: queued.messageId };
}

export async function processOrderReceipt(ctx, message) {
  try {
    await ctx.email.send({
      to: message.payload.email,
      subject: 'Order receipt',
      body: `Order ${message.payload.orderId} processed.`
    });

    return ctx.queue.ack({ delivered: true });
  } catch (error) {
    return ctx.queue.nack({
      requeue: true,
      retryDelayMs: 30000,
      reason: 'email_provider_error'
    });
  }
}

Storage and Uploads (ctx.storage)

Storage supports both direct base64 uploads from handlers and staged upload claims from frontend multipart uploads.

// 1) Frontend uploads multipart file to POST /api/v1/upload and gets fileId
// 2) Handler claims it into managed storage
export async function attachAvatar(ctx, params) {
  const claimed = await ctx.storage.claimUpload(params.fileId, { ttlSeconds: 86400 });

  await ctx.db.collection('profiles').updateOne(
    { _id: params.userId },
    { $set: { avatarUrl: claimed.url, avatarFileId: claimed.id } },
    { upsert: true }
  );

  return { avatarUrl: claimed.url, fileId: claimed.id };
}

Other Integration Namespaces

Additional runtime namespaces available in the Site Mills Sandbox Runtime.

Sandbox Runtime SDK (Jobs Context)

Scheduled/manual jobs are defined in server/jobs.ts and use a job-specific context. Jobs are headless, so user/session fields are not available.

export const jobs = {
  rollupDailyOrders: async (ctx, params) => {
    const since = params?.since || ctx.previousRun?.cursor;

    const rows = await ctx.db.collection('orders').find(
      since ? { createdAt: { $gte: since } } : {}
    );

    await ctx.db.collection('order_rollups').insertOne({
      runId: ctx.runId,
      count: rows.length,
      generatedAt: new Date().toISOString()
    });

    await ctx.state.setCursor(new Date().toISOString());
    await ctx.metrics.track('orders_rollup_completed', { count: String(rows.length) });
  }
};

Frontend API (Browser Code)

Frontend code typically lives under public/ and uses wrappers from public/api and generated stubs under public/stubs.

window.auth

Provided by the auth client bootstrap, this API handles login state and OAuth redirects.

const user = await window.auth.getCurrentUser();
if (!user?.isAuthenticated) {
  window.auth.login('/dashboard');
}

window.backend.call

Backend handlers are invoked by route name from frontend code. This bridge is used by generated stubs and direct frontend calls.

Route names map to exported handler names. Payload is JSON-serializable and passed as the handler's params argument.

const profile = await window.backend.call('getCurrentUser', {});
const leaderboard = await window.backend.call('getLeaderboard', { limit: 25 });

Frontend Upload Endpoint

For browser file uploads, use the runtime multipart endpoint and pass the returned fileId to a backend handler that calls ctx.storage.claimUpload(...).

// Browser example
const formData = new FormData();
formData.append('file', selectedFile);

const uploadRes = await fetch('/api/v1/upload', {
  method: 'POST',
  credentials: 'include',
  body: formData
});

const uploaded = await uploadRes.json();
// uploaded.fileId -> pass to backend handler for claimUpload
await window.backend.call('attachAvatar', { fileId: uploaded.fileId, userId });

UserService Wrapper

The seeded frontend includes public/api/user-service.ts, which wraps auth and user retrieval for app code.

import { UserService } from './api/user-service.js';

const unsubscribe = UserService.onUserChange((user) => {
  console.log('Auth state changed:', user);
});

// Later:
unsubscribe();

Realtime Client

Use public/api/realtime-client.js for channel/event messaging over websocket.

import { connect, subscribe, on, send } from './api/realtime-client.js';

await connect();
subscribe('chat');

on('chat', 'newMessage', (payload) => {
  console.log('Incoming message:', payload);
});

send('chat', 'sendMessage', { text: 'hello' });

P2P Client

Use public/api/p2p-client.js for browser-managed WebRTC sessions (voice/video/data channels).

import {
  createP2PSession,
  createPeerConnection,
  attachLocalMedia
} from './api/p2p-client.js';

const session = await createP2PSession({ sessionId: 'call_alpha' });
const ice = await session.requestIceServers();

const pc = createPeerConnection(ice, {
  onIceCandidate: (candidate) => session.sendSignal('ice-candidate', candidate)
});

await attachLocalMedia(pc, { audio: true, video: true });

Room Client

Use public/api/room-client.js for authoritative room state (multiplayer/game loops).

import { joinRoom } from './api/room-client.js';

const room = await joinRoom('arena', { roomId: 'auto' });

room.onStateChange((state) => {
  renderGame(state);
});

room.onMessage('gameOver', (data) => {
  console.log('Game over:', data);
});

room.send('input', { keys: ['ArrowUp', 'Space'] });

Quick Full-Stack Example

Typical flow: frontend calls a handler, handler uses the sandbox runtime SDK, frontend renders result.

// server/handlers/profile.ts
export async function getProfile(ctx, params) {
  if (!ctx.user?.isAuthenticated) {
    return { profile: null };
  }

  const profile = await ctx.db.collection('profiles').findOne({ email: ctx.user.email });
  return { profile: profile || { email: ctx.user.email } };
}

// public/views/profile-view.tsx
const result = await window.backend.call('getProfile', {});
setProfile(result?.profile ?? null);