@netsapiens/horizon-sdk 0.1.0

package/README.md

@@ -0,0 +1,643 @@
+# @netsapiens/horizon-sdk
+
+Build remote applications that load into NetSapiens Horizon at runtime via Module Federation.
+
+This package is for **third-party developers**. It provides:
+
+- A typed `HorizonContext` you receive as props from the host
+- An `RemoteAppSDK` for registering routes, dynamic UI extensions, and table columns
+- React hooks that handle registration cleanup automatically
+- Re-styled MUI components so your app looks like Horizon
+
+> Internal engineering docs (event-bus contracts, module loader, security layers) live in [`src/sdk/README.md`](../src/sdk/README.md).
+
+---
+
+## Install
+
+```bash
+npm install @netsapiens/horizon-sdk
+```
+
+Peer deps: `react ^18 || ^19`, `react-dom ^18 || ^19`, `loglevel ^1.9`.
+
+> Do **not** add `@mui/material`, `@emotion/*`, or `@mui/x-data-grid-pro` to your `package.json` or your webpack `shared` config. The host's federation loader does not expose them as shared modules — declaring them as singletons causes a version-mismatch crash at load time. Use all MUI components via `horizonContext.ui` instead; that is how Aurora theme and dark mode reach your app.
+
+---
+
+## A complete remote app in one file
+
+```tsx
+// src/App.tsx
+import { useEffect } from 'react';
+import { type HorizonContext, useRemoteApp } from '@netsapiens/horizon-sdk';
+import MyButton from './extensions/MyButton';
+
+export default function App(horizonContext: HorizonContext) {
+  const { sdk, user, theme } = useRemoteApp(horizonContext, 'my-app');
+
+  useEffect(() => {
+    sdk.registerDynamicExtension({
+      id: 'my-app.export-button',
+      zone: 'page-header-actions',
+      routes: [{ pattern: '/manage/*/call-logs' }],
+      component: MyButton,
+    });
+  }, [sdk]);
+
+  return null; // Your App component never renders directly — it just registers.
+}
+```
+
+```tsx
+// src/extensions/MyButton.tsx
+import { type ExtensionComponentProps, useTheme } from '@netsapiens/horizon-sdk';
+
+export default function MyButton({ context }: ExtensionComponentProps) {
+  const { theme } = useTheme(context.eventBus); // reactive — no manual event wiring
+  const { Button, Icon } = context.ui ?? {};
+  if (!Button || !Icon) return null;
+  return (
+    <Button startIcon={<Icon icon="mdi:download" />} onClick={() => alert('Exported!')}>
+      Export
+    </Button>
+  );
+}
+```
+
+`useRemoteApp` returns an `sdk` instance that auto-cleans every registration when your app unmounts.
+
+---
+
+## What's in `horizonContext`
+
+| Field            | Notes                                                                         |
+| ---------------- | ----------------------------------------------------------------------------- |
+| `user`           | `displayName`, `domain`, `email?`, plus host-defined extras                   |
+| `auth`           | `isAuthenticated()`                                                           |
+| `api`            | Authenticated NetSapiens v2 client (`get`/`post`/`put`/`delete`/`getBaseUrl`) |
+| `theme`          | `'light'` \| `'dark'`                                                         |
+| `locale`         | e.g. `'en-US'`                                                                |
+| `navigate(path)` | Pushes a route in the host router                                             |
+| `eventBus`       | `emit`/`on`/`off` for cross-app messages                                      |
+| `ui`             | Pre-themed components and templates (see below)                               |
+
+---
+
+## Registration APIs
+
+### Routes — full pages added to Horizon
+
+Register a full page route using the SDK. Wrap your page component in `HorizonContextProvider` so it gets a live, reactive context — including automatic dark mode — without any extra wiring.
+
+```tsx
+import { HorizonContextProvider, useHorizonContext } from '@netsapiens/horizon-sdk';
+import MySettingsPage from './pages/MySettingsPage';
+
+// In your App component:
+const MySettingsRoute = useMemo(
+  () =>
+    function MySettingsRoute() {
+      return (
+        <HorizonContextProvider context={horizonContext}>
+          <MySettingsPage />
+        </HorizonContextProvider>
+      );
+    },
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  [], // stable identity prevents React from unmounting the page on re-renders
+);
+
+sdk.registerRoute({
+  id: 'my-app.settings',
+  parentPath: '/home', // attach under Apps menu
+  path: 'my-settings', // → /home/my-settings
+  label: 'My Settings',
+  icon: 'mdi:cog',
+  placement: { after: 'settings' }, // position after the Settings item
+  component: MySettingsRoute,
+});
+```
+
+#### Menu placement
+
+Use `placement` to control where your route appears in the menu. You can position relative to existing menu items using semantic anchors:
+
+```tsx
+sdk.registerRoute({
+  id: 'my-app.settings',
+  parentPath: '/home',
+  path: 'my-settings',
+  label: 'My Settings',
+  icon: 'mdi:cog',
+  placement: { after: 'settings' }, // After the Settings item
+  component: MySettingsRoute,
+});
+```
+
+**Placement options:**
+
+- `{ after: 'anchor-id' }` — Place immediately after the specified item
+- `{ before: 'anchor-id' }` — Place immediately before the specified item
+- `{ first: true }` — Force to the start of the menu
+- `{ last: true }` — Force to the end of the menu (default if no placement specified)
+
+The system uses fuzzy matching with a 0.8 similarity threshold, so minor typos (e.g., `contats` instead of `contacts`) will still work. If the anchor isn't found, your item is placed at the end of the menu with a console warning.
+
+Inside the page component, read context with `useHorizonContext()` instead of accepting it as props:
+
+```tsx
+// src/pages/MySettingsPage.tsx
+import { useHorizonContext } from '@netsapiens/horizon-sdk';
+
+export default function MySettingsPage() {
+  const { ui, user, navigate, theme } = useHorizonContext();
+  const { PageTemplate } = ui.templates;
+  const { Button, Stack, Typography } = ui;
+
+  return (
+    <PageTemplate title="Settings" breadcrumbs={[{ label: 'Apps', url: '/apps' }]}>
+      <Stack spacing={2}>
+        <Typography variant="body1">Hello, {user.displayName}.</Typography>
+        <Button variant="contained" onClick={() => navigate('/apps')}>
+          Back
+        </Button>
+      </Stack>
+    </PageTemplate>
+  );
+}
+```
+
+The `useRoute` hook handles register + unregister automatically:
+
+```tsx
+useRoute(horizonContext.eventBus, 'my-app', { id: '...', /* ... */, component: MySettingsRoute });
+```
+
+If your route component lives in a separate exposed module, use `useRouteFromModule`:
+
+```tsx
+const { loading, error } = useRouteFromModule(
+  horizonContext.eventBus,
+  'my-app',
+  { id: 'my-app.settings', parentPath: '/home', path: 'my-settings', label: 'My Settings' },
+  { scope: 'myApp', module: './SettingsPage' },
+);
+```
+
+### Dynamic extensions — inject UI into host pages
+
+Extensions render at named **zones** on routes that match a **pattern**. You don't need the host page to opt in.
+
+```tsx
+sdk.registerDynamicExtension({
+  id: 'my-app.row-action',
+  zone: 'table-row-actions',
+  routes: [{ pattern: '/manage/*/call-logs' }],
+  priority: 10, // higher = first 
+  requiredPermissions: ['calls:read'],
+  condition: (ctx) => ctx.user.domain === 'special.com',
+  component: RowAction,
+});
+```
+
+**Available zones:**
+
+| Zone                       | Where it renders                             |
+| -------------------------- | -------------------------------------------- |
+| `page-header-actions`      | Right side of any page header                |
+| `page-header-secondary`    | Subtitle row of page header (badges, status) |
+| `page-content-before`      | Above main page content                      |
+| `page-content-after`       | Below main page content                      |
+| `page-sidebar`             | Page sidebar                                 |
+| `table-toolbar`            | Above any DataGrid                           |
+| `table-row-actions`        | Per-row action column                        |
+| `detail-panel-tabs`        | Detail-panel tab strip                       |
+| `detail-panel-actions`     | Detail-panel action area                     |
+| `topbar-actions`           | Global top app bar (after comms, before utilities) |
+| `inbound-call-content`     | Incoming-call notification body              |
+
+> **Note**: Check Platform → UI SDK Management → SDK Settings for the current list of available zones and their descriptions.
+
+Custom zones (any string) work for pages that explicitly render `<DynamicExtensionRenderer zone="my-zone" />`.
+
+**Route patterns** support `*` (any segment) and `:name` (named param):
+
+```ts
+{ pattern: '/manage/call-logs' }                    // exact-ish
+{ pattern: '/manage/*/call-logs' }                  // any domain
+{ pattern: '/manage/:domain/users', exact: true }   // exact match, params extracted
+{ pattern: '/*' }                                   // every route
+```
+
+Hook form:
+
+```tsx
+useDynamicExtension(horizonContext.eventBus, 'my-app', {
+  id: 'my-app.banner',
+  zone: 'page-content-before',
+  routes: [{ pattern: '/manage/:domain/users' }],
+  component: Banner,
+});
+```
+
+### Dynamic table columns
+
+Add columns to host DataGrids that opt in (zone names like `call-logs-columns`, `users-columns`, etc.):
+
+```tsx
+sdk.registerDynamicColumn({
+  id: 'my-app.priority',
+  zone: 'call-logs-columns',
+  routes: [{ pattern: '/manage/*/call-logs' }],
+  column: {
+    field: 'priority',
+    headerName: 'Priority',
+    width: 120,
+    sortable: true,
+    filterable: true,
+    renderCell: ({ row }) => <PriorityCell row={row} />,
+    valueGetter: (_v, row) => computePriority(row),
+  },
+});
+```
+
+Hook: `useDynamicColumn(eventBus, appId, config)`.
+
+---
+
+## Using `horizonContext.ui`
+
+Don't ship MUI yourself — render Horizon's themed components instead. They inherit the host's Aurora MUI theme, including automatic dark/light mode switching.
+
+The recommended pattern uses `useHorizonContext()` (see Routes above). The old pattern of accepting `horizonContext` as props still works for extension components:
+
+```tsx
+// Recommended — page component using the hook (fully reactive theme)
+import { useHorizonContext } from '@netsapiens/horizon-sdk';
+
+export default function MyPage() {
+  const { ui, user } = useHorizonContext();
+  const { PageTemplate, DatagridTemplate } = ui.templates;
+  const { Button, Stack, Typography } = ui;
+
+  return (
+    <PageTemplate title="My Page" breadcrumbs={[{ label: 'Apps', url: '/apps' }]}>
+      <Stack spacing={2}>
+        <Typography variant="h5">Hello, {user.displayName}</Typography>
+        <Button variant="contained">Action</Button>
+      </Stack>
+    </PageTemplate>
+  );
+}
+```
+
+```tsx
+// Legacy — still works for extension components (not full pages)
+function MyButton({ context }: ExtensionComponentProps) {
+  const { Button } = context.ui ?? {};
+  return <Button variant="contained">Click</Button>;
+}
+```
+
+Available under `horizonContext.ui` (or via `useHorizonContext().ui`):
+
+- `templates`: `PageTemplate`, `PageTemplateWithExtensions`, `FormTemplate`, `SideTrayTemplate`, `DatagridTemplate`
+
+> **`DatagridTemplate` and the MUI X Pro license** — `DatagridTemplate` wraps MUI's `DataGridPro` internally, which is a paid licensed component. The license is held by the Horizon host; **you do not need an MUI X Pro license** and must not import `@mui/x-data-grid-pro` directly in your remote app. Always use `DatagridTemplate` from the SDK.
+
+- Form: `Button`, `IconButton`, `TextField`, `Select`, `Checkbox`, `Radio`, `RadioGroup`, `Switch`, `ToggleButton`, `ToggleButtonGroup`, `FormLabel`
+- Display: `Typography`, `Chip`, `Avatar`, `Divider`, `Tooltip`, `Icon`
+- Layout: `Stack`, `Paper`
+- Feedback: `Alert`
+- `theme` (`'light' | 'dark'`, reactive via `useHorizonContext()`) and `styles` for derived tokens
+
+#### IconButton — shorthand-only API
+
+`IconButton` does **not** accept the standard MUI children pattern. It is a shorthand wrapper that takes the icon name as a string prop:
+
+```tsx
+// ✅ Correct — pass the Iconify name via the `icon` prop
+<IconButton icon="mdi:account" aria-label="Account" />
+<IconButton icon="material-symbols:bolt" iconSize={18} size="small" onClick={handleClick} />
+
+// ❌ Wrong — children are dropped, the button renders empty at 0×0
+<IconButton aria-label="Account">
+  <Icon icon="mdi:account" />
+</IconButton>
+```
+
+The TypeScript types reject the children pattern at compile time. If you ever see a 0×0 button in the DOM, this is the first thing to check.
+
+Other themed components (`Button`, `Stack`, `Paper`, etc.) follow the standard MUI children pattern.
+
+---
+
+## Dark mode
+
+Dark mode is handled automatically — **you write no theme-switching code for MUI components**.
+
+MUI components (`Button`, `Paper`, `Stack`, `DatagridTemplate`, etc.) inherit the host's Aurora ThemeProvider via the shared module singleton and switch the moment the user toggles the theme. For any conditional logic that reads the theme string (custom colors, conditional icons, etc.), use `useTheme()`:
+
+```tsx
+import { useTheme } from '@netsapiens/horizon-sdk';
+```
+
+`useTheme()` is a single hook that works identically in both contexts:
+
+| Where you use it                                                    | How it works                                                            |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **Page component** (inside `HorizonContextProvider`)                | Reads directly from provider React context — zero subscription overhead |
+| **Extension component** (registered via `registerDynamicExtension`) | Pass `context.eventBus`; hook subscribes and unsubscribes automatically |
+
+```tsx
+// Page component
+export default function MyPage() {
+  const { theme } = useTheme(); // no argument needed inside HorizonContextProvider
+  return <div style={{ background: theme === 'dark' ? '#1B2124' : '#fff' }}>...</div>;
+}
+
+// Extension component
+export default function MyButton({ context }: ExtensionComponentProps) {
+  const { theme } = useTheme(context.eventBus); // pass eventBus for extensions
+  const { Button } = context.ui ?? {};
+  return <Button>{theme === 'dark' ? '🌙' : '☀️'} Export</Button>;
+}
+```
+
+> Do not subscribe to `theme:changed` on the event bus manually. `useTheme()` handles the subscription and cleanup internally.
+
+---
+
+## API client
+
+```tsx
+const { api, user } = horizonContext;
+const devices = await api.get(`/domains/${user.domain}/users/${user.displayName}/devices`);
+await api.post(`/domains/${user.domain}/users/${user.displayName}/contacts`, {
+  'name-first-name': 'John',
+});
+```
+
+All calls run through Horizon's audited proxy — credentials never reach the remote app.
+
+---
+
+## Event bus
+
+For cross-app messages and host events:
+
+```tsx
+useEffect(() => {
+  const handler = (data: unknown) => console.log('theme changed', data);
+  horizonContext.eventBus.on('theme:changed', handler);
+  return () => horizonContext.eventBus.off('theme:changed', handler);
+}, []);
+```
+
+Common host-emitted events: `theme:changed`, `call-event`, `routes:updated`. Apps can emit any custom event under their own namespace (`my-app:something`).
+
+> **You do not need to subscribe to `theme:changed` anywhere.** Use `useTheme()` from the SDK — it handles the subscription internally for both page components and extension components. See the Dark mode section.
+
+---
+
+## Hosting requirements
+
+Your app is delivered as a static bundle served over HTTPS. Before you can register it you need a stable, publicly reachable URL for `remoteEntry.js`.
+
+**SSL** — HTTPS is required in production. Browsers block mixed-content requests, so an HTTP-only endpoint will not load inside an HTTPS Horizon instance. Localhost is the only allowed exception during local development.
+
+**CDN / static hosting** — Any CDN or static file host works (AWS S3 + CloudFront, Cloudflare Pages, Azure Blob, your own nginx). The URL must remain stable across deploys; if you use content-hashed filenames for assets, the `remoteEntry.js` itself should stay at a fixed path (e.g. `https://cdn.example.com/my-app/remoteEntry.js`).
+
+**CORS** — The Horizon host makes a cross-origin request to fetch your `remoteEntry.js`. Your server must respond with:
+
+```
+Access-Control-Allow-Origin: https://your-horizon-instance.com
+```
+
+During local development the webpack dev server sets `Access-Control-Allow-Origin: *` (any origin) so you can test against any Horizon instance. Tighten this to the specific Horizon domain before deploying to production — `*` in production means any website could load your bundle.
+
+**Domain whitelist** — In addition to CORS, your CDN domain must be approved by the Horizon administrator. See [Registering with Horizon](#registering-with-horizon) below for how to request approval.
+
+---
+
+## Build configuration
+
+Use webpack Module Federation. Minimal `webpack.config.js`:
+
+```js
+const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');
+
+module.exports = (_env, argv) => ({
+  entry: './src/App.tsx',
+  output: { publicPath: 'auto', filename: 'remoteEntry.js', clean: true },
+  resolve: { extensions: ['.tsx', '.ts', '.js'] },
+  module: {
+    rules: [{ test: /\.(tsx?|jsx?)$/, exclude: /node_modules/, use: 'babel-loader' }],
+  },
+  plugins: [
+    new ModuleFederationPlugin({
+      name: 'myApp', // your Extension App ID — must match exactly what you enter during registration
+      filename: 'remoteEntry.js',
+      exposes: { './App': './src/App' },
+      shared: {
+        react: { singleton: true, requiredVersion: '^19.0.0' },
+        'react-dom': { singleton: true, requiredVersion: '^19.0.0' },
+        loglevel: { singleton: true, requiredVersion: '^1.9.0' },
+        '@netsapiens/horizon-sdk': { singleton: true, requiredVersion: '^1.0.0' },
+
+        // Do NOT add @mui/material, @emotion/*, or @mui/x-data-grid-pro here.
+        // The host's federation loader does not register MUI as a shared module,
+        // so declaring it as a singleton causes an "Unsatisfied version" crash.
+        //
+        // Instead, consume all MUI components via horizonContext.ui — this is
+        // what gives your components the Aurora theme and dark mode automatically.
+      },
+    }),
+  ],
+  devServer: { port: 5005, headers: { 'Access-Control-Allow-Origin': '*' } },
+});
+```
+
+Your app must expose `./App` as the default export accepting `HorizonContext` as props. Page components rendered via registered routes should use `useHorizonContext()` internally — do not thread `horizonContext` as a prop through every component.
+
+---
+
+## Registering with Horizon
+
+Once your `remoteEntry.js` is hosted and reachable, register it through the Horizon admin UI at **Platform → UI SDK Management → Registered Apps → Add App**, or via the API:
+
+```bash
+curl -X POST "https://your-horizon-instance.com/ns-api/v2/ui-extensions" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "My App",
+    "description": "Short description shown in the app list",
+    "version": "1.0.0",
+    "remote_entry_url": "https://cdn.example.com/my-app/remoteEntry.js",
+    "module_scope": "myApp",
+    "author": "Acme Corp",
+    "enabled": true
+  }'
+```
+
+### Registration fields
+
+| Field                | Required | Notes                                                                                         |
+| -------------------- | -------- | --------------------------------------------------------------------------------------------- |
+| **Name**             | ✓        | Display name shown in the navigation menu and admin UI                                        |
+| **Description**      |          | Brief summary shown as a subtitle in the app list                                             |
+| **Version**          | ✓        | Semantic version (e.g. `1.0.0`). Used for display and auditing only — does not affect caching |
+| **Remote Entry URL** | ✓        | Full HTTPS URL to your `remoteEntry.js`. See Hosting requirements above                       |
+| **Extension App ID** | ✓        | See below                                                                                     |
+| **Author**           |          | Individual or company name. Shown in app details                                              |
+| **Enabled**          |          | Defaults to `true`. Set to `false` to register without immediately activating                 |
+
+### Extension App ID
+
+The **Extension App ID** (stored as `module_scope`) is the single most important field to get right. It must **exactly match** the `name` value in your webpack `ModuleFederationPlugin` config:
+
+```js
+// webpack.config.js
+new ModuleFederationPlugin({
+  name: 'myUcaasApp',   // ← this is your Extension App ID
+  ...
+})
+```
+
+```json
+// Registration
+{ "module_scope": "myUcaasApp" }
+```
+
+**Why it matters:** At runtime, the platform loads your bundle and calls `window['myUcaasApp'].init(...)` to initialise the federation container. If the name doesn't match exactly — including case — the container won't be found and your app silently fails to load with no visible error.
+
+**Rules:**
+
+- Must be unique across every app registered on the platform — duplicate names cause both apps to fail
+- Use camelCase (e.g. `myUcaasApp`, not `my-ucaas-app` or `MyUcaasApp`)
+- No spaces or special characters
+
+### Domain whitelist
+
+Your CDN domain must be approved by the Horizon administrator before the platform will load your app. Contact your admin and provide:
+
+- Your CDN domain or pattern (e.g. `cdn.example.com` or `*.example.com`)
+- Whether you need localhost approved for local development
+
+If the domain is not approved, your app will silently fail to load. Check the browser console for `[HorizonAppsLoader]` error messages containing your URL to confirm this is the cause.
+
+**For local development:** Ask your admin to temporarily add `localhost:5005` (or whatever port your dev server uses) to the approved list.
+
+### Verifying your app loaded
+
+After registering and refreshing the browser:
+
+1. **Open DevTools → Console** and look for log lines starting with `[Demo App]` or your app name — your `App.tsx` runs on page load and any `console.log` calls appear here
+
+2. **Check the network tab** — filter by your domain and look for `remoteEntry.js`. A `200` response confirms the bundle was fetched. A `CORS error` or `net::ERR_*` means the domain isn't reachable or CORS headers are missing
+
+3. **Look for your registered routes** — if you called `sdk.registerRoute`, your page should appear in the navigation sidebar immediately after the app loads
+
+4. **Look for your extensions** — visit the route pattern your extension targets (e.g. `/manage/call-logs`) and confirm the injected component appears
+
+5. **Check the Registered Apps page** (Platform → UI SDK Management → Registered Apps) — the **Extension Zones** column will show which zones your app has active extensions registered in once it has loaded
+
+If nothing appears after a full page refresh:
+
+- Confirm the **Enabled** toggle is on in the admin UI
+- Confirm your CDN domain is approved (see above)
+- Check for JavaScript errors in the console — a crash in your `App.tsx` before `sdk.registerRoute` is called means nothing gets registered
+
+---
+
+## After registration
+
+**Timing:** The app list is cached for up to 5 minutes. After registering, wait up to 5 minutes or do a hard refresh (`Ctrl+Shift+R` / `Cmd+Shift+R`) before expecting other users to see your app. In development mode, the cache is automatically bypassed.
+
+**Per-session load:** Your app's `App.tsx` mounts once per browser session inside a hidden container. It runs for the lifetime of the session, keeping all registrations active. Navigating between pages does not reload the app.
+
+**Enabling and disabling:** Toggling the **Enabled** switch takes effect immediately for new sessions — the running app list is refreshed in the background. Users in active sessions will see the change on their next page load.
+
+---
+
+## Managing your app
+
+### Updating a deployed app
+
+Deploying a new build to the same Remote Entry URL is the simplest strategy — the platform fetches whatever `remoteEntry.js` is at that URL on each session start. Update the **Version** field in the registration to record the change for auditing.
+
+If you use version-specific URLs (e.g. `cdn.example.com/my-app/v1.2.0/remoteEntry.js`), update the **Remote Entry URL** in the registration when you release a new version.
+
+Active sessions continue using the version that loaded when they started. Users see the new version on their next page refresh.
+
+### Disable vs. Delete
+
+| Action      | Effect                                                                                                                                     | Reversible?             |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
+| **Disable** | App stops loading for new sessions. Extensions and routes are immediately unregistered for all active users. Database record is preserved. | ✓ Re-enable at any time |
+| **Delete**  | Permanently removes the registration. Cannot be undone.                                                                                    | ✗                       |
+
+Use **Disable** when you need to take an app offline temporarily (maintenance, incident response). Use **Delete** only when decommissioning an app permanently.
+
+---
+
+## Cleanup & lifecycle
+
+`useRemoteApp` calls `sdk.cleanup()` on unmount, which emits unregister events for every route, dynamic extension, and dynamic column the SDK tracked. If you bypass the hook, call `sdk.cleanup()` yourself in your unmount path.
+
+---
+
+## Errors
+
+Throw and catch typed errors with codes:
+
+```tsx
+import { HorizonSDKError, apiError } from '@netsapiens/horizon-sdk';
+
+try {
+  await api.get('/...');
+} catch (err) {
+  if (HorizonSDKError.isHorizonSDKError(err)) {
+    console.error(err.code, err.getUserMessage());
+  }
+}
+```
+
+Codes: `PERMISSION_DENIED`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `NETWORK_ERROR`, `MODULE_LOAD_FAILED`, `INITIALIZATION_FAILED`, etc.
+
+---
+
+## Scaffolding a new app with Claude Code
+
+Run the slash command:
+
+```
+/create-horizon-app
+```
+
+(see `.claude/skills/create-horizon-app.md` for the full prompt.)
+
+Or paste this into a Claude Code session:
+
+> Scaffold a new remote app for NetSapiens Horizon called `<app-name>` with Extension App ID `<extensionAppId>` on port `<port>`. It should:
+>
+> - Use webpack Module Federation, expose `./App`, and share react/react-dom/loglevel/@netsapiens/horizon-sdk as singletons
+> - Have an `App.tsx` that uses `useRemoteApp(horizonContext, '<app-id>')` and registers one route at `/home/<app-id>` plus one dynamic extension on `page-header-actions` for `/manage/*/users`
+> - Use `HorizonContextProvider` + `useHorizonContext()` for all page components so dark mode works automatically
+> - Do NOT share `@mui/material`, `@mui/x-data-grid-pro`, `@emotion/*` in webpack — these are not provided by the host's federation loader
+> - Render all UI through `horizonContext.ui` to get themed components
+> - Include a README with run + register instructions
+
+For one-off tasks inside an existing remote app, prompts like these work well:
+
+> Add a dynamic table column to the call-logs grid that shows call priority. Use `sdk.registerDynamicColumn` with zone `call-logs-columns` and route pattern `/manage/*/call-logs`. The column should sort and filter by computed priority (`high`/`medium`/`low`).
+
+> Add an extension to `inbound-call-content` zone that fetches caller info from our CRM API and shows name + last contact date. Subscribe to `call-event` on the event bus and enrich the call data through `horizonContext.api`.
+
+---
+
+## License
+
+MIT