Real-World Use Cases

// WHAT: APIForge billing — charge a customer and handle all failure cases
// File: src/controllers/billing.controller.js
// Uses Stripe idempotency key to safely handle network retries

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export async function createSubscription(req, res) {
  const { paymentMethodId, planId } = req.body;
  const userId = req.user.userId;

  // Idempotency key scoped to user + plan — retries are safe
  const idempotencyKey = `sub_${userId}_${planId}_${Date.now()}`;

  try {
    // Step 1: Create or retrieve Stripe customer
    const customer = await stripe.customers.create(
      { email: req.user.email, payment_method: paymentMethodId },
      { idempotencyKey: `cus_${userId}` }
    );

    // Step 2: Create the subscription — activation happens via webhook
    const subscription = await stripe.subscriptions.create({
      customer:          customer.id,
      items:             [{ price: planId }],
      payment_behavior:  'default_incomplete',
      expand:            ['latest_invoice.payment_intent'],
    }, { idempotencyKey });

    const paymentIntent = subscription.latest_invoice.payment_intent;

    // Return the client secret — frontend uses this to confirm the payment
    res.status(202).json({
      subscriptionId:      subscription.id,
      clientSecret:        paymentIntent.client_secret,
      status:              subscription.status,  // 'incomplete' until webhook fires
    });

  } catch (err) {
    // Stripe error codes map directly to user-facing messages
    const messages = {
      card_declined:          'Your card was declined. Please try a different card.',
      insufficient_funds:     'Your card has insufficient funds.',
      card_velocity_exceeded: 'Too many attempts. Please wait before trying again.',
    };

    res.status(402).json({
      error: {
        type:    'payment_error',
        code:    err.code,
        message: messages[err.code] || 'Payment could not be processed.',
        param:   'paymentMethodId',
      }
    });
  }
}

// WHAT: APIForge Slack notification — async job pattern using BullMQ + Redis
// File: src/jobs/notificationJob.js + src/controllers/projects.controller.js
// Project creation returns immediately; Slack call happens in the background

import { Queue, Worker } from 'bullmq';

const notificationQueue = new Queue('notifications', {
  connection: { host: 'localhost', port: 6379 },
});

// ── Route handler — creates project and queues notification, returns fast ──
export async function createProject(req, res) {
  const { name, status } = req.body;

  const project = {
    id:        `proj_${generateId()}`,
    name,
    status:    status || 'active',
    createdBy: req.user.userId,
    createdAt: new Date().toISOString(),
  };

  await db.projects.insert(project);

  // Queue the Slack notification — does NOT await it
  await notificationQueue.add('slack-alert', {
    event:   'project.created',
    project,
    actor:   req.user.email,
  }, {
    attempts: 3,          // retry up to 3 times on Slack failure
    backoff:  { type: 'exponential', delay: 2000 },
  });

  // Return immediately — notification happens in background
  res.status(201).json({ success: true, data: project });
}

// ── Background worker — processes the notification queue ──────────────────
const worker = new Worker('notifications', async (job) => {
  const { event, project, actor } = job.data;

  const slackPayload = {
    text: `New project created by ${actor}`,
    blocks: [
      {
        type: 'section',
        text: { type: 'mrkdwn', text: `${project.name} was just created` },
        fields: [
          { type: 'mrkdwn', text: `Status:\n${project.status}` },
          { type: 'mrkdwn', text: `Project ID:\n${project.id}`  },
        ],
      }
    ],
  };

  const response = await fetch(process.env.SLACK_WEBHOOK_URL, {
    method:  'POST',
    headers: { 'Content-Type': 'application/json' },
    body:    JSON.stringify(slackPayload),
  });

  if (!response.ok) throw new Error(`Slack API error: ${response.status}`);
}, { connection: { host: 'localhost', port: 6379 } });

// WHAT: APIForge project search — search index pattern using Meilisearch
// File: src/controllers/search.controller.js
// Search hits the index, not the database. Index is updated on every write.

import { MeiliSearch } from 'meilisearch';
const search = new MeiliSearch({ host: process.env.MEILISEARCH_URL });
const index  = search.index('projects');

// ── Search endpoint — GET /api/search?q=gateway&status=active&limit=10 ────
export async function searchProjects(req, res) {
  const {
    q      = '',
    status,
    limit  = 20,
    offset = 0,   // offset is fine here — search results are stateless snapshots
  } = req.query;

  const filters = status ? `status = "${status}"` : undefined;

  const results = await index.search(q, {
    limit:             parseInt(limit),
    offset:            parseInt(offset),
    filter:            filters,
    attributesToHighlight: ['name', 'description'],  // wrap matches in <em> tags
    highlightPreTag:   '',
    highlightPostTag:  '',
  });

  res.json({
    query:       q,
    hits:        results.hits,
    total:       results.estimatedTotalHits,
    processingMs: results.processingTimeMs,
    limit:       parseInt(limit),
    offset:      parseInt(offset),
  });
}

