CampusSDK

CampusSDK is the typed capability surface between an installed application and CampusOS. The canonical browser client is createCampusApp(); it exposes named groups rather than one flat RPC client.

Canonical browser entry

import { createCampusApp } from '/assets/campus_sdk/campus_browser.js'

const campus = createCampusApp({
  appId: 'example-notes',
  pullToRefresh: true,
})

renderApp()
await campus.ready({ title: 'Notes' })

Construction is synchronous. Each capability call waits for the trusted launch exchange when necessary. Drawing does not wait for a backend or an SDK-owned hydration phase.

CampusOptions accepts appId, expectedAppId, window, storageKey, and pullToRefresh.

Browser SDK surface

Lifecycle, shell, and private backend

Surface	Current methods	Contract
App lifecycle	ready({ title? }), fail(error), close()	Report a usable interface, expose structured startup failure, or close the app.
shell	insets, onInsetsChanged, onRefresh, setOverlayOpen, dismiss	Interact with trusted shell chrome without reading or mutating the parent DOM.
backend	availability, state, fetch, fetchJson, openSocket, openEventStream, warm, acquireLease, renewLease, releaseLease, on	Reach only this installation’s private backend through its scoped Gateway capability.

Backend state is absent, not-installed, stopped, queued, starting, running, connecting, ready, degraded, or unavailable. Availability also reports runtimeMode, node configuration/online state, and whether funding is required and ready.

const availability = await campus.backend.availability()

if (availability.available) {
  const report = await campus.backend.fetchJson('/v1/report', {
    method: 'POST',
    body: { range: 'week' },
  })
}

const stop = campus.backend.on('disconnected', ({ state, error }) => {
  showConnectionState({ state, error })
})

Apps, account, authority, and settings

Surface	Current methods	Contract
apps	list, search, get, create, customize, activateCustomization, restoreOriginal, install, purchase, uninstall, open, start, warm, pause, stop, order.get/set, pins.get/set	Discover and manage account-visible Campus Apps through trusted lifecycle and installation flows.
appearance	get, update	Read or update scope, theme, wallpaper family, and wallpaper selection.
account	current, identity	Read public Campus name/address or the installation-bound account identity.
access	list, status, grant, revoke	Manage the exact Campus users admitted to this app.
permissions	catalog, current, check, request, revoke, openManager, manager, setForApp, close	Inspect and request bounded grants. Approval remains in trusted shell UI.
settings	snapshot, current, request, background/warm settings, permission/exposure/wallet/MCP/intelligence helpers, identity, schedule helpers	Request changes to lifecycle, routes, authority, identity, budgets, and schedules.
secrets	bind, fetch	Bind and use a protected outbound credential without returning its plaintext.
payments	propose, authorizations.*	Stage exact financial intent and manage existing bounded authorizations.

if (!await campus.permissions.check('files.read', 'owner:*')) {
  await campus.permissions.request({
    permissions: [{ id: 'files.read', resources: ['owner:*'] }],
    reason: 'Open the file selected by the owner.',
  })
}

await campus.secrets.bind('github-token', {
  reason: 'Publish the selected repository.',
})
const response = await campus.secrets.fetch('github-token', '/user')

Data, storage, and cryptography

Surface	Current methods	Contract
kv(namespace, { scope })	get, set, delete, list	Versioned small JSON. account scope is synchronized; device stays in this browser.
files	list, get, create, write, read, setPermissions, delete	Logical large/binary objects with explicit owner, protection, and permission metadata.
encryptedContent	identity/key preparation; collections, entries, objects, versions, imports, sinks, invitations, members, changes	End-to-end encrypted collaborative content graph used by products such as Drive.
crypto.key(namespace)	encrypt, decrypt, signDomainSeparated, verifyDomainSeparated, grant, rotate, revokeGrant	Scoped key handle; raw account keys never leave the trusted boundary.
crypto.recipients(namespace)	prepare, sealTo, open	Recipient-bound encryption using Campus address, app, namespace, domain, and context.
crypto.sealedAssets(namespace)	sealTo, open, acknowledge, delete	Chunked encrypted asset delivery.
crypto.commitments(namespace)	prepare, sign, verify	Domain-separated signed commitments.

const preferences = campus.kv('preferences')
const record = await preferences.get('theme')
await preferences.set('theme', 'dark', {
  ifVersion: record?.version ?? 0,
})

