@topolo/sdk 0.4.1 → 0.4.3

package/src/client.ts

@@ -107,6 +107,29 @@ export interface TopoloServiceCatalogEntry {
   status: string | null;
   surfaceKind: string | null;
   launchable: boolean;
+  permissions: string[];
+}
+
+export interface TopoloActionCatalogEntry {
+  actionId: string;
+  name: string;
+  toolName: string | null;
+  title: string;
+  description: string;
+  serviceId: string;
+  serviceSlug: string | null;
+  serviceName: string | null;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  permissionName: string;
+  requiredPermission: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema: Record<string, unknown>;
+  readOnly: boolean;
+  destructive: boolean;
+  requiresConfirmation: boolean;
+  status: string | null;
+  sourceRevision: string | null;
 }
 
 export class TopoloClient {
@@ -119,6 +142,7 @@ export class TopoloClient {
   private readonly fetchImpl: typeof fetch;
   private readonly debug?: (event: TopoloDebugEvent) => void;
   private serviceCatalogCache: { entries: TopoloServiceCatalogEntry[]; expiresAt: number } | null = null;
+  private actionCatalogCache: { entries: TopoloActionCatalogEntry[]; expiresAt: number } | null = null;
 
   /**
    * Process-wide cache for slug → service-id lookups. Keyed by
@@ -278,14 +302,17 @@ export class TopoloClient {
       throw new TopoloSdkError('unknown_service', 'service is required');
     }
 
-    const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-    if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-
-    const staticUrl = DEFAULT_SERVICE_URLS[serviceKey as ServiceId];
-    if (staticUrl) return { serviceKey, baseUrl: staticUrl };
+    if (serviceKey === 'auth') {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS.auth };
+    }
 
     const live = await this.resolveLiveCallableService(serviceKey);
-    if (live) return live;
+    if (live) {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+    }
 
     throw new TopoloSdkError(
       'unknown_service',
@@ -297,10 +324,7 @@ export class TopoloClient {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
     if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return {
-      serviceKey: normalizeLookupKey(match.slug || match.name || match.serviceId) || serviceKey,
-      baseUrl: match.baseUrl,
-    };
+    return { serviceKey, baseUrl: match.baseUrl };
   }
 
   /**
@@ -374,14 +398,12 @@ export class TopoloClient {
   /**
    * 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.
+   * caller's credential is attached, so the result only includes services the
+   * credential's organization and effective permissions can use.
    *
-   * 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.
+   * Security boundary: this never falls back to the generated global snapshot.
+   * The live Auth catalog is the authority because it is scoped to the caller's
+   * organization and effective permissions.
    */
   async listServices(): Promise<TopoloServiceCatalogEntry[]> {
     const now = Date.now();
@@ -389,53 +411,133 @@ export class TopoloClient {
       return this.serviceCatalogCache.entries;
     }
 
-    try {
-      const res = await this.request<
-        | { data?: { services?: unknown[] } }
-        | { services?: unknown[] }
-      >({ service: 'auth', method: 'GET', path: '/api/services/catalog' });
-      const raw =
-        (res as { data?: { services?: unknown[] } }).data?.services ??
-        (res as { services?: unknown[] }).services;
-      if (Array.isArray(raw) && raw.length > 0) {
-        const entries: TopoloServiceCatalogEntry[] = [];
-        for (const item of raw) {
-          const s = item as Record<string, unknown>;
-          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) {
-          this.serviceCatalogCache = {
-            entries,
-            expiresAt: now + CATALOG_CACHE_TTL_MS,
-          };
-          return entries;
-        }
-      }
-    } catch {
-      // Fall through to the generated snapshot.
+    const res = await this.request<
+      | { data?: { services?: unknown[] } }
+      | { services?: unknown[] }
+    >({ service: 'auth', method: 'GET', path: '/api/services/catalog' });
+    const raw =
+      (res as { data?: { services?: unknown[] } }).data?.services ??
+      (res as { services?: unknown[] }).services;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        'service_catalog_unavailable',
+        'TopoloAuth did not return a service catalog for the current credential.',
+      );
+    }
+
+    const entries: TopoloServiceCatalogEntry[] = [];
+    for (const item of raw) {
+      const s = item as Record<string, unknown>;
+      const serviceId =
+        typeof s.service_id === 'string'
+          ? s.service_id
+          : typeof s.id === 'string'
+            ? s.id
+            : null;
+      if (!serviceId) continue;
+      const permissions = Array.isArray(s.granted_permissions)
+        ? s.granted_permissions
+            .filter((permission): permission is string => typeof permission === 'string' && permission.trim().length > 0)
+        : [];
+      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,
+        permissions,
+      });
+    }
+    this.serviceCatalogCache = {
+      entries,
+      expiresAt: now + CATALOG_CACHE_TTL_MS,
+    };
+    return entries;
+  }
+
+  /**
+   * List callable actions from the live Auth catalog. The response is scoped to
+   * the caller's organization and effective permissions; no bundled/static app
+   * action list is used as an authorization source.
+   */
+  async listActions(options: { service?: string } = {}): Promise<TopoloActionCatalogEntry[]> {
+    const now = Date.now();
+    if (!options.service && this.actionCatalogCache && this.actionCatalogCache.expiresAt > now) {
+      return this.actionCatalogCache.entries;
+    }
+
+    const res = await this.request<
+      | { data?: { actions?: unknown[] } }
+      | { actions?: unknown[] }
+    >({
+      service: 'auth',
+      method: 'GET',
+      path: '/api/actions/catalog',
+      ...(options.service ? { query: { service: options.service } } : {}),
+    });
+    const raw =
+      (res as { data?: { actions?: unknown[] } }).data?.actions ??
+      (res as { actions?: unknown[] }).actions;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        'action_catalog_unavailable',
+        'TopoloAuth did not return an action catalog for the current credential.',
+      );
+    }
+
+    const entries = raw
+      .map((item) => normalizeActionCatalogEntry(item))
+      .filter((entry): entry is TopoloActionCatalogEntry => Boolean(entry));
+    if (!options.service) {
+      this.actionCatalogCache = {
+        entries,
+        expiresAt: now + CATALOG_CACHE_TTL_MS,
+      };
+    }
+    return entries;
+  }
+
+  async getAction(action: string): Promise<TopoloActionCatalogEntry> {
+    const needle = normalizeActionLookupKey(action);
+    const actions = await this.listActions();
+    const match = actions.find((entry) => actionEntryMatches(entry, needle));
+    if (!match) {
+      throw new TopoloSdkError(
+        'unknown_action',
+        `Unknown Topolo action "${action}". Run action discovery first and pass an action id, name, or tool name.`,
+      );
     }
-    return this.generatedCatalogFallback();
+    return match;
   }
 
