@l4yercak3/cli 1.2.15 → 1.2.18

package/src/generators/api-only/webhooks.js

@@ -0,0 +1,377 @@
+/**
+ * Webhooks Generator
+ * Generates webhook handling utilities for the L4YERCAK3 API
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ensureDir, writeFileWithBackup, checkFileOverwrite } = require('../../utils/file-utils');
+
+class WebhooksGenerator {
+  /**
+   * Generate the webhooks utility file
+   * @param {Object} options - Generation options
+   * @returns {Promise<string|null>} - Path to generated file or null if skipped
+   */
+  async generate(options) {
+    const { projectPath, isTypeScript } = options;
+
+    // Determine output directory
+    let outputDir;
+    if (fs.existsSync(path.join(projectPath, 'src'))) {
+      outputDir = path.join(projectPath, 'src', 'lib', 'l4yercak3');
+    } else {
+      outputDir = path.join(projectPath, 'lib', 'l4yercak3');
+    }
+
+    ensureDir(outputDir);
+
+    const extension = isTypeScript ? 'ts' : 'js';
+    const outputPath = path.join(outputDir, `webhooks.${extension}`);
+
+    const action = await checkFileOverwrite(outputPath);
+    if (action === 'skip') {
+      return null;
+    }
+
+    const content = isTypeScript
+      ? this.generateTypeScriptWebhooks()
+      : this.generateJavaScriptWebhooks();
+
+    return writeFileWithBackup(outputPath, content, action);
+  }
+
+  generateTypeScriptWebhooks() {
+    return `/**
+ * L4YERCAK3 Webhook Utilities
+ * Auto-generated by @l4yercak3/cli
+ *
+ * Utilities for handling webhook events from L4YERCAK3.
+ */
+
+import { createHmac, timingSafeEqual } from 'crypto';
+
+export interface WebhookEvent<T = Record<string, unknown>> {
+  id: string;
+  type: WebhookEventType;
+  timestamp: string;
+  data: T;
+  organizationId: string;
+}
+
+export type WebhookEventType =
+  | 'contact.created'
+  | 'contact.updated'
+  | 'contact.deleted'
+  | 'organization.created'
+  | 'organization.updated'
+  | 'event.created'
+  | 'event.updated'
+  | 'event.published'
+  | 'event.cancelled'
+  | 'attendee.registered'
+  | 'attendee.checked_in'
+  | 'attendee.cancelled'
+  | 'form.submitted'
+  | 'order.created'
+  | 'order.paid'
+  | 'order.refunded'
+  | 'invoice.created'
+  | 'invoice.sent'
+  | 'invoice.paid'
+  | 'invoice.overdue'
+  | 'benefit_claim.submitted'
+  | 'benefit_claim.approved'
+  | 'benefit_claim.rejected'
+  | 'benefit_claim.paid'
+  | 'commission.calculated'
+  | 'commission.paid'
+  | 'certificate.issued';
+
+export interface VerifyOptions {
+  /** The raw request body as a string or Buffer */
+  payload: string | Buffer;
+  /** The signature from the X-L4yercak3-Signature header */
+  signature: string;
+  /** Your webhook secret from the L4YERCAK3 dashboard */
+  secret: string;
+  /** Tolerance in seconds for timestamp validation (default: 300 = 5 minutes) */
+  tolerance?: number;
+}
+
+export class WebhookVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WebhookVerificationError';
+  }
+}
+
+/**
+ * Verify a webhook signature and parse the event
+ *
+ * @example
+ * \`\`\`ts
+ * // In your Next.js API route
+ * import { verifyWebhookSignature, WebhookEvent } from '@/lib/l4yercak3';
+ *
+ * export async function POST(req: Request) {
+ *   const payload = await req.text();
+ *   const signature = req.headers.get('x-l4yercak3-signature') || '';
+ *
+ *   try {
+ *     const event = verifyWebhookSignature({
+ *       payload,
+ *       signature,
+ *       secret: process.env.L4YERCAK3_WEBHOOK_SECRET!,
+ *     });
+ *
+ *     switch (event.type) {
+ *       case 'contact.created':
+ *         // Handle new contact
+ *         break;
+ *       case 'order.paid':
+ *         // Handle paid order
+ *         break;
+ *     }
+ *
+ *     return new Response('OK', { status: 200 });
+ *   } catch (error) {
+ *     console.error('Webhook error:', error);
+ *     return new Response('Invalid signature', { status: 400 });
+ *   }
+ * }
+ * \`\`\`
+ */
+export function verifyWebhookSignature<T = Record<string, unknown>>(
+  options: VerifyOptions
+): WebhookEvent<T> {
+  const { payload, signature, secret, tolerance = 300 } = options;
+
+  if (!signature) {
+    throw new WebhookVerificationError('Missing signature header');
+  }
+
+  // Parse the signature header (format: t=timestamp,v1=signature)
+  const parts = signature.split(',').reduce((acc, part) => {
+    const [key, value] = part.split('=');
+    acc[key] = value;
+    return acc;
+  }, {} as Record<string, string>);
+
+  const timestamp = parts['t'];
+  const signatureHash = parts['v1'];
+
+  if (!timestamp || !signatureHash) {
+    throw new WebhookVerificationError('Invalid signature format');
+  }
+
+  // Check timestamp tolerance
+  const timestampNum = parseInt(timestamp, 10);
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - timestampNum) > tolerance) {
+    throw new WebhookVerificationError('Timestamp outside tolerance window');
+  }
+
+  // Compute expected signature
+  const payloadStr = typeof payload === 'string' ? payload : payload.toString('utf8');
+  const signedPayload = \`\${timestamp}.\${payloadStr}\`;
+  const expectedSignature = createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+
+  // Constant-time comparison
+  const expectedBuffer = Buffer.from(expectedSignature);
+  const receivedBuffer = Buffer.from(signatureHash);
+
+  if (expectedBuffer.length !== receivedBuffer.length) {
+    throw new WebhookVerificationError('Invalid signature');
+  }
+
+  if (!timingSafeEqual(expectedBuffer, receivedBuffer)) {
+    throw new WebhookVerificationError('Invalid signature');
+  }
+
+  // Parse and return the event
+  try {
+    return JSON.parse(payloadStr) as WebhookEvent<T>;
+  } catch {
+    throw new WebhookVerificationError('Invalid JSON payload');
+  }
+}
+
+/**
+ * Type guard helpers for specific webhook events
+ */
+export function isContactEvent(event: WebhookEvent): event is WebhookEvent<{ contact: unknown }> {
+  return event.type.startsWith('contact.');
+}
+
+export function isEventEvent(event: WebhookEvent): event is WebhookEvent<{ event: unknown }> {
+  return event.type.startsWith('event.');
+}
+
+export function isOrderEvent(event: WebhookEvent): event is WebhookEvent<{ order: unknown }> {
+  return event.type.startsWith('order.');
+}
+
+export function isInvoiceEvent(event: WebhookEvent): event is WebhookEvent<{ invoice: unknown }> {
+  return event.type.startsWith('invoice.');
+}
+
+export function isBenefitClaimEvent(event: WebhookEvent): event is WebhookEvent<{ claim: unknown }> {
+  return event.type.startsWith('benefit_claim.');
+}
+`;
+  }
+
+  generateJavaScriptWebhooks() {
+    return `/**
+ * L4YERCAK3 Webhook Utilities
+ * Auto-generated by @l4yercak3/cli
+ *
+ * Utilities for handling webhook events from L4YERCAK3.
+ */
+
+const { createHmac, timingSafeEqual } = require('crypto');
+
+class WebhookVerificationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'WebhookVerificationError';
+  }
+}
+
+/**
+ * Verify a webhook signature and parse the event
+ *
+ * @param {Object} options
+ * @param {string|Buffer} options.payload - The raw request body
+ * @param {string} options.signature - The signature from X-L4yercak3-Signature header
+ * @param {string} options.secret - Your webhook secret
+ * @param {number} [options.tolerance=300] - Timestamp tolerance in seconds
+ * @returns {Object} The verified webhook event
+ * @throws {WebhookVerificationError} If verification fails
+ *
+ * @example
+ * // In your Next.js API route
+ * const { verifyWebhookSignature } = require('@/lib/l4yercak3');
+ *
+ * export default async function handler(req, res) {
+ *   const payload = req.body;
+ *   const signature = req.headers['x-l4yercak3-signature'];
+ *
+ *   try {
+ *     const event = verifyWebhookSignature({
+ *       payload: JSON.stringify(payload),
+ *       signature,
+ *       secret: process.env.L4YERCAK3_WEBHOOK_SECRET,
+ *     });
+ *
+ *     switch (event.type) {
+ *       case 'contact.created':
+ *         // Handle new contact
+ *         break;
+ *       case 'order.paid':
+ *         // Handle paid order
+ *         break;
+ *     }
+ *
+ *     res.status(200).json({ received: true });
+ *   } catch (error) {
+ *     console.error('Webhook error:', error);
+ *     res.status(400).json({ error: 'Invalid signature' });
+ *   }
+ * }
+ */
+function verifyWebhookSignature(options) {
+  const { payload, signature, secret, tolerance = 300 } = options;
+
+  if (!signature) {
+    throw new WebhookVerificationError('Missing signature header');
+  }
+
+  // Parse the signature header (format: t=timestamp,v1=signature)
+  const parts = signature.split(',').reduce((acc, part) => {
+    const [key, value] = part.split('=');
+    acc[key] = value;
+    return acc;
+  }, {});
+
+  const timestamp = parts['t'];
+  const signatureHash = parts['v1'];
+
+  if (!timestamp || !signatureHash) {
+    throw new WebhookVerificationError('Invalid signature format');
+  }
+
+  // Check timestamp tolerance
+  const timestampNum = parseInt(timestamp, 10);
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - timestampNum) > tolerance) {
+    throw new WebhookVerificationError('Timestamp outside tolerance window');
+  }
+
+  // Compute expected signature
+  const payloadStr = typeof payload === 'string' ? payload : payload.toString('utf8');
+  const signedPayload = \`\${timestamp}.\${payloadStr}\`;
+  const expectedSignature = createHmac('sha256', secret)
+    .update(signedPayload)
+    .digest('hex');
+
+  // Constant-time comparison
+  const expectedBuffer = Buffer.from(expectedSignature);
+  const receivedBuffer = Buffer.from(signatureHash);
+
+  if (expectedBuffer.length !== receivedBuffer.length) {
+    throw new WebhookVerificationError('Invalid signature');
+  }
+
+  if (!timingSafeEqual(expectedBuffer, receivedBuffer)) {
+    throw new WebhookVerificationError('Invalid signature');
+  }
+
+  // Parse and return the event
+  try {
+    return JSON.parse(payloadStr);
+  } catch {
+    throw new WebhookVerificationError('Invalid JSON payload');
+  }
+}
+
+/**
+ * Type guard helpers for specific webhook events
+ */
+function isContactEvent(event) {
+  return event.type && event.type.startsWith('contact.');
+}
+
+function isEventEvent(event) {
+  return event.type && event.type.startsWith('event.');
+}
+
+function isOrderEvent(event) {
+  return event.type && event.type.startsWith('order.');
+}
+
+function isInvoiceEvent(event) {
+  return event.type && event.type.startsWith('invoice.');
+}
+
+function isBenefitClaimEvent(event) {
+  return event.type && event.type.startsWith('benefit_claim.');
+}
+
+module.exports = {
+  verifyWebhookSignature,
+  WebhookVerificationError,
+  isContactEvent,
+  isEventEvent,
+  isOrderEvent,
+  isInvoiceEvent,
+  isBenefitClaimEvent,
+};
+`;
+  }
+}
+
+module.exports = new WebhooksGenerator();

