@ysk-kit/cli 1.0.0

package/templates/capabilities/billing/apps/web/src/features/orgs/billing-page.tsx

@@ -0,0 +1,183 @@
+import { BILLING_PLANS } from '@ysk-kit/contracts';
+import {
+  Button,
+  Input,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@ysk-kit/ui';
+import { formatHkd, orgRoleCan } from '@ysk-kit/ui-logic';
+import { createBillingHooks, createOrganizationHooks } from '@ysk-kit/web-sdk';
+import { type FormEvent, useState } from 'react';
+import { api, userHooks } from '../../lib/client';
+
+const orgHooks = createOrganizationHooks(api);
+const billingHooks = createBillingHooks(api);
+
+export function BillingPage({ organizationId }: { organizationId: string }) {
+  const me = userHooks.useMe();
+  const members = orgHooks.useOrganizationMembers(organizationId);
+  const myRole = members.data?.find((row) => row.userId === me.data?.id)?.role;
+  const canBill = myRole ? orgRoleCan(myRole, 'org.billing') : false;
+  const subscription = billingHooks.useSubscription(organizationId, canBill);
+  const invoices = billingHooks.useInvoices(organizationId, canBill);
+  const checkout = billingHooks.useCheckout();
+  const portal = billingHooks.useBillingPortal();
+  const cancel = billingHooks.useCancelSubscription();
+  const invoicePdf = billingHooks.useInvoicePdf();
+  const [seatCount, setSeatCount] = useState(1);
+  const [formError, setFormError] = useState<string | null>(null);
+
+  const onCheckout = (event: FormEvent) => {
+    event.preventDefault();
+    const pageUrl = `${window.location.origin}/orgs/${organizationId}/billing`;
+    setFormError(null);
+    checkout.mutate(
+      {
+        organizationId,
+        planCode: 'pro',
+        successUrl: pageUrl,
+        cancelUrl: pageUrl,
+        seatCount,
+      },
+      {
+        onSuccess: (data) => {
+          window.location.assign(data.url);
+        },
+        onError: (error) => setFormError(error.message),
+      },
+    );
+  };
+
+  if (members.isPending) {
+    return (
+      <section className="space-y-2">
+        <h1 className="text-2xl font-semibold">Billing</h1>
+        <p className="text-zinc-600">Loading…</p>
+      </section>
+    );
+  }
+
+  if (!canBill) {
+    return (
+      <section className="space-y-2">
+        <h1 className="text-2xl font-semibold">Billing</h1>
+        <p className="text-zinc-600">Billing is for organization owners and admins.</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="space-y-6">
+      <h1 className="text-2xl font-semibold">Billing</h1>
+      {formError ? <p className="text-sm text-red-600">{formError}</p> : null}
+      <p className="text-sm text-zinc-600">
+        Plan {subscription.data?.planCode ?? 'free'} · {subscription.data?.seatCount ?? 1} seats
+        {subscription.data?.currentPeriodEnd
+          ? ` · period ends ${subscription.data.currentPeriodEnd}`
+          : ''}
+      </p>
+      <ul className="text-sm text-zinc-600">
+        {BILLING_PLANS.map((plan) => (
+          <li key={plan.code}>
+            {plan.name} · {formatHkd(plan.amountHkdCents / 100)} / {plan.interval}
+          </li>
+        ))}
+      </ul>
+      <form onSubmit={onCheckout} className="flex flex-wrap items-end gap-3">
+        <label className="grid gap-1 text-sm" htmlFor="seat-count">
+          Seats
+          <Input
+            id="seat-count"
+            type="number"
+            min={1}
+            max={500}
+            value={seatCount}
+            onChange={(e) => setSeatCount(Number(e.target.value))}
+            required
+          />
+        </label>
+        <Button type="submit" disabled={checkout.isPending}>
+          Checkout Pro
+        </Button>
+      </form>
+      <div className="flex flex-wrap gap-2">
+        <Button
+          type="button"
+          variant="outline"
+          disabled={portal.isPending}
+          onClick={() =>
+            portal.mutate(
+              {
+                organizationId,
+                returnUrl: `${window.location.origin}/orgs/${organizationId}/billing`,
+              },
+              {
+                onSuccess: (data) => {
+                  window.location.assign(data.url);
+                },
+                onError: (error) => setFormError(error.message),
+              },
+            )
+          }
+        >
+          Customer portal
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          disabled={cancel.isPending}
+          onClick={() => {
+            if (!window.confirm('Cancel this subscription?')) return;
+            cancel.mutate({ organizationId }, { onError: (error) => setFormError(error.message) });
+          }}
+        >
+          Cancel
+        </Button>
+      </div>
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>Invoice</TableHead>
+            <TableHead>Status</TableHead>
+            <TableHead>Amount</TableHead>
+            <TableHead />
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {(invoices.data ?? []).map((invoice) => (
+            <TableRow key={invoice.id}>
+              <TableCell>{invoice.number ?? invoice.id}</TableCell>
+              <TableCell>{invoice.status}</TableCell>
+              <TableCell>{formatHkd(invoice.amountDue / 100)}</TableCell>
+              <TableCell>
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  disabled={invoicePdf.isPending}
+                  onClick={() =>
+                    invoicePdf.mutate(
+                      { id: invoice.id, organizationId },
+                      {
+                        onSuccess: (url) => {
+                          window.location.assign(url);
+                        },
+                        onError: (error) => setFormError(error.message),
+                      },
+                    )
+                  }
+                >
+                  PDF
+                </Button>
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </section>
+  );
+}

package/templates/capabilities/billing/packages/contracts/src/api/billing.ts

@@ -0,0 +1,85 @@
+import { initContract } from '@ts-rest/core';
+import { z } from 'zod';
+import {
+  BillingPlanDtoSchema,
+  CancelCommandSchema,
+  CheckoutCommandSchema,
+  CheckoutDtoSchema,
+  InvoiceDtoSchema,
+  OrganizationIdQuerySchema,
+  PortalCommandSchema,
+  SubscriptionDtoSchema,
+} from '../dto/billing';
+import { ErrSchema, OkSchema } from '../errors/envelope';
+
+const c = initContract();
+
+export const billingContract = c.router({
+  plans: {
+    method: 'GET',
+    path: '/v1/billing/plans',
+    responses: { 200: OkSchema(z.array(BillingPlanDtoSchema)) },
+    summary: 'List billing plans',
+  },
+  subscription: {
+    method: 'GET',
+    path: '/v1/billing/subscription',
+    query: OrganizationIdQuerySchema,
+    responses: {
+      200: OkSchema(SubscriptionDtoSchema),
+      401: ErrSchema,
+      403: ErrSchema,
+      422: ErrSchema,
+    },
+    summary: 'Current organization subscription',
+  },
+  checkout: {
+    method: 'POST',
+    path: '/v1/billing/checkout',
+    body: CheckoutCommandSchema,
+    responses: {
+      200: OkSchema(CheckoutDtoSchema),
+      401: ErrSchema,
+      403: ErrSchema,
+      422: ErrSchema,
+    },
+    summary: 'Start organization checkout',
+  },
+  cancel: {
+    method: 'POST',
+    path: '/v1/billing/cancel',
+    body: CancelCommandSchema,
+    responses: {
+      200: OkSchema(z.object({ canceled: z.literal(true) })),
+      401: ErrSchema,
+      403: ErrSchema,
+      422: ErrSchema,
+    },
+    summary: 'Cancel organization subscription',
+  },
+  invoices: {
+    method: 'GET',
+    path: '/v1/billing/invoices',
+    query: OrganizationIdQuerySchema,
+    responses: {
+      200: OkSchema(z.array(InvoiceDtoSchema)),
+      401: ErrSchema,
+      403: ErrSchema,
+      422: ErrSchema,
+    },
+    summary: 'List organization invoices',
+  },
+  portal: {
+    method: 'POST',
+    path: '/v1/billing/portal',
+    body: PortalCommandSchema,
+    responses: {
+      200: OkSchema(CheckoutDtoSchema),
+      401: ErrSchema,
+      403: ErrSchema,
+      409: ErrSchema,
+      422: ErrSchema,
+    },
+    summary: 'Open Stripe Customer Portal',
+  },
+});

package/templates/capabilities/billing/packages/contracts/src/dto/billing.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { BillingPlanCodeSchema, SubscriptionStatusSchema } from '../enums/billing-plan';
+
+export const BillingPlanDtoSchema = z.object({
+  code: BillingPlanCodeSchema,
+  name: z.string().min(1),
+  amountHkdCents: z.number().int().nonnegative(),
+  interval: z.literal('month'),
+});
+export type BillingPlanDto = z.infer<typeof BillingPlanDtoSchema>;
+
+export const SubscriptionDtoSchema = z.object({
+  planCode: BillingPlanCodeSchema,
+  status: SubscriptionStatusSchema,
+  currentPeriodEnd: z.iso.datetime().nullable(),
+  seatCount: z.number().int().positive(),
+});
+export type SubscriptionDto = z.infer<typeof SubscriptionDtoSchema>;
+
+export const OrganizationIdQuerySchema = z.object({
+  organizationId: z.string().uuid(),
+});
+export type OrganizationIdQuery = z.infer<typeof OrganizationIdQuerySchema>;
+
+export const CheckoutCommandSchema = z.object({
+  organizationId: z.string().uuid(),
+  planCode: BillingPlanCodeSchema,
+  successUrl: z.string().url(),
+  cancelUrl: z.string().url(),
+  seatCount: z.number().int().min(1).max(500).default(1),
+});
+export type CheckoutCommand = z.infer<typeof CheckoutCommandSchema>;
+
+export const CheckoutDtoSchema = z.object({
+  url: z.string().url(),
+});
+export type CheckoutDto = z.infer<typeof CheckoutDtoSchema>;
+
+export const PortalCommandSchema = z.object({
+  organizationId: z.string().uuid(),
+  returnUrl: z.string().url(),
+});
+export type PortalCommand = z.infer<typeof PortalCommandSchema>;
+
+export const CancelCommandSchema = z.object({
+  organizationId: z.string().uuid(),
+});
+export type CancelCommand = z.infer<typeof CancelCommandSchema>;
+
+export const InvoiceDtoSchema = z.object({
+  id: z.string().min(1),
+  number: z.string().nullable(),
+  status: z.string().min(1),
+  amountDue: z.number().int(),
+  currency: z.string().min(1),
+  hostedInvoiceUrl: z.string().url().nullable(),
+  createdAt: z.iso.datetime(),
+});
+export type InvoiceDto = z.infer<typeof InvoiceDtoSchema>;

package/templates/capabilities/billing/packages/sdk/src/resources/billing.ts

@@ -0,0 +1,38 @@
+import type {
+  BillingPlanDto,
+  CancelCommand,
+  CheckoutCommand,
+  CheckoutDto,
+  InvoiceDto,
+  PortalCommand,
+  SubscriptionDto,
+} from '@ysk-kit/contracts';
+import type { HttpClient } from '../http';
+
+const withOrg = (path: string, organizationId: string): string =>
+  `${path}?organizationId=${encodeURIComponent(organizationId)}`;
+
+export const billingResource = (http: HttpClient) => ({
+  plans: () => http.request<BillingPlanDto[]>('/v1/billing/plans'),
+  subscription: (organizationId: string) =>
+    http.request<SubscriptionDto>(withOrg('/v1/billing/subscription', organizationId)),
+  invoices: (organizationId: string) =>
+    http.request<InvoiceDto[]>(withOrg('/v1/billing/invoices', organizationId)),
+  invoicePdfUrl: (id: string, organizationId: string) =>
+    http.requestLocation(withOrg(`/v1/billing/invoices/${id}/pdf`, organizationId)),
+  checkout: (body: CheckoutCommand) =>
+    http.request<CheckoutDto>('/v1/billing/checkout', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+  cancel: (body: CancelCommand) =>
+    http.request<{ canceled: true }>('/v1/billing/cancel', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+  portal: (body: PortalCommand) =>
+    http.request<CheckoutDto>('/v1/billing/portal', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    }),
+});

package/templates/capabilities/billing/packages/web-sdk/src/billing-hooks.ts

@@ -0,0 +1,56 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import type { CancelCommand, CheckoutCommand, PortalCommand } from '@ysk-kit/contracts';
+import type { YskClient } from '@ysk-kit/sdk';
+
+export const billingQueryKey = (organizationId: string) => ['billing', organizationId] as const;
+
+export function createBillingHooks(client: YskClient) {
+  return {
+    useBillingPlans: () =>
+      useQuery({
+        queryKey: ['billing-plans'],
+        queryFn: () => client.billing.plans(),
+      }),
+    useSubscription: (organizationId: string, enabled = true) =>
+      useQuery({
+        queryKey: [...billingQueryKey(organizationId), 'subscription'],
+        queryFn: () => client.billing.subscription(organizationId),
+        enabled: organizationId.length > 0 && enabled,
+        retry: false,
+      }),
+    useInvoices: (organizationId: string, enabled = true) =>
+      useQuery({
+        queryKey: [...billingQueryKey(organizationId), 'invoices'],
+        queryFn: () => client.billing.invoices(organizationId),
+        enabled: organizationId.length > 0 && enabled,
+        retry: false,
+      }),
+    useCheckout: () => {
+      const qc = useQueryClient();
+      return useMutation({
+        mutationFn: (body: CheckoutCommand) => client.billing.checkout(body),
+        onSuccess: (_data, body) => {
+          void qc.invalidateQueries({ queryKey: billingQueryKey(body.organizationId) });
+        },
+      });
+    },
+    useBillingPortal: () =>
+      useMutation({
+        mutationFn: (body: PortalCommand) => client.billing.portal(body),
+      }),
+    useCancelSubscription: () => {
+      const qc = useQueryClient();
+      return useMutation({
+        mutationFn: (body: CancelCommand) => client.billing.cancel(body),
+        onSuccess: (_data, body) => {
+          void qc.invalidateQueries({ queryKey: billingQueryKey(body.organizationId) });
+        },
+      });
+    },
+    useInvoicePdf: () =>
+      useMutation({
+        mutationFn: (args: { id: string; organizationId: string }) =>
+          client.billing.invoicePdfUrl(args.id, args.organizationId),
+      }),
+  };
+}

package/templates/capabilities/llm/apps/api/src/modules/llm/application/llm-service.ts

@@ -0,0 +1,48 @@
+import type { LlmCompleteCommand, LlmCompleteDto } from '@ysk-kit/contracts';
+import { AppError } from '@ysk-kit/domain-kernel';
+import type { ILlmPort } from '@ysk-kit/llm';
+import type { ILlmUsageRepository } from '../domain/usage-repository';
+
+export const createLlmService = (opts: {
+  llm: ILlmPort;
+  usage: ILlmUsageRepository;
+  configured: boolean;
+  production: boolean;
+}) => ({
+  models: () => ({ items: [{ id: opts.llm.model }] }),
+  complete: async (
+    userId: string,
+    body: LlmCompleteCommand,
+    requestId?: string,
+  ): Promise<LlmCompleteDto> => {
+    if (opts.production && !opts.configured) {
+      throw new AppError('INTERNAL', 'LLM not configured', 503);
+    }
+    const result = await opts.llm.complete(body);
+    await opts.usage.create({
+      userId,
+      model: result.model,
+      usage: result.usage,
+      requestId,
+    });
+    return result;
+  },
+  stream: async function* (userId: string, body: LlmCompleteCommand, requestId?: string) {
+    if (opts.production && !opts.configured) {
+      throw new AppError('INTERNAL', 'LLM not configured', 503);
+    }
+    for await (const chunk of opts.llm.stream(body)) {
+      if (chunk.done && chunk.usage) {
+        await opts.usage.create({
+          userId,
+          model: opts.llm.model,
+          usage: chunk.usage,
+          requestId,
+        });
+      }
+      yield chunk;
+    }
+  },
+});
+
+export type LlmService = ReturnType<typeof createLlmService>;

package/templates/capabilities/llm/apps/api/src/modules/llm/domain/usage-repository.ts

@@ -0,0 +1,10 @@
+import type { LlmUsage } from '@ysk-kit/contracts';
+
+export interface ILlmUsageRepository {
+  create(input: {
+    userId: string;
+    model: string;
+    usage: LlmUsage;
+    requestId?: string | undefined;
+  }): Promise<void>;
+}

package/templates/capabilities/llm/apps/api/src/modules/llm/infra/llm-router.ts

@@ -0,0 +1,88 @@
+import {
+  type HttpHandler,
+  mountContract,
+  requireAuth,
+  requirePermission,
+} from '@ysk-kit/api-express';
+import { appContract, type LlmCompleteCommand, LlmCompleteCommandSchema } from '@ysk-kit/contracts';
+import { AppError } from '@ysk-kit/domain-kernel';
+import type { Express } from 'express';
+import type { LlmService } from '../application/llm-service';
+
+export const llmHandlers = (service: LlmService): Record<string, HttpHandler> => ({
+  complete: {
+    auth: 'required',
+    permission: 'llm.use',
+    handle: async ({ body, auth, requestId }) => {
+      if (!auth) throw new AppError('UNAUTHENTICATED');
+      return {
+        status: 200,
+        body: {
+          ok: true,
+          data: await service.complete(auth.sub, body as LlmCompleteCommand, requestId),
+        },
+      };
+    },
+  },
+  models: {
+    auth: 'required',
+    permission: 'llm.use',
+    handle: async () => ({
+      status: 200,
+      body: { ok: true, data: service.models() },
+    }),
+  },
+});
+
+export const writeLlmSse = async (
+  service: LlmService,
+  userId: string,
+  command: LlmCompleteCommand,
+  requestId: string,
+  write: (chunk: string) => void,
+  end: () => void,
+): Promise<void> => {
+  for await (const chunk of service.stream(userId, command, requestId)) {
+    const event = chunk.done ? 'done' : 'delta';
+    write(`event: ${event}\ndata: ${JSON.stringify(chunk)}\n\n`);
+  }
+  end();
+};
+
+export const registerLlmRoutes = (app: Express, service: LlmService): void => {
+  mountContract(app, appContract.llm, llmHandlers(service));
+
+  app.post('/v1/llm/stream', requireAuth, requirePermission('llm.use'), async (req, res, next) => {
+    try {
+      const parsed = LlmCompleteCommandSchema.parse(req.body);
+      const userId = req.auth?.sub;
+      if (!userId) {
+        res.status(401).json({
+          ok: false,
+          error: { code: 'UNAUTHENTICATED', message: '尚未登入' },
+        });
+        return;
+      }
+      res.status(200);
+      res.setHeader('content-type', 'text/event-stream');
+      res.setHeader('cache-control', 'no-cache, no-transform');
+      res.setHeader('connection', 'keep-alive');
+      res.setHeader('x-accel-buffering', 'no');
+      res.flushHeaders?.();
+      await writeLlmSse(
+        service,
+        userId,
+        parsed,
+        String(req.headers['x-request-id'] ?? ''),
+        (chunk) => {
+          res.write(chunk);
+        },
+        () => {
+          res.end();
+        },
+      );
+    } catch (error) {
+      next(error);
+    }
+  });
+};

package/templates/capabilities/llm/apps/api/src/modules/llm/infra/llm.app.test.ts

@@ -0,0 +1,89 @@
+import request from 'supertest';
+import { describe, expect, it } from 'vitest';
+import { createApp } from '../../../app';
+import { createMemoryInput } from '../../../create-memory-input';
+
+describe('llm http', () => {
+  it('completes llm as a signed-in user and records usage', async () => {
+    const mem = createMemoryInput();
+    const app = createApp(mem.input);
+    const registered = await request(app).post('/v1/auth/register').send({
+      email: 'dev@ysk.hk',
+      password: 'password1',
+      displayName: 'Ki',
+    });
+    const token = registered.body.data.accessToken as string;
+    const res = await request(app)
+      .post('/v1/llm/complete')
+      .set('authorization', `Bearer ${token}`)
+      .send({ messages: [{ role: 'user', content: 'ping' }] });
+    expect(res.status).toBe(200);
+    expect(res.body.data.text).toBe('pong');
+    expect(mem.usage.rows).toHaveLength(1);
+  });
+
+  it('rejects llm without a token', async () => {
+    const app = createApp(createMemoryInput().input);
+    const res = await request(app)
+      .post('/v1/llm/complete')
+      .send({ messages: [{ role: 'user', content: 'ping' }] });
+    expect(res.status).toBe(401);
+  });
+
+  it('streams llm deltas then done', async () => {
+    const app = createApp(createMemoryInput().input);
+    const registered = await request(app).post('/v1/auth/register').send({
+      email: 'dev@ysk.hk',
+      password: 'password1',
+      displayName: 'Ki',
+    });
+    const token = registered.body.data.accessToken as string;
+    const res = await request(app)
+      .post('/v1/llm/stream')
+      .set('authorization', `Bearer ${token}`)
+      .send({ messages: [{ role: 'user', content: 'ping' }] });
+    expect(res.status).toBe(200);
+    expect(res.text).toContain('event: delta');
+    expect(res.text).toContain('event: done');
+  });
+
+  it('allows an API key with llm.use to complete', async () => {
+    const app = createApp(createMemoryInput().input);
+    const registered = await request(app).post('/v1/auth/register').send({
+      email: 'keys@ysk.hk',
+      password: 'password1',
+      displayName: 'Keys',
+    });
+    const jwt = registered.body.data.accessToken as string;
+    const created = await request(app)
+      .post('/v1/me/api-keys')
+      .set('authorization', `Bearer ${jwt}`)
+      .send({ name: 'ci', permissions: ['llm.use'] });
+    const token = created.body.data.token as string;
+    const llm = await request(app)
+      .post('/v1/llm/complete')
+      .set('authorization', `Bearer ${token}`)
+      .send({ messages: [{ role: 'user', content: 'ping' }] });
+    expect(llm.status).toBe(200);
+  });
+
+  it('forbids API keys without llm.use from completing', async () => {
+    const app = createApp(createMemoryInput().input);
+    const registered = await request(app).post('/v1/auth/register').send({
+      email: 'filekey@ysk.hk',
+      password: 'password1',
+      displayName: 'File',
+    });
+    const jwt = registered.body.data.accessToken as string;
+    const created = await request(app)
+      .post('/v1/me/api-keys')
+      .set('authorization', `Bearer ${jwt}`)
+      .send({ name: 'files', permissions: ['file.upload'] });
+    const token = created.body.data.token as string;
+    const llm = await request(app)
+      .post('/v1/llm/complete')
+      .set('authorization', `Bearer ${token}`)
+      .send({ messages: [{ role: 'user', content: 'ping' }] });
+    expect(llm.status).toBe(403);
+  });
+});

package/templates/capabilities/llm/apps/api/src/modules/llm/infra/memory-usage-repository.ts

@@ -0,0 +1,13 @@
+import type { ILlmUsageRepository } from '../domain/usage-repository';
+
+export const createMemoryLlmUsageRepository = (): ILlmUsageRepository & {
+  rows: Array<{ userId: string; model: string }>;
+} => {
+  const rows: Array<{ userId: string; model: string }> = [];
+  return {
+    rows,
+    async create(input) {
+      rows.push({ userId: input.userId, model: input.model });
+    },
+  };
+};