choco-one-click-payment 1.0.13 → 1.0.15

package/README.md

@@ -16,57 +16,97 @@ ESM:
 import ChocoOneClickWidget from 'choco-one-click-payment';
 
 const widget = new ChocoOneClickWidget({
+  clientId: '12345678',
   trackId: 'your-track-id',
-  clientId: '123456',
   terminalId: 1234,
-  merchantOrderId: '123456',
-  amount: 500,
+  amount: 10000,
   environment: 'stage',
   onSuccess: (data) => console.log('Success', data),
   onError: (error) => console.error('Error', error),
-  onCancel: () => console.log('Cancelled')
+  onCancel: () => console.log('Cancelled'),
+  onConfirmPay: () => console.log('payment button was pressed')
 });
 
 await widget.init();
 ```
 
+Инициализация без `trackId` (способ оплаты будет заблокирован до вызова `updateTrackId`):
+
+```javascript
+const widget = new ChocoOneClickWidget({
+  clientId: '12345678',
+  terminalId: 1234,
+  amount: 10000,
+  environment: 'stage',
+  onSuccess: (data) => console.log('Success', data),
+  onError: (error) => console.error('Error', error),
+});
+
+await widget.init();
+
+// Когда trackId станет известен
+await widget.updateTrackId('your-track-id');
+```
+
 CommonJS:
 
 ```javascript
-const ChocoOneClickWidget = require('choco-one-click-widget');
+const ChocoOneClickWidget = require('choco-one-click-payment');
 ```
 
-## API (Параметры)
-
-- `client_id` - client_id веб-оплаты (обязательно)
-- `trackId` - track_id (обязательно)
-- `terminalId` - ID терминала (обязательно)
-- `merchantOrderId` - ID заказа (обязательно)
-- `amount` - Сумма в тенге (обязательно)
-- `currency` - валюта (по умолчанию KZT) (обязательно)
-- `environment` - production или stage (обязательно)
-- `backlink` - URL для возврата (опционально)
-- `locale` - ru, en, kk (по умолчанию ru, опционально)
-- `preorderId` - preorder_id заказа (опционально)
-- `color` - цвет background-а элементов (по умолчанию #2F2F2F, опционально)
-- `onlyKaspiAvailable` - отключает все способы оплат и оставляет только Kaspi (опционально)
-- `disableKaspi` - отключает оплату по kaspi (опционально)
-- `bonuses: { amount: number, percent: number }` - для ЗПЛ (опционально)
+## Поведение init()
+
+- **clientId** обязателен. Без него вызывается `onError` и `init()` возвращает `false`.
+- Запрос на контекст оплаты (context) **не отправляется**, если нет ни `trackId`, ни `accessToken` (из cookie). В этом случае показывается виджет с заблокированным выбором способа оплаты; кнопка «Оплатить» активна.
+- Если есть **trackId** или **accessToken** — запрашиваются токены (при необходимости) и context, подключается WebSocket, отображается полный виджет.
+
+## Параметры конфигурации
+
+| Параметр | Тип | Обязательный | Описание |
+|----------|-----|--------------|----------|
+| `clientId` | string | да | OAuth2 client_id приложения |
+| `trackId` | string | нет | Идентификатор для получения access token |
+| `terminalId` | number | да | ID терминала Choco |
+| `amount` | number | да | Сумма в тиынах (1₸ = 100 тиынов) |
+| `merchantOrderId` | string | нет | Уникальный ID заказа в вашей системе |
+| `currency` | string | нет | Код валюты (по умолчанию KZT) |
+| `environment` | 'production' \| 'stage' | нет | Окружение API (по умолчанию production) |
+| `backlink` | string | нет | URL для возврата после оплаты (Kaspi Pay, 3DS) |
+| `locale` | string | нет | Язык: ru, en, kk (по умолчанию ru) |
+| `preorderId` | number | нет | Preorder ID |
+| `color` | string | нет | Акцентный цвет (по умолчанию #2F2F2F) |
+| `onlyKaspiAvailable` | boolean | нет | Только Kaspi в списке способов оплаты |
+| `disableKaspi` | boolean | нет | Скрыть Kaspi среди способов оплаты |
+| `bonuses` | { amount: number, percent: number } | нет | Бонусы для ЗПЛ |
+
+### Callbacks
+
+| Параметр | Описание |
+|----------|----------|
+| `onSuccess` | Вызывается при успешной оплате |
+| `onError` | Вызывается при ошибке |
+| `onCancel` | Вызывается при отмене/закрытии |
+| `onConfirmPay` | Callback перед оплатой; для подтверждения вызовите `widget.pay()` |
+| `onAppliedBonus` | Вызывается при включении/выключении бонусов |
 
 ## Методы
 
-- `onSuccess` - вызывается после успешной оплаты (опционально)
-- `onError` - вызывается в случае ошибки оплаты, резолвит текст ошибки (опционально)
-- `onCancel` - вызывается при timeout (опционально)
-- `onConfirmPay` - callback перед оплатой; должен вызвать `widget.pay()` для подтверждения
-- `onAppliedBonus` - вызывается при включении/выключении бонусов 
-- `updateAmount(amount)` - обновляет сумму оплаты и текст кнопки
-- `updateLocale(locale)` - обновляет язык интерфейса
-- `setLoading(boolean)` - включает/выключает loading-состояние
-- `setDisabled(boolean)` - включает/выключает блокировку интеракций
-- `setPreorderId(preorderId)` - обновляет `preorderId` во время жизни виджета
-- `setMerchantOrderId(merchantOrderId)` - обновляет `merchantOrderId` во время жизни виджета
-- `pay()` - подтверждает оплату и запускает создание заказа
+| Метод | Описание |
+|-------|----------|
+| `init()` | Инициализация виджета. Возвращает `Promise<boolean>`. |
+| `destroy()` | Уничтожает виджет (WebSocket, DOM). |
+| `close()` | Закрывает виджет и вызывает `onCancel`. |
+| `openPaymentSheet()` | Открывает bottom sheet выбора способа оплаты. |
+| `closePaymentSheet()` | Закрывает bottom sheet. |
+| `updateAmount(amount)` | Обновляет сумму (в тиынах) и текст кнопки. |
+| `updateLocale(locale)` | Меняет язык интерфейса. |
+| `updateTrackId(trackId)` | Обновляет trackId, запрашивает токены и context, перерисовывает виджет. Возвращает `Promise<boolean>`. |
+| `setLoading(boolean)` | Включает/выключает состояние загрузки. |
+| `setDisabled(boolean)` | Блокирует/разблокирует интеракции. |
+| `setPreorderId(preorderId)` | Обновляет preorderId в рантайме. |
+| `setMerchantOrderId(merchantOrderId)` | Обновляет merchantOrderId в рантайме. |
+| `onConfirmPay(callback)` | Регистрирует callback подтверждения оплаты. |
+| `pay()` | Подтверждает оплату и запускает создание заказа (после onConfirmPay). |
 
 ## Сборка пакета (для разработчиков)
 
@@ -76,6 +116,7 @@ npm run build
 ```
 
 Сборка генерирует:
