skyservice-sdk 0.1.0

package/README.md

@@ -0,0 +1,300 @@
+# @skyservice/sdk
+
+SDK для iframe-додатків всередині Skyservice Dashboard. Надає зручний API для комунікації з Dashboard через `postMessage` bridge.
+
+## Встановлення
+
+```bash
+npm install @skyservice/sdk
+```
+
+### CDN (UMD)
+
+```html
+<script src="https://unpkg.com/@skyservice/sdk"></script>
+<script>
+  const { getBack, getUser } = SkyserviceSDK;
+</script>
+```
+
+## Швидкий старт
+
+```ts
+import { getBack, getUser, getToken, notify } from '@skyservice/sdk';
+
+// Отримати поточного юзера
+const user = await getUser();
+console.log(user);
+
+// Отримати токен для API запитів
+const token = await getToken();
+
+// Показати нотифікацію
+notify('Успішно збережено!');
+
+// Повернутись назад в Dashboard
+getBack();
+```
+
+## API
+
+### Навігація
+
+#### `navigate(path: string): void`
+
+Навігація Dashboard на вказаний шлях.
+
+```ts
+import { navigate } from '@skyservice/sdk';
+
+navigate('/settings');
+navigate('/products/123');
+```
+
+#### `exit(): void` / `getBack(): void`
+
+Вихід з iframe-додатку назад в Dashboard. `getBack()` — аліас для `exit()`.
+
+```ts
+import { getBack } from '@skyservice/sdk';
+
+getBack();
+```
+
+---
+
+### Отримання даних
+
+Всі методи отримання даних повертають `Promise` і мають таймаут 5 секунд.
+
+#### `getStoreData<T>(key: string): Promise<T>`
+
+Отримати значення з Vuex store Dashboard за dot-notation ключем.
+
+```ts
+import { getStoreData } from '@skyservice/sdk';
+
+const company = await getStoreData('company');
+const companyName = await getStoreData<string>('company.name');
+```
+
+#### `getLocalStorageData<T>(key: string): Promise<T>`
+
+Отримати значення з localStorage Dashboard.
+
+```ts
+import { getLocalStorageData } from '@skyservice/sdk';
+
+const token = await getLocalStorageData<string>('token');
+```
+
+#### `getWindowData<T>(key: string): Promise<T>`
+
+Отримати значення з `window` об'єкта Dashboard.
+
+```ts
+import { getWindowData } from '@skyservice/sdk';
+
+const origin = await getWindowData<string>('location.origin');
+```
+
+---
+
+### Shortcut-методи
+
+Зручні обгортки для найчастіших запитів.
+
+| Метод | Джерело | Ключ |
+|---|---|---|
+| `getCompany()` | store | `company` |
+| `getUser()` | store | `user` |
+| `getToken()` | localStorage | `token` |
+| `getLang()` | localStorage | `lang` |
+| `getProductCategories()` | store | `productCategories` |
+
+```ts
+import { getCompany, getUser, getToken, getLang, getProductCategories } from '@skyservice/sdk';
+
+const company = await getCompany();
+const user = await getUser();
+const token = await getToken();
+const lang = await getLang();
+const categories = await getProductCategories();
+```
+
+---
+
+### Дії
+
+#### `setLocalStorage(key: string, value: unknown): void`
+
+Записати значення в localStorage Dashboard.
+
+```ts
+import { setLocalStorage } from '@skyservice/sdk';
+
+setLocalStorage('myApp_lastVisit', Date.now());
+```
+
+#### `setRocketMode(value: boolean): void`
+
+Увімкнути або вимкнути rocket mode в Dashboard.
+
+```ts
+import { setRocketMode } from '@skyservice/sdk';
+
+setRocketMode(true);
+```
+
+#### `trackVisit(name: string, path?: string): void`
+
+Трекінг відвідування сторінки для аналітики.
+
+```ts
+import { trackVisit } from '@skyservice/sdk';
+
+trackVisit('my-app', '/my-app/dashboard');
+```
+
+#### `openExternalLink(url: string): void`
+
+Відкрити зовнішнє посилання. Коректно працює в Android/iOS WebView та браузері.
+
+```ts
+import { openExternalLink } from '@skyservice/sdk';
+
+openExternalLink('https://example.com');
+```
+
+#### `openCrispChat(): void`
+
+Відкрити чат підтримки Crisp.
+
+```ts
+import { openCrispChat } from '@skyservice/sdk';
+
+openCrispChat();
+```
+
+---
+
+### Нотифікації
+
+#### `notify(text: string): void`
+
+Показати success-нотифікацію в Dashboard.
+
+```ts
+import { notify } from '@skyservice/sdk';
+
+notify('Збережено!');
+```
+
+#### `notifyError(text: string): void`
+
+Показати error-нотифікацію.
+
+```ts
+import { notifyError } from '@skyservice/sdk';
+
+notifyError('Не вдалось зберегти');
+```
+
+#### `notifyWarn(text: string): void`
+
+Показати warning-нотифікацію.
+
+```ts
+import { notifyWarn } from '@skyservice/sdk';
+
+notifyWarn('Перевірте заповнені поля');
+```
+
+---
+
+### Утиліти
+
+#### `isInsideIframe(): boolean`
+
+Перевірити чи додаток запущений всередині iframe.
+
+```ts
+import { isInsideIframe } from '@skyservice/sdk';
+
+if (isInsideIframe()) {
+  // Ми всередині Dashboard
+} else {
+  // Standalone режим
+}
+```
+
+#### `onMessage(callback: (data: unknown) => void): () => void`
+
+Підписатись на сирі повідомлення від Dashboard. Повертає функцію для відписки.
+
+```ts
+import { onMessage } from '@skyservice/sdk';
+
+const unsubscribe = onMessage((data) => {
+  console.log('Message from Dashboard:', data);
+});
+
+// Пізніше — відписатись
+unsubscribe();
+```
+
+---
+
+## Приклад: iframe mini-app
+
+```ts
+import { getUser, getToken, getLang, getBack, notify, notifyError, trackVisit } from '@skyservice/sdk';
+
+async function init() {
+  const [user, token, lang] = await Promise.all([
+    getUser(),
+    getToken(),
+    getLang(),
+  ]);
+
+  // Використати токен для API
+  const res = await fetch('https://api.skyservice.online/v1/products', {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const products = await res.json();
+
+  // Трекнути візит
+  trackVisit('my-app', '/my-app');
+
+  // Зберегти щось
+  try {
+    await saveData(products);
+    notify('Дані завантажено');
+  } catch {
+    notifyError('Помилка завантаження');
+  }
+}
+
+// Кнопка "Назад"
+document.getElementById('back-btn')?.addEventListener('click', () => {
+  getBack();
+});
+
+init();
+```
+
+## TypeScript
+
+SDK написаний на TypeScript. Типи включені в пакет — додаткових `@types` не потрібно.
+
+Дженерики підтримуються для data-методів:
+
+```ts
+interface Company {
+  id: number;
+  name: string;
+}
+
+const company = await getStoreData<Company>('company');
+// company має тип Company
+```

