@topolo/sdk 0.5.0 → 0.7.0

package/src/node/credential-store.ts

@@ -0,0 +1,378 @@
+import { mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { TopoloOAuth } from '../oauth.js';
+import type { TopoloCredential } from '../auth.js';
+
+/**
+ * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
+ *
+ * Both need to read (and refresh) the credential that `topolo auth login`
+ * writes to `$XDG_CONFIG_HOME/topolo/config.json`. This lives in a Node-only
+ * subpath (`@topolo/sdk/node`) so the isomorphic SDK core never imports
+ * `node:fs` — importing this module in a browser/worker bundle is a mistake.
+ *
+ * The CLI re-exports every symbol here from `packages/topolo-cli/src/config.ts`
+ * so existing call sites are unchanged; the MCP imports it directly to fall
+ * back to the on-disk credential when no `TOPOLO_*` env credential is set.
+ */
+
+export const TOPOLO_ENVIRONMENTS = ['production', 'staging', 'development', 'local'] as const;
+export type TopoloEnvironment = (typeof TOPOLO_ENVIRONMENTS)[number];
+
+export interface TopoloConfig {
+  credential?: TopoloCredential;
+  /** OAuth client_id used for the most recent login — needed to refresh the access token. */
+  oauthClientId?: string;
+  /** Per-service URL overrides — written when user runs `topolo config set-url`. */
+  serviceUrls?: Record<string, string>;
+  /** Optional agent label propagated as `X-Topolo-Agent`. */
+  agentName?: string;
+  /** Environment-scoped profiles. Legacy top-level fields are treated as production. */
+  profiles?: Partial<Record<TopoloEnvironment, TopoloEnvironmentProfile>>;
+}
+
+export interface TopoloEnvironmentProfile {
+  credential?: TopoloCredential;
+  oauthClientId?: string;
+  serviceUrls?: Record<string, string>;
+  agentName?: string;
+  /**
+   * The context (`personal` or `org:<orgId>`) whose credential is currently
+   * active. `credential` above always mirrors `contexts[activeContext]`, so
+   * credential resolution + the MCP keep working unchanged while `contexts`
+   * lets the CLI hold and switch between multiple org/personal contexts.
+   */
+  activeContext?: string;
+  contexts?: Record<string, TopoloContextCredential>;
+}
+
+/** A signed-in context — personal, or a specific organization. */
+export interface TopoloContextCredential {
+  contextType: 'personal' | 'organization';
+  organizationId?: string;
+  organizationSlug?: string;
+  organizationName?: string;
+  credential?: TopoloCredential;
+  oauthClientId?: string;
+}
+
+/** Stable key for a context within a profile's `contexts` map. */
+export function contextKey(
+  contextType: 'personal' | 'organization',
+  organizationId?: string | null,
+): string {
+  return contextType === 'organization' && organizationId
+    ? `org:${organizationId}`
+    : 'personal';
+}
+
+/**
+ * Default service URLs per environment. `local` has no baked defaults — a
+ * local dev loop points services at ad-hoc ports, so it is driven entirely by
+ * `TOPOLO_LOCAL_SERVICE_URL_*` / `TOPOLO_SERVICE_URL_*` overrides.
+ */
+export const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<
+  TopoloEnvironment,
+  Record<string, string>
+> = {
+  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: {},
+};
+
+export function configPath(): string {
+  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');
+}
+
+export async function readConfig(): Promise<TopoloConfig> {
+  const path = configPath();
+  if (!existsSync(path)) return {};
+  try {
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw) as TopoloConfig;
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(config: TopoloConfig): Promise<void> {
+  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, 0o600);
+    } catch {
+      /* non-fatal */
+    }
+  }
+}
+
+export function normalizeEnvironment(value: string | undefined): TopoloEnvironment {
+  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.`,
+  );
+}
+
+export function selectedEnvironment(): TopoloEnvironment {
+  return normalizeEnvironment(process.env.TOPOLO_ENV);
+}
+
+export function envVarPrefix(environment: TopoloEnvironment): string {
+  if (environment === 'production') return 'TOPOLO_PRODUCTION';
+  if (environment === 'staging') return 'TOPOLO_STAGING';
+  if (environment === 'development') return 'TOPOLO_DEVELOPMENT';
+  return 'TOPOLO_LOCAL';
+}
+
+export function profileForEnvironment(
+  config: TopoloConfig,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): TopoloEnvironmentProfile {
+  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;
+}
+
+export function writeProfileConfig(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+  profile: TopoloEnvironmentProfile,
+): TopoloConfig {
+  const profiles = { ...(config.profiles ?? {}) };
+  profiles[environment] = {
+    ...(profiles[environment] ?? {}),
+    ...profile,
+  };
+  return { ...config, profiles };
+}
+
+/**
+ * Store a context's credential in the profile's `contexts` map. When
+ * `makeActive` (default), also point the profile's active credential at it so
+ * credential resolution + the MCP use this context.
+ */
+export function writeContextCredential(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+  ctx: TopoloContextCredential,
+  makeActive = true,
+): TopoloConfig {
+  const key = contextKey(ctx.contextType, ctx.organizationId);
+  const profile = profileForEnvironment(config, environment);
+  const contexts = { ...(profile.contexts ?? {}), [key]: ctx };
+  const next: TopoloEnvironmentProfile = { contexts };
+  if (makeActive) {
+    next.activeContext = key;
+    next.credential = ctx.credential;
+    next.oauthClientId = ctx.oauthClientId ?? profile.oauthClientId;
+  }
+  return writeProfileConfig(config, environment, next);
+}
+
+/** Point the profile's active credential at an already-stored context. */
+export function activateContext(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+  key: string,
+): TopoloConfig {
+  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,
+  });
+}
+
+export function clearProfileCredential(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+): TopoloConfig {
+  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 };
+}
+
+export function credentialSourceFromConfig(
+  config: TopoloConfig,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): string {
+  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';
+}
+
+/**
+ * Resolve credentials with env-var precedence over on-disk config.
+ * Env vars are what agents set in their environment; config is what
+ * interactive users get after running `topolo auth login`.
+ */
+export async function resolveCredential(
+  environment: TopoloEnvironment = selectedEnvironment(),
+): Promise<TopoloCredential | null> {
+  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;
+}
+
+/**
+ * If the stored access_token is expired (or within the skew window) and a
+ * refresh_token + oauthClientId are present, exchange the refresh_token for a
+ * new pair and persist. On any failure returns the existing (stale) credential
+ * so the next API call fails naturally with auth_error — we don't nuke the
+ * user's config on a transient network blip.
+ */
+const REFRESH_SKEW_SECONDS = 60;
+
+export async function refreshCredentialIfNeeded(
+  environment: TopoloEnvironment = selectedEnvironment(),
+): Promise<TopoloCredential | null> {
+  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() / 1000);
+  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment) as Partial<
+        Record<'auth' | 'crm', string>
+      >,
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: profile.oauthClientId,
+      refreshToken: cred.refreshToken,
+    });
+    const refreshed: TopoloCredential = {
+      kind: 'access_token',
+      accessToken: tokens.access_token,
+      ...(tokens.refresh_token
+        ? { refreshToken: tokens.refresh_token }
+        : { refreshToken: cred.refreshToken }),
+      expiresAt: Math.floor(Date.now() / 1000) + tokens.expires_in,
+    };
+    await writeConfig(
+      environment === 'production' && !config.profiles?.production
+        ? { ...config, credential: refreshed }
+        : writeProfileConfig(config, environment, { credential: refreshed }),
+    );
+    return refreshed;
+  } catch {
+    return cred;
+  }
+}
+
+export function resolveAgentName(configAgentName?: string): string | undefined {
+  return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
+}
+
+export function resolveServiceUrls(
+  configUrls?: Record<string, string>,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): Record<string, string> | undefined {
+  const merged: Record<string, string> = {
+    ...ENVIRONMENT_DEFAULT_SERVICE_URLS[environment],
+    ...(configUrls ?? {}),
+  };
+
+  // Env wins. Pull env-specific and global service URL vars that might be set.
+  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 : undefined;
+}
+
+export function resolvedProfileConfig(
+  config: TopoloConfig,
+  environment: TopoloEnvironment = selectedEnvironment(),
+): TopoloEnvironmentProfile {
+  const profile = profileForEnvironment(config, environment);
+  return {
+    credential: profile.credential,
+    oauthClientId: profile.oauthClientId,
+    agentName: profile.agentName,
+    serviceUrls: resolveServiceUrls(profile.serviceUrls, environment),
+  };
+}

package/src/oauth.ts

@@ -1,5 +1,5 @@
 import { TopoloAuthError, TopoloHttpError } from './errors.js';
-import { resolveServiceUrl, type ServiceId } from './services.js';
+import { resolveServiceUrl, type AppApiId } from './services.js';
 
 const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
 
@@ -22,7 +22,7 @@ export interface TokenResponse {
 
 export interface OAuthHelperOptions {
   /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
-  serviceUrls?: Partial<Record<ServiceId, string>>;
+  serviceUrls?: Partial<Record<AppApiId, string>>;
   /** Injected fetch. Defaults to global fetch. */
   fetch?: typeof fetch;
 }

package/src/services.generated.ts

@@ -2,7 +2,7 @@
 // Source of truth: topolo.cloudcontrol.json in every app repo.
 // Regenerate: npm run generate:services
 
-export const SERVICES = {
+export const APP_API_URLS = {
   agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
@@ -52,4 +52,4 @@ export const SERVICES = {
   web: "https://web.topolo.app",
 } as const;
 
-export type ServiceId = keyof typeof SERVICES;
+export type AppApiId = keyof typeof APP_API_URLS;

package/src/services.test.ts

@@ -3,7 +3,7 @@ import {
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
   APPLICATIONS,
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   applicationRequirementScopes,
@@ -62,9 +62,9 @@ const EXPECTED_APPLICATION_IDS = [
   'web',
 ];
 
-describe('service registry', () => {
+describe('app API registry', () => {
   it('includes every production worker API that belongs to a platform application', () => {
-    expect(DEFAULT_SERVICE_URLS).toMatchObject({
+    expect(DEFAULT_APP_URLS).toMatchObject({
       calendar: 'https://calendar.topolo.app',
       books: 'https://books.topolo.app',
       consent: 'https://consent.topolo.app',
@@ -73,27 +73,27 @@ describe('service registry', () => {
       one: 'https://www.topolo.app',
       web: 'https://web.topolo.app',
     });
-    expect(DEFAULT_SERVICE_URLS).toMatchObject({
+    expect(DEFAULT_APP_URLS).toMatchObject({
       success: 'https://success.topolo.app',
       forms: 'https://forms.topolo.app',
       survey: 'https://survey.topolo.app',
     });
-    expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.api');
-    expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.runtime');
+    expect(DEFAULT_APP_URLS).not.toHaveProperty('web.api');
+    expect(DEFAULT_APP_URLS).not.toHaveProperty('web.runtime');
   });
 
-  it('does not bake opaque Auth service ids into the generated registry', async () => {
+  it('does not bake opaque Auth app ids into the generated registry', async () => {
     const services = await import('./services.js');
 
-    expect(services).not.toHaveProperty('PLATFORM_SERVICE_IDS');
+    expect(services).not.toHaveProperty('PLATFORM_APP_IDS');
   });
 
-  it('maps every callable service back to an application catalog entry', () => {
+  it('maps every callable app API back to an application catalog entry', () => {
     const applicationServices = new Set<string>(
       Object.values(APPLICATIONS).flatMap((application) => [...application.services]),
     );
 
-    for (const appId of Object.keys(DEFAULT_SERVICE_URLS)) {
+    for (const appId of Object.keys(DEFAULT_APP_URLS)) {
       expect(applicationServices.has(appId)).toBe(true);
     }
   });
@@ -133,8 +133,8 @@ describe('application catalog', () => {
     expect(Object.keys(APPLICATIONS).sort()).toEqual(EXPECTED_APPLICATION_IDS);
   });
 
-  it('only references registered service IDs from application metadata', () => {
-    const registeredServices = new Set<string>(Object.keys(DEFAULT_SERVICE_URLS));
+  it('only references registered app API ids from application metadata', () => {
+    const registeredServices = new Set<string>(Object.keys(DEFAULT_APP_URLS));
 
     for (const application of Object.values(APPLICATIONS)) {
       for (const appId of application.services) {
@@ -159,7 +159,7 @@ describe('application catalog', () => {
     ).toBeNull();
     // topolo-web-runtime (Astro, sites.topolo.app) deploys from its own wrangler
     // config and is intentionally listed as non-callable, so it can never be an
-    // agent-callable service.
+    // agent-callable app API.
     expect(
       APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-runtime')?.appId,
     ).toBeNull();
@@ -214,7 +214,7 @@ describe('application requirements', () => {
     expect(adminRequirementIds).toContain('shared-shell-and-launcher');
     expect(adminRequirementIds).not.toContain('organization-scoped-data');
     expect(mailRequirementIds).toContain('organization-scoped-data');
-    expect(mailRequirementIds).toContain('service-registration-and-scopes');
+    expect(mailRequirementIds).toContain('app-registration-and-scopes');
     expect(mailRequirementIds).toContain('native-dashboard-widget');
   });
 
@@ -226,7 +226,7 @@ describe('application requirements', () => {
     expect(audit.application.id).toBe('mail');
     expect(audit.score.total).toBe(audit.findings.length);
     expect(byRequirement.get('platform-metadata')?.status).toBe('met');
-    expect(byRequirement.get('service-registration-and-scopes')?.status).toBe('partial');
+    expect(byRequirement.get('app-registration-and-scopes')?.status).toBe('partial');
     expect(byRequirement.get('canonical-docs')?.status).toBe('needs_review');
   });
 

package/src/services.ts

@@ -1,21 +1,21 @@
 /**
- * Service registry — base URLs for every Topolo platform service.
+ * App API registry — base URLs for callable Topolo platform APIs.
  *
  * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
- * `SERVICES` map is regenerated from those files via
+ * `APP_API_URLS` map is regenerated from those files via
  * `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_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
- * (dots in service IDs become underscores in env vars).
+ * via env vars like `TOPOLO_APP_URL_MAIL` or `TOPOLO_APP_URL_WEB_API`
+ * (dots in app API keys become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
 import {
-  SERVICES,
-  type ServiceId,
+  APP_API_URLS,
+  type AppApiId,
 } from './services.generated.js';
 import {
   APPLICATIONS,
@@ -40,12 +40,12 @@ export {
   type ApplicationRequirementsAuditReport,
 } from './application-requirements.js';
 
-export { SERVICES };
-export type { ServiceId };
+export { APP_API_URLS };
+export type { AppApiId };
 export { APPLICATIONS };
 export type { ApplicationCatalogEntry, ApplicationDeployTarget, ApplicationId };
 
-export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = SERVICES;
+export const DEFAULT_APP_URLS: Record<AppApiId, string> = APP_API_URLS;
 
 export interface ServiceCatalogUrlEntry {
   appId?: string | null;
@@ -61,7 +61,7 @@ export function resolveCatalogServiceUrl(
   entry: ServiceCatalogUrlEntry,
   options: {
     serviceKey?: string;
-    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+    overrides?: Record<string, string> | Partial<Record<AppApiId, string>>;
   } = {},
 ): string | null {
   const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
@@ -75,13 +75,13 @@ export function resolveCatalogServiceUrl(
 }
 
 export function resolveServiceUrl(
-  service: ServiceId,
-  overrides?: Partial<Record<ServiceId, string>>,
+  service: AppApiId,
+  overrides?: Partial<Record<AppApiId, string>>,
 ): string {
   const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
 
-  return DEFAULT_SERVICE_URLS[service];
+  return DEFAULT_APP_URLS[service];
 }
 
 function catalogServiceKeyCandidates(entry: ServiceCatalogUrlEntry, preferred?: string): string[] {
@@ -110,19 +110,19 @@ function serviceKeyCandidates(value: string): string[] {
 
 function resolveServiceUrlOverride(
   keys: string[],
-  overrides?: Record<string, string> | Partial<Record<ServiceId, string>>,
+  overrides?: Record<string, string> | Partial<Record<AppApiId, string>>,
 ): string | null {
   for (const key of keys) {
-    const direct = overrides?.[key as ServiceId];
+    const direct = overrides?.[key as AppApiId];
     if (direct) return direct;
 
     const envStyleKey = key.replace(/\./g, '_');
-    const envStyle = overrides?.[envStyleKey as ServiceId];
+    const envStyle = overrides?.[envStyleKey as AppApiId];
     if (envStyle) return envStyle;
   }
 
   for (const key of keys) {
-    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, '_').toUpperCase()}`;
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, '_').toUpperCase()}`;
     const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
     if (envValue) return envValue;
   }