@farthershore/product 0.0.0

package/dist/types/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/types/business.d.ts

@@ -0,0 +1,244 @@
+import type { CacheProfile, ActionSpecJson, CapabilityFileJson, FrontendComponentId, FrontendGateMode, FrontendManifestJson, GrantJson, ManifestBuildResult, MeterDefinitionJson, MigrationDeclJson, MigrationPinJson, MutationClass, CountedResourceJson, PlanLimitJson, PlanMeterJson, PlanSpecJson, PolicyFileJson, RoutesFileJson } from "./ir-types.js";
+import type { PriceSpec } from "./price.js";
+/** Brand symbol so the bin can recognize a Business 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;
+    displayName?: string;
+    description?: string;
+    sandboxBaseUrl?: string;
+    visibility?: "public" | "private";
+    logoUrl?: string;
+    primaryColor?: string;
+    envBranchPrefix?: string | null;
+    /** API-key header the gateway reads (default x-api-key). */
+    authHeader?: string;
+    upstreamAuth?: {
+        type: "none" | "static_bearer";
+        token?: string;
+    };
+    billOn4xx?: boolean;
+    billing?: {
+        gracePeriodDays?: number;
+        applyLimitUpgradesInstantly?: boolean;
+    };
+};
+export type MeterOptions = Omit<MeterDefinitionJson, "key">;
+export type CapabilityOptions = {
+    title?: string;
+    description?: string;
+    mutationClass?: MutationClass;
+    includesFeatures?: Array<string | FeatureRef>;
+    includesPolicies?: Array<string | PolicyRef>;
+    includesCapabilities?: Array<string | CapabilityRef>;
+};
+export type RouteOptions = {
+    /** Meter keys this route increments. Omitted = all product meters. */
+    meters?: Array<string | MeterRef>;
+    unmetered?: boolean;
+    action?: string | ActionRef;
+};
+export type ActionOptions = Omit<ActionSpecJson, "id">;
+export type FrontendNavItemOptions = {
+    label: string;
+    path: string;
+    capability?: string | CapabilityRef;
+};
+export type FrontendComponentOptions = {
+    component: FrontendComponentId;
+    props?: Record<string, unknown>;
+    capability?: string | CapabilityRef;
+    gateMode?: FrontendGateMode;
+};
+export type FrontendPageOptions = {
+    title: string;
+    requiresAuth: boolean;
+    capability?: string | CapabilityRef;
+    components?: FrontendComponentOptions[];
+};
+export type MigrationPlanRefOptions = {
+    plan: string | PlanRef;
+    version?: string;
+};
+export type MigrationTargetRefOptions = {
+    plan: string | PlanRef;
+    version?: "head";
+};
+export type MigrationPinOptions = Omit<MigrationPinJson, "pinTo"> & {
+    pinTo: {
+        plan: string | PlanRef;
+        version: string;
+    };
+};
+export type MigrationOptions = Omit<MigrationDeclJson, "id" | "from" | "to" | "newCustomers" | "pins"> & {
+    from: MigrationPlanRefOptions;
+    to: MigrationTargetRefOptions;
+    newCustomers?: "immediate";
+    pins?: MigrationPinOptions[];
+};
+export type ResourceOptions = Omit<CountedResourceJson, "name">;
+export type FeatureOptions = {
+    description?: string;
+    mutationClass?: MutationClass;
+    cacheProfile?: CacheProfile;
+    /** Per-feature upstream origin override (default: product baseUrl). */
+    upstreamOrigin?: string | null;
+    policies?: Array<string | PolicyRef>;
+    capabilities?: Array<string | CapabilityRef>;
+    /** Plans that grant this feature directly. */
+    plans?: Array<string | PlanRef>;
+    rolloutKey?: string;
+    requiredFlags?: string[];
+    actions?: Array<{
+        id: string;
+    } & ActionOptions>;
+    /** Routes, e.g. `{ match: "POST /v1/jobs", meters: ["requests"] }`. */
+    routes?: Array<{
+        match: string;
+    } & RouteOptions>;
+};
+export type PolicyOptions = {
+    type: string;
+    config: Record<string, unknown>;
+    description?: string;
+    mutationClass?: MutationClass;
+    cacheProfile?: CacheProfile;
+    compatibleWith?: {
+        routeTypes?: string[];
+        meters?: Array<string | MeterRef>;
+        authModes?: string[];
+    };
+};
+export type PlanOptions = {
+    name: string;
+    description?: string;
+    details?: string[];
+    /** From fs.price.monthly/yearly/free. Omit for a 0-fee plan. */
+    price?: PriceSpec;
+    /** Per-dimension metered pricing (platform 5-knob meters[] shape). */
+    meters?: PlanMeterJson[];
+    /** Credit grants and/or capability enablements from `cap.enable()`. */
+    grants?: Array<GrantJson | PlanCapabilityGrant>;
+    trialDays?: number;
+    maxMonthlySpendCents?: number;
+    minMonthlySpendCents?: number;
+    limits?: PlanLimitJson[];
+    featureGates?: Record<string, boolean>;
+    capabilityLimits?: Record<string, number | boolean>;
+    /** Capability keys granted without per-capability limits. */
+    capabilities?: Array<string | CapabilityRef>;
+    overageBehavior?: "block" | "allow_and_bill";
+    selfServeEnabled?: boolean;
+    legacy?: boolean;
+    archive?: {
+        at?: string;
+        transitionTo?: string;
+        strategy?: "auto" | "explicit" | "block";
+    };
+    /** Escape hatch: merged onto the emitted plan spec last (e.g. variants). */
+    raw?: Record<string, unknown>;
+};
+export type MeterRef = {
+    readonly kind: "meter";
+    readonly key: string;
+};
+export type ResourceRef = {
+    readonly kind: "resource";
+    readonly key: string;
+};
+export type PolicyRef = {
+    readonly kind: "policy";
+    readonly key: string;
+};
+export type PlanRef = {
+    readonly kind: "plan";
+    readonly key: string;
+};
+export type ActionRef = {
+    readonly kind: "action";
+    readonly key: string;
+};
+export type FeatureRef = {
+    readonly kind: "feature";
+    readonly key: string;
+    /** Declare an action co-located with this feature. */
+    action(id: string, options: ActionOptions): ActionRef;
+    /** Append a route to this feature: `feature.route("POST /v1/x", {...})`. */
+    route(match: string, options?: RouteOptions): FeatureRef;
+};
+export type CapabilityRef = {
+    readonly kind: "capability";
+    readonly key: string;
+    /** Grant this capability on a plan, optionally with numeric/boolean
+     *  capability limits: `cap.enable({ limits: { cron_jobs: 10 } })`. */
+    enable(options?: {
+        limits?: Record<string, number | boolean>;
+    }): PlanCapabilityGrant;
+};
+export type PlanCapabilityGrant = {
+    readonly kind: "capability_grant";
+    readonly capability: string;
+    readonly limits?: Record<string, number | boolean>;
+};
+export declare class Business {
+    readonly [BUSINESS_BRAND] = true;
+    readonly name: string;
+    private readonly options;
+    private readonly meters;
+    private readonly resources;
+    private readonly plans;
+    private readonly features;
+    private readonly policies;
+    private readonly capabilities;
+    private migrations;
+    private frontendManifest?;
+    private productPatch;
+    /** Sugar for binding API routes to features. */
+    readonly api: {
+        route: (match: string, options: {
+            feature: string | FeatureRef;
+        } & RouteOptions) => Business;
+    };
+    readonly frontend: {
+        nav: (items: FrontendNavItemOptions[]) => Business;
+        page: (path: string, options: FrontendPageOptions) => Business;
+        manifest: (manifest: FrontendManifestJson) => Business;
+    };
+    readonly lifecycle: {
+        migration: (id: string, options: MigrationOptions) => Business;
+        migrations: (migrations: MigrationDeclJson[]) => Business;
+    };
+    /** 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;
+    };
+    constructor(name: string, options: BusinessOptions);
+    meter(key: string, options: MeterOptions): MeterRef;
+    resource(name: string, options?: ResourceOptions): ResourceRef;
+    capability(key: string, options?: CapabilityOptions): CapabilityRef;
+    feature(key: string, options?: FeatureOptions): FeatureRef;
+    policy(name: string, options: PolicyOptions): PolicyRef;
+    plan(key: string, options: PlanOptions): PlanRef;
+    /** Assemble + validate the Manifest IR. Throws ManifestValidationError
+     *  with structured issues when the declared state is invalid. */
+    toIR(): ManifestBuildResult;
+    private buildProductSpec;
+    private buildRoute;
+    private ensureFrontendManifest;
+    private normalizeMigrationPlanRef;
+    private normalizeMigrationTargetRef;
+    private assertUniqueMigrationId;
+    private assertUniqueMigrationIds;
+    private assertNewKey;
+}
+export declare function isBusiness(value: unknown): value is Business;
+export declare function business(name: string, options: BusinessOptions): Business;

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

