@topolo/sdk 0.4.7 → 0.4.8

package/src/oauth.test.ts

@@ -109,5 +109,108 @@ describe('TopoloOAuth.requestDeviceCode', () => {
   });
 });
 
+describe('TopoloOAuth.exchangeAuthorizationCode', () => {
+  it('POSTs grant_type=authorization_code with PKCE verifier + secret', async () => {
+    const { impl, calls } = stubFetch({
+      status: 200,
+      body: { access_token: 'at', token_type: 'Bearer', expires_in: 3600 },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    const res = await oauth.exchangeAuthorizationCode({
+      clientId: 'doac_x',
+      code: 'auth_code_1',
+      redirectUri: 'https://app/cb',
+      codeVerifier: 'verifier_1',
+      clientSecret: 'secret_1',
+    });
+    expect(res.access_token).toBe('at');
+    const body = new URLSearchParams(calls[0]!.init.body as string);
+    expect(body.get('grant_type')).toBe('authorization_code');
+    expect(body.get('code')).toBe('auth_code_1');
+    expect(body.get('redirect_uri')).toBe('https://app/cb');
+    expect(body.get('code_verifier')).toBe('verifier_1');
+    expect(body.get('client_secret')).toBe('secret_1');
+  });
+
+  it('omits optional PKCE verifier + secret when not provided', async () => {
+    const { impl, calls } = stubFetch({
+      status: 200,
+      body: { access_token: 'at', token_type: 'Bearer', expires_in: 3600 },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await oauth.exchangeAuthorizationCode({
+      clientId: 'doac_x',
+      code: 'c',
+      redirectUri: 'https://app/cb',
+    });
+    const body = new URLSearchParams(calls[0]!.init.body as string);
+    expect(body.has('code_verifier')).toBe(false);
+    expect(body.has('client_secret')).toBe(false);
+  });
+});
+
+describe('TopoloOAuth.requestDeviceCode (single scope + omitted)', () => {
+  function deviceBody() {
+    return {
+      device_code: 'dc',
+      user_code: 'X',
+      verification_uri: 'https://ex/dev',
+      expires_in: 600,
+      interval: 5,
+    };
+  }
+
+  it('passes a string scope through unchanged', async () => {
+    const { impl, calls } = stubFetch({ status: 200, body: deviceBody() });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await oauth.requestDeviceCode({ clientId: 'doac_x', scope: 'read' });
+    expect(new URLSearchParams(calls[0]!.init.body as string).get('scope')).toBe('read');
+  });
+
+  it('omits scope when not provided', async () => {
+    const { impl, calls } = stubFetch({ status: 200, body: deviceBody() });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await oauth.requestDeviceCode({ clientId: 'doac_x' });
+    expect(new URLSearchParams(calls[0]!.init.body as string).has('scope')).toBe(false);
+  });
+});
+
+describe('TopoloOAuth #postForm content negotiation', () => {
+  it('parses a non-JSON (text/plain) successful body as a string', async () => {
+    const impl = vi.fn(async () =>
+      new Response('plain-ok', { status: 200, headers: { 'Content-Type': 'text/plain' } }),
+    ) as unknown as typeof fetch;
+    const oauth = new TopoloOAuth({ fetch: impl });
+    const res = await oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' });
+    expect(res as unknown).toBe('plain-ok');
+  });
+
+  it('wraps a non-OAuth text error body in TopoloHttpError', async () => {
+    const impl = vi.fn(async () =>
+      new Response('upstream exploded', {
+        status: 502,
+        headers: { 'Content-Type': 'text/plain' },
+      }),
+    ) as unknown as typeof fetch;
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await expect(
+      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
+    ).rejects.toBeInstanceOf(TopoloHttpError);
+  });
+
+  it('normalizes a base URL that already ends with a slash', async () => {
+    const { impl, calls } = stubFetch({
+      status: 200,
+      body: { access_token: 'at', token_type: 'Bearer', expires_in: 1 },
+    });
+    const oauth = new TopoloOAuth({
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example/' },
+    });
+    await oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' });
+    expect(calls[0]!.url).toBe('https://auth.example/api/developer-oauth/token');
+  });
+});
+
 // Keep the TopoloAuthError import non-dead for type inference
 void TopoloAuthError;

package/src/services.generated.ts

@@ -3,32 +3,32 @@
 // Regenerate: npm run generate:services
 
 export const SERVICES = {
-  agent: "https://agent-api.topolo.app",
+  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-api.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-api.topolo.app",
+  commerce: "https://commerce.topolo.app",
   compose: "https://compose.topolo.app",
   consent: "https://consent.topolo.app",
-  crm: "https://crm-api.topolo.app",
+  crm: "https://crm.topolo.app",
   developers: "https://developers.topolo.app",
   director: "https://director.topolo.app",
-  feed: "https://feed-api.topolo.app",
+  feed: "https://feed.topolo.app",
   flow: "https://flow.topolo.app",
-  forecast: "https://forecast-api.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-api.topolo.app",
+  learn: "https://learn.topolo.app",
   localize: "https://localize.topolo.app",
-  mail: "https://mail-api.topolo.app",
-  mdm: "https://mdm-api.topolo.app",
+  mail: "https://mail.topolo.app",
+  mdm: "https://mdm.topolo.app",
   messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",
   notify: "https://notify.topolo.app",
@@ -37,20 +37,19 @@ export const SERVICES = {
   p2p: "https://p2p.topolo.app",
   pay: "https://pay.topolo.app",
   people: "https://people.topolo.app",
-  pulse: "https://pulse.topolo.app",
   "quro.api": "https://api.ol0.me",
   "quro.redirect": "https://ol0.me",
-  roadmapper: "https://roadmapper-api.topolo.app",
+  roadmapper: "https://roadmapper.topolo.app",
   sign: "https://sign.topolo.app",
-  social_studio: "https://studio-api.topolo.app",
-  socialize: "https://socialize-api.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-api.topolo.app",
+  web: "https://web.topolo.app",
 } as const;
 
 export type ServiceId = keyof typeof SERVICES;

package/src/services.test.ts

@@ -48,7 +48,6 @@ const EXPECTED_APPLICATION_IDS = [
   'p2p',
   'pay',
   'people',
-  'pulse',
   'quro',
   'roadmapper',
   'sign',
@@ -69,10 +68,10 @@ describe('service registry', () => {
       calendar: 'https://calendar.topolo.app',
       books: 'https://books.topolo.app',
       consent: 'https://consent.topolo.app',
-      feed: 'https://feed-api.topolo.app',
-      mail: 'https://mail-api.topolo.app',
+      feed: 'https://feed.topolo.app',
+      mail: 'https://mail.topolo.app',
       one: 'https://www.topolo.app',
-      web: 'https://web-api.topolo.app',
+      web: 'https://web.topolo.app',
     });
     expect(DEFAULT_SERVICE_URLS).toMatchObject({
       success: 'https://success.topolo.app',
@@ -130,7 +129,7 @@ describe('service registry', () => {
 });
 
 describe('application catalog', () => {
-  it('covers every current Topolo application directory', () => {
+  it('covers every production-routable Topolo application directory', () => {
     expect(Object.keys(APPLICATIONS).sort()).toEqual(EXPECTED_APPLICATION_IDS);
   });
 
@@ -149,9 +148,15 @@ describe('application catalog', () => {
 
   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-api')?.serviceId,
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-studio')?.serviceId,
     ).toBe('web');
+    expect(
+      APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-api')?.serviceId,
+    ).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.
@@ -166,9 +171,15 @@ describe('application catalog', () => {
 
   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-api')?.serviceId,
+      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-web')?.serviceId,
     ).toBe('feed');
+    expect(
+      APPLICATIONS.feed.deployTargets.find((target) => target.name === 'topolo-feed-api')?.serviceId,
+    ).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')?.serviceId,
     ).toBeNull();

package/src/widgets.test.ts

@@ -2,11 +2,23 @@ import { describe, expect, it } from "vitest";
 import {
   createTopoloWidgetError,
   createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   validateTopoloWidgetResponse,
 } from "./widgets.js";
 
+const BASE = {
+  serviceId: "service_x",
+  serviceName: "X",
+  lastUpdated: "2026-04-25T00:00:00.000Z",
+  snapshot: { summary: "A summary that is long enough to read." },
+};
+
 describe("Topolo widget contract", () => {
   it("exports the platform widget endpoint defaults", () => {
     expect(TOPOLO_WIDGET_ENDPOINT).toBe("/api/widget");
@@ -177,6 +189,210 @@ describe("Topolo widget contract", () => {
     ]);
   });
 
+  it("stamps the literal type onto each define* helper", () => {
+    expect(defineTopoloStatsWidget({ ...BASE, stats: [] }).type).toBe("stats");
+    expect(
+      defineTopoloRecentActivityWidget({ ...BASE, activities: [] }).type,
+    ).toBe("recent-activity");
+    expect(
+      defineTopoloQuickActionsWidget({ ...BASE, actions: [] }).type,
+    ).toBe("quick-actions");
+    expect(
+      defineTopoloNotificationsWidget({ ...BASE, notifications: [], unreadCount: 0 })
+        .type,
+    ).toBe("notifications");
+    expect(
+      defineTopoloChartWidget({
+        ...BASE,
+        chartType: "line",
+        title: "Trend",
+        data: { labels: ["a"], values: [1] },
+      }).type,
+    ).toBe("chart");
+  });
+
+  it("derives lastUpdated from a Date instance passed as now", () => {
+    const response = createTopoloWidgetResponse({
+      serviceId: "service_x",
+      serviceName: "X",
+      now: new Date("2026-05-01T12:00:00.000Z"),
+      widgets: [
+        {
+          type: "stats",
+          snapshot: { summary: "Date branch summary content here." },
+          stats: [],
+        },
+      ],
+    });
+    expect(response.widgets[0]!.lastUpdated).toBe("2026-05-01T12:00:00.000Z");
+  });
+
+  it("generates a current timestamp when now is omitted", () => {
+    const before = Date.now();
+    const response = createTopoloWidgetResponse({
+      serviceId: "service_x",
+      serviceName: "X",
+      widgets: [
+        {
+          type: "stats",
+          snapshot: { summary: "Omitted-now summary content here." },
+          stats: [],
+        },
+      ],
+    });
+    const stamped = Date.parse(response.widgets[0]!.lastUpdated);
+    expect(stamped).toBeGreaterThanOrEqual(before);
+    expect(Number.isNaN(stamped)).toBe(false);
+  });
+
+  it("rejects a non-object response", () => {
+    expect(validateTopoloWidgetResponse(null)).toEqual({
+      ok: false,
+      errors: ["response must be an object"],
+    });
+  });
+
+  it("rejects a non-boolean success and a non-array widgets field", () => {
+    const result = validateTopoloWidgetResponse({ success: "yes", widgets: "nope" });
+    expect(result.ok).toBe(false);
+    expect(result.errors).toContain("success must be a boolean");
+    expect(result.errors).toContain("widgets must be an array");
+  });
+
+  it("flags a non-string error on a failed response", () => {
+    const result = validateTopoloWidgetResponse({
+      success: false,
+      widgets: [],
+      error: 42,
+    });
+    expect(result.errors).toContain("error must be a string when provided");
+  });
+
+  it("flags a chart widget whose data is not an object", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          type: "chart",
+          chartType: "bar",
+          title: "T",
+          data: "not-an-object",
+        },
+      ],
+    });
+    expect(result.errors).toContain("widgets[0].data must be an object");
+  });
+
+  it("flags non-number unreadCount and missing notifications array", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          type: "notifications",
+          notifications: "x",
+          unreadCount: "many",
+        },
+      ],
+    });
+    expect(result.errors).toContain("widgets[0].notifications must be an array");
+    expect(result.errors).toContain("widgets[0].unreadCount must be a number");
+  });
+
+  it("flags malformed snapshot metadata arrays and metric entries", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          snapshot: {
+            summary: "Snapshot with bad metadata arrays present here.",
+            defaultMetricKeys: "not-array",
+            highlights: "not-array",
+            availableMetrics: [{ key: "", label: "", value: "NaN" }],
+          },
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.defaultMetricKeys must be an array when provided",
+    );
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.highlights must be an array when provided",
+    );
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics[0].key must be a non-empty string",
+    );
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics[0].value must be a number",
+    );
+  });
+
+  it("flags availableMetrics when it is present but not an array", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          snapshot: {
+            summary: "Snapshot summary with bad availableMetrics field.",
+            availableMetrics: "nope",
+          },
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics must be an array when provided",
+    );
+  });
+
+  it("flags a non-object widget entry and a missing snapshot", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [42],
+    });
+    expect(result.errors).toContain("widgets[0] must be an object");
+
+    const result2 = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          serviceId: "s",
+          serviceName: "n",
+          lastUpdated: "2026-04-25T00:00:00.000Z",
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result2.errors).toContain("widgets[0].snapshot must be an object");
+  });
+
+  it("flags a non-object availableMetrics entry", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          snapshot: {
+            summary: "Snapshot with a non-object metric entry here.",
+            availableMetrics: [42],
+          },
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics[0] must be an object",
+    );
+  });
+
   it("reports missing snapshot summaries", () => {
     const result = validateTopoloWidgetResponse({
       success: true,