@mettlecast/domain-cli 0.2.60 → 0.2.61

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

@@ -1,6 +1,10 @@
 /**
  * Paginated-list API pattern template.
  * Produces: GET with cursor/limit, pagination contract, EMF metrics.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 
 function camelCase(s: string): string {
@@ -10,10 +14,10 @@ function camelCase(s: string): string {
 export function paginatedListTemplate(domain: string, id: string, tenancy: string): string {
   const varName = camelCase(id);
   const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+  const authPosture = tenancy === 'system' ? 'service' : 'required';
 
   return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
-import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
 
@@ -38,34 +42,36 @@ const PageOutput = z.object({
   total: z.number().int().optional(),
 }).default({ items: [], nextCursor: undefined, total: undefined });
 
-// ── API definition ───────────────────────────────────────────
+// ── Action definition (API exposure) ─────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '${tenantPath}/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '${tenantPath}/${domain}/${id}',
+    method: 'GET',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: PageInput,
-      output: PageOutput,
-      handler: async (input, ctx) => {
-        const { cursor, limit, filter } = input;
+  idempotent: true,
+  input: PageInput,
+  output: PageOutput,
+  handler: async (input, ctx) => {
+    const { cursor, limit, filter } = input;
 
-        await ctx.audit.log('${id}.list', ctx.tenant.id, { cursor, limit });
+    await ctx.audit.log('${id}.list', ctx.tenant.id, { cursor, limit });
 
-        // ── paginated data fetch ──────────────────────────────
-        const items: Array<{ id: string }> = [];
-        const nextCursor = items.length === limit ? btoa(items[items.length - 1].id) : undefined;
+    // ── 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,
-        };
-      },
-    },
+    return {
+      items,
+      nextCursor,
+      total: undefined,
+    };
   },
 });
 `;
@@ -75,4 +81,4 @@ export const ${varName} = defineApi({
  * Example body string used as the event body in the add-api fixture for the
  * paginated-list pattern. Mirrors the default shape of the input schema.
  */
-export const paginatedListExampleBody = '{}';
+export const paginatedListExampleBody = '{}';

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

@@ -1,6 +1,10 @@
 /**
  * Simple CRUD API pattern template.
  * Produces: GET / POST / PUT / DELETE with Zod schemas and audit logging.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 
 function camelCase(s: string): string {
@@ -10,10 +14,10 @@ function camelCase(s: string): string {
 export function simpleCrudTemplate(domain: string, id: string, tenancy: string): string {
   const varName = camelCase(id);
   const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+  const authPosture = tenancy === 'system' ? 'service' : 'required';
 
   return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
-import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
 
@@ -40,28 +44,30 @@ const ${varName}ListOutput = z.object({
   nextCursor: z.string().optional(),
 }).default({ items: [], nextCursor: undefined });
 
-// ── API definition ───────────────────────────────────────────
+// ── Action definition (API exposure) ─────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '${tenantPath}/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '${tenantPath}/${domain}/${id}',
+    method: 'POST',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        // Create / Read / Update / Delete based on method
-        await ctx.audit.log('${id}.v1', ctx.tenant.id, { input });
-        return {
-          id: input.id ?? crypto.randomUUID(),
-          createdAt: new Date().toISOString(),
-          updatedAt: new Date().toISOString(),
-        };
-      },
-    },
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    // Create / Read / Update / Delete based on method
+    await ctx.audit.log('${id}.v1', ctx.tenant.id, { input });
+    return {
+      id: input.id ?? crypto.randomUUID(),
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
   },
 });
 `;
@@ -70,9 +76,12 @@ export const ${varName} = defineApi({
 export function simpleCrudListTemplate(domain: string, id: string, tenancy: string): string {
   const varName = camelCase(id);
   const tenantPath = tenancy === 'required' ? '/v1/tenants/{tenantId}' : '/v1';
+  const authPosture = tenancy === 'system' ? 'service' : 'required';
 
   return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
+
+initOtel();
 
 const ${varName}ListInput = z.object({
   cursor: z.string().optional(),
@@ -94,21 +103,23 @@ const ${varName}ListOutput = z.object({
   nextCursor: z.string().optional(),
 }).default({ items: [], nextCursor: undefined });
 
-export const ${varName}List = defineApi({
+export const ${varName}List = defineAction({
   id: '${id}-list',
-  path: '${tenantPath}/${domain}/${id}-list',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '${tenantPath}/${domain}/${id}-list',
+    method: 'GET',
+    auth: '${authPosture}',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}ListInput,
-      output: ${varName}ListOutput,
-      handler: async (input, ctx) => {
-        await ctx.audit.log('${id}-list.v1', ctx.tenant.id);
-        return { items: [], nextCursor: undefined };
-      },
-    },
+  idempotent: true,
+  input: ${varName}ListInput,
+  output: ${varName}ListOutput,
+  handler: async (input, ctx) => {
+    await ctx.audit.log('${id}-list.v1', ctx.tenant.id);
+    return { items: [], nextCursor: undefined };
   },
 });
 `;
@@ -118,4 +129,4 @@ export const ${varName}List = defineApi({
  * Example body string used as the event body in the add-api fixture for the
  * simple-crud pattern. Mirrors the default shape of the input schema.
  */
