@topolo/sdk 0.5.0 → 0.7.0

package/dist/node/credential-store.js

@@ -0,0 +1,427 @@
+// src/node/credential-store.ts
+import { mkdir, readFile, writeFile, chmod } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir, platform } from "os";
+import { dirname, join } from "path";
+
+// src/errors.ts
+var TopoloSdkError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopoloSdkError";
+    this.code = code;
+  }
+};
+var TopoloAuthError = class extends TopoloSdkError {
+  constructor(message, code = "auth_error") {
+    super(code, message);
+    this.name = "TopoloAuthError";
+  }
+};
+var TopoloHttpError = class extends TopoloSdkError {
+  status;
+  body;
+  service;
+  path;
+  constructor(service, path, status, body, message) {
+    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+    this.name = "TopoloHttpError";
+    this.status = status;
+    this.body = body;
+    this.service = service;
+    this.path = path;
+  }
+};
+
+// src/services.generated.ts
+var APP_API_URLS = {
+  agent: "https://agent.topolo.app",
+  auth: "https://auth.topolo.app",
+  backup: "https://backup.topolo.app",
+  books: "https://books.topolo.app",
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://bytes.topolo.app",
+  calendar: "https://calendar.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",
+  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"
+};
+
+// src/services.ts
+var DEFAULT_APP_URLS = APP_API_URLS;
+function resolveServiceUrl(service, overrides) {
+  const override = resolveServiceUrlOverride([service], overrides);
+  if (override) return override;
+  return DEFAULT_APP_URLS[service];
+}
+function resolveServiceUrlOverride(keys, overrides) {
+  for (const key of keys) {
+    const direct = overrides?.[key];
+    if (direct) return direct;
+    const envStyleKey = key.replace(/\./g, "_");
+    const envStyle = overrides?.[envStyleKey];
+    if (envStyle) return envStyle;
+  }
+  for (const key of keys) {
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (envValue) return envValue;
+  }
+  return null;
+}
+
+// src/oauth.ts
+var DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+var TopoloOAuth = class {
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = resolveServiceUrl("auth", options.serviceUrls);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * RFC 8628 device authorization grant — starts the flow by asking the server
+   * for a device_code + user_code. The caller prints the user_code +
+   * verification_uri and then polls `pollDeviceToken` until approval.
+   */
+  async requestDeviceCode(params) {
+    const body = new URLSearchParams();
+    body.set("client_id", params.clientId);
+    if (params.scope) {
+      body.set("scope", Array.isArray(params.scope) ? params.scope.join(" ") : params.scope);
+    }
+    return this.#postForm("/api/developer-oauth/device_authorization", body);
+  }
+  /**
+   * Polls the token endpoint once. Returns the token pair on success, or
+   * throws a `TopoloAuthError` whose `code` is one of the RFC 8628 poll
+   * states: `authorization_pending`, `slow_down`, `access_denied`,
+   * `expired_token`. Callers should back off on `slow_down`, wait at least
+   * one `interval` on `authorization_pending`, and give up on the rest.
+   */
+  async pollDeviceToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", DEVICE_GRANT);
+    body.set("client_id", params.clientId);
+    body.set("device_code", params.deviceCode);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Exchange an authorization code (with PKCE) for tokens. */
+  async exchangeAuthorizationCode(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("client_id", params.clientId);
+    body.set("code", params.code);
+    body.set("redirect_uri", params.redirectUri);
+    if (params.codeVerifier) body.set("code_verifier", params.codeVerifier);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Rotate a refresh token for a new token pair. */
+  async refreshToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "refresh_token");
+    body.set("client_id", params.clientId);
+    body.set("refresh_token", params.refreshToken);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  async #postForm(path, body) {
+    const url = new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
+    const res = await this.fetchImpl(url.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (parsed && typeof parsed === "object" && "error" in parsed) {
+        const err = parsed;
+        throw new TopoloAuthError(err.error_description || err.error, err.error);
+      }
+      throw new TopoloHttpError("auth", path, res.status, parsed);
+    }
+    return parsed;
+  }
+};
+
+// src/node/credential-store.ts
+var TOPOLO_ENVIRONMENTS = ["production", "staging", "development", "local"];
+function contextKey(contextType, organizationId) {
+  return contextType === "organization" && organizationId ? `org:${organizationId}` : "personal";
+}
+var ENVIRONMENT_DEFAULT_SERVICE_URLS = {
+  production: {
+    developers: "https://developers.topolo.app"
+  },
+  staging: {
+    auth: "https://auth.stg.topolo.us",
+    developers: "https://developers.stg.topolo.us",
+    seed: "https://seed.stg.topolo.us"
+  },
+  development: {
+    auth: "https://auth.topolo.dev",
+    developers: "https://developers.topolo.dev"
+  },
+  local: {}
+};
+function configPath() {
+  const override = process.env.TOPOLO_CONFIG_PATH;
+  if (override) return override;
+  const base = process.env.XDG_CONFIG_HOME || (platform() === "win32" ? join(homedir(), "AppData", "Roaming") : join(homedir(), ".config"));
+  return join(base, "topolo", "config.json");
+}
+async function readConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+async function writeConfig(config) {
+  const path = configPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(config, null, 2) + "\n", "utf8");
+  if (platform() !== "win32") {
+    try {
+      await chmod(path, 384);
+    } catch {
+    }
+  }
+}
+function normalizeEnvironment(value) {
+  const normalized = (value ?? "production").trim().toLowerCase();
+  if (normalized === "" || normalized === "production" || normalized === "prod") {
+    return "production";
+  }
+  if (normalized === "staging" || normalized === "stage" || normalized === "stg") {
+    return "staging";
+  }
+  if (normalized === "development" || normalized === "dev") {
+    return "development";
+  }
+  if (normalized === "local" || normalized === "localhost") {
+    return "local";
+  }
+  throw new Error(
+    `Unknown Topolo environment "${value}". Expected production, staging, development, or local.`
+  );
+}
+function selectedEnvironment() {
+  return normalizeEnvironment(process.env.TOPOLO_ENV);
+}
+function envVarPrefix(environment) {
+  if (environment === "production") return "TOPOLO_PRODUCTION";
+  if (environment === "staging") return "TOPOLO_STAGING";
+  if (environment === "development") return "TOPOLO_DEVELOPMENT";
+  return "TOPOLO_LOCAL";
+}
+function profileForEnvironment(config, environment = selectedEnvironment()) {
+  const profile = config.profiles?.[environment] ?? {};
+  if (environment === "production") {
+    return {
+      credential: config.credential,
+      oauthClientId: config.oauthClientId,
+      ...profile,
+      serviceUrls: {
+        ...config.serviceUrls ?? {},
+        ...profile.serviceUrls ?? {}
+      },
+      agentName: profile.agentName ?? config.agentName
+    };
+  }
+  return profile;
+}
+function writeProfileConfig(config, environment, profile) {
+  const profiles = { ...config.profiles ?? {} };
+  profiles[environment] = {
+    ...profiles[environment] ?? {},
+    ...profile
+  };
+  return { ...config, profiles };
+}
+function writeContextCredential(config, environment, ctx, makeActive = true) {
+  const key = contextKey(ctx.contextType, ctx.organizationId);
+  const profile = profileForEnvironment(config, environment);
+  const contexts = { ...profile.contexts ?? {}, [key]: ctx };
+  const next = { contexts };
+  if (makeActive) {
+    next.activeContext = key;
+    next.credential = ctx.credential;
+    next.oauthClientId = ctx.oauthClientId ?? profile.oauthClientId;
+  }
+  return writeProfileConfig(config, environment, next);
+}
+function activateContext(config, environment, key) {
+  const profile = profileForEnvironment(config, environment);
+  const ctx = profile.contexts?.[key];
+  if (!ctx) return config;
+  return writeProfileConfig(config, environment, {
+    activeContext: key,
+    credential: ctx.credential,
+    oauthClientId: ctx.oauthClientId ?? profile.oauthClientId
+  });
+}
+function clearProfileCredential(config, environment) {
+  const next = { ...config };
+  if (environment === "production") {
+    delete next.credential;
+    delete next.oauthClientId;
+  }
+  const profiles = { ...config.profiles ?? {} };
+  const profile = { ...profiles[environment] ?? {} };
+  delete profile.credential;
+  delete profile.oauthClientId;
+  profiles[environment] = profile;
+  return { ...next, profiles };
+}
+function credentialSourceFromConfig(config, environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  if (process.env[`${prefix}_API_KEY`]) return `env:${prefix}_API_KEY`;
+  if (process.env[`${prefix}_ACCESS_TOKEN`]) return `env:${prefix}_ACCESS_TOKEN`;
+  if (process.env.TOPOLO_API_KEY) return "env:TOPOLO_API_KEY";
+  if (process.env.TOPOLO_ACCESS_TOKEN) return "env:TOPOLO_ACCESS_TOKEN";
+  return profileForEnvironment(config, environment).credential ? "config-file" : "none";
+}
+async function resolveCredential(environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
+  if (apiKey) return { kind: "api_key", apiKey };
+  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
+  if (accessToken) return { kind: "access_token", accessToken };
+  const config = await readConfig();
+  return profileForEnvironment(config, environment).credential ?? null;
+}
+var REFRESH_SKEW_SECONDS = 60;
+async function refreshCredentialIfNeeded(environment = selectedEnvironment()) {
+  const prefix = envVarPrefix(environment);
+  if (process.env[`${prefix}_API_KEY`] || process.env[`${prefix}_ACCESS_TOKEN`] || process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+    return resolveCredential(environment);
+  }
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const cred = profile.credential;
+  if (!cred || cred.kind !== "access_token") return cred ?? null;
+  if (!cred.refreshToken || !cred.expiresAt || !profile.oauthClientId) return cred;
+  const now = Math.floor(Date.now() / 1e3);
+  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: profile.oauthClientId,
+      refreshToken: cred.refreshToken
+    });
+    const refreshed = {
+      kind: "access_token",
+      accessToken: tokens.access_token,
+      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
+      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+    };
+    await writeConfig(
+      environment === "production" && !config.profiles?.production ? { ...config, credential: refreshed } : writeProfileConfig(config, environment, { credential: refreshed })
+    );
+    return refreshed;
+  } catch {
+    return cred;
+  }
+}
+function resolveAgentName(configAgentName) {
+  return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
+}
+function resolveServiceUrls(configUrls, environment = selectedEnvironment()) {
+  const merged = {
+    ...ENVIRONMENT_DEFAULT_SERVICE_URLS[environment],
+    ...configUrls ?? {}
+  };
+  const prefix = `${envVarPrefix(environment)}_SERVICE_URL_`;
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith(prefix) && v) {
+      merged[k.slice(prefix.length).toLowerCase()] = v;
+    }
+  }
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith("TOPOLO_SERVICE_URL_") && v) {
+      merged[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
+    }
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+function resolvedProfileConfig(config, environment = selectedEnvironment()) {
+  const profile = profileForEnvironment(config, environment);
+  return {
+    credential: profile.credential,
+    oauthClientId: profile.oauthClientId,
+    agentName: profile.agentName,
+    serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+  };
+}
+export {
+  ENVIRONMENT_DEFAULT_SERVICE_URLS,
+  TOPOLO_ENVIRONMENTS,
+  activateContext,
+  clearProfileCredential,
+  configPath,
+  contextKey,
+  credentialSourceFromConfig,
+  envVarPrefix,
+  normalizeEnvironment,
+  profileForEnvironment,
+  readConfig,
+  refreshCredentialIfNeeded,
+  resolveAgentName,
+  resolveCredential,
+  resolveServiceUrls,
+  resolvedProfileConfig,
+  selectedEnvironment,
+  writeConfig,
+  writeContextCredential,
+  writeProfileConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./node": {
+      "types": "./dist/node/credential-store.d.ts",
+      "import": "./dist/node/credential-store.js",
+      "require": "./dist/node/credential-store.cjs"
     }
   },
   "files": [
@@ -21,7 +26,7 @@
     "generate:services": "node scripts/generate-services.mjs",
     "check:generated": "node scripts/check-generated.mjs",
     "prebuild": "node scripts/generate-services.mjs",
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean && tsup src/node/credential-store.ts --format esm,cjs --dts --out-dir dist/node",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "typecheck": "node scripts/generate-services.mjs && tsc --noEmit",
     "test": "vitest run",

package/src/application-requirements.ts

@@ -105,12 +105,12 @@ export const APPLICATION_REQUIREMENTS = [
     id: 'shared-auth-boundary',
     title: 'Use the shared Topolo auth boundary',
     summary:
-      'Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.',
+      'Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.',
     appliesTo: ['browser', 'api', 'tooling', 'agent_surface'],
     evidence: [
       '@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',
+      'App slug and Auth app registration are documented for protected APIs',
     ],
     implementation: [
       'Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows',
@@ -144,21 +144,21 @@ export const APPLICATION_REQUIREMENTS = [
     ],
   },
   {
-    id: 'service-registration-and-scopes',
-    title: 'Register protected APIs as platform services',
+    id: 'app-registration-and-scopes',
+    title: 'Register protected APIs as platform apps',
     summary:
-      'Callable app APIs need a stable service ID, service slug, permissions, role bundles, and API-key scopes before agents or users rely on them.',
+      'Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.',
     appliesTo: ['api'],
     evidence: [
-      'Auth service catalog contains the service ID and slug',
-      'Permissions, role bundles, and API-key scopes exist for the service',
-      'SDK, CLI, and MCP service discovery include the callable production API',
-      'CloudControl production HTTP targets classify agent reachability with sdk_service_id or agent_callable:false',
+      'Auth app catalog contains the app ID and slug',
+      'Permissions, role bundles, and API-key scopes exist for the app',
+      'SDK, CLI, and MCP app discovery include the callable production API',
+      'CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false',
     ],
     implementation: [
-      'Add production Worker api_url metadata and sdk_service_id for every agent-callable API target',
+      '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 service IDs through generated DEFAULT_SERVICE_URLS and live catalog discovery',
+      'Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery',
       'Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes',
     ],
   },
@@ -410,7 +410,7 @@ function evaluateRequirement(
         'Catalog metadata cannot verify shared shell, launcher, and account menu adoption.',
         evidence,
       );
-    case 'service-registration-and-scopes': {
+    case 'app-registration-and-scopes': {
       if (application.services.length > 0) {
         evidence.push(`services=${application.services.join(',')}`);
         return finding(
@@ -420,7 +420,7 @@ function evaluateRequirement(
           evidence,
         );
       }
-      return finding(requirement, 'missing', 'No SDK service ID is registered for this callable API surface.', evidence);
+      return finding(requirement, 'missing', 'No SDK app API id is registered for this callable API surface.', evidence);
     }
     case 'organization-scoped-data':
       return finding(

package/src/client.test.ts

@@ -46,8 +46,8 @@ const ACTION_CATALOG = {
           title: 'List messages',
           description: 'List Mail messages',
           app_id: 'app_mail',
-          service_slug: 'topolo-mail',
-          service_name: 'Topolo Mail',
+          app_slug: 'topolo-mail',
+          app_name: 'Topolo Mail',
           method: 'GET',
           path: '/api/mail/mailboxes/{mailboxId}/messages',
           permission_name: 'messages:read',
@@ -65,8 +65,8 @@ const ACTION_CATALOG = {
           title: 'Get message',
           description: 'Get Mail message',
           app_id: 'app_mail',
-          service_slug: 'topolo-mail',
-          service_name: 'Topolo Mail',
+          app_slug: 'topolo-mail',
+          app_name: 'Topolo Mail',
           method: 'GET',
           path: '/api/mail/mailboxes/{mailboxId}/messages/{messageId}',
           permission_name: 'messages:read',
@@ -84,8 +84,8 @@ const ACTION_CATALOG = {
           title: 'Send message',
           description: 'Send Mail message',
           app_id: 'app_mail',
-          service_slug: 'topolo-mail',
-          service_name: 'Topolo Mail',
+          app_slug: 'topolo-mail',
+          app_name: 'Topolo Mail',
           method: 'POST',
           path: '/api/mail/mailboxes/{mailboxId}/messages',
           permission_name: 'messages:send',
@@ -395,7 +395,7 @@ describe('TopoloClient.getAppIdBySlug', () => {
     });
   }
 
-  it('uses configured service ids without calling Auth', async () => {
+  it('uses configured app ids without calling Auth', async () => {
     const { impl, calls } = stubFetch([]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'x' },

package/src/client.ts

@@ -7,11 +7,11 @@ import {
 } from './auth.js';
 import { TopoloAuthError, TopoloHttpError, TopoloPermissionError, TopoloSdkError } from './errors.js';
 import {
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   APPLICATIONS,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
-  type ServiceId,
+  type AppApiId,
 } from './services.js';
 
 export interface TopoloClientOptions {
@@ -140,8 +140,8 @@ export interface TopoloActionCatalogEntry {
   title: string;
   description: string;
   appId: string;
-  serviceSlug: string | null;
-  serviceName: string | null;
+  appSlug: string | null;
+  appName: string | null;
   method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   path: string;
   permissionName: string;
@@ -352,7 +352,7 @@ export class TopoloClient {
         const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl('auth', this.serviceUrls));
         if (derived) return { serviceKey, baseUrl: derived };
       }
-      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS[serviceKey as 'auth' | 'developers'] };
+      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey as 'auth' | 'developers'] };
     }
 
     const live = await this.resolveLiveCallableService(serviceKey);
@@ -363,7 +363,7 @@ export class TopoloClient {
 
     throw new TopoloSdkError(
       'unknown_service',
-      `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`,
+      `Unknown Topolo app API "${service}". Run app discovery first and pass a callable app id or slug.`,
     );
   }
 
@@ -603,7 +603,7 @@ export class TopoloClient {
   ): Promise<T> {
     const entry = await this.getAction(action);
     const mapped = mapActionInput(entry, input);
-    const service = entry.serviceSlug || entry.appId;
+    const service = entry.appSlug || entry.appId;
     return this.request<T>({
       service,
       method: entry.method,
@@ -693,7 +693,7 @@ function resolveConfiguredAppId(
   appIds?: Record<string, string>,
 ): string | null {
   for (const serviceKey of serviceKeyCandidates(slug)) {
-    const configured = appIds?.[serviceKey as ServiceId];
+    const configured = appIds?.[serviceKey as AppApiId];
     if (typeof configured === 'string' && configured.trim()) return configured.trim();
 
     const envKey = `TOPOLO_APP_ID_${serviceKey.replace(/\./g, '_').toUpperCase()}`;
@@ -847,8 +847,8 @@ function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry |
     title: pickActionString(a.title) ?? name,
     description: pickActionString(a.description) ?? '',
     appId,
-    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
-    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    appSlug: pickActionString(a.app_slug) ?? pickActionString(a.appSlug) ?? null,
+    appName: pickActionString(a.app_name) ?? pickActionString(a.appName) ?? null,
     method,
     path,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? '',

package/src/index.ts

@@ -10,7 +10,7 @@ export {
 } from "./client.js";
 export type { TopoloCredential, AgentIdentity } from "./auth.js";
 export {
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   APPLICATIONS,
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
@@ -32,7 +32,7 @@ export {
   type ApplicationRequirementStatus,
   type ApplicationRequirementsAuditReport,
   type ServiceCatalogUrlEntry,
-  type ServiceId,
+  type AppApiId,
 } from "./services.js";
 export {
   TopoloSdkError,