create-spatius-app 0.1.2 → 0.1.3-beta.2

package/templates/layers/agora/worker/agora.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createAgoraSession,
+  stopAgoraSession,
+  type AgoraEnvironment,
+} from './agora.js';
+const env: AgoraEnvironment = {
+  AGORA_APP_ID: 'a'.repeat(32),
+  AGORA_APP_CERTIFICATE: 'b'.repeat(32),
+  AGORA_PIPELINE_ID: 'test-pipeline',
+  SPATIUS_API_KEY: 'private-key',
+  SPATIUS_APP_ID: 'test-app',
+  SPATIUS_AVATAR_ID: 'test-avatar',
+  SPATIUS_REGION: 'cn-beijing',
+  AGORA_AVATAR_SAMPLE_RATE: '24000',
+};
+describe('hosted Agora sessions', () => {
+  it('keeps secrets server-side and authorizes idempotent cleanup', async () => {
+    const fetcher = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(Response.json({ agent_id: 'hosted-agent' }))
+      .mockResolvedValueOnce(new Response(null, { status: 404 }));
+    const session = await createAgoraSession(env, fetcher);
+    expect(session.uid).not.toBe(session.agentUid);
+    expect(JSON.stringify(session)).not.toContain(env.AGORA_APP_CERTIFICATE);
+    expect(JSON.stringify(session)).not.toContain(env.SPATIUS_API_KEY);
+    const body = JSON.parse(fetcher.mock.calls[0][1]!.body as string) as {
+      pipeline_id: string;
+      properties: {
+        agent_rtc_uid: string;
+        remote_rtc_uids: string[];
+        avatar: { params: { agora_uid: string; sample_rate: number } };
+      };
+    };
+    expect(body.pipeline_id).toBe('test-pipeline');
+    expect(body.properties.remote_rtc_uids).toEqual([String(session.uid)]);
+    expect(body.properties.agent_rtc_uid).toBe(String(session.agentUid));
+    expect(body.properties.avatar.params.agora_uid).not.toBe(
+      String(session.uid),
+    );
+    expect(body.properties.avatar.params.sample_rate).toBe(24000);
+    await stopAgoraSession(env, session.capability, fetcher);
+    expect(fetcher.mock.calls[1][0]).toContain('/agents/hosted-agent/leave');
+    await expect(
+      stopAgoraSession(env, session.capability + 'bad', fetcher),
+    ).rejects.toThrow();
+    expect(fetcher).toHaveBeenCalledTimes(2);
+  });
+  it('validates configuration before starting a billable agent and redacts upstream errors', async () => {
+    const fetcher = vi.fn<typeof fetch>();
+    await expect(
+      createAgoraSession({ ...env, AGORA_AVATAR_SAMPLE_RATE: '123' }, fetcher),
+    ).rejects.toThrow('sample rate');
+    expect(fetcher).not.toHaveBeenCalled();
+    fetcher.mockResolvedValue(
+      Response.json({ error: env.SPATIUS_API_KEY }, { status: 400 }),
+    );
+    await expect(createAgoraSession(env, fetcher)).rejects.toThrow(
+      'Agora request failed (400)',
+    );
+  });
+});

package/templates/layers/agora/worker/agora.ts

