npm - @managespace/sdk - Versions diffs - 0.1.158-extensions → 0.1.159 - Mend

@managespace/sdk 0.1.158-extensions → 0.1.159

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 (55) hide show

package/README.md +2 -723
package/dist/extensibility/functions/project/billing.d.ts +7 -0
package/dist/extensibility/functions/project/billing.d.ts.map +1 -1
package/dist/extensibility/functions/project/billing.js +5 -0
package/dist/extensibility/types/control.d.ts +1 -1
package/dist/extensibility/types/control.d.ts.map +1 -1
package/dist/generated/apis/default-api.d.ts +9 -1
package/dist/generated/apis/default-api.d.ts.map +1 -1
package/dist/generated/apis/default-api.js +28 -0
package/dist/generated/apis/index.d.ts +0 -1
package/dist/generated/apis/index.d.ts.map +1 -1
package/dist/generated/apis/index.js +0 -1
package/dist/generated/models/index.d.ts +1 -2
package/dist/generated/models/index.d.ts.map +1 -1
package/dist/generated/models/index.js +1 -2
package/dist/generated/models/payment-gateway-client-token-response.d.ts +47 -0
package/dist/generated/models/payment-gateway-client-token-response.d.ts.map +1 -0
package/dist/generated/models/payment-gateway-client-token-response.js +63 -0
package/dist/index.d.ts +0 -1
package/dist/index.d.ts.map +1 -1
package/dist/index.js +0 -1
package/package.deploy.json +7 -3
package/package.json +2 -5
package/src/extensibility/functions/project/billing.ts +6 -0
package/src/extensibility/types/control.ts +1 -0
package/src/generated/.openapi-generator/FILES +1 -3
package/src/generated/apis/default-api.ts +37 -0
package/src/generated/apis/index.ts +0 -1
package/src/generated/models/index.ts +1 -2
package/src/generated/models/payment-gateway-client-token-response.ts +87 -0
package/src/index.ts +0 -1
package/dist/extensions/host-bridge.d.ts +0 -166
package/dist/extensions/host-bridge.d.ts.map +0 -1
package/dist/extensions/host-bridge.js +0 -259
package/dist/extensions/index.d.ts +0 -40
package/dist/extensions/index.d.ts.map +0 -1
package/dist/extensions/index.js +0 -55
package/dist/extensions/types.d.ts +0 -111
package/dist/extensions/types.d.ts.map +0 -1
package/dist/extensions/types.js +0 -2
package/dist/generated/apis/extensions-api.d.ts +0 -98
package/dist/generated/apis/extensions-api.d.ts.map +0 -1
package/dist/generated/apis/extensions-api.js +0 -295
package/dist/generated/models/extension-org.d.ts +0 -64
package/dist/generated/models/extension-org.d.ts.map +0 -1
package/dist/generated/models/extension-org.js +0 -70
package/dist/generated/models/extension.d.ts +0 -106
package/dist/generated/models/extension.d.ts.map +0 -1
package/dist/generated/models/extension.js +0 -98
package/src/extensions/host-bridge.ts +0 -272
package/src/extensions/index.ts +0 -40
package/src/extensions/types.ts +0 -120
package/src/generated/apis/extensions-api.ts +0 -362
package/src/generated/models/extension-org.ts +0 -119
package/src/generated/models/extension.ts +0 -182

package/README.md CHANGED Viewed

@@ -1,727 +1,6 @@
 # @managespace/sdk
-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
-```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/gateway/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
-npm run dev
-```
-This starts a local dev server. During development, the extension runs standalone and waits for context from the host.
-### Build
-```bash
-npm run build
-```
-Creates a production build in `dist/`.
-### Package for Upload
-```bash
-npm run bundle
-```
-Creates `bundle.zip` containing:
-- `index.html`
-- `assets/` (JS, CSS)
-- `manifest.json`
-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
+update version number in package.json
+npm i
 npm run build
 npm publish
-```