-export const simpleCrudExampleBody = '{}';
+export const simpleCrudExampleBody = '{}';

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

@@ -19,6 +19,10 @@
  *   - API Gateway HTTP API with 2.0 payload format (not REST API)
  *   - Lambda runtime v20+
  *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
+ *
  * @param domain - Domain ID in kebab-case
  * @param apiId - API ID in kebab-case
  * @param itemName - Singular item name (e.g. 'ticket', 'member')
@@ -26,7 +30,7 @@
  */
 export function streamingListPattern(domain: string, apiId: string, itemName: string) {
   return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
+import { defineAction } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 
 const ${itemName}Schema = z.object({ id: z.string() });
@@ -39,54 +43,55 @@ const outputSchema = z.object({
   nextCursor: z.string().optional(),
 }).default({ items: [] });
 
-export const ${apiId.replace(/-/g, '_')} = defineApi({
+export const ${apiId.replace(/-/g, '_')} = defineAction({
   id: '${apiId}',
-  path: '/v1/${domain}/${apiId}',
-  method: 'GET',
-  tenancy: 'required',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '/v1/tenants/{tenantId}/${domain}/${apiId}',
+    method: 'GET',
+    auth: 'required',
+    tenancy: 'required',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: inputSchema,
-      output: outputSchema,
-      handler: async (input, ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
-        // Streaming response: each item is yielded as a JSON line
-        // before the full query completes.  The runtime handler
-        // wrapper converts this generator into a chunked response.
-        //
-        //   GET /v1/${domain}/${apiId}?limit=100
-        //   Transfer-Encoding: chunked
-        //   Content-Type: application/x-ndjson
-        //
-        //   {"id":"1"}\\n
-        //   {"id":"2"}\\n
-        //   {"id":"3"}\\n
+  idempotent: true,
+  input: inputSchema,
+  output: outputSchema,
+  handler: async (input, ctx): Promise<Result<z.infer<typeof outputSchema>, AppError>> => {
+    // Streaming response: each item is yielded as a JSON line
+    // before the full query completes.  The runtime handler
+    // wrapper converts this generator into a chunked response.
+    //
+    //   GET /v1/${domain}/${apiId}?limit=100
+    //   Transfer-Encoding: chunked
+    //   Content-Type: application/x-ndjson
+    //
+    //   {"id":"1"}\\n
+    //   {"id":"2"}\\n
+    //   {"id":"3"}\\n
 
-        let nextCursor: string | undefined;
-        const items: unknown[] = [];
+    let nextCursor: string | undefined;
+    const items: unknown[] = [];
 
-        // Replace this query with your actual data source.
-        const rows = await ctx.db.query(
-          '${domain}',
-          'SELECT id FROM ${domain}s LIMIT $1 OFFSET $2',
-          [input.limit + 1, input.cursor ? parseInt(input.cursor, 10) : 0],
-        );
+    // Replace this query with your actual data source.
+    const rows = await ctx.db.query(
+      '${domain}',
+      'SELECT id FROM ${domain}s LIMIT $1 OFFSET $2',
+      [input.limit + 1, input.cursor ? parseInt(input.cursor, 10) : 0],
+    );
 
-        for (let i = 0; i < Math.min(rows.length, input.limit); i++) {
-          items.push(rows[i]);
-        }
+    for (let i = 0; i < Math.min(rows.length, input.limit); i++) {
+      items.push(rows[i]);
+    }
 
-        if (rows.length > input.limit) {
-          nextCursor = String(
-            (input.cursor ? parseInt(input.cursor, 10) : 0) + input.limit,
-          );
-        }
+    if (rows.length > input.limit) {
+      nextCursor = String(
+        (input.cursor ? parseInt(input.cursor, 10) : 0) + input.limit,
+      );
+    }
 
-        return { ok: true, value: { items, nextCursor } };
-      },
-    },
+    return { ok: true, value: { items, nextCursor } };
   },
 });
 `;
-}
+}

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

@@ -1,6 +1,10 @@
 /**
  * System-admin API pattern template.
  * Produces: GET/POST with tenancy: 'system', no tenant context.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 
 function camelCase(s: string): string {
@@ -11,8 +15,7 @@ export function systemAdminTemplate(domain: string, id: string, tenancy: string)
   const varName = camelCase(id);
 
   return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
-import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
 
@@ -30,7 +33,7 @@ const ${varName}Output = z.object({
   data: z.record(z.unknown()).optional(),
 }).default({ ok: true });
 
-// ── System health input ──────────────────────────────────────
+// ── System health output ─────────────────────────────────────
 
 const SystemHealthOutput = z.object({
   status: z.enum(['healthy', 'degraded', 'down']),
@@ -41,64 +44,68 @@ const SystemHealthOutput = z.object({
   })),
 }).default({ status: 'healthy', uptime: 0, domains: [] });
 
-// ── API definitions ──────────────────────────────────────────
+// ── Action definitions (API exposure) ────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '/system/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'platform',
+  exposure: {
+    type: 'api',
+    path: '/system/${domain}/${id}',
+    method: 'POST',
+    auth: 'service',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        await ctx.audit.log('${id}.system', 'system', { command: input.command });
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    await ctx.audit.log('${id}.system', 'system', { 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 };
-        }
-      },
-    },
+    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({
+export const ${varName}Health = defineAction({
   id: '${id}-health',
-  path: '/system/${domain}/${id}-health',
-  tenancy: '${tenancy}',
+  backendAccess: 'platform',
+  exposure: {
+    type: 'api',
+    path: '/system/${domain}/${id}-health',
+    method: 'GET',
+    auth: 'service',
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: z.object({}).default({}),
-      output: SystemHealthOutput,
-      handler: async (_input, _ctx) => {
-        return {
-          status: 'healthy',
-          uptime: process.uptime(),
-          domains: [],
-        };
-      },
-    },
+  idempotent: true,
+  input: z.object({}).default({}),
+  output: SystemHealthOutput,
+  handler: async (_input, _ctx) => {
+    return {
+      status: 'healthy',
+      uptime: process.uptime(),
+      domains: [],
+    };
   },
 });
 `;
@@ -108,4 +115,4 @@ export const ${varName}Health = defineApi({
  * Example body string used as the event body in the add-api fixture for the
  * system-admin pattern. Mirrors the default shape of the input schema.
  */
-export const systemAdminExampleBody = JSON.stringify({ command: 'status' });
+export const systemAdminExampleBody = JSON.stringify({ command: 'status' });

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

@@ -1,6 +1,10 @@
 /**
  * Webhook-receiver-style API pattern template.
  * Produces: POST with signature verification, provider enum.
+ *
+ * Action-first: HTTP endpoints are declared with `defineAction` +
+ * `exposure: { type: 'api', ... }`. The legacy `defineApi` factory was
+ * removed in #4689.
  */
 
 function camelCase(s: string): string {
@@ -9,10 +13,12 @@ function camelCase(s: string): string {
 
 export function webhookReceiverStyleTemplate(domain: string, id: string, tenancy: string): string {
   const varName = camelCase(id);
+  // Webhook receivers are typically public; pair `auth: 'none'` with a
+  // securityException.reason so the validator does not flag the route.
+  const securityException = `\n    securityException: { reason: 'webhook receiver; signature verification handled by authorizer' },`;
 
   return `import { z } from 'zod';
-import { defineApi } from '@mettlecast/domain-runtime';
-import { createKyClient, initOtel } from '@mettlecast/domain-runtime';
+import { defineAction, initOtel } from '@mettlecast/domain-runtime';
 import type { Result, AppError } from '@mettlecast/domain-runtime';
 import { ok, err, notFound } from '@mettlecast/domain-runtime';
 
@@ -50,46 +56,48 @@ const ${varName}Output = z.object({
   provider: 'stripe',
 });
 
-// ── API definition ───────────────────────────────────────────
+// ── Action definition (API exposure) ─────────────────────────
 
-export const ${varName} = defineApi({
+export const ${varName} = defineAction({
   id: '${id}',
-  path: '/webhooks/${domain}/${id}',
-  tenancy: '${tenancy}',
+  backendAccess: 'domain',
+  exposure: {
+    type: 'api',
+    path: '/webhooks/${domain}/${id}',
+    method: 'POST',
+    auth: 'none',${securityException}
+    tenancy: '${tenancy}',
+  },
   outboundAccess: 'internal',
-  versions: {
-    v1: {
-      status: 'stable',
-      input: ${varName}Input,
-      output: ${varName}Output,
-      handler: async (input, ctx) => {
-        // Signature verification belongs in a Lambda authorizer (x-webhook-signature header
-        // is not accessible here). Wire an HttpLambdaAuthorizer in DomainStack for production.
-
-        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.tenant.id,
-        }, 1);
-
-        await ctx.audit.log('${id}.webhook.received', ctx.tenant.id, {
-          provider: input.provider,
-          eventType: input.eventType,
-          eventId,
-        });
-
-        return {
-          received: true,
-          eventId,
-          provider: input.provider,
-        };
-      },
-    },
+  idempotent: false,
+  input: ${varName}Input,
+  output: ${varName}Output,
+  handler: async (input, ctx) => {
+    // Signature verification belongs in a Lambda authorizer (x-webhook-signature header
+    // is not accessible here). Wire an HttpLambdaAuthorizer in DomainStack for production.
+
+    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.tenant.id,
+    }, 1);
+
+    await ctx.audit.log('${id}.webhook.received', ctx.tenant.id, {
+      provider: input.provider,
+      eventType: input.eventType,
+      eventId,
+    });
+
+    return {
+      received: true,
+      eventId,
+      provider: input.provider,
+    };
   },
 });
 `;
@@ -103,4 +111,4 @@ export const webhookReceiverStyleExampleBody = JSON.stringify({
   provider: 'stripe',
   eventType: 'example.event',
   payload: {},
-});
+});