@farthershore/product 0.6.0 → 0.6.1

package/dist/types/codegen/index.d.ts

@@ -1,2 +1,10 @@
-import type { ManifestIrDocument } from "../ir-types.js";
+import type { ManifestIrDocument, PlanSpecJson } from "../ir-types.js";
+/**
+ * Emit a single `product.plan("key", { ... })` statement — the structured plan
+ * block for WS4 dashboard authoring. Reuses the same faithful `planOptions` +
+ * `lit` printer as full-file generation (price sugar, grants, capability_limits,
+ * the `raw` escape hatch), so the snippet a builder applies via a GitHub edit /
+ * PR is byte-identical to what full regeneration would emit for that plan.
+ */
+export declare function generatePlanStatement(plan: PlanSpecJson): string;
 export declare function generateManifestSource(ir: ManifestIrDocument): string;

package/dist/types/declarations.d.ts

@@ -1,4 +1,4 @@
-import type { ActionSpecJson, CacheProfile, CapabilityLayerJson, CountedResourceJson, GrantJson, MigrationDeclJson, MigrationPinJson, MutationClass, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyLayerJson, ProductEntitlementJson, ProductSurfaceJson, ProductSurfaceTypeJson, ProductWorkflowJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, RouteDefinitionJson, RouteLayerJson } from "./ir-types.js";
+import type { ActionSpecJson, CacheProfile, CapabilityLayerJson, CountedResourceJson, CreditPolicyJson, GrantJson, MigrationDeclJson, MigrationPinJson, MutationClass, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyLayerJson, ProductEntitlementJson, ProductSurfaceJson, ProductSurfaceTypeJson, ProductWorkflowJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, RouteDefinitionJson, RouteLayerJson } from "./ir-types.js";
 import type { PriceSpec } from "./price.js";
 import { type KeyRef, type PlanCapabilityGrant } from "./refs.js";
 import type { MeterRef, RouteMeteringOptions } from "./route-metering.js";
