@mettlecast/domain-cli 0.2.0

package/src/templates/patterns/api/idempotent-mutation.ts

@@ -0,0 +1,102 @@
+/**
+ * Idempotent-mutation API pattern template.
+ * Produces: PUT with idempotency key middleware.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function idempotentMutationTemplate(domain: string, id: string, tenancy: string): string {
+  const varName = camelCase(id);
+  const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+
+// ── Idempotency key header ───────────────────────────────────
+
+const IdempotencyKey = z.string().min(1);
+
+// ── Zod schemas ──────────────────────────────────────────────
+
+const ${varName}Input = z.object({
+  id: z.string().uuid(),
+  payload: z.record(z.unknown()),
+});
+
+const ${varName}Output = z.object({
+  id: z.string().uuid(),
+  status: z.enum(['applied', 'already-processed']),
+  idempotencyKey: z.string(),
+});
+
+// ── API definition ───────────────────────────────────────────
+
+export const ${varName} = defineApi({
+  id: '${id}',
+  path: '${tenantPath}/${domain}/${id}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: ${varName}Input,
+      output: ${varName}Output,
+      handler: async (input, ctx) => {
+        // ── Extract idempotency key from headers ──────────────
+        const idempotencyKey = ctx.headers?.['x-idempotency-key'];
+        if (!idempotencyKey) {
+          throw new Error('Missing x-idempotency-key header');
+        }
+        IdempotencyKey.parse(idempotencyKey);
+
+        // ── Check for duplicate ───────────────────────────────
+        const existing = await ctx.db.get({
+          key: { pk: 'IDEMPOTENCY', sk: idempotencyKey },
+        });
+
+        if (existing) {
+          await ctx.auditLog({
+            action: '${id}.idempotent.duplicate',
+            tenantId: ctx.tenantId,
+            meta: { idempotencyKey },
+          });
+          return {
+            id: existing.entityId as string,
+            status: 'already-processed',
+            idempotencyKey,
+          };
+        }
+
+        // ── Apply mutation ────────────────────────────────────
+        const result = await ctx.db.put({
+          pk: '${id.toUpperCase()}',
+          sk: input.id,
+          payload: input.payload,
+        });
+
+        // ── Record idempotency token ──────────────────────────
+        await ctx.db.put({
+          key: { pk: 'IDEMPOTENCY', sk: idempotencyKey },
+          entityId: input.id,
+          ttl: Math.floor(Date.now() / 1000) + 86400, // 24h TTL
+        });
+
+        await ctx.auditLog({
+          action: '${id}.idempotent.applied',
+          tenantId: ctx.tenantId,
+          entityId: input.id,
+          meta: { idempotencyKey },
+        });
+
+        return {
+          id: input.id,
+          status: 'applied',
+          idempotencyKey,
+        };
+      },
+    },
+  },
+});
+`;
+}

package/src/templates/patterns/api/paginated-list.ts

@@ -0,0 +1,74 @@
+/**
+ * Paginated-list API pattern template.
+ * Produces: GET with cursor/limit, pagination contract, EMF metrics.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function paginatedListTemplate(domain: string, id: string, tenancy: string): string {
+  const varName = camelCase(id);
+  const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+
+// ── Pagination contract ──────────────────────────────────────
+
+const PageInput = z.object({
+  cursor: z.string().optional(),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(20),
+  filter: z.string().optional(),
+});
+
+const PageOutput = z.object({
+  items: z.array(z.object({ id: z.string().uuid() })),
+  nextCursor: z.string().optional(),
+  total: z.number().int().optional(),
+});
+
+// ── API definition ───────────────────────────────────────────
+
+export const ${varName} = defineApi({
+  id: '${id}',
+  path: '${tenantPath}/${domain}/${id}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: PageInput,
+      output: PageOutput,
+      handler: async (input, ctx) => {
+        const { cursor, limit, filter } = input;
+
+        // Emit EMF (Embedded Metric Format) metrics
+        ctx.metrics?.putMetric('${id}.pageRequest', 1, 'Count');
+        ctx.metrics?.putMetric('${id}.pageSize', limit, 'Count');
+
+        await ctx.auditLog({
+          action: '${id}.list',
+          tenantId: ctx.tenantId,
+          meta: { cursor, limit },
+        });
+
+        // ── paginated data fetch ──────────────────────────────
+        const items: Array<{ id: string }> = [];
+        const nextCursor = items.length === limit ? btoa(items[items.length - 1].id) : undefined;
+
+        return {
+          items,
+          nextCursor,
+          total: undefined,
+        };
+      },
+    },
+  },
+});
+`;
+}

package/src/templates/patterns/api/simple-crud.ts

@@ -0,0 +1,100 @@
+/**
+ * Simple CRUD API pattern template.
+ * Produces: GET / POST / PUT / DELETE with Zod schemas and audit logging.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function simpleCrudTemplate(domain: string, id: string, tenancy: string): string {
+  const varName = camelCase(id);
+  const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+
+// ── Zod schemas ──────────────────────────────────────────────
+
+const ${varName}Input = z.object({
+  id: z.string().uuid().optional(),
+});
+
+const ${varName}Output = z.object({
+  id: z.string().uuid(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+const ${varName}ListOutput = z.object({
+  items: z.array(${varName}Output),
+  nextCursor: z.string().optional(),
+});
+
+// ── API definition ───────────────────────────────────────────
+
+export const ${varName} = defineApi({
+  id: '${id}',
+  path: '${tenantPath}/${domain}/${id}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: ${varName}Input,
+      output: ${varName}Output,
+      handler: async (input, ctx) => {
+        // Create / Read / Update / Delete based on method
+        await ctx.auditLog({ action: '${id}.v1', tenantId: ctx.tenantId, input });
+        return {
+          id: input.id ?? crypto.randomUUID(),
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        };
+      },
+    },
+  },
+});
+`;
+}
+
+export function simpleCrudListTemplate(domain: string, id: string, tenancy: string): string {
+  const varName = camelCase(id);
+  const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+
+const ${varName}ListInput = z.object({
+  cursor: z.string().optional(),
+  limit: z.number().int().min(1).max(100).default(20),
+});
+
+const ${varName}Output = z.object({
+  id: z.string().uuid(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+});
+
+const ${varName}ListOutput = z.object({
+  items: z.array(${varName}Output),
+  nextCursor: z.string().optional(),
+});
+
+export const ${varName}List = defineApi({
+  id: '${id}-list',
+  path: '${tenantPath}/${domain}/${id}-list',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: ${varName}ListInput,
+      output: ${varName}ListOutput,
+      handler: async (input, ctx) => {
+        await ctx.auditLog({ action: '${id}-list.v1', tenantId: ctx.tenantId });
+        return { items: [], nextCursor: undefined };
+      },
+    },
+  },
+});
+`;
+}

package/src/templates/patterns/api/system-admin.ts

@@ -0,0 +1,101 @@
+/**
+ * System-admin API pattern template.
+ * Produces: GET/POST with tenancy: 'system', no tenant context.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function systemAdminTemplate(domain: string, id: string, tenancy: string): string {
+  const varName = camelCase(id);
+
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+
+// ── Zod schemas ──────────────────────────────────────────────
+
+const ${varName}Input = z.object({
+  command: z.enum(['status', 'metrics', 'health']),
+  domainId: z.string().optional(),
+});
+
+const ${varName}Output = z.object({
+  ok: z.boolean(),
+  data: z.record(z.unknown()).optional(),
+});
+
+// ── System health input ──────────────────────────────────────
+
+const SystemHealthOutput = z.object({
+  status: z.enum(['healthy', 'degraded', 'down']),
+  uptime: z.number(),
+  domains: z.array(z.object({
+    id: z.string(),
+    status: z.enum(['healthy', 'degraded']),
+  })),
+});
+
+// ── API definitions ──────────────────────────────────────────
+
+export const ${varName} = defineApi({
+  id: '${id}',
+  path: '/system/${domain}/${id}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: ${varName}Input,
+      output: ${varName}Output,
+      handler: async (input, ctx) => {
+        await ctx.auditLog({
+          action: '${id}.system',
+          meta: { command: input.command },
+        });
+
+        switch (input.command) {
+          case 'status':
+            return {
+              ok: true,
+              data: { status: 'healthy', domains: [] },
+            };
+          case 'metrics':
+            return {
+              ok: true,
+              data: {
+                requestCount: 0,
+                errorCount: 0,
+                p99LatencyMs: 0,
+              },
+            };
+          case 'health':
+            return { ok: true, data: { status: 'healthy' } };
+          default:
+            return { ok: false };
+        }
+      },
+    },
+  },
+});
+
+export const ${varName}Health = defineApi({
+  id: '${id}-health',
+  path: '/system/${domain}/${id}-health',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: z.object({}).optional(),
+      output: SystemHealthOutput,
+      handler: async (_input, _ctx) => {
+        return {
+          status: 'healthy',
+          uptime: process.uptime(),
+          domains: [],
+        };
+      },
+    },
+  },
+});
+`;
+}

package/src/templates/patterns/api/webhook-receiver-style.ts

@@ -0,0 +1,128 @@
+/**
+ * Webhook-receiver-style API pattern template.
+ * Produces: POST with signature verification, provider enum.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function webhookReceiverStyleTemplate(domain: string, id: string, tenancy: string): string {
+  const varName = camelCase(id);
+
+  return `import { z } from 'zod';
+import { defineApi } from '@mettlecast/domain-runtime';
+import crypto from 'crypto';
+
+// ── Supported webhook providers ───────────────────────────────
+
+const ProviderEnum = z.enum([
+  'stripe',
+  'github',
+  'slack',
+  'custom',
+]);
+
+// ── Zod schemas ──────────────────────────────────────────────
+
+const ${varName}Input = z.object({
+  provider: ProviderEnum,
+  eventType: z.string().min(1),
+  payload: z.record(z.unknown()),
+  rawBody: z.string().optional(),
+});
+
+const ${varName}Output = z.object({
+  received: z.boolean(),
+  eventId: z.string().uuid(),
+  provider: ProviderEnum,
+});
+
+// ── Signature verification ────────────────────────────────────
+
+function verifySignature(
+  provider: z.infer<typeof ProviderEnum>,
+  payload: string,
+  signatureHeader: string,
+  secret: string,
+): boolean {
+  switch (provider) {
+    case 'stripe':
+      // Stripe uses HMAC-SHA256
+      return crypto.timingSafeEqual(
+        Buffer.from(signatureHeader),
+        crypto.createHmac('sha256', secret).update(payload).digest(),
+      );
+    case 'github':
+      // GitHub uses HMAC-SHA256 with 'sha256=' prefix
+      const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');
+      return crypto.timingSafeEqual(
+        Buffer.from(signatureHeader),
+        Buffer.from(expected),
+      );
+    case 'slack':
+      // Slack uses HMAC-SHA256 with 'v0=' prefix
+      const slackExpected = 'v0=' + crypto.createHmac('sha256', secret).update(payload).digest('hex');
+      return crypto.timingSafeEqual(
+        Buffer.from(signatureHeader),
+        Buffer.from(slackExpected),
+      );
+    default:
+      return true; // custom provider — verify externally
+  }
+}
+
+// ── API definition ───────────────────────────────────────────
+
+export const ${varName} = defineApi({
+  id: '${id}',
+  path: '/webhooks/${domain}/${id}',
+  tenancy: '${tenancy}',
+  versions: {
+    v1: {
+      status: 'stable',
+      input: ${varName}Input,
+      output: ${varName}Output,
+      handler: async (input, ctx) => {
+        // ── Retrieve webhook secret ───────────────────────────
+        const secret = await ctx.secrets.get(
+          '${domain.toUpperCase()}_WEBHOOK_SECRET',
+          { provider: input.provider },
+        );
+
+        // ── Verify signature ──────────────────────────────────
+        const signatureHeader = ctx.headers?.['x-webhook-signature'] ?? '';
+        const rawPayload = input.rawBody ?? JSON.stringify(input.payload);
+
+        if (!verifySignature(input.provider, rawPayload, signatureHeader, secret)) {
+          throw new Error('Invalid webhook signature');
+        }
+
+        const eventId = crypto.randomUUID();
+
+        // ── Publish event for downstream processing ───────────
+        await ctx.publish('${domain}.webhook.received', {
+          eventId,
+          provider: input.provider,
+          eventType: input.eventType,
+          payload: input.payload,
+          tenantId: ctx.tenantId,
+        }, 1);
+
+        await ctx.auditLog({
+          action: '${id}.webhook.received',
+          tenantId: ctx.tenantId,
+          meta: { provider: input.provider, eventType: input.eventType, eventId },
+        });
+
+        return {
+          received: true,
+          eventId,
+          provider: input.provider,
+        };
+      },
+    },
+  },
+});
+`;
+}