@stromcom/react-snippet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) STROMCOM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# @stromcom/react-snippet
+
+React integration for the [STROMCOM](https://www.stromcom.cz) chat widget. Loads the SDK, identifies users, and embeds threads as plain React components.
+
+Plain JavaScript with hand-written TypeScript declarations — works in JS and TS projects, no transpilation surprises.
+
+The matching backend helper is [`stromcom/php-snippet`](https://github.com/stromcom/php-snippet) — it hashes user/thread codes server-side (which you must do).
+
+## Requirements
+
+- React **17+**
+- A pair of `clientKey` / `clientSecret` from the STROMCOM dashboard
+- A backend that can hash codes (typically `stromcom/php-snippet`)
+
+## Installation
+
+```bash
+npm install @stromcom/react-snippet
+# or
+pnpm add @stromcom/react-snippet
+# or
+yarn add @stromcom/react-snippet
+```
+
+## Quick start
+
+Wrap your app in `<StromcomProvider>`. It injects the loader script once and exposes the `stromCom` API to children. Components below queue their calls synchronously, so you don't need to wait for the loader to be ready.
+
+```jsx
+import {
+  StromcomProvider,
+  StromcomConf,
+  StromcomUser,
+  StromcomThread,
+  StromcomHome,
+} from '@stromcom/react-snippet';
+
+export default function App() {
+  return (
+    <StromcomProvider clientKey="your-client-key" clientSecret="your-bearer-token">
+      <StromcomConf
+        notificationElementPosition={4}
+        onNotification={(count) => console.log('unread:', count)}
+      />
+
+      <StromcomUser code={user.stromcomHash} name={user.name} emailAddress={user.email} />
+
+      <StromcomThread
+        code={order.stromcomHash}
+        name={`Order #${order.id}`}
+        url={typeof window !== 'undefined' ? window.location.href : undefined}
+        style={{ height: 500 }}
+      />
+
+      <StromcomHome style={{ position: 'fixed', bottom: 24, right: 24 }} />
+    </StromcomProvider>
+  );
+}
+```
+
+## Mental model — what runs once vs. many times
+
+This is the most common confusion, so it's worth being explicit.
+
+| Component            | How many times in app                         | Where to put it                                        | Runs                                                      |
+| -------------------- | --------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| `<StromcomProvider>` | **Exactly once**                              | Top of the tree (root layout / `_app.js` / `main.jsx`) | Injects the loader script                                 |
+| `<StromcomConf>`     | **Exactly once**                              | Direct child of provider                               | Sends configuration                                       |
+| `<StromcomUser>`     | **Exactly once** at a time (per current user) | Direct child of provider                               | Identifies the user; re-runs when props change            |
+| `<StromcomThread>`   | **Many times** — one per conversation         | Anywhere inside provider                               | Renders one thread; **cannot** be re-initialized in place |
+| `<StromcomHome>`     | **Once** typically                            | Anywhere inside provider                               | Renders the notification center                           |
+
+Think of it this way: provider, conf, and user are **app-level singletons**. Threads are **per-resource** — one per order, ticket, article, document, room… whatever your unit of conversation is. You can render five threads on a single page and dozens across the app.
+
+### What's app-level, what's per-resource
+
+```
+StromcomProvider           ← once
+ ├─ StromcomConf           ← once (configuration)
+ ├─ StromcomUser           ← once (current user)
+ ├─ StromcomHome           ← once (notification UI)
+ └─ ...routes...
+     ├─ /orders/123  → StromcomThread code={hash('order-123')}
+     ├─ /orders/456  → StromcomThread code={hash('order-456')}
+     └─ /article/x   → StromcomThread code={hash('article-x')}
+                       StromcomThread code={hash('article-x-internal')}
+                       StromcomThread code={hash('article-x-customer')}
+```
+
+### Multi-page apps (React Router, Next.js, Remix)
+
+**The provider stays mounted the whole time** — put it in your root layout. Routes come and go below it. Each route renders its own `<StromcomThread>` for whatever resource it's showing. The widget script loads only once for the whole session.
+
+You do **not** need to re-mount the provider on navigation, and you do **not** need a separate provider per route. See [`examples/03-multi-page-router.jsx`](./examples/03-multi-page-router.jsx).
+
+### Multiple threads on the same page
+
+Just render `<StromcomThread>` multiple times with different `code`s. Each div hosts one independent conversation. Useful for:
+
+- A page with internal-team and customer-facing threads side by side
+- A list view (e.g. comments on each row)
+- A document with section-level discussions
+
+See [`examples/06-multiple-threads-per-page.jsx`](./examples/06-multiple-threads-per-page.jsx).
+
+### Anonymous / public pages
+
+`<StromcomUser>` is optional. Skip it when there's no logged-in user — threads work read/write according to the dashboard's anonymous policy. Re-mount it the moment a visitor logs in. See [`examples/04-anonymous-then-login.jsx`](./examples/04-anonymous-then-login.jsx).
+
+## Hashing user & thread codes — IMPORTANT
+
+`code` values for `StromcomUser` and `StromcomThread` should be **hard to guess**. Hashing must happen **on your backend** (the secret cannot live in the browser).
+
+Use the matching PHP package [`stromcom/php-snippet`](https://github.com/stromcom/php-snippet) (or any HMAC-SHA256 + base-62 implementation) to hash IDs server-side, then pass the hash through your API to React:
+
+```php
+// Backend (PHP)
+$client = SnippetClientFactory::create(
+    clientKey:      'your-client-key',
+    clientSecret:   'your-bearer-token',
+    codeHashSecret: 'your-app-secret',
+);
+
+$hashedUserCode   = $client->hashCode('user-id-42');     // ~43 chars
+$hashedThreadCode = $client->hashCode('order-12345');
+```
+
+```jsx
+// Frontend (React)
+<StromcomUser code={hashedUserCode} name="Jane" />
+<StromcomThread code={hashedThreadCode} />
+```
+
+Never pass raw internal IDs from the client.
+
+## API
+
+### `<StromcomProvider>`
+
+| Prop           | Type                                      | Required | Description                                                                                                          |
+| -------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `clientKey`    | `string`                                  | ✅       | Project client key.                                                                                                  |
+| `clientSecret` | `string`                                  | ✅       | Project bearer token.                                                                                                |
+| `environment`  | `"production"` \| `"staging"` \| `string` |          | Default `"production"`. Pass any custom URL to point at a self-hosted loader.                                        |
+| `dataLayer`    | `string`                                  |          | Default `"stromCom"`. The global JS variable name. Change it if `stromCom` collides with something else on the page. |
+
+### `<StromcomUser>`
+
+Identifies the logged-in user. Re-calls `initUser` whenever any prop changes. Renders nothing.
+
+| Prop           | Type      | Required | Description                                             |
+| -------------- | --------- | -------- | ------------------------------------------------------- |
+| `code`         | `string`  | ✅       | Hashed user identifier. Max 100 chars, `[a-zA-Z0-9-_]`. |
+| `name`         | `string`  |          | Display name.                                           |
+| `emailAddress` | `string`  |          | Used for email notifications.                           |
+| `readOnly`     | `boolean` |          | When `true`, user can read but not send messages.       |
+| `avatarURL`    | `string`  |          | Full avatar URL.                                        |
+
+### `<StromcomThread>`
+
+Renders a `<div>` and embeds a thread into it. Initialized once on mount; threads cannot be re-initialized in place. To switch the thread shown by the same DOM node, change React's `key` so a fresh div is mounted.
+
+Accepts `className`, `style`, and any `data-*` attributes.
+
+| Prop       | Type      | Required | Description                                               |
+| ---------- | --------- | -------- | --------------------------------------------------------- |
+| `code`     | `string`  | ✅       | Hashed thread identifier. Max 100 chars, `[a-zA-Z0-9-_]`. |
+| `name`     | `string`  |          | Display name shown in the thread header.                  |
+| `url`      | `string`  |          | Canonical URL — appears as a link in the header.          |
+| `userHint` | `boolean` |          | Enable @mention suggestions. Default `true`.              |
+
+### `<StromcomHome>`
+
+Renders a `<div>` and embeds the notification center into it.
+
+| Prop        | Type     | Description                      |
+| ----------- | -------- | -------------------------------- |
+| `className` | `string` | CSS class for the container.     |
+| `style`     | `object` | Inline styles for the container. |
+
+### `<StromcomConf>`
+
+Sends SDK configuration. Place once inside the provider, before threads.
+
+Notable options:
+
+| Prop                          | Type                                      | Description                                   |
+| ----------------------------- | ----------------------------------------- | --------------------------------------------- |
+| `notificationRenderer`        | `Function`                                | Custom notification rendering function.       |
+| `onNotification`              | `Function`                                | Called when unread count changes.             |
+| `pageCSSPath`                 | `string`                                  | CSS file URL injected into the widget iframe. |
+| `notificationElementPosition` | `1\|2\|3\|4`                              | Icon position: 1=TL, 2=TR, 3=BR, 4=BL.        |
+| `theme`                       | `"stromcom-light"\|"stromcom-dark"\|null` | Theme. `null` follows browser preference.     |
+
+See [`src/StromcomConf.jsx`](./src/StromcomConf.jsx) for the full list.
+
+### `useStromcom()` — escape hatch
+
+Returns the global `stromCom` object directly. Use when you need to call something the components don't expose (e.g. switching the active user from a button click).
+
+```jsx
+import { useStromcom } from '@stromcom/react-snippet';
+
+function SwitchUserButton() {
+  const sc = useStromcom();
+  return <button onClick={() => sc?.initUser({ code: 'newHashedCode' })}>Switch user</button>;
+}
+```
+
+## Examples
+
+The [`examples/`](./examples) folder has focused, copy-pasteable snippets for the common patterns:
+
+| File                                                                              | Scenario                                           |
+| --------------------------------------------------------------------------------- | -------------------------------------------------- |
+| [`01-basic-app.jsx`](./examples/01-basic-app.jsx)                                 | Minimal setup — provider + user + one thread       |
+| [`02-nextjs-app-router/`](./examples/02-nextjs-app-router)                        | Next.js 13+ App Router with server-side hashing    |
+| [`03-multi-page-router.jsx`](./examples/03-multi-page-router.jsx)                 | React Router — provider in root, thread per route  |
+| [`04-anonymous-then-login.jsx`](./examples/04-anonymous-then-login.jsx)           | Public site, user mounts only after login          |
+| [`05-conditional-thread.jsx`](./examples/05-conditional-thread.jsx)               | Thread inside a modal / opens on demand            |
+| [`06-multiple-threads-per-page.jsx`](./examples/06-multiple-threads-per-page.jsx) | Several threads on one page (per-row, per-section) |
+| [`07-imperative-api.jsx`](./examples/07-imperative-api.jsx)                       | `useStromcom()` for switch-user / logout flows     |
+| [`08-theme-switcher.jsx`](./examples/08-theme-switcher.jsx)                       | Toggling between light/dark theme at runtime       |
+| [`09-staging-environment.jsx`](./examples/09-staging-environment.jsx)             | Pointing at staging or a custom loader URL         |
+| [`10-php-backend-integration.md`](./examples/10-php-backend-integration.md)       | End-to-end with PHP backend providing hashes       |
+
+## SSR / Next.js
+
+The provider is SSR-safe — it only touches `window` inside `useEffect`. The loader script is appended on the client. No special wrapping needed in Next.js, Remix, etc.
+
+For the App Router, mount `<StromcomProvider>` in a Client Component placed inside your root layout. Server Components above it stay server-rendered. See [`examples/02-nextjs-app-router/`](./examples/02-nextjs-app-router).
+
+## Troubleshooting
+
+**The loader script never appears.** Check that `clientKey` and `clientSecret` are non-empty. The provider does nothing on the server.
+
+**Thread is empty / blank div.** Verify the `code` prop. Make sure it's the hashed value coming from your backend, not the raw internal ID.
+
+**Thread doesn't update when I change props.** By design — threads can't be re-initialized in place. Pass a different React `key` to force a remount.
+
+**Two providers warn / double script.** Don't mount the provider twice. The provider deduplicates the `<script>` tag, but mounting two providers with different `clientKey`s is unsupported.
+
+**Notification count never fires.** Make sure `<StromcomConf onNotification={...}>` is mounted as a child of the provider, and that `<StromcomUser>` runs (notifications are user-scoped).
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,222 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  StromcomConf: () => StromcomConf,
+  StromcomHome: () => StromcomHome,
+  StromcomProvider: () => StromcomProvider,
+  StromcomThread: () => StromcomThread,
+  StromcomUser: () => StromcomUser,
+  useStromcom: () => useStromcom
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/StromcomProvider.jsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var StromcomContext = (0, import_react.createContext)(null);
+var LOADER_URLS = {
+  production: "https://cdn.stromcom.cz/loader.js",
+  staging: "https://cdn.staging.stromcom.cz/loader.js"
+};
+function setupLayer(dataLayer) {
+  var _a;
+  if (typeof window === "undefined") {
+    return null;
+  }
+  if ((_a = window[dataLayer]) == null ? void 0 : _a.__sc_ready) {
+    return window[dataLayer];
+  }
+  const dl = dataLayer + "DL";
+  window[dl] = window[dl] || {};
+  window[dataLayer] = window[dataLayer] || {};
+  const layer = window[dataLayer];
+  const stub = (method, dlKey, isArray) => {
+    dlKey = dlKey || method;
+    if (isArray) {
+      window[dl][dlKey] = window[dl][dlKey] || [];
+    }
+    layer[method] = (...args) => {
+      if (isArray) {
+        window[dl][dlKey].push(args);
+      } else {
+        window[dl][dlKey] = args;
+      }
+    };
+  };
+  stub("initUser", "user");
+  stub("thread", "threads", true);
+  stub("conf");
+  stub("home", "home", true);
+  layer.__sc_ready = true;
+  return layer;
+}
+function StromcomProvider({
+  clientKey,
+  clientSecret,
+  dataLayer = "stromCom",
+  environment = "production",
+  children
+}) {
+  const layer = setupLayer(dataLayer);
+  (0, import_react.useEffect)(() => {
+    var _a;
+    if (typeof window === "undefined") return;
+    if (document.querySelector(`script[data-ck="${clientKey}"][data-type="stromcom"]`)) return;
+    const base = (_a = LOADER_URLS[environment]) != null ? _a : environment;
+    const dl = dataLayer + "DL";
+    const script = document.createElement("script");
+    script.async = true;
+    script.dataset.type = "stromcom";
+    script.dataset.l = dataLayer;
+    script.dataset.dl = dl;
+    script.dataset.ck = clientKey;
+    script.dataset.cs = clientSecret;
+    script.src = `${base}?${clientKey}`;
+    document.head.appendChild(script);
+    return () => script.remove();
+  }, [clientKey, clientSecret, dataLayer, environment]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(StromcomContext.Provider, { value: layer, children });
+}
+function useStromcom() {
+  return (0, import_react.useContext)(StromcomContext);
+}
+
+// src/StromcomUser.jsx
+var import_react2 = require("react");
+function StromcomUser({ code, name, emailAddress, readOnly, avatarURL }) {
+  const sc = useStromcom();
+  (0, import_react2.useEffect)(() => {
+    if (!sc) return;
+    const opts = { code };
+    if (name !== void 0) opts.name = name;
+    if (emailAddress !== void 0) opts.emailAddress = emailAddress;
+    if (readOnly !== void 0) opts.readOnly = readOnly;
+    if (avatarURL !== void 0) opts.avatarURL = avatarURL;
+    sc.initUser(opts);
+  }, [sc, code, name, emailAddress, readOnly, avatarURL]);
+  return null;
+}
+
+// src/StromcomConf.jsx
+var import_react3 = require("react");
+function StromcomConf({
+  notificationRenderer,
+  onNotification,
+  pageCSSPath,
+  notificationElementTargetElement,
+  notificationElementShowAlways,
+  notificationElementPosition,
+  notificationElementStyles,
+  notificationElementCSSPath,
+  notificationElementNoShadowRoot,
+  homeBeforeRender,
+  notificationElementBeforeRender,
+  notificationElementAfterRender,
+  theme
+}) {
+  const sc = useStromcom();
+  (0, import_react3.useEffect)(() => {
+    if (!sc) return;
+    const opts = {};
+    if (notificationRenderer !== void 0) opts.notificationRenderer = notificationRenderer;
+    if (onNotification !== void 0) opts.onNotification = onNotification;
+    if (pageCSSPath !== void 0) opts.pageCSSPath = pageCSSPath;
+    if (notificationElementTargetElement !== void 0)
+      opts.notificationElementTargetElement = notificationElementTargetElement;
+    if (notificationElementShowAlways !== void 0)
+      opts.notificationElementShowAlways = notificationElementShowAlways;
+    if (notificationElementPosition !== void 0)
+      opts.notificationElementPosition = notificationElementPosition;
+    if (notificationElementStyles !== void 0)
+      opts.notificationElementStyles = notificationElementStyles;
+    if (notificationElementCSSPath !== void 0)
+      opts.notificationElementCSSPath = notificationElementCSSPath;
+    if (notificationElementNoShadowRoot !== void 0)
+      opts.notificationElementNoShadowRoot = notificationElementNoShadowRoot;
+    if (homeBeforeRender !== void 0) opts.homeBeforeRender = homeBeforeRender;
+    if (notificationElementBeforeRender !== void 0)
+      opts.notificationElementBeforeRender = notificationElementBeforeRender;
+    if (notificationElementAfterRender !== void 0)
+      opts.notificationElementAfterRender = notificationElementAfterRender;
+    if (theme !== void 0) opts.theme = theme;
+    sc.conf(opts);
+  }, [
+    sc,
+    notificationRenderer,
+    onNotification,
+    pageCSSPath,
+    notificationElementTargetElement,
+    notificationElementShowAlways,
+    notificationElementPosition,
+    notificationElementStyles,
+    notificationElementCSSPath,
+    notificationElementNoShadowRoot,
+    homeBeforeRender,
+    notificationElementBeforeRender,
+    notificationElementAfterRender,
+    theme
+  ]);
+  return null;
+}
+
+// src/StromcomThread.jsx
+var import_react4 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+function StromcomThread({ code, name, url, userHint, className, style, ...rest }) {
+  const sc = useStromcom();
+  const containerRef = (0, import_react4.useRef)(null);
+  const initializedRef = (0, import_react4.useRef)(false);
+  (0, import_react4.useEffect)(() => {
+    if (!sc || !containerRef.current || initializedRef.current) return;
+    const opts = { code };
+    if (name !== void 0) opts.name = name;
+    if (url !== void 0) opts.url = url;
+    if (userHint !== void 0) opts.userHint = userHint;
+    sc.thread(containerRef.current, opts);
+    initializedRef.current = true;
+  }, [sc]);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { ref: containerRef, className, style, ...rest });
+}
+
+// src/StromcomHome.jsx
+var import_react5 = require("react");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+function StromcomHome({ className, style, ...rest }) {
+  const sc = useStromcom();
+  const containerRef = (0, import_react5.useRef)(null);
+  const initializedRef = (0, import_react5.useRef)(false);
+  (0, import_react5.useEffect)(() => {
+    if (!sc || !containerRef.current || initializedRef.current) return;
+    sc.home(containerRef.current);
+    initializedRef.current = true;
+  }, [sc]);
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { ref: containerRef, className, style, ...rest });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StromcomConf,
+  StromcomHome,
+  StromcomProvider,
+  StromcomThread,
+  StromcomUser,
+  useStromcom
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.js","../src/StromcomProvider.jsx","../src/StromcomUser.jsx","../src/StromcomConf.jsx","../src/StromcomThread.jsx","../src/StromcomHome.jsx"],"sourcesContent":["export { StromcomProvider, useStromcom } from './StromcomProvider.jsx';\nexport { StromcomUser } from './StromcomUser.jsx';\nexport { StromcomConf } from './StromcomConf.jsx';\nexport { StromcomThread } from './StromcomThread.jsx';\nexport { StromcomHome } from './StromcomHome.jsx';\n","import { createContext, useContext, useEffect } from 'react';\n\nexport const StromcomContext = createContext(null);\n\nconst LOADER_URLS = {\n  production: 'https://cdn.stromcom.cz/loader.js',\n  staging: 'https://cdn.staging.stromcom.cz/loader.js',\n};\n\n/**\n * Sets up the stromCom stub layer synchronously so that child components can\n * queue calls (initUser, thread, conf, home) before the async loader.js arrives.\n * Mirrors what the PHP snippet() method generates.\n */\nfunction setupLayer(dataLayer) {\n  if (typeof window === 'undefined') {\n    return null;\n  }\n\n  if (window[dataLayer]?.__sc_ready) {\n    return window[dataLayer];\n  }\n\n  const dl = dataLayer + 'DL';\n  window[dl] = window[dl] || {};\n  window[dataLayer] = window[dataLayer] || {};\n  const layer = window[dataLayer];\n\n  const stub = (method, dlKey, isArray) => {\n    dlKey = dlKey || method;\n    if (isArray) {\n      window[dl][dlKey] = window[dl][dlKey] || [];\n    }\n\n    layer[method] = (...args) => {\n      if (isArray) {\n        window[dl][dlKey].push(args);\n      } else {\n        window[dl][dlKey] = args;\n      }\n    };\n  };\n\n  stub('initUser', 'user');\n  stub('thread', 'threads', true);\n  stub('conf');\n  stub('home', 'home', true);\n\n  layer.__sc_ready = true;\n  return layer;\n}\n\n/**\n * Wraps the app and loads the Stromcom widget SDK.\n *\n * @param {object}  props\n * @param {string}  props.clientKey     - Client key from the Stromcom dashboard\n * @param {string}  props.clientSecret  - Bearer token from the Stromcom dashboard\n * @param {string}  [props.dataLayer]   - Global JS variable name (default: \"stromCom\")\n * @param {string}  [props.environment] - \"production\" | \"staging\" | full custom loader URL\n * @param {React.ReactNode} props.children\n *\n * @example\n * <StromcomProvider clientKey=\"ck_xxx\" clientSecret=\"cs_xxx\">\n *   <App />\n * </StromcomProvider>\n */\nexport function StromcomProvider({\n  clientKey,\n  clientSecret,\n  dataLayer = 'stromCom',\n  environment = 'production',\n  children,\n}) {\n  // Set up stubs synchronously so children can queue calls immediately on render.\n  const layer = setupLayer(dataLayer);\n\n  useEffect(() => {\n    if (typeof window === 'undefined') return;\n\n    // Avoid injecting the script twice (React StrictMode, HMR, etc.)\n    if (document.querySelector(`script[data-ck=\"${clientKey}\"][data-type=\"stromcom\"]`)) return;\n\n    const base = LOADER_URLS[environment] ?? environment;\n    const dl = dataLayer + 'DL';\n\n    const script = document.createElement('script');\n    script.async = true;\n    script.dataset.type = 'stromcom';\n    script.dataset.l = dataLayer;\n    script.dataset.dl = dl;\n    script.dataset.ck = clientKey;\n    script.dataset.cs = clientSecret;\n    script.src = `${base}?${clientKey}`;\n    document.head.appendChild(script);\n\n    return () => script.remove();\n  }, [clientKey, clientSecret, dataLayer, environment]);\n\n  return <StromcomContext.Provider value={layer}>{children}</StromcomContext.Provider>;\n}\n\nexport function useStromcom() {\n  return useContext(StromcomContext);\n}\n","import { useEffect } from 'react';\nimport { useStromcom } from './StromcomProvider.jsx';\n\n/**\n * Identifies the currently logged-in user.\n * Re-calls initUser whenever any prop changes.\n *\n * IMPORTANT: The `code` should already be hashed server-side (HMAC + base-62).\n * Never pass your raw internal user ID directly from the client.\n *\n * @param {object}  props\n * @param {string}  props.code          - Hashed unique user identifier (max 100 chars, [a-zA-Z0-9-_])\n * @param {string}  [props.name]        - Display name\n * @param {string}  [props.emailAddress]- Used for email notifications\n * @param {boolean} [props.readOnly]    - When true, user can read but not send messages\n * @param {string}  [props.avatarURL]   - Full URL to avatar image\n *\n * @example\n * <StromcomUser\n *   code={user.stromcomHash}\n *   name={user.name}\n *   emailAddress={user.email}\n * />\n */\nexport function StromcomUser({ code, name, emailAddress, readOnly, avatarURL }) {\n  const sc = useStromcom();\n\n  useEffect(() => {\n    if (!sc) return;\n\n    const opts = { code };\n    if (name !== undefined) opts.name = name;\n    if (emailAddress !== undefined) opts.emailAddress = emailAddress;\n    if (readOnly !== undefined) opts.readOnly = readOnly;\n    if (avatarURL !== undefined) opts.avatarURL = avatarURL;\n\n    sc.initUser(opts);\n  }, [sc, code, name, emailAddress, readOnly, avatarURL]);\n\n  return null;\n}\n","import { useEffect } from 'react';\nimport { useStromcom } from './StromcomProvider.jsx';\n\n/**\n * Sends SDK configuration to the Stromcom widget.\n * Should be placed once inside <StromcomProvider>, before threads or the home component.\n * Re-sends conf whenever any option prop changes.\n *\n * Options that accept functions (notificationRenderer, onNotification, etc.) take\n * actual JS functions here — no need for the string-wrapping used in the PHP library.\n *\n * @param {object}   [props.notificationRenderer]           - Function(notification) for custom notification rendering\n * @param {object}   [props.onNotification]                 - Function(count) called when unread count changes\n * @param {string}   [props.pageCSSPath]                    - URL of CSS file injected into the widget iframe\n * @param {Function} [props.notificationElementTargetElement] - Function/Promise/Element returning the icon mount target\n * @param {boolean}  [props.notificationElementShowAlways]  - Show icon even with zero notifications\n * @param {number}   [props.notificationElementPosition]    - Icon position: 1=top-left 2=top-right 3=bottom-right 4=bottom-left\n * @param {object}   [props.notificationElementStyles]      - Inline styles object for the default notification button\n * @param {string}   [props.notificationElementCSSPath]     - CSS URL for the default notification renderer\n * @param {boolean}  [props.notificationElementNoShadowRoot]- Disable shadow-root for notifications\n * @param {Function} [props.homeBeforeRender]               - Callback before notification center opens\n * @param {Function} [props.notificationElementBeforeRender]- Callback before notification icon renders\n * @param {Function} [props.notificationElementAfterRender] - Callback after notification icon renders\n * @param {('stromcom-light'|'stromcom-dark'|null)} [props.theme] - Theme. null follows browser preference.\n *\n * @example\n * <StromcomConf\n *   notificationElementPosition={4}\n *   onNotification={(count) => setBadge(count)}\n * />\n */\nexport function StromcomConf({\n  notificationRenderer,\n  onNotification,\n  pageCSSPath,\n  notificationElementTargetElement,\n  notificationElementShowAlways,\n  notificationElementPosition,\n  notificationElementStyles,\n  notificationElementCSSPath,\n  notificationElementNoShadowRoot,\n  homeBeforeRender,\n  notificationElementBeforeRender,\n  notificationElementAfterRender,\n  theme,\n}) {\n  const sc = useStromcom();\n\n  useEffect(() => {\n    if (!sc) return;\n\n    const opts = {};\n\n    if (notificationRenderer !== undefined) opts.notificationRenderer = notificationRenderer;\n    if (onNotification !== undefined) opts.onNotification = onNotification;\n    if (pageCSSPath !== undefined) opts.pageCSSPath = pageCSSPath;\n    if (notificationElementTargetElement !== undefined)\n      opts.notificationElementTargetElement = notificationElementTargetElement;\n    if (notificationElementShowAlways !== undefined)\n      opts.notificationElementShowAlways = notificationElementShowAlways;\n    if (notificationElementPosition !== undefined)\n      opts.notificationElementPosition = notificationElementPosition;\n    if (notificationElementStyles !== undefined)\n      opts.notificationElementStyles = notificationElementStyles;\n    if (notificationElementCSSPath !== undefined)\n      opts.notificationElementCSSPath = notificationElementCSSPath;\n    if (notificationElementNoShadowRoot !== undefined)\n      opts.notificationElementNoShadowRoot = notificationElementNoShadowRoot;\n    if (homeBeforeRender !== undefined) opts.homeBeforeRender = homeBeforeRender;\n    if (notificationElementBeforeRender !== undefined)\n      opts.notificationElementBeforeRender = notificationElementBeforeRender;\n    if (notificationElementAfterRender !== undefined)\n      opts.notificationElementAfterRender = notificationElementAfterRender;\n    if (theme !== undefined) opts.theme = theme;\n\n    sc.conf(opts);\n  }, [\n    sc,\n    notificationRenderer,\n    onNotification,\n    pageCSSPath,\n    notificationElementTargetElement,\n    notificationElementShowAlways,\n    notificationElementPosition,\n    notificationElementStyles,\n    notificationElementCSSPath,\n    notificationElementNoShadowRoot,\n    homeBeforeRender,\n    notificationElementBeforeRender,\n    notificationElementAfterRender,\n    theme,\n  ]);\n\n  return null;\n}\n","import { useEffect, useRef } from 'react';\nimport { useStromcom } from './StromcomProvider.jsx';\n\n/**\n * Embeds a Stromcom conversation thread into the rendered div.\n * The thread is initialized once on mount.\n *\n * IMPORTANT: The `code` should already be hashed server-side (HMAC + base-62).\n *\n * @param {object}  props\n * @param {string}  props.code        - Hashed unique thread identifier (max 100 chars, [a-zA-Z0-9-_])\n * @param {string}  [props.name]      - Display name shown in the thread header\n * @param {string}  [props.url]       - Canonical URL of the page (shown as link in header)\n * @param {boolean} [props.userHint]  - Enable @mention suggestions (default: true)\n * @param {string}  [props.className] - CSS class for the container div\n * @param {object}  [props.style]     - Inline styles for the container div\n *\n * @example\n * <StromcomThread\n *   code={order.stromcomHash}\n *   name={`Order #${order.id}`}\n *   url={window.location.href}\n *   style={{ height: '400px' }}\n * />\n */\nexport function StromcomThread({ code, name, url, userHint, className, style, ...rest }) {\n  const sc = useStromcom();\n  const containerRef = useRef(null);\n  const initializedRef = useRef(false);\n\n  useEffect(() => {\n    if (!sc || !containerRef.current || initializedRef.current) return;\n\n    const opts = { code };\n    if (name !== undefined) opts.name = name;\n    if (url !== undefined) opts.url = url;\n    if (userHint !== undefined) opts.userHint = userHint;\n\n    sc.thread(containerRef.current, opts);\n    initializedRef.current = true;\n    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentionally omit option deps, thread cannot be re-initialized\n  }, [sc]);\n\n  return <div ref={containerRef} className={className} style={style} {...rest} />;\n}\n","import { useEffect, useRef } from 'react';\nimport { useStromcom } from './StromcomProvider.jsx';\n\n/**\n * Embeds the Stromcom notification center into the rendered div.\n * Initialized once on mount.\n *\n * @param {object} [props.className] - CSS class for the container div\n * @param {object} [props.style]     - Inline styles for the container div\n *\n * @example\n * <StromcomHome style={{ position: 'fixed', bottom: 24, right: 24 }} />\n */\nexport function StromcomHome({ className, style, ...rest }) {\n  const sc = useStromcom();\n  const containerRef = useRef(null);\n  const initializedRef = useRef(false);\n\n  useEffect(() => {\n    if (!sc || !containerRef.current || initializedRef.current) return;\n    sc.home(containerRef.current);\n    initializedRef.current = true;\n  }, [sc]);\n\n  return <div ref={containerRef} className={className} style={style} {...rest} />;\n}\n"],"mappings":"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","names":["import_react","import_react","import_react","import_jsx_runtime","import_react","import_jsx_runtime"]}

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+export type StromcomEnvironment = 'production' | 'staging' | (string & {});
+
+export interface StromcomLayer {
+  initUser: (options: StromcomUserOptions) => void;
+  thread: (target: HTMLElement, options: StromcomThreadOptions) => void;
+  conf: (options: StromcomConfOptions) => void;
+  home: (target: HTMLElement) => void;
+  [key: string]: any;
+}
+
+export interface StromcomProviderProps {
+  /** Project client key from the Stromcom dashboard. */
+  clientKey: string;
+  /** Bearer token / client secret from the Stromcom dashboard. */
+  clientSecret: string;
+  /** Global JS variable name. Default `"stromCom"`. */
+  dataLayer?: string;
+  /** `"production"`, `"staging"`, or a full custom loader URL. Default `"production"`. */
+  environment?: StromcomEnvironment;
+  children?: ReactNode;
+}
+
+export function StromcomProvider(props: StromcomProviderProps): JSX.Element;
+
+/** Returns the global stromCom object once the loader is set up (or `null` server-side). */
+export function useStromcom(): StromcomLayer | null;
+
+export interface StromcomUserOptions {
+  /** Hashed unique user identifier (max 100 chars, [a-zA-Z0-9-_]). Hash server-side. */
+  code: string;
+  name?: string;
+  emailAddress?: string;
+  readOnly?: boolean;
+  avatarURL?: string;
+}
+
+export function StromcomUser(props: StromcomUserOptions): null;
+
+export interface StromcomThreadOptions {
+  /** Hashed unique thread identifier (max 100 chars, [a-zA-Z0-9-_]). Hash server-side. */
+  code: string;
+  name?: string;
+  url?: string;
+  /** Enable @mention suggestions. Default `true`. */
+  userHint?: boolean;
+}
+
+export interface StromcomThreadProps extends StromcomThreadOptions {
+  className?: string;
+  style?: CSSProperties;
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+export function StromcomThread(props: StromcomThreadProps): JSX.Element;
+
+export interface StromcomHomeProps {
+  className?: string;
+  style?: CSSProperties;
+  [key: `data-${string}`]: string | number | boolean | undefined;
+}
+
+export function StromcomHome(props: StromcomHomeProps): JSX.Element;
+
+export interface StromcomConfOptions {
+  notificationRenderer?: (notification: unknown) => unknown;
+  onNotification?: (count: number) => void;
+  pageCSSPath?: string;
+  notificationElementTargetElement?:
+    (() => HTMLElement | Promise<HTMLElement>) | HTMLElement | Promise<HTMLElement>;
+  notificationElementShowAlways?: boolean;
+  /** Icon position: 1=top-left, 2=top-right, 3=bottom-right, 4=bottom-left. */
+  notificationElementPosition?: 1 | 2 | 3 | 4;
+  notificationElementStyles?: Record<string, string | number | null>;
+  notificationElementCSSPath?: string;
+  notificationElementNoShadowRoot?: boolean;
+  homeBeforeRender?: () => void | Promise<void>;
+  notificationElementBeforeRender?: () => void | Promise<void>;
+  notificationElementAfterRender?: () => void;
+  /** Theme: `"stromcom-light"`, `"stromcom-dark"`, or `null` to follow browser preference. */
+  theme?: 'stromcom-light' | 'stromcom-dark' | null;
+}
+
+export function StromcomConf(props: StromcomConfOptions): null;