Custom routes

// app/resources/post/post.routes.js (from the api template)
export default (r) => {
  r.get('/featured', { policy: 'public', summary: 'Latest published posts' }, async (ctx) => {
    const { items } = await ctx.service.list({ filter: { status: 'published' }, sort: { publishedAt: -1 }, limit: 5 }, ctx);
    return items; // raw documents are serialized with the post visibility rules
  });

  r.post('/:id/publish', { policy: 'owner | admin', summary: 'Publish a draft' }, (ctx) => ctx.service.publish(ctx.params.id, ctx));
};

import { badRequest, notFound } from '#calm';

export default (r) => {
  r.get('/stats', { policy: 'admin', summary: 'Post counts by status' }, async (ctx) => {
    const [drafts, published] = await Promise.all([
      ctx.service.model.countDocuments({ status: 'draft' }),
      ctx.service.model.countDocuments({ status: 'published' }),
    ]);
    return { drafts, published };                       // 200 { data: { drafts, published } }
  });

  r.post('/import', { policy: 'admin', status: 202 }, async (ctx) => {
    if (!Array.isArray(ctx.body?.items)) throw badRequest('items must be an array');
    ctx.app.background(() => ctx.service.importMany(ctx.body.items)); // your method, runs after the response
    return { queued: ctx.body.items.length };            // 202 { data: { queued } }
  });

  r.get('/by-slug/:slug', { policy: 'public' }, async (ctx) => {
    const post = await ctx.service.findOne({ slug: ctx.params.slug }, ctx);
    if (!post) throw notFound('Post not found');
    return post;                                          // serialized automatically
  });
};

r.post('/:id/discount', { policy: 'owner' }, async (ctx) => {
  if (ctx.doc.price < 1) throw badRequest('Too cheap to discount');
  return ctx.service.update(ctx.doc._id, { price: ctx.doc.price - 1 }, ctx);
});

import { f } from '#calm';

r.post('/quote', {
  policy: 'public',
  input: { qty: f.integer().required().min(1), coupon: f.string().max(20) },
}, (ctx) => ({ total: ctx.body.qty * 3 }));

{ "error": { "code": "VALIDATION_ERROR", "message": "Validation failed", "requestId": "...", "details": { "qty": "Must be at least 1" } } }

import { z } from 'zod';

r.post('/contact', {
  policy: 'public',
  input: z.object({ email: z.string().email(), message: z.string().min(10).max(2000) }),
  rateLimit: { windowMs: 60_000, max: 5 },
}, async (ctx) => {
  await ctx.app.mailer.send({ to: 'team@example.com', subject: 'Contact form', text: `${ctx.body.email}\n\n${ctx.body.message}` });
});

// app/routes.js
r.get('/me/summary', { policy: 'authenticated' }, async (ctx) => {
  const posts = await ctx.services.post.find({ author: ctx.user.id }, ctx);
  return {
    user: await ctx.serialize(ctx.user, 'user'),
    posts: await Promise.all(posts.map((p) => ctx.serialize(p, 'post'))),
  };
});

r.post('/upload', {
  policy: 'authenticated',
  status: 201,
  summary: 'Upload a file (multipart/form-data, field "file")',
  middleware: [uploadMiddleware('file')],
}, async (ctx) => {
  const file = ctx.req.file;
  if (!file) throw badRequest('Send the file as multipart/form-data in a field named "file"');
  return ctx.service.create({ originalName: file.originalname, mimeType: file.mimetype, size: file.size, key: file.filename }, ctx);
});

// app/routes.js
export default (r) => {
  r.get('/hello', { policy: 'public', summary: 'Say hello' }, (ctx) => ({
    message: `Hello from ${ctx.config.app.name}`,
    time: new Date().toISOString(),
  }));

  r.get('/dashboard', { policy: 'authenticated' }, async (ctx) => {
    const { total } = await ctx.services.post.list({ limit: 1 }, ctx);
    return { posts: total };
  });
};