@topolo/sdk 0.7.0 → 0.8.1

package/src/oauth.ts

@@ -1,138 +0,0 @@
-import { TopoloAuthError, TopoloHttpError } from './errors.js';
-import { resolveServiceUrl, type AppApiId } from './services.js';
-
-const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
-
-export interface DeviceAuthorizationResponse {
-  device_code: string;
-  user_code: string;
-  verification_uri: string;
-  verification_uri_complete?: string;
-  expires_in: number;
-  interval: number;
-}
-
-export interface TokenResponse {
-  access_token: string;
-  token_type: 'Bearer';
-  expires_in: number;
-  refresh_token?: string;
-  scope?: string;
-}
-
-export interface OAuthHelperOptions {
-  /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
-  serviceUrls?: Partial<Record<AppApiId, string>>;
-  /** Injected fetch. Defaults to global fetch. */
-  fetch?: typeof fetch;
-}
-
-/**
- * Thin client over the Topolo OAuth 2.1 authorization server. Intended for
- * first-party tooling (the CLI) and registered third-party agents. Issued
- * access tokens plug into `createTopolo({ credential: { kind: 'access_token', ... } })`.
- */
-export class TopoloOAuth {
-  private readonly baseUrl: string;
-  private readonly fetchImpl: typeof fetch;
-
-  constructor(options: OAuthHelperOptions = {}) {
-    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: {
-    clientId: string;
-    scope?: string | string[];
-  }): Promise<DeviceAuthorizationResponse> {
-    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: {
-    clientId: string;
-    deviceCode: string;
-    clientSecret?: string;
-  }): Promise<TokenResponse> {
-    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: {
-    clientId: string;
-    code: string;
-    redirectUri: string;
-    codeVerifier?: string;
-    clientSecret?: string;
-  }): Promise<TokenResponse> {
-    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: {
-    clientId: string;
-    refreshToken: string;
-    clientSecret?: string;
-  }): Promise<TokenResponse> {
-    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<T>(path: string, body: URLSearchParams): Promise<T> {
-    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: unknown = 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 as { error: string; error_description?: string };
-        throw new TopoloAuthError(err.error_description || err.error, err.error);
-      }
-      throw new TopoloHttpError('auth', path, res.status, parsed);
-    }
-    return parsed as T;
-  }
-}

package/src/services.generated.ts

@@ -1,55 +0,0 @@
-// AUTO-GENERATED by scripts/generate-services.mjs. Do not edit by hand.
-// Source of truth: topolo.cloudcontrol.json in every app repo.
-// Regenerate: npm run generate:services
-
-export const 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",
-} as const;
-
-export type AppApiId = keyof typeof APP_API_URLS;

package/src/services.test.ts

