Merge pull request #93 from telivity-otaip/feat/platform-ui

feat(platform-ui): add Platform UI dashboard + developer playground

Author: telivity-otaip

examples/ota/src/__tests__/platform.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Integration tests for /api/platform/* — read-only telemetry endpoints.
+ *
+ * Uses Fastify inject (no real HTTP) with MockOtaAdapter so tests don't
+ * pull in the live Duffel client at boot.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+import { MockOtaAdapter } from '../mock-ota-adapter.js';
+import { buildApp } from '../server.js';
+
+let app: FastifyInstance;
+
+beforeAll(async () => {
+  app = await buildApp({
+    adapter: new MockOtaAdapter(),
+    initResolver: false,
+    // The platform routes opt out of rate limiting via per-route config;
+    // this guard makes sure tests don't accidentally trip the global cap.
+    security: { rateLimit: false, helmet: false, cors: false },
+  });
+  await app.ready();
+});
+
+afterAll(async () => {
+  await app.close();
+});
+
+describe('GET /api/platform/agents', () => {
+  it('returns the discovered agent list with domain rollups', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/platform/agents' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      agents: Array<{ id: string; stage: string; contract_status: string; version: string }>;
+      domain_groups: Record<string, { total: number; active: number; stub: number }>;
+      totals: { total: number; active: number; stub: number };
+    };
+    expect(body.agents.length).toBeGreaterThan(0);
+    expect(body.totals.total).toBe(body.agents.length);
+    expect(body.totals.active + body.totals.stub).toBe(body.totals.total);
+    // Every domain bucket totals match its members
+    for (const [stage, bucket] of Object.entries(body.domain_groups)) {
+      const members = body.agents.filter((a) => a.stage === stage);
+      expect(members.length).toBe(bucket.total);
+      expect(members.filter((a) => a.contract_status === 'active').length).toBe(bucket.active);
+    }
+  });
+
+  it('marks v0.0.0 agents as stubs', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/platform/agents' });
+    const body = res.json() as { agents: Array<{ version: string; contract_status: string }> };
+    for (const a of body.agents) {
+      if (a.version === '0.0.0') expect(a.contract_status).toBe('stub');
+      else expect(a.contract_status).toBe('active');
+    }
+  });
+});
+
+describe('GET /api/platform/adapters', () => {
+  it('lists every documented adapter with env-derived configured flags', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/platform/adapters' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      adapters: Array<{ id: string; name: string; configured: boolean; env_vars: string[] }>;
+    };
+    const ids = body.adapters.map((a) => a.id);
+    expect(ids).toEqual(
+      expect.arrayContaining(['amadeus', 'sabre', 'navitaire', 'trippro', 'duffel', 'haip', 'hotelbeds']),
+    );
+    // The hotelbeds adapter is "configured" iff both API_KEY and SECRET are set
+    const hb = body.adapters.find((a) => a.id === 'hotelbeds')!;
+    const hbExpected =
+      Boolean(process.env['HOTELBEDS_API_KEY']) && Boolean(process.env['HOTELBEDS_SECRET']);
+    expect(hb.configured).toBe(hbExpected);
+  });
+});
+
+describe('GET /api/platform/health', () => {
+  it('returns uptime, node version, and a request count after the call lands', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/platform/health' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      status: string;
+      uptime_seconds: number;
+      node_version: string;
+      otaip_version: string;
+      last_request_at: string | null;
+      request_count: number;
+    };
+    expect(body.status).toBe('ok');
+    expect(body.uptime_seconds).toBeGreaterThanOrEqual(0);
+    expect(body.node_version).toMatch(/^v\d+\.\d+\.\d+/);
+    expect(body.request_count).toBeGreaterThan(0);
+    expect(body.last_request_at).not.toBeNull();
+  });
+});
+
+describe('GET /api/platform/stats', () => {
+  it('returns aggregate counts that agree with the agent + adapter endpoints', async () => {
+    const [statsRes, agentsRes, adaptersRes] = await Promise.all([
+      app.inject({ method: 'GET', url: '/api/platform/stats' }),
+      app.inject({ method: 'GET', url: '/api/platform/agents' }),
+      app.inject({ method: 'GET', url: '/api/platform/adapters' }),
+    ]);
+    expect(statsRes.statusCode).toBe(200);
+    const stats = statsRes.json() as {
+      agents: { total: number; active: number; stub: number };
+      adapters: { total: number; configured: number };
+    };
+    const agents = (agentsRes.json() as { totals: { total: number } }).totals;
+    const adapters = (adaptersRes.json() as { adapters: Array<{ configured: boolean }> }).adapters;
+    expect(stats.agents.total).toBe(agents.total);
+    expect(stats.adapters.total).toBe(adapters.length);
+    expect(stats.adapters.configured).toBe(adapters.filter((a) => a.configured).length);
+  });
+});

examples/ota/src/__tests__/playground.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Integration tests for /api/playground/* — interactive API explorer.
+ *
+ * `initResolver: true` so the AirportCodeResolver agent is exercised
+ * end-to-end. The mock OTA adapter handles the search-mode test path.
+ */
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import type { FastifyInstance } from 'fastify';
+import { MockOtaAdapter } from '../mock-ota-adapter.js';
+import { buildApp } from '../server.js';
+
+let app: FastifyInstance;
+
+beforeAll(async () => {
+  app = await buildApp({
+    adapter: new MockOtaAdapter(),
+    initResolver: true,
+    security: { rateLimit: false, helmet: false, cors: false },
+  });
+  await app.ready();
+}, 60_000);
+
+afterAll(async () => {
+  await app.close();
+});
+
+describe('GET /api/playground/catalog', () => {
+  it('returns the discovered agents plus the executable whitelist', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/playground/catalog' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      agents: Array<{ id: string; name: string }>;
+      executable_ids: string[];
+      schemas: Record<string, { description: string; example_input: unknown }>;
+    };
+    expect(body.agents.length).toBeGreaterThan(0);
+    expect(body.executable_ids).toContain('0.1');
+    expect(body.schemas['0.1']).toBeDefined();
+    expect(body.schemas['0.1']?.example_input).toEqual({ code: 'JFK', code_type: 'iata' });
+  });
+});
+
+describe('POST /api/playground/search', () => {
+  it('runs a search through the configured adapter', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/playground/search',
+      payload: {
+        origin: 'JFK',
+        destination: 'LAX',
+        date: '2026-08-15',
+        passengers: 1,
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      offers: unknown[];
+      totalFound: number;
+      sources: string[];
+      duration_ms: number;
+    };
+    expect(Array.isArray(body.offers)).toBe(true);
+    expect(body.totalFound).toBe(body.offers.length);
+    expect(typeof body.duration_ms).toBe('number');
+  });
+
+  it('rejects malformed origin via AJV body schema', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/playground/search',
+      payload: { origin: 'JF', destination: 'LAX', date: '2026-08-15', passengers: 1 },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+});
+
+describe('POST /api/playground/agent', () => {
+  it('executes the AirportCodeResolver (whitelisted)', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/playground/agent',
+      payload: {
+        agent_id: '0.1',
+        input: { code: 'JFK', code_type: 'iata' },
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as {
+      agent_id: string;
+      output: { data: { resolved_airport: { iata_code: string | null } | null } };
+      duration_ms: number;
+    };
+    expect(body.agent_id).toBe('0.1');
+    expect(body.output.data.resolved_airport?.iata_code).toBe('JFK');
+  }, 30_000);
+
+  it('returns 501 with a clear message for unwired agents', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/playground/agent',
+      payload: { agent_id: '99.99', input: {} },
+    });
+    expect(res.statusCode).toBe(501);
+    const body = res.json() as { error: string; agent_id: string; hint: string };
+    expect(body.agent_id).toBe('99.99');
+    expect(body.error).toContain('not yet wired');
+    expect(body.hint).toContain('executable_ids');
+  });
+});
+
+describe('POST /api/playground/adapter', () => {
+  it('runs the adapter health check', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/playground/adapter',
+      payload: { operation: 'isAvailable' },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { operation: string; output: boolean };
+    expect(body.operation).toBe('isAvailable');
+    expect(typeof body.output).toBe('boolean');
+  });
+
+  it('rejects an unknown operation', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/playground/adapter',
+      payload: { operation: 'book' },
+    });
+    expect(res.statusCode).toBe(400);
+  });
+});

