@topolo/sdk 0.2.4 → 0.2.6

package/README.md

@@ -94,6 +94,29 @@ that contract into catalog-backed conformance reports and migration-queue items.
 Catalog-visible evidence is marked directly; implementation details that require
 code or docs inspection are deliberately marked `needs_review`.
 
+## Native dashboard widgets
+
+Launchable first-party applications populate the TopoloOne live workspace through
+their own `GET /api/widget` endpoint. The SDK owns the shared payload contract:
+
+```ts
+import { createTopoloWidgetResponse } from '@topolo/sdk';
+
+return Response.json(createTopoloWidgetResponse({
+  serviceId: 'srv_topolo_example',
+  serviceName: 'Example',
+  widgets: [
+    {
+      type: 'stats',
+      stats: [{ label: 'Open items', value: 3 }],
+    },
+  ],
+}));
+```
+
+Use `validateTopoloWidgetResponse()` in endpoint tests to prevent app-local
+payload drift.
+
 ## Escape hatch
 
 ```ts

package/dist/index.cjs

@@ -1,3 +1,4 @@
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -26,6 +27,8 @@ __export(index_exports, {
   DEFAULT_SERVICE_URLS: () => DEFAULT_SERVICE_URLS,
   IdentityModule: () => IdentityModule,
   PLATFORM_SERVICE_IDS: () => PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT: () => TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS: () => TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError: () => TopoloAuthError,
   TopoloClient: () => TopoloClient,
   TopoloHttpError: () => TopoloHttpError,
@@ -36,8 +39,16 @@ __export(index_exports, {
   auditAllApplicationRequirements: () => auditAllApplicationRequirements,
   auditApplicationRequirements: () => auditApplicationRequirements,
   createTopolo: () => createTopolo,
+  createTopoloWidgetError: () => createTopoloWidgetError,
+  createTopoloWidgetResponse: () => createTopoloWidgetResponse,
+  defineTopoloChartWidget: () => defineTopoloChartWidget,
+  defineTopoloNotificationsWidget: () => defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget: () => defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget: () => defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   requirementsForApplication: () => requirementsForApplication,
-  resolveServiceUrl: () => resolveServiceUrl
+  resolveServiceUrl: () => resolveServiceUrl,
+  validateTopoloWidgetResponse: () => validateTopoloWidgetResponse
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -103,14 +114,20 @@ var TopoloHttpError = class extends TopoloSdkError {
 var SERVICES = {
   agent: "https://topolo-agent-worker.topolo.workers.dev",
   auth: "https://auth.topolo.app",
+  books: "https://books.topolo.app",
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://r2-media-manager-worker.topolo.workers.dev",
   calendar: "https://calendar.topolo.app",
   chat: "https://chat.topolo.app",
   commerce: "https://topolo-commerce-api.topolo.workers.dev",
   crm: "https://crm-api.topolo.app",
+  customer_success: "https://customer-success.topolo.app",
   feed: "https://topolo-feed-api.topolo.app",
+  flow: "https://flow.topolo.app",
   forecast: "https://forecast-worker-production.topolo.workers.dev",
+  forms: "https://forms.topolo.app",
+  insights: "https://insights.topolo.app",
+  inventory: "https://inventory.topolo.app",
   learn: "https://topololearn-api.topolo.workers.dev",
   mail: "https://mail.topolo.app",
   mdm: "https://topolo-mdm-api.topolo.app",
@@ -118,16 +135,30 @@ var SERVICES = {
   nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
   one: "https://one.topolo.app",
   pay: "https://topolo-pay.topolo.workers.dev",
+  people: "https://people.topolo.app",
   "quro.api": "https://api.ol0.me",
   "quro.redirect": "https://ol0.me",
   roadmapper: "https://roadmapper-api.topolo.app",
+  sign: "https://sign.topolo.app",
   social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
   socialize: "https://socialize-prod-api.topolo.workers.dev",
   support: "https://support.topolo.app",
+  survey: "https://survey.topolo.app",
+  voice: "https://voice.topolo.app",
   web: "https://web-api.topolo.app"
 };
 var PLATFORM_SERVICE_IDS = {
-  crm: "srv_iCwM4jGXcwlj"
+  books: "srv_topolo_books",
+  crm: "srv_iCwM4jGXcwlj",
+  customer_success: "srv_topolo_customer_success",
+  flow: "srv_topolo_flow",
+  forms: "srv_topolo_forms",
+  insights: "srv_topolo_insights",
+  inventory: "srv_topolo_inventory",
+  people: "srv_topolo_people",
+  sign: "srv_topolo_sign",
+  survey: "srv_topolo_survey",
+  voice: "srv_topolo_voice"
 };
 
 // src/applications.generated.ts
@@ -202,6 +233,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "books": {
+    "id": "books",
+    "appDir": "TopoloBooks",
+    "name": "topolo-books",
+    "packageName": "topolo-books",
+    "productionUrl": "https://books.topolo.app",
+    "services": [
+      "books"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-books",
+        "kind": "worker",
+        "apiUrl": "https://books.topolo.app",
+        "domains": [
+          "books.topolo.app"
+        ],
+        "routes": [
+          "books.topolo.app"
+        ],
+        "serviceId": "books"
+      }
+    ]
+  },
   "bugfix": {
     "id": "bugfix",
     "appDir": "TopoloBugFix",
@@ -403,6 +458,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "customer_success": {
+    "id": "customer_success",
+    "appDir": "TopoloCustomerSuccess",
+    "name": "topolo-customer-success",
+    "packageName": "topolo-customer-success",
+    "productionUrl": "https://customer-success.topolo.app",
+    "services": [
+      "customer_success"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-customer-success",
+        "kind": "worker",
+        "apiUrl": "https://customer-success.topolo.app",
+        "domains": [
+          "customer-success.topolo.app"
+        ],
+        "routes": [
+          "customer-success.topolo.app"
+        ],
+        "serviceId": "customer_success"
+      }
+    ]
+  },
   "developers": {
     "id": "developers",
     "appDir": "TopoloDevelopers",
@@ -479,6 +558,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "flow": {
+    "id": "flow",
+    "appDir": "TopoloFlow",
+    "name": "topolo-flow",
+    "packageName": "topolo-flow",
+    "productionUrl": "https://flow.topolo.app",
+    "services": [
+      "flow"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-flow",
+        "kind": "worker",
+        "apiUrl": "https://flow.topolo.app",
+        "domains": [
+          "flow.topolo.app"
+        ],
+        "routes": [
+          "flow.topolo.app"
+        ],
+        "serviceId": "flow"
+      }
+    ]
+  },
   "forecast": {
     "id": "forecast",
     "appDir": "TopoloForecast",
@@ -507,6 +610,78 @@ var APPLICATIONS = {
       }
     ]
   },
+  "forms": {
+    "id": "forms",
+    "appDir": "TopoloForms",
+    "name": "topolo-forms",
+    "packageName": "topolo-forms",
+    "productionUrl": "https://forms.topolo.app",
+    "services": [
+      "forms"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-forms",
+        "kind": "worker",
+        "apiUrl": "https://forms.topolo.app",
+        "domains": [
+          "forms.topolo.app"
+        ],
+        "routes": [
+          "forms.topolo.app"
+        ],
+        "serviceId": "forms"
+      }
+    ]
+  },
+  "insights": {
+    "id": "insights",
+    "appDir": "TopoloInsights",
+    "name": "topolo-insights",
+    "packageName": "topolo-insights",
+    "productionUrl": "https://insights.topolo.app",
+    "services": [
+      "insights"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-insights",
+        "kind": "worker",
+        "apiUrl": "https://insights.topolo.app",
+        "domains": [
+          "insights.topolo.app"
+        ],
+        "routes": [
+          "insights.topolo.app"
+        ],
+        "serviceId": "insights"
+      }
+    ]
+  },
+  "inventory": {
+    "id": "inventory",
+    "appDir": "TopoloInventory",
+    "name": "topolo-inventory",
+    "packageName": "topolo-inventory",
+    "productionUrl": "https://inventory.topolo.app",
+    "services": [
+      "inventory"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-inventory",
+        "kind": "worker",
+        "apiUrl": "https://inventory.topolo.app",
+        "domains": [
+          "inventory.topolo.app"
+        ],
+        "routes": [
+          "inventory.topolo.app"
+        ],
+        "serviceId": "inventory"
+      }
+    ]
+  },
   "learn": {
     "id": "learn",
     "appDir": "TopoloLearn",
@@ -707,7 +882,9 @@ var APPLICATIONS = {
         "kind": "worker",
         "apiUrl": null,
         "domains": [
-          "one.topolo.io"
+          "one.topolo.io",
+          "topolo.io",
+          "www.topolo.io"
         ],
         "routes": [],
         "serviceId": null
@@ -744,6 +921,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "people": {
+    "id": "people",
+    "appDir": "TopoloPeople",
+    "name": "topolo-people",
+    "packageName": "topolo-people",
+    "productionUrl": "https://people.topolo.app",
+    "services": [
+      "people"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-people",
+        "kind": "worker",
+        "apiUrl": "https://people.topolo.app",
+        "domains": [
+          "people.topolo.app"
+        ],
+        "routes": [
+          "people.topolo.app"
+        ],
+        "serviceId": "people"
+      }
+    ]
+  },
   "quro": {
     "id": "quro",
     "appDir": "TopoloQuro",
@@ -815,6 +1016,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "sign": {
+    "id": "sign",
+    "appDir": "TopoloSign",
+    "name": "topolo-sign",
+    "packageName": "topolo-sign",
+    "productionUrl": "https://sign.topolo.app",
+    "services": [
+      "sign"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-sign",
+        "kind": "worker",
+        "apiUrl": "https://sign.topolo.app",
+        "domains": [
+          "sign.topolo.app"
+        ],
+        "routes": [
+          "sign.topolo.app"
+        ],
+        "serviceId": "sign"
+      }
+    ]
+  },
   "social_studio": {
     "id": "social_studio",
     "appDir": "TopoloSocialStudio",
@@ -911,6 +1136,54 @@ var APPLICATIONS = {
       }
     ]
   },
+  "survey": {
+    "id": "survey",
+    "appDir": "TopoloSurvey",
+    "name": "topolo-survey",
+    "packageName": "topolo-survey",
+    "productionUrl": "https://survey.topolo.app",
+    "services": [
+      "survey"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-survey",
+        "kind": "worker",
+        "apiUrl": "https://survey.topolo.app",
+        "domains": [
+          "survey.topolo.app"
+        ],
+        "routes": [
+          "survey.topolo.app"
+        ],
+        "serviceId": "survey"
+      }
+    ]
+  },
+  "voice": {
+    "id": "voice",
+    "appDir": "TopoloVoice",
+    "name": "topolo-voice",
+    "packageName": "topolo-voice",
+    "productionUrl": "https://voice.topolo.app",
+    "services": [
+      "voice"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-voice",
+        "kind": "worker",
+        "apiUrl": "https://voice.topolo.app",
+        "domains": [
+          "voice.topolo.app"
+        ],
+        "routes": [
+          "voice.topolo.app"
+        ],
+        "serviceId": "voice"
+      }
+    ]
+  },
   "web": {
     "id": "web",
     "appDir": "TopoloWeb",
@@ -956,7 +1229,7 @@ var APPLICATIONS = {
 };
 
 // src/application-requirements.ts
-var APPLICATION_REQUIREMENTS_VERSION = "2026-04-22.1";
+var APPLICATION_REQUIREMENTS_VERSION = "2026-04-25.1";
 var APPLICATION_REQUIREMENTS = [
   {
     id: "platform-metadata",
@@ -1088,6 +1361,22 @@ var APPLICATION_REQUIREMENTS = [
       "Keep command output JSON-stable for agents and human-readable with --no-json"
     ]
   },
+  {
+    id: "native-dashboard-widget",
+    title: "Expose a native dashboard widget contract",
+    summary: "Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.",
+    appliesTo: ["api"],
+    evidence: [
+      "The app-owned API exposes GET /api/widget",
+      "The endpoint returns TopoloWidgetApiResponse from @topolo/sdk",
+      "The endpoint derives organization/user context from the app auth boundary"
+    ],
+    implementation: [
+      "Import createTopoloWidgetResponse from @topolo/sdk in the app backend",
+      "Return native app metrics or action widgets instead of generic launch-card fallbacks",
+      "Add a route-level test that validates the response with validateTopoloWidgetResponse"
+    ]
+  },
   {
     id: "observability-and-audit",
     title: "Emit platform audit and debugging signals",
@@ -1123,9 +1412,8 @@ var APPLICATION_REQUIREMENTS = [
 ];
 function applicationRequirementScopes(application) {
   const scopes = /* @__PURE__ */ new Set(["all"]);
-  const deployTargets = application.deployTargets;
-  const hasBrowserSurface = Boolean(application.productionUrl) || deployTargets.some((target) => target.kind === "pages");
-  const hasApiSurface = application.services.length > 0 || deployTargets.some((target) => Boolean(target.apiUrl));
+  const hasBrowserSurface = Boolean(application.productionUrl) || application.deployTargets.some((target) => target.kind === "pages");
+  const hasApiSurface = application.services.length > 0 || application.deployTargets.some((target) => Boolean(target.apiUrl));
   if (hasBrowserSurface) scopes.add("browser");
   if (hasApiSurface) scopes.add("api");
   if (application.id === "cli" || application.id === "mcp" || application.id === "cloudcontrol") {
@@ -1260,6 +1548,13 @@ function evaluateRequirement(application, requirement) {
       }
       return finding(requirement, "missing", "No SDK service or tooling surface is registered.", evidence);
     }
+    case "native-dashboard-widget":
+      return finding(
+        requirement,
+        "needs_review",
+        "Catalog metadata cannot verify app-owned /api/widget implementation details.",
+        evidence
+      );
     case "observability-and-audit":
       return finding(
         requirement,
@@ -1313,11 +1608,10 @@ function statusRank(status) {
 // src/services.ts
 var DEFAULT_SERVICE_URLS = SERVICES;
 function resolveServiceUrl(service, overrides) {
-  var _a;
-  const override = overrides == null ? void 0 : overrides[service];
+  const override = overrides?.[service];
   if (override) return override;
   const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, "_").toUpperCase()}`;
