Config API

The /config entry point supports the typed app configuration format used by compatible integrations. The package root re-exports the same API.

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

export default defineApp({
  ui: [
    {
      type: 'workspace-left-sidebar',
      id: 'example-panel',
      name: 'Example',
      entryPoint: './ui/desktop',
    },
  ],
  tools: {
    echo: {
      description: 'Return the supplied text.',
      parametersSchema: {
        type: 'object',
        properties: { text: { type: 'string' } },
        required: ['text'],
      },
      execute(arguments_: { text: string }) {
        return { text: arguments_.text };
      },
    },
  },
});

defineApp preserves the inferred configuration type while checking it against AppConfig. It does not publish, validate host permissions, or replace manifest.tap.json.

Discovery Categories

MiniAppCategory is the closed discovery taxonomy used by presentation.categories in manifest.tap.json. A package can declare at most three unique categories; unknown or repeated values fail descriptor validation.

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

const categories: MiniAppCategory[] = ['developer-tools', 'productivity'];

The supported values are productivity, developer-tools, creativity, communication, data-and-analytics, business, education, media-and-entertainment, utilities, and other.

UI Entry Points

UIEntrypointType supports workspace-left and chat-right sidebar containers and items. UIEntrypoint provides the stable ID, display name, exposed entry point, optional icon, and optional persistence choice.

An entry point string must resolve to the contribution you build and declare. It is not a remote URL.

const ui: UIEntrypoint = {
  type: 'workspace-left-sidebar-item',
  id: 'reports',
  name: 'Reports',
  entryPoint: './ui/reports',
};

Tools

ToolDefinition describes a tool's display metadata, JsonSchema parameters, optional timeout and action template, and its execute function. The generic argument and result types let callers retain precise inference.

Tool execution can still be constrained by the selected target and host-granted capabilities. Validate untrusted inputs at runtime even when callers use TypeScript.

const echo: ToolDefinition<{ text: string }, { text: string }> = {
  description: 'Return text to the caller.',
  parametersSchema: { type: 'object' },
  execute: ({ text }) => ({ text }),
};

Public Export Contract

ExportPurposeInputs and resultLifecycle and errorsWorking example
UIEntrypointTypeEnumerates supported sidebar entry-point placements.Supplies one placement string to UIEntrypoint.Type only; unsupported values fail TypeScript and descriptor validation.UI entry points
MiniAppCategoryEnumerates the supported package discovery categories.Supplies up to three unique values to descriptor presentation metadata.Type only; unknown, duplicate, or oversized category lists fail validation.Discovery categories
UIEntrypointDescribes one typed UI entry for AppConfig.Contains type, ID, name, exposed entry point, and optional presentation fields.Type only; the referenced expose must exist in the built contribution graph.UI entry points
JsonSchemaRepresents JSON Schema data supplied to a tool definition.Accepts a read-only string-keyed schema record.Type only; callers still validate untrusted input at runtime.Tools
ToolDefinitionDescribes typed tool metadata and execution.Accepts schema and execute function plus optional display and timeout fields.The selected host target controls invocation; thrown errors reject the tool call.Tools
AppConfigGroups optional UI and tool declarations.Contains a read-only UI list and tool map.Type only; it does not replace the package descriptor or host authorization.Config API
defineAppPreserves inferred configuration while checking AppConfig.Accepts one config object and returns that same typed object.It has no runtime side effects and does not validate permissions or publish.Config API