@@ -1,243 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  APPLICATION_REQUIREMENTS,
-  APPLICATION_REQUIREMENTS_VERSION,
-  APPLICATIONS,
-  DEFAULT_APP_URLS,
-  auditAllApplicationRequirements,
-  auditApplicationRequirements,
-  applicationRequirementScopes,
-  resolveCatalogServiceUrl,
-  requirementsForApplication,
-} from './services.js';
-
-const EXPECTED_APPLICATION_IDS = [
-  'admin',
-  'agent',
-  'auth',
-  'backup',
-  'books',
-  'bugfix',
-  'bytes',
-  'calendar',
-  'capacity',
-  'chat',
-  'commerce',
-  'compose',
-  'consent',
-  'crm',
-  'developers',
-  'director',
-  'docs',
-  'feed',
-  'flow',
-  'forecast',
-  'forms',
-  'home',
-  'insights',
-  'inventory',
-  'learn',
-  'localize',
-  'mail',
-  'mdm',
-  'messages',
-  'nexus',
-  'notify',
-  'observability_watch',
-  'one',
-  'p2p',
-  'pay',
-  'people',
-  'quro',
-  'roadmapper',
-  'sign',
-  'social_studio',
-  'socialize',
-  'spaces',
-  'status',
-  'success',
-  'support',
-  'survey',
-  'voice',
-  'web',
-];
-
-describe('app API registry', () => {
-  it('includes every production worker API that belongs to a platform application', () => {
-    expect(DEFAULT_APP_URLS).toMatchObject({
-      calendar: 'https://calendar.topolo.app',
-      books: 'https://books.topolo.app',
-      consent: 'https://consent.topolo.app',
-      feed: 'https://feed.topolo.app',
-      mail: 'https://mail.topolo.app',
-      one: 'https://www.topolo.app',
-      web: 'https://web.topolo.app',
-    });
-    expect(DEFAULT_APP_URLS).toMatchObject({
-      success: 'https://success.topolo.app',
-      forms: 'https://forms.topolo.app',
-      survey: 'https://survey.topolo.app',
-    });
-    expect(DEFAULT_APP_URLS).not.toHaveProperty('web.api');
-    expect(DEFAULT_APP_URLS).not.toHaveProperty('web.runtime');
-  });
-
-  it('does not bake opaque Auth app ids into the generated registry', async () => {
-    const services = await import('./services.js');
-
-    expect(services).not.toHaveProperty('PLATFORM_APP_IDS');
-  });
-
-  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_APP_URLS)) {
-      expect(applicationServices.has(appId)).toBe(true);
-    }
-  });
-
-  it('resolves services from explicit catalog API URLs', () => {
-    expect(resolveCatalogServiceUrl({
-      appId: 'app_crm',
-      slug: 'topolo-crm',
-      name: 'Topolo CRM',
-      launchUrl: 'https://crm.topolo.app',
-      apiBaseUrl: 'https://crm-api.topolo.app',
-    }, { serviceKey: 'crm' })).toBe('https://crm-api.topolo.app');
-  });
-
-  it('does not infer callable URLs from launcher URLs', () => {
-    expect(resolveCatalogServiceUrl({
-      appId: 'app_crm',
-      slug: 'topolo-crm',
-      name: 'Topolo CRM',
-      launchUrl: 'https://crm.stg.topolo.us',
-    }, { serviceKey: 'crm' })).toBeNull();
-  });
-
-  it('prefers explicit catalog API URLs over launch URLs', () => {
-    expect(resolveCatalogServiceUrl({
-      appId: 'app_future',
-      slug: 'topolo-future',
-      name: 'Future',
-      launchUrl: 'https://future.topolo.app',
-      apiBaseUrl: 'https://future-api.topolo.app',
-    })).toBe('https://future-api.topolo.app');
-  });
-});
-
-describe('application catalog', () => {
-  it('covers every production-routable Topolo application directory', () => {
-    expect(Object.keys(APPLICATIONS).sort()).toEqual(EXPECTED_APPLICATION_IDS);
-  });
-
-  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) {
-        expect(registeredServices.has(appId)).toBe(true);
-      }
-      for (const target of application.deployTargets) {
-        if (target.appId) expect(registeredServices.has(target.appId)).toBe(true);
-      }
-    }
-  });
-
-  it('treats TopoloWeb runtime as a standalone deploy, not an agent-callable API service', () => {
-    expect(APPLICATIONS.web.services).toEqual(['web']);
-    // Front-door standardization: the callable `web` service is served by the
-    // studio web worker (web.topolo.app/api); the API worker is de-routed and
-    // no longer carries a public service registration.
-    expect(
-      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-studio')?.appId,
-    ).toBe('web');
-    expect(
-      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-api')?.appId,
-    ).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 app API.
-    expect(
-      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-runtime')?.appId,
-    ).toBeNull();
-    const callableTargetNames = APPLICATIONS.web.deployTargets
-      .filter((target) => target.appId)
-      .map((target) => target.name);
-    expect(callableTargetNames).not.toContain('topolo-web-runtime');
-  });
-
-  it('treats TopoloFeed analytics as telemetry, not an agent-callable API service', () => {
-    expect(APPLICATIONS.feed.services).toEqual(['feed']);
-    // Front-door standardization: the callable `feed` service is served by the
-    // feed web worker (feed.topolo.app/api); the API worker is de-routed.
-    expect(
-      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-web')?.appId,
-    ).toBe('feed');
-    expect(
-      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-api')?.appId,
-    ).toBeNull();
-    // The analytics ingestion worker keeps its own host and is non-callable.
-    expect(
-      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-analytics-api')?.appId,
-    ).toBeNull();
-  });
-});
-
-describe('application requirements', () => {
-  it('exposes a stable versioned requirement list', () => {
-    expect(APPLICATION_REQUIREMENTS_VERSION).toMatch(/^\d{4}-\d{2}-\d{2}\.\d+$/);
-    expect(APPLICATION_REQUIREMENTS.length).toBeGreaterThan(5);
-    expect(APPLICATION_REQUIREMENTS.map((requirement) => requirement.id)).toContain(
-      'shared-auth-boundary',
-    );
-    expect(APPLICATION_REQUIREMENTS.map((requirement) => requirement.id)).toContain(
-      'native-dashboard-widget',
-    );
-  });
-
-  it('derives browser and API scopes from app metadata', () => {
-    expect(applicationRequirementScopes(APPLICATIONS.commerce)).toEqual(
-      expect.arrayContaining(['all', 'browser', 'api', 'agent_surface']),
-    );
-    expect(applicationRequirementScopes(APPLICATIONS.mail)).toEqual(
-      expect.arrayContaining(['all', 'browser', 'api', 'agent_surface']),
-    );
-  });
-
-  it('filters requirements for a target application', () => {
-    const adminRequirementIds = requirementsForApplication('admin').map((requirement) => requirement.id);
-    const mailRequirementIds = requirementsForApplication('mail').map((requirement) => requirement.id);
-
-    expect(adminRequirementIds).toContain('shared-shell-and-launcher');
-    expect(adminRequirementIds).not.toContain('organization-scoped-data');
-    expect(mailRequirementIds).toContain('organization-scoped-data');
-    expect(mailRequirementIds).toContain('app-registration-and-scopes');
-    expect(mailRequirementIds).toContain('native-dashboard-widget');
-  });
-
-  it('audits one application against the catalog-backed requirements', () => {
-    const audit = auditApplicationRequirements('mail');
-    const byRequirement = new Map(audit.findings.map((finding) => [finding.requirementId, finding]));
-
-    expect(audit.version).toBe(APPLICATION_REQUIREMENTS_VERSION);
-    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('app-registration-and-scopes')?.status).toBe('partial');
-    expect(byRequirement.get('canonical-docs')?.status).toBe('needs_review');
-  });
-
-  it('builds a sorted migration queue for all applications', () => {
-    const report = auditAllApplicationRequirements(['mail', 'admin']);
-    expect(report.applications).toHaveLength(2);
-    expect(report.migrationQueue.length).toBeGreaterThan(0);
-    expect(report.migrationQueue[0]).toMatchObject({
-      applicationId: expect.any(String),
-      requirementId: expect.any(String),
-      status: expect.stringMatching(/missing|partial|needs_review/),
-    });
-  });
-});

