Integration Guide

<script src="https://your-widget-builder-url.com/embed/sdk.js"></script>

<widget-builder-button
  session-id="ess_YOUR_SESSION_ID"
  base-url="https://your-widget-builder-url.com"
></widget-builder-button>

<div id="my-widgets"></div>

<script>
  WidgetBuilder.renderAll({
    sessionId: 'ess_YOUR_SESSION_ID',
    container: '#my-widgets',
    baseUrl: 'https://your-widget-builder-url.com',
    columns: 2
  });
</script>

Content-Type: application/json
Authorization: Bearer <SETUP_SECRET>

{
  "email": "you@your-company.com",   // Required: admin's email
  "name": "Your Name"                // Required: admin's display name
}

curl -X POST {WIDGET_BUILDER_URL}/api/setup \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <SETUP_SECRET>" \
  -d '{
    "email": "you@your-company.com",
    "name": "Your Name"
  }'

{
  "data": {
    "message": "Setup completed successfully. Login at /admin/login using email OTP",
    "admin": {
      "email": "you@your-company.com",
      "name": "Your Name"
    }
  },
  "error": null
}

{
  "data": null,
  "error": "Setup already completed. Admin user already exists."
}

curl {WIDGET_BUILDER_URL}/api/setup \
  -H "Authorization: Bearer <SETUP_SECRET>"

{
  "data": {
    "setupRequired": false,
    "adminCount": 1
  },
  "error": null
}

{
  "appName": "Construction Portal",
  "version": "1.0.0",
  "endpoints": [
    {
      "path": "/api/projects",
      "method": "GET",
      "description": "List construction projects with status, budget, site manager, start/end dates. Supports filtering by status and date range, plus pagination and sorting.",
      "module": "projects",
      "listArrayPath": "data",
      "queryParameters": [
        { "name": "status",    "type": "string", "required": false, "description": "Filter by status. One of: planning, active, on_hold, completed, cancelled." },
        { "name": "startDate", "type": "string", "required": false, "description": "ISO date. Returns projects starting on or after this date." },
        { "name": "endDate",   "type": "string", "required": false, "description": "ISO date. Returns projects ending on or before this date." },
        { "name": "limit",     "type": "number", "required": false, "description": "Max rows to return. Default 50, max 500." },
        { "name": "offset",    "type": "number", "required": false, "description": "Rows to skip for pagination." },
        { "name": "sortBy",    "type": "string", "required": false, "description": "Field to sort by. One of: name, startDate, budget, status." },
        { "name": "sortOrder", "type": "string", "required": false, "description": "Sort direction. One of: asc, desc." }
      ],
      "fieldSchema": [
        { "name": "id",          "path": "id",          "type": "string", "description": "Unique project identifier",             "isIdentifier": true },
        { "name": "name",        "path": "name",        "type": "string", "description": "Project name" },
        { "name": "status",      "path": "status",      "type": "string", "description": "Current project status",                "groupable": true, "enumValues": ["planning","active","on_hold","completed","cancelled"] },
        { "name": "budget",      "path": "budget",      "type": "number", "description": "Total budget in USD",                   "numeric": true },
        { "name": "spent",       "path": "spent",       "type": "number", "description": "Amount spent to date in USD",           "numeric": true },
        { "name": "startDate",   "path": "startDate",   "type": "date",   "description": "Project start date",                    "dateLike": true },
        { "name": "endDate",     "path": "endDate",     "type": "date",   "description": "Scheduled end date",                    "dateLike": true },
        { "name": "siteManager", "path": "siteManager", "type": "string", "description": "Site manager's user id",                "lookupRef": "users" },
        { "name": "region",      "path": "region",      "type": "string", "description": "Geographic region",                     "groupable": true, "enumValues": ["north","south","east","west","central"] },
        { "name": "progress",    "path": "progress",    "type": "number", "description": "Completion percentage 0-100",           "numeric": true }
      ]
    },
    {
      "path": "/api/tasks",
      "method": "GET",
      "description": "List tasks across all projects. Can be filtered by project, assignee, priority, or status.",
      "module": "tasks",
      "listArrayPath": "items",
      "queryParameters": [
        { "name": "projectId", "type": "string", "required": false, "description": "Filter tasks belonging to a specific project id." },
        { "name": "assignee",  "type": "string", "required": false, "description": "Filter by assigned user id." },
        { "name": "priority",  "type": "string", "required": false, "description": "One of: low, medium, high, urgent." },
        { "name": "status",    "type": "string", "required": false, "description": "One of: todo, in_progress, blocked, done." },
        { "name": "limit",     "type": "number", "required": false, "description": "Max rows. Default 50." }
      ],
      "fieldSchema": [
        { "name": "id",          "path": "id",          "type": "string", "description": "Task id",                          "isIdentifier": true },
        { "name": "title",       "path": "title",       "type": "string", "description": "Task title" },
        { "name": "projectId",   "path": "projectId",   "type": "string", "description": "Parent project id",                "lookupRef": "projects" },
        { "name": "assignee",    "path": "assignee",    "type": "string", "description": "Assigned user id",                 "lookupRef": "users" },
        { "name": "priority",    "path": "priority",    "type": "string", "description": "Task priority",                    "groupable": true, "enumValues": ["low","medium","high","urgent"] },
        { "name": "status",      "path": "status",      "type": "string", "description": "Task status",                      "groupable": true, "enumValues": ["todo","in_progress","blocked","done"] },
        { "name": "dueDate",     "path": "dueDate",     "type": "date",   "description": "Task due date",                    "dateLike": true },
        { "name": "hoursLogged", "path": "hoursLogged", "type": "number", "description": "Hours logged against this task",   "numeric": true }
      ]
    },
    {
      "path": "/api/invoices",
      "method": "GET",
      "description": "List invoices issued to clients. Returns amount, payment status, and issue/due dates.",
      "module": "finance",
      "listArrayPath": "data",
      "queryParameters": [
        { "name": "status",   "type": "string", "required": false, "description": "One of: draft, sent, paid, overdue, cancelled." },
        { "name": "clientId", "type": "string", "required": false, "description": "Filter by client id." },
        { "name": "fromDate", "type": "string", "required": false, "description": "ISO date. Issued on or after." },
        { "name": "toDate",   "type": "string", "required": false, "description": "ISO date. Issued on or before." },
        { "name": "limit",    "type": "number", "required": false, "description": "Max rows. Default 50." }
      ],
      "fieldSchema": [
        { "name": "id",       "path": "id",       "type": "string", "description": "Invoice id",                  "isIdentifier": true },
        { "name": "number",   "path": "number",   "type": "string", "description": "Human-readable invoice number" },
        { "name": "clientId", "path": "clientId", "type": "string", "description": "Client id",                   "lookupRef": "clients" },
        { "name": "amount",   "path": "amount",   "type": "number", "description": "Total amount in USD",         "numeric": true },
        { "name": "status",   "path": "status",   "type": "string", "description": "Payment status",              "groupable": true, "enumValues": ["draft","sent","paid","overdue","cancelled"] },
        { "name": "issuedAt", "path": "issuedAt", "type": "date",   "description": "Date the invoice was issued", "dateLike": true },
        { "name": "dueAt",    "path": "dueAt",    "type": "date",   "description": "Date payment is due",         "dateLike": true },
        { "name": "paidAt",   "path": "paidAt",   "type": "date",   "description": "Date payment was received",   "dateLike": true }
      ]
    }
  ]
}