-- `index.js` (UMD/CJS entry)
-- `index.esm.js` (ESM entry)
+
+- `index.js` (UMD/CJS)
+- `index.esm.js` (ESM)
 - `index.d.ts` (типы TypeScript)

package/index.d.ts

@@ -10,9 +10,9 @@ export interface ChocoOneClickConfig {
     preorderId?: number;
     /**
      * TrackId для авторизации. При init() по нему получается access token.
-     * @required
+     * @optional
      */
-    trackId: string;
+    trackId?: string;
 
     /**
      * OAuth2 client_id — идентификатор приложения. Требуется бэкендом при
@@ -234,8 +234,8 @@ export default class ChocoOneClickWidget {
     constructor(config: ChocoOneClickConfig);
 
     /**
-     * Инициализирует виджет: загружает контекст оплаты, 
-     * подключается к WebSocket и отображает UI
+     * Инициализирует виджет: загружает контекст оплаты (если передан trackId),
+     * подключается к WebSocket и отображает UI. clientId обязателен.
      * @returns Promise<boolean> - true при успешной инициализации
      */
     init(): Promise<boolean>;
@@ -290,6 +290,12 @@ export default class ChocoOneClickWidget {
      */
     setMerchantOrderId(merchantOrderId: string | number): Promise<void>;
 
+    /**
+     * Обновляет trackId в рантайме, запрашивает токены и подтягивает context
+     * @returns Promise<boolean> — true при успехе
+     */
+    updateTrackId(trackId: string): Promise<boolean>;
+
     /**
      * Регистрирует callback на подтверждение оплаты
      */