@theaiplatform/miniapp-sdk 0.0.0

package/dist/sdk.d.ts

@@ -0,0 +1,441 @@
+export declare type CreateChannelOptions = {
+    workspaceId?: string;
+    name: string;
+    description?: string;
+    projectId?: string | null;
+    visibility?: string;
+};
+
+export declare type CreateChannelResult = {
+    roomId: string;
+};
+
+export declare type CreateProjectOptions = {
+    workspaceId?: string;
+    id?: string;
+    name: string;
+    discoverable?: boolean;
+};
+
+export declare type CreateProjectResult = {
+    projectId: string;
+};
+
+export declare type GetChannelAccessOptions = {
+    workspaceId?: string;
+    channelId: string;
+};
+
+export 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;
+};
+
+export declare type GetChannelTimelineOptions = {
+    workspaceId?: string;
+    channelId: string;
+};
+
+export declare type GetChannelTimelineResult = {
+    timeline: {
+        messages: MiniAppChannelMessage[];
+        sequence: number;
+    };
+};
+
+export declare type GetProjectOptions = {
+    workspaceId?: string;
+    projectId: string;
+};
+
+export declare type GetProjectResult = {
+    project: MiniAppProject | null;
+};
+
+export declare type InvokeSavedWorkflowOptions<TPayload = unknown> = {
+    workflowId: string;
+    payload?: TPayload;
+};
+
+export declare type InvokeWorkflowOptions<TPayload = unknown> = {
+    workflowJson: string;
+    payload?: TPayload;
+};
+
+export declare type InvokeWorkflowResult = {
+    success: boolean;
+    status: string;
+    message: string;
+    runId?: string | null;
+    error?: string | null;
+};
+
+export declare type ListChannelsOptions = {
+    workspaceId?: string;
+};
+
+export declare type ListChannelsResult = {
+    rooms: MiniAppChannel[];
+    readMode: string;
+};
+
+export declare type ListWorkflowsOptions = {
+    workspaceId?: string;
+};
+
+export declare type ListWorkflowsResult = {
+    workflows: MiniAppWorkflow[];
+};
+
+export declare type MiniAppAuthApi = {
+    getUserProfile(): MiniAppMaybePromise<MiniAppUserProfile | null>;
+};
+
+/**
+ * @capability integrations-and-marketplace
+ */
+export 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.
+ */
+export declare type MiniAppChannelMessage = MiniAppJsonValue;
+
+export 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>;
+};
+
+export declare type MiniAppCreateSpecialistOptions = {
+    name: string;
+    domain: string;
+    description: string | null;
+    configuration: MiniAppJsonValue;
+};
+
+export declare type MiniAppCreateSpecialistResult = {
+    id: string;
+    name: string;
+    domain: string;
+    description: string | null;
+    isActive: boolean;
+};
+
+/** JSON-compatible values accepted by public miniapp operations. */
+export 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.
+ */
+export 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[];
+};
+
+export declare type MiniAppManagedSpecialistResult = {
+    specialistId: string;
+};
+
+export declare type MiniAppMaybePromise<T> = T | Promise<T>;
+
+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;
+};
+
+export declare type MiniAppProject = {
+    id: string;
+    name: string;
+    workspaceId: string;
+    discoverable: boolean;
+    channelIds: string[];
+    archivedChannelIds: string[];
+};
+
+export declare type MiniAppProvisionProjectChatOptions = {
+    conversationId: string;
+    projectId: string;
+    referenceBranch?: string | null;
+};
+
+export declare type MiniAppProvisionProjectChatResult = {
+    mountedRoots: string[];
+    worktreeBranch?: string | null;
+    worktreeBaseCommit?: string | null;
+};
+
+export 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>;
+};
+
+export 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;
+};
+
+export declare type MiniAppSpecialistInteractionMode = 'conversational' | 'agentic' | 'planning' | 'background' | 'longRunning' | 'inlineEdit' | 'focus';
+
+export 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;
+};
+
+export declare type MiniAppSpecialistTurnOptions = {
+    workspaceId: string;
+    channelId: string;
+    specialistId: string;
+    content: string;
+    modelOverride: string;
+    messageId: null;
+    interactionMode: MiniAppSpecialistInteractionMode;
+    timeoutMs: number;
+};
+
+export declare type MiniAppSpecialistTurnResult = {
+    completionEvent: {
+        parts: MiniAppSpecialistConversationPart[];
+        finishReason?: string;
+        modelUsed?: string;
+    };
+};
+
+export 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;
+};
+
+export declare type MiniAppVfsApi = {
+    provisionProjectChat(options: MiniAppProvisionProjectChatOptions): MiniAppMaybePromise<MiniAppProvisionProjectChatResult>;
+    writeFile(conversationId: string, path: string, data: Uint8Array): MiniAppMaybePromise<null>;
+    mkdir(conversationId: string, path: string): MiniAppMaybePromise<null>;
+};
+
+export declare type MiniAppWorkflow = {
+    id: string;
+    name: string;
+    type: string;
+    createdAt: number;
+    updatedAt: number;
+};
+
+export declare type OpenNavigationOptions = {
+    path: string;
+};
+
+/**
+ * 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 sdk: MiniAppPlatformApi;
+
+export 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>;
+};
+
+export declare type SendChannelMessageResult = {
+    messageId: string;
+    clientMessageId: string;
+};
+
+export declare type SendChannelSpecialistMessageOptions = {
+    workspaceId?: string;
+    channelId: string;
+    projectId: string;
+    specialistId: string;
+    clientMessageId: string;
+    body: string;
+    messageContent?: Record<string, MiniAppJsonValue>;
+};
+
+export declare type SendChannelSpecialistMessageResult = {
+    messageId: string;
+    clientMessageId: string;
+};
+
+export declare type UpdateProjectOptions = {
+    workspaceId?: string;
+    projectId: string;
+    name?: string;
+    discoverable?: boolean;
+    channelIds?: string[];
+    archivedChannelIds?: string[];
+};
+
+export declare type UpdateProjectResult = {
+    project: MiniAppProject;
+};
+
+export { }

package/dist/sdk.js

@@ -0,0 +1,27 @@
+const SDK_SLOT = Symbol.for('tap.internal.v1');
+const UNSUPPORTED_ENVIRONMENT_MESSAGE = 'Attempted to use The AI Platform MiniApp SDK outside a supported environment';
+function readMiniAppSdk() {
+    const value = Reflect.get(globalThis, SDK_SLOT);
+    if ('object' != typeof value || null === value) throw new Error(UNSUPPORTED_ENVIRONMENT_MESSAGE);
+    return value;
+}
+const lazyMiniAppSdk = new Proxy(Object.create(null), {
+    get (_target, property) {
+        return Reflect.get(readMiniAppSdk(), property);
+    },
+    has (_target, property) {
+        return Reflect.has(readMiniAppSdk(), property);
+    },
+    ownKeys () {
+        return Reflect.ownKeys(readMiniAppSdk());
+    },
+    getOwnPropertyDescriptor (_target, property) {
+        const descriptor = Reflect.getOwnPropertyDescriptor(readMiniAppSdk(), property);
+        return descriptor ? {
+            ...descriptor,
+            configurable: true
+        } : void 0;
+    }
+});
+const sdk = lazyMiniAppSdk;
+export { sdk };

package/dist/surface.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Resolves one raw package-relative asset path inside the descriptor-selected
+ * target directory. Absolute, encoded-alias, and traversal inputs fail closed.
+ */
+export declare function resolvePackageAssetUrl(context: Pick<TapFederatedSurfaceMountContext, 'packageAssetBaseUrl'>, relativePath: string): URL;
+
+/**
+ * Read-only authority projected by TAP for the exact package release/frame.
+ * A candidate frame starts without authority and may only perform host-backed
+ * work after the host confirms that release. Subscribers are notified only
+ * when the boolean snapshot changes.
+ */
+export declare interface TapFederatedSurfaceHostAuthority {
+    getSnapshot(): boolean;
+    subscribe(listener: () => void): () => void;
+}
+
+/** Cleanup handle returned by a federated surface mount. */
+export declare interface TapFederatedSurfaceMount {
+    unmount(): void | Promise<void>;
+}
+
+/** Context supplied by TAP's isolated webview surface runtime. */
+export declare interface TapFederatedSurfaceMountContext {
+    readonly packageId: string;
+    readonly packageNamespace: string;
+    readonly releaseId: string;
+    readonly installationId: string;
+    readonly contributionId: string;
+    readonly instanceId: string;
+    readonly hostOrigin: string;
+    readonly packageAssetBaseUrl: string;
+    readonly workspaceId?: string;
+    readonly channelId?: string;
+    readonly conversationId?: string;
+    readonly events: TapPackageEventPublisher;
+    readonly hostAuthority: TapFederatedSurfaceHostAuthority;
+}
+
+/**
+ * @capability integrations-and-marketplace
+ */
+/** Declared package-event channel supplied to an isolated UI contribution. */
+export declare interface TapPackageEventPublisher {
+    publish(name: string, payload: Readonly<Record<string, unknown>>): void | Promise<void>;
+    subscribe(name: string, listener: (payload: unknown, envelope: Readonly<Record<string, unknown>>) => void | Promise<void>): () => void;
+}
+
+export { }

