@bhooai/nexus-cli 0.1.0

package/templates/apps/backend/src/modules/ai/aiProxy.ts

@@ -0,0 +1,265 @@
+import type { Router } from '@bhooai/nexus-core';
+import { AiClient, type ChatCompletionRequest } from '@bhooai/nexus-ai-client';
+
+/**
+ * Mount OpenAI-compatible AI routes on the backend.
+ *
+ * The browser never calls external AI APIs directly — Node proxies:
+ *
+ *   - provider "together" → Together AI SDK (direct, API key from config)
+ *   - provider "openai"/"ollama" → Python AI server via @bhooai/nexus-ai-client
+ *   - any other configured OpenAI-compatible provider → direct fetch to its
+ *     baseUrl with the configured API key (so e.g. Groq/DeepSeek/Mistral list
+ *     their own models instead of falling back to the AI server's providers)
+ *
+ * Node re-emits the SSE stream chunk-by-chunk so CSRF + auth still apply.
+ *
+ * Routes (CSRF-protected like all unsafe methods):
+ *   POST /ai/chat/completions   (streaming or JSON)
+ *   POST /ai/embeddings
+ *   GET  /ai/models
+ */
+export interface AiProxyProvider {
+  id: string;
+  baseUrl?: string;
+  apiKey?: string;
+  enabled: boolean;
+}
+
+export function registerAiRoutes(router: Router, opts: {
+  serverUrl: string;
+  timeoutMs: number;
+  authToken?: string;
+  /** Live AI providers array from config (shared reference — updated in-place
+   *  by the admin provider management endpoints, so API key changes are visible
+   *  here without restarting). */
+  providers?: Array<AiProxyProvider>;
+}): AiClient {
+  const client = new AiClient({ serverUrl: opts.serverUrl, timeoutMs: opts.timeoutMs, authToken: opts.authToken });
+
+  // Find a configured, enabled provider (case-insensitive on the id).
+  const findProvider = (id?: string): AiProxyProvider | undefined => {
+    if (!id) return undefined;
+    return opts.providers?.find((p) => p.id.toLowerCase() === id.toLowerCase() && p.enabled);
+  };
+
+  // Resolve the Together AI key from the live providers array (not a snapshot).
+  const resolveTogetherKey = (): string | undefined => {
+    if (opts.providers?.find((p) => p.id === 'together' && p.enabled)?.apiKey) {
+      return opts.providers.find((p) => p.id === 'together' && p.enabled)?.apiKey;
+    }
+    return process.env.TOGETHER_API_KEY;
+  };
+
+  // Together SDK is optional — lazy-load it so scaffolded projects without
+  // together-ai installed still boot (they'd need the key to use it anyway).
+  let togetherCtor: any = null;
+  const loadTogether = async (): Promise<any> => {
+    if (!togetherCtor) {
+      const mod = await import('together-ai');
+      togetherCtor = mod.default ?? mod;
+    }
+    return togetherCtor;
+  };
+
+  // Normalise a provider baseUrl to its OpenAI-compatible root (append /v1
+  // unless it already ends in a version segment like /v1).
+  const openAiBase = (baseUrl: string): string => {
+    const u = baseUrl.replace(/\/+$/, '');
+    return /\/v\d+(\/)?$/.test(u) ? u : `${u}/v1`;
+  };
+
+  const providerAuth = (p: AiProxyProvider) => (p.apiKey ? { authorization: `Bearer ${p.apiKey}` } : {});
+
+  /** Proxy a streaming chat request to an OpenAI-compatible provider, re-emitting SSE. */
+  const relayProviderStream = async (ctx: any, p: AiProxyProvider, req: ChatCompletionRequest): Promise<boolean> => {
+    ctx.res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+    try {
+      const upstream = await fetch(`${openAiBase(p.baseUrl ?? '')}/chat/completions`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...providerAuth(p) },
+        body: JSON.stringify({ model: req.model, messages: req.messages, stream: true }),
+      });
+      if (!upstream.ok || !upstream.body) {
+        const text = await upstream.text();
+        throw new Error(`provider responded with HTTP ${upstream.status} ${text.slice(0, 300)}`);
+      }
+      const reader = upstream.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (trimmed.startsWith('data: ')) ctx.res.write(`${trimmed}\n\n`);
+        }
+      }
+      ctx.res.write('data: [DONE]\n\n');
+    } catch (err) {
+      ctx.res.write(`data: ${JSON.stringify({ error: { message: String((err as Error)?.message ?? err) } })}\n\n`);
+    } finally {
+      if (!ctx.res.writableEnded) ctx.res.end();
+    }
+    return true;
+  };
+
+  // ── Chat completions: configured provider direct, Together SDK, or Python ──
+  router.post('/ai/chat/completions', async (ctx) => {
+    const req = (ctx.body ?? {}) as ChatCompletionRequest & { provider?: string };
+    const isTogether = (req as any).provider === 'together';
+
+    // ── Together AI direct SDK path ──
+    if (isTogether) {
+      const apiKey = resolveTogetherKey();
+      if (!apiKey) {
+        ctx.json({ error: { message: 'Together AI API key not configured. Set it in AI Providers or TOGETHER_API_KEY env var.' } }, 401);
+        return;
+      }
+      try {
+        const Together = await loadTogether();
+        const together = new Together({ apiKey });
+        if (req.stream) {
+          ctx.res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+          try {
+            const stream = await together.chat.completions.create({
+              model: req.model,
+              messages: req.messages.map((m) => ({ role: m.role as 'system' | 'user' | 'assistant', content: m.content })),
+              stream: true,
+              ...(req.temperature != null ? { temperature: req.temperature } : {}),
+              ...(req.max_tokens != null ? { max_tokens: req.max_tokens } : {}),
+            } as any);
+            for await (const chunk of stream as any) ctx.res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+            ctx.res.write('data: [DONE]\n\n');
+          } catch (err: any) {
+            ctx.res.write(`data: ${JSON.stringify({ error: { message: err?.message ?? String(err) } })}\n\n`);
+          } finally {
+            if (!ctx.res.writableEnded) ctx.res.end();
+          }
+          return;
+        }
+        const result: any = await together.chat.completions.create({
+          model: req.model,
+          messages: req.messages.map((m) => ({ role: m.role as 'system' | 'user' | 'assistant', content: m.content })),
+          ...(req.temperature != null ? { temperature: req.temperature } : {}),
+          ...(req.max_tokens != null ? { max_tokens: req.max_tokens } : {}),
+        } as any);
+        if (result?.error) { ctx.json({ error: { message: String(result.error.message ?? result.error) } }, result.error.status ?? 502); return; }
+        ctx.json(result);
+      } catch (err: any) {
+        const status = err?.status ?? 502;
+        const message = String(err?.message ?? err?.error?.message ?? JSON.stringify(err));
+        const body = JSON.stringify({ error: { message, status } });
+        if (!ctx.res.headersSent) { ctx.res.statusCode = status; ctx.res.setHeader('content-type', 'application/json; charset=utf-8'); }
+        if (!ctx.res.writableEnded) ctx.res.end(body);
+      }
+      return;
+    }
+
+    // ── Other configured OpenAI-compatible providers (direct) ──
+    const cfgProvider = findProvider(req.provider);
+    if (cfgProvider && cfgProvider.baseUrl) {
+      if (req.stream) {
+        await relayProviderStream(ctx, cfgProvider, req);
+        return;
+      }
+      try {
+        const upstream = await fetch(`${openAiBase(cfgProvider.baseUrl)}/chat/completions`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...providerAuth(cfgProvider) },
+          body: JSON.stringify({ model: req.model, messages: req.messages }),
+        });
+        const data = await upstream.json().catch(() => ({}));
+        if (!upstream.ok) {
+          ctx.json({ error: { message: data?.error?.message ?? `provider responded with HTTP ${upstream.status}` } }, upstream.status === 401 ? 401 : 502);
+          return;
+        }
+        ctx.json(data);
+      } catch (err) {
+        ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, 502);
+      }
+      return;
+    }
+
+    // ── Default: proxy to the Python AI server ──
+    if (req.stream) {
+      ctx.res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+      try {
+        for await (const chunk of client.chatStream(req)) ctx.res.write(`data: ${JSON.stringify(chunk)}\n\n`);
+        ctx.res.write('data: [DONE]\n\n');
+      } catch (err) {
+        ctx.res.write(`data: ${JSON.stringify({ error: { message: String((err as Error)?.message ?? err) } })}\n\n`);
+      } finally {
+        if (!ctx.res.writableEnded) ctx.res.end();
+      }
+      return;
+    }
+    try {
+      ctx.json(await client.chat(req));
+    } catch (err) {
+      ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, (err as { status?: number })?.status ?? 502);
+    }
+  });
+
+  // ── Models: configured provider direct, Together SDK, or Python ──────────
+  router.get('/ai/models', async (ctx) => {
+    const provider = typeof ctx.query['provider'] === 'string' ? (ctx.query['provider'] as string) : undefined;
+
+    // Other configured OpenAI-compatible providers → list their own /models.
+    const cfgProvider = findProvider(provider);
+    if (cfgProvider && cfgProvider.baseUrl) {
+      try {
+        const upstream = await fetch(`${openAiBase(cfgProvider.baseUrl)}/models`, { headers: providerAuth(cfgProvider) });
+        const data = await upstream.json().catch(() => ({}));
+        if (!upstream.ok) {
+          ctx.json({ provider: cfgProvider.id, data: [], error: data?.error?.message ?? `provider responded with HTTP ${upstream.status}` });
+          return;
+        }
+        const models = Array.isArray(data?.data)
+          ? (data.data as any[]).map((m: any) => ({ id: String(m.id ?? m), owned_by: m.owned_by ?? cfgProvider.id }))
+          : [];
+        ctx.json({ provider: cfgProvider.id, data: models });
+      } catch (err) {
+        ctx.json({ provider: cfgProvider.id, data: [], error: String((err as Error)?.message ?? err) });
+      }
+      return;
+    }
+
+    if (provider === 'together') {
+      const apiKey = resolveTogetherKey();
+      if (!apiKey) {
+        ctx.json({ provider: 'together', data: [] });
+        return;
+      }
+      try {
+        const Together = await loadTogether();
+        const together = new Together({ apiKey });
+        const models = await together.models.list();
+        ctx.json({ provider: 'together', data: (models as any[])?.map((m: any) => ({ id: m.id, owned_by: m.owned_by ?? 'together' })) ?? [] });
+      } catch (err) {
+        ctx.json({ provider: 'together', data: [], error: String((err as Error)?.message ?? err) });
+      }
+      return;
+    }
+
+    try {
+      ctx.json(await client.listModels(provider));
+    } catch (err) {
+      ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, (err as { status?: number })?.status ?? 502);
+    }
+  });
+
+  router.post('/ai/embeddings', async (ctx) => {
+    const req = (ctx.body ?? {}) as { model: string; input: string | string[]; provider?: string };
+    try {
+      ctx.json(await client.embeddings(req));
+    } catch (err) {
+      ctx.json({ error: { message: String((err as Error)?.message ?? err) } }, (err as { status?: number })?.status ?? 502);
+    }
+  });
+
+  return client;
+}

