@hezzlgames/sdk 1.1.0

package/index.cjs

@@ -0,0 +1,7 @@
+/* CommonJS-вход пакета: require('@hezzlgames/sdk') → объект Hezzl. */
+'use strict';
+require('./hezzl-sdk.js');
+const Hezzl = globalThis.Hezzl;
+module.exports = Hezzl;
+module.exports.Hezzl = Hezzl;
+module.exports.default = Hezzl;

package/index.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Hezzl Games SDK — типы. Полные требования: docs/GAME-REQUIREMENTS.md
+ * в репозитории play.hezzl.com; ссылки на разделы ведут туда.
+ */
+
+/** Команды центра, которые игра может обрабатывать (3.1). */
+export type Command =
+  | 'mute' | 'haptics' | 'pause' | 'resume' | 'restart'
+  | 'setlang' | 'settheme' | 'setaccent';
+
+/** Уведомления центра: приходят сами, не в ответ (3.1, 7.8, 7.9). */
+export type Notice =
+  | 'signedin' | 'signedout' | 'signincancelled' | 'profile'
+  | 'balance' | 'walletclosed';
+
+/** Умения центра из ack (3.8). */
+export type CentreAbility =
+  | 'share' | 'support' | 'exit' | 'auth' | 'profile' | 'storage' | 'balance';
+
+export type Mode = 'unknown' | 'centre' | 'standalone';
+export type GameMode = 'quick' | 'levels' | 'pvp_bot' | 'arena' | 'hotseat';
+export type Orientation = 'portrait' | 'landscape' | 'any';
+export type Lang = 'ru' | 'en' | '';
+export type Theme = 'light' | 'dark' | '';
+
+/** Причины отказа. Ветвиться по ним, не по тексту (7.6, 7.9). */
+export type Reason =
+  | 'unavailable' | 'quota' | 'invalid' | 'unknown'
+  | 'insufficient' | 'cancelled' | 'signin' | 'notfound' | 'disabled';
+
+export interface Refusal extends Error {
+  reason: Reason;
+  /** Сколько на балансе — у денежных отказов. */
+  amount?: number;
+  /** Сколько не хватило — у insufficient. */
+  need?: number;
+}
+
+export interface Settings {
+  lang: Lang;
+  theme: Theme;
+  /** Шесть шестнадцатеричных знаков без решётки или пустая строка. */
+  accent: string;
+  muted: boolean;
+  haptics: boolean;
+  /** Метка партнёра, уже проверенная маской (раздел 2). */
+  ref: string;
+}
+
+export interface Profile {
+  userId: string;
+  name?: string;
+  avatar?: string;
+  age?: number;
+  gender?: string;
+}
+
+export interface Currency {
+  key?: string;
+  title?: string;
+  icon?: string;
+  /** Последняя известная сумма; null, пока не приходила. */
+  amount: number | null;
+}
+
+export interface Good {
+  id: number | string;
+  title: string;
+  picture?: string;
+  price: number;
+  award: Record<string, unknown>;
+}
+
+export interface Handlers {
+  mute?(muted: boolean, data: Record<string, unknown>): void;
+  haptics?(enabled: boolean, data: Record<string, unknown>): void;
+  pause?(): void;
+  resume?(): void;
+  restart?(): void;
+  setlang?(lang: 'ru' | 'en', data: Record<string, unknown>): void;
+  settheme?(theme: 'light' | 'dark', data: Record<string, unknown>): void;
+  setaccent?(hex: string, data: Record<string, unknown>): void;
+  signedin?(userId: string, data: Record<string, unknown>): void;
+  signedout?(): void;
+  signincancelled?(): void;
+  profile?(profile: Profile | null, data: Record<string, unknown>): void;
+  /** Баланс изменился — по любой причине (7.9). */
+  balance?(amount: number | null, data: { amount?: number; currency?: Currency; signedIn?: boolean }): void;
+  walletclosed?(amount: number | null, data: { amount?: number; bought?: boolean }): void;
+}
+
+export interface InitOptions {
+  /** Ярлык из каталога, как в hezzl.json. */
+  id: string;
+  version: string;
+  modes?: GameMode[];
+  orientation?: Orientation;
+  on?: Handlers;
+  /** Отладочный вывод в консоль. В собранной игре — false (раздел 38). */
+  debug?: boolean;
+}
+
+export interface StorageOptions {
+  /** Уносить ли на сервер, когда человек войдёт (7.2). */
+  sync?: boolean;
+  /** Версия формата записи (7.7). */
+  schema?: number;
+}
+
+export interface HezzlStorage {
+  get<T = unknown>(key: string): Promise<T | null>;
+  set(key: string, value: unknown, opts?: StorageOptions): Promise<void>;
+  remove(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+export interface AuthAnswer { signedIn: boolean; code?: string; rid?: string }
+export interface ProfileAnswer { signedIn: boolean; profile?: Profile; rid?: string }
+export interface BalanceAnswer { signedIn: boolean; amount: number; currency?: Currency; rid?: string }
+export interface GoodsAnswer { goods: Good[]; currency?: Currency; rid?: string }
+export interface BuyAnswer {
+  ok: true;
+  goodId: number | string;
+  /** Сколько осталось. */
+  amount: number;
+  /** Что выдано — из ответа центра, не из своих ожиданий. */
+  award: Record<string, unknown>;
+  issued?: { id: number; rewardId: number; status: string };
+}
+export interface SpendAnswer { ok: true; amount: number; spent: number }
+export interface WalletAnswer { closed: true; amount: number; bought: boolean }
+
+export interface HezzlSDK {
+  /** Версия протокола (3.2). */
+  readonly sdk: number;
+  /** Версия пакета @hezzlgames/sdk. */
+  readonly version: string;
+  readonly settings: Settings;
+
+  init(about: InitOptions): HezzlSDK;
+  /** Игра приняла ввод. Обязателен: по нему центр гасит заставку (раздел 5). */
+  ready(extra?: Record<string, unknown>): HezzlSDK;
+  mode(): Mode;
+  can(what: CentreAbility): boolean;
+  on(name: Command | Notice, fn: (value: unknown, data: Record<string, unknown>) => void): HezzlSDK;
+  resolve<T>(name: keyof Settings, saved: T | '' | null | undefined, fallback: T | (() => T)): T;
+
+  gameStart(about?: Record<string, unknown>): void;
+  score(value: number, about?: Record<string, unknown>): void;
+  milestone(what: string, value?: unknown): void;
+  levelComplete(about?: Record<string, unknown>): void;
+  levelFailed(about?: Record<string, unknown>): void;
+  gameOver(about?: Record<string, unknown>): void;
+
+  share(about?: { text?: string; image?: string }): void;
+  support(about?: { message?: string; state?: Record<string, unknown> }): void;
+  exit(): void;
+  signin(): void;
+  auth(): Promise<AuthAnswer>;
+  profile(need?: Array<keyof Profile>): Promise<ProfileAnswer>;
+  error(code: 'asset_load' | 'storage_write' | 'webgl_lost' | 'runtime' | string, message?: string, fatal?: boolean): void;
+
+  /* валюта центра, 7.9 */
+  currency(): Currency | null;
+  balance(): Promise<BalanceAnswer>;
+  goods(): Promise<GoodsAnswer>;
+  buy(goodId: number | string, opts?: { wallet?: boolean }): Promise<BuyAnswer>;
+  spend(amount: number, opts?: { item?: string; wallet?: boolean }): Promise<SpendAnswer>;
+  wallet(opts?: { need?: number; reason?: string }): Promise<WalletAnswer>;
+
+  storage: HezzlStorage;
+}
+
+export declare const Hezzl: HezzlSDK;
+export default Hezzl;
+
+declare global {
+  interface Window { Hezzl: HezzlSDK }
+  var Hezzl: HezzlSDK;
+}

package/index.mjs

@@ -0,0 +1,7 @@
+/* ESM-вход пакета. Сам SDK — IIFE, который объявляет window.Hezzl:
+   импорт ради побочного эффекта, потом отдаём объект. Один исходник
+   на все три способа подключения. */
+import './hezzl-sdk.js';
+const Hezzl = globalThis.Hezzl;
+export { Hezzl };
+export default Hezzl;

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@hezzlgames/sdk",
+  "version": "1.1.0",
+  "description": "Hezzl Games SDK: договор игры с игровым центром play.hezzl.ru — настройки, рукопожатие, хранилище, валюта центра",
+  "license": "UNLICENSED",
+  "homepage": "https://play.hezzl.ru",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hezzl/play.hezzl.com.git",
+    "directory": "sdk"
+  },
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "browser": "./hezzl-sdk.js",
+  "unpkg": "./hezzl-sdk.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "default": "./hezzl-sdk.js"
+    },
+    "./hezzl-sdk.js": "./hezzl-sdk.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "hezzl-sdk": "bin/hezzl-sdk.mjs"
+  },
+  "files": [
+    "hezzl-sdk.js",
+    "index.mjs",
+    "index.cjs",
+    "index.d.ts",
+    "bin/",
+    "demo/",
+    "README.md"
+  ],
+  "sideEffects": true,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/run.mjs",
+    "stand": "node bin/hezzl-sdk.mjs stand",
+    "check": "node bin/hezzl-sdk.mjs check demo",
+    "prepack": "npm test && npm run check"
+  },
+  "keywords": [
+    "hezzl",
+    "games",
+    "sdk",
+    "postmessage",
+    "game-centre"
+  ]
+}