JavaScript / Браузерный SDK

@lartech/infraio-checkout-js — единственный SDK, который мы публикуем сегодня. Он работает в браузере и открывает наш размещённый checkout. Backend-SDK (Node, Go, Python) в roadmap; до их публикации общайтесь с gateway напрямую — см. Быстрый старт для хелпера HMAC-подписи.

• Текущая версия: 0.1.1-beta.17 (pre-1.0; возможны минорные ломки)
• Форматы: ESM (index.js), CJS (index.cjs), IIFE (index.global.js)
• Типы в комплекте (index.d.ts)
• Нулевые runtime-peers — нет React, jQuery или других зависимостей

Установка

npm install @lartech/infraio-checkout-js

pnpm add @lartech/infraio-checkout-js

yarn add @lartech/infraio-checkout-js

bun add @lartech/infraio-checkout-js

<script src="https://unpkg.com/@lartech/infraio-checkout-js/dist/index.global.js"></script>
<script>
  const sdk = await InfraIo.loadInfraIo("pk_live_yourkeyhere");
  sdk.checkout({ sessionId, checkoutUrl });
</script>

loadInfraIo(publicKey, options?)

Возвращает Promise<InfraIoInstance>.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere", {
  // Опционально. Переопределяйте только при указании на non-prod окружение.
  checkoutUrl: "https://checkout-dev.infraio.xyz",
});

sdk.checkout({ … })

Открывает размещённый checkout. Возвращает void (используйте callback’и для состояния).

sdk.close()

Программно закрыть открытый popup или embed. No-op для режима redirect.

sdk.checkout({ sessionId, mode: "popup", /* … */ });
// позже, например когда пользователь уходит со страницы
sdk.close();

sdk.openRefundRequest({ … })

Открывает размещённую форму refund-request для одноразового токена, который ваш backend выпустил через POST /b2b/v1/merchants/{merchant_id}/refund-requests. Покупатель вводит адрес назначения возврата + причину + (опциональные) метаданные на нашей странице; ваша страница только обрабатывает жизненный цикл открыть/закрыть. Возвращает функцию close() — вызовите её, чтобы программно закрыть popup или открепить embed iframe. В режиме redirect возвращаемая функция — no-op.

import { loadInfraIo } from "@lartech/infraio-checkout-js";
 
const sdk = await loadInfraIo("pk_live_yourkeyhere");
 
// Выпустите токен на сервере, затем передайте в SDK в браузере.
const { token } = await fetch("/api/mint-refund-token", { method: "POST" }).then(r => r.json());
 
const close = sdk.openRefundRequest({
  token,
  mode: "popup",
  onSuccess: ({ linkToken, refundId }) => {
    // Покупатель отправил форму.
    // linkToken → /r/:linkToken страница статуса (поделитесь с покупателем).
    // refundId  → используйте с B2B API для approve / reject.
    window.location.href = `/r/${linkToken}`;
  },
  onCancel: () => { /* покупатель закрыл без отправки */ },
});
 
// Программно закрыть popup позже, если нужно:
// close();

Состояния токена, всплывающие через onError

Если покупатель открывает устаревший токен, страница сама обрабатывает отображение (отрисовывает приглашение «Истёк — запросите новую ссылку» и т. д.), и SDK не отправляет onError для этих случаев — покупатель внутри потока формы, и вашему коду не нужно реагировать. onError срабатывает только для того, на что ваш код может реагировать (плохие аргументы, сетевой сбой при загрузке iframe).

Класс ошибки

import { InfraIoError } from "@lartech/infraio-checkout-js";
 
sdk.checkout({
  sessionId,
  onError: (err: InfraIoError) => {
    switch (err.code) {
      case "invalid_request_error":   /* плохой sessionId / аргументы */ break;
      case "iframe_load_error":       /* iframe не загрузился */ break;
      case "iframe_timeout_error":    /* превышен timeoutMs */ break;
      case "already_open_error":      /* другой checkout уже открыт */ break;
      case "network_error":           /* временная сетевая проблема при общении с origin checkout */ break;
      case "api_error":               /* backend вернул non-2xx для вызова, инициированного SDK */ break;
    }
  },
});

sdk.openRefundRequest() выбрасывает только invalid_request_error (отсутствующий или некорректный токен / аргументы), синхронно. iframe_load_error (iframe refund-request не загрузился) доставляется асинхронно через onError, а не выбрасывается. Он не отправляет iframe_timeout_error или already_open_error — у popup refund-request нет load-timeout, и разрешено несколько одновременных popup’ов.

Заметки по режимам

Popup

• Центрированный overlay с тёмным полупрозрачным backdrop
• z-index: 2147483647 (максимум int32) — сидит над всем остальным
• Скролл body заблокирован пока открыт; восстанавливается при закрытии
• Кнопка закрытия получает начальный фокус; Tab захвачен в popup
• Закрывается через: кнопку закрытия, Escape, клик снаружи, sdk.close(). Все они вызывают onCancel
• Страница checkout может запросить resize через postMessage — SDK обрезает в пределах ограничений width/height

Redirect

• Жёсткая навигация через window.location.href
• Автоматически добавляет ?return_url=<current-page>, чтобы покупатель вернулся туда, откуда пришёл. Если success_url / cancel_url в сессии уже покрывают это, round-trip игнорирует return_url

Embed

• iframe с allow="payment; clipboard-write" (директивы HTML5 Feature Policy — не атрибут sandbox). iframe обслуживается с origin checkout, поэтому wallet popup’ы и запись в clipboard со стороны покупателя работают без дополнительного opt-in.
• Ширина контейнера 100%; высота авто-настраивается через INFRAIO_RESIZE postMessage, ограничена [200, 2000]px
• Никакой CSS-изоляции за границей iframe — стили вашей родительской страницы не протекают внутрь
• Всегда подключайте onReady, чтобы скрыть собственный loading-state, когда checkout становится интерактивным

TypeScript

Все типы в комплекте. Самые полезные экспорты:

import type {
  CheckoutOptions,
  RefundRequestOptions,
  LoadOptions,
  InfraIoInstance,
  InfraIoErrorCode,
} from "@lartech/infraio-checkout-js";
import { loadInfraIo, InfraIoError, VERSION } from "@lartech/infraio-checkout-js";

VERSION — строка версии самого SDK — полезна в bug-репортах.

Что дальше

• Обёртки для React / Vue — запланированы на пост-launch итерацию, как только vanilla JS-поверхность стабилизируется по пилотным мерчантам. Vanilla SDK сегодня нормально работает внутри React; обёртки просто уберут ручной useRef + lifecycle-боилерплейт.
• Возобновление сессии между вкладками — открыть checkout во вкладке A, завершить в B. Полезно, когда покупатель идёт по magic-link посреди потока. В планах на следующий минорный релиз.
• Темизация через CSS-переменные — показать небольшой набор design-токенов (радиус, акцентный цвет) на iframe, чтобы мерчанты могли соответствовать своему бренду без форка страницы.
• Серверные хелперы — крошечный пакет @lartech/infraio-server, экспортирующий verifyWebhook() + signedRequest(), чтобы backend-коду не приходилось копировать ритуал HMAC. До его выпуска на странице проверки подписи есть готовые реализации на TypeScript, Go, Python и Ruby.