package/templates/apps/backend/src/modules/auth/authRoutes.ts

@@ -0,0 +1,220 @@
+import { Router } from '@bhooai/nexus-core/http';
+import type { NexusConfig } from '@bhooai/nexus-core';
+import { ConflictError, AuthenticationError, ValidationError } from '@bhooai/nexus-core';
+import { ObjectId } from '@bhooai/nexus-data';
+import {
+  AuthService,
+  MemorySessionStore,
+  authToken,
+  requireAuth,
+  setAuthCookies,
+  clearAuthCookies,
+  readCookieValue,
+  hashPassword,
+  verifyPassword,
+  buildGoogleAuthUrl,
+  buildFacebookAuthUrl,
+  exchangeGoogleCode,
+  exchangeFacebookCode,
+  fetchGoogleProfile,
+  fetchFacebookProfile,
+  generateState,
+  generatePkceVerifier,
+  MemoryOAuthStateStore,
+  type GoogleOAuthConfig,
+  type FacebookOAuthConfig,
+} from '@bhooai/nexus-auth';
+import { initUserModel, getUserModel, findUserForLogin, upsertOAuthUser } from '../users/userModel.js';
+
+const sessions = new MemorySessionStore();
+const oauthState = new MemoryOAuthStateStore();
+
+function origin(config: NexusConfig): string {
+  const proto = config.server.https ? 'https' : 'http';
+  return `${proto}://${config.server.host === '0.0.0.0' ? 'localhost' : config.server.host}:${config.server.port}`;
+}
+
+function jwtOptions(config: NexusConfig) {
+  return {
+    secret: config.auth.jwt.secret,
+    algorithm: 'HS256' as const,
+    issuer: config.auth.jwt.issuer,
+    audience: config.auth.jwt.audience,
+    accessTtl: config.auth.jwt.accessTtl,
+    refreshTtl: config.auth.jwt.refreshTtl,
+  };
+}
+
+function authService(config: NexusConfig): AuthService {
+  return new AuthService(jwtOptions(config), sessions);
+}
+
+/** Register /auth/* routes onto the given router. Call after `connect()` + `initUserModel()`. */
+export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCreated?: () => void): void {
+  initUserModel();
+  const service = authService(config);
+
+  // POST /auth/register
+  router.post('/auth/register', async (ctx) => {
+    const body = (ctx.body ?? {}) as { email?: string; password?: string; name?: string };
+    if (!body.email || !body.password) throw new ValidationError('email and password are required');
+    if (body.password.length < 8) throw new ValidationError('password must be at least 8 characters');
+
+    const User = getUserModel();
+    const existing = await User.findOne({ email: body.email.toLowerCase() }).lean();
+    if (existing) throw new ConflictError('A user with that email already exists');
+
+    const passwordHash = await hashPassword(body.password);
+    // Bootstrap: the very first registered user becomes an admin.
+    const userCount = await User.countDocuments();
+    const roles = userCount === 0 ? ['admin'] : ['user'];
+    const [user] = await User.create({ email: body.email, name: body.name, passwordHash, roles });
+    // Notify subscribers (e.g. the GraphQL `userCount` subscription) if wired.
+    onUserCreated?.();
+    const pair = await service.login({ userId: String(user._id), roles: user.roles, meta: { ip: ctx.req.socket.remoteAddress } });
+    setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ user: publicUser(user), accessToken: pair.accessToken, refreshToken: pair.refreshToken });
+  });
+
+  // POST /auth/login
+  router.post('/auth/login', async (ctx) => {
+    const body = (ctx.body ?? {}) as { email?: string; password?: string };
+    if (!body.email || !body.password) throw new ValidationError('email and password are required');
+    const user = await findUserForLogin(body.email);
+    if (!user || !user.passwordHash) throw new AuthenticationError('Invalid email or password');
+    const ok = await verifyPassword(body.password, user.passwordHash);
+    if (!ok) throw new AuthenticationError('Invalid email or password');
+    const pair = await service.login({ userId: String(user._id), roles: user.roles });
+    setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ user: publicUser(user), accessToken: pair.accessToken, refreshToken: pair.refreshToken });
+  });
+
+  // POST /auth/refresh
+  router.post('/auth/refresh', async (ctx) => {
+    const body = (ctx.body ?? {}) as { refreshToken?: string };
+    const refreshToken = body.refreshToken ?? readCookieValue(ctx, config.auth.refreshCookieName);
+    if (!refreshToken) throw new AuthenticationError('Missing refresh token');
+    const pair = await service.refresh(refreshToken);
+    setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ accessToken: pair.accessToken, refreshToken: pair.refreshToken });
+  });
+
+  // POST /auth/logout
+  router.post('/auth/logout', async (ctx) => {
+    // Optional auth: end the session if a token is present, but never 401 on logout.
+    await authToken(service, { required: false, allowCookie: true, cookieName: config.auth.cookieName })(ctx, async () => {});
+    const sid = (ctx.state.user as { sid?: string } | undefined)?.sid;
+    if (sid) await service.logout(sid);
+    clearAuthCookies(ctx, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+    ctx.json({ ok: true });
+  });
+
+  // GET /auth/me
+  router.get('/auth/me', async (ctx) => {
+    const User = getUserModel();
+    const id = (ctx.state.user as { id: string }).id;
+    const user = await User.findById(id).lean();
+    ctx.json({ user: publicUser(user) });
+  }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
+
+  // PUT /auth/profile — update the signed-in user's display name.
+  router.put('/auth/profile', async (ctx) => {
+    const body = (ctx.body ?? {}) as { name?: string };
+    const name = typeof body.name === 'string' ? body.name.trim() : '';
+    if (!name) throw new ValidationError('name is required');
+    const id = (ctx.state.user as { id: string }).id;
+    const User = getUserModel();
+    await User.updateOne({ _id: id }, { $set: { name } });
+    const user = await User.findById(id).lean();
+    ctx.json({ ok: true, user: publicUser(user) });
+  }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
+
+  // POST /auth/change-password — verify the current password, then set a new one.
+  router.post('/auth/change-password', async (ctx) => {
+    const body = (ctx.body ?? {}) as { currentPassword?: string; newPassword?: string };
+    if (!body.currentPassword) throw new ValidationError('current password is required');
+    if (!body.newPassword || body.newPassword.length < 8) throw new ValidationError('password must be at least 8 characters');
+
+    const id = (ctx.state.user as { id: string }).id;
+    const User = getUserModel();
+    const coll = await User.collection;
+    const raw = await coll.findOne({ _id: new ObjectId(id) });
+    if (!raw) throw new AuthenticationError('User not found');
+    const passwordHash = raw.passwordHash as string | undefined;
+    if (!passwordHash) throw new AuthenticationError('This account has no password (OAuth account)');
+    const ok = await verifyPassword(body.currentPassword, passwordHash);
+    if (!ok) throw new AuthenticationError('Current password is incorrect');
+    const nextHash = await hashPassword(body.newPassword);
+    await User.updateOne({ _id: id }, { $set: { passwordHash: nextHash } });
+    ctx.json({ ok: true });
+  }, [authToken(service, { cookieName: config.auth.cookieName }), requireAuth()]);
+
+  // ── OAuth: Google ──────────────────────────────────────────────────────────
+  if (config.auth.google?.clientId) {
+    const google: GoogleOAuthConfig = {
+      clientId: config.auth.google.clientId,
+      clientSecret: config.auth.google.clientSecret,
+      redirectUri: `${origin(config)}${config.auth.google.callbackPath}`,
+      scope: config.auth.google.scope.split(/\s+/).filter(Boolean),
+    };
+    router.get('/auth/google', async (ctx) => {
+      const state = generateState();
+      const verifier = generatePkceVerifier();
+      await oauthState.set(state, { provider: 'google', verifier }, 5 * 60_000);
+      ctx.redirect(buildGoogleAuthUrl(google, { state, verifier }));
+    });
+    router.get(config.auth.google.callbackPath, async (ctx) => {
+      const code = ctx.query.code as string | undefined;
+      const state = ctx.query.state as string | undefined;
+      if (!code || !state) throw new AuthenticationError('Missing OAuth code/state');
+      const data = await oauthState.consume(state);
+      if (!data || data.provider !== 'google') throw new AuthenticationError('Invalid OAuth state');
+      const tokens = await exchangeGoogleCode(code, google, data.verifier as string);
+      const profile = await fetchGoogleProfile(tokens.accessToken);
+      const user = await upsertOAuthUser({ provider: 'google', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
+      const pair = await service.login({ userId: String(user._id), roles: user.roles });
+      setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+      ctx.json({ user: publicUser(user), accessToken: pair.accessToken });
+    });
+  }
+
+  // ── OAuth: Facebook ─────────────────────────────────────────────────────────
+  if (config.auth.facebook?.clientId) {
+    const facebook: FacebookOAuthConfig = {
+      clientId: config.auth.facebook.clientId,
+      clientSecret: config.auth.facebook.clientSecret,
+      redirectUri: `${origin(config)}${config.auth.facebook.callbackPath}`,
+      scope: config.auth.facebook.scope.split(/\s+/).filter(Boolean),
+    };
+    router.get('/auth/facebook', async (ctx) => {
+      const state = generateState();
+      await oauthState.set(state, { provider: 'facebook' }, 5 * 60_000);
+      ctx.redirect(buildFacebookAuthUrl(facebook, state));
+    });
+    router.get(config.auth.facebook.callbackPath, async (ctx) => {
+      const code = ctx.query.code as string | undefined;
+      const state = ctx.query.state as string | undefined;
+      if (!code || !state) throw new AuthenticationError('Missing OAuth code/state');
+      const data = await oauthState.consume(state);
+      if (!data || data.provider !== 'facebook') throw new AuthenticationError('Invalid OAuth state');
+      const tokens = await exchangeFacebookCode(code, facebook);
+      const profile = await fetchFacebookProfile(tokens.accessToken);
+      const user = await upsertOAuthUser({ provider: 'facebook', providerUserId: profile.providerUserId, email: profile.email, name: profile.name });
+      const pair = await service.login({ userId: String(user._id), roles: user.roles });
+      setAuthCookies(ctx, pair, { accessTokenName: config.auth.cookieName, refreshTokenName: config.auth.refreshCookieName });
+      ctx.json({ user: publicUser(user), accessToken: pair.accessToken });
+    });
+  }
+}
+
+function publicUser(user: unknown): Record<string, unknown> | null {
+  if (!user) return null;
+  // DocumentInstance → use toObject() (avoids spreading the Proxy and its circular _model).
+  // Plain objects (raw lean docs / JWT claims) → spread directly.
+  const obj =
+    (user as { toObject?: () => Record<string, unknown> }).toObject?.() ??
+    (user as Record<string, unknown>);
+  const u = { ...obj };
+  delete u.passwordHash;
+  return u;
+}

package/templates/apps/backend/src/modules/payments/paymentRoutes.ts

@@ -0,0 +1,100 @@
+import type { Router, NexusConfig } from '@bhooai/nexus-core';
+import type { PaymentsService } from '@bhooai/nexus-payments';
+import { authToken, type AuthService } from '@bhooai/nexus-auth';
+import { upsertOrder } from './paymentStore.js';
+
+/**
+ * Phase 11 — browser-facing checkout routes. The browser creates an order and
+ * (for hosted-checkout providers) is redirected to `paymentUrl`; for direct
+ * providers the client confirms capture via a second call. Webhooks remain the
+ * source of truth (mounted separately in main.ts).
+ *
+ * Routes:
+ *   POST /payments/order          — create an order with a named provider
+ *   POST /payments/order/:id/capture — capture an authorized order
+ *   GET  /payments/order/:id         — get order status (provider in query)
+ */
+export function registerPaymentRoutes(
+  router: Router,
+  config: NexusConfig,
+  payments: PaymentsService,
+  authService: AuthService,
+): void {
+  const guard = [authToken(authService, { cookieName: config.auth.cookieName, allowCookie: true })];
+
+  router.post(
+    '/payments/order',
+    async (ctx) => {
+      const body = ctx.body as { provider?: string; amount?: number; currency?: string; reference?: string; description?: string; returnUrl?: string; cancelUrl?: string } | undefined;
+      const providerName = (body?.provider ?? '').toLowerCase();
+      const provider = payments.providers.get(providerName);
+      if (!provider) {
+        ctx.json({ error: `Unknown or disabled provider: ${providerName}. Enabled: ${[...payments.providers.keys()].join(', ') || 'none'}` }, 400);
+        return;
+      }
+      if (typeof body?.amount !== 'number' || body.amount <= 0) {
+        ctx.json({ error: 'amount (major units, > 0) is required' }, 400);
+        return;
+      }
+      const origin = `http${config.server.https ? 's' : ''}://${ctx.headers.host}`;
+      let order;
+      try {
+        order = await provider.createOrder({
+          amount: body.amount,
+          currency: body.currency ?? 'USD',
+          reference: body.reference ?? `nx_${Date.now()}`,
+          description: body.description,
+          returnUrl: body.returnUrl ?? `${origin}/checkout/return`,
+          cancelUrl: body.cancelUrl ?? `${origin}/checkout/cancel`,
+        });
+      } catch (e) {
+        ctx.json({ error: `${providerName} order failed: ${(e as Error).message}` }, 502);
+        return;
+      }
+      await upsertOrder(order, providerName, {
+        customer: (body as Record<string, unknown>).customer as Record<string, unknown> | undefined,
+        description: body.description,
+      });
+      ctx.json({ provider: providerName, order });
+    },
+    guard,
+  );
+
+  router.post(
+    '/payments/order/:id/capture',
+    async (ctx) => {
+      const providerName = ((ctx.body as { provider?: string } | undefined)?.provider ?? '').toLowerCase();
+      const provider = payments.providers.get(providerName);
+      if (!provider) { ctx.json({ error: 'Unknown or disabled provider' }, 400); return; }
+      let order;
+      try {
+        order = await provider.capture({ orderId: ctx.params.id, amount: (ctx.body as { amount?: number } | undefined)?.amount } as any);
+      } catch (e) {
+        ctx.json({ error: `${providerName} capture failed: ${(e as Error).message}` }, 502);
+        return;
+      }
+      await upsertOrder(order, providerName);
+      ctx.json({ provider: providerName, order });
+    },
+    guard,
+  );
+
+  router.get(
+    '/payments/order/:id',
+    async (ctx) => {
+      const providerName = (ctx.query.provider ?? '').toString().toLowerCase();
+      const provider = payments.providers.get(providerName);
+      if (!provider) { ctx.json({ error: 'Unknown or disabled provider (pass ?provider=)' }, 400); return; }
+      let order;
+      try {
+        order = await provider.getOrderStatus(ctx.params.id);
+      } catch (e) {
+        ctx.json({ error: `${providerName} status failed: ${(e as Error).message}` }, 502);
+        return;
+      }
+      await upsertOrder(order, providerName);
+      ctx.json({ provider: providerName, order });
+    },
+    guard,
+  );
+}