-  const envValue = typeof process !== "undefined" ? (_a = process.env) == null ? void 0 : _a[envKey] : void 0;
+  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
   if (envValue) return envValue;
   return DEFAULT_SERVICE_URLS[service];
 }
@@ -1333,9 +1627,8 @@ var TopoloClient = class {
   fetchImpl;
   debug;
   constructor(options) {
-    var _a;
     if (!options.credential) throw new TopoloAuthError("credential is required");
-    if (!((_a = options.agent) == null ? void 0 : _a.clientName)) throw new TopoloAuthError("agent.clientName is required");
+    if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
     this.credential = options.credential;
     this.agent = options.agent;
     this.serviceUrls = options.serviceUrls;
@@ -1525,7 +1818,6 @@ var CrmModule = class {
   }
   client;
   async listContacts(options = {}) {
-    var _a, _b, _c;
     const res = await this.client.request({
       service: "crm",
       path: "/api/contacts",
@@ -1535,12 +1827,12 @@ var CrmModule = class {
         pageSize: options.pageSize
       }
     });
-    const rows = Array.isArray(res == null ? void 0 : res.contacts) ? res.contacts : Array.isArray(res == null ? void 0 : res.data) ? res.data : [];
+    const rows = Array.isArray(res?.contacts) ? res.contacts : Array.isArray(res?.data) ? res.data : [];
     return {
       contacts: rows.map(toSummary),
-      total: (res == null ? void 0 : res.total) ?? ((_a = res == null ? void 0 : res.pagination) == null ? void 0 : _a.total) ?? rows.length,
-      page: (res == null ? void 0 : res.page) ?? ((_b = res == null ? void 0 : res.pagination) == null ? void 0 : _b.page) ?? options.page ?? 1,
-      pageSize: (res == null ? void 0 : res.pageSize) ?? ((_c = res == null ? void 0 : res.pagination) == null ? void 0 : _c.pageSize) ?? options.pageSize ?? rows.length
+      total: res?.total ?? res?.pagination?.total ?? rows.length,
+      page: res?.page ?? res?.pagination?.page ?? options.page ?? 1,
+      pageSize: res?.pageSize ?? res?.pagination?.pageSize ?? options.pageSize ?? rows.length
     };
   }
   async getContact(contactId) {
@@ -1661,6 +1953,126 @@ var TopoloOAuth = class {
   }
 };
 
+// src/widgets.ts
+var TOPOLO_WIDGET_ENDPOINT = "/api/widget";
+var TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 6e4;
+function defineTopoloStatsWidget(widget) {
+  return { ...widget, type: "stats" };
+}
+function defineTopoloRecentActivityWidget(widget) {
+  return { ...widget, type: "recent-activity" };
+}
+function defineTopoloQuickActionsWidget(widget) {
+  return { ...widget, type: "quick-actions" };
+}
+function defineTopoloNotificationsWidget(widget) {
+  return { ...widget, type: "notifications" };
+}
+function defineTopoloChartWidget(widget) {
+  return { ...widget, type: "chart" };
+}
+function createTopoloWidgetResponse({
+  serviceId,
+  serviceName,
+  widgets,
+  now
+}) {
+  const lastUpdated = toIsoTimestamp(now);
+  return {
+    success: true,
+    widgets: widgets.map((widget) => ({
+      ...widget,
+      serviceId: widget.serviceId?.trim() || serviceId,
+      serviceName: widget.serviceName?.trim() || serviceName,
+      lastUpdated: widget.lastUpdated?.trim() || lastUpdated
+    }))
+  };
+}
+function createTopoloWidgetError(error) {
+  return {
+    success: false,
+    widgets: [],
+    error
+  };
+}
+function validateTopoloWidgetResponse(response) {
+  const errors = [];
+  if (!isRecord(response)) {
+    return { ok: false, errors: ["response must be an object"] };
+  }
+  if (typeof response.success !== "boolean") {
+    errors.push("success must be a boolean");
+  }
+  if (!Array.isArray(response.widgets)) {
+    errors.push("widgets must be an array");
+    return { ok: errors.length === 0, errors };
+  }
+  response.widgets.forEach((widget, index) => {
+    validateWidget(widget, `widgets[${index}]`, errors);
+  });
+  if (response.success === false && response.error !== void 0 && typeof response.error !== "string") {
+    errors.push("error must be a string when provided");
+  }
+  return { ok: errors.length === 0, errors };
+}
+function validateWidget(widget, path, errors) {
+  if (!isRecord(widget)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  validateNonEmptyString(widget.serviceId, `${path}.serviceId`, errors);
+  validateNonEmptyString(widget.serviceName, `${path}.serviceName`, errors);
+  validateNonEmptyString(widget.lastUpdated, `${path}.lastUpdated`, errors);
+  switch (widget.type) {
+    case "stats":
+      validateArray(widget.stats, `${path}.stats`, errors);
+      break;
+    case "recent-activity":
+      validateArray(widget.activities, `${path}.activities`, errors);
+      break;
+    case "quick-actions":
+      validateArray(widget.actions, `${path}.actions`, errors);
+      break;
+    case "notifications":
+      validateArray(widget.notifications, `${path}.notifications`, errors);
+      if (typeof widget.unreadCount !== "number") {
+        errors.push(`${path}.unreadCount must be a number`);
+      }
+      break;
+    case "chart":
+      validateNonEmptyString(widget.chartType, `${path}.chartType`, errors);
+      validateNonEmptyString(widget.title, `${path}.title`, errors);
+      if (!isRecord(widget.data)) {
+        errors.push(`${path}.data must be an object`);
+      } else {
+        validateArray(widget.data.labels, `${path}.data.labels`, errors);
+        validateArray(widget.data.values, `${path}.data.values`, errors);
+      }
+      break;
+    default:
+      errors.push(`${path}.type must be a supported Topolo widget type`);
+  }
+}
+function validateNonEmptyString(value, path, errors) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    errors.push(`${path} must be a non-empty string`);
+  }
+}
+function validateArray(value, path, errors) {
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toIsoTimestamp(input) {
+  if (input instanceof Date) {
+    return input.toISOString();
+  }
+  return input ?? (/* @__PURE__ */ new Date()).toISOString();
+}
+
 // src/index.ts
 function createTopolo(options) {
   const client = new TopoloClient(options);
@@ -1679,6 +2091,8 @@ function createTopolo(options) {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
   TopoloHttpError,
@@ -1689,6 +2103,14 @@ function createTopolo(options) {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   createTopolo,
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   requirementsForApplication,
-  resolveServiceUrl
+  resolveServiceUrl,
+  validateTopoloWidgetResponse
 });