package/dist/skyservice-sdk.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`DASHBOARD`,t=5e3,n=0;function r(){return`sdk_${Date.now()}_${++n}`}function i(e){window.parent.postMessage(e,`*`)}function a(n,a,o=t){return new Promise((t,s)=>{let c=r(),l=setTimeout(()=>{window.removeEventListener(`message`,u),s(Error(`[skyservice-sdk] Request timed out: ${n}.${a}`))},o);function u(e){let{type:n,requestId:r,data:i}=e.data||{};n!==`DATA_RESPONSE`||r!==c||(clearTimeout(l),window.removeEventListener(`message`,u),t(i))}window.addEventListener(`message`,u),i({type:`DATA_REQUEST`,requestId:c,source:n,key:a,target:e})})}function o(t){i({type:`navigate`,path:t,target:e})}function s(){i({type:`exit`,target:e})}var c=s;function l(e){return a(`store`,e)}function u(e){return a(`localStorage`,e)}function d(e){return a(`window`,e)}function f(){return l(`company`)}function p(){return l(`user`)}function m(){return u(`token`)}function h(){return u(`lang`)}function g(){return l(`productCategories`)}function _(t,n){i({type:`setLocalStorage`,key:t,value:n,target:e})}function v(t){i({type:`setRocketMode`,value:t,target:e})}function y(t,n){i({type:`trackVisit`,name:t,path:n,target:e})}function b(t){i({type:`openExternalLink`,url:t,target:e})}function x(){i({type:`openCrispChat`,target:e})}function S(t){i({type:`notification`,text:t,target:e})}function C(t){i({type:`notification`,text:t,variant:`error`,target:e})}function w(t){i({type:`notification`,text:t,variant:`warn`,target:e})}function T(){return window.self!==window.top}function E(t){function n(n){n.data?.sender===e&&t(n.data)}return window.addEventListener(`message`,n),()=>window.removeEventListener(`message`,n)}exports.exit=s,exports.getBack=c,exports.getCompany=f,exports.getLang=h,exports.getLocalStorageData=u,exports.getProductCategories=g,exports.getStoreData=l,exports.getToken=m,exports.getUser=p,exports.getWindowData=d,exports.isInsideIframe=T,exports.navigate=o,exports.notify=S,exports.notifyError=C,exports.notifyWarn=w,exports.onMessage=E,exports.openCrispChat=x,exports.openExternalLink=b,exports.setLocalStorage=_,exports.setRocketMode=v,exports.trackVisit=y;

