@theaiplatform/miniapp-sdk 0.2.1 → 0.2.4

package/README.md

@@ -40,6 +40,20 @@ requests through host consent instead of browser `fetch`, and
 secrets remain in the host vault and are injected only by the native request
 authority.
 
+`sdk.printing` is an optional desktop-only receipt printer API. It discovers
+bounded machine-local printer metadata and host-supported 58 mm and 80 mm paper
+profiles, then accepts only bounded semantic version-1 receipt rows with
+printable ASCII text and a stable job key. The miniapp passes its exact
+printer/profile selection to status and submission; the host revalidates that
+destination and owns wrapping, feed, cut, and OS spooler submission. Packages
+must declare the exact descriptor effect
+`{ "kind": "physical-output", "resources": ["receipt-printer"] }` and a
+persisted `printing.receipt` action with reusable consent, `do` autonomy, and
+consequential risk. Raw ESC/POS, direct USB/network access, and `window.print()`
+are not SDK capabilities. Job-key journaling suppresses
+routine reconnect duplicates, but physical exactly-once printing is impossible;
+every result therefore carries `physicalExactlyOnce: false`.
+
 ## Discovery metadata
 
 Descriptor-backed packages may assign up to three unique

package/THIRD_PARTY_NOTICES.md

@@ -9,30 +9,30 @@ distributed as source. Optional peer dependencies are not distributed with
 this package and remain subject to their own licenses.
 
 The inventory below records the direct and transitive runtime dependency
-versions resolved by the release workspace lockfile on July 18, 2026. A
+versions resolved by the release workspace lockfile on July 22, 2026. A
 downstream application may resolve a different compatible transitive version
 and is responsible for reviewing the notices required by its own lockfile and
 distribution artifact.
 
 | Relationship     | Package                        | Version | License      |
 | ---------------- | ------------------------------ | ------: | ------------ |
-| Direct UI        | `@radix-ui/react-alert-dialog` |  1.1.15 | MIT          |
-| Direct UI        | `@radix-ui/react-avatar`       |  1.1.11 | MIT          |
-| Direct UI        | `@radix-ui/react-checkbox`     |   1.3.3 | MIT          |
-| Direct UI        | `@radix-ui/react-compose-refs` |   1.1.2 | MIT          |
-| Direct UI        | `@radix-ui/react-dialog`       |  1.1.15 | MIT          |
-| Direct UI        | `@radix-ui/react-label`        |   2.1.8 | MIT          |
-| Direct UI        | `@radix-ui/react-progress`     |   1.1.8 | MIT          |
-| Direct UI        | `@radix-ui/react-radio-group`  |   1.3.8 | MIT          |
-| Direct UI        | `@radix-ui/react-scroll-area`  |  1.2.10 | MIT          |
-| Direct UI        | `@radix-ui/react-select`       |   2.2.6 | MIT          |
-| Direct UI        | `@radix-ui/react-separator`    |   1.1.8 | MIT          |
-| Direct UI        | `@radix-ui/react-slider`       |   1.3.6 | MIT          |
-| Direct UI        | `@radix-ui/react-slot`         |   1.2.4 | MIT          |
-| Direct UI        | `@radix-ui/react-tabs`         |  1.1.13 | MIT          |
-| Direct UI        | `@radix-ui/react-toggle`       |  1.1.10 | MIT          |
-| Direct UI        | `@radix-ui/react-toggle-group` |  1.1.11 | MIT          |
-| Direct UI        | `@radix-ui/react-tooltip`      |   1.2.8 | MIT          |
+| Direct UI        | `@radix-ui/react-alert-dialog` |  1.1.20 | MIT          |
+| Direct UI        | `@radix-ui/react-avatar`       |   1.2.3 | MIT          |
+| Direct UI        | `@radix-ui/react-checkbox`     |   1.3.8 | MIT          |
+| Direct UI        | `@radix-ui/react-compose-refs` |   1.1.3 | MIT          |
+| Direct UI        | `@radix-ui/react-dialog`       |  1.1.20 | MIT          |
+| Direct UI        | `@radix-ui/react-label`        |  2.1.12 | MIT          |
+| Direct UI        | `@radix-ui/react-progress`     |  1.1.13 | MIT          |
+| Direct UI        | `@radix-ui/react-radio-group`  |   1.4.4 | MIT          |
+| Direct UI        | `@radix-ui/react-scroll-area`  |  1.2.15 | MIT          |
+| Direct UI        | `@radix-ui/react-select`       |   2.3.4 | MIT          |
+| Direct UI        | `@radix-ui/react-separator`    |  1.1.12 | MIT          |
+| Direct UI        | `@radix-ui/react-slider`       |   1.4.4 | MIT          |
+| Direct UI        | `@radix-ui/react-slot`         |   1.3.0 | MIT          |
+| Direct UI        | `@radix-ui/react-tabs`         |  1.1.18 | MIT          |
+| Direct UI        | `@radix-ui/react-toggle`       |  1.1.15 | MIT          |
+| Direct UI        | `@radix-ui/react-toggle-group` |  1.1.16 | MIT          |
+| Direct UI        | `@radix-ui/react-tooltip`      |  1.2.13 | MIT          |
 | Direct UI        | `class-variance-authority`     |   0.7.1 | Apache-2.0   |
 | Direct UI        | `clsx`                         |   2.1.1 | MIT          |
 | Direct UI        | `lucide-react`                 |  1.20.0 | ISC          |

