choco-one-click-payment 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# Choco One-Click Widget
+
+Встраиваемый виджет для быстрой оплаты с bottom sheet интерфейсом.
+
+## Установка
+
+```bash
+npm i choco-one-click-payment
+```
+
+## Использование
+
+ESM:
+
+```javascript
+import ChocoOneClickWidget from 'choco-one-click-payment';
+
+const widget = new ChocoOneClickWidget({
+  trackId: 'your-track-id',
+  clientId: '123446',
+  terminalId: 6344,
+  merchantOrderId: 'ORDER-123',
+  amount: 410000,
+  environment: 'stage',
+  onSuccess: (data) => console.log('Success', data),
+  onError: (error) => console.error('Error', error),
+  onCancel: () => console.log('Cancelled')
+});
+
+await widget.init();
+```
+
+CommonJS:
+
+```javascript
+const ChocoOneClickWidget = require('choco-one-click-widget');
+```
+
+## API
+
+- `clientId`- client_id
+- `trackId` - track_id
+- `terminalId` - ID терминала
+- `merchantOrderId` - ID заказа
+- `amount` - Сумма в тиынах
+- `currency` - KZT или GEL (по умолчанию KZT)
+- `environment` - production или stage
+- `backlink` - URL для возврата
+- `locale` - ru, en, kk (по умолчанию ru)
+
+## Сборка пакета (для разработчиков)
+
+```bash
+npm install
+npm run build
+```
+
+Сборка генерирует:
+- `index.js` (UMD/CJS entry)
+- `index.esm.js` (ESM entry)
+- `index.d.ts` (типы TypeScript)

package/index.d.ts

@@ -0,0 +1,224 @@
+/**
+ * TypeScript definitions for Choco One-Click Widget
+ */
+
+declare module 'choco-one-click-widget' {
+  export interface ChocoOneClickConfig {
+    /**
+     * TrackId для авторизации. При init() по нему получается access token.
+     * @required
+     */
+    trackId: string;
+
+    /**
+     * OAuth2 client_id — идентификатор приложения. Требуется бэкендом при
+     * обмене trackId на access token (запрос к /api/v2/oauth2/tokens).
+     * @required
+     */
+    clientId: string;
+
+    /**
+     * ID терминала от Choco
+     * @required
+     * @example 6344 (для staging)
+     */
+    terminalId: number;
+
+    /**
+     * Уникальный ID заказа в вашей системе
+     * @required
+     * @example "ORDER-12345"
+     */
+    merchantOrderId: string;
+
+    /**
+     * Сумма в тиынах (1₸ = 100 тиынов)
+     * @required
+     * @example 10000 (100₸)
+     */
+    amount: number;
+
+    /**
+     * Код валюты
+     * @default "KZT"
+     */
+    currency?: 'KZT' | 'GEL';
+
+    /**
+     * Окружение для API
+     * @default "production"
+     */
+    environment?: 'production' | 'stage';
+
+    /**
+     * URL для возврата после оплаты (важно для Kaspi Pay и 3DS)
+     * @optional
+     */
+    backlink?: string;
+
+    /**
+     * Язык интерфейса виджета
+     * @default "ru"
+     */
+    locale?: 'ru' | 'en' | 'kk';
+
+    /**
+     * Callback вызываемый при успешной оплате
+     * @param data - данные о платеже
+     */
+    onSuccess?: (data: PaymentSuccessEvent) => void;
+
+    /**
+     * Callback вызываемый при ошибке оплаты
+     * @param error - информация об ошибке
+     */
+    onError?: (error: PaymentErrorEvent | Error) => void;
+
+    /**
+     * Callback вызываемый при отмене оплаты пользователем
+     */
+    onCancel?: () => void;
+  }
+
+  export interface PaymentSuccessEvent {
+    /**
+     * Тип события
+     */
+    type: 'order.paid';
+
+    /**
+     * ID заказа в системе Choco
+     */
+    id: string;
+
+    /**
+     * Дополнительные данные
+     */
+    attributes: {
+      /**
+       * Сумма платежа
+       */
+      amount: number;
+
+      /**
+       * Дата и время оплаты
+       */
+      paid_at: string;
+    };
+  }
+
+  export interface PaymentErrorEvent {
+    /**
+     * Тип события
+     */
+    type: 'order.failed';
+
+    /**
+     * ID заказа в системе Choco
+     */
+    id: string;
+
+    /**
+     * Дополнительные данные
+     */
+    attributes: {
+      /**
+       * Сообщение об ошибке
+       */
+      message: string;
+    };
+  }
+
+  export interface PaymentActionRequiredEvent {
+    /**
+     * Тип события
+     */
+    type: 'order.action_required';
+
+    /**
+     * ID заказа в системе Choco
+     */
+    id: string;
+
+    /**
+     * Дополнительные данные
+     */
+    attributes: {
+      /**
+       * URL для редиректа (3DS, Kaspi)
+       */
+      action_url: string;
+    };
+  }
+
+  export interface PaymentMethod {
+    /**
+     * Тип метода оплаты
+     */
+    type: 'card' | 'kaspi_pay' | 'apple_pay' | 'google_pay' | 'new_card';
+
+    /**
+     * Отображаемое название метода
+     */
+    label: string;
+
+    /**
+     * ID карты (только для type: "card")
+     */
+    cardId?: number;
+
+    /**
+     * Тип карты (только для type: "card")
+     */
+    cardType?: string;
+
+    /**
+     * Является ли методом по умолчанию
+     */
+    isDefault?: boolean;
+  }
+
+  export default class ChocoOneClickWidget {
+    /**
+     * Создает экземпляр виджета
+     * @param config - конфигурация виджета
+     */
+    constructor(config: ChocoOneClickConfig);
+
+    /**
+     * Инициализирует виджет: загружает контекст оплаты, 
+     * подключается к WebSocket и отображает UI
+     * @returns Promise<boolean> - true при успешной инициализации
+     */
+    init(): Promise<boolean>;
+
+    /**
+     * Уничтожает виджет: отключает WebSocket, удаляет UI
+     */
+    destroy(): void;
+
+    /**
+     * Закрывает виджет (вызывает onCancel)
+     */
+    close(): void;
+
+    /**
+     * Открывает bottom sheet с выбором метода оплаты
+     */
+    openPaymentSheet(): void;
+
+    /**
+     * Закрывает bottom sheet
+     */
+    closePaymentSheet(): void;
+  }
+}
+
+/**
+ * Global declarations for CDN usage
+ */
+declare global {
+  interface Window {
+    ChocoOneClickWidget: typeof import('choco-one-click-widget').default;
+  }
+}