package/dist/skyservice-sdk.d.ts

@@ -0,0 +1,59 @@
+/** Exit current iframe app and return to Dashboard home */
+export declare function exit(): void;
+
+/** Alias for exit() */
+export declare const getBack: typeof exit;
+
+export declare function getCompany(): Promise<Record<string, unknown>>;
+
+export declare function getLang(): Promise<string>;
+
+/** Get a value from Dashboard's localStorage */
+export declare function getLocalStorageData<T = unknown>(key: string): Promise<T>;
+
+export declare function getProductCategories(): Promise<unknown[]>;
+
+/** Get a value from Dashboard's Vuex store by dot-notated key */
+export declare function getStoreData<T = unknown>(key: string): Promise<T>;
+
+export declare function getToken(): Promise<string>;
+
+export declare function getUser(): Promise<Record<string, unknown>>;
+
+/** Get a value from Dashboard's window object */
+export declare function getWindowData<T = unknown>(key: string): Promise<T>;
+
+/** Check if running inside an iframe */
+export declare function isInsideIframe(): boolean;
+
+/** Navigate Dashboard to a given path */
+export declare function navigate(path: string): void;
+
+/** Show a success notification in Dashboard */
+export declare function notify(text: string): void;
+
+/** Show an error notification in Dashboard */
+export declare function notifyError(text: string): void;
+
+/** Show a warning notification in Dashboard */
+export declare function notifyWarn(text: string): void;
+
+/** Listen for raw messages from Dashboard */
+export declare function onMessage(callback: (data: unknown) => void): () => void;
+
+/** Open Crisp support chat */
+export declare function openCrispChat(): void;
+
+/** Open an external link (handles webview bridges) */
+export declare function openExternalLink(url: string): void;
+
+/** Set a key in Dashboard's localStorage */
+export declare function setLocalStorage(key: string, value: unknown): void;
+
+/** Toggle rocket mode in Dashboard */
+export declare function setRocketMode(value: boolean): void;
+
+/** Track a page visit for analytics */
+export declare function trackVisit(name: string, path?: string): void;
+
+export { }

package/dist/skyservice-sdk.js

@@ -0,0 +1,134 @@
+//#region src/skyservice-sdk.ts
+var e = "DASHBOARD", t = 5e3, n = 0;
+function r() {
+	return `sdk_${Date.now()}_${++n}`;
+}
+function i(e) {
+	window.parent.postMessage(e, "*");
+}
+function a(n, a, o = t) {
+	return new Promise((t, s) => {
+		let c = r(), l = setTimeout(() => {
+			window.removeEventListener("message", u), s(/* @__PURE__ */ Error(`[skyservice-sdk] Request timed out: ${n}.${a}`));
+		}, o);
+		function u(e) {
+			let { type: n, requestId: r, data: i } = e.data || {};
+			n !== "DATA_RESPONSE" || r !== c || (clearTimeout(l), window.removeEventListener("message", u), t(i));
+		}
+		window.addEventListener("message", u), i({
+			type: "DATA_REQUEST",
+			requestId: c,
+			source: n,
+			key: a,
+			target: e
+		});
+	});
+}
+function o(t) {
+	i({
+		type: "navigate",
+		path: t,
+		target: e
+	});
+}
+function s() {
+	i({
+		type: "exit",
+		target: e
+	});
+}
+var c = s;
+function l(e) {
+	return a("store", e);
+}
+function u(e) {
+	return a("localStorage", e);
+}
+function d(e) {
+	return a("window", e);
+}
+function f() {
+	return l("company");
+}
+function p() {
+	return l("user");
+}
+function m() {
+	return u("token");
+}
+function h() {
+	return u("lang");
+}
+function g() {
+	return l("productCategories");
+}
+function _(t, n) {
+	i({
+		type: "setLocalStorage",
+		key: t,
+		value: n,
+		target: e
+	});
+}
+function v(t) {
+	i({
+		type: "setRocketMode",
+		value: t,
+		target: e
+	});
+}
+function y(t, n) {
+	i({
+		type: "trackVisit",
+		name: t,
+		path: n,
+		target: e
+	});
+}
+function b(t) {
+	i({
+		type: "openExternalLink",
+		url: t,
+		target: e
+	});
+}
+function x() {
+	i({
+		type: "openCrispChat",
+		target: e
+	});
+}
+function S(t) {
+	i({
+		type: "notification",
+		text: t,
+		target: e
+	});
+}
+function C(t) {
+	i({
+		type: "notification",
+		text: t,
+		variant: "error",
+		target: e
+	});
+}
+function w(t) {
+	i({
+		type: "notification",
+		text: t,
+		variant: "warn",
+		target: e
+	});
+}
+function T() {
+	return window.self !== window.top;
+}
+function E(t) {
+	function n(n) {
+		n.data?.sender === e && t(n.data);
+	}
+	return window.addEventListener("message", n), () => window.removeEventListener("message", n);
+}
+//#endregion
+export { s as exit, c as getBack, f as getCompany, h as getLang, u as getLocalStorageData, g as getProductCategories, l as getStoreData, m as getToken, p as getUser, d as getWindowData, T as isInsideIframe, o as navigate, S as notify, C as notifyError, w as notifyWarn, E as onMessage, x as openCrispChat, b as openExternalLink, _ as setLocalStorage, v as setRocketMode, y as trackVisit };

