#SDK API

Import sdk from the dedicated runtime entry point:

import { sdk } from '@theaiplatform/miniapp-sdk/sdk';

The sdk export is a lazy MiniAppPlatformApi. Importing it is safe in tests and build tools. Reading any property before The AI Platform installs the capability session throws an unsupported-environment error, so keep host access at a target or surface boundary.

Every host operation can cross a process or network boundary. Always await its result even when the type also permits a synchronous value through MiniAppMaybePromise.

#Declare Permissions

Every host-backed method must be declared before installation. Add each action ID you use to a permission.catalog, include it in a package level, and reference it from the calling contribution's authorization.allOf. The autonomy value below is the minimum ceiling required by that method. Declarations are requests, not grants: installation review and current workspace policy decide whether a call is allowed, and a later revocation makes the operation reject.

The browser-only openEditorProject helper appears in the table because it requests a host action even though it is imported from /web. Theme helpers, type exports, getPlatform, and capability-flag checks do not request a host action and therefore need no permission action.

sdk.storage, sdk.presence, sdk.http, and sdk.credentials use descriptor effects in addition to the calling contribution's ordinary permission binding. Declare a storage or presence effect whose resources contains each namespace the contribution uses. HTTP requires an external-network effect for each exact URL origin, such as https://api.vanta.com. Credential listing or use also requires { "kind": "credentials", "resources": ["http"] }. Wildcards do not match an origin. The host derives workspace, package, instance, document, and participant identity from the verified frame; none of those are caller inputs.

The quickstart shows a complete catalog, level, role recommendation, and surface binding for channels.list. For a package that uses several methods, list each action once and bind only the actions needed by each contribution.

#Namespaced Storage

sdk.storage stores bounded, non-secret JSON under a package-controlled namespace and key. The host prepends the authenticated workspace and exact package identity, so two packages cannot address each other's data. get returns a value and optimistic revision; a missing entry returns both as null. Pass that exact revision to set or delete. Pass null only to create a missing key.

const address = { namespace: 'canvas', key: 'scene/main' };
const current = await sdk.storage.get(address);
const saved = await sdk.storage.set({
  ...address,
  expectedRevision: current.revision,
  value: { title: 'Launch plan', nodes: [] },
});
console.log(saved.revision);

Values are limited to plain finite JSON and five MiB. Secrets, credentials, binary assets, and signed URLs do not belong in this API. A revision conflict rejects; reload, merge, and retry instead of silently overwriting another realm's update.

#Presence

sdk.presence carries bounded ephemeral JSON in a host-scoped namespace and room. Call subscribe before join, refresh state with update, and call leave during explicit teardown. The host also removes a participant when its document or frame is retired.

const address = { namespace: 'canvas', room: 'scene/main' };
const unsubscribe = sdk.presence.subscribe(address, (snapshot) => {
  const collaborators = snapshot.participants.filter(
    (participant) => participant.participantId !== snapshot.selfParticipantId,
  );
  renderCollaborators(collaborators);
});

await sdk.presence.join({
  ...address,
  state: { cursor: { x: 120, y: 80 }, selection: ['node-1'] },
});

Participant IDs, display names, and timestamps are host-stamped. App state cannot replace them. Presence is not durable storage or a permission grant; participants expire after missed heartbeats and must be prepared to rejoin.

#HTTP and credentials

Feature-detect sdk.http, sdk.credentials, and hasHostHttpRequest === true because non-desktop targets may omit these capabilities. sdk.http.request sends bounded HTTP(S) through the native transport, so it is not subject to the miniapp iframe's browser CORS path. The host validates the URL and limits, requires persisted package grants, and asks the signed-in human for origin consent. Credential-backed requests additionally revalidate the active workspace and user before resolving a secret.

if (!sdk.http || !sdk.credentials || sdk.hasHostHttpRequest !== true) {
  throw new Error('Host-mediated HTTP is unavailable in this target.');
}

const credentials = await sdk.credentials.listHttp();
const credential = credentials.find(
  (candidate) => candidate.credentialType === 'http_bearer',
);
if (!credential) throw new Error('Configure an HTTP bearer credential first.');

const response = await sdk.http.request(
  { method: 'GET', url: 'https://api.vanta.com/v1/controls' },
  { credentialRef: credential.id },
);

listHttp returns IDs, types, display names, and non-secret metadata only. A miniapp cannot read credential values. The host injects the selected secret, redacts credential material from reflected response fields, suppresses binary bodies on credential-backed requests, and rejects destination conflicts. Request timeouts are capped at 120 seconds after consent; the SDK itself does not race the native human-decision prompt with a shorter client timeout.

#Channels

sdk.channels provides six operations:

MiniAppChannel describes a visible channel. MiniAppChannelMessage is intentionally opaque, bounded MiniAppJsonValue: the host versions timeline-row shapes independently, so narrow and validate a row before reading any fields. The timeline result also supplies the visible sequence. A former participant can remain readable through GetChannelAccessResult.visibleUntilSequence; do not interpret that as permission to write.

const access = await sdk.channels.getAccess({ channelId });
if (access.capabilities.includes('message:create')) {
  await sdk.channels.sendMessage({
    channelId,
    content: 'The report is ready.',
    body: 'The report is ready.',
  });
}