@@ -0,0 +1,156 @@
+import { randomInt, randomUUID } from 'node:crypto';
+import agoraToken from 'agora-token';
+const { RtcTokenBuilder, RtcRole } = agoraToken;
+import { signCapability, verifyCapability } from './capability.js';
+export type AgoraEnvironment = CloudflareBindings;
+export class ConfigurationError extends Error {}
+function configuration(env: AgoraEnvironment) {
+  for (const key of [
+    'AGORA_APP_ID',
+    'AGORA_APP_CERTIFICATE',
+    'AGORA_PIPELINE_ID',
+    'SPATIUS_APP_ID',
+    'SPATIUS_API_KEY',
+    'SPATIUS_AVATAR_ID',
+  ] as const)
+    if (!env[key] || env[key].startsWith('your-'))
+      throw new ConfigurationError(`Missing ${key}`);
+  if (
+    !/^[a-f\d]{32}$/i.test(env.AGORA_APP_ID) ||
+    !/^[a-f\d]{32}$/i.test(env.AGORA_APP_CERTIFICATE)
+  )
+    throw new ConfigurationError(
+      'Agora App ID and certificate must be 32 hexadecimal characters.',
+    );
+  const rate = Number(env.AGORA_AVATAR_SAMPLE_RATE ?? 24000);
+  if (![8000, 16000, 22050, 24000, 32000, 44100, 48000].includes(rate))
+    throw new ConfigurationError('Unsupported avatar sample rate.');
+  return rate;
+}
+function rtcToken(
+  env: AgoraEnvironment,
+  channel: string,
+  uid: number,
+  seconds = 1800,
+) {
+  return RtcTokenBuilder.buildTokenWithUid(
+    env.AGORA_APP_ID,
+    env.AGORA_APP_CERTIFICATE,
+    channel,
+    uid,
+    RtcRole.PUBLISHER,
+    seconds,
+    seconds,
+  );
+}
+async function upstream(
+  env: AgoraEnvironment,
+  path: string,
+  body?: object,
+  fetcher: typeof fetch = fetch,
+) {
+  const response = await fetcher(
+    `https://api.agora.io/api/conversational-ai-agent/v2/projects/${env.AGORA_APP_ID}/${path}`,
+    {
+      method: 'POST',
+      headers: {
+        authorization: `agora token="${rtcToken(env, '', 1, 300)}"`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body ?? {}),
+      signal: AbortSignal.timeout(15000),
+    },
+  );
+  if (path.endsWith('/leave') && response.status === 404) return {};
+  if (!response.ok)
+    throw new Error(
+      `Agora request failed (${response.status}). Check the published pipeline and project configuration.`,
+    );
+  return (await response.json().catch(() => ({}))) as Record<string, unknown>;
+}
+export async function createAgoraSession(
+  env: AgoraEnvironment,
+  fetcher: typeof fetch = fetch,
+) {
+  const sampleRate = configuration(env);
+  const channel = `spatius-${randomUUID().replaceAll('-', '')}`;
+  const uid = randomInt(100000, 599999),
+    agentUid = randomInt(600000, 799999),
+    avatarUid = randomInt(800000, 999999);
+  const response = await upstream(
+    env,
+    'join',
+    {
+      name: channel,
+      pipeline_id: env.AGORA_PIPELINE_ID,
+      properties: {
+        channel,
+        agent_rtc_uid: String(agentUid),
+        token: rtcToken(env, channel, agentUid),
+        remote_rtc_uids: [String(uid)],
+        idle_timeout: 60,
+        advanced_features: { enable_rtm: true },
+        parameters: { data_channel: 'rtm', enable_error_message: true },
+        avatar: {
+          enable: true,
+          vendor: 'spatius',
+          params: {
+            spatius_api_key: env.SPATIUS_API_KEY,
+            spatius_app_id: env.SPATIUS_APP_ID,
+            spatius_avatar_id: env.SPATIUS_AVATAR_ID,
+            agora_uid: String(avatarUid),
+            agora_token: rtcToken(env, channel, avatarUid),
+            region: env.SPATIUS_REGION ?? 'cn-beijing',
+            sample_rate: sampleRate,
+            session_expire_minutes: 30,
+          },
+        },
+      },
+    },
+    fetcher,
+  );
+  if (typeof response.agent_id !== 'string' || !response.agent_id)
+    throw new Error('Agora returned an invalid session.');
+  const capability = await signCapability(
+    env.AGORA_APP_CERTIFICATE,
+    { purpose: 'agora-session', agent: response.agent_id },
+    3600,
+  );
+  return {
+    capability,
+    appId: env.AGORA_APP_ID,
+    channel,
+    uid,
+    agentUid,
+    token: RtcTokenBuilder.buildTokenWithRtm(
+      env.AGORA_APP_ID,
+      env.AGORA_APP_CERTIFICATE,
+      channel,
+      String(uid),
+      RtcRole.PUBLISHER,
+      1800,
+      1800,
+    ),
+    spatiusAppId: env.SPATIUS_APP_ID,
+    avatarId: env.SPATIUS_AVATAR_ID,
+    region: env.SPATIUS_REGION ?? 'cn-beijing',
+  };
+}
+export async function stopAgoraSession(
+  env: AgoraEnvironment,
+  capability: string,
+  fetcher: typeof fetch = fetch,
+) {
+  const claims = await verifyCapability(
+    env.AGORA_APP_CERTIFICATE,
+    capability,
+    'agora-session',
+  );
+  if (typeof claims.agent !== 'string') throw new Error('Invalid session');
+  await upstream(
+    env,
+    `agents/${encodeURIComponent(claims.agent)}/leave`,
+    {},
+    fetcher,
+  );
+}

package/templates/layers/agora/worker/index.test.ts

