@topolo/sdk 0.6.0 → 0.8.0

package/src/client.ts

@@ -5,7 +5,13 @@ import {
   type AgentIdentity,
   type TopoloCredential,
 } from './auth.js';
-import { TopoloAuthError, TopoloHttpError, TopoloPermissionError, TopoloSdkError } from './errors.js';
+import {
+  TopoloAuthError,
+  TopoloConfirmationRequiredError,
+  TopoloHttpError,
+  TopoloPermissionError,
+  TopoloSdkError,
+} from './errors.js';
 import {
   DEFAULT_APP_URLS,
   APPLICATIONS,
@@ -30,6 +36,12 @@ export interface TopoloClientOptions {
   timeoutMs?: number;
   /** Injected fetch, for testing. Defaults to global fetch. */
   fetch?: typeof fetch;
+  /**
+   * Refresh a rejected access-token credential. When supplied, the client
+   * retries one 401 response with the returned credential. Concurrent 401s
+   * share one refresh operation. API keys are never refreshed.
+   */
+  refreshCredential?: () => Promise<TopoloCredential | null>;
   /**
    * Observability hook. Fires once per request lifecycle (`request` at start,
    * then exactly one of `response` or `error`). Safe to leave unset — off by
@@ -72,6 +84,8 @@ export type TopoloDebugEvent =
 
 export interface RequestOptions {
   service: string;
+  /** Catalog-resolved origin for an action target. */
+  baseUrl?: string;
   path: string;
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   query?: Record<string, string | number | boolean | undefined>;
@@ -96,7 +110,6 @@ const TOPOLO_RESOURCE_ID_HEADER = 'X-Topolo-Resource-ID';
 
 const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
-const CATALOG_CACHE_TTL_MS = 60 * 1000; // 1 minute
 
 interface AppIdCacheEntry {
   value: string | null;
@@ -135,6 +148,8 @@ export interface TopoloApiKeyResourceMetadata {
 
 export interface TopoloActionCatalogEntry {
   actionId: string;
+  target: string | null;
+  apiBaseUrl: string | null;
   name: string;
   toolName: string | null;
   title: string;
@@ -146,6 +161,8 @@ export interface TopoloActionCatalogEntry {
   path: string;
   permissionName: string;
   requiredPermission: string;
+  /** Static catalog permission or target-enforced input-dependent authorization. */
+  authorizationMode?: 'static' | 'runtime';
   inputSchema: Record<string, unknown>;
   outputSchema: Record<string, unknown>;
   readOnly: boolean;
@@ -157,17 +174,38 @@ export interface TopoloActionCatalogEntry {
   sourceRevision: string | null;
 }
 
+export interface TopoloCatalogPage {
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+export interface TopoloServiceCatalogPage {
+  services: TopoloServiceCatalogEntry[];
+  page: TopoloCatalogPage;
+}
+
+export interface TopoloActionCatalogPage {
+  actions: TopoloActionCatalogEntry[];
+  page: TopoloCatalogPage;
+}
+
+export interface TopoloCatalogSearchOptions {
+  query?: string;
+  cursor?: string;
+  limit?: number;
+}
+
 export class TopoloClient {
-  private readonly credential: TopoloCredential;
+  private credential: TopoloCredential;
   private readonly agent: AgentIdentity;
   private readonly serviceUrls?: Record<string, string>;
   private readonly appIds?: Record<string, string>;
   private readonly requireConfirmForWrites: boolean;
   private readonly timeoutMs: number;
   private readonly fetchImpl: typeof fetch;
+  private readonly refreshCredential?: () => Promise<TopoloCredential | null>;
+  private refreshInFlight: Promise<TopoloCredential | null> | null = null;
   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 → app-id lookups. Keyed by
@@ -195,6 +233,7 @@ export class TopoloClient {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 30_000;
     this.fetchImpl = options.fetch ?? fetch;
+    this.refreshCredential = options.refreshCredential;
     this.debug = options.debug;
   }
 
@@ -215,13 +254,15 @@ export class TopoloClient {
   async request<T = unknown>(opts: RequestOptions): Promise<T> {
     const method = opts.method ?? 'GET';
     if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
-      throw new TopoloAuthError(
+      throw new TopoloConfirmationRequiredError(
         `Mutating ${method} requests require { confirm: true }. This guardrail prevents ` +
           `agents from issuing writes without an explicit human-in-the-loop acknowledgement.`,
       );
     }
 
-    const resolvedService = await this.resolveRequestService(opts.service);
+    const resolvedService = opts.baseUrl
+      ? { serviceKey: normalizeLookupKey(opts.service), baseUrl: requireHttpOrigin(opts.baseUrl) }
+      : await this.resolveRequestService(opts.service);
     const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     if (opts.query) {
@@ -256,24 +297,44 @@ export class TopoloClient {
       headers.set(TOPOLO_RESOURCE_ID_HEADER, resourceId);
     }
 
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
-    const signal = opts.signal
-      ? mergeSignals(opts.signal, controller.signal)
-      : controller.signal;
-
     const urlStr = url.toString();
     const startedAt = Date.now();
     this.emit({ phase: 'request', method, service: resolvedService.serviceKey, path: opts.path, url: urlStr, requestId });
 
+    const fetchOnce = async (): Promise<Response> => {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+      const signal = opts.signal
+        ? mergeSignals(opts.signal, controller.signal)
+        : controller.signal;
+      try {
+        return await this.fetchImpl(urlStr, {
+          method,
+          headers: new Headers(headers),
+          body: opts.body !== undefined ? JSON.stringify(opts.body) : null,
+          signal,
+        });
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    };
+
     let res: Response;
     try {
-      res = await this.fetchImpl(urlStr, {
-        method,
-        headers,
-        body: opts.body !== undefined ? JSON.stringify(opts.body) : null,
-        signal,
-      });
+      const attemptedCredential = this.credential;
+      res = await fetchOnce();
+      if (
+        res.status === 401
+        && attemptedCredential.kind === 'access_token'
+        && this.refreshCredential
+      ) {
+        await res.body?.cancel().catch(() => undefined);
+        const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
+        if (refreshed) {
+          applyAuthHeaders(headers, refreshed);
+          res = await fetchOnce();
+        }
+      }
     } catch (err) {
       this.emit({
         phase: 'error',
@@ -286,8 +347,6 @@ export class TopoloClient {
         error: err instanceof Error ? err.message : String(err),
       });
       throw err;
-    } finally {
-      clearTimeout(timeoutId);
     }
 
     const contentType = res.headers.get('Content-Type') ?? '';
@@ -333,6 +392,23 @@ export class TopoloClient {
     return parsed as T;
   }
 
+  private async refreshRejectedAccessToken(attemptedAccessToken: string): Promise<TopoloCredential | null> {
+    if (this.credential.kind === 'access_token' && this.credential.accessToken !== attemptedAccessToken) {
+      return this.credential;
+    }
+    if (!this.refreshCredential) return null;
+    this.refreshInFlight ??= this.refreshCredential()
+      .then((credential) => {
+        if (credential) this.credential = credential;
+        return credential;
+      })
+      .catch(() => null)
+      .finally(() => {
+        this.refreshInFlight = null;
+      });
+    return this.refreshInFlight;
+  }
+
   private async resolveRequestService(service: string): Promise<{ serviceKey: string; baseUrl: string }> {
     const serviceKey = normalizeLookupKey(service);
     if (!serviceKey) {
@@ -368,9 +444,8 @@ export class TopoloClient {
   }
 
   private async resolveLiveCallableService(serviceKey: string): Promise<{ serviceKey: string; baseUrl: string } | null> {
-    const catalog = await this.listServices();
-    const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match) return null;
+    const match = await this.getService(serviceKey).catch(() => null);
+    if (!match || !catalogEntryMatches(match, serviceKey)) return null;
     const baseUrl = resolveCatalogServiceUrl(match, {
       serviceKey,
       overrides: this.serviceUrls,
@@ -457,19 +532,19 @@ export class TopoloClient {
    * 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();
-    if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
-      return this.serviceCatalogCache.entries;
-    }
-
+  async searchServices(options: TopoloCatalogSearchOptions = {}): Promise<TopoloServiceCatalogPage> {
     // app-catalog greenfield: the catalog moved to the Catalog (developers)
     // service. Auth no longer owns the registry; it only provides scoping, which
     // the Catalog composes server-side. Consumers pass the per-env developers URL.
     const res = await this.request<
-      | { data?: { services?: unknown[] } }
-      | { services?: unknown[] }
-    >({ service: 'developers', method: 'GET', path: '/api/services/catalog' });
+      | { data?: { services?: unknown[]; page?: unknown } }
+      | { services?: unknown[]; page?: unknown }
+    >({
+      service: 'developers',
+      method: 'GET',
+      path: '/api/services/catalog',
+      query: catalogSearchQuery(options),
+    });
     const raw =
       (res as { data?: { services?: unknown[] } }).data?.services ??
       (res as { services?: unknown[] }).services;
@@ -482,7 +557,8 @@ export class TopoloClient {
 
     const entries: TopoloServiceCatalogEntry[] = [];
     for (const item of raw) {
-      const s = item as Record<string, unknown>;
+      if (!isRecord(item)) continue;
+      const s = item;
       const appId =
         typeof s.app_id === 'string'
           ? s.app_id
@@ -533,11 +609,36 @@ export class TopoloClient {
         apiKeyResources,
       });
     }
-    this.serviceCatalogCache = {
-      entries,
-      expiresAt: now + CATALOG_CACHE_TTL_MS,
-    };
-    return entries;
+    const page = normalizeCatalogPage(
+      (res as { data?: { page?: unknown } }).data?.page ?? (res as { page?: unknown }).page,
+    );
+    return { services: entries, page };
+  }
+
+  /** @deprecated Prefer searchServices() so callers retain the continuation cursor. */
+  async listServices(options: TopoloCatalogSearchOptions = {}): Promise<TopoloServiceCatalogEntry[]> {
+    return (await this.searchServices(options)).services;
+  }
+
+  async getService(application: string): Promise<TopoloServiceCatalogEntry> {
+    const needle = application.trim();
+    if (!needle) throw new TopoloSdkError('unknown_service', 'application is required');
+    const res = await this.request<
+      | { data?: { application?: unknown } }
+      | { application?: unknown }
+    >({
+      service: 'developers',
+      method: 'GET',
+      path: '/api/services/catalog',
+      query: { application: needle },
+    });
+    const raw = (res as { data?: { application?: unknown } }).data?.application
+      ?? (res as { application?: unknown }).application;
+    const entry = normalizeServiceCatalogEntry(raw);
+    if (!entry) {
+      throw new TopoloSdkError('unknown_service', `Unknown Topolo application "${application}".`);
+    }
+    return entry;
   }
 
   /**
@@ -546,20 +647,20 @@ export class TopoloClient {
    * 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;
+  async searchActions(
+    options: TopoloCatalogSearchOptions & { service: string },
+  ): Promise<TopoloActionCatalogPage> {
+    if (!options.service?.trim()) {
+      throw new TopoloSdkError('service_required', 'service is required for bounded action discovery');
     }
-
     const res = await this.request<
-      | { data?: { actions?: unknown[] } }
-      | { actions?: unknown[] }
+      | { data?: { actions?: unknown[]; page?: unknown } }
+      | { actions?: unknown[]; page?: unknown }
     >({
       service: 'developers',
       method: 'GET',
       path: '/api/actions/catalog',
-      ...(options.service ? { query: { service: options.service } } : {}),
+      query: { service: options.service, ...catalogSearchQuery(options) },
     });
     const raw =
       (res as { data?: { actions?: unknown[] } }).data?.actions ??
@@ -574,42 +675,78 @@ export class TopoloClient {
     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 {
+      actions: entries,
+      page: normalizeCatalogPage(
+        (res as { data?: { page?: unknown } }).data?.page ?? (res as { page?: unknown }).page,
+      ),
+    };
+  }
+
+  /** @deprecated Prefer searchActions() so callers retain the continuation cursor. */
+  async listActions(options?: TopoloCatalogSearchOptions & { service: string }): Promise<TopoloActionCatalogEntry[]> {
+    if (!options) {
+      throw new TopoloSdkError('service_required', 'service is required for bounded action discovery');
     }
-    return entries;
+    return (await this.searchActions(options)).actions;
   }
 
   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) {
+    const actionId = action.trim();
+    if (!actionId) {
       throw new TopoloSdkError(
         'unknown_action',
-        `Unknown Topolo action "${action}". Run action discovery first and pass an action id, name, or tool name.`,
+        'action id is required',
       );
     }
+    const res = await this.request<
+      | { data?: { action?: unknown } }
+      | { action?: unknown }
+    >({
+      service: 'developers',
+      method: 'GET',
+      path: '/api/actions/catalog',
+      query: { actionId },
+    });
+    const raw = (res as { data?: { action?: unknown } }).data?.action
+      ?? (res as { action?: unknown }).action;
+    const match = normalizeActionCatalogEntry(raw);
+    if (!match) throw new TopoloSdkError('unknown_action', `Unknown Topolo action "${action}".`);
     return match;
   }
 
   async callAction<T = unknown>(
     action: string,
     input: Record<string, unknown> = {},
-    options: { confirm?: boolean } = {},
+    options: {
+      confirm?: boolean;
+      resource?: { resourceType: string; resourceId: string };
+    } = {},
   ): Promise<T> {
     const entry = await this.getAction(action);
+    const agentAccess = entry.agentAccess
+      ?? (entry.destructive ? 'off' : entry.readOnly && !entry.requiresConfirmation ? 'auto' : 'confirm');
+    if (agentAccess === 'off') {
+      throw new TopoloPermissionError(
+        `Topolo action "${entry.actionId}" is not available for agent invocation.`,
+        entry.requiredPermission ? [entry.requiredPermission] : [],
+      );
+    }
+    if ((agentAccess === 'confirm' || entry.requiresConfirmation || entry.destructive) && options.confirm !== true) {
+      throw new TopoloConfirmationRequiredError(
+        `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`,
+      );
+    }
     const mapped = mapActionInput(entry, input);
     const service = entry.appSlug || entry.appId;
     return this.request<T>({
       service,
+      ...(entry.apiBaseUrl ? { baseUrl: entry.apiBaseUrl } : {}),
       method: entry.method,
       path: mapped.path,
       ...(mapped.query ? { query: mapped.query } : {}),
       ...(mapped.body !== undefined ? { body: mapped.body } : {}),
+      ...(options.resource ? { resource: options.resource } : {}),
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name,
@@ -791,6 +928,19 @@ function normalizeLookupKey(value: string): string {
   return String(value || '').trim().toLowerCase().replace(/\s+/g, '-');
 }
 
+function requireHttpOrigin(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new TopoloSdkError('invalid_action_target', `Invalid action API origin "${value}".`);
+  }
+  if ((url.protocol !== 'https:' && url.protocol !== 'http:') || url.username || url.password) {
+    throw new TopoloSdkError('invalid_action_target', `Invalid action API origin "${value}".`);
+  }
+  return url.origin;
+}
+
 /**
  * Derive the Catalog (developers) base URL from a configured auth base URL by
  * swapping the leading `auth` host label for `developers` (auth.stg.topolo.us ->
@@ -828,6 +978,70 @@ function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
   return [...keys];
 }
 
+function catalogSearchQuery(options: TopoloCatalogSearchOptions): Record<string, string | number> {
+  const query: Record<string, string | number> = {};
+  if (typeof options.query === 'string' && options.query.trim()) query.query = options.query.trim();
+  if (typeof options.cursor === 'string' && options.cursor.trim()) query.cursor = options.cursor.trim();
+  if (typeof options.limit === 'number' && Number.isFinite(options.limit)) query.limit = Math.trunc(options.limit);
+  return query;
+}
+
+function normalizeCatalogPage(value: unknown): TopoloCatalogPage {
+  if (!isRecord(value)) return { nextCursor: null, hasMore: false };
+  return {
+    nextCursor: typeof value.nextCursor === 'string' && value.nextCursor ? value.nextCursor : null,
+    hasMore: value.hasMore === true,
+  };
+}
+
+function normalizeServiceCatalogEntry(item: unknown): TopoloServiceCatalogEntry | null {
+  if (!isRecord(item)) return null;
+  const appId = typeof item.app_id === 'string'
+    ? item.app_id
+    : typeof item.id === 'string'
+      ? item.id
+      : null;
+  if (!appId) return null;
+  const permissions = Array.isArray(item.granted_permissions)
+    ? item.granted_permissions.filter(
+        (permission): permission is string => typeof permission === 'string' && permission.trim().length > 0,
+      )
+    : [];
+  const catalogApiKeyResources = normalizeApiKeyResourceMetadataList(
+    item.api_key_resources ?? item.apiKeyResources,
+  );
+  const apiKeyResource = normalizeApiKeyResourceMetadata(item.api_key_resource ?? item.apiKeyResource)
+    ?? catalogApiKeyResources[0]
+    ?? null;
+  const apiKeyResources = catalogApiKeyResources.length > 0
+    ? catalogApiKeyResources
+    : apiKeyResource
+      ? [apiKeyResource]
+      : [];
+  return {
+    appId,
+    slug: typeof item.app_slug === 'string' ? item.app_slug : null,
+    name: typeof item.name === 'string' ? item.name : null,
+    description: typeof item.description === 'string' ? item.description : null,
+    apiBaseUrl: typeof item.api_base_url === 'string'
+      ? item.api_base_url
+      : typeof item.apiBaseUrl === 'string'
+        ? item.apiBaseUrl
+        : null,
+    launchUrl: typeof item.launch_url === 'string'
+      ? item.launch_url
+      : typeof item.launchUrl === 'string'
+        ? item.launchUrl
+        : null,
+    status: typeof item.status === 'string' ? item.status : null,
+    surfaceKind: typeof item.surface_kind === 'string' ? item.surface_kind : null,
+    launchable: item.launchable === true,
+    permissions,
+    apiKeyResource,
+    apiKeyResources,
+  };
+}
+
 function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry | null {
   if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
   const a = item as Record<string, unknown>;
@@ -842,6 +1056,8 @@ function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry |
 
   return {
     actionId,
+    target: pickActionString(a.target_key) ?? pickActionString(a.target) ?? null,
+    apiBaseUrl: pickActionString(a.api_base_url) ?? pickActionString(a.apiBaseUrl) ?? null,
     name,
     toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
     title: pickActionString(a.title) ?? name,
@@ -853,6 +1069,7 @@ function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry |
     path,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? '',
     requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? '',
+    authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
     outputSchema: plainObject(a.output_schema ?? a.outputSchema),
     readOnly: Boolean(a.read_only ?? a.readOnly),
@@ -876,6 +1093,10 @@ function pickAgentAccess(value: unknown): 'auto' | 'confirm' | 'off' | null {
   return value === 'auto' || value === 'confirm' || value === 'off' ? value : null;
 }
 
+function pickAuthorizationMode(value: unknown): 'static' | 'runtime' {
+  return value === 'runtime' ? 'runtime' : 'static';
+}
+
 function plainObject(value: unknown): Record<string, unknown> {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? value as Record<string, unknown>

package/src/errors.ts

@@ -23,6 +23,13 @@ export class TopoloPermissionError extends TopoloSdkError {
   }
 }
 
+export class TopoloConfirmationRequiredError extends TopoloSdkError {
+  constructor(message: string) {
+    super('confirmation_required', message);
+    this.name = 'TopoloConfirmationRequiredError';
+  }
+}
+
 export class TopoloHttpError extends TopoloSdkError {
   readonly status: number;
   readonly body: unknown;

package/src/index.ts

@@ -37,6 +37,7 @@ export {
 export {
   TopoloSdkError,
   TopoloAuthError,
+  TopoloConfirmationRequiredError,
   TopoloPermissionError,
   TopoloHttpError,
 } from "./errors.js";

package/src/modules/crm.test.ts

@@ -18,8 +18,7 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
       return new Response(
         JSON.stringify({
           data: {
-            services: [
-              {
+            application: {
                 app_id: 'app_crm',
                 app_slug: 'topolo-crm',
                 name: 'Topolo CRM',
@@ -29,7 +28,6 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
                 status: 'active',
                 granted_permissions: ['app_crm.contacts:read'],
               },
-            ],
           },
         }),
         { status: 200, headers: { 'Content-Type': 'application/json' } },

package/src/modules/p2p.test.ts

@@ -17,8 +17,7 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
     if (String(url).includes('/api/services/catalog')) {
       return new Response(JSON.stringify({
         data: {
-          services: [
-            {
+          application: {
               app_id: 'app_p2p',
               app_slug: 'topolo-p2p',
               name: 'Topolo P2P',
@@ -28,7 +27,6 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
               status: 'active',
               granted_permissions: ['app_p2p.directory:read'],
             },
-          ],
         },
       }), {
         status: 200,