@pancake-pos/ui-extensions 0.0.0-stage → 2026.1.0

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @pancake-pos/ui-extensions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK for Pancake POS apps: types for the global `pos` object and `pos-*` elements, `defineExtension`, and `connect()` for iframe pages.
+
+```ts
+// tsconfig.json: "types": ["@pancake-pos/ui-extensions"]
+import { defineExtension } from '@pancake-pos/ui-extensions';
+
+export default defineExtension('order.details.action', async ({ record }) => {
+  return { message: `Order ${record.system_id}` };
+});
+```
+
+Docs: https://pos.pages.fm/developers/apps/en (English), https://pos.pages.fm/developers/apps (Tiếng Việt). For AI tools: https://pos.pages.fm/developers/apps/llms-full.txt.
+
+Part of Pancake POS Apps. Use is limited to building apps for Pancake POS.

package/dist/elements.generated.d.ts

@@ -0,0 +1,419 @@
+export declare const API_VERSION = "2026-01";
+/** Sự kiện của element pos-*: giá trị nằm trong `detail`. */
+export interface PosEvent<D> {
+    readonly type: string;
+    readonly detail: D;
+    readonly target: unknown;
+    readonly currentTarget: unknown;
+}
+/** Thuộc tính chung của mọi element pos-* trong JSX. */
+export interface PosBaseAttributes {
+    slot?: string;
+    key?: string | number;
+    ref?: unknown;
+    children?: unknown;
+}
+/** Thuộc tính của `<pos-badge>`. */
+export interface PosBadgeProps {
+    tone?: "default" | "info" | "success" | "warning" | "critical";
+}
+/** Sự kiện của `<pos-badge>` → kiểu `event.detail`. */
+export interface PosBadgeEvents {
+}
+export interface PosBadgeAttributes extends PosBadgeProps, PosBaseAttributes {
+}
+export interface PosBadgeElement extends PosBadgeProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-banner>`. */
+export interface PosBannerProps {
+    tone?: "info" | "success" | "warning" | "critical";
+    heading?: string;
+    dismissible?: boolean;
+}
+/** Sự kiện của `<pos-banner>` → kiểu `event.detail`. */
+export interface PosBannerEvents {
+    dismiss: null;
+}
+export interface PosBannerAttributes extends PosBannerProps, PosBaseAttributes {
+    onDismiss?: (event: PosEvent<PosBannerEvents["dismiss"]>) => void;
+}
+export interface PosBannerElement extends PosBannerProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-button>`. */
+export interface PosButtonProps {
+    variant?: "primary" | "secondary" | "tertiary" | "danger";
+    size?: "small" | "medium";
+    loading?: boolean;
+    disabled?: boolean;
+}
+/** Sự kiện của `<pos-button>` → kiểu `event.detail`. */
+export interface PosButtonEvents {
+    click: null;
+}
+export interface PosButtonAttributes extends PosButtonProps, PosBaseAttributes {
+    onClick?: (event: PosEvent<PosButtonEvents["click"]>) => void;
+}
+export interface PosButtonElement extends PosButtonProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-checkbox>`. */
+export interface PosCheckboxProps {
+    label?: string;
+    disabled?: boolean;
+    required?: boolean;
+    error?: string;
+    help?: string;
+    checked?: boolean;
+}
+/** Sự kiện của `<pos-checkbox>` → kiểu `event.detail`. */
+export interface PosCheckboxEvents {
+    change: boolean;
+    blur: null;
+}
+export interface PosCheckboxAttributes extends PosCheckboxProps, PosBaseAttributes {
+    onChange?: (event: PosEvent<PosCheckboxEvents["change"]>) => void;
+    onBlur?: (event: PosEvent<PosCheckboxEvents["blur"]>) => void;
+}
+export interface PosCheckboxElement extends PosCheckboxProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-date-picker>`. */
+export interface PosDatePickerProps {
+    label?: string;
+    disabled?: boolean;
+    required?: boolean;
+    error?: string;
+    help?: string;
+    value?: string | null;
+    min?: string;
+    max?: string;
+}
+/** Sự kiện của `<pos-date-picker>` → kiểu `event.detail`. */
+export interface PosDatePickerEvents {
+    change: string | null;
+    blur: null;
+}
+export interface PosDatePickerAttributes extends PosDatePickerProps, PosBaseAttributes {
+    onChange?: (event: PosEvent<PosDatePickerEvents["change"]>) => void;
+    onBlur?: (event: PosEvent<PosDatePickerEvents["blur"]>) => void;
+}
+export interface PosDatePickerElement extends PosDatePickerProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-divider>`. */
+export interface PosDividerProps {
+}
+/** Sự kiện của `<pos-divider>` → kiểu `event.detail`. */
+export interface PosDividerEvents {
+}
+export interface PosDividerAttributes extends PosDividerProps, PosBaseAttributes {
+}
+export interface PosDividerElement extends PosDividerProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-grid>`. */
+export interface PosGridProps {
+    columns?: number;
+    gap?: "none" | "small" | "medium" | "large";
+}
+/** Sự kiện của `<pos-grid>` → kiểu `event.detail`. */
+export interface PosGridEvents {
+}
+export interface PosGridAttributes extends PosGridProps, PosBaseAttributes {
+}
+export interface PosGridElement extends PosGridProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-heading>`. */
+export interface PosHeadingProps {
+    level?: number;
+}
+/** Sự kiện của `<pos-heading>` → kiểu `event.detail`. */
+export interface PosHeadingEvents {
+}
+export interface PosHeadingAttributes extends PosHeadingProps, PosBaseAttributes {
+}
+export interface PosHeadingElement extends PosHeadingProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-image>`. */
+export interface PosImageProps {
+    src?: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    fit?: "cover" | "contain";
+}
+/** Sự kiện của `<pos-image>` → kiểu `event.detail`. */
+export interface PosImageEvents {
+}
+export interface PosImageAttributes extends PosImageProps, PosBaseAttributes {
+}
+export interface PosImageElement extends PosImageProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-link>`. */
+export interface PosLinkProps {
+    href?: string;
+}
+/** Sự kiện của `<pos-link>` → kiểu `event.detail`. */
+export interface PosLinkEvents {
+    click: null;
+}
+export interface PosLinkAttributes extends PosLinkProps, PosBaseAttributes {
+    onClick?: (event: PosEvent<PosLinkEvents["click"]>) => void;
+}
+export interface PosLinkElement extends PosLinkProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-modal>`. */
+export interface PosModalProps {
+    open?: boolean;
+    heading?: string;
+}
+/** Sự kiện của `<pos-modal>` → kiểu `event.detail`. */
+export interface PosModalEvents {
+    close: null;
+}
+export interface PosModalAttributes extends PosModalProps, PosBaseAttributes {
+    onClose?: (event: PosEvent<PosModalEvents["close"]>) => void;
+}
+export interface PosModalElement extends PosModalProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-money>`. */
+export interface PosMoneyProps {
+    value?: number;
+    currency?: string;
+    tone?: "default" | "subdued" | "success" | "warning" | "critical";
+}
+/** Sự kiện của `<pos-money>` → kiểu `event.detail`. */
+export interface PosMoneyEvents {
+}
+export interface PosMoneyAttributes extends PosMoneyProps, PosBaseAttributes {
+}
+export interface PosMoneyElement extends PosMoneyProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-number-field>`. */
+export interface PosNumberFieldProps {
+    label?: string;
+    disabled?: boolean;
+    required?: boolean;
+    error?: string;
+    help?: string;
+    value?: number | null;
+    min?: number;
+    max?: number;
+    step?: number;
+    suffix?: string;
+}
+/** Sự kiện của `<pos-number-field>` → kiểu `event.detail`. */
+export interface PosNumberFieldEvents {
+    change: number | null;
+    blur: null;
+}
+export interface PosNumberFieldAttributes extends PosNumberFieldProps, PosBaseAttributes {
+    onChange?: (event: PosEvent<PosNumberFieldEvents["change"]>) => void;
+    onBlur?: (event: PosEvent<PosNumberFieldEvents["blur"]>) => void;
+}
+export interface PosNumberFieldElement extends PosNumberFieldProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-section>`. */
+export interface PosSectionProps {
+    heading?: string;
+    description?: string;
+}
+/** Sự kiện của `<pos-section>` → kiểu `event.detail`. */
+export interface PosSectionEvents {
+}
+export interface PosSectionAttributes extends PosSectionProps, PosBaseAttributes {
+}
+export interface PosSectionElement extends PosSectionProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-select>`. */
+export interface PosSelectProps {
+    label?: string;
+    disabled?: boolean;
+    required?: boolean;
+    error?: string;
+    help?: string;
+    options?: {
+        label: string;
+        value: string;
+        disabled?: boolean;
+    }[];
+    value?: string | string[];
+    multiple?: boolean;
+    placeholder?: string;
+    searchable?: boolean;
+}
+/** Sự kiện của `<pos-select>` → kiểu `event.detail`. */
+export interface PosSelectEvents {
+    change: string | string[];
+    blur: null;
+}
+export interface PosSelectAttributes extends PosSelectProps, PosBaseAttributes {
+    onChange?: (event: PosEvent<PosSelectEvents["change"]>) => void;
+    onBlur?: (event: PosEvent<PosSelectEvents["blur"]>) => void;
+}
+export interface PosSelectElement extends PosSelectProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-spinner>`. */
+export interface PosSpinnerProps {
+    size?: "small" | "medium" | "large";
+}
+/** Sự kiện của `<pos-spinner>` → kiểu `event.detail`. */
+export interface PosSpinnerEvents {
+}
+export interface PosSpinnerAttributes extends PosSpinnerProps, PosBaseAttributes {
+}
+export interface PosSpinnerElement extends PosSpinnerProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-stack>`. */
+export interface PosStackProps {
+    direction?: "vertical" | "horizontal";
+    gap?: "none" | "small" | "medium" | "large";
+    align?: "start" | "center" | "end" | "stretch";
+    justify?: "start" | "center" | "end" | "space-between";
+    wrap?: boolean;
+}
+/** Sự kiện của `<pos-stack>` → kiểu `event.detail`. */
+export interface PosStackEvents {
+}
+export interface PosStackAttributes extends PosStackProps, PosBaseAttributes {
+}
+export interface PosStackElement extends PosStackProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-table>`. */
+export interface PosTableProps {
+    columns?: ({
+        key: string;
+        title: string;
+        align?: "left" | "center" | "right";
+        width?: number;
+        format?: "text" | "number" | "money" | "date" | "datetime";
+    })[];
+    rows?: (Record<string, string | number | boolean | null>)[];
+    rowKey?: string;
+    loading?: boolean;
+    pagination?: {
+        page: number;
+        pageSize: number;
+        total: number;
+    } | null;
+    emptyText?: string;
+}
+/** Sự kiện của `<pos-table>` → kiểu `event.detail`. */
+export interface PosTableEvents {
+    pagechange: {
+        page: number;
+        pageSize: number;
+    };
+    rowclick: Record<string, string | number | boolean | null>;
+}
+export interface PosTableAttributes extends PosTableProps, PosBaseAttributes {
+    onPageChange?: (event: PosEvent<PosTableEvents["pagechange"]>) => void;
+    onRowClick?: (event: PosEvent<PosTableEvents["rowclick"]>) => void;
+}
+export interface PosTableElement extends PosTableProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-text>`. */
+export interface PosTextProps {
+    tone?: "default" | "subdued" | "success" | "warning" | "critical";
+    size?: "small" | "medium" | "large";
+    weight?: "regular" | "semibold" | "bold";
+}
+/** Sự kiện của `<pos-text>` → kiểu `event.detail`. */
+export interface PosTextEvents {
+}
+export interface PosTextAttributes extends PosTextProps, PosBaseAttributes {
+}
+export interface PosTextElement extends PosTextProps {
+    scrollIntoView(): void;
+}
+/** Thuộc tính của `<pos-text-field>`. */
+export interface PosTextFieldProps {
+    label?: string;
+    disabled?: boolean;
+    required?: boolean;
+    error?: string;
+    help?: string;
+    value?: string;
+    placeholder?: string;
+    multiline?: boolean | number;
+    maxLength?: number;
+}
+/** Sự kiện của `<pos-text-field>` → kiểu `event.detail`. */
+export interface PosTextFieldEvents {
+    change: string;
+    blur: null;
+}
+export interface PosTextFieldAttributes extends PosTextFieldProps, PosBaseAttributes {
+    onChange?: (event: PosEvent<PosTextFieldEvents["change"]>) => void;
+    onBlur?: (event: PosEvent<PosTextFieldEvents["blur"]>) => void;
+}
+export interface PosTextFieldElement extends PosTextFieldProps {
+    focus(): void;
+    scrollIntoView(): void;
+}
+/** Tên element → thuộc tính trong JSX. */
+export interface PosIntrinsicElements {
+    "pos-badge": PosBadgeAttributes;
+    "pos-banner": PosBannerAttributes;
+    "pos-button": PosButtonAttributes;
+    "pos-checkbox": PosCheckboxAttributes;
+    "pos-date-picker": PosDatePickerAttributes;
+    "pos-divider": PosDividerAttributes;
+    "pos-grid": PosGridAttributes;
+    "pos-heading": PosHeadingAttributes;
+    "pos-image": PosImageAttributes;
+    "pos-link": PosLinkAttributes;
+    "pos-modal": PosModalAttributes;
+    "pos-money": PosMoneyAttributes;
+    "pos-number-field": PosNumberFieldAttributes;
+    "pos-section": PosSectionAttributes;
+    "pos-select": PosSelectAttributes;
+    "pos-spinner": PosSpinnerAttributes;
+    "pos-stack": PosStackAttributes;
+    "pos-table": PosTableAttributes;
+    "pos-text": PosTextAttributes;
+    "pos-text-field": PosTextFieldAttributes;
+}
+/** Tên element → element tạo bằng `document.createElement` (JS thuần). */
+export interface PosHTMLElementTagNameMap {
+    "pos-badge": Omit<HTMLElement, keyof PosBadgeElement> & PosBadgeElement;
+    "pos-banner": Omit<HTMLElement, keyof PosBannerElement> & PosBannerElement;
+    "pos-button": Omit<HTMLElement, keyof PosButtonElement> & PosButtonElement;
+    "pos-checkbox": Omit<HTMLElement, keyof PosCheckboxElement> & PosCheckboxElement;
+    "pos-date-picker": Omit<HTMLElement, keyof PosDatePickerElement> & PosDatePickerElement;
+    "pos-divider": Omit<HTMLElement, keyof PosDividerElement> & PosDividerElement;
+    "pos-grid": Omit<HTMLElement, keyof PosGridElement> & PosGridElement;
+    "pos-heading": Omit<HTMLElement, keyof PosHeadingElement> & PosHeadingElement;
+    "pos-image": Omit<HTMLElement, keyof PosImageElement> & PosImageElement;
+    "pos-link": Omit<HTMLElement, keyof PosLinkElement> & PosLinkElement;
+    "pos-modal": Omit<HTMLElement, keyof PosModalElement> & PosModalElement;
+    "pos-money": Omit<HTMLElement, keyof PosMoneyElement> & PosMoneyElement;
+    "pos-number-field": Omit<HTMLElement, keyof PosNumberFieldElement> & PosNumberFieldElement;
+    "pos-section": Omit<HTMLElement, keyof PosSectionElement> & PosSectionElement;
+    "pos-select": Omit<HTMLElement, keyof PosSelectElement> & PosSelectElement;
+    "pos-spinner": Omit<HTMLElement, keyof PosSpinnerElement> & PosSpinnerElement;
+    "pos-stack": Omit<HTMLElement, keyof PosStackElement> & PosStackElement;
+    "pos-table": Omit<HTMLElement, keyof PosTableElement> & PosTableElement;
+    "pos-text": Omit<HTMLElement, keyof PosTextElement> & PosTextElement;
+    "pos-text-field": Omit<HTMLElement, keyof PosTextFieldElement> & PosTextFieldElement;
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { PosHTMLElementTagNameMap, PosIntrinsicElements } from './elements.generated';
+import type { DataOf, Pos, ResultOf, Target } from './types';
+export * from './types';
+export * from './elements.generated';
+/**
+ * Giúp type của `data` và giá trị trả về khớp target. Trả lại đúng hàm truyền vào,
+ * nên tương đương `export default async function (data)` (tài liệu public `sdk` › defineExtension).
+ */
+export declare function defineExtension<T extends Target>(target: T, fn: (data: DataOf<T>) => ResultOf<T> | Promise<ResultOf<T>>): (data: DataOf<T>) => ResultOf<T> | Promise<ResultOf<T>>;
+declare global {
+    /** Đối tượng POS trong worker của extension (tài liệu public `runtime-api`). */
+    const pos: Pos;
+    /** `document.createElement('pos-button')` trong JS thuần trả element có thuộc tính đúng kiểu. */
+    interface HTMLElementTagNameMap extends PosHTMLElementTagNameMap {
+    }
+}
+declare module 'preact' {
+    namespace JSX {
+        interface IntrinsicElements extends PosIntrinsicElements {
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+// src/elements.generated.ts
+var API_VERSION = "2026-01";
+
+// src/index.ts
+function defineExtension(target, fn) {
+  void target;
+  return fn;
+}
+export {
+  API_VERSION,
+  defineExtension
+};

package/dist/page.d.ts

@@ -0,0 +1,10 @@
+import type { PosApiError as PosApiErrorType, PosPage, PosRuntimeError as PosRuntimeErrorType } from './types';
+export type { PageData, PosPage } from './types';
+export declare const PosApiError: new (status: number, message: string, code?: number | string, body?: unknown) => PosApiErrorType;
+export declare const PosRuntimeError: new (code: string, message: string) => PosRuntimeErrorType;
+export interface ConnectOptions {
+    /** Chờ POS trả lời (mặc định 10 giây); quá hạn thường do mở trang ngoài POS. */
+    timeout?: number;
+}
+/** Kết nối với POS. Gọi nhiều lần trả cùng một kết nối. */
+export declare function connect(options?: ConnectOptions): Promise<PosPage>;

package/dist/page.js

@@ -0,0 +1,332 @@
+// ../app-protocol/src/protocol.ts
+var PROTOCOL_VERSION = 1;
+function extensionContext(kind, target) {
+  if (kind === "hook") return "hook";
+  if (kind === "headless") return "action-headless";
+  if (target === "app.page") return "page";
+  if (target.endsWith(".details.block")) return "block";
+  return "action-ui";
+}
+var AVAILABILITY = {
+  "toast.show": ["block", "action-headless", "action-ui", "page"],
+  "ui.confirm": ["block", "action-headless", "action-ui", "page"],
+  navigate: ["block", "action-headless", "action-ui", "page"],
+  refresh: ["block", "action-headless", "action-ui"],
+  close: ["action-ui"],
+  "session.token": ["block", "action-headless", "action-ui", "hook", "page"],
+  "element.focus": ["block", "action-ui", "page"],
+  "element.scrollIntoView": ["block", "action-ui", "page"],
+  "page.setTitle": ["page"],
+  "page.setPrimaryAction": ["page"],
+  "data-change": ["block", "action-ui", "page"]
+};
+function isAvailable(capability, context) {
+  return Object.prototype.hasOwnProperty.call(AVAILABILITY, capability) && AVAILABILITY[capability].includes(context);
+}
+
+// ../../runtime/worker/pos.ts
+var TOKEN_REFRESH_BEFORE_MS = 6e4;
+var TOKEN_REFRESH_MIN_INTERVAL_MS = 3e4;
+var TOAST_LIMIT = 3;
+var TOAST_WINDOW_MS = 1e4;
+var PosRuntimeError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PosRuntimeError";
+  }
+};
+var PosApiError = class extends Error {
+  constructor(status, message, code, body) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.name = "PosApiError";
+  }
+};
+function buildQuery(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) for (const item of value) params.append(key, String(item));
+    else params.append(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+  }
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+function createPos(deps) {
+  const { init } = deps;
+  const now = deps.now ?? Date.now;
+  const context = extensionContext(init.kind, init.target);
+  const listeners = /* @__PURE__ */ new Map();
+  let data = init.data;
+  let token = { ...init.token };
+  let lastRefresh = 0;
+  let refreshing = null;
+  const toasts = [];
+  const require2 = (capability, name) => {
+    if (!isAvailable(capability, context)) throw new PosRuntimeError("unavailable", `${name} is not available in ${init.target}`);
+  };
+  const callHost = (method, args, name) => {
+    require2(method, name);
+    return deps.call(method, args);
+  };
+  const refreshToken = (force) => {
+    const expiresAt = Date.parse(token.expiresAt);
+    const stale = force || !Number.isFinite(expiresAt) || expiresAt - now() < TOKEN_REFRESH_BEFORE_MS;
+    if (!stale || !force && now() - lastRefresh < TOKEN_REFRESH_MIN_INTERVAL_MS) return Promise.resolve();
+    refreshing ?? (refreshing = deps.call("session.token", force ? [{ force: true }] : []).then((next) => {
+      const value = next;
+      if (typeof value?.token === "string" && typeof value.expiresAt === "string") token = { token: value.token, expiresAt: value.expiresAt };
+      lastRefresh = now();
+    }).finally(() => {
+      refreshing = null;
+    }));
+    return refreshing;
+  };
+  const request = async (options) => {
+    const method = String(options.method).toUpperCase();
+    if (!init.api.methods.includes(method)) throw new PosRuntimeError("method_not_allowed", `${method} is not in access.methods`);
+    const shopPath = `/shops/${init.shop.id}`;
+    const path = options.path;
+    const inShop = typeof path === "string" && (path === shopPath || path.startsWith(`${shopPath}/`) || path.startsWith(`${shopPath}?`));
+    if (!inShop || path.includes("..")) {
+      throw new PosRuntimeError("invalid_path", `path must start with ${shopPath}`);
+    }
+    const url = `${init.api.baseUrl}${options.path}${buildQuery(options.query)}`;
+    const send = async () => {
+      const headers = { Authorization: `Bearer ${token.token}`, Accept: "application/json" };
+      if (options.body !== void 0) headers["Content-Type"] = "application/json";
+      return deps.fetch(url, {
+        method,
+        headers,
+        ...options.body !== void 0 ? { body: JSON.stringify(options.body) } : {},
+        ...options.signal ? { signal: options.signal } : {}
+      });
+    };
+    await refreshToken(false);
+    let response = await send();
+    if (response.status === 401) {
+      await refreshToken(true);
+      response = await send();
+    }
+    const text = await response.text();
+    let body = text;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+    }
+    const failed = typeof body === "object" && body !== null && body.success === false;
+    if (response.status >= 400 || failed) {
+      const info = typeof body === "object" && body !== null ? body : {};
+      const message = typeof info.message === "string" ? info.message : `Open API request failed with status ${response.status}`;
+      const code = typeof info.error_code === "number" || typeof info.error_code === "string" ? info.error_code : void 0;
+      throw new PosApiError(response.status, message, code, body);
+    }
+    return body;
+  };
+  const shortcut = (method) => (path, options = {}) => request({ method, path, ...options });
+  const withBody = (method) => (path, body, options = {}) => request({ method, path, body, ...options });
+  const pos = {
+    apiVersion: init.apiVersion,
+    target: init.target,
+    extensionId: init.extensionId,
+    app: Object.freeze({ ...init.app }),
+    shop: Object.freeze({ ...init.shop }),
+    user: Object.freeze({ ...init.user }),
+    get data() {
+      return data;
+    },
+    api: Object.freeze({
+      baseUrl: init.api.baseUrl,
+      request,
+      get: shortcut("GET"),
+      delete: shortcut("DELETE"),
+      post: withBody("POST"),
+      put: withBody("PUT")
+    }),
+    session: Object.freeze({
+      async getToken() {
+        await refreshToken(false);
+        return { ...token };
+      }
+    }),
+    toast: Object.freeze({
+      show(message, options = {}) {
+        require2("toast.show", "pos.toast.show");
+        const time = now();
+        while (toasts.length && time - toasts[0] > TOAST_WINDOW_MS) toasts.shift();
+        if (toasts.length >= TOAST_LIMIT) return;
+        toasts.push(time);
+        void deps.call("toast.show", [String(message), { ...options.tone ? { tone: options.tone } : {}, ...options.duration ? { duration: options.duration } : {} }]);
+      }
+    }),
+    ui: Object.freeze({
+      async confirm(options) {
+        return await callHost("ui.confirm", [options], "pos.ui.confirm") === true;
+      }
+    }),
+    navigate(to) {
+      void callHost("navigate", [to], "pos.navigate");
+    },
+    refresh() {
+      void callHost("refresh", [], "pos.refresh");
+    },
+    close() {
+      void callHost("close", [], "pos.close");
+    },
+    on(event, handler) {
+      if (event === "data-change") require2("data-change", "pos.on('data-change')");
+      else if (!deps.events?.includes(event)) throw new PosRuntimeError("unavailable", `event ${event} is not available in ${init.target}`);
+      let set = listeners.get(event);
+      if (!set) listeners.set(event, set = /* @__PURE__ */ new Set());
+      set.add(handler);
+      return () => set.delete(handler);
+    }
+  };
+  const emit = (event, payload) => {
+    for (const handler of [...listeners.get(event) ?? []]) handler(payload);
+  };
+  return {
+    pos: Object.freeze(pos),
+    setData(next) {
+      data = next;
+      emit("data-change", next);
+    },
+    emit
+  };
+}
+
+// src/page.ts
+var PosApiError2 = PosApiError;
+var PosRuntimeError2 = PosRuntimeError;
+var currentLocation = () => {
+  const query = {};
+  new URLSearchParams(window.location.search).forEach((value, key) => {
+    query[key] = value;
+  });
+  return { path: window.location.pathname, query };
+};
+var toUrl = (data) => {
+  const search = new URLSearchParams(data.query).toString();
+  return `${data.path}${search ? `?${search}` : ""}`;
+};
+var connecting = null;
+function connect(options = {}) {
+  connecting ?? (connecting = open(options.timeout ?? 1e4).catch((error) => {
+    connecting = null;
+    throw error;
+  }));
+  return connecting;
+}
+function open(timeout) {
+  if (typeof window === "undefined" || window.parent === window) {
+    return Promise.reject(new PosRuntimeError2("unavailable", "This page must be opened from Pancake POS"));
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      window.removeEventListener("message", onMessage);
+      reject(new PosRuntimeError2("unavailable", `POS did not respond within ${timeout} ms; open this page from Pancake POS`));
+    }, timeout);
+    const onMessage = (event) => {
+      if (event.source !== window.parent || event.data?.t !== "connect" || event.data.protocol !== PROTOCOL_VERSION) return;
+      const [port] = event.ports;
+      if (!port) return;
+      window.removeEventListener("message", onMessage);
+      port.onmessage = (message) => {
+        if (message.data?.t !== "page-init") return;
+        clearTimeout(timer);
+        resolve(start(port, message.data));
+      };
+    };
+    window.addEventListener("message", onMessage);
+    const ready = { t: "page-ready", protocol: PROTOCOL_VERSION };
+    window.parent.postMessage(ready, "*");
+  });
+}
+function start(port, init) {
+  const post = (message) => port.postMessage(message);
+  let callId = 0;
+  const pending = /* @__PURE__ */ new Map();
+  const call = (method, args) => new Promise((resolve, reject) => {
+    callId += 1;
+    pending.set(callId, { resolve, reject });
+    post({ t: "call", call: callId, method, args });
+  });
+  const runtime = createPos({
+    init: { ...init, kind: "ui", data: currentLocation() },
+    events: ["primary-action"],
+    call,
+    fetch: window.fetch.bind(window)
+  });
+  let reported = "";
+  const report = () => {
+    const location = currentLocation();
+    const url = toUrl(location);
+    if (url === reported) return;
+    reported = url;
+    runtime.setData(location);
+    post({ t: "location", ...location });
+  };
+  for (const method of ["pushState", "replaceState"]) {
+    const original = history[method].bind(history);
+    history[method] = (...args) => {
+      original(...args);
+      report();
+    };
+  }
+  window.addEventListener("popstate", report);
+  report();
+  port.onmessage = ({ data: message }) => {
+    switch (message?.t) {
+      case "reply": {
+        const entry = pending.get(message.call);
+        if (!entry) return;
+        pending.delete(message.call);
+        if (message.ok) entry.resolve(message.value);
+        else entry.reject(Object.assign(new PosRuntimeError2("unavailable", message.error.message), { code: message.error.code }));
+        return;
+      }
+      case "navigate": {
+        const target = toUrl(message);
+        if (target === toUrl(currentLocation())) return;
+        history.pushState(null, "", target);
+        window.dispatchEvent(new PopStateEvent("popstate", { state: null }));
+        return;
+      }
+      case "primary-action":
+        runtime.emit("primary-action");
+        return;
+    }
+  };
+  const reportError = (error) => {
+    const value = error;
+    post({
+      t: "error",
+      error: {
+        code: "uncaught",
+        message: String(value?.message ?? error).slice(0, 1024),
+        ...typeof value?.stack === "string" ? { stack: value.stack.slice(0, 4096) } : {}
+      }
+    });
+  };
+  window.addEventListener("error", (event) => reportError(event.error ?? event.message));
+  window.addEventListener("unhandledrejection", (event) => reportError(event.reason));
+  const page = Object.freeze({
+    setTitle(title) {
+      void call("page.setTitle", [String(title).slice(0, 200)]);
+    },
+    setPrimaryAction(action) {
+      void call("page.setPrimaryAction", [action ? { label: String(action.label).slice(0, 50), disabled: !!action.disabled, loading: !!action.loading } : null]);
+    }
+  });
+  const pos = Object.defineProperties({}, { ...Object.getOwnPropertyDescriptors(runtime.pos), page: { value: page, enumerable: true } });
+  return Object.freeze(pos);
+}
+export {
+  PosApiError2 as PosApiError,
+  PosRuntimeError2 as PosRuntimeError,
+  connect
+};

