@topolo/sdk 0.4.10 → 0.6.0

package/dist/node/credential-store.js

@@ -0,0 +1,399 @@
+// 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"];
+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 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,
+  clearProfileCredential,
+  configPath,
+  credentialSourceFromConfig,
+  envVarPrefix,
+  normalizeEnvironment,
+  profileForEnvironment,
+  readConfig,
+  refreshCredentialIfNeeded,
+  resolveAgentName,
+  resolveCredential,
+  resolveServiceUrls,
+  resolvedProfileConfig,
+  selectedEnvironment,
+  writeConfig,
+  writeProfileConfig
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.4.10",
+  "version": "0.6.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',
     ],
   },
@@ -281,12 +281,12 @@ export function applicationRequirementScopes(
     // the generated kind union to "worker" (no "pages" literal remains).
     application.deployTargets.some((target) => String(target.kind) === 'pages');
   // An API surface means an agent-callable service — keyed on a resolved
-  // serviceId, NOT a bare apiUrl. After the Pages->Worker migration every
+  // appId, NOT a bare apiUrl. After the Pages->Worker migration every
   // frontend shell carries an apiUrl (its own serving domain), so apiUrl is no
-  // longer a signal for "exposes a callable API"; serviceId is.
+  // longer a signal for "exposes a callable API"; appId is.
   const hasApiSurface =
     application.services.length > 0 ||
-    application.deployTargets.some((target) => Boolean(target.serviceId));
+    application.deployTargets.some((target) => Boolean(target.appId));
 
   if (hasBrowserSurface) scopes.add('browser');
   if (hasApiSurface) scopes.add('api');
@@ -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(