{
  "appName": "My App",
  "version": "1.0.0",
  "endpoints": [
    { "path": "/api/analytics/revenue", "method": "GET", "description": "Monthly revenue aggregates" }
  ]
}

import { NextRequest, NextResponse } from "next/server";
import { getAllApiEndpoints } from "@/lib/api-discovery";

export async function GET(req: NextRequest) {
  // 1. Refuse to run if the secret isn't configured — don't leak the catalog
  const expectedSecret = process.env.WIDGET_BUILDER_APP_SECRET;
  if (!expectedSecret) {
    return NextResponse.json(
      { error: "Server misconfigured: app secret not set" },
      { status: 500 }
    );
  }

  // 2. Validate x-app-secret — this is how Widget Builder authenticates
  const providedSecret = req.headers.get("x-app-secret");
  if (!providedSecret || providedSecret !== expectedSecret) {
    return NextResponse.json(
      { error: "Unauthorized: missing or invalid x-app-secret" },
      { status: 401 }
    );
  }

  // 3. Only expose GET endpoints — never mutating routes
  const allEndpoints = await getAllApiEndpoints();
  const endpoints = allEndpoints.filter((ep) => ep.method === "GET");

  return NextResponse.json({
    appName: "Construction Portal",
    version: "1.0.0",
    endpoints: endpoints.map((ep) => ({
      path: ep.path,
      method: ep.method,
      description: ep.description,
      module: ep.module,
      queryParameters: ep.queryParameters,
      listArrayPath: ep.listArrayPath,
      fieldSchema: ep.fieldSchema,
    })),
  });
}

// Optional: respond to HEAD pings (Widget Builder uses these for health checks)
export async function HEAD() {
  return new NextResponse(null, { status: 200 });
}