package/src/generators/index.js

@@ -5,6 +5,11 @@
  * Supports multiple frameworks:
  * - nextjs: Next.js (App Router and Pages Router)
  * - expo: Expo/React Native
+ *
+ * Supports multiple integration paths:
+ * - quickstart: Full-stack with UI components & database
+ * - api-only: Just the typed API client
+ * - mcp-assisted: AI-powered custom generation
  */
 
 const apiClientGenerator = require('./api-client-generator');
@@ -12,6 +17,9 @@ const envGenerator = require('./env-generator');
 const nextauthGenerator = require('./nextauth-generator');
 const oauthGuideGenerator = require('./oauth-guide-generator');
 const gitignoreGenerator = require('./gitignore-generator');
+const apiOnlyGenerator = require('./api-only');
+const mcpGuideGenerator = require('./mcp-guide-generator');
+const quickstartGenerator = require('./quickstart');
 
 class FileGenerator {
   /**
@@ -32,6 +40,86 @@ class FileGenerator {
    * Generate all files based on configuration
    */
   async generate(options) {
+    const integrationPath = options.integrationPath || 'api-only';
+
+    // Route to the appropriate generator based on integration path
+    switch (integrationPath) {
+      case 'api-only':
+        return this.generateApiOnly(options);
+      case 'mcp-assisted':
+        return this.generateMcpAssisted(options);
+      case 'quickstart':
+        return this.generateQuickStart(options);
+      default:
+        return this.generateLegacy(options);
+    }
+  }
+
+  /**
+   * API-Only path: Generate typed API client and types
+   */
+  async generateApiOnly(options) {
+    const results = {
+      apiClient: null,
+      types: null,
+      webhooks: null,
+      index: null,
+      envFile: null,
+      gitignore: null,
+    };
+
+    // Generate the full typed API client package
+    const apiOnlyResults = await apiOnlyGenerator.generate(options);
+    results.apiClient = apiOnlyResults.client;
+    results.types = apiOnlyResults.types;
+    results.webhooks = apiOnlyResults.webhooks;
+    results.index = apiOnlyResults.index;
+
+    // Generate environment file
+    results.envFile = envGenerator.generate(options);
+
+    // Update .gitignore
+    results.gitignore = gitignoreGenerator.generate(options);
+
+    return results;
+  }
+
+  /**
+   * MCP-Assisted path: Generate MCP config and guide
+   */
+  async generateMcpAssisted(options) {
+    const results = {
+      mcpConfig: null,
+      mcpGuide: null,
+      envFile: null,
+      gitignore: null,
+    };
+
+    // Generate MCP configuration and guide
+    const mcpResults = await mcpGuideGenerator.generate(options);
+    results.mcpConfig = mcpResults.config;
+    results.mcpGuide = mcpResults.guide;
+
+    // Generate environment file
+    results.envFile = envGenerator.generate(options);
+
+    // Update .gitignore
+    results.gitignore = gitignoreGenerator.generate(options);
+
+    return results;
+  }
+
+  /**
+   * Quick Start path: Full-stack generation with database, hooks, and components
+   */
+  async generateQuickStart(options) {
+    return quickstartGenerator.generate(options);
+  }
+
+  /**
+   * Legacy generation (backward compatibility)
+   */
+  async generateLegacy(options) {
     const results = {
       apiClient: null,
       envFile: null,
@@ -57,12 +145,10 @@ class FileGenerator {
       if (isNextJs) {
         results.nextauth = await nextauthGenerator.generate(options);
       }
-      // For mobile, OAuth is handled differently (expo-auth-session, etc.)
     }
 
     // Generate OAuth guide if OAuth is enabled
     if (options.features && options.features.includes('oauth') && options.oauthProviders) {
-      // Pass framework info so guide can be customized
       results.oauthGuide = oauthGuideGenerator.generate({
         ...options,
         isMobile,