@theaiplatform/miniapp-sdk 0.0.0

package/dist/web.d.ts

@@ -0,0 +1,507 @@
+/**
+ * Public miniapp API installed by the host. Importing this value is safe in
+ * build tools and tests; an unsupported-environment error is raised only when a
+ * property is read before the host installs the API.
+ */
+export declare const app: MiniAppPlatformApi;
+
+export declare function applyMiniAppTheme(theme: MiniAppTheme): void;
+
+declare type CreateChannelOptions = {
+    workspaceId?: string;
+    name: string;
+    description?: string;
+    projectId?: string | null;
+    visibility?: string;
+};
+
+declare type CreateChannelResult = {
+    roomId: string;
+};
+
+declare type CreateProjectOptions = {
+    workspaceId?: string;
+    id?: string;
+    name: string;
+    discoverable?: boolean;
+};
+
+declare type CreateProjectResult = {
+    projectId: string;
+};
+
+declare type GetChannelAccessOptions = {
+    workspaceId?: string;
+    channelId: string;
+};
+
+declare type GetChannelAccessResult = {
+    archived: boolean;
+    capabilities: string[];
+    isParticipant: boolean;
+    /**
+     * Last timeline sequence retained for a former participant. When present,
+     * the channel remains readable through this sequence even though
+     * `isParticipant` is false.
+     */
+    visibleUntilSequence?: number | null;
+};
+
+declare type GetChannelTimelineOptions = {
+    workspaceId?: string;
+    channelId: string;
+};
+
+declare type GetChannelTimelineResult = {
+    timeline: {
+        messages: MiniAppChannelMessage[];
+        sequence: number;
+    };
+};
+
+export declare function getMiniAppThemeFromSearch(search?: string | URLSearchParams): MiniAppTheme;
+
+/** Returns the public miniapp API proxy, which fails only when it is used. */
+export declare function getPlatform(): MiniAppPlatform;
+
+declare type GetProjectOptions = {
+    workspaceId?: string;
+    projectId: string;
+};
+
+declare type GetProjectResult = {
+    project: MiniAppProject | null;
+};
+
+export declare function installMiniAppThemeSync({ applyTheme, search, }?: InstallMiniAppThemeSyncOptions): () => void;
+
+export declare type InstallMiniAppThemeSyncOptions = {
+    applyTheme?: (theme: MiniAppTheme) => void;
+    search?: string | URLSearchParams;
+};
+
+declare type InvokeSavedWorkflowOptions<TPayload = unknown> = {
+    workflowId: string;
+    payload?: TPayload;
+};
+
+declare type InvokeWorkflowOptions<TPayload = unknown> = {
+    workflowJson: string;
+    payload?: TPayload;
+};
+
+declare type InvokeWorkflowResult = {
+    success: boolean;
+    status: string;
+    message: string;
+    runId?: string | null;
+    error?: string | null;
+};
+
+declare type ListChannelsOptions = {
+    workspaceId?: string;
+};
+
+declare type ListChannelsResult = {
+    rooms: MiniAppChannel[];
+    readMode: string;
+};
+
+declare type ListWorkflowsOptions = {
+    workspaceId?: string;
+};
+
+declare type ListWorkflowsResult = {
+    workflows: MiniAppWorkflow[];
+};
+
+declare type MiniAppAuthApi = {
+    getUserProfile(): MiniAppMaybePromise<MiniAppUserProfile | null>;
+};
+
+/**
+ * @capability integrations-and-marketplace
+ */
+declare type MiniAppChannel = {
+    roomId: string;
+    title?: string;
+    kind?: string;
+    description?: string;
+    visibility: string;
+    archived: boolean;
+    createdAt: number;
+    updatedAt: number;
+};
+
+/**
+ * One bounded JSON timeline row. The row schema is host-versioned, so callers
+ * must narrow it before reading fields.
+ */
+declare type MiniAppChannelMessage = MiniAppJsonValue;
+
+declare type MiniAppChatApi = {
+    /**
+     * Select the miniapp's active conversation, reveal the shared chat panel,
+     * and place text in its composer without unmounting the miniapp surface.
+     */
+    sendTextToChat(text: string): MiniAppMaybePromise<void>;
+    joinChannelSpecialist?(channelId: string, specialistId: string): MiniAppMaybePromise<null>;
+    archiveConversation?(workspaceId: string, userId: string, conversationId: string, projectId: string): MiniAppMaybePromise<null>;
+};
+
+declare type MiniAppCreateSpecialistOptions = {
+    name: string;
+    domain: string;
+    description: string | null;
+    configuration: MiniAppJsonValue;
+};
+
+declare type MiniAppCreateSpecialistResult = {
+    id: string;
+    name: string;
+    domain: string;
+    description: string | null;
+    isActive: boolean;
+};
+
+/** JSON-compatible values accepted by public miniapp operations. */
+declare type MiniAppJsonValue = null | boolean | number | string | MiniAppJsonValue[] | {
+    [key: string]: MiniAppJsonValue;
+};
+
+/**
+ * Author-controlled manifest accepted by the host-managed specialist
+ * persistence operation. Ownership, visibility, installation, and verification
+ * metadata are derived by the host and cannot be supplied by a miniapp.
+ */
+declare type MiniAppManagedSpecialist = {
+    id: string;
+    slug: string;
+    name: string;
+    publisher: string;
+    description: string;
+    icon: string;
+    category?: string;
+    categoryDisplayName?: string;
+    version?: string;
+    schemaVersion?: string;
+    displayName?: string;
+    maintainers?: Array<{
+        name: string;
+        email: string;
+        url?: string;
+    }>;
+    license?: string;
+    lastUpdated?: string;
+    fullDescription?: string;
+    knowledgeSources?: MiniAppJsonValue[];
+    ownedKnowledgePlotId?: string;
+    links?: {
+        terms?: string;
+        privacy?: string;
+        website?: string;
+    };
+    systemPrompt?: string;
+    prompts?: MiniAppJsonValue;
+    skills?: string[];
+    tooling?: MiniAppJsonValue;
+    orchestration?: MiniAppJsonValue;
+    taskModels?: Record<string, string>;
+    knowledgeTargeting?: MiniAppJsonValue;
+    tasks?: MiniAppJsonValue[];
+    identity?: MiniAppJsonValue;
+    audience?: MiniAppJsonValue;
+    constraints?: MiniAppJsonValue;
+    domainContext?: MiniAppJsonValue;
+    purpose?: string;
+    values?: MiniAppJsonValue[];
+    attributes?: string[];
+    techStack?: string[];
+    writingStyle?: MiniAppJsonValue;
+    tags?: string[];
+    preferredModel?: string;
+    supportsLocal?: boolean;
+    requiresNetwork?: boolean;
+    knowledgeGardens?: string[];
+};
+
+declare type MiniAppManagedSpecialistResult = {
+    specialistId: string;
+};
+
+declare type MiniAppMaybePromise<T> = T | Promise<T>;
+
+/** Browser view of the public miniapp API. */
+export declare type MiniAppPlatform = MiniAppPlatformApi;
+
+export declare type MiniAppPlatformApi = {
+    channels: {
+        create(options: CreateChannelOptions): CreateChannelResult | Promise<CreateChannelResult>;
+        list(options?: ListChannelsOptions): ListChannelsResult | Promise<ListChannelsResult>;
+        sendMessage(options: SendChannelMessageOptions): SendChannelMessageResult | Promise<SendChannelMessageResult>;
+        /** Persist one deterministic completed row under a joined specialist. */
+        sendSpecialistMessage(options: SendChannelSpecialistMessageOptions): SendChannelSpecialistMessageResult | Promise<SendChannelSpecialistMessageResult>;
+        getAccess(options: GetChannelAccessOptions): GetChannelAccessResult | Promise<GetChannelAccessResult>;
+        getTimeline(options: GetChannelTimelineOptions): GetChannelTimelineResult | Promise<GetChannelTimelineResult>;
+    };
+    projects: {
+        create(options: CreateProjectOptions): CreateProjectResult | Promise<CreateProjectResult>;
+        get(options: GetProjectOptions): GetProjectResult | Promise<GetProjectResult>;
+        update(options: UpdateProjectOptions): UpdateProjectResult | Promise<UpdateProjectResult>;
+    };
+    workflows: {
+        list(options?: ListWorkflowsOptions): ListWorkflowsResult | Promise<ListWorkflowsResult>;
+        invokeSaved<TPayload = unknown>(options: InvokeSavedWorkflowOptions<TPayload>): InvokeWorkflowResult | Promise<InvokeWorkflowResult>;
+        invoke?<TPayload = unknown>(options: InvokeWorkflowOptions<TPayload>): InvokeWorkflowResult | Promise<InvokeWorkflowResult>;
+    };
+    navigation: {
+        open(options: OpenNavigationOptions): void | Promise<void>;
+    };
+    chat: MiniAppChatApi;
+    /** Browser capabilities appear only when the selected target supports them. */
+    auth?: MiniAppAuthApi;
+    vfs?: MiniAppVfsApi;
+    specialist?: MiniAppSpecialistApi;
+    hasEditorView?: boolean;
+    hasHostHttpRequest?: boolean;
+};
+
+declare type MiniAppProject = {
+    id: string;
+    name: string;
+    workspaceId: string;
+    discoverable: boolean;
+    channelIds: string[];
+    archivedChannelIds: string[];
+};
+
+declare type MiniAppProvisionProjectChatOptions = {
+    conversationId: string;
+    projectId: string;
+    referenceBranch?: string | null;
+};
+
+declare type MiniAppProvisionProjectChatResult = {
+    mountedRoots: string[];
+    worktreeBranch?: string | null;
+    worktreeBaseCommit?: string | null;
+};
+
+declare type MiniAppSpecialistApi = {
+    joinToChannel(channelId: string, specialistId: string): MiniAppMaybePromise<string>;
+    listWorkspace(workspaceId: string): MiniAppMaybePromise<MiniAppSpecialistSummary[]>;
+    create(options: MiniAppCreateSpecialistOptions): MiniAppMaybePromise<MiniAppCreateSpecialistResult>;
+    upsertManaged?(specialist: MiniAppManagedSpecialist): MiniAppMaybePromise<MiniAppManagedSpecialistResult>;
+    runTurnWithTools?(options: MiniAppSpecialistTurnOptions): MiniAppMaybePromise<MiniAppSpecialistTurnResult>;
+};
+
+declare type MiniAppSpecialistConversationPart = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'tool';
+    toolCallId: string;
+    toolName: string;
+    arguments: MiniAppJsonValue;
+    toolIntent: string | null;
+    success: boolean;
+    content: MiniAppJsonValue;
+    mediaCost?: MiniAppJsonValue | null;
+    error?: string | null;
+    executionTimeMs: number;
+} | {
+    type: 'stepEnd';
+    iteration: number;
+};
+
+declare type MiniAppSpecialistInteractionMode = 'conversational' | 'agentic' | 'planning' | 'background' | 'longRunning' | 'inlineEdit' | 'focus';
+
+declare type MiniAppSpecialistSummary = {
+    id: string;
+    slug: string;
+    displayName: string;
+    description: string;
+    tags: string[];
+    version: string;
+    availability: 'public' | 'internal' | 'private' | 'restricted';
+    canRunLocally: boolean;
+    category: string;
+    categoryDisplayName: string;
+    requiredCapabilities: {
+        inputModalities: string[];
+        toolUse?: boolean | null;
+        reasoning?: boolean | null;
+    } | null;
+    omnipresence?: {
+        autoJoinChannels: boolean;
+        includeDms: boolean;
+        pinSidebar: boolean;
+    } | null;
+    displayIcon?: {
+        type: 'bundled';
+        path: string;
+    } | {
+        type: 'remote';
+        url: string;
+    } | null;
+};
+
+declare type MiniAppSpecialistTurnOptions = {
+    workspaceId: string;
+    channelId: string;
+    specialistId: string;
+    content: string;
+    modelOverride: string;
+    messageId: null;
+    interactionMode: MiniAppSpecialistInteractionMode;
+    timeoutMs: number;
+};
+
+declare type MiniAppSpecialistTurnResult = {
+    completionEvent: {
+        parts: MiniAppSpecialistConversationPart[];
+        finishReason?: string;
+        modelUsed?: string;
+    };
+};
+
+export declare type MiniAppTheme = 'light' | 'dark';
+
+declare type MiniAppUserProfile = {
+    sub: string;
+    name?: string | null;
+    givenName?: string | null;
+    familyName?: string | null;
+    middleName?: string | null;
+    nickname?: string | null;
+    preferredUsername?: string | null;
+    profile?: string | null;
+    picture?: string | null;
+    website?: string | null;
+    email?: string | null;
+    emailVerified?: boolean | null;
+    gender?: string | null;
+    birthdate?: string | null;
+    zoneinfo?: string | null;
+    locale?: string | null;
+    phoneNumber?: string | null;
+    phoneNumberVerified?: boolean | null;
+    address?: MiniAppJsonValue | null;
+    updatedAt?: string | null;
+};
+
+declare type MiniAppVfsApi = {
+    provisionProjectChat(options: MiniAppProvisionProjectChatOptions): MiniAppMaybePromise<MiniAppProvisionProjectChatResult>;
+    writeFile(conversationId: string, path: string, data: Uint8Array): MiniAppMaybePromise<null>;
+    mkdir(conversationId: string, path: string): MiniAppMaybePromise<null>;
+};
+
+declare type MiniAppWorkflow = {
+    id: string;
+    name: string;
+    type: string;
+    createdAt: number;
+    updatedAt: number;
+};
+
+/** Requests the host-owned editor capability for this exact miniapp frame. */
+export declare function openEditorProject(options: OpenEditorProjectOptions): Promise<void>;
+
+export declare type OpenEditorProjectOptions = {
+    conversationId: string;
+    files?: Array<{
+        path: string;
+        selection?: {
+            line: number;
+            column: number;
+        };
+    }>;
+    mode: 'embedded';
+    projectId?: string | null;
+};
+
+declare type OpenNavigationOptions = {
+    path: string;
+};
+
+/** Unknown capabilities fail closed. */
+export declare function platformSatisfiesApp(platform: MiniAppPlatform, requiredCapabilities: readonly string[]): boolean;
+
+declare type SendChannelMessageOptions = {
+    workspaceId?: string;
+    channelId: string;
+    /**
+     * Optional stable client id for product-owned messages such as seeded
+     * lifecycle notices. Omit for ordinary miniapp messages.
+     */
+    clientMessageId?: string;
+    name?: string;
+    /** Display body to persist. When omitted, the host formats `name` and `content`. */
+    body?: string;
+    content: string;
+    /** Optional structured chat content persisted with the message. */
+    messageContent?: Record<string, MiniAppJsonValue>;
+};
+
+declare type SendChannelMessageResult = {
+    messageId: string;
+    clientMessageId: string;
+};
+
+declare type SendChannelSpecialistMessageOptions = {
+    workspaceId?: string;
+    channelId: string;
+    projectId: string;
+    specialistId: string;
+    clientMessageId: string;
+    body: string;
+    messageContent?: Record<string, MiniAppJsonValue>;
+};
+
+declare type SendChannelSpecialistMessageResult = {
+    messageId: string;
+    clientMessageId: string;
+};
+
+export declare type SpecialistEvent = SpecialistTurnCompletedEvent | SpecialistTurnErrorEvent;
+
+export declare type SpecialistTurnCompletedEvent = {
+    type: 'turnCompleted';
+    channelId: string;
+    clientMessageId?: string | null;
+    finishReason?: string | null;
+    messageId: string | null;
+    modelUsed?: string | null;
+    parts?: MiniAppSpecialistConversationPart[];
+    providerUsed?: string | null;
+    specialistId: string;
+    totalIterations?: number | null;
+    totalTimeMs?: number | null;
+    totalToolCalls?: number | null;
+    turnId?: string | null;
+};
+
+export declare type SpecialistTurnErrorEvent = {
+    type: 'turnError';
+    channelId: string;
+    clientMessageId?: string | null;
+    error?: string | null;
+    messageId?: string | null;
+    specialistId: string;
+    turnId?: string | null;
+};
+
+declare type UpdateProjectOptions = {
+    workspaceId?: string;
+    projectId: string;
+    name?: string;
+    discoverable?: boolean;
+    channelIds?: string[];
+    archivedChannelIds?: string[];
+};
+
+declare type UpdateProjectResult = {
+    project: MiniAppProject;
+};
+
+export { }