# Public — so the SDK script can load in the browser
NEXT_PUBLIC_WIDGET_BUILDER_URL=https://widget-builder.example.com

# Server-only — never expose to the browser
WIDGET_BUILDER_APP_ID=6651b...
WIDGET_BUILDER_APP_SECRET=wbs_...

Content-Type: application/json
x-app-secret: wbs_your_app_secret      // or pass appSecret in the body

{
  "organizationName": "Acme Corp",          // Required: tenant/org display name
  "firstName": "Jane",                      // Required: owner first name
  "lastName": "Doe",                        // Required: owner last name
  "email": "jane@acme.com",                 // Required: owner email
  "appId": "673abc123def456789012345",      // Required: appId from admin portal (or use appName)
  "appName": "construction-portal",         // Alt to appId: exact connected app name
  "appSecret": "wbs_xxx...",                // Required if not sent as x-app-secret header
  "apiKeyName": "Acme Corp - Embed Token",  // Optional: default = "{orgName} - Embed Token"
  "allowedDomains": ["acme.com"],           // Optional: domain whitelist (empty = allow all)
  "hasExpiry": false,                       // Optional: set true for expiring token
  "expiryDays": 90                          // Optional: days until expiry (1-365), only when hasExpiry: true
}

curl -X POST https://your-widget-builder.com/api/embed/onboard \
  -H "Content-Type: application/json" \
  -H "x-app-secret: wbs_your_app_secret" \
  -d '{
    "organizationName": "Acme Corp",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acme.com",
    "appId": "673abc123def456789012345",
    "allowedDomains": ["acme.com", "*.acme.com"]
  }'

{
  "success": true,
  "data": {
    "message": "Successfully onboarded. Store the embed token securely — it won't be shown again.",
    "organization": {
      "id": "6651a1b2c3d4e5f6a7b8c9d0",
      "name": "Acme Corp",
      "slug": "acme-corp-1742035200000"
    },
    "user": {
      "id": "65fa1b2c3d4e5f6a7b8c9d0e",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@acme.com",
      "role": "owner",
      "isExistingUser": false
    },
    "embedToken": {
      "id": "6651c1b2c3d4e5f6a7b8c9d0",
      "name": "Acme Corp - Embed Token",
      "token": "emb_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789012345678",
      "allowedDomains": ["acme.com", "*.acme.com"],
      "expiresAt": null
    },
    "appId": "673abc123def456789012345"
  }
}

curl -X POST https://your-widget-builder.com/api/embed/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "6651b...",
    "appSecret": "wbs_your_app_secret",
    "userEmail": "user@company.com",
    "embedToken": "emb_STORED_FOR_THIS_TENANT"
  }'

{
  "success": true,
  "data": {
    "sessionId": "ess_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "expiresAt": "2025-01-02T12:00:00.000Z",
    "userEmail": "user@company.com",
    "organizationId": "6651a...",
    "appId": "6651b..."
  }
}

WidgetBuilder.init({
  sessionId: 'ess_a1b2c3d4...',
  container: '#widget-builder',
  baseUrl: 'https://your-widget-builder.com',
});

// Web component
// <widget-builder-button session-id="ess_xxx" base-url="https://..." />

curl https://your-widget-builder.com/api/embed/verify \
  -H "x-session-id: ess_YOUR_SESSION_ID"

const res = await fetch(
  `${WB_URL}/api/embed/sessions/${sessionId}/refresh`,
  {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      appId: "6651b...",
      appSecret: "wbs_your_app_secret",
    }),
  }
);
const { data } = await res.json();
// data.expiresAt → new expiration timestamp

{
  "create": true,
  "edit":   "ALL",
  "delete": "OWN",
  "drag":   false
}

const role = await getRoleForUser(userId, tenantId);

const permissions = role.isAdmin
  ? { create: true, edit: "ALL", delete: "ALL", drag: true }
  : role.widgetPermissions ?? UNRESTRICTED;   // absent ⇒ unrestricted

{
  "appId": "6651b...",
  "appSecret": "wbs_your_app_secret",
  "userEmail": "user@company.com",
  "embedToken": "emb_STORED_FOR_THIS_TENANT",
  "permissions": { "create": true, "edit": "OWN", "delete": "NONE", "drag": false },
  "roleKey": "site-manager"
}

{
  "appId": "6651b...",
  "appSecret": "wbs_your_app_secret",
  "organizationId": "6651a...",
  "roleKey": "site-manager",
  "permissions": { "create": false, "edit": "OWN", "delete": "NONE", "drag": false }
}

