@ysk-kit/cli 1.2.1 → 1.2.2

package/templates/agent/skills/security-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: security-review
+description: >
+  Review YSK Kit authz, tenant isolation, secrets, logging redaction, token
+  storage, webhook signatures, and LLM input against hexagonal modules and
+  the {ok,data}/{ok,error} envelope. Optional lightweight threat-model mode.
+  Use when the user asks for a security review or audit; the diff touches
+  auth, apikey, organizations, billing, files, crypto, webhooks, env/secrets,
+  or a new capability; or the plan's security section is not "none".
+  中文：安全審查、權限、跨租戶、密鑰、日誌遮罩、webhook 簽名。
+  Do not use for pure UI styling, docs typos, or generic dependency bumps.
+---
+
+Read `docs/skills/security-review.md`. Law: `AGENTS.md`.
+
+1. Diff is the report scope; the repo is research. HIGH confidence only.
+2. AuthZ in `application/` (membership + role). Cross-tenant memory tests.
+3. No secrets in logs. Webhook signatures. Client token stores.
+4. Threat-model sub-mode only when the user asks or a new trust boundary lands.
+Full steps: `docs/skills/security-review.md`.

package/templates/agent/skills/webhook-handling/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: webhook-handling
+description: >
+  Handle inbound webhooks in YSK Kit: verify signature on the raw body, ack
+  fast, idempotency by event id, out-of-order events, retries, replay tests.
+  Stripe is the main example; the same rules apply to other providers.
+  Use when adding or changing /v1/*/webhook, adding billing, or debugging
+  "paid but not activated" / duplicate fulfilments.
+  中文：webhook、驗簽、冪等、Stripe 回調、重送。
+  Do not use for outbound HTTP or a general security audit with no webhook route.
+---
+
+Read `docs/skills/webhook-handling.md`. Law: `AGENTS.md`.
+
+1. Mount raw body before JSON parsers (Express + Fastify). Verify signature.
+2. Persist event id, return `{ ok: true, data: { received: true } }`, fulfil via jobs.
+3. Do not trust event order. Replay tests in memory; never call Stripe in CI.
+Full steps: `docs/skills/webhook-handling.md`.

package/templates/agent/ysk-kit.mdc

@@ -3,4 +3,4 @@ description: YSK Kit agent law — follow root AGENTS.md
 alwaysApply: true
 ---
 
-Follow `AGENTS.md` at the repo root (Chinese: `AGENTS.zh.md`). Do not copy that file here. Procedures: `docs/skills/`. Plan first when required: `pnpm ysk-kit plan <slug>` → `docs/plans/<yyyy-mm-dd>-<slug>.md`. New HTTP features start with `pnpm ysk-kit add module <kebab-name> --prisma --web`. Verify with `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`.
+Follow `AGENTS.md` at the repo root (Chinese: `AGENTS.zh.md`). Do not copy that file here. Procedures: `docs/skills/`. Plan first when required: `pnpm ysk-kit plan <slug>` → `docs/plans/<yyyy-mm-dd>-<slug>.md`. New HTTP features start with `pnpm ysk-kit add module <kebab-name> --prisma --web`. Verify with `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi && pnpm ysk-kit check agent`. Security / Prisma / webhooks / Electron: `docs/skills/security-review.md`, `db-migration.md`, `webhook-handling.md`, `desktop-electron.md`.

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

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { createMemoryOrganizationRepository } from '../../organizations/infra/memory-organization-repository';
+import { createLogBilling } from '../infra/log-billing';
+import { createMemorySubscriptionRepository } from '../infra/memory-subscription-repository';
+import { createMemoryWebhookEventRepository } from '../infra/memory-webhook-event-repository';
+import { createBillingService } from './billing-service';
+
+describe('createBillingService webhooks', () => {
+  it('activates once and skips a replay plus a stale event', async () => {
+    const orgs = createMemoryOrganizationRepository();
+    const subscriptions = createMemorySubscriptionRepository();
+    const service = createBillingService({
+      subscriptions,
+      billing: createLogBilling(),
+      orgs,
+      webhookEvents: createMemoryWebhookEventRepository(),
+    });
+    const owner = await orgs.createWithOwner({ name: 'Pay', ownerUserId: 'user-1' });
+    await service.handleStripeEvent({
+      id: 'evt_new',
+      type: 'checkout.session.completed',
+      created: 100,
+      data: {
+        object: {
+          customer: 'cus_1',
+          metadata: { organizationId: owner.id, planCode: 'pro', seatCount: '4' },
+        },
+      },
+    });
+    await service.handleStripeEvent({
+      id: 'evt_new',
+      type: 'checkout.session.completed',
+      created: 100,
+      data: {
+        object: {
+          customer: 'cus_1',
+          metadata: { organizationId: owner.id, planCode: 'pro', seatCount: '4' },
+        },
+      },
+    });
+    await service.handleStripeEvent({
+      id: 'evt_old',
+      type: 'checkout.session.completed',
+      created: 50,
+      data: {
+        object: {
+          customer: 'cus_1',
+          metadata: { organizationId: owner.id, planCode: 'pro', seatCount: '1' },
+        },
+      },
+    });
+    const row = await subscriptions.findByOrganizationId(owner.id);
+    expect(row?.seatCount).toBe(4);
+    expect(row?.status).toBe('active');
+  });
+});

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

@@ -3,7 +3,9 @@ import { BILLING_PLANS, orgRoleCan } from '@ysk-kit/contracts';
 import { AppError } from '@ysk-kit/domain-kernel';
 import type { IOrganizationRepository } from '../../organizations/domain/organization-repository';
 import type { IBillingPort } from '../domain/billing-port';
+import type { StripeWebhookEvent } from '../domain/stripe-webhook-event';
 import type { ISubscriptionRepository } from '../domain/subscription-repository';
+import type { IProcessedWebhookRepository } from '../domain/webhook-event-repository';
 
 const PERIOD_MS = 1000 * 60 * 60 * 24 * 30;
 
@@ -30,6 +32,7 @@ export const createBillingService = (opts: {
   subscriptions: ISubscriptionRepository;
   billing: IBillingPort;
   orgs: IOrganizationRepository;
+  webhookEvents: IProcessedWebhookRepository;
   now?: () => Date;
 }) => {
   const now = () => opts.now?.() ?? new Date();
@@ -44,6 +47,25 @@ export const createBillingService = (opts: {
     return org;
   };
 
+  const activate = async (
+    organizationId: string,
+    planCode: SubscriptionDto['planCode'],
+    customerId?: string,
+    seatCount = 1,
+  ) => {
+    if (planCode === 'free') return;
+    const org = await opts.orgs.findById(organizationId);
+    if (!org) throw new AppError('NOT_FOUND');
+    await opts.subscriptions.upsert({
+      organizationId,
+      planCode,
+      status: 'active',
+      currentPeriodEnd: new Date(now().getTime() + PERIOD_MS),
+      seatCount,
+    });
+    if (customerId) await opts.orgs.setStripeCustomerId(organizationId, customerId);
+  };
+
   return {
     plans: () => BILLING_PLANS,
     subscription: async (userId: string, organizationId: string): Promise<SubscriptionDto> => {
@@ -64,24 +86,7 @@ export const createBillingService = (opts: {
         invoiceId,
       });
     },
-    activate: async (
-      organizationId: string,
-      planCode: SubscriptionDto['planCode'],
-      customerId?: string,
-      seatCount = 1,
-    ) => {
-      if (planCode === 'free') return;
-      const org = await opts.orgs.findById(organizationId);
-      if (!org) throw new AppError('NOT_FOUND');
-      await opts.subscriptions.upsert({
-        organizationId,
-        planCode,
-        status: 'active',
-        currentPeriodEnd: new Date(now().getTime() + PERIOD_MS),
-        seatCount,
-      });
-      if (customerId) await opts.orgs.setStripeCustomerId(organizationId, customerId);
-    },
+    activate,
     portal: async (userId: string, organizationId: string, returnUrl: string) => {
       const org = await requireBiller(userId, organizationId);
       const customerId = org.stripeCustomerId;
@@ -120,6 +125,54 @@ export const createBillingService = (opts: {
       }
       return { url: result.url };
     },
+    handleStripeEvent: async (event: StripeWebhookEvent) => {
+      if (!event.id) throw new AppError('VALIDATION_FAILED', 'Stripe event id required');
+      const organizationId = event.data.object.metadata?.organizationId;
+      const eventCreatedAt = new Date((Number.isFinite(event.created) ? event.created : 0) * 1000);
+      const claim = await opts.webhookEvents.tryClaim({
+        provider: 'stripe',
+        eventId: event.id,
+        eventType: event.type,
+        eventCreatedAt,
+        ...(organizationId ? { organizationId } : {}),
+      });
+      if (claim === 'duplicate') return { received: true as const };
+
+      try {
+        if (organizationId) {
+          const latest = await opts.webhookEvents.maxEventCreatedAt(
+            'stripe',
+            organizationId,
+            event.id,
+          );
+          if (latest && eventCreatedAt < latest) return { received: true as const };
+        }
+        if (event.type === 'checkout.session.completed') {
+          const planCode = event.data.object.metadata?.planCode;
+          const seatRaw = Number(event.data.object.metadata?.seatCount ?? '1');
+          const seatCount = Number.isFinite(seatRaw) && seatRaw >= 1 ? Math.floor(seatRaw) : 1;
+          if (organizationId && (planCode === 'pro' || planCode === 'free')) {
+            const customer = event.data.object.customer;
+            await activate(
+              organizationId,
+              planCode,
+              typeof customer === 'string' ? customer : undefined,
+              seatCount,
+            );
+          }
+        }
+        return { received: true as const };
+      } catch (error) {
+        if (
+          error instanceof AppError &&
+          (error.code === 'NOT_FOUND' || error.code === 'VALIDATION_FAILED')
+        ) {
+          return { received: true as const };
+        }
+        await opts.webhookEvents.release('stripe', event.id);
+        throw error;
+      }
+    },
     cancel: async (userId: string, organizationId: string) => {
       await requireBiller(userId, organizationId);
       const row = await opts.subscriptions.findByOrganizationId(organizationId);

package/templates/capabilities/billing/apps/api/src/modules/billing/domain/stripe-webhook-event.ts

@@ -0,0 +1,12 @@
+export type StripeWebhookEvent = {
+  id: string;
+  type: string;
+  created: number;
+  data: {
+    object: {
+      metadata?: Record<string, string>;
+      customer?: string;
+      payment_status?: string;
+    };
+  };
+};

package/templates/capabilities/billing/apps/api/src/modules/billing/domain/webhook-event-repository.ts

@@ -0,0 +1,19 @@
+export type ProcessedWebhookClaim = 'claimed' | 'duplicate';
+
+export type ProcessedWebhookRecord = {
+  provider: string;
+  eventId: string;
+  eventType: string;
+  eventCreatedAt: Date;
+  organizationId?: string;
+};
+
+export interface IProcessedWebhookRepository {
+  tryClaim(input: ProcessedWebhookRecord): Promise<ProcessedWebhookClaim>;
+  maxEventCreatedAt(
+    provider: string,
+    organizationId: string,
+    exceptEventId: string,
+  ): Promise<Date | null>;
+  release(provider: string, eventId: string): Promise<void>;
+}

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

@@ -2,10 +2,12 @@ import { createHmac } from 'node:crypto';
 import request from 'supertest';
 import { describe, expect, it } from 'vitest';
 import { createApp } from '../../../app';
+import { createFastifyApp } from '../../../app-fastify';
 import { createMemoryInput } from '../../../create-memory-input';
 import { createBillingService } from '../application/billing-service';
 import { createLogBilling } from './log-billing';
 import { createMemorySubscriptionRepository } from './memory-subscription-repository';
+import { createMemoryWebhookEventRepository } from './memory-webhook-event-repository';
 import { createStripeBilling } from './stripe-billing';
 
 describe('billing http', () => {
@@ -34,7 +36,9 @@ describe('billing http', () => {
       .send({ name: 'Pay' });
     const organizationId = org.body.data.id as string;
     const payload = JSON.stringify({
+      id: 'evt_checkout_1',
       type: 'checkout.session.completed',
+      created: Math.floor(Date.now() / 1000),
       data: {
         object: {
           customer: 'cus_1',
@@ -73,6 +77,7 @@ describe('billing http', () => {
         fetchImpl: (async () => new Response('{}', { status: 500 })) as typeof fetch,
       }),
       orgs: mem.orgs,
+      webhookEvents: createMemoryWebhookEventRepository(),
     });
     const stripeApp = createApp({ ...mem.input, billingService });
     const registered = await request(stripeApp).post('/v1/auth/register').send({
@@ -251,6 +256,7 @@ describe('billing http', () => {
         getInvoicePdf: async () => ({ url: 'https://files.stripe.com/x.pdf' }),
       },
       orgs: mem.orgs,
+      webhookEvents: createMemoryWebhookEventRepository(),
     });
     const pdfApp = createApp({ ...mem.input, billingService });
     const registered = await request(pdfApp).post('/v1/auth/register').send({
@@ -270,4 +276,170 @@ describe('billing http', () => {
     expect(pdf.status).toBe(302);
     expect(pdf.headers.location).toBe('https://files.stripe.com/x.pdf');
   });
+
+  const sign = (secret: string, payload: string): string => {
+    const t = String(Math.floor(Date.now() / 1000));
+    const v1 = createHmac('sha256', secret).update(`${t}.${payload}`).digest('hex');
+    return `t=${t},v1=${v1}`;
+  };
+
+  it('acks a replayed Stripe event without applying it twice', async () => {
+    const mem = createMemoryInput();
+    const secret = 'whsec_replay';
+    const app = createApp({ ...mem.input, stripeWebhookSecret: secret });
+    const registered = await request(app).post('/v1/auth/register').send({
+      email: 'replay@ysk.hk',
+      password: 'password1',
+      displayName: 'Replay',
+    });
+    const jwt = registered.body.data.accessToken as string;
+    const org = await request(app)
+      .post('/v1/organizations')
+      .set('authorization', `Bearer ${jwt}`)
+      .send({ name: 'Replay Co' });
+    const organizationId = org.body.data.id as string;
+    const payload = JSON.stringify({
+      id: 'evt_replay_1',
+      type: 'checkout.session.completed',
+      created: 1_800_000_000,
+      data: {
+        object: {
+          customer: 'cus_replay',
+          metadata: { organizationId, planCode: 'pro', seatCount: '3' },
+        },
+      },
+    });
+    const header = sign(secret, payload);
+    const first = await request(app)
+      .post('/v1/billing/webhook')
+      .set('content-type', 'application/json')
+      .set('stripe-signature', header)
+      .send(payload);
+    const second = await request(app)
+      .post('/v1/billing/webhook')
+      .set('content-type', 'application/json')
+      .set('stripe-signature', header)
+      .send(payload);
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    expect(second.body).toEqual({ ok: true, data: { received: true } });
+    const sub = await request(app)
+      .get(`/v1/billing/subscription?organizationId=${organizationId}`)
+      .set('authorization', `Bearer ${jwt}`);
+    expect(sub.body.data.seatCount).toBe(3);
+  });
+
+  it('ignores an older Stripe event after a newer one for the same org', async () => {
+    const mem = createMemoryInput();
+    const secret = 'whsec_order';
+    const app = createApp({ ...mem.input, stripeWebhookSecret: secret });
+    const registered = await request(app).post('/v1/auth/register').send({
+      email: 'order@ysk.hk',
+      password: 'password1',
+      displayName: 'Order',
+    });
+    const jwt = registered.body.data.accessToken as string;
+    const org = await request(app)
+      .post('/v1/organizations')
+      .set('authorization', `Bearer ${jwt}`)
+      .send({ name: 'Order Co' });
+    const organizationId = org.body.data.id as string;
+    const newer = JSON.stringify({
+      id: 'evt_new',
+      type: 'checkout.session.completed',
+      created: 1_800_000_100,
+      data: {
+        object: {
+          customer: 'cus_new',
+          metadata: { organizationId, planCode: 'pro', seatCount: '5' },
+        },
+      },
+    });
+    const older = JSON.stringify({
+      id: 'evt_old',
+      type: 'checkout.session.completed',
+      created: 1_800_000_001,
+      data: {
+        object: {
+          customer: 'cus_old',
+          metadata: { organizationId, planCode: 'pro', seatCount: '2' },
+        },
+      },
+    });
+    const first = await request(app)
+      .post('/v1/billing/webhook')
+      .set('content-type', 'application/json')
+      .set('stripe-signature', sign(secret, newer))
+      .send(newer);
+    const second = await request(app)
+      .post('/v1/billing/webhook')
+      .set('content-type', 'application/json')
+      .set('stripe-signature', sign(secret, older))
+      .send(older);
+    expect(first.status).toBe(200);
+    expect(second.status).toBe(200);
+    const sub = await request(app)
+      .get(`/v1/billing/subscription?organizationId=${organizationId}`)
+      .set('authorization', `Bearer ${jwt}`);
+    expect(sub.body.data.seatCount).toBe(5);
+  });
+
+  it('handles a signed Stripe webhook on Fastify', async () => {
+    const mem = createMemoryInput();
+    const secret = 'whsec_fastify';
+    const app = await createFastifyApp({ ...mem.input, stripeWebhookSecret: secret });
+    const registered = await app.inject({
+      method: 'POST',
+      url: '/v1/auth/register',
+      payload: { email: 'ff@ysk.hk', password: 'password1', displayName: 'Ff' },
+    });
+    const jwt = registered.json().data.accessToken as string;
+    const org = await app.inject({
+      method: 'POST',
+      url: '/v1/organizations',
+      headers: { authorization: `Bearer ${jwt}` },
+      payload: { name: 'Ff Co' },
+    });
+    const organizationId = org.json().data.id as string;
+    const payload = JSON.stringify({
+      id: 'evt_fastify',
+      type: 'checkout.session.completed',
+      created: 1_800_000_200,
+      data: {
+        object: {
+          customer: 'cus_ff',
+          metadata: { organizationId, planCode: 'pro', seatCount: '2' },
+        },
+      },
+    });
+    const unsigned = await app.inject({
+      method: 'POST',
+      url: '/v1/billing/webhook',
+      headers: { 'content-type': 'application/json' },
+      payload,
+    });
+    expect(unsigned.statusCode).toBe(401);
+    const signed = await app.inject({
+      method: 'POST',
+      url: '/v1/billing/webhook',
+      headers: {
+        'content-type': 'application/json',
+        'stripe-signature': sign(secret, payload),
+      },
+      payload,
+    });
+    expect(signed.statusCode).toBe(200);
+    expect(signed.json()).toEqual({ ok: true, data: { received: true } });
+    const replay = await app.inject({
+      method: 'POST',
+      url: '/v1/billing/webhook',
+      headers: {
+        'content-type': 'application/json',
+        'stripe-signature': sign(secret, payload),
+      },
+      payload,
+    });
+    expect(replay.statusCode).toBe(200);
+    await app.close();
+  });
 });

package/templates/capabilities/billing/apps/api/src/modules/billing/infra/memory-webhook-event-repository.ts

@@ -0,0 +1,31 @@
+import type {
+  IProcessedWebhookRepository,
+  ProcessedWebhookRecord,
+} from '../domain/webhook-event-repository';
+
+const keyOf = (provider: string, eventId: string): string => `${provider}:${eventId}`;
+
+export const createMemoryWebhookEventRepository = (): IProcessedWebhookRepository => {
+  const rows = new Map<string, ProcessedWebhookRecord>();
+  return {
+    async tryClaim(input) {
+      const key = keyOf(input.provider, input.eventId);
+      if (rows.has(key)) return 'duplicate';
+      rows.set(key, input);
+      return 'claimed';
+    },
+    async maxEventCreatedAt(provider, organizationId, exceptEventId) {
+      let latest: Date | null = null;
+      for (const row of rows.values()) {
+        if (row.provider !== provider) continue;
+        if (row.organizationId !== organizationId) continue;
+        if (row.eventId === exceptEventId) continue;
+        if (!latest || row.eventCreatedAt > latest) latest = row.eventCreatedAt;
+      }
+      return latest;
+    },
+    async release(provider, eventId) {
+      rows.delete(keyOf(provider, eventId));
+    },
+  };
+};

package/templates/capabilities/billing/apps/api/src/modules/billing/infra/prisma-webhook-event-repository.ts

@@ -0,0 +1,39 @@
+import type { PrismaClient } from '../../../generated/prisma/client';
+import type { IProcessedWebhookRepository } from '../domain/webhook-event-repository';
+
+export const createPrismaWebhookEventRepository = (
+  prisma: PrismaClient,
+): IProcessedWebhookRepository => ({
+  async tryClaim(input) {
+    try {
+      await prisma.processedWebhookEvent.create({
+        data: {
+          provider: input.provider,
+          eventId: input.eventId,
+          eventType: input.eventType,
+          eventCreatedAt: input.eventCreatedAt,
+          ...(input.organizationId ? { organizationId: input.organizationId } : {}),
+        },
+      });
+      return 'claimed';
+    } catch (error) {
+      const code =
+        error && typeof error === 'object' && 'code' in error
+          ? String((error as { code?: unknown }).code)
+          : '';
+      if (code === 'P2002') return 'duplicate';
+      throw error;
+    }
+  },
+  async maxEventCreatedAt(provider, organizationId, exceptEventId) {
+    const row = await prisma.processedWebhookEvent.findFirst({
+      where: { provider, organizationId, eventId: { not: exceptEventId } },
+      orderBy: { eventCreatedAt: 'desc' },
+      select: { eventCreatedAt: true },
+    });
+    return row?.eventCreatedAt ?? null;
+  },
+  async release(provider, eventId) {
+    await prisma.processedWebhookEvent.deleteMany({ where: { provider, eventId } });
+  },
+});

package/templates/capabilities/billing/apps/api/src/modules/billing/infra/stripe-billing.test.ts

@@ -110,7 +110,9 @@ describe('stripe billing', () => {
     const secret = 'whsec_test';
     const payload = Buffer.from(
       JSON.stringify({
+        id: 'evt_1',
         type: 'checkout.session.completed',
+        created: 1_700_000_000,
         data: { object: { metadata: { organizationId: 'o1', planCode: 'pro', seatCount: '2' } } },
       }),
     );
@@ -120,6 +122,7 @@ describe('stripe billing', () => {
       .digest('hex');
     const event = verifyStripeSignature(payload, `t=${t},v1=${v1}`, secret, 1_700_000_000_000);
     expect(event.type).toBe('checkout.session.completed');
+    expect(event.id).toBe('evt_1');
     expect(() =>
       verifyStripeSignature(payload, `t=${t},v1=dead`, secret, 1_700_000_000_000),
     ).toThrow();

package/templates/capabilities/billing/apps/api/src/modules/billing/infra/stripe-billing.ts

@@ -2,16 +2,16 @@ import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { InvoiceDto } from '@ysk-kit/contracts';
 import { AppError } from '@ysk-kit/domain-kernel';
 import type { IBillingPort } from '../domain/billing-port';
+import type { StripeWebhookEvent } from '../domain/stripe-webhook-event';
+
+export type { StripeWebhookEvent };
 
 export const verifyStripeSignature = (
   raw: Buffer,
   header: string,
   secret: string,
   nowMs = Date.now(),
-): {
-  type: string;
-  data: { object: { metadata?: Record<string, string>; customer?: string } };
-} => {
+): StripeWebhookEvent => {
   const parts = Object.fromEntries(
     header.split(',').map((item) => {
       const [key, ...rest] = item.split('=');
@@ -33,12 +33,39 @@ export const verifyStripeSignature = (
   if (a.length !== b.length || !timingSafeEqual(a, b)) {
     throw new AppError('UNAUTHENTICATED', 'Invalid Stripe signature');
   }
-  return JSON.parse(raw.toString('utf8')) as {
-    type: string;
-    data: { object: { metadata?: Record<string, string>; customer?: string } };
+  const parsed = JSON.parse(raw.toString('utf8')) as Partial<StripeWebhookEvent>;
+  if (!parsed.id || typeof parsed.id !== 'string' || typeof parsed.type !== 'string') {
+    throw new AppError('VALIDATION_FAILED', 'Stripe event id required');
+  }
+  return {
+    id: parsed.id,
+    type: parsed.type,
+    created: typeof parsed.created === 'number' ? parsed.created : 0,
+    data: {
+      object: {
+        ...(parsed.data?.object?.metadata ? { metadata: parsed.data.object.metadata } : {}),
+        ...(typeof parsed.data?.object?.customer === 'string'
+          ? { customer: parsed.data.object.customer }
+          : {}),
+        ...(typeof parsed.data?.object?.payment_status === 'string'
+          ? { payment_status: parsed.data.object.payment_status }
+          : {}),
+      },
+    },
   };
 };
 
+export const applyVerifiedStripeWebhook = async (
+  raw: Buffer,
+  header: string,
+  secret: string,
+  billing: { handleStripeEvent: (event: StripeWebhookEvent) => Promise<unknown> },
+  nowMs = Date.now(),
+): Promise<void> => {
+  const event = verifyStripeSignature(raw, header, secret, nowMs);
+  await billing.handleStripeEvent(event);
+};
+
 export const createStripeBilling = (opts: {
   secretKey: string;
   pricePro: string;

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

@@ -9,8 +9,8 @@ import {
   OrganizationIdQuerySchema,
   PortalCommandSchema,
   SubscriptionDtoSchema,
-} from '../dto/billing';
-import { ErrSchema, OkSchema } from '../errors/envelope';
+} from '../dto/billing.js';
+import { ErrSchema, OkSchema } from '../errors/envelope.js';
 
 const c = initContract();
 

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { BillingPlanCodeSchema, SubscriptionStatusSchema } from '../enums/billing-plan';
+import { BillingPlanCodeSchema, SubscriptionStatusSchema } from '../enums/billing-plan.js';
 
 export const BillingPlanDtoSchema = z.object({
   code: BillingPlanCodeSchema,

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

@@ -7,7 +7,7 @@ import type {
   PortalCommand,
   SubscriptionDto,
 } from '@ysk-kit/contracts';
-import type { HttpClient } from '../http';
+import type { HttpClient } from '../http.js';
 
 const withOrg = (path: string, organizationId: string): string =>
   `${path}?organizationId=${encodeURIComponent(organizationId)}`;