Route groups & grants

fs.group(id, members) creates a reusable bundle of route refs and other group refs. Plans grant the group directly.

import * as fs from "@farthershore/business";
fs.backend("api");
const requests = fs.requests();

const listReports = fs.route("/v1/reports", { get: {} });
const createReport = fs.route("/v1/reports", { post: {} });
const reporting = fs.group("reporting", [listReports, createReport]);

fs.plan("pro", {
  kind: fs.plan.kind.flat,
  price: fs.money.usd(29).monthly(),
  grants: [reporting],
  limits: [requests.perMinute(600)],
});

export default fs.business();

A plain group is authoring-time composition. It does not create a customer-visible feature, permission namespace, or route. The compiled plan contains the concrete operation grants reached through the group.

A group declared with the permission option is different: its id becomes a custom permission subject that gates its member routes at the gateway. See Custom permission subjects.

Good uses#

• Reuse a stable set of operations across several plans.
• Compose a broad plan from smaller route families.
• Target the same route family with fs.meterRoutes(key, group, options).

Rules#

• Members must be authentic refs from the current compilation.
• Cycles and unused plain groups fail validation (a permission group counts as used by its permission declaration — it needs no plan grant).
• A group does not grant anything until a plan references it.
• Permission groups may not nest inside each other; plain groups may nest.
• Adding a route to a group changes every plan that grants the group; inspect the commercial-release diff before activation.

Use separate fs.route() declarations when methods have different policies or economics. A group is not a substitute for method-level route design.