@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import worker from './index.js';
+
+const env: CloudflareBindings = {
+  AGORA_APP_ID: 'a'.repeat(32),
+  AGORA_APP_CERTIFICATE: 'b'.repeat(32),
+  AGORA_PIPELINE_ID: 'test-pipeline',
+  SPATIUS_API_KEY: 'private-key',
+  SPATIUS_APP_ID: 'test-app',
+  SPATIUS_AVATAR_ID: 'test-avatar',
+  SPATIUS_REGION: 'cn-beijing',
+  AGORA_AVATAR_SAMPLE_RATE: '24000',
+};
+const request = (path: string, method = 'GET', body?: object) =>
+  new Request(`https://app.example${path}`, {
+    method,
+    ...(body ? { body: JSON.stringify(body) } : {}),
+  });
+afterEach(() => vi.unstubAllGlobals());
+describe('Cloudflare Agora API', () => {
+  it('serves health and rejects unknown routes and unsupported methods', async () => {
+    expect(
+      await (await worker.fetch(request('/api/health'), env)).json(),
+    ).toEqual({ ok: true });
+    expect((await worker.fetch(request('/api/missing'), env)).status).toBe(404);
+    expect((await worker.fetch(request('/api/session'), env)).status).toBe(405);
+    expect(
+      (await worker.fetch(request('/api/health', 'POST'), env)).status,
+    ).toBe(405);
+  });
+  it('uses Worker bindings to create and stop hosted sessions without leaking secrets', async () => {
+    const fetcher = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(Response.json({ agent_id: 'hosted-agent' }))
+      .mockResolvedValueOnce(new Response(null, { status: 404 }));
+    vi.stubGlobal('fetch', fetcher);
+    const response = await worker.fetch(request('/api/session', 'POST'), env);
+    expect(response.status).toBe(201);
+    expect(response.headers.get('cache-control')).toBe('no-store');
+    const session = await response.json<{ capability: string }>();
+    expect(JSON.stringify(session)).not.toContain(env.AGORA_APP_CERTIFICATE);
+    expect(JSON.stringify(session)).not.toContain(env.SPATIUS_API_KEY);
+    expect(
+      (await worker.fetch(request('/api/session/stop', 'POST', session), env))
+        .status,
+    ).toBe(200);
+    expect(fetcher).toHaveBeenCalledTimes(2);
+  });
+  it('fails missing configuration and invalid stop authorization before contacting Agora', async () => {
+    const fetcher = vi.fn<typeof fetch>();
+    vi.stubGlobal('fetch', fetcher);
+    expect(
+      (
+        await worker.fetch(request('/api/session', 'POST'), {
+          ...env,
+          AGORA_APP_CERTIFICATE: '',
+        })
+      ).status,
+    ).toBe(503);
+    expect(
+      (await worker.fetch(request('/api/session/stop', 'POST', {}), env))
+        .status,
+    ).toBe(403);
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+});

package/templates/layers/agora/worker/index.ts

@@ -0,0 +1,54 @@
+import {
+  ConfigurationError,
+  createAgoraSession,
+  stopAgoraSession,
+  type AgoraEnvironment,
+} from './agora.js';
+export async function handleRequest(
+  request: Request,
+  env: AgoraEnvironment,
+): Promise<Response> {
+  const path = new URL(request.url).pathname;
+  const json = (value: unknown, status = 200) =>
+    Response.json(value, { status, headers: { 'cache-control': 'no-store' } });
+  if (path === '/api/health')
+    return request.method === 'GET'
+      ? json({ ok: true })
+      : json({ error: 'Method not allowed' }, 405);
+  if (!['/api/session', '/api/session/stop'].includes(path))
+    return json({ error: 'Not found' }, 404);
+  if (request.method !== 'POST')
+    return json({ error: 'Method not allowed' }, 405);
+  try {
+    if (path === '/api/session')
+      return json(await createAgoraSession(env), 201);
+    const body: unknown = await request.json();
+    if (
+      !body ||
+      typeof body !== 'object' ||
+      !('capability' in body) ||
+      typeof body.capability !== 'string'
+    )
+      return json({ error: 'Missing session authorization' }, 403);
+    await stopAgoraSession(env, body.capability);
+    return json({ ok: true });
+  } catch (error) {
+    return json(
+      {
+        error:
+          error instanceof ConfigurationError
+            ? 'Configure the Agora pipeline and Spatius credentials before starting.'
+            : 'The session request failed. Please try again.',
+      },
+      error instanceof ConfigurationError
+        ? 503
+        : path.endsWith('/stop')
+          ? 403
+          : 502,
+    );
+  }
+}
+
+export default {
+  fetch: handleRequest,
+} satisfies ExportedHandler<CloudflareBindings>;

package/templates/layers/agora/wrangler.jsonc

@@ -0,0 +1,24 @@
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "spatius-agora-app",
+  "main": "./worker/index.ts",
+  "compatibility_date": "2026-09-11",
+  "compatibility_flags": ["nodejs_compat"],
+  "vars": {
+    "AGORA_APP_ID": "your-agora-app-id",
+    "AGORA_PIPELINE_ID": "your-published-pipeline-id",
+    "SPATIUS_APP_ID": "your-spatius-app-id",
+    "SPATIUS_AVATAR_ID": "your-spatius-avatar-id",
+    "SPATIUS_REGION": "cn-beijing",
+    "AGORA_AVATAR_SAMPLE_RATE": "24000",
+  },
+  "secrets": {
+    "required": ["AGORA_APP_CERTIFICATE", "SPATIUS_API_KEY"],
+  },
+  "assets": {
+    "not_found_handling": "single-page-application",
+    "run_worker_first": ["/api/*"],
+  },
+  "observability": { "enabled": true, "head_sampling_rate": 1 },
+  "upload_source_maps": true,
+}

package/templates/layers/catalog/DEPLOYMENT.md

@@ -0,0 +1,3 @@
+# Deployment
+
+**SPATIUS_DEPLOYMENT**

package/templates/layers/catalog/spatius.config.json

@@ -0,0 +1 @@
+{ "version": 2, "stack": "cloudflare-livekit" }