package/dist/surface.js

@@ -0,0 +1,28 @@
+const ENCODED_PATH_SEPARATOR_OR_DOT_PATTERN = /%(?:2e|2f|5c)/iu;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
+function packageAssetBaseUrl(context) {
+    const value = context.packageAssetBaseUrl;
+    if (value.trim() !== value || value.includes('\\') || CONTROL_CHARACTER_PATTERN.test(value) || ENCODED_PATH_SEPARATOR_OR_DOT_PATTERN.test(value)) throw new Error('The TAP package asset base URL must be a canonical target directory.');
+    let base;
+    try {
+        base = new URL(value);
+    } catch  {
+        throw new Error('The TAP package asset base URL is invalid.');
+    }
+    if ('http:' !== base.protocol && 'https:' !== base.protocol || 'null' === base.origin || '' !== base.username || '' !== base.password || '' !== base.search || '' !== base.hash || !base.pathname.endsWith('/') || base.pathname.slice(1).includes('//') || base.pathname.includes('\\') || ENCODED_PATH_SEPARATOR_OR_DOT_PATTERN.test(base.pathname)) throw new Error('The TAP package asset base URL must be a canonical target directory.');
+    return base;
+}
+function packageAssetPathSegments(relativePath) {
+    if ('' === relativePath || relativePath.trim() !== relativePath || relativePath.startsWith('/') || relativePath.includes('\\') || relativePath.includes('?') || relativePath.includes('#') || relativePath.includes(':') || relativePath.includes('%') || CONTROL_CHARACTER_PATTERN.test(relativePath)) throw new Error('A TAP package asset path must be a canonical relative path.');
+    const segments = relativePath.split('/');
+    if (segments.some((segment)=>'' === segment || '.' === segment || '..' === segment)) throw new Error('A TAP package asset path must not escape its target directory.');
+    return segments;
+}
+function resolvePackageAssetUrl(context, relativePath) {
+    const base = packageAssetBaseUrl(context);
+    const encodedRelativePath = packageAssetPathSegments(relativePath).map((segment)=>encodeURIComponent(segment)).join('/');
+    const resolved = new URL(encodedRelativePath, base);
+    if (resolved.origin !== base.origin || '' !== resolved.username || '' !== resolved.password || '' !== resolved.search || '' !== resolved.hash || !resolved.pathname.startsWith(base.pathname)) throw new Error('The TAP package asset URL must remain inside its target directory.');
+    return resolved;
+}
+export { resolvePackageAssetUrl };