@hexah/skin-sdk 0.2.0 → 0.9.1

package/README.md

@@ -5,8 +5,7 @@ deweloperzy budują własne podstrony (ekrany szablonu) i motywy, **bez dostępu
 
 Pakiet jest celowo „chudy": zawiera wyłącznie kontrakt (zero implementacji, zero importów
 z aplikacji, brak Reacta i kroku budowania). Implementacje read-modeli, usług platformy i
-prymitywów UI dostarcza **host** w runtime (docelowo przez Module Federation; lokalnie w
-repo: `frontend/common/skin-sdk/{runtime,ui,slots}.js`).
+prymitywów UI dostarcza **aplikacja-host** w runtime przez Module Federation (shareScope).
 
 ## Instalacja
 
@@ -28,20 +27,46 @@ import { SCREEN_KEYS, SLOT_KEYS, DEFAULT_TEMPLATE, SKIN_API_VERSION } from '@hex
 - `SKIN_API_VERSION` — wersja kontraktu, którą deklaruje skórka (host odrzuca niezgodny major).
 - Typy JSDoc: `ReportListItem`, `ReportListView`, `ReportListResult`, `Pagination`, `SkinScreenProps`.
 
-Read-modele/usługi (`useReports`, `useSnackbar`, `useDialog`, `useShard`…), prymitywy UI
-(`PageBox`, `HexahChip`, `DataList`…) i `useSlots()` paczka udostępnia jako **typowane atrapy**
-(`runtime-stubs.js`) — dają podpowiedzi w edytorze, a realne implementacje dostarcza host w
-runtime (Module Federation, shareScope). Atrapa wywołana poza hostem rzuca jasny błąd: skórka
-działa wyłącznie wewnątrz aplikacji Hexah. Bundler skórki dzieli te paczki z `import: false`,
-więc atrapy nigdy nie trafiają do bundla.
+### Hooki danych (per strona gry)
 
-## Wersjonowanie
+| Strona | Hook |
+| --- | --- |
+| Aktualności / Kurier | `useArticles` |
+| Harold (GPT) | `useGptThreads` |
+| Operacje | `useTales` |
+| Metropolia | `useTown` |
+| Frakcje | `useGuild` |
+| Kolonie | `useVillages` |
+| Zgłoszenia | `useReports` |
+| Konfiguracja | `useSettings` |
+| Zaopatrzenie | `useShop` |
+| Profil | `useAccountProfile` |
 
-`SKIN_API_VERSION` (semver): **major** = zmiana łamiąca powierzchnię, **minor** = dodanie
-zgodne wstecz, **patch** = bez zmiany powierzchni.
+### Stan i usługi
+
+Read-modele stanu: `useShard`, `useShardUser`, `useCharacter`, `useAccount`, `usePageData`,
+`useOnlineCharacters`. Usługi: `useSnackbar`, `useDialog`, `useGamePageShell`. Sloty hosta:
+`useSlots()` + `SLOT_KEYS`. Prymitywy UI: `PageBox`, `HexahChip`, `DataList`, `HexahPagination`,
+`AngularPanel`, `StandardButton`, `RoundAvatar`, `HexahCharacterSection`.
+
+Wszystko paczka udostępnia jako **typowane atrapy** — dają podpowiedzi w edytorze, a realne
+implementacje dostarcza host w runtime (Module Federation, shareScope). Atrapa wywołana poza
+hostem rzuca jasny błąd: skórka działa wyłącznie wewnątrz aplikacji Hexah. Bundler skórki dzieli
+te paczki z `import: false`, więc atrapy nigdy nie trafiają do bundla.
+
+## Tworzenie skórki
+
+Najszybciej wystartujesz przez scaffolder:
 
-## Dokumentacja
+```bash
+npm create @hexah/skin moja-skorka     # albo: npx @hexah/create-skin moja-skorka
+```
+
+Wygenerowany projekt zawiera gotowy build (rspack + Module Federation), przykładowy ekran i
+instrukcję podłączenia do środowiska testowego Hexah.
 
