// ❌ WRONG - Standard Koa (does NOT work in Firebase)
const data = ctx.request.body;

// ✅ CORRECT - Firebase/Koa
const data = ctx.req.body;

packages/functions/src/
├── routes/              # Route definitions
│   ├── api.js           # Admin API routes
│   ├── restApiV2.js     # Public REST API v2
│   └── apiHookV1.js     # Webhook routes
├── controllers/         # Request handlers
├── middleware/          # Auth, validation, rate limiting
├── validations/         # Yup schemas
└── helpers/
    └── restApiResponse.js  # Response helpers

import {
  successResponse,
  errorResponse,
  paginatedResponse,
  itemResponse
} from '../helpers/restApiResponse';

// Single item
ctx.body = itemResponse(customer);

// Paginated list
ctx.body = paginatedResponse(customers, pageInfo, total);

// Error
ctx.status = 400;
ctx.body = errorResponse('Invalid email', 'VALIDATION_ERROR', 400);

import Router from 'koa-router';

const router = new Router({prefix: '/api/v2'});

router.use(verifyAuthenticate);
router.use(verifyPlanAccess);

// Resources
router.get('/customers', validateQuery(paginationSchema), getCustomers);
router.get('/customers/:id', getCustomer);
router.post('/customers', validateInput(createSchema), createCustomer);
router.put('/customers/:id', validateInput(updateSchema), updateCustomer);

// Sub-resources
router.get('/customers/:id/rewards', getCustomerRewards);

// Actions
router.post('/customers/:id/points/award', awardPoints);

import * as Yup from 'yup';

export const createCustomerSchema = Yup.object({
  email: Yup.string().email().required(),
  firstName: Yup.string().max(100).optional(),
  points: Yup.number().positive().optional()
});

export const paginationSchema = Yup.object({
  limit: Yup.number().min(1).max(100).default(20),
  cursor: Yup.string().optional()
});

export function validateInput(schema) {
  return async (ctx, next) => {
    try {
      ctx.request.body = await schema.validate(ctx.request.body, {
        stripUnknown: true
      });
      await next();
    } catch (error) {
      ctx.status = 400;
      ctx.body = errorResponse(error.message, 'VALIDATION_ERROR', 400);
    }
  };
}

export async function getOne(ctx) {
  try {
    const {shop} = ctx.state;
    const {id} = ctx.params;

    const resource = await repository.getById(shop.id, id);

    if (!resource) {
      ctx.status = 404;
      ctx.body = errorResponse('Not found', 'NOT_FOUND', 404);
      return;
    }

    ctx.body = itemResponse(pick(resource, publicFields));
  } catch (error) {
    console.error('Error:', error);
    ctx.status = 500;
    ctx.body = errorResponse('Server error', 'INTERNAL_ERROR', 500);
  }
}

// Request
GET /api/customers?limit=20&cursor=eyJpZCI6IjEyMyJ9

// Response
{
  "data": [...],
  "meta": {
    "pagination": {
      "hasNext": true,
      "nextCursor": "eyJpZCI6IjE0MyJ9",
      "limit": 20
    }
  }
}

□ Uses response helpers (successResponse/errorResponse)
□ Correct HTTP status codes
□ Input validated with Yup schema
□ Queries scoped by shopId
□ Response fields picked (no internal data)
□ Error handling with try-catch
□ Rate limiting applied
□ Authentication middleware

packages/functions/src/
├── routes/
│   └── clientApi.js           # Public storefront routes
├── controllers/
│   └── clientApi/             # Storefront handlers
│       └── featureClientController.js
└── presenters/
    └── featurePresenter.js    # Strip PII before response

// routes/clientApi.js
import Router from 'koa-router';
import * as featureController from '../controllers/clientApi/featureClientController';

const router = new Router({prefix: '/clientApi'});

// No authentication middleware - public endpoints
// Shop identified via app proxy 'shop' query param

// Read endpoints
router.get('/feature/:resourceId', featureController.getResource);
router.get('/feature/bulk', featureController.getBulkResources);

// Write endpoints (may check logged_in_customer_id)
router.post('/feature', featureController.submitResource);

// Settings (filtered for storefront)
router.get('/feature/settings', featureController.getSettings);

export default router;

// Helper function in controller
async function getShopFromQuery(ctx) {
  const shopDomain = ctx.query.shop || ctx.query.shopifyDomain;

  if (!shopDomain) {
    return {shop: null, error: 'Missing shop parameter'};
  }

  const shop = await shopRepository.getShopByShopifyDomain(shopDomain);
  if (!shop) {
    return {shop: null, error: 'Shop not found'};
  }

  return {shop, error: null};
}

// controllers/clientApi/featureClientController.js
import * as featureService from '../../services/featureService';
import {presentForStorefront} from '../../presenters/featurePresenter';

export async function getResource(ctx) {
  const {resourceId} = ctx.params;
  const {limit, cursor} = ctx.query;

  // Resolve shop from app proxy
  const {shop, error} = await getShopFromQuery(ctx);
  if (error) {
    ctx.body = {success: false, error};
    return;
  }

  const result = await featureService.getResource(shop.id, resourceId, {
    limit: limit ? parseInt(limit, 10) : 10,
    startAfter: cursor
  });

  // CRITICAL: Strip PII before returning to storefront
  ctx.body = {
    ...result,
    data: {
      ...result.data,
      items: presentForStorefront(result.data.items)
    }
  };
}

export async function submitResource(ctx) {
  const inputData = ctx.req.body;

  const {shop, error} = await getShopFromQuery(ctx);
  if (error) {
    ctx.body = {success: false, error};
    return;
  }

  // Get customer ID from app proxy if logged in
  const customerId = ctx.query.logged_in_customer_id || null;
  if (customerId) {
    inputData.customerId = customerId;
  }

  const result = await featureService.createResource(shop.id, inputData);
  ctx.body = result;
}

export async function getBulkResources(ctx) {
  let {ids} = ctx.query;

  const {shop, error} = await getShopFromQuery(ctx);
  if (error) {
    ctx.body = {success: false, error};
    return;
  }

  // Handle comma-separated string
  if (typeof ids === 'string') {
    ids = ids.split(',').map(id => id.trim());
  }

  // CRITICAL: Limit array size to prevent abuse
  if (ids.length > 100) {
    ctx.body = {success: false, error: 'Maximum 100 items allowed'};
    return;
  }

  const result = await featureService.getBulkResources(shop.id, ids);
  ctx.body = result;
}

export async function getSettings(ctx) {
  const {shop, error} = await getShopFromQuery(ctx);
  if (error) {
    ctx.body = {success: false, error};
    return;
  }

  const result = await featureService.getSettings(shop.id);

  // Only expose necessary settings for storefront
  ctx.body = {
    success: true,
    data: {
      enabled: result.data.enabled,
      primaryColor: result.data.primaryColor
      // Don't expose: internalFlags, adminSettings, etc.
    }
  };
}

// presenters/featurePresenter.js

export function presentForStorefront(item) {
  if (!item) return null;

  // Destructure to exclude sensitive fields
  // eslint-disable-next-line no-unused-vars
  const {email, customerId, shopId, internalId, ...safeItem} = item;

  return safeItem;
}

export function presentListForStorefront(items) {
  if (!Array.isArray(items)) return [];
  return items.map(presentForStorefront);
}

□ Shop resolved from ctx.query.shop (app proxy)
□ No authentication middleware (public)
□ PII stripped via presenters before response
□ Array inputs have size limits
□ Settings expose only needed fields
□ Customer ID from logged_in_customer_id (optional)
□ Proper error responses for missing shop