Access can change after a check. Handle rejection from the operation itself and do not infer authority from cached channel data.

#Projects

sdk.projects uses CreateProjectOptions, GetProjectOptions, and UpdateProjectOptions. The corresponding CreateProjectResult, GetProjectResult, and UpdateProjectResult return the project ID or a MiniAppProject snapshot.

const result = await sdk.projects.get({ projectId });
if (result.project) {
  await sdk.projects.update({
    projectId,
    name: `${result.project.name} copy`,
  });
}

GetProjectResult.project can be null when the project is missing or outside the current capability scope.

#Workflows

sdk.workflows.list accepts optional ListWorkflowsOptions and returns ListWorkflowsResult, whose entries are MiniAppWorkflow values. invokeSaved accepts InvokeSavedWorkflowOptions; the optional invoke method accepts InvokeWorkflowOptions. Both return InvokeWorkflowResult.

const result = await sdk.workflows.invokeSaved({
  workflowId,
  payload: { source: 'miniapp' },
});
if (!result.success) {
  throw new Error(result.error ?? result.message);
}

Feature-detect the optional inline invoke method. A successful request reports status and may include a run ID; it does not imply that unrelated follow-up operations are authorized.

#Authentication

sdk.auth is an optional MiniAppAuthApi. Its getUserProfile method returns a MiniAppUserProfile or null. The profile exposes a subject when available and host-approved public fields; it never contains raw platform credentials.

const profile = (await sdk.auth?.getUserProfile()) ?? null;
if (profile) {
  console.log(profile.sub, profile.email ?? 'No email was shared');
}

Treat a missing capability and a signed-out profile as normal states. Request the profile again after an account or scope change.

#Virtual Files

sdk.vfs is an optional MiniAppVfsApi with provisionProjectChat, mkdir, and writeFile. File paths are relative to the selected conversation storage, not operating-system paths.

const vfs = sdk.vfs;
if (vfs) {
  const provisioned = await vfs.provisionProjectChat({
    conversationId,
    projectId,
  });
  console.log(provisioned.mountedRoots);
  await vfs.mkdir(conversationId, 'notes');
  await vfs.writeFile(
    conversationId,
    'notes/README.md',
    new TextEncoder().encode('# Notes\n'),
  );
}

The VFS API does not expose raw host filesystem access. Handle unavailable scope, conflicts, and deletion as recoverable failures.

#Specialists

sdk.specialist is an optional MiniAppSpecialistApi. It can join a specialist to a channel, list a workspace, and create a specialist. A compatible host can additionally expose upsertManaged and runTurnWithTools.

Managed upsert can return MiniAppManagedSpecialistResult. A supported turn accepts MiniAppSpecialistTurnOptions and returns MiniAppSpecialistTurnResult. Feature-detect both optional methods before showing their actions.

const specialists = sdk.specialist;
if (specialists) {
  const available = await specialists.listWorkspace(workspaceId);
  const first = available[0];
  if (first) {
    const sessionId = await specialists.joinToChannel(channelId, first.id);
    console.log(`Joined specialist session ${sessionId}`);
  }
}

MiniAppCreateSpecialistOptions and MiniAppCreateSpecialistResult describe a basic created specialist. MiniAppManagedSpecialist is the bounded, author-controlled manifest accepted by upsertManaged; the result always contains the effective specialist ID. Ownership, workspace, visibility, installation, and verification metadata are derived by the host and are rejected if a miniapp supplies them. MiniAppSpecialistInteractionMode, MiniAppSpecialistConversationPart, and the turn option/result types describe the complete request and terminal response for a supported tool-enabled turn. Hosts reject invalid IDs, unsupported modes, out-of-range timeouts, unauthorized channel access, and malformed manifests.

#Chat

sdk.chat is the required MiniAppChatApi. sendTextToChat selects the active conversation, reveals the shared composer, and places text there. Compatible hosts can also expose joinChannelSpecialist and archiveConversation.

await sdk.chat.sendTextToChat('Summarize the current project.');

The method places text for the user; do not describe it as silently sending a user-authored message.

joinChannelSpecialist takes a channel and specialist ID and resolves with null after the roster update. archiveConversation takes workspace, user, conversation, and project IDs and resolves with null after archival. Both are optional and can reject when the current package session lacks authority.

#Navigation and Feature Flags

sdk.navigation.open accepts OpenNavigationOptions with a platform-relative path. It is not a general URL or script launcher.

hasEditorView and hasHostHttpRequest are optional boolean feature flags. Treat values other than true as unavailable. When hasHostHttpRequest is true, the desktop host also supplies sdk.http and sdk.credentials; portable code should still check the objects before calling them.

await sdk.navigation.open({
  path: `/workspace/${workspaceId}/channels/${channelId}`,
});

if (sdk.hasEditorView === true) {
  // Render an action that uses the documented web editor helper.
}

Navigation rejects malformed or out-of-scope paths. Feature flags are snapshots; re-check them after a new surface realm mounts.

#Public Export Contract

Every exported name below is public. “Type only” rows have no runtime lifecycle of their own; the linked working example shows where the contract is consumed.