package/dist/web.js

@@ -0,0 +1,146 @@
+import { sdk } from "./sdk.js";
+function getPlatform() {
+    return sdk;
+}
+const PLATFORM_CAPABILITIES = {
+    editorView: (platform)=>true === platform.hasEditorView,
+    hostHttpRequest: (platform)=>true === platform.hasHostHttpRequest
+};
+function platformSatisfiesApp(platform, requiredCapabilities) {
+    return requiredCapabilities.every((capability)=>PLATFORM_CAPABILITIES[capability]?.(platform) ?? false);
+}
+const HOST_ACTION_REQUEST = 'tap-miniapp-host-action';
+const HOST_ACTION_RESPONSE = 'tap-miniapp-host-action-response';
+const OPEN_EDITOR_PROJECT_ACTION = 'tap.editor.open-project';
+const HOST_ACTION_TIMEOUT_MS = 4000;
+const MAX_HOST_ACTION_ID_CHARS = 256;
+const MAX_HOST_ACTION_ERROR_CHARS = 1024;
+const MINIAPP_DOCUMENT_ID_GLOBAL_KEY = 'zephyrcloudio.miniapp.document-id';
+let hostActionSequence = 0;
+function isExactBoundedString(value, maximumLength) {
+    return 'string' == typeof value && value.length > 0 && value.length <= maximumLength && value.trim() === value && !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function getMiniappDocumentId() {
+    const documentId = Reflect.get(globalThis, Symbol.for(MINIAPP_DOCUMENT_ID_GLOBAL_KEY));
+    if (!isExactBoundedString(documentId, MAX_HOST_ACTION_ID_CHARS)) throw new Error('The miniapp document identity is unavailable.');
+    return documentId;
+}
+function exactOrigin(value) {
+    if (!value) return null;
+    try {
+        const url = new URL(value);
+        return 'null' === url.origin || url.username || url.password ? null : url.origin;
+    } catch  {
+        return null;
+    }
+}
+function getHostOrigin() {
+    const params = new URLSearchParams(window.location.search);
+    const referrer = "u" < typeof document ? '' : document.referrer;
+    return exactOrigin(params.get('hostOrigin')) ?? exactOrigin(params.get('miniappHostOrigin')) ?? exactOrigin(referrer);
+}
+function getFrameInstanceId() {
+    const params = new URLSearchParams(window.location.search);
+    const instanceId = params.get('miniappInstanceId') ?? params.get('instanceId') ?? params.get('miniappFrameId');
+    return isExactBoundedString(instanceId, MAX_HOST_ACTION_ID_CHARS) ? instanceId : null;
+}
+function createHostActionId() {
+    hostActionSequence += 1;
+    return `tap-host-action-${hostActionSequence}-${globalThis.crypto?.randomUUID?.() ?? Date.now().toString(36)}`;
+}
+function getHostActionError(value) {
+    if (isRecord(value) && isExactBoundedString(value.error, MAX_HOST_ACTION_ERROR_CHARS)) return new Error(value.error);
+    return new Error('The miniapp host action failed.');
+}
+function requestHostAction(action, payload) {
+    const hostOrigin = getHostOrigin();
+    if (!hostOrigin) return Promise.reject(new Error('The miniapp host origin is unavailable.'));
+    const instanceId = getFrameInstanceId();
+    if (!instanceId) return Promise.reject(new Error('The miniapp frame identity is unavailable.'));
+    const documentId = getMiniappDocumentId();
+    const parent = window.parent;
+    if (!parent || parent === window) return Promise.reject(new Error('The miniapp host is unavailable.'));
+    const id = createHostActionId();
+    return new Promise((resolve, reject)=>{
+        const timeout = setTimeout(()=>{
+            cleanup();
+            reject(new Error('The miniapp host action timed out.'));
+        }, HOST_ACTION_TIMEOUT_MS);
+        const handleMessage = (event)=>{
+            if (event.source !== parent || event.origin !== hostOrigin) return;
+            if (!isRecord(event.data)) return;
+            if (event.data.type !== HOST_ACTION_RESPONSE || event.data.id !== id || 'boolean' != typeof event.data.ok) return;
+            cleanup();
+            if (event.data.ok) resolve(event.data.result);
+            else reject(getHostActionError(event.data));
+        };
+        const cleanup = ()=>{
+            clearTimeout(timeout);
+            window.removeEventListener('message', handleMessage);
+        };
+        window.addEventListener('message', handleMessage);
+        try {
+            parent.postMessage({
+                type: HOST_ACTION_REQUEST,
+                id,
+                action,
+                documentId,
+                payload,
+                instanceId
+            }, hostOrigin);
+        } catch (error) {
+            cleanup();
+            reject(error);
+        }
+    });
+}
+async function openEditorProject(options) {
+    if ("u" < typeof window) throw new Error('The miniapp host is unavailable.');
+    await requestHostAction(OPEN_EDITOR_PROJECT_ACTION, options);
+}
+const MINIAPP_THEME_CHANGED_EVENTS = new Set([
+    'zephyr-app-theme-changed',
+    'tap-miniapp-theme-changed'
+]);
+function isMiniAppTheme(value) {
+    return 'light' === value || 'dark' === value;
+}
+function readThemeFromSearch(search) {
+    const params = 'string' == typeof search ? new URLSearchParams(search.startsWith('?') ? search.slice(1) : search) : search;
+    const appTheme = params.get('appTheme');
+    return isMiniAppTheme(appTheme) ? appTheme : 'light';
+}
+function getMiniAppThemeFromSearch(search = "u" < typeof window ? '' : window.location.search) {
+    return readThemeFromSearch(search);
+}
+function applyMiniAppTheme(theme) {
+    if ("u" < typeof document) return;
+    document.documentElement.dataset.appTheme = theme;
+    document.documentElement.classList.toggle('dark', 'dark' === theme);
+    document.documentElement.classList.toggle('light', 'light' === theme);
+    document.documentElement.style.colorScheme = theme;
+}
+function installMiniAppThemeSync({ applyTheme = applyMiniAppTheme, search } = {}) {
+    applyTheme(getMiniAppThemeFromSearch(search));
+    if ("u" < typeof window) return ()=>void 0;
+    const hostOrigin = getHostOrigin();
+    const parent = window.parent;
+    if (!hostOrigin || !parent || parent === window) return ()=>void 0;
+    const handleMessage = (event)=>{
+        if (event.source !== parent || event.origin !== hostOrigin) return;
+        const data = event.data;
+        if ('object' != typeof data || null === data) return;
+        const record = data;
+        if ('string' != typeof record.type || !MINIAPP_THEME_CHANGED_EVENTS.has(record.type) || !isMiniAppTheme(record.appTheme)) return;
+        applyTheme(record.appTheme);
+    };
+    window.addEventListener('message', handleMessage);
+    return ()=>{
+        window.removeEventListener('message', handleMessage);
+    };
+}
+export { sdk as app } from "./sdk.js";
+export { applyMiniAppTheme, getMiniAppThemeFromSearch, getPlatform, installMiniAppThemeSync, openEditorProject, platformSatisfiesApp };