@topolo/sdk 0.2.12 → 0.4.0

package/README.md

@@ -103,7 +103,7 @@ their own `GET /api/widget` endpoint. The SDK owns the shared payload contract:
 import { createTopoloWidgetResponse } from '@topolo/sdk';
 
 return Response.json(createTopoloWidgetResponse({
-  serviceId: 'srv_topolo_example',
+  serviceId: '<runtime-service-id>',
   serviceName: 'Example',
   widgets: [
     {

package/dist/index.cjs

@@ -27,7 +27,6 @@ __export(index_exports, {
   DEFAULT_SERVICE_URLS: () => DEFAULT_SERVICE_URLS,
   IdentityModule: () => IdentityModule,
   P2PModule: () => P2PModule,
-  PLATFORM_SERVICE_IDS: () => PLATFORM_SERVICE_IDS,
   TOPOLO_WIDGET_ENDPOINT: () => TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS: () => TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError: () => TopoloAuthError,
@@ -146,41 +145,20 @@ var SERVICES = {
   p2p: "https://p2p.topolo.app",
   pay: "https://pay.topolo.app",
   people: "https://people.topolo.app",
+  pulse: "https://pulse.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://studio-api.topolo.app",
   socialize: "https://socialize-api.topolo.app",
+  spaces: "https://spaces.topolo.app",
   status: "https://status.topolo.app",
   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 = {
-  books: "srv_0g260hbN8oqv",
-  bugfix: "srv_kQ1t8qUSDgNs",
-  compose: "srv_aR3ETYmgygmd",
-  consent: "srv_8FIGR7Q7zP9r",
-  crm: "srv_iCwM4jGXcwlj",
-  customer_success: "srv_RWpOxkgZdZbH",
-  developers: "srv_NjDq9G9qyyjr",
-  director: "srv_wRCnLLbtvmVT",
-  flow: "srv_GBCuKkHhnRXv",
-  forms: "srv_UE7IcGe80J5o",
-  home: "srv_hE6HBldVzjth",
-  insights: "srv_DgbBMwWSIhmC",
-  inventory: "srv_hmvjbv3ZxDnh",
-  localize: "srv_Ze1g9OmXuZjF",
-  notify: "srv_9pRdkIjYyKX0",
-  p2p: "srv_4BzeLqH0wCve",
-  people: "srv_VDMBAonA5fKb",
-  sign: "srv_Bd8pRw5ZqRBT",
-  status: "srv_topolo_status",
-  survey: "srv_RCOi7CJkwf7R",
-  voice: "srv_BZANHkshGAK5"
-};
 
 // src/applications.generated.ts
 var APPLICATIONS = {
@@ -260,6 +238,24 @@ var APPLICATIONS = {
       }
     ]
   },
+  "backup": {
+    "id": "backup",
+    "appDir": "TopoloBackup",
+    "name": "topolo-backup",
+    "packageName": "topolo-backup",
+    "productionUrl": null,
+    "services": [],
+    "deployTargets": [
+      {
+        "name": "topolo-backup",
+        "kind": "worker",
+        "apiUrl": null,
+        "domains": [],
+        "routes": [],
+        "serviceId": null
+      }
+    ]
+  },
   "books": {
     "id": "books",
     "appDir": "TopoloBooks",
@@ -410,15 +406,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "cli": {
-    "id": "cli",
-    "appDir": "TopoloCli",
-    "name": "@topolo/cli",
-    "packageName": "@topolo/cli",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": []
-  },
   "cloudcontrol": {
     "id": "cloudcontrol",
     "appDir": "TopoloCloudControl",
@@ -584,24 +571,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "d1_backup": {
-    "id": "d1_backup",
-    "appDir": "TopoloD1Backup",
-    "name": "topolo-d1-backup",
-    "packageName": "topolo-d1-backup",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": [
-      {
-        "name": "topolo-d1-backup",
-        "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
-        "routes": [],
-        "serviceId": null
-      }
-    ]
-  },
   "developers": {
     "id": "developers",
     "appDir": "TopoloDevelopers",
@@ -944,15 +913,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "mcp": {
-    "id": "mcp",
-    "appDir": "TopoloMCP",
-    "name": "@topolo/mcp",
-    "packageName": "@topolo/mcp",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": []
-  },
   "mdm": {
     "id": "mdm",
     "appDir": "TopoloMDM",
@@ -1087,7 +1047,7 @@ var APPLICATIONS = {
   "one": {
     "id": "one",
     "appDir": "TopoloOne",
-    "name": "topolo-oneclick-sso",
+    "name": "TopoloOne",
     "packageName": "topolo-oneclick-sso",
     "productionUrl": "https://one.topolo.app",
     "services": [
@@ -1208,9 +1168,24 @@ var APPLICATIONS = {
     "appDir": "TopoloPulse",
     "name": "topolo-pulse",
     "packageName": "topolo-pulse",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": []
+    "productionUrl": "https://pulse.topolo.app",
+    "services": [
+      "pulse"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-pulse",
+        "kind": "worker",
+        "apiUrl": "https://pulse.topolo.app",
+        "domains": [
+          "pulse.topolo.app"
+        ],
+        "routes": [
+          "pulse.topolo.app"
+        ],
+        "serviceId": "pulse"
+      }
+    ]
   },
   "quro": {
     "id": "quro",
@@ -1393,6 +1368,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "spaces": {
+    "id": "spaces",
+    "appDir": "TopoloSpaces",
+    "name": "topolo-spaces",
+    "packageName": "@topolo/spaces",
+    "productionUrl": "https://spaces.topolo.app",
+    "services": [
+      "spaces"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-spaces",
+        "kind": "worker",
+        "apiUrl": "https://spaces.topolo.app",
+        "domains": [
+          "spaces.topolo.app"
+        ],
+        "routes": [
+          "spaces.topolo.app"
+        ],
+        "serviceId": "spaces"
+      }
+    ]
+  },
   "status": {
     "id": "status",
     "appDir": "TopoloStatus",
@@ -1574,12 +1573,12 @@ var APPLICATION_REQUIREMENTS = [
     summary: "Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.",
     appliesTo: ["browser", "api", "tooling", "agent_surface"],
     evidence: [
-      "@topolo/auth-client or @topolo/auth-middleware is used where applicable",
+      "@topolo/auth-client or @topolo-io/worker-runtime is used where applicable",
       "No public command, tool, or SDK method accepts orgId",
       "Service slug and Auth service registration are documented for protected services"
     ],
     implementation: [
-      "Use shared auth packages instead of copying token parsing or browser storage flows",
+      "Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows",
       "Derive organization from the credential on every request",
       "Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract"
     ]
@@ -1719,14 +1718,15 @@ var APPLICATION_REQUIREMENTS = [
 ];
 function applicationRequirementScopes(application) {
   const scopes = /* @__PURE__ */ new Set(["all"]);
+  const appId = application.id;
   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") {
+  if (appId === "cli" || appId === "mcp" || appId === "cloudcontrol") {
     scopes.add("tooling");
   }
-  if (application.id === "cli" || application.id === "mcp" || hasApiSurface) {
+  if (appId === "cli" || appId === "mcp" || hasApiSurface) {
     scopes.add("agent_surface");
   }
   return Array.from(scopes);
@@ -1845,12 +1845,13 @@ function evaluateRequirement(application, requirement) {
       return finding(requirement, "met", "CloudControl deploy target metadata is present.", evidence);
     }
     case "agent-and-operator-surfaces": {
+      const appId = application.id;
       if (application.services.length > 0) {
         evidence.push(`services=${application.services.join(",")}`);
         return finding(requirement, "partial", "SDK service discovery exists; typed SDK/CLI/MCP workflow coverage should be checked as APIs stabilize.", evidence);
       }
-      if (application.id === "cli" || application.id === "mcp" || application.id === "cloudcontrol") {
-        evidence.push(`tooling=${application.id}`);
+      if (appId === "cli" || appId === "mcp" || appId === "cloudcontrol") {
+        evidence.push(`tooling=${appId}`);
         return finding(requirement, "met", "This application is itself an agent/operator surface.", evidence);
       }
       return finding(requirement, "missing", "No SDK service or tooling surface is registered.", evidence);
@@ -1925,20 +1926,38 @@ function resolveServiceUrl(service, overrides) {
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
-var TopoloClient = class {
+var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
+var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
+var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
+  serviceIds;
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
   debug;
+  /**
+   * Process-wide cache for slug → service-id lookups. Keyed by
+   * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+   * the same Auth share, but staging vs prod don't poison each other.
+   * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+   */
+  static serviceIdCache = /* @__PURE__ */ new Map();
+  /**
+   * Drop the slug→service-id cache. Test-only — production callers should
+   * let the 5-minute TTL expire naturally.
+   */
+  static clearServiceIdCache() {
+    _TopoloClient.serviceIdCache.clear();
+  }
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential 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;
+    this.serviceIds = options.serviceIds;
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
@@ -1973,7 +1992,7 @@ var TopoloClient = class {
     const headers = new Headers();
     headers.set("Accept", "application/json");
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
-    const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
+    const platformServiceId = resolveConfiguredServiceId(opts.service, this.serviceIds);
     if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
     applyAuthHeaders(headers, this.credential);
     const requestId = generateRequestId();
@@ -2047,6 +2066,115 @@ var TopoloClient = class {
     });
     return parsed;
   }
+  /**
+   * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
+   *
+   * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
+   * results (404) are cached for 60s so a typo doesn't hot-loop the
+   * resolver. Returns null when the slug isn't registered — callers decide
+   * whether to throw.
+   *
+   * No credential is sent: the endpoint is public (slugs aren't secret).
+   * This keeps the resolver usable during early bootstrap before a caller
+   * has acquired an access token.
+   */
+  async getServiceIdBySlug(slug) {
+    if (typeof slug !== "string") return null;
+    const normalized = slug.trim().toLowerCase();
+    if (!normalized) return null;
+    const configuredServiceId = resolveConfiguredServiceId(normalized, this.serviceIds);
+    if (configuredServiceId) return configuredServiceId;
+    const authBase = resolveServiceUrl("auth", this.serviceUrls);
+    const cacheKey = `${authBase}|${normalized}`;
+    const now = Date.now();
+    const cached = _TopoloClient.serviceIdCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+      return cached.value;
+    }
+    const url = new URL(
+      `/api/services/by-slug/${encodeURIComponent(normalized)}`,
+      authBase.endsWith("/") ? authBase : `${authBase}/`
+    ).toString();
+    let res;
+    try {
+      res = await this.fetchImpl(url, {
+        method: "GET",
+        headers: { Accept: "application/json" }
+      });
+    } catch {
+      return null;
+    }
+    if (res.status === 404) {
+      _TopoloClient.serviceIdCache.set(cacheKey, {
+        value: null,
+        expiresAt: now + NEGATIVE_CACHE_TTL_MS
+      });
+      return null;
+    }
+    if (!res.ok) {
+      return null;
+    }
+    const body = await res.json().catch(() => null);
+    const serviceId = body?.data?.service_id;
+    const value = typeof serviceId === "string" && serviceId ? serviceId : null;
+    _TopoloClient.serviceIdCache.set(cacheKey, {
+      value,
+      expiresAt: now + POSITIVE_CACHE_TTL_MS
+    });
+    return value;
+  }
+  /**
+   * List the platform service catalog from the live registry
+   * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
+   * caller's credential is attached, so an authenticated caller in an
+   * entitled org also receives the `developer_only` services its role
+   * permits; an unauthenticated/agent caller receives `active` only.
+   *
+   * Resilient: on any network/HTTP failure this falls back to the
+   * build-time generated `APPLICATIONS` snapshot so offline/degraded
+   * callers still get a usable (if static) catalog. The live result is
+   * authoritative; the snapshot is a floor, not a cap.
+   */
+  async listServices() {
+    try {
+      const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
+      const raw = res.data?.services ?? res.services;
+      if (Array.isArray(raw) && raw.length > 0) {
+        const entries = [];
+        for (const item of raw) {
+          const s = item;
+          const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
+          if (!serviceId) continue;
+          entries.push({
+            serviceId,
+            slug: typeof s.app_slug === "string" ? s.app_slug : null,
+            name: typeof s.name === "string" ? s.name : null,
+            description: typeof s.description === "string" ? s.description : null,
+            baseUrl: typeof s.base_url === "string" ? s.base_url : null,
+            status: typeof s.status === "string" ? s.status : null,
+            surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
+            launchable: s.launchable === true
+          });
+        }
+        if (entries.length > 0) return entries;
+      }
+    } catch {
+    }
+    return this.generatedCatalogFallback();
+  }
+  generatedCatalogFallback() {
+    const apps = Object.values(APPLICATIONS);
+    return apps.map((app) => ({
+      serviceId: app.id,
+      slug: app.id,
+      name: app.name ?? app.id,
+      description: null,
+      baseUrl: app.productionUrl ?? null,
+      status: "active",
+      surfaceKind: "application",
+      launchable: Boolean(app.productionUrl)
+    }));
+  }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
    * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -2083,6 +2211,26 @@ var TopoloClient = class {
     };
   }
 };
+function resolveConfiguredServiceId(slug, serviceIds) {
+  for (const serviceKey of serviceKeyCandidates(slug)) {
+    const configured = serviceIds?.[serviceKey];
+    if (typeof configured === "string" && configured.trim()) return configured.trim();
+    const envKey = `TOPOLO_SERVICE_ID_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (typeof envValue === "string" && envValue.trim()) return envValue.trim();
+  }
+  return null;
+}
+function serviceKeyCandidates(slug) {
+  const normalized = slug.trim().toLowerCase();
+  const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
+  return [.../* @__PURE__ */ new Set([
+    normalized,
+    normalized.replace(/-/g, "_"),
+    withoutTopolo,
+    withoutTopolo.replace(/-/g, "_")
+  ])];
+}
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
@@ -2649,7 +2797,6 @@ function createTopolo(options) {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   P2PModule,
-  PLATFORM_SERVICE_IDS,
   TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,