package/dist/index.d.ts

@@ -230,10 +230,17 @@ export declare type MiniAppHttpRequestInput = {
 
 export declare type MiniAppHttpRequestOptions = {
     /**
-     * Opaque host-managed credential reference. Secret material never enters
-     * miniapp JavaScript.
+     * Opaque host-managed credential reference, or the reserved
+     * `platform-session` reference for the active TAP account. Secret material
+     * never enters miniapp JavaScript.
      */
     credentialRef?: string;
+    /**
+     * Requests one host-managed integration credential. The host attaches it
+     * only after the package declares and receives the corresponding credential
+     * permission; secret material never enters miniapp JavaScript.
+     */
+    auth?: 'github';
 };
 
 export declare type MiniAppHttpResponse = {
@@ -323,8 +330,6 @@ export declare type MiniAppPlatformApi = {
         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>;
     };
@@ -348,6 +353,8 @@ export declare type MiniAppPlatformApi = {
     http?: MiniAppHttpApi;
     /** Desktop host capability; feature-detect before use on portable targets. */
     credentials?: MiniAppCredentialsApi;
+    /** Desktop host capability; feature-detect before use on portable targets. */
+    printing?: MiniAppReceiptPrintingApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -403,7 +410,8 @@ export declare type MiniAppProject = {
 export declare type MiniAppProvisionProjectChatOptions = {
     conversationId: string;
     projectId: string;
-    referenceBranch?: string | null;
+    baseBranch?: string | null;
+    workingBranch?: string | null;
 };
 
 export declare type MiniAppProvisionProjectChatResult = {
@@ -412,6 +420,91 @@ export declare type MiniAppProvisionProjectChatResult = {
     worktreeBaseCommit?: string | null;
 };
 
+/** Bounded semantic receipt rendered, wrapped, fed, and cut by the desktop host. */
+export declare type MiniAppReceiptDocument = {
+    version: 1;
+    /** One to 200 rows; each text field is capped at 512 printable ASCII characters. */
+    lines: MiniAppReceiptLine[];
+    /** Defaults to 3 and is capped at 8. */
+    feedLines?: number;
+    /** Defaults to true. */
+    cut?: boolean;
+};
+
+/** One semantic receipt row. Raw printer commands are intentionally absent. */
+export declare type MiniAppReceiptLine = {
+    kind: 'text';
+    text: string;
+    alignment?: MiniAppReceiptTextAlignment;
+    weight?: MiniAppReceiptTextWeight;
+} | {
+    kind: 'key-value';
+    label: string;
+    value: string;
+} | {
+    kind: 'divider';
+} | {
+    kind: 'blank';
+};
+
+/** Host rendering capabilities for one supported receipt paper width. */
+export declare type MiniAppReceiptPaperProfile = {
+    id: MiniAppReceiptPrinterProfile;
+    widthMm: 58 | 80;
+    columns: 32 | 48;
+};
+
+/** Bounded metadata for one machine-local printer visible to an authorized miniapp. */
+export declare type MiniAppReceiptPrinter = {
+    name: string;
+    isDefault: boolean;
+};
+
+export declare type MiniAppReceiptPrinterDiscovery = {
+    printers: MiniAppReceiptPrinter[];
+    paperProfiles: MiniAppReceiptPaperProfile[];
+};
+
+export declare type MiniAppReceiptPrinterProfile = 'receipt-58mm' | 'receipt-80mm';
+
+/** Miniapp-owned selection passed explicitly to status and submission calls. */
+export declare type MiniAppReceiptPrinterSelection = {
+    printerName: string;
+    profile: MiniAppReceiptPrinterProfile;
+};
+
+/** Readiness for an exact machine-local printer selection. */
+export declare type MiniAppReceiptPrinterStatus = {
+    availability: 'ready' | 'unavailable';
+};
+
+/** Desktop-only silent receipt output through a discovered OS spooler. */
+export declare type MiniAppReceiptPrintingApi = {
+    listPrinters(): MiniAppMaybePromise<MiniAppReceiptPrinterDiscovery>;
+    getStatus(selection: MiniAppReceiptPrinterSelection): MiniAppMaybePromise<MiniAppReceiptPrinterStatus>;
+    submit(options: MiniAppReceiptPrintOptions): MiniAppMaybePromise<MiniAppReceiptPrintResult>;
+};
+
+export declare type MiniAppReceiptPrintOptions = {
+    /**
+     * Stable caller key, capped at 128 characters. The host journals it within
+     * installation, workspace, and selected-destination scope.
+     */
+    jobKey: string;
+    selection: MiniAppReceiptPrinterSelection;
+    document: MiniAppReceiptDocument;
+};
+
+export declare type MiniAppReceiptPrintResult = {
+    disposition: 'submitted' | 'duplicate-suppressed' | 'indeterminate';
+    /** Always false: spooler acknowledgement cannot prove physical exactly-once output. */
+    physicalExactlyOnce: false;
+};
+
+export declare type MiniAppReceiptTextAlignment = 'left' | 'center' | 'right';
+
+export declare type MiniAppReceiptTextWeight = 'normal' | 'bold';
+
 export declare type MiniAppSpecialistApi = {
     joinToChannel(channelId: string, specialistId: string): MiniAppMaybePromise<string>;
     listWorkspace(workspaceId: string): MiniAppMaybePromise<MiniAppSpecialistSummary[]>;
@@ -596,21 +689,6 @@ export declare type SendChannelMessageResult = {
     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 ToolDefinition<TArguments = unknown, TResult = unknown> = {
     displayName?: string;
     description: string;

package/dist/rspack/index.js

@@ -358,6 +358,10 @@ const optionalSafeId = (name) => {
   }
   return value;
 };
+const packageTarget = optionalSafeId('target');
+if (packageTarget !== undefined && packageTarget !== 'desktop' && packageTarget !== 'mobile') {
+  throw new Error('Invalid federated surface package target.');
+}
 const exactOrigin = (value) => {
   const origin = new URL(value).origin;
   if (origin === 'null') throw new Error('The TAP host origin must be concrete.');
@@ -453,6 +457,11 @@ const MAX_PRESENCE_JSON_BYTES = 16 * 1024;
 const MAX_HTTP_REQUEST_JSON_BYTES = 11 * 1024 * 1024;
 const MAX_HTTP_URL_CHARS = 64 * 1024;
 const MAX_CREDENTIAL_REFERENCE_CHARS = 512;
+const MAX_RECEIPT_JOB_KEY_CHARS = 128;
+const MAX_RECEIPT_PRINTER_NAME_CHARS = 512;
+const MAX_RECEIPT_LINES = 200;
+const MAX_RECEIPT_LINE_CHARS = 512;
+const MAX_RECEIPT_TOTAL_CHARS = 32768;
 const PRESENCE_EVENT = 'tap-miniapp-presence-event';
 const HOST_ACTION_TIMEOUT_MS = 4000;
 const pendingHostActions = new Map();
@@ -774,6 +783,12 @@ const http = Object.freeze({
         !validPlatformPartition(options.credentialRef, MAX_CREDENTIAL_REFERENCE_CHARS)) {
       throw new Error('app.http.request credentialRef is invalid.');
     }
+    if (options.auth !== undefined && options.auth !== 'github') {
+      throw new Error('app.http.request auth is invalid.');
+    }
+    if (options.credentialRef !== undefined && options.auth !== undefined) {
+      throw new Error('app.http.request accepts either credentialRef or auth, not both.');
+    }
     return invokeSdkHostAction(
       'tap.platform.http.request',
       {
@@ -781,6 +796,7 @@ const http = Object.freeze({
         ...(options.credentialRef === undefined
           ? {}
           : { credentialRef: options.credentialRef }),
+        ...(options.auth === undefined ? {} : { auth: options.auth }),
       },
       'app.http.request',
       null,
@@ -820,6 +836,142 @@ const credentials = Object.freeze({
     });
   },
 });
+const checkedReceiptDocument = (document) => {
+  requireOptionsObject(document, 'app.printing.submit document');
+  if (document.version !== 1 || !Array.isArray(document.lines) ||
+      document.lines.length < 1 || document.lines.length > MAX_RECEIPT_LINES ||
+      Object.keys(document).some(
+        (key) => !new Set(['version', 'lines', 'feedLines', 'cut']).has(key),
+      ) ||
+      (document.feedLines !== undefined &&
+        (!Number.isInteger(document.feedLines) || document.feedLines < 0 || document.feedLines > 8)) ||
+      (document.cut !== undefined && typeof document.cut !== 'boolean')) {
+    throw new Error('app.printing.submit document is invalid.');
+  }
+  let totalChars = 0;
+  const text = (value) => {
+    if (typeof value !== 'string' || value.length > MAX_RECEIPT_LINE_CHARS ||
+        /[^\u0020-\u007e]/u.test(value)) {
+      throw new Error('app.printing.submit receipt text is invalid.');
+    }
+    totalChars += value.length;
+  };
+  for (const line of document.lines) {
+    requireOptionsObject(line, 'app.printing.submit receipt line');
+    const keys = Object.keys(line);
+    if (line.kind === 'text') {
+      text(line.text);
+      if ((line.alignment !== undefined && !new Set(['left', 'center', 'right']).has(line.alignment)) ||
+          (line.weight !== undefined && !new Set(['normal', 'bold']).has(line.weight)) ||
+          keys.some((key) => !new Set(['kind', 'text', 'alignment', 'weight']).has(key))) {
+        throw new Error('app.printing.submit text line is invalid.');
+      }
+    } else if (line.kind === 'key-value') {
+      text(line.label);
+      text(line.value);
+      if (keys.some((key) => !new Set(['kind', 'label', 'value']).has(key))) {
+        throw new Error('app.printing.submit key-value line is invalid.');
+      }
+    } else if ((line.kind !== 'divider' && line.kind !== 'blank') || keys.length !== 1) {
+      throw new Error('app.printing.submit receipt line is invalid.');
+    }
+  }
+  if (totalChars > MAX_RECEIPT_TOTAL_CHARS) {
+    throw new Error('app.printing.submit receipt text exceeds the allowed size.');
+  }
+  return document;
+};
+const checkedPrinterSelection = (selection, operation) => {
+  requireOptionsObject(selection, operation + ' selection');
+  if (Object.keys(selection).some((key) => !new Set(['printerName', 'profile']).has(key)) ||
+      !validPlatformPartition(selection.printerName, MAX_RECEIPT_PRINTER_NAME_CHARS) ||
+      !new Set(['receipt-58mm', 'receipt-80mm']).has(selection.profile)) {
+    throw new Error(operation + ' selection is invalid.');
+  }
+  return selection;
+};
+const printing = Object.freeze({
+  listPrinters() {
+    return invokeSdkHostAction(
+      'tap.platform.printing.receipt.v2.list-printers',
+      {},
+      'app.printing.listPrinters',
+      30000,
+    ).then((value) => {
+      if (!value || typeof value !== 'object' || Array.isArray(value) ||
+          !Array.isArray(value.printers) || !Array.isArray(value.paperProfiles)) {
+        throw new Error('app.printing.listPrinters returned an invalid result.');
+      }
+      const printers = value.printers.map((printer) => {
+        if (!printer || typeof printer !== 'object' || Array.isArray(printer) ||
+            Object.keys(printer).some((key) => !new Set(['name', 'isDefault']).has(key)) ||
+            !validPlatformPartition(printer.name, MAX_RECEIPT_PRINTER_NAME_CHARS) ||
+            typeof printer.isDefault !== 'boolean') {
+          throw new Error('app.printing.listPrinters returned an invalid printer.');
+        }
+        return projectResultFields(printer, ['name', 'isDefault'], 'app.printing.listPrinters');
+      });
+      const paperProfiles = value.paperProfiles.map((profile) => {
+        const expected = profile?.id === 'receipt-58mm' ? [58, 32]
+          : profile?.id === 'receipt-80mm' ? [80, 48] : null;
+        if (!profile || typeof profile !== 'object' || Array.isArray(profile) || !expected ||
+            Object.keys(profile).some((key) => !new Set(['id', 'widthMm', 'columns']).has(key)) ||
+            profile.widthMm !== expected[0] || profile.columns !== expected[1]) {
+          throw new Error('app.printing.listPrinters returned an invalid paper profile.');
+        }
+        return projectResultFields(
+          profile,
+          ['id', 'widthMm', 'columns'],
+          'app.printing.listPrinters',
+        );
+      });
+      return { printers, paperProfiles };
+    });
+  },
+  getStatus(selection) {
+    checkedPrinterSelection(selection, 'app.printing.getStatus');
+    return invokeSdkHostAction(
+      'tap.platform.printing.receipt.v2.status',
+      selection,
+      'app.printing.getStatus',
+      30000,
+    ).then((value) => {
+      if (!value || typeof value !== 'object' || Array.isArray(value) ||
+          !new Set(['ready', 'unavailable']).has(value.availability)) {
+        throw new Error('app.printing.getStatus returned an invalid result.');
+      }
+      return projectResultFields(value, ['availability'], 'app.printing.getStatus');
+    });
+  },
+  submit(options) {
+    requireOptionsObject(options, 'app.printing.submit');
+    if (Object.keys(options).some((key) => !new Set(['jobKey', 'selection', 'document']).has(key)) ||
+        !validPlatformPartition(options.jobKey, MAX_RECEIPT_JOB_KEY_CHARS)) {
+      throw new Error('app.printing.submit jobKey is invalid.');
+    }
+    checkedPrinterSelection(options.selection, 'app.printing.submit');
+    checkedReceiptDocument(options.document);
+    return invokeSdkHostAction(
+      'tap.platform.printing.receipt.v2.submit',
+      options,
+      'app.printing.submit',
+      // Physical output cannot be cancelled when an SDK timer expires. Keep
+      // the request correlated until the host reports its journaled outcome.
+      null,
+    ).then((value) => {
+      if (!value || typeof value !== 'object' || Array.isArray(value) ||
+          !new Set(['submitted', 'duplicate-suppressed', 'indeterminate']).has(value.disposition) ||
+          value.physicalExactlyOnce !== false) {
+        throw new Error('app.printing.submit returned an invalid result.');
+      }
+      return projectResultFields(
+        value,
+        ['disposition', 'physicalExactlyOnce'],
+        'app.printing.submit',
+      );
+    });
+  },
+});
 const channels = Object.freeze({
   create(options) {
     requireOptionString(options?.name, 'app.channels.create name');
@@ -833,33 +985,6 @@ const channels = Object.freeze({
     requireOptionString(options?.content, 'app.channels.sendMessage content');
     return invokeSdkHostAction('sendChannelMessage', options, 'app.channels.sendMessage');
   },
-  sendSpecialistMessage(options) {
-    requireOptionString(
-      options?.channelId,
-      'app.channels.sendSpecialistMessage channelId',
-    );
-    requireOptionString(
-      options?.specialistId,
-      'app.channels.sendSpecialistMessage specialistId',
-    );
-    requireOptionString(
-      options?.projectId,
-      'app.channels.sendSpecialistMessage projectId',
-    );
-    requireOptionString(
-      options?.clientMessageId,
-      'app.channels.sendSpecialistMessage clientMessageId',
-    );
-    requireOptionString(
-      options?.body,
-      'app.channels.sendSpecialistMessage body',
-    );
-    return invokeSdkHostAction(
-      'sendSpecialistChannelMessage',
-      options,
-      'app.channels.sendSpecialistMessage',
-    );
-  },
   getAccess(options) {
     requireOptionString(options?.channelId, 'app.channels.getAccess channelId');
     return invokeSdkHostAction('getChannelAccess', options, 'app.channels.getAccess');
@@ -1098,6 +1223,7 @@ const miniappSdk = Object.freeze({
   presence,
   http,
   credentials,
+  ...(packageTarget === 'desktop' ? { printing } : {}),
   auth: platformAuth,
   vfs: platformVfs,
   specialist: platformSpecialist,

package/dist/sdk.d.ts

@@ -201,10 +201,17 @@ export declare type MiniAppHttpRequestInput = {
 
 export declare type MiniAppHttpRequestOptions = {
     /**
-     * Opaque host-managed credential reference. Secret material never enters
-     * miniapp JavaScript.
+     * Opaque host-managed credential reference, or the reserved
+     * `platform-session` reference for the active TAP account. Secret material
+     * never enters miniapp JavaScript.
      */
     credentialRef?: string;
+    /**
+     * Requests one host-managed integration credential. The host attaches it
+     * only after the package declares and receives the corresponding credential
+     * permission; secret material never enters miniapp JavaScript.
+     */
+    auth?: 'github';
 };
 
 export declare type MiniAppHttpResponse = {
@@ -294,8 +301,6 @@ export declare type MiniAppPlatformApi = {
         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>;
     };
@@ -319,6 +324,8 @@ export declare type MiniAppPlatformApi = {
     http?: MiniAppHttpApi;
     /** Desktop host capability; feature-detect before use on portable targets. */
     credentials?: MiniAppCredentialsApi;
+    /** Desktop host capability; feature-detect before use on portable targets. */
+    printing?: MiniAppReceiptPrintingApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -374,7 +381,8 @@ export declare type MiniAppProject = {
 export declare type MiniAppProvisionProjectChatOptions = {
     conversationId: string;
     projectId: string;
-    referenceBranch?: string | null;
+    baseBranch?: string | null;
+    workingBranch?: string | null;
 };
 
 export declare type MiniAppProvisionProjectChatResult = {
@@ -383,6 +391,91 @@ export declare type MiniAppProvisionProjectChatResult = {
     worktreeBaseCommit?: string | null;
 };
 
+/** Bounded semantic receipt rendered, wrapped, fed, and cut by the desktop host. */
+export declare type MiniAppReceiptDocument = {
+    version: 1;
+    /** One to 200 rows; each text field is capped at 512 printable ASCII characters. */
+    lines: MiniAppReceiptLine[];
+    /** Defaults to 3 and is capped at 8. */
+    feedLines?: number;
+    /** Defaults to true. */
+    cut?: boolean;
+};
+
+/** One semantic receipt row. Raw printer commands are intentionally absent. */
+export declare type MiniAppReceiptLine = {
+    kind: 'text';
+    text: string;
+    alignment?: MiniAppReceiptTextAlignment;
+    weight?: MiniAppReceiptTextWeight;
+} | {
+    kind: 'key-value';
+    label: string;
+    value: string;
+} | {
+    kind: 'divider';
+} | {
+    kind: 'blank';
+};
+
+/** Host rendering capabilities for one supported receipt paper width. */
+export declare type MiniAppReceiptPaperProfile = {
+    id: MiniAppReceiptPrinterProfile;
+    widthMm: 58 | 80;
+    columns: 32 | 48;
+};
+
+/** Bounded metadata for one machine-local printer visible to an authorized miniapp. */
+export declare type MiniAppReceiptPrinter = {
+    name: string;
+    isDefault: boolean;
+};
+
+export declare type MiniAppReceiptPrinterDiscovery = {
+    printers: MiniAppReceiptPrinter[];
+    paperProfiles: MiniAppReceiptPaperProfile[];
+};
+
+export declare type MiniAppReceiptPrinterProfile = 'receipt-58mm' | 'receipt-80mm';
+
+/** Miniapp-owned selection passed explicitly to status and submission calls. */
+export declare type MiniAppReceiptPrinterSelection = {
+    printerName: string;
+    profile: MiniAppReceiptPrinterProfile;
+};
+
+/** Readiness for an exact machine-local printer selection. */
+export declare type MiniAppReceiptPrinterStatus = {
+    availability: 'ready' | 'unavailable';
+};
+
+/** Desktop-only silent receipt output through a discovered OS spooler. */
+export declare type MiniAppReceiptPrintingApi = {
+    listPrinters(): MiniAppMaybePromise<MiniAppReceiptPrinterDiscovery>;
+    getStatus(selection: MiniAppReceiptPrinterSelection): MiniAppMaybePromise<MiniAppReceiptPrinterStatus>;
+    submit(options: MiniAppReceiptPrintOptions): MiniAppMaybePromise<MiniAppReceiptPrintResult>;
+};
+
+export declare type MiniAppReceiptPrintOptions = {
+    /**
+     * Stable caller key, capped at 128 characters. The host journals it within
+     * installation, workspace, and selected-destination scope.
+     */
+    jobKey: string;
+    selection: MiniAppReceiptPrinterSelection;
+    document: MiniAppReceiptDocument;
+};
+
+export declare type MiniAppReceiptPrintResult = {
+    disposition: 'submitted' | 'duplicate-suppressed' | 'indeterminate';
+    /** Always false: spooler acknowledgement cannot prove physical exactly-once output. */
+    physicalExactlyOnce: false;
+};
+
+export declare type MiniAppReceiptTextAlignment = 'left' | 'center' | 'right';
+
+export declare type MiniAppReceiptTextWeight = 'normal' | 'bold';
+
 export declare type MiniAppSpecialistApi = {
     joinToChannel(channelId: string, specialistId: string): MiniAppMaybePromise<string>;
     listWorkspace(workspaceId: string): MiniAppMaybePromise<MiniAppSpecialistSummary[]>;
@@ -567,21 +660,6 @@ export declare type SendChannelMessageResult = {
     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;

package/dist/web.d.ts

@@ -239,10 +239,17 @@ declare type MiniAppHttpRequestInput = {
 
 declare type MiniAppHttpRequestOptions = {
     /**
-     * Opaque host-managed credential reference. Secret material never enters
-     * miniapp JavaScript.
+     * Opaque host-managed credential reference, or the reserved
+     * `platform-session` reference for the active TAP account. Secret material
+     * never enters miniapp JavaScript.
      */
     credentialRef?: string;
+    /**
+     * Requests one host-managed integration credential. The host attaches it
+     * only after the package declares and receives the corresponding credential
+     * permission; secret material never enters miniapp JavaScript.
+     */
+    auth?: 'github';
 };
 
 declare type MiniAppHttpResponse = {
@@ -335,8 +342,6 @@ export declare type MiniAppPlatformApi = {
         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>;
     };
@@ -360,6 +365,8 @@ export declare type MiniAppPlatformApi = {
     http?: MiniAppHttpApi;
     /** Desktop host capability; feature-detect before use on portable targets. */
     credentials?: MiniAppCredentialsApi;
+    /** Desktop host capability; feature-detect before use on portable targets. */
+    printing?: MiniAppReceiptPrintingApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -415,7 +422,8 @@ declare type MiniAppProject = {
 declare type MiniAppProvisionProjectChatOptions = {
     conversationId: string;
     projectId: string;
-    referenceBranch?: string | null;
+    baseBranch?: string | null;
+    workingBranch?: string | null;
 };
 
 declare type MiniAppProvisionProjectChatResult = {
@@ -424,6 +432,91 @@ declare type MiniAppProvisionProjectChatResult = {
     worktreeBaseCommit?: string | null;
 };
 
+/** Bounded semantic receipt rendered, wrapped, fed, and cut by the desktop host. */
+declare type MiniAppReceiptDocument = {
+    version: 1;
+    /** One to 200 rows; each text field is capped at 512 printable ASCII characters. */
+    lines: MiniAppReceiptLine[];
+    /** Defaults to 3 and is capped at 8. */
+    feedLines?: number;
+    /** Defaults to true. */
+    cut?: boolean;
+};
+
+/** One semantic receipt row. Raw printer commands are intentionally absent. */
+declare type MiniAppReceiptLine = {
+    kind: 'text';
+    text: string;
+    alignment?: MiniAppReceiptTextAlignment;
+    weight?: MiniAppReceiptTextWeight;
+} | {
+    kind: 'key-value';
+    label: string;
+    value: string;
+} | {
+    kind: 'divider';
+} | {
+    kind: 'blank';
+};
+
+/** Host rendering capabilities for one supported receipt paper width. */
+declare type MiniAppReceiptPaperProfile = {
+    id: MiniAppReceiptPrinterProfile;
+    widthMm: 58 | 80;
+    columns: 32 | 48;
+};
+
+/** Bounded metadata for one machine-local printer visible to an authorized miniapp. */
+declare type MiniAppReceiptPrinter = {
+    name: string;
+    isDefault: boolean;
+};
+
+declare type MiniAppReceiptPrinterDiscovery = {
+    printers: MiniAppReceiptPrinter[];
+    paperProfiles: MiniAppReceiptPaperProfile[];
+};
+
+declare type MiniAppReceiptPrinterProfile = 'receipt-58mm' | 'receipt-80mm';
+
+/** Miniapp-owned selection passed explicitly to status and submission calls. */
+declare type MiniAppReceiptPrinterSelection = {
+    printerName: string;
+    profile: MiniAppReceiptPrinterProfile;
+};
+
+/** Readiness for an exact machine-local printer selection. */
+declare type MiniAppReceiptPrinterStatus = {
+    availability: 'ready' | 'unavailable';
+};
+
+/** Desktop-only silent receipt output through a discovered OS spooler. */
+declare type MiniAppReceiptPrintingApi = {
+    listPrinters(): MiniAppMaybePromise<MiniAppReceiptPrinterDiscovery>;
+    getStatus(selection: MiniAppReceiptPrinterSelection): MiniAppMaybePromise<MiniAppReceiptPrinterStatus>;
+    submit(options: MiniAppReceiptPrintOptions): MiniAppMaybePromise<MiniAppReceiptPrintResult>;
+};
+
+declare type MiniAppReceiptPrintOptions = {
+    /**
+     * Stable caller key, capped at 128 characters. The host journals it within
+     * installation, workspace, and selected-destination scope.
+     */
+    jobKey: string;
+    selection: MiniAppReceiptPrinterSelection;
+    document: MiniAppReceiptDocument;
+};
+
+declare type MiniAppReceiptPrintResult = {
+    disposition: 'submitted' | 'duplicate-suppressed' | 'indeterminate';
+    /** Always false: spooler acknowledgement cannot prove physical exactly-once output. */
+    physicalExactlyOnce: false;
+};
+
+declare type MiniAppReceiptTextAlignment = 'left' | 'center' | 'right';
+
+declare type MiniAppReceiptTextWeight = 'normal' | 'bold';
+
 declare type MiniAppSpecialistApi = {
     joinToChannel(channelId: string, specialistId: string): MiniAppMaybePromise<string>;
     listWorkspace(workspaceId: string): MiniAppMaybePromise<MiniAppSpecialistSummary[]>;
@@ -624,21 +717,6 @@ declare type SendChannelMessageResult = {
     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 = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theaiplatform/miniapp-sdk",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "Public SDK for building portable miniapps that run in The AI Platform.",
   "type": "module",
   "engines": {
@@ -177,23 +177,23 @@
     "typescript": "catalog:typescript"
   },
   "dependencies": {
-    "@radix-ui/react-alert-dialog": "^1.1.15",
-    "@radix-ui/react-avatar": "1.1.11",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-compose-refs": "^1.1.2",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-progress": "^1.1.8",
-    "@radix-ui/react-radio-group": "^1.3.8",
-    "@radix-ui/react-scroll-area": "^1.2.10",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.8",
-    "@radix-ui/react-slider": "^1.3.6",
-    "@radix-ui/react-slot": "^1.2.4",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-toggle": "^1.1.10",
-    "@radix-ui/react-toggle-group": "^1.1.11",
-    "@radix-ui/react-tooltip": "^1.2.8",
+    "@radix-ui/react-alert-dialog": "^1.1.20",
+    "@radix-ui/react-avatar": "1.2.3",
+    "@radix-ui/react-checkbox": "^1.3.8",
+    "@radix-ui/react-compose-refs": "^1.1.3",
+    "@radix-ui/react-dialog": "^1.1.20",
+    "@radix-ui/react-label": "^2.1.12",
+    "@radix-ui/react-progress": "^1.1.13",
+    "@radix-ui/react-radio-group": "^1.4.4",
+    "@radix-ui/react-scroll-area": "^1.2.15",
+    "@radix-ui/react-select": "^2.3.4",
+    "@radix-ui/react-separator": "^1.1.12",
+    "@radix-ui/react-slider": "^1.4.4",
+    "@radix-ui/react-slot": "^1.3.0",
+    "@radix-ui/react-tabs": "^1.1.18",
+    "@radix-ui/react-toggle": "^1.1.15",
+    "@radix-ui/react-toggle-group": "^1.1.16",
+    "@radix-ui/react-tooltip": "^1.2.13",
     "ajv": "^8.20.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",