-- Przewodnik dewelopera skórek: `docs/skin-sdk/README.md`
-- Reguły: `docs/skin-sdk/SKIN_SDK_AI_RULES.md`
-- Granica publiczne/prywatne: `docs/skin-sdk/inventory-publicznego-api.md`
+## Wersjonowanie
+
+`SKIN_API_VERSION` (semver): **major** = zmiana łamiąca powierzchnię, **minor** = dodanie
+zgodne wstecz, **patch** = bez zmiany powierzchni. Skórka deklaruje wersję w configu; host
+odrzuca niezgodny major.

package/index.js

@@ -19,7 +19,7 @@
  * major. Bump: major = zmiana łamiąca powierzchnię, minor = dodanie zgodne wstecz,
  * patch = bez zmiany powierzchni.
  */
-const SKIN_API_VERSION = "0.2.0";
+const SKIN_API_VERSION = "0.9.0";
 
 /** Domyślny szablon, gdy motyw nie ma własnego wariantu wizualnego. */
 const DEFAULT_TEMPLATE = "medieval";
@@ -98,6 +98,31 @@ const SLOT_KEYS = Object.freeze({
  * @property {Pagination} pagination
  */
 
+/**
+ * @typedef {object} ArticleListView — paginacja listy artykułów (Aktualności/Kurier).
+ * @property {number} [page]
+ * @property {number} [pageSize]
+ */
+
+/**
+ * @typedef {object} Article — artykuł (read-model); pola dodatkowe z `getBySlug`.
+ * @property {number} id
+ * @property {string} title
+ * @property {string} slug
+ * @property {boolean} [pinned]
+ * @property {{ url?: string, name?: string }} [cover]
+ * @property {string} [createdAt]
+ * @property {number} [heartCount]
+ * @property {number} [uniqueViewCount]
+ * @property {boolean} [userHasHeart]
+ */
+
+/**
+ * @typedef {object} ArticleListResult
+ * @property {Article[]} results
+ * @property {Pagination} pagination
+ */
+
 /**
  * Kontrakt propsów ekranu skórki (komponent zarejestrowany pod `SCREEN_KEYS`).
  * Sloty (gotowe komponenty hosta) przychodzą w `slots`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hexah/skin-sdk",
-  "version": "0.2.0",
+  "version": "0.9.1",
   "description": "Publiczny, wersjonowany kontrakt SDK skórek Hexah (stałe + typy). Implementacje dostarcza host w runtime.",
   "main": "index.js",
   "types": "index.js",

package/runtime-stubs.js

@@ -58,6 +58,86 @@ const useDialog = hostProvided("useDialog");
 const useReports = hostProvided("useReports");
 /** @param {{ title?: string }} shell Ustawia tytuł/powłokę strony. @returns {void} */
 const useGamePageShell = hostProvided("useGamePageShell");
+/**
+ * API artykułów (Aktualności/Kurier).
+ * @returns {{
+ *   list: (data: import('./index').ArticleListView & { callback: (r:any)=>void }) => void,
+ *   getBySlug: (data: { slug: string, callback: (r:any)=>void }) => void,
+ *   recordView: (data: { slug: string, callback?: (r:any)=>void }) => void,
+ *   markKurierRead: (data: { slug: string, callback?: (r:any)=>void }) => void,
+ *   listComments: (data: { slug: string, page?: number, pageSize?: number, callback: (r:any)=>void }) => void,
+ *   createComment: (data: { slug: string, body: string, callback: (r:any)=>void }) => void,
+ *   toggleReaction: (data: { slug: string, callback: (r:any)=>void }) => void,
+ * }}
+ */
+const useArticles = hostProvided("useArticles");
+/**
+ * API wątków GPT (Harold).
+ * @returns {{
+ *   list: (data: { page?: number, pageSize?: number, callback: (r:any)=>void }) => void,
+ *   get: (data: { threadId: number, callback: (r:any)=>void }) => void,
+ *   create: (data: { message: string, callback: (r:any)=>void }) => void,
+ *   remove: (data: { threadId: number, callback: (r:any)=>void }) => void,
+ *   sendMessage: (data: { threadId: number, message: string, callback: (r:any)=>void }) => void,
+ * }}
+ */
+const useGptThreads = hostProvided("useGptThreads");
+/**
+ * API opowieści/operacji (lista, wyszukiwanie, podgląd, ulubione/preferencje, dołącz/opuść,
+ * subskrypcja). Rozgrywka w pokoju sesji jest po stronie hosta (poza tą powierzchnią).
+ * @returns {{
+ *   list: (data: { type?: string, filter?: string, page?: number, pageSize?: number, callback: (r:any)=>void }) => void,
+ *   search: (data: { callback: (r:any)=>void }) => void,
+ *   get: (data: { callback: (r:any)=>void }) => void,
+ *   getFavorites: (data: { callback: (r:any)=>void }) => void,
+ *   getPreferences: (data: { callback: (r:any)=>void }) => void,
+ *   togglePreference: (data: { callback: (r:any)=>void }) => void,
+ *   join: (data: { callback: (r:any)=>void }) => void,
+ *   leave: (data: { callback: (r:any)=>void }) => void,
+ *   toggleSubscribe: (data: { callback: (r:any)=>void }) => void,
+ *   checkSubscribe: (data: { callback: (r:any)=>void }) => void,
+ * }}
+ */
+const useTales = hostProvided("useTales");
+/**
+ * API budynków Metropolii (bank, mesa, zielarz, Voltar, ratusz, warsztat, kuźnia, praca).
+ * Metody: bankSend, innRest, innBuyTravelerKit, healerPlantsList, healerHeal, voltarToolsList,
+ * voltarBuy, hallTypes, hallPriceList, hallBuy, workshopPlansList, workshopPlanGet,
+ * workshopCraftItem, forgePlansList, forgePlanGet, forgeCraftMaterial, workPerform.
+ * @returns {Record<string, (data: { callback: (r:any)=>void }) => void>}
+ */
+const useTown = hostProvided("useTown");
+/**
+ * API Frakcji (gildii): create, join, list, search, get, sendCrabs, headquartersRestInfo,
+ * headquartersRest, leave, getPermissions, specialActions, getProperties, hexmap (populacje/
+ * aktywność), provinceInfo, publicStats, warehouse (get/deposit/withdraw), materials
+ * (get/donate/distribute).
+ * @returns {Record<string, (data: { callback: (r:any)=>void }) => void>}
+ */
+const useGuild = hostProvided("useGuild");
+/**
+ * API Kolonii (osad): found, takeAbandoned, get, list, build (create/cost/upgrade/demolish/
+ * move/resetAll), depositCrabs, withdrawCrabs, sendResourcesToGuild, abandon, rebellionResolve,
+ * taxesSet, governorAssign, techniqueList, techniqueUpgrade, hexDecorationsUpdate, nameUpdate.
+ * @returns {Record<string, (data: { callback: (r:any)=>void }) => void>}
+ */
+const useVillages = hostProvided("useVillages");
+/**
+ * API Konfiguracji: updateSetting, setInvisibleOnline, updateNewsletterSubscription.
+ * @returns {Record<string, (data: { callback: (r:any)=>void }) => void>}
+ */
+const useSettings = hostProvided("useSettings");
+/**
+ * API sklepu (Zaopatrzenie): getOffers, getItems, buyItem, startPayment.
+ * @returns {Record<string, (data: { callback: (r:any)=>void }) => void>}
+ */
+const useShop = hostProvided("useShop");
+/**
+ * API Profilu/konta: getAccountInfo, getBlockedList, blockUser, unblockUser, linkDiscord,
+ * getGlobalStats.
+ * @returns {Record<string, (data: { callback: (r:any)=>void }) => void>}
+ */
+const useAccountProfile = hostProvided("useAccountProfile");
 
 /* ---------- Sloty (host) ---------- */
 /** Provider slotów hosta (host montuje go sam; skórka go nie używa). */
@@ -118,6 +198,15 @@ module.exports = {
   useDialog,
   useReports,
   useGamePageShell,
+  useArticles,
+  useGptThreads,
+  useTales,
+  useTown,
+  useGuild,
+  useVillages,
+  useSettings,
+  useShop,
+  useAccountProfile,
   SlotsProvider,
   useSlots,
   PageBox,