SDK & CLI

#Các gói

Phiên bản gói đi theo api_version: gói 2026.1.x dùng cho "api_version": "2026-01". CLI báo lỗi nếu hai giá trị không khớp.

#SDK và runtime của POS

Code chạy trong sandbox gồm hai phần, do hai bên khác nhau cung cấp:

Worker trong sandbox của app
┌─────────────────────────────────────────────────────┐
│ Bundle của app (shop build và upload)               │
│   module extension + Preact hoặc JS thuần           │
├─────────────────────────────────────────────────────┤
│ Runtime POS (POS cung cấp, không nằm trong bundle)  │
│   DOM tối giản · element pos-* · biến toàn cục pos  │
│   kênh postMessage · app token · gọi Open API       │
└─────────────────────────────────────────────────────┘

• Runtime POS do POS nạp sẵn vào worker trước module của app. Vì runtime không nằm trong bundle, POS sửa lỗi bảo mật hoặc cải thiện runtime mà app không phải deploy lại, và module của app nhỏ.
• @pancake-pos/ui-extensions khi dùng trong extensions/ chủ yếu cung cấp type và helper; gần như không thêm code vào bundle.
• Trang iframe không có runtime nạp sẵn: app import connect() từ @pancake-pos/ui-extensions/page, đoạn client nhỏ này được bundle cùng trang.

#Việc SDK và runtime lo thay app

#Cài đặt

Dự án tạo bằng create-pos-app đã cài sẵn. Thêm vào dự án có sẵn:

npm install @pancake-pos/ui-extensions preact
npm install -D @pancake-pos/app-cli typescript eslint @pancake-pos/eslint-plugin
npm install @pancake-pos/ui react react-dom   # chỉ khi có trang iframe

#TypeScript

tsconfig.json ở gốc dự án dùng cho extensions/:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "strict": true,
    "types": ["@pancake-pos/ui-extensions"]
  },
  "include": ["extensions"]
}

• types khai báo biến toàn cục pos và các element pos-* cho JSX (thuộc tính, sự kiện, event.detail).
• Trang page/ có page/tsconfig.json riêng với "jsxImportSource": "react", do template sinh sẵn; không gộp chung vào tsconfig gốc.
• extensions/ hỗ trợ Preact (khuyến nghị, nhẹ) và JS thuần dùng DOM API của runtime. Chưa hỗ trợ React trong extensions/: React 18 truyền thuộc tính dạng mảng/đối tượng thành chuỗi và không nghe được sự kiện của element pos-*; React 19 đang được đánh giá. Trang iframe dùng React bình thường.

#defineExtension

Helper không bắt buộc, giúp type của tham số data và giá trị trả về khớp với target.

import { defineExtension } from '@pancake-pos/ui-extensions';

export default defineExtension('order.before_submit', async (data) => {
  // data: DetailsData<'order'>, phải trả BeforeSubmitResult
  if (data.draft.total_price > 20_000_000 && !data.draft.bill_phone_number) {
    return { ok: false, message: 'Đơn lớn cần số điện thoại.' };
  }
  return { ok: true };
});

defineExtension chỉ trả lại đúng hàm truyền vào, nên tương đương export default async function (data).

Resource lấy theo tên target, nên cùng helper này cho data.draft kiểu PurchaseDraft trong purchase.before_submit, hay data.records kiểu WarehouseTransferRef[] trong warehouse_transfer.index.selection-action.

Các type xuất ra từ gói: Resource, DetailsData, IndexData, SelectionData, AfterSaveInput, BeforeSubmitResult, HeadlessActionResult, PageData, cặp Ref/Draft của từng resource (OrderRef, OrderDraft, ProductRef, ProductDraft, PurchaseRef, PurchaseDraft, ExportRef, ExportDraft, WarehouseTransferRef, WarehouseTransferDraft), PosApiError, PosRuntimeError.

#Trang iframe

import { connect } from '@pancake-pos/ui-extensions/page';