@@ -0,0 +1,2 @@
+import type { ManifestIrDocument } from "../ir-types.js";
+export declare function generateManifestSource(ir: ManifestIrDocument): string;

package/dist/types/errors.d.ts

@@ -0,0 +1,19 @@
+/** One validation problem, in the platform's diagnostic envelope shape. */
+export type ManifestIssue = {
+    code: string;
+    path: string;
+    message: string;
+};
+/**
+ * Thrown by `business.toIR()` (and the manifest-build bin) when the
+ * assembled manifest fails schema validation. Plain-data `issues` so the
+ * error survives serialization across the runner callback boundary.
+ */
+export declare class ManifestValidationError extends Error {
+    readonly issues: ManifestIssue[];
+    constructor(issues: ManifestIssue[]);
+}
+/** Thrown on builder misuse (duplicate keys, unknown refs) at call time. */
+export declare class ManifestBuilderError extends Error {
+    constructor(message: string);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,21 @@
+import { business } from "./business.js";
+export declare const product: typeof business;
+export declare const fs: {
+    business: typeof business;
+    product: typeof business;
+    price: {
+        monthly(dollars: number): import("./price.js").PriceSpec;
+        yearly(dollars: number): import("./price.js").PriceSpec;
+        free(): import("./price.js").PriceSpec;
+    };
+};
+export { business, Business, isBusiness, BUSINESS_BRAND } from "./business.js";
+export { price } from "./price.js";
+export { validateManifestIr, hashIr, canonicalIrJson } from "./validate.js";
+export { ManifestValidationError, ManifestBuilderError } from "./errors.js";
+export { SDK_VERSION } from "./version.js";
+export type { BusinessOptions, MeterOptions, CapabilityOptions, FrontendNavItemOptions, FrontendPageOptions, FrontendComponentOptions, FeatureOptions, RouteOptions, PolicyOptions, PlanOptions, MeterRef, PolicyRef, PlanRef, FeatureRef, CapabilityRef, PlanCapabilityGrant, } from "./business.js";
+export type { PriceSpec } from "./price.js";
+export type { ManifestIssue } from "./errors.js";
+export type { ValidationResult } from "./validate.js";
+export type { ManifestIrDocument, ManifestBuildResult, ProductSpecJson, PlanSpecJson, RoutesFileJson, PolicyFileJson, CapabilityFileJson, FrontendManifestJson, FrontendNavItemJson, FrontendPageJson, FrontendComponentJson, FrontendComponentId, FrontendGateMode, MeterDefinitionJson, PlanMeterJson, PlanLimitJson, GrantJson, HttpMethod, MutationClass, CacheProfile, } from "./ir-types.js";

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

@@ -0,0 +1,250 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "*";
+export type MutationClass = "runtime" | "contractual";
+export type CacheProfile = "long" | "short" | "blocking";
+export type MeterDefinitionJson = {
+    key: string;
+    display: string;
+    unit?: string;
+    enforcementType?: "exact_pre_request" | "estimated_then_settled" | "postpaid" | "strict_concurrency";
+    aggregation?: "SUM" | "COUNT" | "MAX" | "UNIQUE_COUNT" | "LATEST";
+    window?: "minute" | "hour" | "day" | "month" | "billing_period";
+    valueProperty?: string;
+    uniqueProperty?: string;
+    groupBy?: string[];
+    eventCode?: string;
+};
+/** Per-plan meter pricing (the 5-knob `meters[]` entry). Field set follows
+ *  the platform schema; extra fields pass through to validation. */
+export type PlanMeterJson = {
+    dimension: string;
+    [key: string]: unknown;
+};
+export type GrantJson = {
+    kind: "recurring" | "one_time" | "promotional" | "trial" | "rollover" | "top_up" | "auto_recharge";
+    [key: string]: unknown;
+};
+export type PlanLimitWindowJson = {
+    type: "named";
+    name: "second" | "minute" | "hour" | "day" | "week" | "month";
+} | {
+    type: "custom";
+    seconds: number;
+    label?: string;
+};
+export type PlanLimitJson = {
+    dimension: string;
+    window: PlanLimitWindowJson;
+    capacity: number;
+    enforcement?: "enforce" | "track";
+    reset_trigger?: "billing_period" | "subscription_start";
+};
+export type PlanArchiveJson = {
+    at?: string;
+    transitionTo?: string;
+    strategy?: "auto" | "explicit" | "block";
+};
+export type PlanSpecJson = {
+    key: string;
+    name: string;
+    description?: string;
+    details?: string[];
+    meters?: PlanMeterJson[];
+    recurring_fee_cents?: number;
+    billing_interval?: "month" | "year";
+    trial_days?: number;
+    max_monthly_spend_cents?: number;
+    min_monthly_spend_cents?: number;
+    grants?: GrantJson[];
+    free?: boolean;
+    limits?: PlanLimitJson[];
+    featureGates?: Record<string, boolean>;
+    capability_limits?: Record<string, number | boolean>;
+    overageBehavior?: "block" | "allow_and_bill";
+    selfServeEnabled?: boolean;
+    legacy?: boolean;
+    archive?: PlanArchiveJson;
+    /** Escape hatch: A/B variants and future fields ride through here. */
+    [key: string]: unknown;
+};
+export type RouteDefinitionJson = {
+    match: {
+        method?: HttpMethod;
+        path: string;
+    };
+    meters?: string[] | null;
+    unmetered?: boolean;
+    action?: string;
+};
+export type ActionSpecJson = {
+    id: string;
+    title?: string;
+    kind: "query" | "mutation";
+    actorType?: string;
+    subject?: {
+        type: string;
+        from: "header" | "path_param";
+        name: string;
+    };
+    inputSchemaRef?: string;
+    audit?: "none" | "metadata" | "full";
+    resource?: {
+        resource: string;
+        effect: "create" | "delete";
+    };
+};
+export type RoutesFileJson = {
+    feature: string;
+    description?: string;
+    mutation_class?: MutationClass;
+    cacheProfile?: CacheProfile;
+    routes: RouteDefinitionJson[];
+    upstream?: {
+        override_origin: string | null;
+    };
+    policies?: string[];
+    runtime?: {
+        rollout_key?: string;
+        required_flags?: string[];
+    };
+    capabilities?: string[];
+    plans?: string[];
+    actions?: ActionSpecJson[];
+};
+export type PolicyFileJson = {
+    name: string;
+    description?: string;
+    type: string;
+    config: Record<string, unknown>;
+    compatible_with?: {
+        route_types?: string[];
+        meters?: string[];
+        auth_modes?: string[];
+    };
+    mutation_class?: MutationClass;
+    cacheProfile?: CacheProfile;
+};
+export type CapabilityFileJson = {
+    capability: string;
+    description?: string;
+    mutation_class?: MutationClass;
+    includes_features?: string[];
+    includes_policies?: string[];
+    includes_capabilities?: string[];
+};
+export type FrontendComponentId = "plans_table" | "usage_card" | "api_keys_panel" | "billing_summary" | "credit_balance" | "feature_panel" | "product_docs" | "audit_log" | "team_panel" | "markdown";
+export type FrontendGateMode = "hide" | "disable" | "upsell";
+export type FrontendNavItemJson = {
+    label: string;
+    path: string;
+    capability?: string;
+};
+export type FrontendComponentJson = {
+    component: FrontendComponentId;
+    props?: Record<string, unknown>;
+    capability?: string;
+    gateMode?: FrontendGateMode;
+};
+export type FrontendPageJson = {
+    path: string;
+    title: string;
+    requiresAuth: boolean;
+    capability?: string;
+    components?: FrontendComponentJson[];
+};
+export type FrontendManifestJson = {
+    version: 1;
+    nav?: FrontendNavItemJson[];
+    pages?: FrontendPageJson[];
+};
+export type MigrationEffectiveJson = "grandfather" | "next_renewal" | "by_date" | "immediate" | "opt_in";
+export type MigrationProrationJson = "none" | "prorate" | "credit";
+export type MigrationPlanVersionRefJson = {
+    plan: string;
+    version?: string;
+};
+export type MigrationTargetRefJson = {
+    plan: string;
+    version: "head";
+};
+export type MigrationExistingCustomersJson = {
+    effective: MigrationEffectiveJson;
+    date?: string;
+    proration?: MigrationProrationJson;
+};
+export type MigrationPinJson = {
+    subscriber: string;
+    pinTo: {
+        plan: string;
+        version: string;
+    };
+    until?: string;
+    notes?: string;
+};
+export type MigrationDeclJson = {
+    id: string;
+    from: MigrationPlanVersionRefJson;
+    to: MigrationTargetRefJson;
+    newCustomers: "immediate";
+    existingCustomers: MigrationExistingCustomersJson;
+    pins?: MigrationPinJson[];
+};
+export type CountedResourceScopeJson = "subscription" | "subject";
+export type CountedResourceCountSourceJson = "reported" | "action_inferred";
+export type CountedResourceJson = {
+    name: string;
+    display?: string;
+    scope?: CountedResourceScopeJson;
+    subjectType?: string;
+    countSource?: CountedResourceCountSourceJson;
+};
+export type ProductBlockJson = {
+    name: string;
+    displayName?: string;
+    description?: string;
+    baseUrl: string;
+    sandboxBaseUrl?: string;
+    visibility?: "public" | "private";
+    logoUrl?: string;
+    primaryColor?: string;
+    envBranchPrefix?: string | null;
+};
+export type ProductSpecJson = {
+    product: ProductBlockJson;
+    gateway?: {
+        authHeader?: string;
+        upstreamAuth?: {
+            type: "none" | "static_bearer";
+            token?: string;
+        };
+    };
+    metering?: {
+        meters?: MeterDefinitionJson[];
+        billOn4xx?: boolean;
+    };
+    frontend?: FrontendManifestJson;
+    migrations?: MigrationDeclJson[];
+    resources?: CountedResourceJson[];
+    plans?: PlanSpecJson[];
+    /** Legacy / advanced product blocks (usage, features, billing,
+     *  webhooks, environments, add_ons, lifecycle, ephemeral, …) ride
+     *  through untyped; the platform schema validates them. */
+    [key: string]: unknown;
+};
+export type ManifestIrDocument = {
+    irVersion: 1;
+    sdkVersion: string;
+    product: ProductSpecJson;
+    routes: RoutesFileJson[];
+    policies: PolicyFileJson[];
+    capabilities: CapabilityFileJson[];
+    runtime: {
+        rollout: null;
+        flags: null;
+        migrations: null;
+    };
+};
+/** `toIR()` result: the validated envelope plus its canonical hash. */
+export type ManifestBuildResult = {
+    ir: ManifestIrDocument;
+    irHash: string;
+};

package/dist/types/price.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Price sugar — maps onto the plan's 5-knob billing fields.
+ *
+ *   fs.price.monthly(29)   → { recurring_fee_cents: 2900, billing_interval: "month" }
+ *   fs.price.yearly(290)   → { recurring_fee_cents: 29000, billing_interval: "year" }
+ *   fs.price.free()        → { recurring_fee_cents: 0, free: true }
+ */
+export type PriceSpec = {
+    recurring_fee_cents: number;
+    billing_interval: "month" | "year";
+    free: boolean;
+};
+export declare const price: {
+    monthly(dollars: number): PriceSpec;
+    yearly(dollars: number): PriceSpec;
+    free(): PriceSpec;
+};

package/dist/types/validate.d.ts

@@ -0,0 +1,22 @@
+import type { ManifestIssue } from "./errors.js";
+import type { ManifestIrDocument } from "./ir-types.js";
+export type ValidationResult = {
+    ok: true;
+    ir: ManifestIrDocument;
+    irHash: string;
+} | {
+    ok: false;
+    issues: ManifestIssue[];
+};
+/**
+ * Validate a candidate envelope against the platform schemas. On success
+ * the returned `ir` is the JSON-normalized ORIGINAL candidate — NOT the
+ * zod-parsed value. The platform treats the product spec as a raw document
+ * (the YAML path never zod-transformed it before storing/compiling, and
+ * the compiler reads some fields — e.g. `plan.capabilities` — off the raw
+ * spec via casts that a default-stripping parse would erase). Validation
+ * proves the document is acceptable; the bytes stay the author's.
+ */
+export declare function validateManifestIr(candidate: unknown): ValidationResult;
+export declare function hashIr(ir: unknown): string;
+export declare function canonicalIrJson(ir: unknown): string;

package/dist/types/version.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION: string;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@farthershore/product",
+  "version": "0.0.0",
+  "description": "Farther Shore product-as-code SDK — declare your business in TypeScript",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "farthershore-manifest-build": "dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./codegen": {
+      "types": "./dist/types/codegen/index.d.ts",
+      "import": "./dist/codegen.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "farthershore",
+    "product-as-code",
+    "api",
+    "billing",
+    "api-monetization"
+  ],
+  "author": "Farther Shore",
+  "license": "MIT",
+  "dependencies": {
+    "tsx": "^4.20.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "esbuild": "^0.25.0",
+    "eslint": "^10.3.0",
+    "eslint-plugin-sonarjs": "^4.0.3",
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.59.0",
+    "vitest": "^4.1.6",
+    "@farthershore/contracts": "0.61.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit && node scripts/build.mjs",
+    "pack:check": "node scripts/check-pack.mjs",
+    "test": "vitest run",
+    "lint": "prettier --check \"src/**/*.ts\" && eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "tsc --noEmit"
+  }
+}