@farthershore/product 0.3.1 → 0.4.0

package/README.md

@@ -2,11 +2,12 @@
 
 Product-as-Code SDK for Farther Shore. Builder repos use this package from
 `product/product.config.ts` to declare product contracts in TypeScript. Builders
-author and export a `Business`; Farther Shore compiles that program to
-backend-owned IR, validates it, and applies it through Core. Every product is
-created with a GitHub repo that contains the editable `frontend/` starter and
-the Product SDK entrypoint; connecting GitHub is a product-creation
-precondition.
+author and export a `Product`; Farther Shore compiles that program to
+backend-owned IR, validates it, and applies it through Core. The Product SDK
+describes the sellable software product: its business logic origin,
+surfaces, plans, capabilities, meters, and lifecycle. Every product is created
+with a GitHub repo that contains the editable `frontend/` starter and the
+Product SDK entrypoint; connecting GitHub is a product-creation precondition.
 
 ## Install
 
@@ -47,15 +48,17 @@ import { configureMeters } from "./meters.js";
 import { configureCronRoutes } from "./routes/cron.js";
 import { configurePlans } from "./plans/index.js";
 
-const business = fs.business("croncloud", {
-  baseUrl: "https://api.example.com",
+const product = fs.product("croncloud", {
+  origin: "https://app.example.com",
   displayName: "CronCloud",
   description: "Managed cron jobs",
 });
 
-business.use(configureMeters, configureCronRoutes, configurePlans);
+product.surface("frontend");
+product.surface("api");
+product.use(configureMeters, configureCronRoutes, configurePlans);
 
-export default business;
+export default product;
 ```
 
 Modules are plain synchronous functions:
@@ -100,7 +103,7 @@ plain request counting.
 
 ```ts
 const product = fs.product("croncloud", {
-  baseUrl: "https://api.croncloud.com",
+  origin: "https://app.croncloud.com",
 });
 
 product.requests();
@@ -145,18 +148,18 @@ Generated product repos use GitHub as the required automation and frontend
 workspace:
 
 1. Loads `product/product.config.ts`.
-2. Requires the default export to be the `Business` returned by
-   `fs.business(...)` or `fs.product(...)`.
-3. Executes imported modules and compiles the business into deterministic
+2. Requires the default export to be the `Product` returned by
+   `fs.product(...)`.
+3. Executes imported modules and compiles the product into deterministic
    Manifest IR.
 4. Validates the result against the deployed platform contract.
 5. Publishes the accepted release through Core so edge artifacts propagate.
 
-The same IR can also be applied to an already repo-backed product through
-trusted Core APIs, for example `farthershore build --apply <product>`. That path
-is useful for local validation/apply loops, but it is not a replacement for the
-product repo. The repo remains the required frontend customization workspace
-because `frontend/` is where the starter UI and all custom React code live.
+The same IR can be built locally with `farthershore build`; accepted lifecycle
+state is validated and applied by the GitHub bot after `product/**` changes are
+committed and pushed. The repo remains the required frontend customization
+workspace because `frontend/` is where the starter UI and all custom React code
+live.
 
 The bundled `farthershore-manifest-build` binary is shared by the bot,
 build-runner, and CLI. It emits the deterministic Manifest IR envelope that Core
@@ -164,24 +167,32 @@ accepts; Core, not the user repo, remains the lifecycle authority.
 
 ## Public API
 
-- `fs.business(name, options)` / `fs.product(name, options)` — create the
-  product builder.
-- `business.use(...modules)` — compose Product SDK modules from any files under
+- `fs.product(name, options)` — create the product builder. `options.origin`
+  is required and is the business logic origin Farther Shore calls for
+  customer-facing actions.
+- `product.use(...modules)` — compose Product SDK modules from any files under
   `product/`.
-- `business.meter(...)` — declare billable or enforceable dimensions.
-- `business.requests()` — declare and inherit the platform-managed successful
+- `product.surface(...)` — declare the product surfaces customers interact with
+  (`frontend`, `api`, `docs`, `widget`, `webhook`, `worker`, or `agent`).
+- `product.entitlement(...)` — group capabilities, feature gates, limits, and
+  meters into reusable access metadata.
+- `product.offering.plan(...)` — declare a subscription plan through the
+  generalized offering namespace. `product.plan(...)` remains the direct plan
+  helper.
+- `product.meter(...)` — declare billable or enforceable dimensions.
+- `product.requests()` — declare and inherit the platform-managed successful
   request meter.
-- `business.defaultMeters(...)` — apply reusable fixed costs to metered routes.
-- `business.resource(...)` — declare counted resources for resource-count
+- `product.defaultMeters(...)` — apply reusable fixed costs to metered routes.
+- `product.resource(...)` — declare counted resources for resource-count
   constraints.
-- `business.capability(...)` — declare capability bundles and plan grants.
-- `business.feature(...)` / `business.api.route(...)` — declare gateway routes,
+- `product.capability(...)` — declare capability bundles and plan grants.
+- `product.feature(...)` / `product.api.route(...)` — declare gateway routes,
   static costs, dynamic reports, estimates, and action metadata.
-- `business.policy(...)` — declare policy files in code.
-- `business.plan(...)` — declare plan pricing, limits, grants, and lifecycle
+- `product.policy(...)` — declare policy files in code.
+- `product.plan(...)` — declare plan pricing, limits, grants, and lifecycle
   behavior.
-- `business.lifecycle.*` — declare migrations.
-- `business.raw.*` — escape hatches for platform-schema JSON when the typed SDK
+- `product.lifecycle.*` — declare migrations.
+- `product.raw.*` — escape hatches for platform-schema JSON when the typed SDK
   does not yet have sugar.
 
 ## Determinism

package/dist/bin.js

@@ -1393,7 +1393,7 @@ var customerPortalAuthStrategySchema = z13.enum([
 var productCustomerContextSchema = z13.object({
   /**
    * Edge credential identity policy. This is intentionally Product-scoped:
-   * B7 keeps Product as the business boundary and avoids customer-side
+   * B7 keeps Product as the product boundary and avoids customer-side
    * Workspace/subject models until per-subject entitlements need them.
    */
   identity_requirement: customerIdentityRequirementSchema.optional(),
@@ -1414,6 +1414,70 @@ var productCustomerContextSchema = z13.object({
     strategy: customerPortalAuthStrategySchema
   }).optional()
 });
+var productSurfaceTypeSchema = z13.enum([
+  "frontend",
+  "api",
+  "docs",
+  "widget",
+  "dashboard",
+  "webhook",
+  "worker",
+  "agent"
+]);
+var productSurfaceSchema = z13.object({
+  key: z13.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Surface key must be lowercase alphanumeric with hyphens/underscores"),
+  type: productSurfaceTypeSchema,
+  display: z13.string().min(1).max(100).optional(),
+  description: z13.string().max(500).optional()
+});
+var productEntitlementSchema = z13.object({
+  key: z13.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Entitlement key must be lowercase alphanumeric with hyphens/underscores"),
+  description: z13.string().max(500).optional(),
+  capabilities: z13.array(z13.string().min(1).max(100)).max(100).optional(),
+  featureGates: z13.record(z13.string().min(1), z13.boolean()).optional(),
+  limits: z13.array(planLimitRuleSchema).max(100).optional(),
+  meters: z13.array(z13.string().min(1).max(64)).max(100).optional()
+});
+var productSurfacesSchema = z13.array(productSurfaceSchema).max(20).default([]);
+var productEntitlementsSchema = z13.array(productEntitlementSchema).max(100).default([]);
+var productWorkflowKindSchema = z13.enum([
+  "async_job",
+  "agent_task",
+  "scheduled",
+  "lifecycle",
+  "background"
+]);
+var productWorkflowTriggerSchema = z13.discriminatedUnion("type", [
+  z13.object({ type: z13.literal("manual") }),
+  z13.object({
+    type: z13.literal("schedule"),
+    cron: z13.string().min(1).max(120)
+  }),
+  z13.object({
+    type: z13.literal("event"),
+    event: z13.string().min(1).max(120)
+  }),
+  z13.object({
+    type: z13.literal("api"),
+    path: z13.string().min(1).max(240).regex(/^\//, "path must start with /")
+  }),
+  z13.object({
+    type: z13.literal("lifecycle"),
+    event: z13.string().min(1).max(120)
+  })
+]);
+var productWorkflowSchema = z13.object({
+  key: z13.string().min(1).max(64).regex(/^[a-z0-9_-]+$/, "Workflow key must be lowercase alphanumeric with hyphens/underscores"),
+  title: z13.string().min(1).max(120).optional(),
+  description: z13.string().max(1e3).optional(),
+  kind: productWorkflowKindSchema,
+  trigger: productWorkflowTriggerSchema,
+  capabilities: z13.array(z13.string().min(1).max(100)).max(100).optional(),
+  meters: z13.array(z13.string().min(1).max(64)).max(100).optional(),
+  estimates: z13.record(z13.string().min(1).max(64), z13.number().finite()).optional(),
+  metadata: z13.record(z13.string().min(1), z13.unknown()).optional()
+});
+var productWorkflowsSchema = z13.array(productWorkflowSchema).max(100).default([]);
 var productSpecSchema = z13.object({
   product: z13.object({
     name: z13.string().min(1).max(100),
@@ -1447,6 +1511,9 @@ var productSpecSchema = z13.object({
   resources: countedResourcesSchema,
   policies: productOperatorPoliciesSchema,
   customer_context: productCustomerContextSchema.optional(),
+  surfaces: productSurfacesSchema,
+  entitlements: productEntitlementsSchema,
+  workflows: productWorkflowsSchema,
   /**
    * Legacy/internal declarative frontend surface. New product repos customize
    * the generated `frontend/` project directly; this remains for existing IR
@@ -2156,6 +2223,9 @@ var productSpecV2Schema = z20.object({
   resources: countedResourcesSchema,
   policies: productOperatorPoliciesSchema,
   customer_context: productCustomerContextSchema.optional(),
+  surfaces: productSurfacesSchema,
+  entitlements: productEntitlementsSchema,
+  workflows: productWorkflowsSchema,
   billing: z20.object({
     gracePeriodDays: z20.number().int().nonnegative().default(3),
     // When true (default), a plan limit INCREASE re-projects onto active
@@ -2353,10 +2423,10 @@ function hashIr(ir) {
 }
 
 // src/version.ts
-var SDK_VERSION = true ? "0.3.1" : "0.0.0-dev";
+var SDK_VERSION = true ? "0.4.0" : "0.0.0-dev";
 
-// src/business.ts
-var BUSINESS_BRAND = Symbol.for("farthershore.product.business");
+// src/product.ts
+var PRODUCT_BRAND = Symbol.for("farthershore.product.product");
 function isCapabilityGrant(value) {
   return typeof value === "object" && value !== null && value.kind === "capability_grant";
 }
@@ -2401,8 +2471,8 @@ function parseRouteMatch(match) {
   }
   return { method, path };
 }
-var Business = class {
-  [BUSINESS_BRAND] = true;
+var Product = class {
+  [PRODUCT_BRAND] = true;
   name;
   options;
   graph = new ManifestResourceGraph();
@@ -2413,15 +2483,16 @@ var Business = class {
   api;
   frontend;
   lifecycle;
+  offering;
   /** Escape hatches — raw platform-schema JSON, validated at toIR(). */
   raw;
   constructor(name, options) {
     if (!name || typeof name !== "string") {
-      throw new ManifestBuilderError("fs.business(name, \u2026): name is required");
+      throw new ManifestBuilderError("fs.product(name, \u2026): name is required");
     }
-    if (!options?.baseUrl) {
+    if (!options?.origin) {
       throw new ManifestBuilderError(
-        `fs.business("${name}", \u2026): options.baseUrl is required (the upstream origin the gateway proxies to)`
+        `fs.product("${name}", \u2026): options.origin is required (the business logic origin Farther Shore calls for customer-facing actions)`
       );
     }
     this.name = name;
@@ -2436,7 +2507,7 @@ var Business = class {
         const file = this.getFeatureFile(featureKey);
         if (!file) {
           throw new ManifestBuilderError(
-            `api.route("${match}"): feature "${featureKey}" is not declared \u2014 call business.feature("${featureKey}", \u2026) first`
+            `api.route("${match}"): feature "${featureKey}" is not declared \u2014 call product.feature("${featureKey}", \u2026) first`
           );
         }
         file.routes.push(this.buildRoute(match, options2));
@@ -2529,6 +2600,9 @@ var Business = class {
         return this;
       }
     };
+    this.offering = {
+      plan: (key, options2) => this.plan(key, options2)
+    };
     this.raw = {
       productPatch: (patch) => {
         this.productPatch = deepMerge(this.productPatch, patch);
@@ -2699,6 +2773,57 @@ var Business = class {
     this.graph.register("policy", name, file, this.policyDependsOn(file));
     return { kind: "policy", key: name };
   }
+  surface(type, options = {}) {
+    const key = options.key ?? type;
+    this.assertNewKey("surface", key, "surface");
+    const surface = {
+      key,
+      type,
+      ...options.display !== void 0 ? { display: options.display } : {},
+      ...options.description !== void 0 ? { description: options.description } : {}
+    };
+    this.graph.register("surface", key, surface);
+    return { kind: "surface", key };
+  }
+  workflow(key, options = {}) {
+    this.assertNewKey("workflow", key, "workflow");
+    const workflow = {
+      key,
+      kind: options.kind ?? "async_job",
+      trigger: options.trigger ?? { type: "manual" },
+      ...options.title !== void 0 ? { title: options.title } : {},
+      ...options.description !== void 0 ? { description: options.description } : {},
+      ...options.capabilities?.length ? { capabilities: options.capabilities.map(keyOf) } : {},
+      ...options.meters?.length ? { meters: options.meters.map(keyOf) } : {},
+      ...options.estimates !== void 0 ? { estimates: options.estimates } : {},
+      ...options.metadata !== void 0 ? { metadata: options.metadata } : {}
+    };
+    this.graph.register(
+      "workflow",
+      key,
+      workflow,
+      this.workflowDependsOn(workflow)
+    );
+    return { kind: "workflow", key };
+  }
+  entitlement(key, options = {}) {
+    this.assertNewKey("entitlement", key, "entitlement");
+    const entitlement = {
+      key,
+      ...options.description !== void 0 ? { description: options.description } : {},
+      ...options.capabilities?.length ? { capabilities: options.capabilities.map(keyOf) } : {},
+      ...options.featureGates !== void 0 ? { featureGates: options.featureGates } : {},
+      ...options.limits?.length ? { limits: options.limits } : {},
+      ...options.meters?.length ? { meters: options.meters.map(keyOf) } : {}
+    };
+    this.graph.register(
+      "entitlement",
+      key,
+      entitlement,
+      this.entitlementDependsOn(entitlement)
+    );
+    return { kind: "entitlement", key };
+  }
   plan(key, options) {
     this.assertNewKey("plan", key, "plan");
     const capabilityKeys = (options.capabilities ?? []).map(keyOf);
@@ -2765,16 +2890,14 @@ var Business = class {
   /** Assemble + validate the Manifest IR. Throws ManifestValidationError
    *  with structured issues when the declared state is invalid. */
   toIR() {
+    const routes = this.materializeFeatureFiles();
+    this.assertRouteMeteringValid(routes);
     this.assertGraphDependenciesSatisfied();
-    this.assertRouteMeteringValid();
     const candidate = {
       irVersion: 1,
       sdkVersion: SDK_VERSION,
       product: this.buildProductSpec(),
-      routes: this.graph.sortedValues(
-        "feature",
-        (file) => file.feature
-      ),
+      routes,
       policies: this.graph.sortedValues(
         "policy",
         (file) => file.name
@@ -2794,10 +2917,10 @@ var Business = class {
     const base = {
       product: {
         name: this.name,
-        baseUrl: options.baseUrl,
+        baseUrl: options.origin,
         ...options.displayName !== void 0 ? { displayName: options.displayName } : {},
         ...options.description !== void 0 ? { description: options.description } : {},
-        ...options.sandboxBaseUrl !== void 0 ? { sandboxBaseUrl: options.sandboxBaseUrl } : {},
+        ...options.sandboxOrigin !== void 0 ? { sandboxBaseUrl: options.sandboxOrigin } : {},
         ...options.visibility !== void 0 ? { visibility: options.visibility } : {},
         ...options.logoUrl !== void 0 ? { logoUrl: options.logoUrl } : {},
         ...options.primaryColor !== void 0 ? { primaryColor: options.primaryColor } : {},
@@ -2814,6 +2937,24 @@ var Business = class {
       ...options.billing !== void 0 ? { billing: options.billing } : {},
       ...options.operatorPolicies !== void 0 ? { policies: options.operatorPolicies } : {},
       ...options.customerContext !== void 0 ? { customer_context: buildCustomerContext(options.customerContext) } : {},
+      ...this.graph.values("surface").length ? {
+        surfaces: this.graph.sortedValues(
+          "surface",
+          (surface) => surface.key
+        )
+      } : {},
+      ...this.graph.values("entitlement").length ? {
+        entitlements: this.graph.sortedValues(
+          "entitlement",
+          (entitlement) => entitlement.key
+        )
+      } : {},
+      ...this.graph.values("workflow").length ? {
+        workflows: this.graph.sortedValues(
+          "workflow",
+          (workflow) => workflow.key
+        )
+      } : {},
       ...this.graph.has("frontend", "manifest") ? {
         frontend: this.graph.get(
           "frontend",
@@ -2849,6 +2990,9 @@ var Business = class {
   }
   routeValueMeterKeys() {
     const keys = /* @__PURE__ */ new Set();
+    for (const cost of this.defaultMeterCosts) {
+      keys.add(cost.meter);
+    }
     for (const file of this.graph.values("feature")) {
       for (const route of file.routes) {
         for (const meter of Object.keys(route.metering?.defaults ?? {})) {
@@ -2859,6 +3003,11 @@ var Business = class {
         }
       }
     }
+    for (const workflow of this.graph.values("workflow")) {
+      for (const meter of workflow.meters ?? []) keys.add(meter);
+      for (const meter of Object.keys(workflow.estimates ?? {}))
+        keys.add(meter);
+    }
     return keys;
   }
   buildRoute(match, options) {
@@ -2883,11 +3032,6 @@ var Business = class {
   buildRouteMetering(options) {
     if (options.unmetered === true) return void 0;
     const defaults = {};
-    if (options.inheritDefaultMeters !== false) {
-      for (const cost of this.defaultMeterCosts) {
-        defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
-      }
-    }
     for (const cost of this.normalizeMeterCosts(options.costs)) {
       defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
     }
@@ -2915,6 +3059,32 @@ var Business = class {
       out.onStatusCodes = options.onStatusCodes;
     return Object.keys(out).length ? out : void 0;
   }
+  materializeFeatureFiles() {
+    return this.graph.sortedValues("feature", (file) => file.feature).map((file) => ({
+      ...file,
+      routes: file.routes.map((route) => this.materializeRoute(route))
+    }));
+  }
+  materializeRoute(route) {
+    if (route.unmetered === true) return route;
+    const defaults = {
+      ...route.metering?.defaults ?? {}
+    };
+    if (route.inheritDefaultMeters !== false) {
+      for (const cost of this.defaultMeterCosts) {
+        defaults[cost.meter] = (defaults[cost.meter] ?? 0) + cost.value;
+      }
+    }
+    const hasMetering = route.metering !== void 0 || Object.keys(defaults).length > 0;
+    const metering = hasMetering ? {
+      ...route.metering ?? {},
+      ...Object.keys(defaults).length ? { defaults } : {}
+    } : void 0;
+    return {
+      ...route,
+      ...metering ? { metering } : {}
+    };
+  }
   normalizeMeterCost(cost) {
     if (!cost || cost.kind !== "meter_cost") {
       throw new ManifestBuilderError(
@@ -3039,6 +3209,27 @@ var Business = class {
   policyDependsOn(file) {
     return this.dependenciesFor("meter", file.compatible_with?.meters);
   }
+  entitlementDependsOn(entitlement) {
+    const limitDimensions = (entitlement.limits ?? []).map(
+      (limit) => limit.dimension
+    );
+    return [
+      ...this.dependenciesFor("capability", entitlement.capabilities),
+      ...this.existingDependenciesFor("meter", [
+        ...entitlement.meters ?? [],
+        ...limitDimensions
+      ])
+    ];
+  }
+  workflowDependsOn(workflow) {
+    return [
+      ...this.dependenciesFor("capability", workflow.capabilities),
+      ...this.dependenciesFor("meter", [
+        ...workflow.meters ?? [],
+        ...Object.keys(workflow.estimates ?? {})
+      ])
+    ];
+  }
   featureDependsOn(file) {
     const meterKeys = file.routes.flatMap(
       (route) => this.routeMeterDependencyKeys(route)
@@ -3061,12 +3252,26 @@ var Business = class {
     }
     return [...keys];
   }
-  assertRouteMeteringValid() {
-    for (const file of this.graph.values("feature")) {
+  assertRouteMeteringValid(files) {
+    const declaredMeters = new Set(
+      this.graph.values("meter").map((meter) => meter.key)
+    );
+    for (const file of files) {
       file.routes.forEach((route, routeIndex) => {
         if (route.unmetered === true) return;
         const defaults = new Set(Object.keys(route.metering?.defaults ?? {}));
+        for (const meter of defaults) {
+          if (declaredMeters.has(meter)) continue;
+          throw new ManifestBuilderError(
+            `feature "${file.feature}" route ${routeIndex}: fixed meter "${meter}" is not declared \u2014 declare it with product.meter("${meter}", ...) first`
+          );
+        }
         for (const meter of route.metering?.reports ?? []) {
+          if (!declaredMeters.has(meter)) {
+            throw new ManifestBuilderError(
+              `feature "${file.feature}" route ${routeIndex}: reported meter "${meter}" is not declared \u2014 declare it with product.meter("${meter}", ...) first`
+            );
+          }
           if (defaults.has(meter)) {
             throw new ManifestBuilderError(
               `feature "${file.feature}" route ${routeIndex}: meter "${meter}" cannot be both a fixed route cost and a dynamic report`
@@ -3089,6 +3294,12 @@ var Business = class {
             );
           }
         }
+        for (const meter of Object.keys(route.metering?.estimates ?? {})) {
+          if (declaredMeters.has(meter)) continue;
+          throw new ManifestBuilderError(
+            `feature "${file.feature}" route ${routeIndex}: estimate meter "${meter}" is not declared \u2014 declare it with product.meter("${meter}", ...) first`
+          );
+        }
       });
     }
   }
@@ -3144,8 +3355,8 @@ var Business = class {
     return [...new Set(keys)].filter((key) => this.graph.has(kind, key)).map((key) => resourceDependency(kind, key));
   }
 };
-function isBusiness(value) {
-  return typeof value === "object" && value !== null && value[BUSINESS_BRAND] === true;
+function isProduct(value) {
+  return typeof value === "object" && value !== null && value[PRODUCT_BRAND] === true;
 }
 function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -3154,7 +3365,7 @@ function buildCustomerContext(options) {
   return {
     ...options.identityRequirement !== void 0 ? { identity_requirement: options.identityRequirement } : {},
     ...options.contextTokens !== void 0 ? { context_tokens: options.contextTokens } : {},
-    ...options.portalAuth !== void 0 ? { portal_auth: options.portalAuth } : {}
+    ...options.customerAuth !== void 0 ? { portal_auth: options.customerAuth } : {}
   };
 }
 function deepMerge(base, patch) {
@@ -3267,10 +3478,10 @@ async function main() {
   }
   const direct = mod.default;
   const interop = direct?.default;
-  const candidate = isBusiness(direct) ? direct : interop;
-  if (!isBusiness(candidate)) {
+  const candidate = isProduct(direct) ? direct : interop;
+  if (!isProduct(candidate)) {
     process.stderr.write(
-      `farthershore-manifest-build: ${resolvedEntry.entry} must \`export default\` the Business returned by fs.business(\u2026)
+      `farthershore-manifest-build: ${resolvedEntry.entry} must \`export default\` the Product returned by fs.product(\u2026)
 `
     );
     process.exit(1);