WidgetBuilder.getPermissions({ sessionId: 'ess_...' }).then((p) => {
  addWidgetButton.hidden = !p.create;
});

{
  "success": true,
  "data": {
    "permissions": { "create": false, "edit": "OWN", "delete": "NONE", "drag": false },
    "userId": "6651c...",
    "userEmail": "user@company.com",
    "restricted": true
  }
}

╔══════════════════╗     (1) /api/embed/sessions     ╔══════════════════╗
║   Your backend   ║◀─────────────────────────────────║  Widget Builder  ║
║                  ║─────── sessionId: ess_… ─────────▶║                  ║
╚════════╤═════════╝                                   ╚════════▲═════════╝
         │                                                      │
         │ (2) returns sessionId                                 │ (4) iframe
         ▼                                                      │     loads
╔══════════════════╗     (3) WidgetBuilder.init(cfg)    ╔═══════╧═════════╗
║   Your browser   ║─────────────────────────────────▶ ║ sdk.js creates  ║
║                  ║◀─── onSave / onClose callbacks ──║ iframes/buttons ║
╚══════════════════╝                                   ╚══════════════════╝

<!DOCTYPE html>
<html>
<body>

  <!-- 1. Load the SDK once, at the top -->
  <script src="https://your-widget-builder.com/embed/sdk.js"></script>

  <!-- 2. The "+ Add Widget" button (opens a modal on click) -->
  <widget-builder-button
    session-id="ess_YOUR_SESSION_ID"
    base-url="https://your-widget-builder.com"
    dashboard-id="main"
    label="+ Add Widget"
    theme="light"
  ></widget-builder-button>

  <!-- 3. Container where the dashboard iframe will mount -->
  <div id="my-dashboard"></div>

  <!-- 4. Mount the dashboard into the container above -->
  <script>
    WidgetBuilder.init({
      sessionId: 'ess_YOUR_SESSION_ID',
      baseUrl:   'https://your-widget-builder.com',
      container: '#my-dashboard',
      dashboardId: 'main',    // ← MUST match dashboard-id on the button
      height:    '700px',
    })
  </script>

</body>
</html>

const btn = document.querySelector('widget-builder-button');

// Fires when a widget is saved
btn.addEventListener('widget-saved', function(e) {
  console.log('Widget saved:', e.detail);
  // e.detail contains { _id, name, ... }
});

// Fires when the modal is closed
btn.addEventListener('widget-closed', function(e) {
  console.log('Modal closed');
});

export function loadWidgetBuilderSdk(baseUrl) {
  return new Promise((resolve, reject) => {
    // Already loaded? Done.
    if (window.WidgetBuilder) return resolve(window.WidgetBuilder)

    // Script already appended but still loading? Wait for it.
    const existing = document.querySelector('script[data-wb-sdk]')
    if (existing) {
      existing.addEventListener('load', () => resolve(window.WidgetBuilder))
      existing.addEventListener('error', reject)
      return
    }

    // First time: inject the script.
    const s = document.createElement('script')
    s.src = baseUrl.replace(/\/$/, '') + '/embed/sdk.js'
    s.async = true
    s.dataset.wbSdk = 'true'
    s.onload = () => resolve(window.WidgetBuilder)
    s.onerror = () => reject(new Error('Failed to load Widget Builder SDK'))
    document.head.appendChild(s)
  })
}

<script setup>
import { onMounted, ref } from 'vue'
import { loadWidgetBuilderSdk } from './loadWidgetBuilderSdk'

const props = defineProps({ sessionId: String, dashboardId: String })
const container = ref(null)
const BASE_URL = 'https://your-widget-builder.com'

onMounted(async () => {
  const sdk = await loadWidgetBuilderSdk(BASE_URL)
  sdk.init({
    sessionId: props.sessionId,
    baseUrl: BASE_URL,
    container: container.value,
    dashboardId: props.dashboardId,
    height: '680px',
  })
})
</script>

<template>
  <div ref="container"></div>
</template>

WidgetBuilder.addButton({
  sessionId: 'ess_...',          // required — session minted by your backend
  container: '#my-btn',          // required — CSS selector or HTMLElement
  baseUrl: 'https://...',        // required
  tenantId: 'tenant_123',        // optional
  appId: 'app_456',              // optional
  dashboardId: 'my-dashboard',   // optional — scope widgets to a specific dashboard
  label: '+ Add Widget',         // optional
  theme: 'light',                // optional: 'light' | 'dark' | 'auto' — also themes the builder modal
  buttonStyle: {                 // optional: CSS overrides
    borderRadius: '20px',
    background: '#e11d48',
  },
  onSave: function(widget) {},   // optional — called when widget is saved
  onClose: function() {},        // optional — called when modal closes
});