package/dist/skyservice-sdk.umd.cjs

@@ -0,0 +1 @@
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.SkyserviceSDK={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=`DASHBOARD`,n=5e3,r=0;function i(){return`sdk_${Date.now()}_${++r}`}function a(e){window.parent.postMessage(e,`*`)}function o(e,r,o=n){return new Promise((n,s)=>{let c=i(),l=setTimeout(()=>{window.removeEventListener(`message`,u),s(Error(`[skyservice-sdk] Request timed out: ${e}.${r}`))},o);function u(e){let{type:t,requestId:r,data:i}=e.data||{};t!==`DATA_RESPONSE`||r!==c||(clearTimeout(l),window.removeEventListener(`message`,u),n(i))}window.addEventListener(`message`,u),a({type:`DATA_REQUEST`,requestId:c,source:e,key:r,target:t})})}function s(e){a({type:`navigate`,path:e,target:t})}function c(){a({type:`exit`,target:t})}var l=c;function u(e){return o(`store`,e)}function d(e){return o(`localStorage`,e)}function f(e){return o(`window`,e)}function p(){return u(`company`)}function m(){return u(`user`)}function h(){return d(`token`)}function g(){return d(`lang`)}function _(){return u(`productCategories`)}function v(e,n){a({type:`setLocalStorage`,key:e,value:n,target:t})}function y(e){a({type:`setRocketMode`,value:e,target:t})}function b(e,n){a({type:`trackVisit`,name:e,path:n,target:t})}function x(e){a({type:`openExternalLink`,url:e,target:t})}function S(){a({type:`openCrispChat`,target:t})}function C(e){a({type:`notification`,text:e,target:t})}function w(e){a({type:`notification`,text:e,variant:`error`,target:t})}function T(e){a({type:`notification`,text:e,variant:`warn`,target:t})}function E(){return window.self!==window.top}function D(e){function n(n){n.data?.sender===t&&e(n.data)}return window.addEventListener(`message`,n),()=>window.removeEventListener(`message`,n)}e.exit=c,e.getBack=l,e.getCompany=p,e.getLang=g,e.getLocalStorageData=d,e.getProductCategories=_,e.getStoreData=u,e.getToken=h,e.getUser=m,e.getWindowData=f,e.isInsideIframe=E,e.navigate=s,e.notify=C,e.notifyError=w,e.notifyWarn=T,e.onMessage=D,e.openCrispChat=S,e.openExternalLink=x,e.setLocalStorage=v,e.setRocketMode=y,e.trackVisit=b});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "skyservice-sdk",
+  "version": "0.1.0",
+  "description": "SDK for iframe apps inside Skyservice Dashboard",
+  "type": "module",
+  "main": "dist/skyservice-sdk.cjs",
+  "module": "dist/skyservice-sdk.js",
+  "types": "dist/skyservice-sdk.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/skyservice-sdk.js",
+      "require": "./dist/skyservice-sdk.cjs",
+      "types": "./dist/skyservice-sdk.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch"
+  },
+  "keywords": [
+    "skyservice",
+    "iframe",
+    "sdk",
+    "dashboard"
+  ],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vite": "^8.0.8",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}