@topolo/sdk 0.9.9 → 0.10.0

package/README.md

@@ -97,22 +97,27 @@ traceable to a specific agent invocation.
 Agents should use the action catalog for app-specific operations so new
 services and actions become usable without an SDK, CLI, or MCP release.
 
-## Application catalog
-
-`APPLICATIONS` describes every Topolo platform application discovered from the
-PlatformApplications metadata, including Worker apps that do not expose a
-callable app API. `DEFAULT_APP_URLS` is the bundled callable API service
-snapshot generated from `topolo.cloudcontrol.json`.
-
-For agent-scale fleets, the bundle is packaging metadata, not an authorization
-source. `TopoloClient.listServices()` always calls the live TopoloAuth catalog
-with the current credential and returns only services that credential can use in
-its organization, including the granted permissions. `TopoloClient.request()`
-uses that credential-scoped catalog before routing any non-Auth service, so a
-bundled app ID is only a convenient alias after Auth confirms access.
-
-`listBundledServices()` is available for packaging/audit tooling that needs the
-generated snapshot. Do not use it to decide what an end user or agent may call.
+## Application directory (live registry)
+
+The platform scales to millions of constantly-changing applications, so the
+SDK ships NO compiled application map that decides behavior. The live
+credential-scoped registry is the source of truth:
+
+- `TopoloClient.searchServices()` / `getService()` enumerate and resolve
+  applications for the current credential.
+- `listApplicationDirectory(client)` walks the registry to exhaustion and
+  returns friendly ids derived from live slugs (`topolo-notify` → `notify`).
+- `resolveApplicationDirectoryEntry(client, application)` resolves one app by
+  id, slug, or name — including apps registered after this package was built.
+- `friendlyAppId(entry)` derives the display id from a live catalog entry.
+
+`DEFAULT_APP_URLS` now contains ONLY the `auth` and `developers` bootstrap
+seeds — the endpoints that must be reachable before the registry can be
+consulted. `APPLICATIONS` remains as a frozen static fallback snapshot used
+only when the registry is unreachable (it can enrich repo/deploy metadata for
+registry-confirmed apps, but never gates or rejects a registry-known app).
+`listBundledServices()` reads that snapshot and is deprecated for anything
+behavior-deciding.
 
 ## Action catalog
 

package/dist/index.cjs

