# SDK & CLI

## Các gói

| Gói | Dùng ở | Vai trò |
|---|---|---|
| `@pancake-pos/ui-extensions` | `extensions/`, `page/` | Type cho `pos` và element `pos-*`, helper `defineExtension`, client cho trang iframe (`/page`) |
| `@pancake-pos/ui` | `page/` | Component React cùng tên, thuộc tính với element `pos-*`, `PosProvider`, theme, font, token của POS cho trang iframe ([Giao diện trang iframe](/developers/apps/page-ui)) |
| `@pancake-pos/app-cli` | Máy dev, CI | Lệnh `pos-app`: đăng nhập, chạy thử, kiểm tra, build, upload |
| `@pancake-pos/eslint-plugin` | Editor, `pos-app check` | Luật kiểm tra code cho app; editor báo lỗi ngay khi gõ |
| `create-pos-app` | Một lần | Tạo dự án mẫu, cài sẵn các gói trên và `AGENTS.md` |

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:

```text
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

| Việc | Chi tiết |
|---|---|
| Kênh giao tiếp | postMessage giữa sandbox và POS, kiểm tra nguồn gửi, gửi lệnh và sự kiện hai chiều |
| Xác thực | Lấy app token, gia hạn trước khi hết hạn, gặp 401 thì lấy token mới và thử lại 1 lần |
| Gọi Open API | `pos.api.*`, gắn header `Authorization`, chặn method ngoài `access.methods`, đổi lỗi thành `PosApiError` |
| Worker UI | DOM tối giản, định nghĩa element `pos-*`, gom thay đổi gửi về POS theo lô, chuyển sự kiện từ POS vào worker |
| Ngữ cảnh | Cập nhật `pos.data`, phát sự kiện `data-change` |
| Trang iframe | Đồng bộ URL với POS, `setTitle`, `setPrimaryAction`, `setHeader`, `setFrame`, chiều cao trong modal |
| Chế độ phát triển | Nạp bundle từ `localhost`, tự nạp lại extension và trang sau mỗi lần build |

## 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:

```bash
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/`:

```json
{
  "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.

```ts
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

Trang React dùng `<PosProvider>` của `@pancake-pos/ui` (xem [Giao diện trang iframe](/developers/apps/page-ui)). Không dùng React thì gọi `connect()`:

```ts
import { connect, isEmbedded } from '@pancake-pos/ui-extensions/page';

const pos = await connect({ timeout: 10_000 });
const maybe = await connect({ optional: true });   // null khi mở ngoài POS
```

- `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. `optional: true` trả `null` thay vì lỗi (trang tự host mở được cả ngoài POS); `isEmbedded()` là `false` khi chắc chắn trang không nằm trong cửa sổ khác.
- 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](/developers/apps/runtime-api#trang-iframe).

## CLI (pos-app)

| Lệnh | Mô tả |
|---|---|
| `pos-app login [--no-browser]` | Mở trang **Kết nối CLI** của POS trên trình duyệt để chọn cửa hàng cho máy này (cần quyền Cấu hình ở cửa hàng đó); không phải sao chép token. Chạy lại để thêm cửa hàng. Mỗi cửa hàng nhận một token riêng: chỉ dùng cho cửa hàng đó và các lệnh của CLI (upload, xem version, lỗi, dữ liệu mẫu; không kích hoạt app hay đăng nhập POS được), hạn 30 ngày, hết hiệu lực khi bạn đăng xuất khỏi POS hoặc bị thu hồi ở nút **Kết nối CLI**. POS ngoài `pos.pancake.vn` thì thêm `--api` và `--pos-origin` như lệnh hiện ở nút **Kết nối CLI** |
| `pos-app login --token <mã> --shop <shop_id>` | Lưu token tạo tay ở nút **Kết nối CLI** (máy không có trình duyệt, CI) |
| `pos-app shops` | Cửa hàng đã kết nối, hạn token, cửa hàng mặc định |
| `pos-app use <shop_id>` | Đổi cửa hàng mặc định |
| `pos-app logout [--shop <shop_id>]` | Thu hồi token CLI của một cửa hàng, hoặc mọi cửa hàng khi không có `--shop`, rồi xóa khỏi máy |
| `pos-app dev [--port 5174] [--page-url <url>]` | Build theo dõi thay đổi và phục vụ tại `http://localhost:<port>` cho chế độ phát triển của POS; POS tự nạp lại sau mỗi lần build. `--page-url`: [trang tự host](/developers/apps/runtime-api#trang-tu-host) đang chạy trên máy (ví dụ `http://localhost:3000`) |
| `pos-app check` | Kiểm tra manifest và code (xem bên dưới), không upload |
| `pos-app build` | Build ra `dist/` |
| `pos-app deploy [--shop <shop_id>…\|--all] [--message "..."]` | Chạy `check` và `build` một lần, upload thành version mới (chưa kích hoạt) lên từng cửa hàng; `--shop` lặp được hoặc phân cách dấu phẩy, `--all` là mọi cửa hàng đã kết nối |
| `pos-app versions [--shop <shop_id>…\|--all]` | Version đã upload và version đang kích hoạt; kết nối nhiều cửa hàng thì liệt kê từng cửa hàng (5 version mới nhất mỗi cửa hàng, `--json` có đủ) |
| `pos-app mcp [--shop <shop_id>]` | Chạy MCP server cho công cụ AI, xem [MCP](#mcp); `--shop` đổi cửa hàng mặc định của các tool |

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

Cách gọi CLI:

- **Trong dự án** tạo bằng `create-pos-app`: `npm run dev`, `npm run check`, `npm run build`, `npm run deploy`. Tuỳ chọn đặt sau `--`, ví dụ `npm run deploy -- --message "Sửa box công nợ"`.
- **Lệnh khác, hoặc ở bất kỳ đâu:** `npx @pancake-pos/app-cli <lệnh>`, ví dụ `npx @pancake-pos/app-cli versions`. Trong dự án đã cài, lệnh này dùng đúng bản trong dự án.
- **Gõ ngắn ở mọi nơi:** cài toàn máy `npm i -g @pancake-pos/app-cli`, rồi chạy `pos-app <lệnh>`.

Không chạy `npx pos-app`: gói `pos-app` trên npm không phải của Pancake. Ngoài dự án đã cài, npx tải và chạy gói đó.

### Một app cho nhiều cửa hàng

Thường viết một app rồi đưa lên nhiều cửa hàng. Mỗi cửa hàng là một bản cài riêng: upload, duyệt quyền và kích hoạt riêng, nhật ký lỗi riêng.

```bash
npx @pancake-pos/app-cli login               # chọn các cửa hàng trên trình duyệt
npm run deploy -- --all                       # upload cùng version lên mọi cửa hàng đã kết nối
npm run deploy -- --shop 123 --shop 456       # hoặc vài cửa hàng
npx @pancake-pos/app-cli versions --all       # cửa hàng nào chưa kích hoạt bản mới
```

- Lệnh cần một cửa hàng chọn theo thứ tự: `--shop`, biến môi trường `POS_APP_SHOP`, cửa hàng mặc định (`pos-app use`). `POS_APP_TOKEN` thắng mọi token đã lưu (CI).
- Id thẻ, kho, nguồn đơn, ĐVVC khác nhau giữa các cửa hàng: app tra theo tên qua Open API lúc chạy (`pos.api.get(path, { cache })`), không viết cứng id lấy từ cửa hàng mẫu.
- Phiên đăng nhập lưu ở `~/.config/pos-app/credentials.json` (quyền 0600), mỗi cửa hàng một token. Token hết hạn hay bị thu hồi thì CLI bỏ cửa hàng đó và nhắc chạy lại `login`.
- Dự án còn SDK 2026.1.9 trở về trước chỉ thấy cửa hàng mặc định. Chạy `login --token` bằng CLI cũ sẽ xóa các cửa hàng đã kết nối qua trình duyệt khỏi máy; `logout` bằng CLI cũ chỉ thu hồi token của cửa hàng mặc định, token của cửa hàng khác vẫn dùng được tới khi hết hạn: [cập nhật SDK](#cap-nhat-sdk) trước khi dùng nhiều cửa hàng.

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

### Cập nhật SDK

`check`, `build`, `deploy` và `dev` hỏi npm bản mới nhất (tối đa một lần mỗi ngày, chờ không quá 1,5 giây, mất mạng thì bỏ qua). Khi gói SDK cũ nhất trong dự án thấp hơn bản mới, CLI in lệnh cập nhật đúng các gói dự án khai báo:

```text
ℹ Đã có SDK 2026.1.9 (dự án đang dùng 2026.1.8). Cập nhật:
  npm i @pancake-pos/ui@latest @pancake-pos/ui-extensions@latest && npm i -D @pancake-pos/app-cli@latest @pancake-pos/eslint-plugin@latest
  Có gì mới: https://pos.pancake.vn/developers/apps/changelog
```

- Kết quả `--json` và tool MCP `check_app`, `deploy`, `get_errors` có trường `update` (`current`, `latest`, `command`, `changelog`, `message`) để công cụ AI đề nghị cập nhật. Cập nhật xong thì khởi động lại MCP server.
- Tắt nhắc bằng biến môi trường `POS_APP_NO_UPDATE_CHECK=1`; trong CI (`CI` có giá trị) CLI không hỏi.
- App đã deploy không cần cập nhật: runtime do POS phục vụ. Cập nhật để có type, luật kiểm tra, tài liệu và ví dụ mới; xem [Có gì mới](/developers/apps/changelog).

### 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](/developers/apps/manifest), 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](#luat-kiem-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.
- **Trang iframe trong gói** (`entry`): không có `<link>`, `<script src>`, `@import`, `@font-face` trỏ ra ngoài gói (POS chặn khi chạy); font Inter có sẵn trong `@pancake-pos/ui`.

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.

| Nhóm | Luật | Mức |
|---|---|---|
| Môi trường worker | Không dùng `window`, `document.querySelector`, `localStorage`, `alert`…; không import `react`, `react-dom`, file CSS hay thư viện UI trong `extensions/` | error |
| Element `pos-*` | Element, thuộc tính, sự kiện có trong [danh mục](/developers/apps/components) (gợi ý tên đúng khi gõ sai); giá trị enum hợp lệ; element con và slot hợp lệ; text nằm trong element chứa được text | error |
| Dữ liệu và an toàn | Method `pos.api.*` có trong `access.methods`; URL `fetch` và `src` của `pos-image` viết cố định thuộc `network.allowed_origins` (ảnh được dùng thêm `public/`); không viết cứng mã shop; không có chuỗi giống API key, token, secret | error |
| Hành vi | Module `export default` một hàm; danh sách render có `key`; không đặt `value` của ô nhập sau `await`; `before_submit` không gọi API nối tiếp nhiều lần | warning |
| Màn hình chuẩn | Theo [Màn hình chuẩn](/developers/apps/components#man-hinh-chuan): không emoji, ký hiệu hình trong nhãn; `pos-section` chỉ chứa tiêu đề và số thì dùng `pos-stat`; `pos-section` không lồng quá hai cấp; nút chỉ có icon có `tooltip`; `heading` của `pos-page` không trùng `pos.page.setTitle` | warning |
| Trang iframe | Không dùng `window.top`, `window.parent`; không dùng route bắt đầu bằng `/_pos/` | error |
| Giao diện trang iframe | Không dùng thư viện UI khác (`@mui/*`, `@chakra-ui/*`, `@mantine/*`, `bootstrap`…); màu trong `style`, CSS-in-JS, class Tailwind `[#…]` thuộc bảng màu POS; tiền định dạng bằng `PosMoney`/`pos.format.money`, không `toLocaleString`, `Intl.NumberFormat` kiểu currency; file vào của trang (theo `page/index.html`) dùng `PosProvider` hoặc `connect()`; không dùng `Modal`, `Drawer`, `Modal.confirm` của antd (chỉ phủ iframe): dùng `PosModal`/`PosDrawer` (hoặc `usePosBackdrop`), `pos.ui.*` | warning |

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`:

```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

```text
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](https://modelcontextprotocol.io) server (stdio) để công cụ AI tra tài liệu và endpoint Open API, 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.

```bash
npx @pancake-pos/app-cli mcp                     # 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](/developers/apps/ai-guide#mcp).
