@topolo/sdk 0.1.2 → 0.2.2

package/src/index.ts

@@ -8,8 +8,26 @@ export {
 export type { TopoloCredential, AgentIdentity } from './auth.js';
 export {
   DEFAULT_SERVICE_URLS,
+  APPLICATIONS,
+  APPLICATION_REQUIREMENTS,
+  APPLICATION_REQUIREMENTS_VERSION,
   PLATFORM_SERVICE_IDS,
+  auditAllApplicationRequirements,
+  auditApplicationRequirements,
+  applicationRequirementScopes,
+  requirementsForApplication,
   resolveServiceUrl,
+  type ApplicationCatalogEntry,
+  type ApplicationDeployTarget,
+  type ApplicationId,
+  type ApplicationRequirement,
+  type ApplicationRequirementAudit,
+  type ApplicationRequirementFinding,
+  type ApplicationRequirementMigrationItem,
+  type ApplicationRequirementScore,
+  type ApplicationRequirementScope,
+  type ApplicationRequirementStatus,
+  type ApplicationRequirementsAuditReport,
   type ServiceId,
 } from './services.js';
 export {

package/src/services.generated.ts

@@ -0,0 +1,35 @@
+// 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 SERVICES = {
+  agent: "https://topolo-agent-worker.topolo.workers.dev",
+  auth: "https://auth.topolo.app",
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://r2-media-manager-worker.topolo.workers.dev",
+  calendar: "https://calendar.topolo.app",
+  chat: "https://chat.topolo.app",
+  commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  crm: "https://crm-api.topolo.app",
+  forecast: "https://forecast-worker-production.topolo.workers.dev",
+  learn: "https://topololearn-api.topolo.workers.dev",
+  mail: "https://mail.topolo.app",
+  mdm: "https://topolo-mdm-api.topolo.app",
+  messaging: "https://messages.topolo.app",
+  nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  one: "https://topoloone-worker.topolo.workers.dev",
+  pay: "https://topolo-pay.topolo.workers.dev",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper-api.topolo.app",
+  social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
+  socialize: "https://socialize-prod-api.topolo.workers.dev",
+  support: "https://support.topolo.app",
+  web: "https://web-api.topolo.app",
+} as const;
+
+export type ServiceId = keyof typeof SERVICES;
+
+export const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>> = {
+  crm: "srv_iCwM4jGXcwlj",
+};

package/src/services.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import {
+  APPLICATION_REQUIREMENTS,
+  APPLICATION_REQUIREMENTS_VERSION,
+  APPLICATIONS,
+  DEFAULT_SERVICE_URLS,
+  auditAllApplicationRequirements,
+  auditApplicationRequirements,
+  applicationRequirementScopes,
+  requirementsForApplication,
+} from './services.js';
+
+const EXPECTED_APPLICATION_IDS = [
+  'admin',
+  'agent',
+  'auth',
+  'bugfix',
+  'bytes',
+  'calendar',
+  'chat',
+  'cli',
+  'cloudcontrol',
+  'commerce',
+  'crm',
+  'developers',
+  'docs',
+  'feed',
+  'forecast',
+  'learn',
+  'mail',
+  'mcp',
+  'mdm',
+  'messaging',
+  'nexus',
+  'one',
+  'pay',
+  'quro',
+  'roadmapper',
+  'social_studio',
+  'socialize',
+  'support',
+  'web',
+];
+
+describe('service registry', () => {
+  it('includes every production worker API that belongs to a platform application', () => {
+    expect(DEFAULT_SERVICE_URLS).toMatchObject({
+      calendar: 'https://calendar.topolo.app',
+      mail: 'https://mail.topolo.app',
+      web: 'https://web-api.topolo.app',
+    });
+    expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.api');
+    expect(DEFAULT_SERVICE_URLS).not.toHaveProperty('web.runtime');
+  });
+
+  it('maps every callable service back to an application catalog entry', () => {
+    const applicationServices = new Set<string>(
+      Object.values(APPLICATIONS).flatMap((application) => [...application.services]),
+    );
+
+    for (const serviceId of Object.keys(DEFAULT_SERVICE_URLS)) {
+      expect(applicationServices.has(serviceId)).toBe(true);
+    }
+  });
+});
+
+describe('application catalog', () => {
+  it('covers every current Topolo application directory', () => {
+    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));
+
+    for (const application of Object.values(APPLICATIONS)) {
+      for (const serviceId of application.services) {
+        expect(registeredServices.has(serviceId)).toBe(true);
+      }
+      for (const target of application.deployTargets) {
+        if (target.serviceId) expect(registeredServices.has(target.serviceId)).toBe(true);
+      }
+    }
+  });
+
+  it('treats TopoloWeb runtime as a deploy target, not an agent-callable API service', () => {
+    expect(APPLICATIONS.web.services).toEqual(['web']);
+    expect(
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topoloweb-api')?.serviceId,
+    ).toBe('web');
+    expect(
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topoloweb-runtime')?.serviceId,
+    ).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',
+    );
+  });
+
+  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']),
+    );
+    expect(applicationRequirementScopes(APPLICATIONS.cli)).toEqual(
+      expect.arrayContaining(['all', 'tooling', '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);
+    const cliRequirementIds = requirementsForApplication('cli').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('service-registration-and-scopes');
+    expect(cliRequirementIds).toContain('agent-and-operator-surfaces');
+    expect(cliRequirementIds).not.toContain('service-registration-and-scopes');
+  });
+
+  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('service-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,30 +1,52 @@
 /**
- * Service registry — base URLs for each Topolo platform service.
+ * Service registry — base URLs for every Topolo platform service.
  *
- * Defaults point at production. Any entry can be overridden per-call via
- * `TopoloClient` options, or globally via env vars like `TOPOLO_SERVICE_URL_CRM`.
+ * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
+ * `SERVICES` 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_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * (dots in service IDs 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.
  */
-export type ServiceId =
-  | 'auth'
-  | 'crm';
+import {
+  SERVICES,
+  PLATFORM_SERVICE_IDS,
+  type ServiceId,
+} 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 const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = {
-  auth: 'https://auth.topolo.app',
-  crm: 'https://topolo-crm-worker.topolo.workers.dev',
-};
+export { SERVICES, PLATFORM_SERVICE_IDS };
+export type { ServiceId };
+export { APPLICATIONS };
+export type { ApplicationCatalogEntry, ApplicationDeployTarget, ApplicationId };
 
-/**
- * Service IDs as registered in TopoloAuth's service catalog. These are sent in
- * the `X-Service-ID` header when the platform needs to route an API-key
- * introspection or permission check.
- */
-export const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>> = {
-  crm: 'srv_iCwM4jGXcwlj',
-};
+export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = SERVICES;
 
 export function resolveServiceUrl(
   service: ServiceId,
@@ -33,7 +55,7 @@ export function resolveServiceUrl(
   const override = overrides?.[service];
   if (override) return override;
 
-  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, '_').toUpperCase()}`;
   const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
   if (envValue) return envValue;