examples/ota/src/routes/platform.ts

@@ -0,0 +1,32 @@
+/**
+ * GET /api/platform/* — read-only telemetry for the Platform UI dashboard.
+ *
+ * Routes are registered with a high per-route rate limit (5 000/min) so
+ * dashboard polling cannot trip the global default 100/min cap.
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { PlatformService } from '../services/platform-service.js';
+
+const HIGH_RATE_LIMIT = { max: 5_000, timeWindow: '1 minute' };
+
+export function registerPlatformRoutes(
+  app: FastifyInstance,
+  platform: PlatformService,
+): void {
+  app.get('/api/platform/agents', { config: { rateLimit: HIGH_RATE_LIMIT } }, async (_req, reply) => {
+    return reply.send(platform.agents());
+  });
+
+  app.get('/api/platform/adapters', { config: { rateLimit: HIGH_RATE_LIMIT } }, async (_req, reply) => {
+    return reply.send({ adapters: platform.adapters() });
+  });
+
+  app.get('/api/platform/health', { config: { rateLimit: HIGH_RATE_LIMIT } }, async (_req, reply) => {
+    return reply.send(platform.health());
+  });
+
+  app.get('/api/platform/stats', { config: { rateLimit: HIGH_RATE_LIMIT } }, async (_req, reply) => {
+    return reply.send(platform.stats());
+  });
+}