package/dist/types.d.ts

@@ -0,0 +1,272 @@
+export type Resource = 'order' | 'product' | 'purchase' | 'export' | 'warehouse_transfer';
+export type OrderRef = {
+    /** Mã đơn hiển thị (mã tuỳ chỉnh nếu shop dùng, ngược lại là mã hệ thống). */
+    id: string | number;
+    /** Mã đơn hệ thống, như trường `system_id` của đơn trong Open API: `/shops/{shop_id}/orders/{system_id}`. */
+    system_id: number;
+    status: number;
+    updated_at: string;
+};
+export type OrderDraft = {
+    status: number;
+    customer_id: string | null;
+    bill_full_name: string | null;
+    bill_phone_number: string | null;
+    warehouse_id: string | null;
+    tags: (number | string)[];
+    note: string | null;
+    items: {
+        variation_id: string;
+        product_id: string;
+        quantity: number;
+        price: number;
+    }[];
+    total_price: number;
+};
+export type ProductRef = {
+    id: string;
+    display_id: number;
+    custom_id: string | null;
+    name: string;
+    is_hide: boolean;
+    updated_at: string;
+};
+export type ProductDraft = {
+    name: string;
+    custom_id: string | null;
+    category_ids: number[];
+    brand_id: number | null;
+    tags: (number | string)[];
+    variations: {
+        id: string | null;
+        custom_id: string | null;
+        barcode: string | null;
+        retail_price: number;
+    }[];
+};
+export type PurchaseRef = {
+    id: string;
+    display_id: number;
+    custom_id: string | null;
+    status: number;
+    warehouse_id: string;
+    updated_at: string;
+};
+export type PurchaseDraft = {
+    status: number;
+    warehouse_id: string | null;
+    supplier_products_id: string | null;
+    tags: (number | string)[];
+    note: string | null;
+    items: {
+        variation_id: string;
+        quantity: number;
+        imported_price: number;
+    }[];
+    total_price: number;
+};
+export type ExportRef = {
+    id: string;
+    display_id: number;
+    custom_id: string | null;
+    status: number;
+    type: number;
+    warehouse_id: string;
+    updated_at: string;
+};
+export type ExportDraft = {
+    status: number;
+    type: number;
+    warehouse_id: string | null;
+    tags: (number | string)[];
+    note: string | null;
+    export_items: {
+        variation_id: string;
+        quantity: number;
+    }[];
+};
+export type WarehouseTransferRef = {
+    id: string;
+    display_id: number;
+    custom_id: string | null;
+    status: number;
+    from_warehouse_id: string;
+    to_warehouse_id: string;
+    updated_status_at: string;
+};
+export type WarehouseTransferDraft = {
+    status: number;
+    from_warehouse_id: string | null;
+    to_warehouse_id: string | null;
+    note: string | null;
+    items: {
+        variation_id: string;
+        quantity: number;
+    }[];
+};
+interface Refs {
+    order: OrderRef;
+    product: ProductRef;
+    purchase: PurchaseRef;
+    export: ExportRef;
+    warehouse_transfer: WarehouseTransferRef;
+}
+interface Drafts {
+    order: OrderDraft;
+    product: ProductDraft;
+    purchase: PurchaseDraft;
+    export: ExportDraft;
+    warehouse_transfer: WarehouseTransferDraft;
+}
+export type RefOf<R extends Resource> = Refs[R];
+export type DraftOf<R extends Resource> = Drafts[R];
+/** Form chi tiết: `*.details.action`, `*.details.block`, `*.before_submit`. */
+export type DetailsData<R extends Resource = Resource> = {
+    resource: R;
+    mode: 'create' | 'edit';
+    /** null khi bản ghi chưa lưu. */
+    record: RefOf<R> | null;
+    /** Dữ liệu form đang hiển thị, gồm cả phần chưa lưu. */
+    draft: DraftOf<R>;
+};
+/** Một dòng của danh sách: `*.index.action`. */
+export type IndexData<R extends Resource = Resource> = {
+    resource: R;
+    record: RefOf<R>;
+};
+/** Thanh thao tác hàng loạt: `*.index.selection-action` (tối đa 500 bản ghi). */
+export type SelectionData<R extends Resource = Resource> = {
+    resource: R;
+    records: RefOf<R>[];
+};
+export type AfterSaveInput<R extends Resource = Resource> = {
+    resource: R;
+    mode: 'create' | 'edit';
+    record: RefOf<R>;
+};
+export type BeforeSubmitInput<R extends Resource = Resource> = DetailsData<R>;
+/** `message` tối đa 200 ký tự, hiện cho người dùng. */
+export type BeforeSubmitResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export type HeadlessActionResult = {
+    message?: string;
+    refresh?: boolean;
+} | void;
+/** `app.page`: đường dẫn sau `/apps/<handle>` và query của URL POS. */
+export type PageData = {
+    path: string;
+    query: Record<string, string>;
+};
+export type DetailsTarget<R extends Resource = Resource> = `${R}.details.action` | `${R}.details.block`;
+export type Target = 'app.page' | DetailsTarget | `${Resource}.index.action` | `${Resource}.index.selection-action` | `${Resource}.before_submit` | `${Resource}.after_save`;
+type ResourceOf<T extends string> = T extends `${infer R extends Resource}.${string}` ? R : never;
+/** `pos.data` và tham số của module theo target. */
+export type DataOf<T extends Target> = T extends 'app.page' ? PageData : T extends `${string}.index.selection-action` ? SelectionData<ResourceOf<T>> : T extends `${string}.index.action` ? IndexData<ResourceOf<T>> : T extends `${string}.after_save` ? AfterSaveInput<ResourceOf<T>> : DetailsData<ResourceOf<T>>;
+/** Giá trị module trả về theo target (action có giao diện và block tự render, không trả gì). */
+export type ResultOf<T extends Target> = T extends `${string}.before_submit` ? BeforeSubmitResult : T extends `${string}.after_save` | `${string}.details.block` | 'app.page' ? void : HeadlessActionResult;
+export type ToastOptions = {
+    tone?: 'success' | 'error' | 'info' | 'warning';
+    duration?: number;
+};
+export type ConfirmOptions = {
+    title: string;
+    content?: string;
+    okText?: string;
+    cancelText?: string;
+    danger?: boolean;
+};
+export type NavigateTarget = {
+    page: string;
+    path?: string;
+    query?: Record<string, string>;
+};
+type RequestOptions = {
+    query?: Record<string, unknown>;
+    signal?: AbortSignal;
+};
+export interface PosApi {
+    /** Gốc Open API, ví dụ `https://pos.pages.fm/api/v1`. */
+    readonly baseUrl: string;
+    request<T = any>(options: {
+        method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+        path: string;
+        query?: Record<string, unknown>;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    get<T = any>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = any>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    put<T = any>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T = any>(path: string, options?: RequestOptions): Promise<T>;
+}
+export type PosEventName = 'data-change' | 'primary-action';
+export interface Pos<D = any> {
+    readonly apiVersion: string;
+    readonly target: string;
+    readonly extensionId: string;
+    readonly app: {
+        readonly id: string;
+        readonly handle: string;
+        readonly version: string;
+    };
+    readonly shop: {
+        readonly id: number;
+        readonly name: string;
+        readonly currency: string;
+        readonly country: string;
+        readonly timezone: string;
+    };
+    readonly user: {
+        readonly id: string;
+        readonly name: string;
+        readonly locale: string;
+    };
+    /** Dữ liệu ngữ cảnh, dạng theo target (`DataOf<target>`). */
+    readonly data: D;
+    readonly api: PosApi;
+    readonly session: {
+        getToken(): Promise<{
+            token: string;
+            expiresAt: string;
+        }>;
+    };
+    readonly toast: {
+        show(message: string, options?: ToastOptions): void;
+    };
+    readonly ui: {
+        confirm(options: ConfirmOptions): Promise<boolean>;
+    };
+    navigate(to: NavigateTarget): void;
+    refresh(): void;
+    close(): void;
+    on(event: 'data-change', handler: (data: D) => void): () => void;
+    on(event: PosEventName, handler: (payload: any) => void): () => void;
+}
+/** `pos` của trang iframe: thêm `pos.page`. */
+export interface PosPage extends Pos<PageData> {
+    readonly page: {
+        setTitle(title: string): void;
+        setPrimaryAction(action: {
+            label: string;
+            disabled?: boolean;
+            loading?: boolean;
+        } | null): void;
+    };
+}
+/** Lỗi khi gọi `pos.api`; dùng `error.name === 'PosApiError'` hoặc kiểm `status`. */
+export interface PosApiError extends Error {
+    readonly name: 'PosApiError';
+    readonly status: number;
+    readonly code?: number | string;
+    readonly body?: unknown;
+}
+/** Lỗi khi gọi API của `pos` không có ở target này, hoặc POS từ chối. */
+export interface PosRuntimeError extends Error {
+    readonly name: 'PosRuntimeError';
+    readonly code: string;
+}
+export {};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@pancake-pos/ui-extensions",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.1.0",
+  "description": "Types for pos and pos-* elements, defineExtension, and connect() for iframe pages of Pancake POS apps",
+  "license": "UNLICENSED",
+  "type": "module",
+  "homepage": "https://pos.pages.fm/developers/apps/en",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pancake-vn/pos-app-platform.git",
+    "directory": "packages/ui-extensions"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "default": "./dist/page.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "preact": "^10.19.0 || ^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "preact": {
+      "optional": true
+    }
+  }
+}