@farthershore/product 0.3.0 → 0.4.0

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

@@ -228,6 +228,48 @@ export type ProductCustomerContextJson = {
         strategy: CustomerPortalAuthStrategyJson;
     };
 };
+export type ProductSurfaceTypeJson = "frontend" | "api" | "docs" | "widget" | "dashboard" | "webhook" | "worker" | "agent";
+export type ProductSurfaceJson = {
+    key: string;
+    type: ProductSurfaceTypeJson;
+    display?: string;
+    description?: string;
+};
+export type ProductEntitlementJson = {
+    key: string;
+    description?: string;
+    capabilities?: string[];
+    featureGates?: Record<string, boolean>;
+    limits?: PlanLimitJson[];
+    meters?: string[];
+};
+export type ProductWorkflowKindJson = "async_job" | "agent_task" | "scheduled" | "lifecycle" | "background";
+export type ProductWorkflowTriggerJson = {
+    type: "manual";
+} | {
+    type: "schedule";
+    cron: string;
+} | {
+    type: "event";
+    event: string;
+} | {
+    type: "api";
+    path: string;
+} | {
+    type: "lifecycle";
+    event: string;
+};
+export type ProductWorkflowJson = {
+    key: string;
+    title?: string;
+    description?: string;
+    kind: ProductWorkflowKindJson;
+    trigger: ProductWorkflowTriggerJson;
+    capabilities?: string[];
+    meters?: string[];
+    estimates?: Record<string, number>;
+    metadata?: Record<string, unknown>;
+};
 export type ProductBlockJson = {
     name: string;
     displayName?: string;
@@ -257,6 +299,9 @@ export type ProductSpecJson = {
     resources?: CountedResourceJson[];
     policies?: ProductPoliciesJson;
     customer_context?: ProductCustomerContextJson;
+    surfaces?: ProductSurfaceJson[];
+    entitlements?: ProductEntitlementJson[];
+    workflows?: ProductWorkflowJson[];
     plans?: PlanSpecJson[];
     /** Legacy / advanced product blocks (usage, features, billing,
      *  webhooks, environments, add_ons, lifecycle, ephemeral, …) ride

package/dist/types/{business.d.ts → product.d.ts}

@@ -1,15 +1,15 @@
-import type { CacheProfile, ActionSpecJson, CapabilityFileJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, ManifestBuildResult, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyFileJson, ProductPoliciesJson, ProductCustomerContextJson, RoutesFileJson } from "./ir-types.js";
+import type { CacheProfile, ActionSpecJson, CapabilityFileJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, ManifestBuildResult, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyFileJson, ProductPoliciesJson, ProductCustomerContextJson, ProductWorkflowKindJson, ProductWorkflowTriggerJson, ProductSurfaceTypeJson, RoutesFileJson } from "./ir-types.js";
 import type { PriceSpec } from "./price.js";
 import { type ManifestResourceGraphSnapshot } from "./resource-graph.js";
-/** Brand symbol so the bin can recognize a Business across SDK copies
+/** Brand symbol so the bin can recognize a Product across SDK copies
  *  (the repo's pinned SDK vs whatever loaded the entry). */
-export declare const BUSINESS_BRAND: unique symbol;
-export type BusinessOptions = {
-    /** Upstream origin the gateway proxies to. */
-    baseUrl: string;
+export declare const PRODUCT_BRAND: unique symbol;
+export type ProductOptions = {
+    /** Business logic origin Farther Shore calls for customer-facing actions. */
+    origin: string;
     displayName?: string;
     description?: string;
-    sandboxBaseUrl?: string;
+    sandboxOrigin?: string;
     visibility?: "public" | "private";
     logoUrl?: string;
     primaryColor?: string;
@@ -27,7 +27,7 @@ export type BusinessOptions = {
     customerContext?: {
         identityRequirement?: ProductCustomerContextJson["identity_requirement"];
         contextTokens?: ProductCustomerContextJson["context_tokens"];
-        portalAuth?: ProductCustomerContextJson["portal_auth"];
+        customerAuth?: ProductCustomerContextJson["portal_auth"];
     };
     billing?: {
         gracePeriodDays?: number;
@@ -114,7 +114,7 @@ export type FeatureOptions = {
     description?: string;
     mutationClass?: MutationClass;
     cacheProfile?: CacheProfile;
-    /** Per-feature upstream origin override (default: product baseUrl). */
+    /** Per-feature upstream origin override (default: product origin). */
     upstreamOrigin?: string | null;
     policies?: Array<string | PolicyRef>;
     capabilities?: Array<string | CapabilityRef>;
@@ -171,6 +171,28 @@ export type PlanOptions = {
     /** Escape hatch: merged onto the emitted plan spec last (e.g. variants). */
     raw?: Record<string, unknown>;
 };
+export type SurfaceOptions = {
+    key?: string;
+    display?: string;
+    description?: string;
+};
+export type WorkflowOptions = {
+    title?: string;
+    description?: string;
+    kind?: ProductWorkflowKindJson;
+    trigger?: ProductWorkflowTriggerJson;
+    capabilities?: Array<string | CapabilityRef>;
+    meters?: Array<string | MeterRef>;
+    estimates?: Record<string, number>;
+    metadata?: Record<string, unknown>;
+};
+export type EntitlementOptions = {
+    description?: string;
+    capabilities?: Array<string | CapabilityRef>;
+    featureGates?: Record<string, boolean>;
+    limits?: PlanLimitJson[];
+    meters?: Array<string | MeterRef>;
+};
 export type MeterRef = {
     readonly kind: "meter";
     readonly key: string;
@@ -191,6 +213,18 @@ export type PlanRef = {
     readonly kind: "plan";
     readonly key: string;
 };
+export type SurfaceRef = {
+    readonly kind: "surface";
+    readonly key: string;
+};
+export type WorkflowRef = {
+    readonly kind: "workflow";
+    readonly key: string;
+};
+export type EntitlementRef = {
+    readonly kind: "entitlement";
+    readonly key: string;
+};
 export type ActionRef = {
     readonly kind: "action";
     readonly key: string;
@@ -221,9 +255,9 @@ export type PlanCapabilityGrant = {
  * A synchronous Product SDK module. Use this to split a product across files:
  * `product.use(configureMeters, configureRoutes, configurePlans)`.
  */
-export type ProductModule = (product: Business) => void;
-export declare class Business {
-    readonly [BUSINESS_BRAND] = true;
+export type ProductModule = (product: Product) => void;
+export declare class Product {
+    readonly [PRODUCT_BRAND] = true;
     readonly name: string;
     private readonly options;
     private readonly graph;
@@ -234,38 +268,44 @@ export declare class Business {
     readonly api: {
         route: (match: string, options: {
             feature: string | FeatureRef;
-        } & RouteOptions) => Business;
+        } & RouteOptions) => Product;
     };
     readonly frontend: {
-        nav: (items: FrontendNavItemOptions[]) => Business;
-        page: (path: string, options: FrontendPageOptions) => Business;
-        manifest: (manifest: FrontendManifestJson) => Business;
+        nav: (items: FrontendNavItemOptions[]) => Product;
+        page: (path: string, options: FrontendPageOptions) => Product;
+        manifest: (manifest: FrontendManifestJson) => Product;
     };
     readonly lifecycle: {
-        migration: (id: string, options: MigrationOptions) => Business;
-        migrations: (migrations: MigrationDeclJson[]) => Business;
+        migration: (id: string, options: MigrationOptions) => Product;
+        migrations: (migrations: MigrationDeclJson[]) => Product;
+    };
+    readonly offering: {
+        plan: (key: string, options: PlanOptions) => PlanRef;
     };
     /** Escape hatches — raw platform-schema JSON, validated at toIR(). */
     readonly raw: {
         /** Deep-merged onto the emitted product spec (usage, webhooks,
          *  environments, add_ons, lifecycle, billing overrides, …). */
-        productPatch: (patch: Record<string, unknown>) => Business;
-        plan: (spec: PlanSpecJson) => Business;
-        routesFile: (file: RoutesFileJson) => Business;
-        policyFile: (file: PolicyFileJson) => Business;
-        capabilityFile: (file: CapabilityFileJson) => Business;
-        frontend: (manifest: FrontendManifestJson) => Business;
+        productPatch: (patch: Record<string, unknown>) => Product;
+        plan: (spec: PlanSpecJson) => Product;
+        routesFile: (file: RoutesFileJson) => Product;
+        policyFile: (file: PolicyFileJson) => Product;
+        capabilityFile: (file: CapabilityFileJson) => Product;
+        frontend: (manifest: FrontendManifestJson) => Product;
     };
-    constructor(name: string, options: BusinessOptions);
+    constructor(name: string, options: ProductOptions);
     meter(key: string, options: MeterOptions): MeterRef;
     requests(options?: RequestMeterOptions): MeterRef;
-    defaultMeters(costs: MeterCost | MeterCost[]): Business;
+    defaultMeters(costs: MeterCost | MeterCost[]): Product;
     resource(name: string, options?: ResourceOptions): ResourceRef;
     capability(key: string, options?: CapabilityOptions): CapabilityRef;
     feature(key: string, options?: FeatureOptions): FeatureRef;
     policy(name: string, options: PolicyOptions): PolicyRef;
+    surface(type: ProductSurfaceTypeJson, options?: SurfaceOptions): SurfaceRef;
+    workflow(key: string, options?: WorkflowOptions): WorkflowRef;
+    entitlement(key: string, options?: EntitlementOptions): EntitlementRef;
     plan(key: string, options: PlanOptions): PlanRef;
-    use(...modules: ProductModule[]): Business;
+    use(...modules: ProductModule[]): Product;
     /** Inspect the SDK-local declaration graph used to emit the Manifest IR. */
     resourceGraph(): ManifestResourceGraphSnapshot;
     /** Assemble + validate the Manifest IR. Throws ManifestValidationError
@@ -277,6 +317,8 @@ export declare class Business {
     private buildRoute;
     private makeMeterRef;
     private buildRouteMetering;
+    private materializeFeatureFiles;
+    private materializeRoute;
     private normalizeMeterCost;
     private normalizeMeterCosts;
     private normalizeMeterRefs;
@@ -293,6 +335,8 @@ export declare class Business {
     private syncFrontendGraphNode;
     private capabilityDependsOn;
     private policyDependsOn;
+    private entitlementDependsOn;
+    private workflowDependsOn;
     private featureDependsOn;
     private routeMeterDependencyKeys;
     private assertRouteMeteringValid;
@@ -303,5 +347,5 @@ export declare class Business {
     private dependenciesFor;
     private existingDependenciesFor;
 }
-export declare function isBusiness(value: unknown): value is Business;
-export declare function business(name: string, options: BusinessOptions, configure?: ProductModule): Business;
+export declare function isProduct(value: unknown): value is Product;
+export declare function product(name: string, options: ProductOptions, configure?: ProductModule): Product;

package/dist/types/resource-graph.d.ts

@@ -1,4 +1,4 @@
-export type ManifestResourceKind = "product" | "meter" | "counted_resource" | "capability" | "policy" | "feature" | "action" | "plan" | "frontend" | "lifecycle_migration";
+export type ManifestResourceKind = "product" | "meter" | "counted_resource" | "capability" | "surface" | "entitlement" | "workflow" | "policy" | "feature" | "action" | "plan" | "frontend" | "lifecycle_migration";
 export type ManifestResourceUrn = `urn:farthershore:product:${ManifestResourceKind}:${string}`;
 export type ManifestResourceRef = {
     readonly kind: ManifestResourceKind;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@farthershore/product",
-  "version": "0.3.0",
-  "description": "Farther Shore product-as-code SDK — declare your business in TypeScript",
+  "version": "0.4.0",
+  "description": "Farther Shore product-as-code SDK — declare your software product in TypeScript",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
@@ -31,9 +31,9 @@
   "keywords": [
     "farthershore",
     "product-as-code",
-    "api",
+    "software-product",
     "billing",
-    "api-monetization"
+    "monetization"
   ],
   "author": "Farther Shore",
   "license": "MIT",