npm - @zeyos/client - Versions diffs - 0.1.0 - Mend

@zeyos/client 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (110) hide show

package/CHANGELOG.md +31 -0
package/LICENSE +21 -0
package/README.md +458 -0
package/agents/README.md +66 -0
package/agents/shared/business-app-benchmarks.md +111 -0
package/agents/shared/zeyos-entity-map.md +142 -0
package/agents/shared/zeyos-entity-reference.md +570 -0
package/agents/shared/zeyos-query-patterns.md +89 -0
package/agents/zeyos-account-intelligence/SKILL.md +34 -0
package/agents/zeyos-account-intelligence/agents/openai.yaml +4 -0
package/agents/zeyos-account-intelligence/references/workflows.md +84 -0
package/agents/zeyos-billing-insights/SKILL.md +41 -0
package/agents/zeyos-billing-insights/agents/openai.yaml +4 -0
package/agents/zeyos-billing-insights/references/workflows.md +106 -0
package/agents/zeyos-campaign-and-outreach/SKILL.md +44 -0
package/agents/zeyos-campaign-and-outreach/agents/openai.yaml +4 -0
package/agents/zeyos-campaign-and-outreach/references/workflows.md +100 -0
package/agents/zeyos-collaboration-and-activity/SKILL.md +37 -0
package/agents/zeyos-collaboration-and-activity/agents/openai.yaml +4 -0
package/agents/zeyos-collaboration-and-activity/references/workflows.md +104 -0
package/agents/zeyos-collections-and-dunning/SKILL.md +46 -0
package/agents/zeyos-collections-and-dunning/agents/openai.yaml +4 -0
package/agents/zeyos-collections-and-dunning/references/workflows.md +132 -0
package/agents/zeyos-commerce-and-inventory/SKILL.md +38 -0
package/agents/zeyos-commerce-and-inventory/agents/openai.yaml +4 -0
package/agents/zeyos-commerce-and-inventory/references/workflows.md +101 -0
package/agents/zeyos-mail-operations/SKILL.md +35 -0
package/agents/zeyos-mail-operations/agents/openai.yaml +4 -0
package/agents/zeyos-mail-operations/references/workflows.md +110 -0
package/agents/zeyos-notes-and-sops/SKILL.md +31 -0
package/agents/zeyos-notes-and-sops/agents/openai.yaml +4 -0
package/agents/zeyos-notes-and-sops/references/workflows.md +85 -0
package/agents/zeyos-platform-and-schema/SKILL.md +37 -0
package/agents/zeyos-platform-and-schema/agents/openai.yaml +4 -0
package/agents/zeyos-platform-and-schema/references/workflows.md +97 -0
package/agents/zeyos-work-management/SKILL.md +45 -0
package/agents/zeyos-work-management/agents/openai.yaml +4 -0
package/agents/zeyos-work-management/references/workflows.md +148 -0
package/docs/01-api-reference/01-data-retrieval.md +601 -0
package/docs/01-api-reference/02-authentication.md +288 -0
package/docs/01-api-reference/03-resources.md +270 -0
package/docs/01-api-reference/04-schema.md +539 -0
package/docs/01-api-reference/_category_.json +9 -0
package/docs/02-javascript-client/01-getting-started.md +146 -0
package/docs/02-javascript-client/02-authentication.md +287 -0
package/docs/02-javascript-client/03-making-requests.md +572 -0
package/docs/02-javascript-client/04-practical-guide.md +348 -0
package/docs/02-javascript-client/_category_.json +9 -0
package/docs/03-cli/01-getting-started.md +219 -0
package/docs/03-cli/02-commands.md +407 -0
package/docs/03-cli/03-configuration.md +220 -0
package/docs/03-cli/_category_.json +9 -0
package/docs/04-agent-workflows/00-coding-agents.md +35 -0
package/docs/04-agent-workflows/01-agent-quickstart.md +147 -0
package/docs/04-agent-workflows/02-agent-recipes.md +109 -0
package/docs/04-agent-workflows/03-cli-coverage-and-escalation.md +65 -0
package/docs/04-agent-workflows/_category_.json +9 -0
package/docs/04-sample-apps/01-kanban.md +89 -0
package/docs/04-sample-apps/02-crm.md +81 -0
package/docs/04-sample-apps/03-dashboard.md +80 -0
package/docs/04-sample-apps/_category_.json +9 -0
package/docs/05-tutorials/00-application-developers.md +43 -0
package/docs/05-tutorials/01-integration-architecture.md +60 -0
package/docs/05-tutorials/02-build-your-own-zeyos-frontend.md +517 -0
package/docs/05-tutorials/03-server-side-integrations.md +185 -0
package/docs/05-tutorials/_category_.json +9 -0
package/docs/intro.md +197 -0
package/openapi/api.json +24308 -0
package/openapi/auth.json +415 -0
package/openapi/dbref.json +56223 -0
package/openapi/oauth2.json +781 -0
package/openapi/sdk.json +949 -0
package/openapi/views.txt +642 -0
package/package.json +49 -0
package/samples/crm/README.md +28 -0
package/samples/crm/index.html +327 -0
package/samples/crm/js/api.js +208 -0
package/samples/crm/js/auth.js +61 -0
package/samples/crm/js/main.js +545 -0
package/samples/crm/js/state.js +90 -0
package/samples/crm/js/ui.js +51 -0
package/samples/dashboard/README.md +28 -0
package/samples/dashboard/index.html +280 -0
package/samples/dashboard/js/api.js +197 -0
package/samples/dashboard/js/auth.js +59 -0
package/samples/dashboard/js/main.js +382 -0
package/samples/dashboard/js/state.js +81 -0
package/samples/dashboard/js/ui.js +48 -0
package/samples/kanban/README.md +28 -0
package/samples/kanban/index.html +263 -0
package/samples/kanban/js/api.js +152 -0
package/samples/kanban/js/auth.js +59 -0
package/samples/kanban/js/constants.js +40 -0
package/samples/kanban/js/kanban.js +246 -0
package/samples/kanban/js/main.js +362 -0
package/samples/kanban/js/modals.js +474 -0
package/samples/kanban/js/settings.js +82 -0
package/samples/kanban/js/state.js +118 -0
package/samples/kanban/js/ui.js +49 -0
package/scripts/generate-client.mjs +344 -0
package/src/generated/operations.js +9772 -0
package/src/generated/schema.js +8982 -0
package/src/index.js +85 -0
package/src/runtime/client.js +1208 -0
package/src/runtime/error.js +29 -0
package/src/runtime/http.js +174 -0
package/src/runtime/request-shape.js +35 -0
package/src/runtime/schema.js +206 -0
package/src/runtime/suggest.js +74 -0
package/src/runtime/token-store.js +105 -0

