@managespace/sdk 0.1.158-braintree → 0.1.158-extensions-v2

package/README.md

@@ -1,6 +1,750 @@
 # @managespace/sdk
 
-update version number in package.json
-npm i
+ManageSpace SDK for building integrations and extensions.
+
+## Installation
+
+```bash
+npm install @managespace/sdk
+```
+
+---
+
+# Extension Development Guide
+
+This guide explains how to build extensions that run within the ManageSpace platform.
+
+## Overview
+
+ManageSpace extensions are standalone web applications that run in an iframe within the ManageSpace UI. They have access to:
+
+- **Authentication context** - User's auth token, org/site IDs
+- **ManageSpace APIs** - Full access to the REST API
+- **Host navigation** - Ability to navigate the main application
+- **Toast notifications** - Display feedback to users
+- **Entity events** - React to changes in ManageSpace data
+
+## Quick Start
+
+### 1. Create Project Structure
+
+```
+my-extension/
+├── package.json
+├── tsconfig.json
+├── vite.config.ts
+├── manifest.json
+├── index.html
+└── src/
+    ├── main.tsx
+    ├── App.tsx
+    └── styles.css
+```
+
+### 2. package.json
+
+**Important:** The `bundle` script is required to create the uploadable ZIP package. It builds the extension, copies the manifest, and creates the ZIP file.
+
+```json
+{
+    "name": "my-extension",
+    "version": "1.0.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc && vite build",
+        "bundle": "bun run build && cp manifest.json dist/ && cd dist && zip -r ../bundle.zip ."
+    },
+    "dependencies": {
+        "@managespace/sdk": "^0.1.0",
+        "react": "^18.3.0",
+        "react-dom": "^18.3.0"
+    },
+    "devDependencies": {
+        "@types/react": "^18.3.0",
+        "@types/react-dom": "^18.3.0",
+        "@vitejs/plugin-react": "^4.3.0",
+        "typescript": "^5.6.0",
+        "vite": "^5.4.0"
+    }
+}
+```
+
+### 3. tsconfig.json
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "useDefineForClassFields": true,
+        "lib": ["ES2020", "DOM", "DOM.Iterable"],
+        "module": "ESNext",
+        "skipLibCheck": true,
+        "moduleResolution": "bundler",
+        "allowImportingTsExtensions": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "noEmit": true,
+        "jsx": "react-jsx",
+        "strict": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noFallthroughCasesInSwitch": true
+    },
+    "include": ["src"]
+}
+```
+
+### 4. vite.config.ts
+
+```typescript
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+    plugins: [react()],
+    build: {
+        outDir: 'dist',
+        assetsDir: 'assets',
+        rollupOptions: {
+            output: {
+                entryFileNames: 'assets/[name].js',
+                chunkFileNames: 'assets/[name].js',
+                assetFileNames: 'assets/[name].[ext]',
+            },
+        },
+    },
+});
+```
+
+### 5. manifest.json
+
+```json
+{
+    "name": "My Extension",
+    "version": "1.0.0",
+    "author": "Your Name",
+    "description": "Description of what your extension does",
+    "navLabel": "My Extension",
+    "navIcon": "Layout",
+    "navRoute": "/extensions/my-extension",
+    "entryPoint": "index.html"
+}
+```
+
+**Manifest Fields:**
+
+| Field         | Required | Description                                              |
+| ------------- | -------- | -------------------------------------------------------- |
+| `name`        | Yes      | Display name of the extension                            |
+| `version`     | Yes      | Semantic version (e.g., "1.0.0")                         |
+| `author`      | Yes      | Author or company name                                   |
+| `description` | No       | Short description                                        |
+| `navLabel`    | Yes      | Label shown in navigation menu                           |
+| `navIcon`     | Yes      | Lucide icon name (e.g., "Users", "Settings", "BarChart") |
+| `navRoute`    | Yes      | Route path, must start with "/extensions/"               |
+| `entryPoint`  | Yes      | Entry HTML file (usually "index.html")                   |
+| `bff.url`     | No       | URL of your Backend for Frontend server                  |
+
+### 6. index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>My Extension</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>
+```
+
+### 7. src/main.tsx
+
+```typescript
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import { signalReady } from '@managespace/sdk/extensions';
+import './styles.css';
+
+// Signal to host that extension is ready to receive context
+signalReady();
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode>
+        <App />
+    </React.StrictMode>
+);
+```
+
+### 8. src/App.tsx
+
+```typescript
+import { useEffect, useState } from 'react';
+import {
+    getContext,
+    createApiFetch,
+    navigate,
+    showToast,
+    type ExtensionContext,
+} from '@managespace/sdk/extensions';
+
+export default function App() {
+    const [context, setContext] = useState<ExtensionContext | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        getContext()
+            .then(setContext)
+            .finally(() => setLoading(false));
+    }, []);
+
+    if (loading) {
+        return <div>Loading...</div>;
+    }
+
+    if (!context) {
+        return <div>Failed to receive context from host</div>;
+    }
+
+    return (
+        <div>
+            <h1>My Extension</h1>
+            <p>Organisation: {context.orgId}</p>
+            <p>User: {context.userId}</p>
+            {/* Your extension UI here */}
+        </div>
+    );
+}
+```
+
+---
+
+## Extension SDK API
+
+Import from `@managespace/sdk/extensions`:
+
+### getContext()
+
+Get the extension context from the ManageSpace host.
+
+```typescript
+import { getContext } from '@managespace/sdk/extensions';
+
+const context = await getContext();
+// context.orgId - Current organisation ID
+// context.userId - Current user ID
+// context.siteId - Current site ID
+// context.apiBaseUrl - Base URL for API calls
+// context.bffUrl - Your BFF URL (if configured)
+```
+
+### signalReady()
+
+Signal to the host that your extension is ready to receive context. Call this early in your extension's lifecycle.
+
+```typescript
+import { signalReady } from '@managespace/sdk/extensions';
+
+signalReady();
+```
+
+### navigate(path)
+
+Navigate the ManageSpace host to a specific path.
+
+```typescript
+import { navigate } from '@managespace/sdk/extensions';
+
+// Navigate to a customer profile
+navigate('/customer/abc-123');
+
+// Navigate to the assets page
+navigate('/assets');
+```
+
+### showToast(message, variant?)
+
+Show a toast notification in the host application.
+
+```typescript
+import { showToast } from '@managespace/sdk/extensions';
+
+showToast('Operation successful');
+showToast('Something went wrong', 'error');
+```
+
+### createApiFetch(context)
+
+Create a fetch function configured for ManageSpace API calls.
+
+```typescript
+import { getContext, createApiFetch } from '@managespace/sdk/extensions';
+
+const context = await getContext();
+const apiFetch = createApiFetch(context);
+
+const response = await apiFetch('/api/crm/customers/queries', {
+    method: 'POST',
+    body: JSON.stringify({
+        pageOptions: { offset: 0, limit: 20 },
+    }),
+});
+const data = await response.json();
+```
+
+### createBffFetch(context)
+
+Create a fetch function for calling your extension's Backend for Frontend.
+
+```typescript
+import { getContext, createBffFetch } from '@managespace/sdk/extensions';
+
+const context = await getContext();
+const bffFetch = createBffFetch(context);
+
+if (bffFetch) {
+    const response = await bffFetch('/api/my-endpoint');
+    const data = await response.json();
+}
+```
+
+### onEntityEvent(handler)
+
+Subscribe to entity events from the ManageSpace host.
+
+```typescript
+import { onEntityEvent } from '@managespace/sdk/extensions';
+
+const unsubscribe = onEntityEvent((event) => {
+    console.log(`${event.entityType} ${event.entityId} was ${event.action}`);
+    // event.entityType: 'customer', 'asset', 'subscription', etc.
+    // event.action: 'created', 'updated', 'deleted'
+});
+
+// To stop listening:
+unsubscribe();
+```
+
+---
+
+## ManageSpace API Reference
+
+Use `createApiFetch(context)` to call these endpoints. All requests include authentication automatically.
+
+### Customers
+
+#### List/Query Customers
+
+```typescript
+const response = await apiFetch('/api/crm/customers/queries', {
+    method: 'POST',
+    body: JSON.stringify({
+        pageOptions: { offset: 0, limit: 20 },
+        filters: [{ field: 'name', operator: 'contains', value: 'Smith' }],
+    }),
+});
+
+// Response: { results: Customer[], total: number }
+```
+
+**Customer Type:**
+
+```typescript
+interface Customer {
+    id: string;
+    name: string;
+    description: string | null;
+    orgId: string;
+    createdAt: Date;
+    updatedAt: Date | null;
+    customerStatusId: string;
+    commercial: boolean;
+    contacts?: Contact[];
+    // ... additional fields
+}
+```
+
+#### Get Customer by ID
+
+```typescript
+const response = await apiFetch(`/api/crm/customers/${customerId}`);
+const customer = await response.json();
+```
+
+### Assets
+
+#### List Assets
+
+```typescript
+const response = await apiFetch('/api/assets');
+// Response: { results: Asset[], total: number }
+```
+
+#### Get Asset by ID
+
+```typescript
+const response = await apiFetch(`/api/assets/${assetId}`);
+const asset = await response.json();
+```
+
+**Asset Type:**
+
+```typescript
+interface Asset {
+    id: string;
+    name: string;
+    siteId: string;
+    assetClassId: string;
+    status: string;
+    width: number | null;
+    height: number | null;
+    depth: number | null;
+    // ... additional fields
+}
+```
+
+### Subscriptions
+
+#### List Subscriptions
+
+```typescript
+const response = await apiFetch('/api/subscriptions/queries', {
+    method: 'POST',
+    body: JSON.stringify({
+        pageOptions: { offset: 0, limit: 20 },
+    }),
+});
+// Response: { results: Subscription[], total: number }
+```
+
+**Subscription Type:**
+
+```typescript
+interface Subscription {
+    id: string;
+    customerId: string;
+    assetId: string;
+    planId: string;
+    status: string;
+    startDate: Date;
+    endDate: Date | null;
+    // ... additional fields
+}
+```
+
+### Sites
+
+#### List Sites
+
+```typescript
+const response = await apiFetch('/api/sites');
+// Response: { results: Site[], total: number }
+```
+
+### Invoices
+
+#### List Invoices
+
+```typescript
+const response = await apiFetch('/api/billing/invoices/queries', {
+    method: 'POST',
+    body: JSON.stringify({
+        pageOptions: { offset: 0, limit: 20 },
+    }),
+});
+// Response: { results: Invoice[], total: number }
+```
+
+### Payments
+
+#### List Payments
+
+```typescript
+const response = await apiFetch('/api/billing/payments/queries', {
+    method: 'POST',
+    body: JSON.stringify({
+        pageOptions: { offset: 0, limit: 20 },
+    }),
+});
+// Response: { results: Payment[], total: number }
+```
+
+---
+
+## Building a Backend for Frontend (BFF)
+
+If your extension needs to call external APIs, perform complex data processing, or keep secrets secure, you can create a BFF.
+
+### 1. Update manifest.json
+
+```json
+{
+    "name": "My Extension",
+    "version": "1.0.0",
+    "author": "Your Name",
+    "navLabel": "My Extension",
+    "navIcon": "Layout",
+    "navRoute": "/extensions/my-extension",
+    "entryPoint": "index.html",
+    "bff": {
+        "url": "https://my-bff.example.com"
+    }
+}
+```
+
+### 2. Create BFF Server
+
+Using Hono (recommended):
+
+```typescript
+// server.ts
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+
+const app = new Hono();
+
+// Enable CORS for your ManageSpace instance
+app.use(
+    '*',
+    cors({
+        origin: ['https://your-managespace-instance.com'],
+        credentials: true,
+    }),
+);
+
+app.get('/api/my-endpoint', async (c) => {
+    // Get auth cookie forwarded from extension
+    const cookie = c.req.header('Cookie');
+
+    if (!cookie) {
+        return c.json({ error: 'Not authenticated' }, 401);
+    }
+
+    // Call ManageSpace API with forwarded credentials
+    const response = await fetch(
+        'https://your-instance/api/crm/customers/queries',
+        {
+            method: 'POST',
+            headers: {
+                Cookie: cookie,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ pageOptions: { offset: 0, limit: 20 } }),
+        },
+    );
+
+    const data = await response.json();
+
+    // Enrich or transform data
+    const enrichedData = data.results.map((customer) => ({
+        ...customer,
+        customField: 'added by BFF',
+    }));
+
+    return c.json({ customers: enrichedData });
+});
+
+export default {
+    port: 4000,
+    fetch: app.fetch,
+};
+```
+
+### 3. Call BFF from Extension
+
+```typescript
+import { getContext, createBffFetch } from '@managespace/sdk/extensions';
+
+const context = await getContext();
+const bffFetch = createBffFetch(context);
+
+if (bffFetch) {
+    const response = await bffFetch('/api/my-endpoint');
+    const data = await response.json();
+}
+```
+
+---
+
+## Building and Packaging
+
+### Development
+
+```bash
+bun run dev
+```
+
+This starts a local dev server. During development, the extension runs standalone and waits for context from the host.
+
+### Build
+
+```bash
+bun run build
+```
+
+Creates a production build in `dist/`.
+
+### Package for Upload (Required)
+
+Every extension must include a `bundle` script in package.json:
+
+```json
+{
+    "scripts": {
+        "bundle": "bun run build && cp manifest.json dist/ && cd dist && zip -r ../bundle.zip ."
+    }
+}
+```
+
+Run it to create the uploadable package:
+
+```bash
+bun run bundle
+```
+
+This creates `bundle.zip` containing:
+
+- `index.html` - Entry point
+- `assets/` - JS, CSS bundles
+- `manifest.json` - Extension metadata (copied from project root)
+
+Upload this ZIP file through the ManageSpace Admin > Extensions page.
+
+---
+
+## Available Lucide Icons
+
+For `navIcon` in manifest.json, use any Lucide icon name:
+
+**Common icons:**
+
+- `Users` - People/customers
+- `Building` - Properties/sites
+- `Box` - Assets/inventory
+- `CreditCard` - Payments/billing
+- `FileText` - Documents/invoices
+- `Settings` - Configuration
+- `BarChart` - Analytics/reports
+- `Calendar` - Scheduling
+- `Bell` - Notifications
+- `Search` - Search functionality
+- `Layout` - Dashboard/overview
+- `Truck` - Delivery/logistics
+- `Key` - Access/security
+- `Mail` - Communications
+
+See https://lucide.dev/icons for the full list.
+
+---
+
+## TypeScript Types
+
+All types are exported from `@managespace/sdk/extensions`:
+
+```typescript
+import type {
+    ExtensionContext,
+    ExtensionManifest,
+    HostMessage,
+    ExtensionMessage,
+    EntityEvent,
+    EntityEventHandler,
+} from '@managespace/sdk/extensions';
+```
+
+Entity types are available from the main SDK:
+
+```typescript
+import type {
+    Customer,
+    Asset,
+    Subscription,
+    Site,
+    Invoice,
+    Payment,
+    Contact,
+} from '@managespace/sdk';
+```
+
+---
+
+## Example: Customer List Extension
+
+Complete example showing customers with click-to-navigate:
+
+```typescript
+// src/App.tsx
+import { useEffect, useState } from 'react';
+import {
+    getContext,
+    createApiFetch,
+    navigate,
+    showToast,
+    type ExtensionContext,
+} from '@managespace/sdk/extensions';
+import type { Customer } from '@managespace/sdk';
+
+export default function App() {
+    const [context, setContext] = useState<ExtensionContext | null>(null);
+    const [customers, setCustomers] = useState<Customer[]>([]);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        getContext().then(setContext);
+    }, []);
+
+    useEffect(() => {
+        if (!context) return;
+
+        const apiFetch = createApiFetch(context);
+
+        apiFetch('/api/crm/customers/queries', {
+            method: 'POST',
+            body: JSON.stringify({
+                pageOptions: { offset: 0, limit: 20 }
+            })
+        })
+            .then(res => res.json())
+            .then(data => setCustomers(data.results || []))
+            .catch(() => showToast('Failed to load customers', 'error'))
+            .finally(() => setLoading(false));
+    }, [context]);
+
+    if (loading) return <div>Loading...</div>;
+
+    return (
+        <div>
+            <h1>Customers</h1>
+            <ul>
+                {customers.map(customer => (
+                    <li
+                        key={customer.id}
+                        onClick={() => navigate(`/customer/${customer.id}`)}
+                        style={{ cursor: 'pointer' }}
+                    >
+                        {customer.name}
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+}
+```
+
+---
+
+## Publishing the SDK
+
+```bash
+# Update version in package.json
+npm install
 npm run build
 npm publish
+```