YPF Backend Developer Guide

// Guard types available:
Visitors.ALL                    // Public access
Visitors.AUTHENTICATED          // Any logged-in user
Visitors.hasProfile("ADMIN", "MEMBER")  // Has one of these profiles
Visitors.hasRole(ADMIN.SUPER)   // Has specific role
Visitors.hasID((req) => req.Params.id)  // Matches constituent ID

// Combine guards:
anyOf(guard1, guard2)   // OR: passes if ANY guard passes
allOf(guard1, guard2)   // AND: passes if ALL guards pass

// Example: Allow ADMIN or resource owner
router.get(
  "/constituents/:constituentId",
  authenticate,
  validateParams(z.object({ constituentId: z.string() })),
  authorize(
    anyOf(
      Visitors.hasProfile("ADMIN"),
      Visitors.hasID((req) => req.Params.constituentId)
    )
  ),
  handler
);

// 1. Define a new role matcher
export const MEMBER = {
  // Matches any chapter lead role
  CHAPTERLEAD: Role.matches(/^MEMBER\.lead\..+$/),
  
  // Factory for specific chapter
  chapterLead: (chapterId: string) =>
    Role.new(`MEMBER.chapterlead.${chapterId}`),
};

// 2. Use in route authorization
authorize(
  anyOf(
    Visitors.hasRole(ADMIN.SUPER),
    Visitors.hasRole((req) => MEMBER.chapterLead(req.Params.id))
  )
)

router.post(
  "/:id/media",
  authenticate,
  filesUpload.mediaUpload.single("file"),
  validateParams(...),
  authorize(...),
  async (req, res, next) => {
    const file = req.file;  // Multer file
    const uploadMeta = await mediaUtils.storeMediumFile(file);
    // uploadMeta contains: externalId, type, width, height, size
  }
);

// Success response
{
  "success": true,
  "data": { ... },
  "message"?: "Optional message"
}

// Error response
{
  "success": false,
  "message": "Error description"
}

// Paginated response
{
  "success": true,
  "data": {
    "items": [...],
    "page": 1,
    "pageSize": 10,
    "total": 42
  }
}