@@ -37,9 +37,12 @@ __export(index_exports, {
   TopoloOAuth: () => TopoloOAuth,
   TopoloPermissionError: () => TopoloPermissionError,
   TopoloSdkError: () => TopoloSdkError,
+  WorkspacesModule: () => WorkspacesModule,
   actionContractCompleteness: () => actionContractCompleteness,
+  applicationEntryFromCatalog: () => applicationEntryFromCatalog,
   applicationRequirementScopes: () => applicationRequirementScopes,
   auditAllApplicationRequirements: () => auditAllApplicationRequirements,
+  auditApplicationEntries: () => auditApplicationEntries,
   auditApplicationRequirements: () => auditApplicationRequirements,
   createTopolo: () => createTopolo,
   createTopoloWidgetError: () => createTopoloWidgetError,
@@ -51,12 +54,17 @@ __export(index_exports, {
   defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   digestTopoloActionCatalog: () => digestTopoloActionCatalog,
   enrichActionContract: () => enrichActionContract,
+  formatDirectoryApplicationIds: () => formatDirectoryApplicationIds,
+  friendlyAppId: () => friendlyAppId,
+  listApplicationDirectory: () => listApplicationDirectory,
   parseTopoloActionUploadContract: () => parseTopoloActionUploadContract,
   prepareTopoloActionBase64UploadInput: () => prepareTopoloActionBase64UploadInput,
   prepareTopoloActionUploadInput: () => prepareTopoloActionUploadInput,
   requirementsForApplication: () => requirementsForApplication,
+  resolveApplicationDirectoryEntry: () => resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
+  staticApplicationDirectory: () => staticApplicationDirectory,
   validateTopoloActionInput: () => validateTopoloActionInput,
   validateTopoloWidgetResponse: () => validateTopoloWidgetResponse
 });
@@ -165,62 +173,13 @@ var TopoloHttpError = class extends TopoloSdkError {
   }
 };
 
-// src/services.generated.ts
+// src/bootstrap-services.ts
 var APP_API_URLS = {
-  agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
-  backup: "https://backup.topolo.app",
-  blog: "https://blog.topolo.app",
-  books: "https://books.topolo.app",
-  brand: "https://brand.topolo.app",
-  bugfix: "https://bugfix.topolo.app",
-  bytes: "https://bytes.topolo.app",
-  calendar: "https://calendar.topolo.app",
-  campaigns: "https://campaigns.topolo.app",
-  capacity: "https://capacity.topolo.app",
-  chat: "https://chat.topolo.app",
-  commerce: "https://commerce.topolo.app",
-  compose: "https://compose.topolo.app",
-  consent: "https://consent.topolo.app",
-  crm: "https://crm.topolo.app",
-  design: "https://design.topolo.app",
-  developers: "https://developers.topolo.app",
-  director: "https://director.topolo.app",
-  feed: "https://feed.topolo.app",
-  flow: "https://flow.topolo.app",
-  forecast: "https://forecast.topolo.app",
-  forms: "https://forms.topolo.app",
-  home: "https://home.topolo.app",
-  insights: "https://insights.topolo.app",
-  inventory: "https://inventory.topolo.app",
-  learn: "https://learn.topolo.app",
-  localize: "https://localize.topolo.app",
-  mail: "https://mail.topolo.app",
-  mdm: "https://mdm.topolo.app",
-  messages: "https://messages.topolo.app",
-  nexus: "https://nexus.topolo.app",
-  notify: "https://notify.topolo.app",
-  observability_watch: "https://observability-watch.topolo.app",
-  one: "https://www.topolo.app",
-  p2p: "https://p2p.topolo.app",
-  pay: "https://pay.topolo.app",
-  people: "https://people.topolo.app",
-  "quro.api": "https://api.ol0.me",
-  "quro.redirect": "https://ol0.me",
-  roadmapper: "https://roadmapper.topolo.app",
-  sign: "https://sign.topolo.app",
-  social_studio: "https://studio.topolo.app",
-  socialize: "https://socialize.topolo.app",
-  spaces: "https://spaces.topolo.app",
-  status: "https://status.topolo.app",
-  success: "https://success.topolo.app",
-  support: "https://support.topolo.app",
-  survey: "https://survey.topolo.app",
-  voice: "https://voice.topolo.app",
-  web: "https://web.topolo.app"
+  developers: "https://developers.topolo.app"
 };
 
-// src/applications.generated.ts
+// src/applications-fallback.ts
 var APPLICATIONS = {
   "admin": {
     "id": "admin",
@@ -1946,8 +1905,148 @@ var APPLICATIONS = {
   }
 };
 
+// src/application-directory.ts
+function friendlyAppId(entry) {
+  for (const value of [entry.slug, entry.name, entry.appId]) {
+    if (typeof value !== "string" || !value.trim()) continue;
+    const normalized = value.trim().toLowerCase().replace(/\s+/g, "-");
+    const withoutPrefix = normalized.replace(/^(?:app[_-])?topolo[-_]+/, "");
+    if (withoutPrefix) return withoutPrefix;
+  }
+  return entry.appId;
+}
+function idVariants(value) {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, "-");
+  return [.../* @__PURE__ */ new Set([
+    normalized,
+    normalized.replace(/-/g, "_"),
+    normalized.replace(/_/g, "-")
+  ])].filter(Boolean);
+}
+var STATIC_APPLICATIONS = APPLICATIONS;
+function staticApplicationForId(id) {
+  for (const variant of idVariants(id)) {
+    const entry = STATIC_APPLICATIONS[variant];
+    if (entry) return entry;
+  }
+  return null;
+}
+function applicationEntryFromCatalog(live) {
+  const id = friendlyAppId(live);
+  return {
+    id,
+    appDir: "-",
+    name: live.name ?? live.slug ?? live.appId,
+    packageName: null,
+    productionUrl: live.launchUrl ?? live.apiBaseUrl ?? null,
+    services: live.apiBaseUrl ? [id] : [],
+    deployTargets: []
+  };
+}
+var DIRECTORY_PAGE_LIMIT = 100;
+var DIRECTORY_MAX_PAGES = 100;
+function staticApplicationDirectory() {
+  const applications = Object.entries(STATIC_APPLICATIONS).map(([id, application]) => ({
+    id,
+    application,
+    source: "static",
+    live: null
+  })).sort((left, right) => left.id.localeCompare(right.id));
+  return { source: "static_fallback", applications };
+}
+function directoryApplicationFromLive(live) {
+  const id = friendlyAppId(live);
+  return {
+    id,
+    // Prefer the static snapshot's richer repo/deploy metadata when the live
+    // registry confirms the app; synthesize from the live entry otherwise.
+    application: staticApplicationForId(id) ?? applicationEntryFromCatalog(live),
+    source: "live",
+    live
+  };
+}
+async function listApplicationDirectory(client) {
+  if (!client) return staticApplicationDirectory();
+  let services;
+  try {
+    services = [];
+    let cursor;
+    for (let page = 0; page < DIRECTORY_MAX_PAGES; page += 1) {
+      const result = await client.searchServices({
+        ...cursor ? { cursor } : {},
+        limit: DIRECTORY_PAGE_LIMIT
+      });
+      services.push(...result.services);
+      if (!result.page.nextCursor) break;
+      cursor = result.page.nextCursor;
+    }
+  } catch {
+    return staticApplicationDirectory();
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const live of services) {
+    const entry = directoryApplicationFromLive(live);
+    if (!seen.has(entry.id)) seen.set(entry.id, entry);
+  }
+  return {
+    source: "live",
+    applications: [...seen.values()].sort((left, right) => left.id.localeCompare(right.id))
+  };
+}
+function matchesDirectoryApplication(app, needle) {
+  const candidates = new Set(idVariants(needle));
+  const keys = [
+    app.id,
+    app.application.id,
+    app.application.name,
+    app.live?.appId,
+    app.live?.slug,
+    app.live?.name
+  ];
+  for (const key of keys) {
+    if (typeof key !== "string" || !key.trim()) continue;
+    for (const variant of idVariants(key)) {
+      if (candidates.has(variant)) return true;
+    }
+    for (const variant of idVariants(friendlyAppId({ appId: key }))) {
+      if (candidates.has(variant)) return true;
+    }
+  }
+  return false;
+}
+function formatDirectoryApplicationIds(directory) {
+  const ids = directory.applications.map((app) => app.id).sort();
+  const preview = ids.slice(0, 50).join(", ");
+  const suffix = ids.length > 50 ? `, ... +${ids.length - 50} more` : "";
+  const label = directory.source === "live" ? "Applications available to this credential" : "Applications in the bundled static snapshot (live registry unreachable)";
+  return `${label}: ${preview}${suffix}`;
+}
+async function resolveApplicationDirectoryEntry(client, application) {
+  const needle = typeof application === "string" ? application.trim() : "";
+  if (!needle) {
+    throw new TopoloSdkError("unknown_application", "application is required");
+  }
+  if (client) {
+    let live = null;
+    try {
+      live = await client.getService(needle);
+    } catch {
+      live = null;
+    }
+    if (live) return directoryApplicationFromLive(live);
+  }
+  const directory = await listApplicationDirectory(client);
+  const match = directory.applications.find((app) => matchesDirectoryApplication(app, needle));
+  if (match) return match;
+  throw new TopoloSdkError(
+    "unknown_application",
+    `Unknown application "${application}". ${formatDirectoryApplicationIds(directory)}`
+  );
+}
+
 // src/application-requirements.ts
-var APPLICATION_REQUIREMENTS_VERSION = "2026-06-07.1";
+var STATIC_APPLICATIONS2 = APPLICATIONS;
+var APPLICATION_REQUIREMENTS_VERSION = "2026-08-11.1";
 var APPLICATION_REQUIREMENTS = [
   {
     id: "platform-metadata",
@@ -1957,10 +2056,10 @@ var APPLICATION_REQUIREMENTS = [
     evidence: [
       "topolo.cloudcontrol.json exists for every deployed app surface",
       "package.json names the package or app when the repo ships code",
-      "The SDK application catalog exposes the app through topolo apps and MCP discovery"
+      "The live platform registry exposes the app through topolo apps and MCP discovery"
     ],
     implementation: [
-      "Add the app to the SDK application catalog generator before exposing it to agents",
+      "Register the app in the live platform registry (Auth service catalog) before exposing it to agents",
       "Keep production URLs, Worker names, Pages projects, routes, domains, and bindings current in CloudControl metadata",
       "Do not leave a new Topolo* app directory without an explicit application ID"
     ]
@@ -2035,7 +2134,7 @@ var APPLICATION_REQUIREMENTS = [
     implementation: [
       "Add production Worker api_url metadata and sdk_app_id for every agent-callable API target",
       "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false",
-      "Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery",
+      "Expose stable app IDs through live catalog discovery",
       "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"
     ]
   },
@@ -2155,15 +2254,24 @@ function applicationRequirementScopes(application) {
   }
   return Array.from(scopes);
 }
+function fallbackApplication(id) {
+  const entry = STATIC_APPLICATIONS2[id];
+  if (!entry) {
+    throw new Error(
+      `Unknown application "${id}" in the static fallback snapshot. Resolve applications from the live registry (resolveApplicationDirectoryEntry) and pass the entry directly.`
+    );
+  }
+  return entry;
+}
 function requirementsForApplication(applicationOrId) {
-  const application = typeof applicationOrId === "string" ? APPLICATIONS[applicationOrId] : applicationOrId;
+  const application = typeof applicationOrId === "string" ? fallbackApplication(applicationOrId) : applicationOrId;
   const scopes = new Set(applicationRequirementScopes(application));
   return APPLICATION_REQUIREMENTS.filter(
     (requirement) => requirement.appliesTo.some((scope) => scopes.has(scope))
   );
 }
 function auditApplicationRequirements(applicationOrId) {
-  const application = typeof applicationOrId === "string" ? APPLICATIONS[applicationOrId] : applicationOrId;
+  const application = typeof applicationOrId === "string" ? fallbackApplication(applicationOrId) : applicationOrId;
   const scopes = applicationRequirementScopes(application);
   const findings = requirementsForApplication(application).map(
     (requirement) => evaluateRequirement(application, requirement)
@@ -2176,10 +2284,17 @@ function auditApplicationRequirements(applicationOrId) {
     findings
   };
 }
+function auditApplicationEntries(applications) {
+  return buildAuditReport(
+    applications.map((application) => auditApplicationRequirements(application))
+  );
+}
 function auditAllApplicationRequirements(applicationIds = Object.keys(APPLICATIONS).sort()) {
-  const applications = applicationIds.map(
-    (applicationId) => auditApplicationRequirements(applicationId)
+  return buildAuditReport(
+    applicationIds.map((applicationId) => auditApplicationRequirements(applicationId))
   );
+}
+function buildAuditReport(applications) {
   const migrationQueue = applications.flatMap(
     (audit) => audit.findings.filter((finding2) => finding2.status !== "met").map((finding2) => ({
       applicationId: audit.application.id,
@@ -3490,8 +3605,9 @@ var TopoloClient = class _TopoloClient {
     });
   }
   /**
-   * Bundled generated registry for tooling that audits platform packaging, not
-   * for deciding what the current credential may use.
+   * @deprecated Static fallback snapshot only. Use `searchServices()` (the
+   * live credential-scoped registry) for anything that decides behavior; this
+   * exists for offline packaging audits when the registry is unreachable.
    */
   listBundledServices() {
     const apps = Object.values(APPLICATIONS);
@@ -4287,6 +4403,67 @@ var IdentityModule = class {
   }
 };
 
+// src/modules/workspaces.ts
+var ACTIONS = {
+  list: "app_topolo_auth.workspaces.list",
+  create: "app_topolo_auth.workspaces.create",
+  rename: "app_topolo_auth.workspaces.rename",
+  setDefault: "app_topolo_auth.workspaces.default.set"
+};
+var WorkspacesModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list(application) {
+    const context = await this.resolveContext(application);
+    return this.client.callAction(ACTIONS.list, {
+      org_id: context.organizationId,
+      app_id: context.appId
+    });
+  }
+  async create(application, input) {
+    const current = await this.list(application);
+    if (!current.data.policy.canCreate) {
+      throw new TopoloSdkError(
+        "workspace_creation_not_allowed",
+        `Workspace creation is not allowed for ${current.data.appId}: ${current.data.policy.reason}`
+      );
+    }
+    return this.client.callAction(ACTIONS.create, {
+      organizationId: current.data.organizationId,
+      appId: current.data.appId,
+      name: input.name,
+      ...input.isDefault === void 0 ? {} : { isDefault: input.isDefault }
+    }, { confirm: input.confirm === true });
+  }
+  async rename(application, workspaceId, name, confirm = false) {
+    const context = await this.resolveContext(application);
+    return this.client.callAction(ACTIONS.rename, {
+      workspaceId,
+      organizationId: context.organizationId,
+      appId: context.appId,
+      name
+    }, { confirm });
+  }
+  async setDefault(application, workspaceId, confirm = false) {
+    const context = await this.resolveContext(application);
+    return this.client.callAction(ACTIONS.setDefault, {
+      workspaceId,
+      organizationId: context.organizationId,
+      appId: context.appId
+    }, { confirm });
+  }
+  async resolveContext(application) {
+    const identity = await this.client.introspect();
+    if (!identity.organization?.id) {
+      throw new TopoloSdkError("organization_required", "Workspace lifecycle requires an organization-scoped credential.");
+    }
+    const service = await this.client.getService(application);
+    return { organizationId: identity.organization.id, appId: service.appId };
+  }
+};
+
 // src/modules/p2p.ts
 var P2PModule = class {
   constructor(client) {
@@ -4745,6 +4922,7 @@ function createTopolo(options) {
   return {
     client,
     identity: new IdentityModule(client),
+    workspaces: new WorkspacesModule(client),
     crm: new CrmModule(client)
   };
 }
@@ -4767,9 +4945,12 @@ function createTopolo(options) {
   TopoloOAuth,
   TopoloPermissionError,
   TopoloSdkError,
+  WorkspacesModule,
   actionContractCompleteness,
+  applicationEntryFromCatalog,
   applicationRequirementScopes,
   auditAllApplicationRequirements,
+  auditApplicationEntries,
   auditApplicationRequirements,
   createTopolo,
   createTopoloWidgetError,
@@ -4781,12 +4962,17 @@ function createTopolo(options) {
   defineTopoloStatsWidget,
   digestTopoloActionCatalog,
   enrichActionContract,
+  formatDirectoryApplicationIds,
+  friendlyAppId,
+  listApplicationDirectory,
   parseTopoloActionUploadContract,
   prepareTopoloActionBase64UploadInput,
   prepareTopoloActionUploadInput,
   requirementsForApplication,
+  resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  staticApplicationDirectory,
   validateTopoloActionInput,
   validateTopoloWidgetResponse
 });