#Platform API

Import the host-backed API from the sdk entry point:

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

The host installs the API before evaluating a supported miniapp target. Importing the module is safe outside a miniapp realm, but reading an sdk property before the host installs a capability session throws immediately. For unit tests, pass a typed test double into your application code instead of trying to reproduce the host bootstrap.

Always await SDK operations. Some compatible hosts can complete a small operation synchronously, while others cross a process or network boundary.

#Channels

sdk.channels supports creating and listing visible channels, sending ordinary messages, reading access, and loading the visible timeline.

const { rooms } = await sdk.channels.list({ workspaceId });
const channel = rooms.find((room) => !room.archived);

if (channel) {
  await sdk.channels.sendMessage({
    workspaceId,
    channelId: channel.roomId,
    content: 'A report is ready.',
    body: 'A report is ready.',
  });
}

Use getAccess before presenting a protected action. Access can change after the check, so still handle an authorization failure from the action itself.

#Projects

sdk.projects creates, reads, and updates projects visible to the current capability session. Project updates can change the display name, discoverability, and associated channel sets.

Do not retain a project response as proof of continued access. Request current data again when acting after a scope or account change.

#Workflows

sdk.workflows.list returns saved workflows available to the current workspace. invokeSaved starts one by ID. A compatible host may also expose invoke for an inline workflow definition; feature-detect that optional method before enabling the action.

const invokeInline = sdk.workflows.invoke;
if (invokeInline) {
  const result = await invokeInline({
    workflowJson: JSON.stringify(workflow),
    payload: { source: 'hello-miniapp' },
  });
  if (!result.success) throw new Error(result.error ?? result.message);
}

#Authentication

sdk.auth exposes the signed-in state and public user profile needed by a miniapp. The host retains raw platform credentials.

const profile = (await sdk.auth?.getUserProfile()) ?? null;
if (!profile) {
  renderSignedOutState();
}

Authentication is an optional capability. Show a signed-out or unavailable state when sdk.auth is absent, and request current profile data again after an account or scope change.

#Virtual Files

sdk.vfs provides granted, scope-aware file operations. Paths are relative to the conversation or project storage selected by the method; they are not host filesystem paths.

const vfs = sdk.vfs;
if (!vfs) {
  renderStorageUnavailable();
} else {
  await vfs.mkdir(conversationId, 'notes');
  const bytes = new TextEncoder().encode('# Miniapp notes\n');
  await vfs.writeFile(conversationId, 'notes/README.md', bytes);
  await vfs.writeFiles(conversationId, seedFiles);
}

Request only the file effects your contribution needs. Treat missing scope, denied access, conflicts, and deleted files as normal recoverable errors.

#Direct inference

sdk.inference exposes managed model discovery and isolated text generation. Use it for bounded comparisons or evaluations, then write only the selected output to sdk.vfs when it should persist. Prefer a specialist for work that needs tools, history, or product-specific behavior. It is desktop-only and requires compatibility.tapHost to exclude versions before 2.3.5. See the SDK reference for the complete contract.

#Specialists

sdk.specialist exposes the specialist operations granted to the package, including listing or creating specialists, joining one to a channel, preparing several declared specialists with shared host work, and running supported managed turns.

Optional methods represent host-version or capability differences. Feature-detect them and provide a useful fallback.

#Chat and Navigation

Use sdk.chat.sendTextToChat to select the miniapp's active conversation, reveal the shared composer, and place text there without unmounting the surface.

Use sdk.navigation.open({ path }) for supported in-product navigation. Pass a platform route, not an arbitrary script or host URL.

On desktop, feature-detect sdk.navigation.openExternal when a user needs to leave The AI Platform. Call it directly from a trusted click with a canonical HTTPS URL. The exact origin must be declared by that UI contribution through the on-demand navigation.open-external action and an external-navigation effect; the host never supplies a global origin allowlist and always delegates successful calls to the operating-system browser.

#Errors

An SDK promise can reject because:

• the current realm has not received host authority;
• the contribution did not declare or receive the required permission;
• its workspace, channel, conversation, or project scope is unavailable;
• the selected host version does not implement an optional capability;
• input validation failed; or
• a platform or network operation failed.

Show errors in the miniapp surface, retain the last safe state, and let the user retry. Do not parse error strings to infer permission or compatibility; feature-detect optional methods and use typed results where the API provides them.