#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 or specialist-attributed 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);
}

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

#Specialists

sdk.specialist exposes the specialist operations granted to the package, including listing or creating specialists, joining one to a channel, 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.

#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.