const file = await campus.files.create('report.json', JSON.stringify(report), {
  contentType: 'application/json',
  owner: 'user',
  protection: { mode: 'platform-readable', service: 'example-notes', purpose: 'report' },
})

const recipients = campus.crypto.recipients('messages', {
  domain: 'example.message',
})
const envelope = await recipients.sealTo('bob.campus.host', {
  text: 'hello',
})

Do not put large values in KV. Files is not automatically end-to-end encrypted; choose explicit file protection or use encryptedContent when endpoints must own plaintext.

Events, communication, and discovery

Surface	Current methods	Contract
accountEvents	subscribe, connect; stream receive, events, ack, close, abort	Realtime or durable account-scoped events. Durable delivery is at-least-once and explicitly acknowledged.
deliveries	send, list, get, acknowledge, cancel	TTL-bound opaque envelope delivery to an exact Campus address, app, and channel.
rendezvous	create, list, get, messages, send, close	Short-lived ordered coordination with an exact account/app peer.
notifications	snapshot, list, markRead, markAllRead, activate, system/web-push helpers, publish	Account notifications with optional trusted presentation actions.
schedules	snapshot, create, update, delete, run, runs, close	Schedule an eligible installed app tool with timezone and bounded runtime/run count.
search	replace, index, upsert, delete, clear, query	Maintain this app’s private entries and query the account search index.

const stream = await campus.accountEvents.subscribe(['report:*'], {
  delivery: 'durable',
  consumer: 'report-indexer',
  ackMode: 'explicit',
})

for await (const event of stream) {
  await commitIdempotently(event.id, event.data)
  await stream.ack(event)
}

await campus.notifications.publish({
  topic: 'report.ready',
  title: 'Report ready',
})
await campus.search.upsert([{ id: 'report:weekly', title: 'Weekly report' }])

Platform services and tools

Surface	Current methods	Contract
intelligence	request(provider, path, options)	Run inference within the installation’s provider, model, and budget grants.
speech	start, toggle, cancel, onTranscript, close	Browser microphone transcription with visible browser permission.
mcp	list, searchPublic, call, callAdmitted, cancelAdmission, serveBrowser, callBrowser, appStatus, close	Discover, call, or serve permission-filtered product tools while preserving admission contracts.
activity	snapshot	Read the account’s authorized runtime activity view.
domains	snapshot, bind, attachDns, refresh, unbind, finalize	Manage public domain bindings for apps with approved public routes.
distribution	products, sources, mcpListings, revenue, publish, setPrice, publishRelease, withdraw, setMcpListing	Package and publish immutable app releases and MCP listings.
securityReviews	list, get, request	Request and read Store release security review state.

const response = await campus.intelligence.request('openai', '/v1/responses', {
  method: 'POST',
  body: { model: 'configured', input: 'Summarize this report.' },
})

const result = await campus.mcp.call({
  name: 'campus-calendar.availability',
  arguments: { query: { fromMs, toMs } },
})

if (result.resultType === 'complete') {
  renderAvailability(result.structuredContent)
}

Product behavior such as starting a call, sending a Matrix message, or booking a calendar offer is app-owned MCP—not a new CampusSDK namespace.

Execution surfaces

Environment	Entry	Use
Browser app	createCampusApp()	Trusted launch, shell, typed Campus primitives, private backend transport, and MCP.
JavaScript backend	CampusServicesClient.fromEnv()	Installation-scoped Gateway services, durable events/workflows, files, and work leases.
Rust backend	campus_sdk::CampusServicesClient	Native equivalent for Rust workloads.
Native Agent	@campus/sdk/account-mcp	Caller-filtered account/product MCP catalog over stdio.
App MCP provider	manifest mcp.tools	App-owned product contracts executed by browser, workload, or reviewed service transport.

Transport and authority

The browser SDK routes each operation through one of three transports:

• shell for trusted visible UI and user confirmation;
• service for installation-authorized Campus services;
• workload for this installation’s private backend.

The app receives a Gateway endpoint ticket and installation capability, never a reusable backend address. Product MCP calls preserve the product package’s own schemas, permissions, routing, and admission contract.

Compatibility

CampusApp.connect(), storage(), content(), and workload-named browser methods remain deprecated compatibility APIs. New code uses createCampusApp(), kv(), encryptedContent, and backend.*.

For exact TypeScript shapes and ownership boundaries, continue to the full SDK surface, generated Platform API operation catalog, WebSockets, server-sent events, and Drive/files model.