@@ -71,6 +71,8 @@ export type PlanDeclarationOptions = {
     price?: PriceSpec;
     meters?: PlanMeterJson[];
     grants?: Array<GrantJson | PlanCapabilityGrant>;
+    /** Non-grant credit policies (rollover + auto-recharge). */
+    creditPolicy?: CreditPolicyJson;
     trialDays?: number;
     maxMonthlySpendCents?: number;
     minMonthlySpendCents?: number;

package/dist/types/ir-types.d.ts

@@ -22,9 +22,20 @@ export type PlanMeterJson = {
     [key: string]: unknown;
 };
 export type GrantJson = {
-    kind: "recurring" | "one_time" | "promotional" | "trial" | "rollover" | "top_up" | "auto_recharge";
+    kind: "credit" | "top_up";
     [key: string]: unknown;
 };
+/** Non-grant credit policies (rollover + auto-recharge) — mirrors the
+ *  platform creditPolicySchema. */
+export type CreditPolicyJson = {
+    rollover?: {
+        percent: number;
+    };
+    auto_recharge?: {
+        threshold_cents: number;
+        refill_cents: number;
+    };
+};
 export type PlanLimitWindowJson = {
     type: "named";
     name: "second" | "minute" | "hour" | "day" | "week" | "month";
@@ -57,6 +68,7 @@ export type PlanSpecJson = {
     max_monthly_spend_cents?: number;
     min_monthly_spend_cents?: number;
     grants?: GrantJson[];
+    creditPolicy?: CreditPolicyJson;
     capabilities?: string[];
     free?: boolean;
     limits?: PlanLimitJson[];

package/dist/types/product.d.ts

@@ -1,4 +1,4 @@
-import type { CacheProfile, ActionSpecJson, CapabilityLayerJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyLayerJson, ProductPoliciesJson, ProductCustomerContextJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, ProductSurfaceTypeJson, RouteLayerJson } from "./ir-types.js";
+import type { CacheProfile, ActionSpecJson, CapabilityLayerJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, CreditPolicyJson, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyLayerJson, ProductPoliciesJson, ProductCustomerContextJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, ProductSurfaceTypeJson, RouteLayerJson } from "./ir-types.js";
 import type { PriceSpec } from "./price.js";
 import { type ManifestResourceGraphSnapshot } from "./resource-graph.js";
 import { type BackendOptions } from "./backend.js";
@@ -36,7 +36,6 @@ export type ProductOptions = {
         customerAuth?: ProductCustomerContextJson["portal_auth"];
     };
     billing?: {
-        gracePeriodDays?: number;
         applyLimitUpgradesInstantly?: boolean;
     };
 };
@@ -81,9 +80,16 @@ export type FrontendPageOptions = {
     capability?: string | CapabilityRef;
     components?: FrontendComponentOptions[];
 };
+/**
+ * A plan-version reference: `"head"` (newest ACTIVE version) or a
+ * positive-integer string ("1", "2", ...). The template-literal type rejects
+ * obvious mistakes like date strings (`"2026-06-01"`) at compile time; the
+ * contracts `versionRefSchema` is the runtime source of truth.
+ */
+export type VersionRef = "head" | `${number}`;
 export type MigrationPlanRefOptions = {
     plan: string | PlanRef;
-    version?: string;
+    version?: VersionRef;
 };
 export type MigrationTargetRefOptions = {
     plan: string | PlanRef;
@@ -92,7 +98,7 @@ export type MigrationTargetRefOptions = {
 export type MigrationPinOptions = Omit<MigrationPinJson, "pinTo"> & {
     pinTo: {
         plan: string | PlanRef;
-        version: string;
+        version: VersionRef;
     };
 };
 export type MigrationOptions = Omit<MigrationDeclJson, "id" | "from" | "to" | "newCustomers" | "pins"> & {
@@ -143,6 +149,8 @@ export type PlanOptions = {
     meters?: PlanMeterJson[];
     /** Credit grants and/or capability enablements from `cap.enable()`. */
     grants?: Array<GrantJson | PlanCapabilityGrant>;
+    /** Non-grant credit policies (rollover + auto-recharge). */
+    creditPolicy?: CreditPolicyJson;
     trialDays?: number;
     maxMonthlySpendCents?: number;
     minMonthlySpendCents?: number;

package/dist/types/route-metering.d.ts

@@ -1,4 +1,4 @@
-import type { HttpMethod, MeterDefinitionJson, RouteDefinitionJson, RouteLayerJson } from "./ir-types.js";
+import type { MeterDefinitionJson, RouteDefinitionJson, RouteLayerJson } from "./ir-types.js";
 import { type KeyRef } from "./refs.js";
 export type MeterCost = {
     readonly kind: "meter_cost";
@@ -20,7 +20,7 @@ export type MeterRef = {
 };
 export type RouteMeteringOptions = {
     /**
-     * Dynamic meter keys the upstream may report with @farthershore/metering.
+     * Dynamic meter keys the upstream may report with @farthershore/backend.
      */
     reports?: string | MeterRef | Array<string | MeterRef>;
     /** Fixed gateway-known route costs. */
@@ -40,20 +40,13 @@ type RouteBindingOptions = RouteMeteringOptions & {
      *  zero-config). */
     backend?: KeyRef;
 };
-export type RouteMeteringDeps = {
+type RouteMeteringDeps = {
     normalizeMeterCost(cost: MeterCost): MeterCost;
     getMeterDefinition(key: string): MeterDefinitionJson | undefined;
 };
-export declare function parseRouteMatch(match: string): {
-    method: HttpMethod;
-    path: string;
-};
 export declare function makeMeterRef(key: string): MeterRef;
 export declare function normalizeMeterCost(cost: MeterCost, hasMeter: (meter: string) => boolean): MeterCost;
-export declare function normalizeMeterCosts(costs: RouteMeteringOptions["costs"], normalize: (cost: MeterCost) => MeterCost): MeterCost[];
-export declare function normalizeMeterRefs(refs: string | MeterRef | Array<string | MeterRef>): string[];
 export declare function buildRouteDefinition(match: string, options: RouteBindingOptions, deps: RouteMeteringDeps): RouteDefinitionJson;
-export declare function buildRouteMetering(options: RouteMeteringOptions, deps: RouteMeteringDeps): RouteDefinitionJson["metering"] | undefined;
 export declare function materializeRoute(route: RouteDefinitionJson, defaultMeterCosts: readonly MeterCost[]): RouteDefinitionJson;
 export declare function routeMeterDependencyKeys(route: RouteDefinitionJson): string[];
 export declare function assertRouteMeteringValid(files: RouteLayerJson[], meterDefinitions: Iterable<MeterDefinitionJson>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farthershore/product",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Farther Shore product-as-code SDK — declare your software product in TypeScript",
   "type": "module",
   "main": "./dist/index.js",