// ── Keep index in sync — called from project create/update/delete routes ──
export async function syncProjectToIndex(project, operation = 'upsert') {
  if (operation === 'delete') {
    await index.deleteDocument(project.id);
    return;
  }
  await index.addDocuments([{
    id:          project.id,
    name:        project.name,
    description: project.description,
    status:      project.status,
    ownerEmail:  project.owner.email,
    createdAt:   project.createdAt,
  }]);
}

// WHAT: APIForge file upload — pre-signed URL pattern with AWS S3
// File: src/controllers/uploads.controller.js
// Client uploads directly to S3 — API server handles only metadata

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl }               from '@aws-sdk/s3-request-presigner';

const s3 = new S3Client({ region: process.env.AWS_REGION });

// Step 1: Client requests a pre-signed upload URL
export async function getUploadUrl(req, res) {
  const { projectId, filename, contentType, fileSizeBytes } = req.body;

  // Validate file size before issuing the URL (50MB limit)
  if (fileSizeBytes > 50 * 1024 * 1024) {
    return res.status(413).json({
      error: { type: 'invalid_request_error', code: 'file_too_large',
               message: 'Files must be under 50MB.' }
    });
  }

  // Allowed types only
  const allowed = ['application/pdf', 'image/png', 'image/jpeg'];
  if (!allowed.includes(contentType)) {
    return res.status(415).json({
      error: { type: 'invalid_request_error', code: 'unsupported_media_type',
               message: `Content type ${contentType} is not permitted.` }
    });
  }

  const key = `projects/${projectId}/${Date.now()}-${filename}`;

  const command = new PutObjectCommand({
    Bucket:      process.env.S3_BUCKET,
    Key:         key,
    ContentType: contentType,
  });

  // URL expires in 5 minutes — client must upload within this window
  const uploadUrl = await getSignedUrl(s3, command, { expiresIn: 300 });

  // Record the pending upload in the database
  const attachment = await db.attachments.create({
    projectId, key, filename, contentType, fileSizeBytes,
    status:    'pending',   // becomes 'ready' when S3 confirms upload
    uploadedBy: req.user.userId,
  });

  res.status(200).json({
    uploadUrl,                            // client POSTs file bytes here
    attachmentId: attachment.id,          // client sends this on completion
    expiresAt:    new Date(Date.now() + 300000).toISOString(),
  });
}

// WHAT: APIForge GitHub integration — OAuth token exchange + webhook handler
// File: src/controllers/github.controller.js
// OAuth flow: redirect → callback → exchange code for token → store token

// Step 1: Redirect user to GitHub to approve access
export function initiateOAuth(req, res) {
  const params = new URLSearchParams({
    client_id:    process.env.GITHUB_CLIENT_ID,
    redirect_uri: 'https://api.apiforge.dev/integrations/github/callback',
    scope:        'repo:status read:user',  // minimum required scopes only
    state:        generateCsrfToken(req),   // prevents CSRF attacks on the callback
  });
  res.redirect(`https://github.com/login/oauth/authorize?${params}`);
}

// Step 2: GitHub redirects back with a one-time code — exchange for access token
export async function handleOAuthCallback(req, res) {
  const { code, state } = req.query;

  if (!verifyCsrfToken(req, state)) {
    return res.status(400).json({ error: 'Invalid state parameter — possible CSRF attack' });
  }

  const tokenResponse = await fetch('https://github.com/login/oauth/access_token', {
    method:  'POST',
    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
    body:    JSON.stringify({
      client_id:     process.env.GITHUB_CLIENT_ID,
      client_secret: process.env.GITHUB_CLIENT_SECRET,
      code,
    }),
  });

  const { access_token, scope, token_type } = await tokenResponse.json();

  // Store the encrypted token — never log or expose it
  await db.integrations.upsert({
    userId:          req.user.userId,
    provider:        'github',
    accessToken:     encrypt(access_token),  // encrypted at rest
    scopes:          scope,
    connectedAt:     new Date().toISOString(),
  });

  res.redirect('/settings/integrations?github=connected');
}

// Step 3: GitHub webhook fires when a PR merges — update project status
export async function handleGithubWebhook(req, res) {
  // Verify signature (same HMAC pattern as Lesson 34)
  verifyGithubSignature(req.body, req.headers['x-hub-signature-256']);

  const event   = req.headers['x-github-event'];
  const payload = JSON.parse(req.body);

  if (event === 'pull_request' && payload.action === 'closed' && payload.pull_request.merged) {
    const repoFullName = payload.repository.full_name;
    const project      = await db.projects.findByRepo(repoFullName);

    if (project) {
      await db.projects.update(project.id, {
        lastMergedAt: new Date().toISOString(),
        prCount:      project.prCount + 1,
      });
    }
  }

  res.status(200).json({ received: true }); // always acknowledge quickly
}