package/samples/dashboard/js/main.js ADDED Viewed

@@ -0,0 +1,382 @@
+/**
+ * Dashboard application entry point.
+ * Bootstraps the client, handles auth, wires up all UI events,
+ * and orchestrates data loading + rendering.
+ *
+ * Authentication: reads config from <body> data attributes + localStorage.
+ *  1. If tokens are available -> token mode
+ *  2. If URL only -> try session detection via /oauth2/v1/userinfo
+ *  3. Otherwise -> connection screen with troubleshooting
+ *
+ * Exposes a global ZeyOS console API for debugging / configuration.
+ */
+import {
+  initTokenClient, initSessionClient,
+  countTickets, fetchRecentTickets, fetchTicketsByStatus,
+  countAccounts, fetchRecentAccounts,
+  STATUS_LABELS, STATUS_COLORS,
+} from './api.js';
+import { trySessionAuth, logout }                                from './auth.js';
+import { runtime, resolveConfig, saveUrl, saveTokens, clearTokens, clearUrl } from './state.js';
+import { showToast, showLoading, hideLoading }                   from './ui.js';
+// -- Priority labels ----------------------------------------------------------
+const PRIORITY_LABELS = {
+  0: 'Lowest',
+  1: 'Low',
+  2: 'Medium',
+  3: 'High',
+  4: 'Highest',
+};
+const PRIORITY_CLASSES = {
+  0: 'bg-slate-100 text-slate-600',
+  1: 'bg-blue-100 text-blue-700',
+  2: 'bg-amber-100 text-amber-700',
+  3: 'bg-orange-100 text-orange-700',
+  4: 'bg-red-100 text-red-700',
+};
+// -- Boot ---------------------------------------------------------------------
+document.addEventListener('DOMContentLoaded', async () => {
+  const config = resolveConfig();
+  // 1. No URL configured -> show connection screen immediately
+  if (!config.url) {
+    _showConnectionScreen('No ZeyOS URL configured.');
+    return;
+  }
+  runtime.url = config.url;
+  // 2. Tokens available -> initialize in token mode
+  if (config.accessToken) {
+    saveTokens({
+      accessToken:  config.accessToken,
+      refreshToken: config.refreshToken ?? null,
+    });
+    initTokenClient(config.url);
+    runtime.authMode = 'token';
+    await _bootApp();
+    return;
+  }
+  // 3. No tokens -> try session detection
+  showLoading();
+  const userInfo = await trySessionAuth(config.url);
+  hideLoading();
+  if (userInfo) {
+    initSessionClient(config.url);
+    runtime.authMode = 'session';
+    await _bootApp();
+    return;
+  }
+  // 4. Nothing works -> connection screen
+  _showConnectionScreen('Could not connect. Set a token or log into ZeyOS first.');
+});
+// -- Connection Screen --------------------------------------------------------
+function _showConnectionScreen(message) {
+  document.getElementById('connection-screen')?.classList.remove('hidden');
+  document.getElementById('app-shell')?.classList.add('hidden');
+  const msgEl = document.getElementById('connection-message');
+  if (msgEl) msgEl.textContent = message;
+}
+// -- Main App Boot ------------------------------------------------------------
+async function _bootApp() {
+  document.getElementById('connection-screen')?.classList.add('hidden');
+  document.getElementById('app-shell')?.classList.remove('hidden');
+  _wireNavbar();
+  await _loadDashboard();
+}
+// -- Data Loading & Rendering -------------------------------------------------
+async function _loadDashboard() {
+  showLoading();
+  try {
+    // Fire all queries in parallel for speed
+    const [
+      totalTickets,
+      activeTickets,
+      overdueTickets,
+      totalAccounts,
+      statusDistribution,
+      recentTickets,
+      recentAccounts,
+    ] = await Promise.all([
+      countTickets(),
+      countTickets({ status: 4 }),
+      _countOverdueTickets(),
+      countAccounts(),
+      fetchTicketsByStatus(),
+      fetchRecentTickets(10),
+      fetchRecentAccounts(10),
+    ]);
+    _renderKPIs(totalTickets, activeTickets, overdueTickets, totalAccounts);
+    _renderStatusChart(statusDistribution);
+    _renderRecentTickets(recentTickets);
+    _renderRecentAccounts(recentAccounts);
+  } catch (err) {
+    if (err?.status === 401) {
+      showToast('Session expired. Please log in again.', 'error');
+      setTimeout(async () => { await logout(); location.reload(); }, 2000);
+      return;
+    }
+    showToast(`Failed to load data: ${err.message}`, 'error');
+  } finally {
+    hideLoading();
+  }
+}
+/**
+ * Count overdue tickets: duedate < now AND status < 8 (not cancelled/completed/failed/booked).
+ */
+async function _countOverdueTickets() {
+  const now = Math.floor(Date.now() / 1000); // Unix timestamp in seconds
+  const promises = [];
+  for (let status = 0; status < 8; status++) {
+    promises.push(
+      countTickets({ status, duedate: { '<': now } })
+    );
+  }
+  const counts = await Promise.all(promises);
+  return counts.reduce((sum, c) => sum + c, 0);
+}
+// -- KPI Cards ----------------------------------------------------------------
+function _renderKPIs(totalTickets, activeTickets, overdueTickets, totalAccounts) {
+  _setKpi('kpi-total-tickets', totalTickets);
+  _setKpi('kpi-active-tickets', activeTickets);
+  _setKpi('kpi-overdue-tickets', overdueTickets);
+  _setKpi('kpi-total-accounts', totalAccounts);
+}
+function _setKpi(id, value) {
+  const el = document.getElementById(id);
+  if (el) el.textContent = typeof value === 'number' ? value.toLocaleString() : value;
+}
+// -- Status Distribution Chart ------------------------------------------------
+function _renderStatusChart(distribution) {
+  const container = document.getElementById('status-chart');
+  if (!container) return;
+  const withCount = distribution.filter(d => d.count > 0);
+  if (withCount.length === 0) {
+    container.innerHTML = '<p class="text-sm text-slate-400 italic">No ticket data available.</p>';
+    return;
+  }
+  const maxCount = Math.max(...withCount.map(d => d.count));
+  const bars = withCount.map(d => {
+    const pct = maxCount > 0 ? (d.count / maxCount) * 100 : 0;
+    return `
+      <div class="flex items-center gap-3">
+        <span class="text-xs text-slate-600 w-36 text-right truncate flex-shrink-0">${_esc(d.label)}</span>
+        <div class="flex-1 h-7 bg-slate-100 rounded-md overflow-hidden relative">
+          <div class="h-full rounded-md transition-all duration-500"
+               style="width:${pct}%; background:${d.color}; min-width:${d.count > 0 ? '2px' : '0'}"></div>
+        </div>
+        <span class="text-sm font-semibold text-slate-700 w-10 text-right flex-shrink-0">${d.count}</span>
+      </div>
+    `;
+  }).join('');
+  container.innerHTML = bars;
+}
+// -- Recent Tickets Table -----------------------------------------------------
+function _renderRecentTickets(tickets) {
+  const tbody = document.getElementById('recent-tickets-body');
+  if (!tbody) return;
+  if (tickets.length === 0) {
+    tbody.innerHTML = '<tr><td colspan="6" class="px-4 py-8 text-center text-sm text-slate-400 italic">No tickets found.</td></tr>';
+    return;
+  }
+  tbody.innerHTML = tickets.map(t => {
+    const statusNum = Number(t.status ?? 0);
+    const statusLabel = STATUS_LABELS[statusNum] ?? `Status ${statusNum}`;
+    const statusColor = STATUS_COLORS[statusNum] ?? '#94a3b8';
+    const priorityNum = Number(t.priority ?? 1);
+    const priorityLabel = PRIORITY_LABELS[priorityNum] ?? 'Normal';
+    const priorityClass = PRIORITY_CLASSES[priorityNum] ?? PRIORITY_CLASSES[1];
+    const duedate = t.duedate ? _formatDate(t.duedate) : '--';
+    const isOverdue = t.duedate && t.duedate < Math.floor(Date.now() / 1000) && statusNum < 8;
+    return `
+      <tr class="border-b border-slate-100 hover:bg-slate-50/50 transition-colors">
+        <td class="px-4 py-2.5 text-xs text-slate-400 font-mono">${_esc(t.ticketnum ?? t.ID)}</td>
+        <td class="px-4 py-2.5 text-sm text-slate-800 font-medium max-w-xs truncate">${_esc(t.name ?? '')}</td>
+        <td class="px-4 py-2.5">
+          <span class="inline-flex items-center gap-1.5 text-xs font-medium">
+            <span class="w-2 h-2 rounded-full flex-shrink-0" style="background:${statusColor}"></span>
+            ${_esc(statusLabel)}
+          </span>
+        </td>
+        <td class="px-4 py-2.5">
+          <span class="px-2 py-0.5 rounded-full text-xs font-medium ${priorityClass}">${_esc(priorityLabel)}</span>
+        </td>
+        <td class="px-4 py-2.5 text-xs ${isOverdue ? 'text-red-600 font-semibold' : 'text-slate-500'}">${duedate}</td>
+      </tr>
+    `;
+  }).join('');
+}
+// -- Recent Accounts Table ----------------------------------------------------
+function _renderRecentAccounts(accounts) {
+  const tbody = document.getElementById('recent-accounts-body');
+  if (!tbody) return;
+  if (accounts.length === 0) {
+    tbody.innerHTML = '<tr><td colspan="5" class="px-4 py-8 text-center text-sm text-slate-400 italic">No accounts found.</td></tr>';
+    return;
+  }
+  const typeLabels = {
+    0: 'Prospect',
+    1: 'Customer',
+    2: 'Supplier',
+    3: 'Cust. & Suppl.',
+    4: 'Competitor',
+    5: 'Employee',
+  };
+  tbody.innerHTML = accounts.map(a => {
+    const typeNum = Number(a.type ?? 0);
+    const typeLabel = typeLabels[typeNum] ?? `Type ${typeNum}`;
+    const name = [a.firstname, a.lastname].filter(Boolean).join(' ') || '--';
+    const city = a['contact.city'] ?? '--';
+    const email = a['contact.email'] ?? '--';
+    const assignee = a['assigneduser.name'] ?? '--';
+    return `
+      <tr class="border-b border-slate-100 hover:bg-slate-50/50 transition-colors">
+        <td class="px-4 py-2.5 text-xs text-slate-400 font-mono">${_esc(a.ID)}</td>
+        <td class="px-4 py-2.5 text-sm text-slate-800 font-medium max-w-xs truncate">${_esc(name)}</td>
+        <td class="px-4 py-2.5 text-xs text-slate-600">${_esc(typeLabel)}</td>
+        <td class="px-4 py-2.5 text-xs text-slate-500">${_esc(city)}</td>
+        <td class="px-4 py-2.5 text-xs text-slate-500 truncate max-w-[180px]">${_esc(assignee)}</td>
+      </tr>
+    `;
+  }).join('');
+}
+// -- Navbar Wiring ------------------------------------------------------------
+function _wireNavbar() {
+  document.getElementById('btn-reload')?.addEventListener('click', () => _loadDashboard());
+  document.getElementById('btn-logout')?.addEventListener('click', async () => {
+    if (!confirm('Log out of ZeyOS Dashboard?')) return;
+    await logout();
+    clearUrl();
+    location.reload();
+  });
+}
+// -- Helpers ------------------------------------------------------------------
+function _formatDate(unixSeconds) {
+  if (!unixSeconds) return '--';
+  const d = new Date(Number(unixSeconds) * 1000);
+  return d.toLocaleDateString(undefined, { year: 'numeric', month: 'short', day: 'numeric' });
+}
+function _esc(str) {
+  return String(str)
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+// -- Console API --------------------------------------------------------------
+globalThis.ZeyOS = {
+  /**
+   * Set the ZeyOS instance URL.
+   * @param {string} url
+   */
+  setUrl(url) {
+    if (!url || typeof url !== 'string') {
+      console.error('[ZeyOS] Usage: ZeyOS.setUrl("https://cloud.zeyos.com/demo/")');
+      return;
+    }
+    saveUrl(url.trim());
+    console.log(`%c[ZeyOS]%c URL set to: ${url}`, 'color:#2563eb;font-weight:bold', '');
+    console.log('%c[ZeyOS]%c Call ZeyOS.reconnect() to apply.', 'color:#2563eb;font-weight:bold', '');
+  },
+  /**
+   * Set access (and optionally refresh) token.
+   * @param {string} accessToken
+   * @param {string} [refreshToken]
+   */
+  setToken(accessToken, refreshToken) {
+    if (!accessToken || typeof accessToken !== 'string') {
+      console.error('[ZeyOS] Usage: ZeyOS.setToken("access-token", "optional-refresh-token")');
+      return;
+    }
+    saveTokens({
+      accessToken:  accessToken.trim(),
+      refreshToken: refreshToken?.trim() ?? null,
+    });
+    console.log('%c[ZeyOS]%c Token saved.', 'color:#2563eb;font-weight:bold', '');
+    console.log('%c[ZeyOS]%c Call ZeyOS.reconnect() to apply.', 'color:#2563eb;font-weight:bold', '');
+  },
+  /**
+   * Print the current connection status to the console.
+   */
+  status() {
+    const config = resolveConfig();
+    const lines = [
+      '',
+      `  URL:            ${config.url ?? '(not set)'}`,
+      `  Access Token:   ${config.accessToken ? config.accessToken.slice(0, 16) + '...' : '(not set)'}`,
+      `  Refresh Token:  ${config.refreshToken ? 'yes' : 'no'}`,
+      `  Auth Mode:      ${runtime.authMode ?? '(not connected)'}`,
+      '',
+    ];
+    console.log(`%c[ZeyOS] Status%c\n${lines.join('\n')}`, 'color:#2563eb;font-weight:bold', 'color:inherit');
+  },
+  /**
+   * Clear all stored config (URL + tokens) and reload.
+   */
+  logout() {
+    clearTokens();
+    clearUrl();
+    console.log('%c[ZeyOS]%c Config cleared. Reloading...', 'color:#2563eb;font-weight:bold', '');
+    location.reload();
+  },
+  /**
+   * Reload the page to re-run the boot sequence with current config.
+   */
+  reconnect() {
+    console.log('%c[ZeyOS]%c Reconnecting...', 'color:#2563eb;font-weight:bold', '');
+    location.reload();
+  },
+};

package/samples/dashboard/js/state.js ADDED Viewed

@@ -0,0 +1,81 @@
+/**
+ * Application state -- persistence via localStorage, in-memory for runtime data.
+ * Config resolution merges <body> data attributes with localStorage overrides.
+ */
+const KEYS = {
+  URL:    'zeyos_dashboard_url',
+  TOKENS: 'zeyos_dashboard_tokens',
+};
+// -- helpers ------------------------------------------------------------------
+function readJson(key, fallback) {
+  try {
+    const raw = localStorage.getItem(key);
+    return raw != null ? JSON.parse(raw) : fallback;
+  } catch {
+    return fallback;
+  }
+}
+function writeJson(key, value) {
+  try {
+    localStorage.setItem(key, JSON.stringify(value));
+  } catch {
+    // storage full or unavailable -- silently ignore
+  }
+}
+// -- URL ----------------------------------------------------------------------
+export function loadUrl()    { return localStorage.getItem(KEYS.URL) ?? null; }
+export function saveUrl(url) { localStorage.setItem(KEYS.URL, url); }
+export function clearUrl()   { localStorage.removeItem(KEYS.URL); }
+// -- tokens -------------------------------------------------------------------
+export function loadTokens() {
+  return readJson(KEYS.TOKENS, null);
+}
+export function saveTokens(tokens) {
+  writeJson(KEYS.TOKENS, tokens);
+}
+export function clearTokens() {
+  localStorage.removeItem(KEYS.TOKENS);
+}
+// -- config resolution --------------------------------------------------------
+/**
+ * Resolve effective config by merging <body> data attributes with localStorage.
+ * localStorage values (set via ZeyOS console API) override body attributes.
+ * Returns { url, accessToken, refreshToken }.
+ */
+export function resolveConfig() {
+  const body = document.body;
+  // Body attributes (defaults)
+  const bodyUrl     = body?.dataset.zeyosUrl?.trim()         || null;
+  const bodyAccess  = body?.dataset.zeyosAccesstoken?.trim() || null;
+  const bodyRefresh = body?.dataset.zeyosRefreshtoken?.trim() || null;
+  // localStorage overrides
+  const storedUrl    = loadUrl();
+  const storedTokens = loadTokens();
+  return {
+    url:          storedUrl    || bodyUrl,
+    accessToken:  storedTokens?.accessToken  || bodyAccess,
+    refreshToken: storedTokens?.refreshToken || bodyRefresh,
+  };
+}
+// -- in-memory runtime state (not persisted) ----------------------------------
+export const runtime = {
+  url:      null,      // resolved ZeyOS instance URL
+  authMode: null,      // 'token' | 'session' | null
+};

package/samples/dashboard/js/ui.js ADDED Viewed

@@ -0,0 +1,48 @@
+/**
+ * Shared UI utilities: toast notifications + loading overlay.
+ */
+// -- Toast Notifications ------------------------------------------------------
+/**
+ * @param {string} message
+ * @param {'success'|'error'|'info'} type
+ */
+export function showToast(message, type = 'info') {
+  const container = document.getElementById('toast-container');
+  if (!container) return;
+  const colors = {
+    success: 'bg-emerald-600',
+    error:   'bg-red-600',
+    info:    'bg-slate-700',
+  };
+  const toast = document.createElement('div');
+  toast.className =
+    `pointer-events-auto flex items-center gap-3 px-4 py-3 rounded-xl text-white text-sm shadow-xl ` +
+    `${colors[type] ?? colors.info} translate-y-2 opacity-0 transition-all duration-200`;
+  toast.textContent = message;
+  container.appendChild(toast);
+  // Trigger transition on next frame
+  requestAnimationFrame(() => {
+    requestAnimationFrame(() => toast.classList.remove('translate-y-2', 'opacity-0'));
+  });
+  const duration = type === 'error' ? 5000 : 3000;
+  setTimeout(() => {
+    toast.classList.add('opacity-0', 'translate-y-2');
+    toast.addEventListener('transitionend', () => toast.remove(), { once: true });
+  }, duration);
+}
+// -- Loading Overlay ----------------------------------------------------------
+export function showLoading() {
+  document.getElementById('loading-overlay')?.classList.remove('hidden');
+}
+export function hideLoading() {
+  document.getElementById('loading-overlay')?.classList.add('hidden');
+}

package/samples/kanban/README.md ADDED Viewed

@@ -0,0 +1,28 @@
+# ZeyOS Kanban Sample
+This directory contains the static Kanban sample application.
+The canonical documentation is:
+- [Kanban sample docs](../../docs/04-sample-apps/01-kanban.md)
+## Quick Run
+Serve the repository root with any static file server:
+```bash
+cd /path/to/zeyos/client
+python3 -m http.server 8080
+```
+Then open:
+```text
+http://localhost:8080/samples/kanban/
+```
+Configure the sample via `data-zeyos-*` attributes in [`index.html`](./index.html) or through the `window.ZeyOS` console API described in the docs.
+For localhost, token mode is usually the reliable path. Session mode only works from the same origin or when the ZeyOS instance allows credentialed CORS.
+> **Note:** The sample must be served from the **repository root** (the directory containing `src/`), because the client is imported via `../../../src/index.js`. Copying the `samples/` folder in isolation will break that import. Also, do **not** open `index.html` directly via the `file://` protocol — browsers block ES module relative imports under `file://`. Always use a local static server as shown above.