-  private generatedCatalogFallback(): TopoloServiceCatalogEntry[] {
+  async callAction<T = unknown>(
+    action: string,
+    input: Record<string, unknown> = {},
+    options: { confirm?: boolean } = {},
+  ): Promise<T> {
+    const entry = await this.getAction(action);
+    const mapped = mapActionInput(entry, input);
+    const service = entry.serviceSlug || entry.serviceId;
+    return this.request<T>({
+      service,
+      method: entry.method,
+      path: mapped.path,
+      ...(mapped.query ? { query: mapped.query } : {}),
+      ...(mapped.body !== undefined ? { body: mapped.body } : {}),
+      confirm: options.confirm === true,
+    });
+  }
+
+  /**
+   * Bundled generated registry for tooling that audits platform packaging, not
+   * for deciding what the current credential may use.
+   */
+  listBundledServices(): TopoloServiceCatalogEntry[] {
     const apps = Object.values(APPLICATIONS) as ReadonlyArray<{
       id: string;
       name?: string;
@@ -447,9 +549,10 @@ export class TopoloClient {
       name: app.name ?? app.id,
       description: null,
       baseUrl: app.productionUrl ?? null,
-      status: 'active',
+      status: 'bundled',
       surfaceKind: 'application',
       launchable: Boolean(app.productionUrl),
+      permissions: [],
     }));
   }
 