const pos = await connect({ timeout: 10_000 });

• connect() chờ POS gửi ngữ cảnh và token; quá timeout (mặc định 10 giây) thì ném lỗi, thường do mở trang ngoài POS.
• Trang chỉ chạy trong iframe của POS. Mở URL sandbox trên tab hay cửa sổ riêng, kể cả popup do trang tự mở, sẽ bị từ chối (403). Luồng đăng nhập kiểu popup phải quay về trang của bạn ngoài sandbox, rồi báo lại cho app qua server của bạn.
• pos của trang có cùng API như trong worker, thêm pos.page.*. Xem Runtime API.

#CLI (pos-app)

Mọi lệnh nhận --json để trả kết quả dạng máy đọc được (CI, script, MCP server).

Lệnh pos-app có trong dự án sau khi cài @pancake-pos/app-cli, nên npx pos-app … chạy được trong thư mục dự án. Ngoài dự án, gọi theo tên gói: npx @pancake-pos/app-cli <lệnh>. Gói pos-app trên npm không phải của Pancake.

Kích hoạt và rollback làm trên trang quản lý ứng dụng tuỳ biến trong POS, để admin luôn duyệt quyền trước khi app chạy.

#pos-app check

Kiểm tra tĩnh, chạy tự động trước deploy. Đặc biệt hữu ích khi code do AI sinh:

• Manifest: hợp lệ theo schema, báo đúng dòng; target có trong api_version; file module/entry tồn tại; khoá conditions hợp lệ theo resource.
• Code: chạy bộ luật kiểm tra code với cấu hình có sẵn, không cần cấu hình gì trong dự án.
• Kích thước module và bundle trong giới hạn.

Lỗi mức error chặn deploy; warning chỉ báo. Mỗi lỗi có file, dòng, mã luật và gợi ý sửa (--json cho CI và MCP). pos-app check bỏ qua comment eslint-disable, nên tắt luật trong code không vượt được bước kiểm tra này.

#Luật kiểm tra code

Bộ luật nằm trong gói @pancake-pos/eslint-plugin. Luật về element sinh từ danh mục component của đúng api_version, nên luôn khớp với POS.

Kiểm tra tĩnh không bắt được trường hợp động, ví dụ tên element tạo từ biến. Ở chế độ phát triển, POS cảnh báo thêm trong console khi chạy.

#Báo lỗi trong editor

Dự án tạo bằng create-pos-app có sẵn eslint.config.js:

import posApp from '@pancake-pos/eslint-plugin';

// recommended đọc pos-app.json để biết api_version, access và allowed_origins
export default [...posApp.configs.recommended];

Cài extension ESLint cho editor (VS Code, Cursor…) để thấy lỗi ngay khi gõ. npx eslint . cho cùng kết quả với phần code của pos-app check.

#Kết quả build

dist/
├─ pos-app.json              # manifest, đường dẫn module đã đổi sang file build
├─ ext/
│  ├─ order-block.js         # mỗi module một file ES module, đã gồm Preact
│  └─ push-erp.js
├─ public/                   # ảnh cho pos-image, chép nguyên từ dự án
└─ page/                     # trang iframe do Vite build
   ├─ index.html
   └─ assets/...

• Module extension build bằng esbuild, đích ES2020, không tách chunk, không import từ CDN.
• Trang iframe build bằng Vite với cấu hình có sẵn trong template.

#MCP

pos-app mcp chạy một MCP server (stdio) để công cụ AI tra tài liệu, xem dữ liệu nền thật của shop, kiểm tra app, chạy thử, đọc lỗi, deploy và báo lỗi cho Pancake ngay trong cuộc trò chuyện.

npx @pancake-pos/app-cli mcp --shop 123          # chạy trong thư mục dự án app, hoặc thêm --cwd <thư mục>

Cách thêm server vào Claude Code, Cursor, VS Code, Codex, Claude Desktop, danh sách tool và câu lệnh mẫu: Làm app với AI › MCP.