@topolo/sdk 0.4.10 → 0.6.0

package/src/services.ts

@@ -1,21 +1,21 @@
 /**
- * Service registry — base URLs for every Topolo platform service.
+ * App API registry — base URLs for callable Topolo platform APIs.
  *
  * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
- * `SERVICES` map is regenerated from those files via
+ * `APP_API_URLS` map is regenerated from those files via
  * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
  *
  * Any entry can be overridden per-call via `TopoloClient` options, or globally
- * via env vars like `TOPOLO_SERVICE_URL_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
- * (dots in service IDs become underscores in env vars).
+ * via env vars like `TOPOLO_APP_URL_MAIL` or `TOPOLO_APP_URL_WEB_API`
+ * (dots in app API keys become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
 import {
-  SERVICES,
-  type ServiceId,
+  APP_API_URLS,
+  type AppApiId,
 } from './services.generated.js';
 import {
   APPLICATIONS,
@@ -40,15 +40,15 @@ export {
   type ApplicationRequirementsAuditReport,
 } from './application-requirements.js';
 
-export { SERVICES };
-export type { ServiceId };
+export { APP_API_URLS };
+export type { AppApiId };
 export { APPLICATIONS };
 export type { ApplicationCatalogEntry, ApplicationDeployTarget, ApplicationId };
 
-export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = SERVICES;
+export const DEFAULT_APP_URLS: Record<AppApiId, string> = APP_API_URLS;
 
 export interface ServiceCatalogUrlEntry {
-  serviceId?: string | null;
+  appId?: string | null;
   slug?: string | null;
   name?: string | null;
   apiBaseUrl?: string | null;
@@ -61,7 +61,7 @@ export function resolveCatalogServiceUrl(
   entry: ServiceCatalogUrlEntry,
   options: {
     serviceKey?: string;
-    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+    overrides?: Record<string, string> | Partial<Record<AppApiId, string>>;
   } = {},
 ): string | null {
   const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
@@ -75,17 +75,17 @@ export function resolveCatalogServiceUrl(
 }
 
 export function resolveServiceUrl(
-  service: ServiceId,
-  overrides?: Partial<Record<ServiceId, string>>,
+  service: AppApiId,
+  overrides?: Partial<Record<AppApiId, string>>,
 ): string {
   const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
 
-  return DEFAULT_SERVICE_URLS[service];
+  return DEFAULT_APP_URLS[service];
 }
 
 function catalogServiceKeyCandidates(entry: ServiceCatalogUrlEntry, preferred?: string): string[] {
-  const values = [preferred, entry.slug, entry.name, entry.serviceId].filter(
+  const values = [preferred, entry.slug, entry.name, entry.appId].filter(
     (value): value is string => typeof value === 'string' && value.trim().length > 0,
   );
   const keys = new Set<string>();
@@ -110,19 +110,19 @@ function serviceKeyCandidates(value: string): string[] {
 
 function resolveServiceUrlOverride(
   keys: string[],
-  overrides?: Record<string, string> | Partial<Record<ServiceId, string>>,
+  overrides?: Record<string, string> | Partial<Record<AppApiId, string>>,
 ): string | null {
   for (const key of keys) {
-    const direct = overrides?.[key as ServiceId];
+    const direct = overrides?.[key as AppApiId];
     if (direct) return direct;
 
     const envStyleKey = key.replace(/\./g, '_');
-    const envStyle = overrides?.[envStyleKey as ServiceId];
+    const envStyle = overrides?.[envStyleKey as AppApiId];
     if (envStyle) return envStyle;
   }
 
   for (const key of keys) {
-    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, '_').toUpperCase()}`;
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, '_').toUpperCase()}`;
     const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
     if (envValue) return envValue;
   }

package/src/widgets.test.ts

@@ -13,7 +13,7 @@ import {
 } from "./widgets.js";
 
 const BASE = {
-  serviceId: "service_x",
+  appId: "service_x",
   serviceName: "X",
   lastUpdated: "2026-04-25T00:00:00.000Z",
   snapshot: { summary: "A summary that is long enough to read." },
@@ -27,7 +27,7 @@ describe("Topolo widget contract", () => {
 
   it("stamps service metadata and timestamp onto widget drafts", () => {
     const response = createTopoloWidgetResponse({
-      serviceId: "service_bytes",
+      appId: "service_bytes",
       serviceName: "Bytes",
       now: "2026-04-25T00:00:00.000Z",
       widgets: [
@@ -45,7 +45,7 @@ describe("Topolo widget contract", () => {
       success: true,
       widgets: [
         {
-          serviceId: "service_bytes",
+          appId: "service_bytes",
           serviceName: "Bytes",
           lastUpdated: "2026-04-25T00:00:00.000Z",
           type: "stats",
@@ -60,12 +60,12 @@ describe("Topolo widget contract", () => {
 
   it("keeps explicit widget metadata when an app needs multiple service cards", () => {
     const response = createTopoloWidgetResponse({
-      serviceId: "service_platform",
+      appId: "service_platform",
       serviceName: "Platform",
       now: "2026-04-25T00:00:00.000Z",
       widgets: [
         {
-          serviceId: "service_crm",
+          appId: "service_crm",
           serviceName: "CRM",
           lastUpdated: "2026-04-24T23:00:00.000Z",
           type: "stats",
@@ -78,7 +78,7 @@ describe("Topolo widget contract", () => {
     });
 
     expect(response.widgets[0]).toMatchObject({
-      serviceId: "service_crm",
+      appId: "service_crm",
       serviceName: "CRM",
       lastUpdated: "2026-04-24T23:00:00.000Z",
     });
@@ -94,7 +94,7 @@ describe("Topolo widget contract", () => {
 
   it("validates a compliant response", () => {
     const response = createTopoloWidgetResponse({
-      serviceId: "service_crm",
+      appId: "service_crm",
       serviceName: "CRM",
       now: "2026-04-25T00:00:00.000Z",
       widgets: [
@@ -126,7 +126,7 @@ describe("Topolo widget contract", () => {
 
   it("keeps required snapshot metadata for configurable TopoloOne datapoints", () => {
     const response = createTopoloWidgetResponse({
-      serviceId: "service_admin",
+      appId: "service_admin",
       serviceName: "Admin",
       now: "2026-04-28T00:00:00.000Z",
       widgets: [
@@ -172,7 +172,7 @@ describe("Topolo widget contract", () => {
       success: true,
       widgets: [
         {
-          serviceId: "",
+          appId: "",
           serviceName: "Bad App",
           lastUpdated: "",
           type: "calendar",
@@ -182,7 +182,7 @@ describe("Topolo widget contract", () => {
 
     expect(result.ok).toBe(false);
     expect(result.errors).toEqual([
-      "widgets[0].serviceId must be a non-empty string",
+      "widgets[0].appId must be a non-empty string",
       "widgets[0].lastUpdated must be a non-empty string",
       "widgets[0].snapshot must be an object",
       "widgets[0].type must be a supported Topolo widget type",
@@ -213,7 +213,7 @@ describe("Topolo widget contract", () => {
 
   it("derives lastUpdated from a Date instance passed as now", () => {
     const response = createTopoloWidgetResponse({
-      serviceId: "service_x",
+      appId: "service_x",
       serviceName: "X",
       now: new Date("2026-05-01T12:00:00.000Z"),
       widgets: [
@@ -230,7 +230,7 @@ describe("Topolo widget contract", () => {
   it("generates a current timestamp when now is omitted", () => {
     const before = Date.now();
     const response = createTopoloWidgetResponse({
-      serviceId: "service_x",
+      appId: "service_x",
       serviceName: "X",
       widgets: [
         {
@@ -362,7 +362,7 @@ describe("Topolo widget contract", () => {
       success: true,
       widgets: [
         {
-          serviceId: "s",
+          appId: "s",
           serviceName: "n",
           lastUpdated: "2026-04-25T00:00:00.000Z",
           type: "stats",
@@ -398,7 +398,7 @@ describe("Topolo widget contract", () => {
       success: true,
       widgets: [
         {
-          serviceId: "service_bad",
+          appId: "service_bad",
           serviceName: "Bad App",
           lastUpdated: "2026-04-25T00:00:00.000Z",
           type: "stats",

package/src/widgets.ts

@@ -9,7 +9,7 @@ export type TopoloWidgetType =
   | "chart";
 
 export interface TopoloWidgetBase {
-  serviceId: string;
+  appId: string;
   serviceName: string;
   serviceIcon?: string;
   type: TopoloWidgetType;
@@ -114,9 +114,9 @@ export type TopoloWidget =
 
 type TopoloWidgetWithOptionalMetadata<T extends TopoloWidget> = Omit<
   T,
-  "serviceId" | "serviceName" | "lastUpdated"
+  "appId" | "serviceName" | "lastUpdated"
 > &
-  Partial<Pick<TopoloWidgetBase, "serviceId" | "serviceName" | "lastUpdated">>;
+  Partial<Pick<TopoloWidgetBase, "appId" | "serviceName" | "lastUpdated">>;
 
 export type TopoloWidgetDraft = TopoloWidget extends infer Widget
   ? Widget extends TopoloWidget
@@ -131,7 +131,7 @@ export interface TopoloWidgetApiResponse {
 }
 
 export interface TopoloWidgetResponseOptions {
-  serviceId: string;
+  appId: string;
   serviceName: string;
   widgets: TopoloWidgetDraft[];
   now?: Date | string;
@@ -143,7 +143,7 @@ export interface TopoloWidgetValidationResult {
 }
 
 export interface TopoloWidgetConfig {
-  serviceId: string;
+  appId: string;
   serviceName: string;
   baseUrl: string;
   widgetEndpoint: string;
@@ -182,7 +182,7 @@ export function defineTopoloChartWidget(
 }
 
 export function createTopoloWidgetResponse({
-  serviceId,
+  appId,
   serviceName,
   widgets,
   now,
@@ -193,7 +193,7 @@ export function createTopoloWidgetResponse({
     success: true,
     widgets: widgets.map((widget) => ({
       ...widget,
-      serviceId: widget.serviceId?.trim() || serviceId,
+      appId: widget.appId?.trim() || appId,
       serviceName: widget.serviceName?.trim() || serviceName,
       lastUpdated: widget.lastUpdated?.trim() || lastUpdated,
     })) as TopoloWidget[],
@@ -249,7 +249,7 @@ function validateWidget(widget: unknown, path: string, errors: string[]) {
     return;
   }
 
-  validateNonEmptyString(widget.serviceId, `${path}.serviceId`, errors);
+  validateNonEmptyString(widget.appId, `${path}.appId`, errors);
   validateNonEmptyString(widget.serviceName, `${path}.serviceName`, errors);
   validateNonEmptyString(widget.lastUpdated, `${path}.lastUpdated`, errors);
   validateSnapshotMetadata(widget.snapshot, `${path}.snapshot`, errors);