@@ -543,7 +646,7 @@ function serviceKeyCandidates(slug: string): string[] {
 }
 
 function normalizeLookupKey(value: string): string {
-  return String(value || '').trim().toLowerCase();
+  return String(value || '').trim().toLowerCase().replace(/\s+/g, '-');
 }
 
 function catalogEntryMatches(entry: TopoloServiceCatalogEntry, needle: string): boolean {
@@ -558,12 +661,8 @@ function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    keys.add(normalized);
-    keys.add(normalized.replace(/-/g, '_'));
-    if (normalized.startsWith('topolo-')) {
-      const withoutTopolo = normalized.slice('topolo-'.length);
-      keys.add(withoutTopolo);
-      keys.add(withoutTopolo.replace(/-/g, '_'));
+    for (const candidate of serviceKeyCandidates(normalized)) {
+      keys.add(candidate);
     }
   }
   return [...keys];
@@ -572,7 +671,123 @@ function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
 function isCallableCatalogEntry(entry: TopoloServiceCatalogEntry): boolean {
   const kind = normalizeLookupKey(entry.surfaceKind || '');
   if (kind === 'api' || kind === 'technical_service' || kind === 'service') return true;
-  return Boolean(entry.slug && Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, catalogEntryLookupKeys(entry)[0] ?? ''));
+  return Boolean(
+    entry.baseUrl &&
+    catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key)),
+  );
+}
+
+function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry | null {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const a = item as Record<string, unknown>;
+  const actionId = pickActionString(a.action_id) ?? pickActionString(a.actionId);
+  const name = pickActionString(a.name);
+  const serviceId = pickActionString(a.service_id) ?? pickActionString(a.serviceId);
+  const method = pickActionString(a.method)?.toUpperCase();
+  const path = pickActionString(a.path);
+  if (!actionId || !name || !serviceId || !method || !path || !isHttpMethod(method)) {
+    return null;
+  }
+
+  return {
+    actionId,
+    name,
+    toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
+    title: pickActionString(a.title) ?? name,
+    description: pickActionString(a.description) ?? '',
+    serviceId,
+    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
+    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    method,
+    path,
+    permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? '',
+    requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? '',
+    inputSchema: plainObject(a.input_schema ?? a.inputSchema),
+    outputSchema: plainObject(a.output_schema ?? a.outputSchema),
+    readOnly: Boolean(a.read_only ?? a.readOnly),
+    destructive: Boolean(a.destructive),
+    requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
+    status: pickActionString(a.status),
+    sourceRevision: pickActionString(a.source_revision) ?? pickActionString(a.sourceRevision),
+  };
+}
+
+function isHttpMethod(value: string): value is TopoloActionCatalogEntry['method'] {
+  return value === 'GET' || value === 'POST' || value === 'PUT' || value === 'PATCH' || value === 'DELETE';
+}
+
+function pickActionString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function plainObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function normalizeActionLookupKey(value: string): string {
+  return String(value || '').trim().toLowerCase();
+}
+
+function actionEntryMatches(entry: TopoloActionCatalogEntry, needle: string): boolean {
+  if (!needle) return false;
+  return [entry.actionId, entry.name, entry.toolName]
+    .filter((value): value is string => typeof value === 'string' && value.length > 0)
+    .some((value) => value.toLowerCase() === needle);
+}
+
+function mapActionInput(
+  action: TopoloActionCatalogEntry,
+  input: Record<string, unknown>,
+): { path: string; query?: Record<string, string | number | boolean>; body?: unknown } {
+  const remaining: Record<string, unknown> = { ...(input || {}) };
+  const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key: string) => {
+    const value = remaining[key];
+    if (value === undefined || value === null || value === '') {
+      throw new TopoloSdkError(
+        'invalid_action_input',
+        `Action "${action.name}" requires path parameter "${key}".`,
+      );
+    }
+    delete remaining[key];
+    return encodeURIComponent(String(value));
+  });
+
+  const explicitQuery = plainObject(remaining.query);
+  delete remaining.query;
+  const explicitBody = Object.prototype.hasOwnProperty.call(remaining, 'body')
+    ? remaining.body
+    : undefined;
+  delete remaining.body;
+
+  if (action.method === 'GET') {
+    return {
+      path,
+      query: objectToQuery({ ...remaining, ...explicitQuery }),
+    };
+  }
+
+  const query = objectToQuery(explicitQuery);
+  const body = explicitBody !== undefined ? explicitBody : remaining;
+  return {
+    path,
+    ...(query ? { query } : {}),
+    body,
+  };
+}
+
+function objectToQuery(value: Record<string, unknown>): Record<string, string | number | boolean> | undefined {
+  const query: Record<string, string | number | boolean> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (raw === undefined || raw === null) continue;
+    if (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean') {
+      query[key] = raw;
+    } else {
+      query[key] = JSON.stringify(raw);
+    }
+  }
+  return Object.keys(query).length > 0 ? query : undefined;
 }
 
 interface AuthMePayload {

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type CredentialIntrospection,
   type TopoloDebugEvent,
   type TopoloServiceCatalogEntry,
+  type TopoloActionCatalogEntry,
 } from "./client.js";
 export type { TopoloCredential, AgentIdentity } from "./auth.js";
 export {

package/src/modules/p2p.test.ts

@@ -14,6 +14,26 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
         headers: { 'Content-Type': 'application/json' },
       });
     }
+    if (String(url).includes('/api/services/catalog')) {
+      return new Response(JSON.stringify({
+        data: {
+          services: [
+            {
+              service_id: 'srv_p2p',
+              app_slug: 'topolo-p2p',
+              name: 'Topolo P2P',
+              base_url: 'https://p2p.topolo.app',
+              surface_kind: 'api',
+              status: 'active',
+              granted_permissions: ['srv_p2p.directory:read'],
+            },
+          ],
+        },
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
     const next = responses.shift() ?? { status: 200, body: { success: true, data: {} } };
     return new Response(JSON.stringify(next.body ?? { success: true, data: {} }), {
       status: next.status ?? 200,
@@ -24,7 +44,10 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
 }
 
 function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
-  return calls.filter((call) => !call.url.includes('/api/services/by-slug/'));
+  return calls.filter((call) =>
+    !call.url.includes('/api/services/by-slug/') &&
+    !call.url.includes('/api/services/catalog')
+  );
 }
 
 function clientWith(impl: typeof fetch) {
@@ -138,7 +161,7 @@ describe('P2PModule.publishCapability', () => {
     expect(sent.trust_level).toBe('standard');
     const url = new URL(call.url);
     expect(url.pathname).toBe('/api/p2p/internal/capabilities/sync');
-    expect((calls[0]!.init.method ?? '').toUpperCase()).toBe('POST');
+    expect((call.init.method ?? '').toUpperCase()).toBe('POST');
   });
 
   it('honours an explicit acting_for_org_id when the platform key is publishing for another org', async () => {

package/src/services.ts

@@ -6,7 +6,7 @@
  * `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_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * via env vars like `TOPOLO_SERVICE_URL_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
  * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is