package/src/services.ts

@@ -1,138 +0,0 @@
-/**
- * App API registry — base URLs for callable Topolo platform APIs.
- *
- * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
- * `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_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 {
-  APP_API_URLS,
-  type AppApiId,
-} from './services.generated.js';
-import {
-  APPLICATIONS,
-  type ApplicationCatalogEntry,
-  type ApplicationDeployTarget,
-  type ApplicationId,
-} from './applications.generated.js';
-export {
-  APPLICATION_REQUIREMENTS,
-  APPLICATION_REQUIREMENTS_VERSION,
-  auditAllApplicationRequirements,
-  auditApplicationRequirements,
-  applicationRequirementScopes,
-  requirementsForApplication,
-  type ApplicationRequirement,
-  type ApplicationRequirementAudit,
-  type ApplicationRequirementFinding,
-  type ApplicationRequirementMigrationItem,
-  type ApplicationRequirementScore,
-  type ApplicationRequirementScope,
-  type ApplicationRequirementStatus,
-  type ApplicationRequirementsAuditReport,
-} from './application-requirements.js';
-
-export { APP_API_URLS };
-export type { AppApiId };
-export { APPLICATIONS };
-export type { ApplicationCatalogEntry, ApplicationDeployTarget, ApplicationId };
-
-export const DEFAULT_APP_URLS: Record<AppApiId, string> = APP_API_URLS;
-
-export interface ServiceCatalogUrlEntry {
-  appId?: string | null;
-  slug?: string | null;
-  name?: string | null;
-  apiBaseUrl?: string | null;
-  launchUrl?: string | null;
-  api_base_url?: string | null;
-  launch_url?: string | null;
-}
-
-export function resolveCatalogServiceUrl(
-  entry: ServiceCatalogUrlEntry,
-  options: {
-    serviceKey?: string;
-    overrides?: Record<string, string> | Partial<Record<AppApiId, string>>;
-  } = {},
-): string | null {
-  const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
-  const override = resolveServiceUrlOverride(keys, options.overrides);
-  if (override) return override;
-
-  const apiBaseUrl = firstString(entry.apiBaseUrl, entry.api_base_url);
-  if (apiBaseUrl) return apiBaseUrl;
-
-  return null;
-}
-
-export function resolveServiceUrl(
-  service: AppApiId,
-  overrides?: Partial<Record<AppApiId, string>>,
-): string {
-  const override = resolveServiceUrlOverride([service], overrides);
-  if (override) return override;
-
-  return DEFAULT_APP_URLS[service];
-}
-
-function catalogServiceKeyCandidates(entry: ServiceCatalogUrlEntry, preferred?: string): string[] {
-  const values = [preferred, entry.slug, entry.name, entry.appId].filter(
-    (value): value is string => typeof value === 'string' && value.trim().length > 0,
-  );
-  const keys = new Set<string>();
-  for (const value of values) {
-    for (const candidate of serviceKeyCandidates(value)) keys.add(candidate);
-  }
-  return [...keys];
-}
-
-function serviceKeyCandidates(value: string): string[] {
-  const normalized = value.trim().toLowerCase().replace(/\s+/g, '-');
-  const withoutTopolo = normalized.startsWith('topolo-')
-    ? normalized.slice('topolo-'.length)
-    : normalized;
-  return [...new Set([
-    normalized,
-    normalized.replace(/-/g, '_'),
-    withoutTopolo,
-    withoutTopolo.replace(/-/g, '_'),
-  ])].filter(Boolean);
-}
-
-function resolveServiceUrlOverride(
-  keys: string[],
-  overrides?: Record<string, string> | Partial<Record<AppApiId, string>>,
-): string | null {
-  for (const key of keys) {
-    const direct = overrides?.[key as AppApiId];
-    if (direct) return direct;
-
-    const envStyleKey = key.replace(/\./g, '_');
-    const envStyle = overrides?.[envStyleKey as AppApiId];
-    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] : undefined;
-    if (envValue) return envValue;
-  }
-
-  return null;
-}
-
-function firstString(...values: Array<string | null | undefined>): string | null {
-  for (const value of values) {
-    if (typeof value === 'string' && value.trim()) return value.trim();
-  }
-  return null;
-}