# STROMCOM.cz — instrukce pro AI asistenta k integraci > Tento soubor je určený **AI asistentovi** (Claude, ChatGPT, Copilot, Cursor…), který > pomáhá vývojáři zapojit STROMCOM.cz do jeho interního systému. Ulož ho do repozitáře > (např. `docs/stromcom.md`) a odkaž na něj z `CLAUDE.md` / `AGENTS.md` / pravidel editoru. > > Aktuální verze: https://www.stromcom.cz/public/static/stromcom-ai.md > Lidský přehled: https://www.stromcom.cz/ai-integrace/ --- ## 0. Pravidla, která nikdy neporušuj 1. **Nikdy nesahej do datové vrstvy STROMCOM.** - `window.stromComDL` (nebo `window.DL`) je **interní** objekt snippetu. Nečti ho, nezapisuj do něj, nevolej na něm `.push()`, nepřiřazuj mu nový objekt, nedrž si na něj referenci. Snippet ho po načtení nahradí proxy a čte z něj data v interním tvaru — jakýkoli přímý zápis se tiše ztratí nebo rozbije vykreslení. - Se snippetem komunikuj **výhradně přes fasádu `window.stromCom`** (`initUser`, `thread`, `home`, `conf`) nebo přes oficiální balíky (PHP / React) a Customer API. - Nesahej do vnitřku widgetu: Shadow DOM, iframe aplikace, `postMessage` protokol mezi stránkou a iframem, URL parametry iframu, interní třídy a CSS selektory uvnitř. Nic z toho není veřejné API a mění se bez ohlášení. Vzhled měň jen přes podporované CSS klíče (§7.4). - Nevolej App API (`/api/app/v1/`) ze serveru jako „integrační“ API — je to interní API widgetu jednající jménem koncového uživatele. Pro serverovou integraci je Customer API (§10). - Neobcházej limity plánu (např. zakládáním více projektů, rotací uživatelů). 2. **Tajemství patří na server.** Klíč typu `customer`/`both` (Customer API), tajný klíč pro hashování kódů a secret WebHooků nikdy nesmí do HTML, JS bundlu, mobilní aplikace ani URL. 3. **Identitu uživatele určuje backend zákazníka**, ne prohlížeč. Snippet vykresli až po ověření přihlášení ve vlastní aplikaci (§5). 4. **Neodhaduj API.** Když tu něco chybí, podívej se do OpenAPI specifikace (https://www.stromcom.cz/docs/customer/openapi.json) nebo se zeptej vývojáře. Nevymýšlej metody fasády, conf klíče ani endpointy, které tu nejsou. 5. **Pokud oficiální balík danou věc neumí, nepatchuj ho a nepiš kolem něj hacky** — přepni na ruční JS integraci přes `window.stromCom` (§6), která umí všechno. Kdy přesně, viz §8.4 a §9.4. 6. **Měň jen to, co integrace potřebuje.** Úpravy omez na vložení snippetu, předání uživatele, kontejnery vláken, konfiguraci widgetu a volání Customer API / WebHooky. Nesahej do ostatní logiky, dat, databáze, autentizace ani nastavení zákazníkova systému a nedělej refaktory „po cestě“. Když integrace zásah jinam opravdu vyžaduje (např. nový sloupec, změna routy, úprava CSP hlavičky), nejdřív to vývojáři popiš a počkej na souhlas. --- ## 1. Co STROMCOM je STROMCOM.cz je B2B SaaS pro **interní firemní komunikaci v kontextu business entit**. Zákazník vloží JS snippet do svého **interního** systému (administrace e-shopu, ERP, CRM, helpdesk) a jeho **zaměstnanci** pak u konkrétní objednávky / ticketu / zakázky vedou vlákno zpráv (zmínky `@kolega`, přílohy, reakce, notifikace). **Není to live chat pro návštěvníky webu.** Neintegruj ho na veřejný web pro anonymní uživatele — každý uživatel widgetu je přihlášený zaměstnanec zákazníka. ### Doménový model | Pojem | Význam | Identifikace | |---|---|---| | Zákazník | firma, která si službu platí; spravuje se v panelu `/customer/` | účet v panelu | | Projekt | jedna integrace (jeden systém). Má plán (předplatné), klíče a uživatele | `clientKey` | | Uživatel | zaměstnanec, který píše zprávy | `code` = tvoje stabilní ID (hash), STROMCOM přidělí `hash` | | Vlákno | diskuse u jedné business entity | `code` = tvůj klíč entity, např. `order-12345` | | Zpráva | HTML zpráva ve vlákně, s přílohami a reakcemi | `hash` | Uživatelé i vlákna vznikají **automaticky** při prvním použití ve snippetu (pokud to projekt povoluje — výchozí stav ano). Nic není potřeba předem synchronizovat. --- ## 2. Registrace a nastavení projektu (dělá člověk, AI navede) AI nemůže zaregistrovat účet ani vygenerovat klíče — vyzvi vývojáře k těmto krokům: 1. **Registrace:** https://www.stromcom.cz/registration/ (jméno, příjmení, e-mail, heslo; firma / IČO / DIČ volitelně). Přihlásit jde i přes Google, Microsoft, GitHub, Facebook. Když je registrace v režimu jen na pozvánku, je potřeba kód pozvánky. 2. **Potvrzení e-mailu:** odkaz z e-mailu (`/confirmation/emailAddress/?token=…`). Službu neblokuje, ale bez potvrzení nejde obnova hesla. Znovu poslat jde z profilu. 3. **Založení projektu:** panel → `/customer/project/create/` → výběr plánu → název projektu. Placený plán vytvoří objednávku k úhradě. Nový projekt může začít zkušebním obdobím; aktuální podmínky jsou na ceníku (§3). 4. **Klíče:** `/customer/project/{id}/credentials/` (záložka **API Klíče**). - **Client Key** — 50 znaků `[a-zA-Z0-9]`, veřejný identifikátor projektu. - **Client Secret** (bearer token) — 50 znaků, je v detailu klíče `/customer/project/{id}/credentials/{credential_id}/` (tlačítko kopírovat). Tamtéž hotový snippet. - **Typ klíče:** | Typ | Panel | K čemu | |---|---|---| | `app` | „Snippet API (výchozí)“ | do snippetu v prohlížeči — **jediný typ, který smí do HTML** | | `customer` | „Projekt API (vlastní)“ | server→server Customer API; nikdy do prohlížeče | | `both` | „Obojí“ | nedoporučeno — v prohlížeči by odhalil Customer API | Typ `customer`/`both` jde zvolit jen s plánem, který má API. Doporučení: **dva klíče** — výchozí `app` pro snippet, samostatný `customer` pro server. - **Omezení klíče:** „Dovolené adresy (origin)“ (např. `https://admin.example.com, https://*.example.com`), „Povolené IP (IPv4)“ (masky i CIDR), expirace. Snippetový klíč omez na origin interního systému, serverový na IP serveru. - Klíč jde **přegenerovat** (starý přestane platit). Výchozí klíč nejde smazat. 5. **Další nastavení projektu** (záložky pod `/customer/project/{id}/`): Uživatelé, Skupiny, WebHooky, Konfigurace editoru (pravidla URL → entita, §7.5), Nastavení (vlastní CSS…), Konfigurace (mj. „Důvěřovat jakékoli doméně“ = vypnutí kontroly originu), Náhled, Integrace. 6. **Kolegové v panelu** (správa fakturace, projektů): `/customer/user/` s rolemi Administrátor, Správce, Fakturace. To jsou účty do panelu, **ne** uživatelé widgetu. Vyzkoušet bez integrace: https://www.stromcom.cz/playground/ (vygeneruje kód pro JS / PHP / React proti vlastnímu projektu). --- ## 3. Plány a co odemykají Plány, ceny i limity se mění — **nikdy je neopisuj z paměti ani z tohoto souboru.** - Lidský ceník: https://www.stromcom.cz/cenik/ - **Strojově čitelný ceník: https://www.stromcom.cz/cenik.json** (veřejný, bez autentizace; `/sk/cenik.json` = slovenský trh v EUR). Načti ho, když potřebuješ zjistit, který plán odemyká funkci, kterou integrace potřebuje: ```json {"status":"success","data":{ "plans":[{"name":"…","slug":"…","url":"/balicek/…/","type":"free|subscription|…", "available":,"currency":"CZK","pricing":[{"pricePerMonth":…,"pricePerYear":…,"vatRate":…}], "features":{"maxActiveUser":,"maxThreadInMonth":,"attachmentMaxSize":, "allowProjectCustomization":,"allowAPI":,"allowEmbed":,"allowWebHook":,…}}], "features":[{"code":"maxActiveUser","name":"…","type":"limit","unit":null},…]}} ``` - `type: "limit"` → číslo, `null` = neomezeno; `type: "boolean"` → `true`/`false`, nebo `"inDevelopment"` (funkce se připravuje — nepočítej s ní). - Klíče, které integraci rozhodují: `allowAPI` (Customer API, §10), `allowEmbed` (§10.4), `allowWebHook` (§11), `allowUserGroup` (skupiny), `allowProjectCustomization` (`appCSSPath`, §7.4), `maxActiveUser`, `maxThreadInMonth`, `attachmentMaxSize` (MB), `messageMaxHistory` (měsíce). - `available: false` → plán teď nejde objednat (nákup je dočasně vypnutý), `pricing` je prázdné. - Plány mimo veřejný ceník (zkušební období, individuální smlouvy) v JSON nejsou. - Co má **konkrétní projekt**, je v panelu na záložce Předplatné, přes Customer API `GET project/` (pole `allow*` = skutečně platná hodnota) — to je zdroj pravdy pro běžící integraci. Doplňky (uživatelé, úložiště, balíčky vláken) jdou dokoupit v záložce Doplňky. **Jak se projeví limit:** - Customer API vrací **HTTP 402** s kódem `USER_LIMIT_REACHED`, `THREAD_LIMIT_REACHED`, `MESSAGE_LIMIT_REACHED`, `STORAGE_LIMIT_REACHED`, `MESSAGE_STORAGE_LIMIT_REACHED`. - Uživatelé nad limit jsou **uspáni** (suspended), založení přes API nad limit vytvoří uživatele rovnou uspaného (s varováním v `meta.warnings`). - Zprávy starší než historie plánu se nevracejí. - Měsíční limity se nulují 1. dne v měsíci 00:00 UTC. - Funkce, kterou plán nemá, vrací `PROJECT_FUNCTION_NOT_ALLOWED` (HTTP 401) s `details.function` (`embed`, `webHook`, `userGroup`, …); nastavení mimo plán se v `PATCH project/` tiše ignoruje. - `appCSSPath` / vlastní CSS aplikace se bez nároku tiše nepoužije (rám widgetu jde stylovat vždy). Když integrace potřebuje funkci, kterou plán nemá, **řekni to vývojáři** a navrhni upgrade (`/customer/project/{id}/subscription/upgrade/`) — nehledej obchvat. --- ## 4. Ověření (co existuje a co ne) | Ověření | Stav | Jak | |---|---|---| | E-mail zákazníka / účtu | existuje | odkaz v e-mailu po registraci, znovu z profilu | | Omezení klíče na origin | existuje, volitelné | „Dovolené adresy (origin)“ u klíče; bez nastavení widget běží s varováním | | Omezení klíče na IP | existuje, volitelné | „Povolené IP“ u klíče — ideální pro serverový klíč a intranety | | Expirace klíče | existuje, volitelné | v detailu klíče | | Podpis WebHooků | existuje, volitelné | `secret` u WebHooku → hlavička `X-Stromcom-Signature` (§11) | | Podepsaná identita uživatele ve snippetu (JWT/HMAC) | **neexistuje** | viz §5 — chraň se hashováním kódů | | Ověření firmy (ARES/VIES), domény (DNS TXT), KYC | **neexistuje** | nenavrhuj to jako krok integrace | --- ## 5. Bezpečnostní model identity — přečti před psaním kódu - Snippet posílá na server `Bearer :@`. Server ověří **projekt** podle secretu a uživatele najde **jen podle `code`**. Neexistuje podpis ani token per uživatel. - `clientSecret` snippetového klíče je **nutně veřejný** (je v HTML v `data-cs`). Kdo ho zná a uhodne `code` uživatele, může se za něj vydávat. - Proto: 1. **Nikdy nepoužívej jako `code` čitelné interní ID** (`1`, `42`, e-mail). Posílej **HMAC hash** ID spočítaný na serveru vlastním tajným klíčem (doporučeně HMAC-SHA256, base62 nebo hex). Klíč pro hash drž na serveru a **neměň ho** — změna = všichni uživatelé i vlákna dostanou novou identitu. 2. Totéž doporučeně pro `code` vláken (aby nešlo hádat cizí entity). 3. Omez snippetový klíč na origin interního systému (případně IP). 4. `initUser` vypisuj **až po ověření přihlášení** ve vlastní aplikaci; nepřihlášenému nic. 5. Read-only uživatele (např. externí) označ `readOnly: true`. - Pravidla kódů (server je vynucuje): - **uživatel** `code`: 1–100 znaků `[a-zA-Z0-9._@+-]` (zakázané `:` a `/`). Po založení je to identita uživatele — musí být stabilní. - **vlákno** `code`: 1–100 znaků `[a-zA-Z0-9_-]`. Doporučený tvar `{typ}-{id}` (`order-12345`), resp. hash z toho. Hash v PHP bez balíku (stejný výsledek jako `stromcom/php-snippet` s `base62: false`): ```php $userCode = hash_hmac('sha256', 'user-' . $user->id, $_ENV['STROMCOM_CODE_SECRET']); // 64 hex znaků ``` V Node.js: `crypto.createHmac('sha256', secret).update('user-' + id).digest('hex')`. --- ## 6. Rozhodovací strom — kterou cestu integrace zvolit ``` Kde poběží widget? ├─ Ve webové aplikaci, kde ovládám HTML │ ├─ Server-renderované stránky v PHP (klasická administrace, Laravel/Nette/Symfony bez SPA) │ │ → stromcom/php-snippet (§8); dynamiku po načtení dopiš ručně přes window.stromCom │ ├─ React SPA / Next.js │ │ → @stromcom/react-snippet (§9); co neumí, přes useStromcom() (§9.4) │ └─ Cokoli jiného (Vue, Angular, Svelte, jQuery, Python/Java/.NET backend, Shoptet admin…) │ → ruční JS přes window.stromCom (§7); hashe kódů počítej na backendu ├─ V desktopové / mobilní aplikaci, webview, nebo nemám kontrolu nad HTML / přísné CSP │ → Embed odkaz z Customer API (§10.4) — plán s Embed └─ Na serveru bez UI (synchronizace, automatické zprávy, reporty) → Customer API: PHP SDK stromcom/customer-sdk nebo REST (§10) — plán s API → reakce na události → WebHooky (§11) — plán s WebHooky ``` Cesty jdou kombinovat (snippet v administraci + Customer API pro systémové zprávy + WebHooky). --- ## 7. Ruční JS integrace (`window.stromCom`) — referenční, umí vše ### 7.1 Bootstrap snippet Vlož **jednou** na stránku, co nejdřív (do ``). Vytvoří fasádu `window.stromCom`, která volání do načtení skriptu zafrontuje — pořadí volání pak nehraje roli. ```html ``` - Tento kód **neupravuj** kromě posledního řádku (klíče, případně název fasády). Je to jediné místo, kde se `stromComDL` legitimně objevuje — v tvém kódu nikde jinde. - `` = secret klíče typu **`app`**. - Výchozí jazyk před `conf` jde dát přes `j.dataset.lang='cs';` (`en`, `cs`, `sk`). - Pro CSP bez `'unsafe-inline'` dej skriptu `nonce`, nebo ho přesuň do vlastního `.js` souboru (§12). - Staging prostředí: `https://cdn.staging.stromcom.cz/loader.js` (jen pokud ho máte přidělené). ### 7.2 Fasáda — čtyři metody Žádná nic nevrací a nejde z nich nic přečíst. | Metoda | Chování | |---|---| | `stromCom.initUser(user)` | nastaví aktuálního uživatele; **přepíše** předchozího | | `stromCom.conf(options)` | nastaví konfiguraci; **přepíše celou** předchozí (nespojuje!) | | `stromCom.thread(element, thread)` | vykreslí vlákno do elementu; každé volání **přidá** další | | `stromCom.home(element)` | vykreslí přehled vláken / notifikací do elementu | ```js stromCom.initUser({ code: 'Xb3k…', // povinné — HMAC hash ID z backendu (§5) name: 'Jana Nováková', // povinné — bez jména se widget nevykreslí! emailAddress: 'jana@firma.cz', // volitelné — e-mailové notifikace readOnly: false, // volitelné — true = jen čte avatarURL: 'https://…/jana.png', // volitelné }); stromCom.thread(document.querySelector('#stromcom-thread'), { code: 'order-12345', // povinné (nebo hash existujícího vlákna) name: 'Objednávka 12345', // výchozí document.title url: 'https://admin.example.com/orders/12345', // odkaz zpět z notifikací; výchozí location.href userHint: true, // false = bez nabídky @zmínek (vlákno jako poznámky) attributes: [ // experimentální: max 20 položek, krátké hodnoty { name: 'Stav', value: 'Expedováno' }, ], }); stromCom.home(document.querySelector('#stromcom-home')); ``` - `element` musí být **HTMLElement** (nebo funkce / Promise vracející element), ne selektor. - Widget **nic nevykreslí, dokud `initUser` nemá `code` i `name`** — v konzoli je `[stromcom][user] not set, waiting…`. - Kontejneru vlákna dej výšku (např. `height: 500px`), jinak bude prázdný pruh. - Více vláken na stránce = více volání `thread()` do různých elementů. ### 7.3 `conf` — všechny klíče **Volá se jednou s kompletním objektem.** Každé další volání nahradí celou konfiguraci — když měníš jeden klíč, pošli znovu všechny (drž si objekt u sebe a slučuj ho sám). | Klíč | Typ / výchozí | Účel | |---|---|---| | `theme` | `'stromcom-default' \| 'stromcom-dark' \| null` | téma; mění se živě | | `language` | `'en' \| 'cs' \| 'sk' \| null` (null = jazyk prohlížeče, fallback en) | změna znovu načte iframy | | `appFrameCSSPath` | `string \| string[]` | CSS rámu widgetu (shadow root kolem iframu) — bez omezení plánem | | `appCSSPath` | `string \| string[]` | CSS uvnitř aplikace (iframe) — **jen plán s vlastním vzhledem** | | `notificationElementPosition` | `null` (= žádná bublina), `1` vlevo nahoře, `2` vpravo nahoře, `3` vpravo dole, `4` vlevo dole | plovoucí bublina s počtem nepřečtených | | `notificationElementShowAlways` | `false` | bublina i při nule | | `notificationElementStyles` | `{cssProp: value}` | inline styly bubliny, typicky `{zIndex: 1000}` | | `notificationElementCSSPath` | `string \| false` | **nahradí** výchozí CSS bubliny (`false`/`''` = žádné) | | `notificationElementNoShadowRoot` | `false` | bublina do běžného DOM (výchozí CSS se pak nevkládá) | | `notificationElementTargetElement` | element / funkce / Promise | kam bublinu vložit | | `onNotification` | `(payload) => void` | data notifikací při každém dotazu (~120 s) — vlastní počítadlo v menu | | `notificationRenderer` | `(api, dl, builder) => updateFn?` | úplně vlastní vykreslení bubliny | | `notificationElementBeforeRender`, `notificationElementAfterRender` | `(api, dl, builder)` | háčky kolem bubliny | | `homeBeforeRender` | `(node, homeAppApi, api)` | před otevřením přehledu po kliknutí na bublinu | | `onLoad` | `(api)` | start widgetu; `api.on(api.EVENT.APP_ADD, (app) => …)`; `app.show/hide/openThread/openHome/maximalize/normalize` | | `entityResolve` | `async ({type, id, groups, url}) => ({title, url?, fields:[{label, value}]})` | náhled entity při najetí na odkaz v zprávě (§7.5) | Callbacky berou funkci nebo Promise funkce. Výjimka v callbacku se zaloguje a klíč se chová jako nenastavený. Neznámé klíče se ignorují. ```js stromCom.conf({ language: 'cs', theme: 'stromcom-default', notificationElementPosition: 3, notificationElementStyles: { zIndex: 1000 }, onNotification: (payload) => updateMenuBadge(payload), entityResolve: async ({ type, id }) => { const order = await fetch(`/api/orders/${id}`).then(r => r.json()); return { title: `Objednávka #${order.number}`, url: order.detailUrl, fields: [{ label: 'Stav', value: order.status }] }; }, }); ``` ### 7.4 Vzhled — tři vrstvy 1. **Tvoje stránka** — jen loading overlay; styluješ si ji sama. 2. **Rám widgetu** (shadow root) — `appFrameCSSPath`. Stránkové CSS sem nedosáhne. 3. **Aplikace v iframu** — vlastní CSS z Nastavení projektu, pak `appCSSPath`. Jen plán s vlastním vzhledem. Bublina má vlastní shadow root (`notificationElementCSSPath`). Naše CSS se načítá vždy dřív než tvoje, takže jde přebít. **Nepiš selektory do vnitřku widgetu z CSS stránky** — nefungují a nejsou podporované. ### 7.5 Odkazy na entity ve zprávách (`entityResolve`) V panelu → Konfigurace editoru se nastaví pravidla: typ (`[a-z0-9_]`), popisek, regex na URL, skupina s ID a šablona odkazu. Když uživatel vloží do zprávy URL odpovídající pravidlu, vznikne „chip“ entity. Bez `entityResolve` funguje jako obyčejný odkaz; s ním ukáže při najetí náhled z dat, která vrátíš (volá se v prohlížeči — data si načti z vlastního API přihlášeného uživatele). ### 7.6 SPA a dynamické změny - **Změna stránky / entity:** vytvoř **nový** kontejner a zavolej `thread()` znovu. Na stejný element nejde volat `thread()` dvakrát (shadow root nejde recyklovat). Snippet nesleduje router. - **Odebrání vlákna:** odstraň kontejner z DOM — není na to metoda; snippet se odpojí sám. - **Změna uživatele:** `initUser(nový)` a **znovu vytvoř** kontejnery vláken a home (běžící iframy si uživatele převzaly při načtení). - **Odhlášení:** odstraň kontejnery a přestaň volat `initUser`. - **Změna jazyka/tématu za běhu:** `conf({...celý objekt...})`. ### 7.7 Ověření, že integrace funguje 1. V konzoli prohlížeče nejsou chyby s prefixem `[stromcom]` (`No project configuration found`, `user not set`, `Cannot create APP, argument must be an HTML element`, `Unknown key`…). 2. Network: `loader.js` z `cdn.stromcom.cz` (200), iframe z `app.stromcom.cz`, dotazy na `www.stromcom.cz/api/app/v1/…` (200, ne 401). 3. Uživatel se objeví v panelu → projekt → Uživatelé; vlákno po první zprávě v přehledu. 4. Druhý uživatel (jiný prohlížeč) vidí stejné vlákno u stejné entity a dostane notifikaci po `@zmínce`. 5. 401 = špatný secret / typ klíče / origin mimo povolené / expirovaný klíč / neaktivní projekt. --- ## 8. PHP: `stromcom/php-snippet` Generuje bootstrap a volání fasády jako inline `