document.getElementById('my-custom-button').onclick = function() {
  WidgetBuilder.openModal({
    sessionId: 'ess_...',        // required
    baseUrl: 'https://...',      // required
    tenantId: 'tenant_123',      // optional
    appId: 'app_456',            // optional
    dashboardId: 'my-dashboard', // optional
    path: '/embed/add',          // optional — see table below
    theme: 'dark',               // optional: 'light' | 'dark' | 'auto'
    onSave: function(widget) { console.log('Saved:', widget); },
    onClose: function() { console.log('Closed'); },
  });
};

WidgetBuilder.init({
  sessionId: 'ess_...',          // required — session minted by your backend
  container: '#my-container',    // required
  baseUrl: 'https://...',        // required
  tenantId: 'tenant_123',        // optional
  appId: '...',                  // optional — scope to a specific connected app
  dashboardId: 'my-dashboard',   // optional — scope widgets to a named dashboard
  theme: 'dark',                 // optional: 'light' | 'dark' | 'auto' (follows OS)
  width: '100%',                 // optional, default: '100%'
  height: '600px',               // optional, default: '600px'
});

WidgetBuilder.render({
  widgetId: '...',               // required — the widget's _id
  sessionId: 'ess_...',          // required
  container: '#my-widget',       // required
  baseUrl: 'https://...',        // required
  tenantId: 'tenant_123',        // optional
  dashboardId: 'my-dashboard',   // optional — must match what the widget was saved with
  theme: 'dark',                 // optional: 'light' | 'dark' | 'auto'
  width: '100%',                 // optional, default: '100%'
  height: '400px',               // optional, default: '400px'
});

WidgetBuilder.renderAll({
  sessionId: 'ess_...',          // required
  container: '#dashboard',       // required
  baseUrl: 'https://...',        // required
  tenantId: 'tenant_123',        // optional
  dashboardId: 'my-dashboard',   // optional — only load widgets for this dashboard
  theme: 'dark',                 // optional: 'light' | 'dark' | 'auto' — applied to every widget iframe
  columns: 2,                    // optional, default: 2
  widgetHeight: '400px',         // optional, default: '400px'
  gap: '16px',                   // optional, default: '16px'
});

WidgetBuilder.init({
  sessionId, container: '#dash', baseUrl, dashboardId: 'main',
  theme: 'dark',
});

WidgetBuilder.addButton({
  sessionId, container: '#add-btn', baseUrl, dashboardId: 'main',
  theme: 'dark',   // matches init — button AND modal go dark
});

// when host theme changes
container.innerHTML = '';
WidgetBuilder.init({ ...previousConfig, theme: newTheme });

WidgetBuilder.addButton({
  sessionId, baseUrl, container: '#my-btn',
  dashboardId: 'main',

  onSave: function (widget) {
    // widget = { _id, name, html, css, js, ... }
    console.log('Saved:', widget)
    // If init() was called with the SAME dashboardId,
    // the SDK auto-refreshes that iframe — no extra code needed.
  },

  onClose: function () {
    console.log('User cancelled')
  },
})

const btn = document.querySelector('widget-builder-button')

btn.addEventListener('widget-saved', (e) => {
  console.log('Saved:', e.detail)    // { _id, name, ... }
})

btn.addEventListener('widget-closed', () => {
  console.log('Modal closed')
})

const WB_ORIGIN = 'https://your-widget-builder.com'

window.addEventListener('message', (event) => {
  if (event.origin !== WB_ORIGIN) return       // verify origin!

  switch (event.data?.type) {
    case 'widget-builder:saved':
      console.log('Saved:', event.data.widget)
      break
    case 'widget-builder:close':
      console.log('Closed')
      break
  }
})

<widget-builder-button
  session-id="ess_YOUR_SESSION_ID"
  base-url="https://your-widget-builder.com"
  tenant-id="CURRENT_TENANT_ID"
></widget-builder-button>

// When the user switches tenants in your app:
WidgetBuilder.setTenant({ tenantId: 'new_tenant_id' });
// This reloads all active Widget Builder iframes with the new tenant context.

{
  "success": true,
  "data": {
    // Response data here
  }
}

{
  "success": false,
  "error": "Human-readable error message"
}

{
  "success": true,
  "data": [
    { "_id": "...", "name": "Widget 1", "createdAt": "2025-01-01T..." },
    { "_id": "...", "name": "Widget 2", "createdAt": "2025-01-02T..." }
  ]
}