Выберите настоящий источник пакета
Source-пакет @hallify/sdk версии 0.1.0 находится в packages/sdk репозитория hallify.co. Установите этот каталог как file dependency своего package manager либо используйте versioned browser module /sdk/0.1.0/browser/index.mjs после развёртывания. Пакет включает ESM JavaScript и TypeScript declarations; SDK bundler build или React/Redux runtime dependency не нужны. Документация не утверждает публикацию npm или развёртывание подготовленного маршрута.
Browser entry экспортирует createGuestClient, mountWidget, SdkError, SDK_VERSION, SCHEMA_HASH и WIDGET_PROTOCOL_VERSION. Server entry @hallify/sdk/server предназначен только для Node и экспортирует createPartnerPreordersClient. Импорт browser-модуля безопасен для SSR; гостевые запросы и mount выполняются в браузере. Нативные wire contracts генерируются из тех же canonical OpenAPI и явного Developers registry, что и приложение.
Используйте точные generated guest methods
Browser client предоставляет явно зарегистрированные операции с точными integration keys storefront, public-preorders, reservations, table-access, guest-payments, guest-observers и guest-portal. Методы используют registry methodName, например guest.reservations.configuration и guest['guest-payments'].prepareTransition. Careers, Candidate, staff и provider callback API не входят в SDK. Каждый метод использует generated argument/body type и возвращает { data, status, requestId }; SDK не добавляет cache или копию бизнес-состояния.
createGuestClient принимает конфигурацию apiBaseUrl, fetch и timeoutMs. По умолчанию используется https://api.hallify.co; override проходит ту же безопасную public URL policy. Browser Origin/Host/Cookie/Referer и аккаунтный CSRF не являются аргументами SDK. Запросы опускают cookies, используют no-store и отклоняют редиректы. Фактический Origin задаёт браузер, в том числе изолированный frame для widget-запросов.
import { createGuestClient, SdkError } from '@hallify/sdk/browser';
const guest = createGuestClient();
try {
const { data, status, requestId } = await guest.reservations.configuration({
publicHandle: 'example-native-channel',
});
// Render the returned native configuration in the owning guest flow.
} catch (error) {
if (error instanceof SdkError && error.outcome === 'UNKNOWN') {
// Preserve the original command key, payload and private recovery context.
}
throw error;
}Передавайте только канонические данные доступа метода
Header credentials передаются в per-call auth по canonical scheme, например { auth: { reservationManageToken: currentCapability } } или { auth: { guestPaymentAccessToken: paymentCapability } }. Body credentials остаются в generated DTO. Нет дополнительного Authorization argument, глобального token registry, автоматической выдачи ключей или account fallback. Приватные тела, ответы, доступы и tickets хранятся внутри собственного гостевого сценария.
Для нового widget-спроса auth внутри frame может дополнительно содержать storefrontWidgetContext. Этот подписанный proof представления не заменяет draft/manage/membership/payment authority. Frame получает его через bootstrap и проверяет точного родителя; swc1 или нативная capability не отправляются странице встраивания. Существующие продолжения сохраняют исходные presentation identity и сроки без вымышленного нового proof.
Разделяйте Portal proof, нативный вход и QR-историю
guest['guest-portal'] покрывает ограниченные history/details, payment receipts, приватный reentryContext, подготовку/проверку/статус target proof, issueNativeEntry и исходные QR consent/receipts. История и UUID proof/grant не являются bearer управления. Ответ выдачи сохраняет исходную receipt отдельно от current.state и nullable current.manageToken; явное восстановление потерянного ответа использует исходные key/input и audience. reentryContext — приватная POST-команда вне profile/query cache.
Начальная association находится в guest['table-access']: portalAssociationStatement, preparePortalBookingProof, preparePortalReentryProof и associatePortalHistory. preparePortalReentryProof требует одновременно auth: { tableGuestToken, guestPortalToken }. Подготовка BOOKING и association допускают table-only или обе capabilities. Не помещайте credentials или Origin override в generated args. Настоящий OTP, согласие и повтор вводятся явно; неверные коды расходуют канонический бюджет, статус не опрашивается циклически.
Начальный вход использует guest.reservations.preparePortalEntry с auth.reservationManageToken либо guest['public-preorders'].preparePortal с настоящей READ SESSION в auth.preorderManageToken. Сохраняйте исходный Idempotency-Key. Результат содержит только приватный reentryContext hint и срок. Передайте hint и сохранённый requestId в guest['guest-portal'].requestReentry, затем действительно доставленный код с тем же requestId в confirmReentry. Храните полученное continuation приватно; клиент не выбирает контакт, личность или область доступа.
guest['guest-portal'].exchangeAccess принимает необязательный exchangeId UUID в generated body. Сохраните его с исходным gpb2 token до отправки. Явное восстановление повторяет точную пару после UNKNOWN или перезагрузки и возвращает только актуальный исходный результат и срок. Не создавайте другой nonce после неопределённого ответа и не считайте обмен без nonce восстанавливаемым. Истёкшие, отозванные и ротированные исходные полномочия не восстанавливаются.
import { createGuestClient } from '@hallify/sdk/browser';
const guest = createGuestClient();
// Сохраните исходные preparationKey и requestId до вызова функции.
// nativeSession — текущая легитимная preorder READ SESSION.
export async function requestPortalCode(
nativeSession: string,
preparationKey: string,
requestId: string
) {
const { data: prepared } = await guest['public-preorders'].preparePortal(
{ 'idempotency-key': preparationKey },
{ auth: { preorderManageToken: nativeSession } }
);
return guest['guest-portal'].requestReentry({
guestPortalReentryRequestDto: {
portalHint: prepared.reentryContext.hint,
requestId,
},
});
}
// Вызывайте только после ввода гостем действительно доставленного кода.
export function confirmPortalCode(requestId: string, code: string) {
return guest['guest-portal'].confirmReentry({
guestPortalReentryConfirmationDto: { requestId, code },
});
}Оставляйте partner Preorders на сервере
Node entry содержит ровно partner-preorders.catalog, createQuote, createOrder и getOrder. Уполномоченный администратор выдаёт настоящий scoped partner key в /venues/:venueId/settings/fulfillment → настройки ресурса → Интеграции при активном нативном публичном канале и service actor. Передавайте auth.preorderPartnerKey на каждый вызов; не включайте ключ в browser bundle и не подставляйте вымышленный browser Origin.
Прочитайте разрешённый каталог, проверьте выданный quote, сохраните точный quoteToken и передайте createOrder с одним сохранённым Idempotency-Key и неизменным payload. Эти четыре запроса используют Bearer partner authentication, а не HMAC. Quote token выдаётся сервером и не подписывается или восстанавливается SDK. Проверка исходящего preorder webhook — отдельный протокол, не рецепт подписи callback-симулятора.
Для DELIVERY каталог возвращает deliveryMethods, currency и timeZone. createQuote условно требует собственный исходный аргумент idempotency-key; сохраните его до запроса и удерживайте точное тело, включая исходное отсутствие deliveryMethod. Сохраните возвращённый deliveryQuoteId вместе с нативным quoteToken для createOrder. PREORDER_DELIVERY_QUOTE_UNKNOWN или PREORDER_DELIVERY_QUOTE_NOT_READY доступен через SdkError.apiCode; явно повторяйте тот же исходный запрос вместо нового ключа или предположения о наличии error.details. Принятый клиентский сбор отделён от последующей staff-стоимости перевозчика. Настройка и безопасные поля отслеживания описаны в руководстве партнёрских предзаказов.
import { createPartnerPreordersClient } from '@hallify/sdk/server';
const key = process.env.HALLIFY_PREORDER_PARTNER_KEY;
if (!key) {
throw new Error('Partner key is required');
}
const partner = createPartnerPreordersClient();
const { data: catalog } = await partner['partner-preorders'].catalog(
{ salesChannelId: '2604de3a-da74-4ad5-89f6-2dfe000d5391' },
{ auth: { preorderPartnerKey: key } },
);Сохраняйте исходную команду при неизвестности
SdkError раскрывает безопасные code, status, apiCode, requestId, retryAfter и outcome без сырых URL, тел или данных доступа. NOT_SENT, UNKNOWN и NOT_APPLICABLE описывают исходы запроса, включая неопределённость после отправленной мутации, отдельно от нативных бизнес-статусов. Timeout, abort после отправки, некорректный ответ или сетевой сбой могут оставить мутацию UNKNOWN. SDK не выполняет автоматические повторы и не создаёт новый idempotency key.
До отправки сохраняйте точные command key, payload и приватный журнал восстановления своего источника. Следуйте нативному восстановлению reservation/preorder/table или checkout с исходной identity. При конфликте перечитайте текущую ревизию и допустимые действия; храните исходные квитанции отдельно от текущего состояния. Ready/completed событие виджета, query возврата провайдера или квитанция PREPARED не доказывают списанные средства или итоговое нативное применение.
Соблюдайте границы пакета и runtime
SDK покрывает выбранные Guest PRO и четыре партнёрские операции с теми же нативными правилами и правами, что Hallify. Нативные публичные и партнёрские контракты предзаказов поддерживают настроенный выбор SELF, UBER_DIRECT и WOLT_DRIVE, исходные клиентские расчёты доставки и безопасную текущую проекцию отслеживания. Wolt Drive требует настоящие координаты доставки. Staff-настройки подключений, офферы отправки, вызов/отмена/readback курьера, локальное прерывание и staff-истории остаются вне allowlist SDK. SDK не предоставляет хранилище секретов, финансовые права сотрудников или активацию боевого перевозчика. Browser/device/storage, реальные DB/HTTP, merchant/provider, deployed artifact и version/package квалификации отделены от source-поставки и FAST checks.