@topolo/sdk 0.2.4 → 0.2.6

package/dist/index.js

@@ -60,14 +60,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",
@@ -75,16 +81,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
@@ -159,6 +179,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",
@@ -360,6 +404,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",
@@ -436,6 +504,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",
@@ -464,6 +556,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",
@@ -664,7 +828,9 @@ var APPLICATIONS = {
         "kind": "worker",
         "apiUrl": null,
         "domains": [
-          "one.topolo.io"
+          "one.topolo.io",
+          "topolo.io",
+          "www.topolo.io"
         ],
         "routes": [],
         "serviceId": null
@@ -701,6 +867,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",
@@ -772,6 +962,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",
@@ -868,6 +1082,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",
@@ -913,7 +1175,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",
@@ -1045,6 +1307,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",
@@ -1080,9 +1358,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") {
@@ -1217,6 +1494,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,
@@ -1270,11 +1554,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];
 }
@@ -1290,9 +1573,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;
@@ -1482,7 +1764,6 @@ var CrmModule = class {
   }
   client;
   async listContacts(options = {}) {
-    var _a, _b, _c;
     const res = await this.client.request({
       service: "crm",
       path: "/api/contacts",
@@ -1492,12 +1773,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) {
@@ -1618,6 +1899,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);
@@ -1635,6 +2036,8 @@ export {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
   TopoloHttpError,
@@ -1645,6 +2048,14 @@ export {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   createTopolo,
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   requirementsForApplication,
-  resolveServiceUrl
+  resolveServiceUrl,
+  validateTopoloWidgetResponse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",

package/src/application-requirements.ts

@@ -1,11 +1,10 @@
 import {
   APPLICATIONS,
   type ApplicationCatalogEntry,
-  type ApplicationDeployTarget,
   type ApplicationId,
 } from './applications.generated.js';
 
-export const APPLICATION_REQUIREMENTS_VERSION = '2026-04-22.1';
+export const APPLICATION_REQUIREMENTS_VERSION = '2026-04-25.1';
 
 export type ApplicationRequirementScope =
   | 'all'
@@ -206,6 +205,23 @@ export const 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',
@@ -246,12 +262,11 @@ export function applicationRequirementScopes(
   application: ApplicationCatalogEntry,
 ): ApplicationRequirementScope[] {
   const scopes = new Set<ApplicationRequirementScope>(['all']);
-  const deployTargets = application.deployTargets as readonly ApplicationDeployTarget[];
   const hasBrowserSurface =
-    Boolean(application.productionUrl) || deployTargets.some((target) => target.kind === 'pages');
+    Boolean(application.productionUrl) || application.deployTargets.some((target) => target.kind === 'pages');
   const hasApiSurface =
     application.services.length > 0 ||
-    deployTargets.some((target) => Boolean(target.apiUrl));
+    application.deployTargets.some((target) => Boolean(target.apiUrl));
 
   if (hasBrowserSurface) scopes.add('browser');
   if (hasApiSurface) scopes.add('api');
@@ -413,6 +428,13 @@ function evaluateRequirement(
       }
       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,