@theaiplatform/miniapp-sdk 0.2.0 → 0.2.2

package/README.md

@@ -40,6 +40,17 @@ 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 accepts only
+bounded semantic version-1 receipt rows with printable ASCII text and a stable job key; the host chooses
+the machine-local printer/profile 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. Printer identity, 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/dist/index.d.ts

@@ -348,6 +348,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;
@@ -412,6 +414,64 @@ 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';
+};
+
+/** Abstract machine-local printer readiness; destination identity stays host-only. */
+export declare type MiniAppReceiptPrinterStatus = {
+    availability: 'unconfigured' | 'ready' | 'unavailable';
+    profile: 'receipt-58mm' | 'receipt-80mm' | null;
+};
+
+/** Desktop-only silent receipt output through the host-configured OS spooler. */
+export declare type MiniAppReceiptPrintingApi = {
+    getStatus(): 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 configured-destination scope.
+     */
+    jobKey: string;
+    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[]>;

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,10 @@ 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_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();
@@ -820,6 +828,95 @@ 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 printing = Object.freeze({
+  getStatus() {
+    return invokeSdkHostAction(
+      'tap.platform.printing.receipt.status',
+      {},
+      'app.printing.getStatus',
+      30000,
+    ).then((value) => {
+      if (!value || typeof value !== 'object' || Array.isArray(value) ||
+          !new Set(['unconfigured', 'ready', 'unavailable']).has(value.availability) ||
+          !new Set([null, 'receipt-58mm', 'receipt-80mm']).has(value.profile)) {
+        throw new Error('app.printing.getStatus returned an invalid result.');
+      }
+      return projectResultFields(value, ['availability', 'profile'], 'app.printing.getStatus');
+    });
+  },
+  submit(options) {
+    requireOptionsObject(options, 'app.printing.submit');
+    if (Object.keys(options).some((key) => !new Set(['jobKey', 'document']).has(key)) ||
+        !validPlatformPartition(options.jobKey, MAX_RECEIPT_JOB_KEY_CHARS)) {
+      throw new Error('app.printing.submit jobKey is invalid.');
+    }
+    checkedReceiptDocument(options.document);
+    return invokeSdkHostAction(
+      'tap.platform.printing.receipt.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');
@@ -1098,6 +1195,7 @@ const miniappSdk = Object.freeze({
   presence,
   http,
   credentials,
+  ...(packageTarget === 'desktop' ? { printing } : {}),
   auth: platformAuth,
   vfs: platformVfs,
   specialist: platformSpecialist,

package/dist/sdk.d.ts

@@ -319,6 +319,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;
@@ -383,6 +385,64 @@ 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';
+};
+
+/** Abstract machine-local printer readiness; destination identity stays host-only. */
+export declare type MiniAppReceiptPrinterStatus = {
+    availability: 'unconfigured' | 'ready' | 'unavailable';
+    profile: 'receipt-58mm' | 'receipt-80mm' | null;
+};
+
+/** Desktop-only silent receipt output through the host-configured OS spooler. */
+export declare type MiniAppReceiptPrintingApi = {
+    getStatus(): 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 configured-destination scope.
+     */
+    jobKey: string;
+    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[]>;

package/dist/web.d.ts

@@ -360,6 +360,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;
@@ -424,6 +426,64 @@ 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';
+};
+
+/** Abstract machine-local printer readiness; destination identity stays host-only. */
+declare type MiniAppReceiptPrinterStatus = {
+    availability: 'unconfigured' | 'ready' | 'unavailable';
+    profile: 'receipt-58mm' | 'receipt-80mm' | null;
+};
+
+/** Desktop-only silent receipt output through the host-configured OS spooler. */
+declare type MiniAppReceiptPrintingApi = {
+    getStatus(): 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 configured-destination scope.
+     */
+    jobKey: string;
+    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[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theaiplatform/miniapp-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Public SDK for building portable miniapps that run in The AI Platform.",
   "type": "module",
   "engines": {
@@ -67,9 +67,60 @@
     "LICENSE.md",
     "THIRD_PARTY_NOTICES.md"
   ],
+  "scripts": {
+    "prepack": "pnpm run build",
+    "build": "rm -rf dist && rslib build && node scripts/copy-rspack-loaders.mjs && node scripts/build-ui-styles.mjs",
+    "test": "rstest run",
+    "typecheck": "tsc --noEmit"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
-    "access": "public"
+    "access": "public",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "./sdk": {
+        "types": "./dist/sdk.d.ts",
+        "import": "./dist/sdk.js"
+      },
+      "./mcp": {
+        "types": "./dist/mcp.d.ts",
+        "import": "./dist/mcp.js"
+      },
+      "./web": {
+        "types": "./dist/web.d.ts",
+        "import": "./dist/web.js"
+      },
+      "./ui": {
+        "types": "./dist/ui.d.ts",
+        "import": "./dist/ui.js"
+      },
+      "./ui/wasm": {
+        "types": "./dist/ui/wasm.d.ts",
+        "import": "./dist/ui/wasm.js"
+      },
+      "./ui/styles.css": "./dist/ui/styles.css",
+      "./ui/tailwind.css": "./dist/ui/tailwind.css",
+      "./ui-components.json": "./ui-components.json",
+      "./surface": {
+        "types": "./dist/surface.d.ts",
+        "import": "./dist/surface.js"
+      },
+      "./config": {
+        "types": "./dist/config.d.ts",
+        "import": "./dist/config.js"
+      },
+      "./rspack": {
+        "types": "./dist/rspack/index.d.ts",
+        "import": "./dist/rspack/index.js"
+      },
+      "./config-schema.json": "./config-schema.json"
+    }
   },
   "peerDependencies": {
     "@module-federation/rsbuild-plugin": "2.8.0",
@@ -113,17 +164,17 @@
     "@module-federation/runtime-tools": "2.8.0",
     "@rsbuild/core": "^2.1.4",
     "@rslib/core": "^0.23.2",
-    "@rstest/core": "^0.9.10",
+    "@rstest/core": "catalog:rstest",
     "@tailwindcss/postcss": "^4.3.0",
     "@types/jsdom": "^28.0.3",
-    "@types/node": "^25.7.0",
-    "@types/react": "19.2.14",
-    "@types/react-dom": "19.2.3",
+    "@types/node": "catalog:node",
+    "@types/react": "catalog:react",
+    "@types/react-dom": "catalog:react",
     "jsdom": "^29.1.1",
     "postcss": "^8.5.6",
     "tailwindcss": "^4.3.0",
     "tw-animate-css": "^1.4.0",
-    "typescript": "npm:@typescript/typescript6@6.0.2"
+    "typescript": "catalog:typescript"
   },
   "dependencies": {
     "@radix-ui/react-alert-dialog": "^1.1.15",
@@ -152,11 +203,5 @@
     "saxes": "^6.0.0",
     "tailwind-merge": "^3.6.0",
     "zod": "^4.4.3"
-  },
-  "scripts": {
-    "build": "rm -rf dist && rslib build && node scripts/copy-rspack-loaders.mjs && node scripts/build-ui-styles.mjs",
-    "test": "rstest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "module": "./dist/index.js"
-}
+  }
+}