owostack 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { CheckResult, PlanFeatureEntry, ResetInterval, CreditSystemDefinition, AddEntityResult, RemoveEntityResult, ListEntitiesResult, MeteredFeatureConfig, TrackResult, CatalogEntry, SyncPayload, Currency, CreditPackDefinition, PlanInterval, PlanDefinition, OwostackConfig, BillingUsageParams, BillingUsageResult, InvoiceParams, InvoiceResult, InvoicesParams, InvoicesResult, PayInvoiceParams, PayInvoiceResult, WalletResult, WalletSetupResult, WalletRemoveResult, SyncResult, AttachParams, AttachResult, CheckParams, TrackParams, AddonParams, AddonResult, CustomerParams, CustomerResult, AddEntityParams, RemoveEntityParams, ListEntitiesParams, PlansParams, PlansResult, PublicPlan } from '@owostack/types';
-export { AddEntityParams, AddEntityResult, AddonParams, AddonResult, AttachParams, AttachResult, BillingFeatureUsage, BillingUsageParams, BillingUsageResult, BooleanFeatureConfig, CardInfo, CatalogEntry, CheckCode, CheckParams, CheckResult, CustomerData, CustomerParams, CustomerResult, Invoice, InvoiceLineItem, InvoiceParams, InvoiceResult, InvoicesParams, InvoicesResult, ListEntitiesParams, ListEntitiesResult, MeteredFeatureConfig, OverageDetails, OwostackConfig, PayInvoiceParams, PayInvoiceResult, PaymentMethodInfo, PlanCredits, PlanDefinition, PlanFeatureEntry, PlansParams, PlansResult, PublicPlan, PublicPlanFeature, RemoveEntityParams, RemoveEntityResult, ResponseDetails, SyncChanges, SyncPayload, SyncResult, TrackCode, TrackParams, TrackResult, WalletRemoveResult, WalletResult, WalletSetupResult } from '@owostack/types';
+import { CheckResult, PlanFeatureEntry, ResetInterval, CreditSystemDefinition, AddEntityResult, RemoveEntityResult, ListEntitiesResult, MeteredFeatureConfig, TrackResult, PricingTier, CatalogEntry, SyncPayload, Currency, CreditPackDefinition, PlanInterval, PlanDefinition, OwostackConfig, BillingUsageParams, BillingUsageResult, InvoiceParams, InvoiceResult, InvoicesParams, InvoicesResult, PayInvoiceParams, PayInvoiceResult, WalletResult, WalletSetupResult, WalletRemoveResult, SyncResult, AttachParams, AttachResult, CheckParams, TrackParams, AddonParams, AddonResult, CustomerParams, CustomerResult, AddEntityParams, RemoveEntityParams, ListEntitiesParams, PlansParams, PlansResult, PublicPlan } from '@owostack/types';
+export { AddEntityParams, AddEntityResult, AddonParams, AddonResult, AttachParams, AttachResult, BillingFeatureUsage, BillingTierBreakdown, BillingUsageParams, BillingUsageResult, BooleanFeatureConfig, CardInfo, CatalogEntry, CheckCode, CheckParams, CheckResult, CurrentPricingTier, CustomerData, CustomerParams, CustomerResult, Invoice, InvoiceLineItem, InvoiceParams, InvoiceResult, InvoicesParams, InvoicesResult, ListEntitiesParams, ListEntitiesResult, MeteredFeatureConfig, OverageDetails, OwostackConfig, PayInvoiceParams, PayInvoiceResult, PaymentMethodInfo, PlanCredits, PlanDefinition, PlanFeatureEntry, PlansParams, PlansResult, PricingDetails, PricingTier, PublicPlan, PublicPlanFeature, RatingModel, RemoveEntityParams, RemoveEntityResult, ResponseDetails, SyncChanges, SyncPayload, SyncResult, TrackCode, TrackParams, TrackResult, WalletRemoveResult, WalletResult, WalletSetupResult } from '@owostack/types';
 
 /**
  * BooleanHandle — returned by boolean().
@@ -37,6 +37,15 @@ interface MeteredHandle {
     limit(value: number, config?: Omit<MeteredFeatureConfig, "limit">): PlanFeatureEntry;
     included(value: number, config?: Omit<MeteredFeatureConfig, "limit">): PlanFeatureEntry;
     unlimited(config?: Omit<MeteredFeatureConfig, "limit">): PlanFeatureEntry;
+    perUnit(unitPrice: number, config?: {
+        reset?: ResetInterval;
+    }): PlanFeatureEntry;
+    graduated(tiers: PricingTier[], config?: {
+        reset?: ResetInterval;
+    }): PlanFeatureEntry;
+    volume(tiers: PricingTier[], config?: {
+        reset?: ResetInterval;
+    }): PlanFeatureEntry;
     config(opts: MeteredFeatureConfig): PlanFeatureEntry;
     (creditCost: number): {
         feature: string;

package/dist/index.js

@@ -45,6 +45,74 @@ var BooleanHandle = class {
     };
   }
 };
+function validateUnitPrice(unitPrice, methodName) {
+  if (!Number.isFinite(unitPrice) || unitPrice < 0) {
+    throw new Error(`${methodName}() requires a non-negative unit price.`);
+  }
+}
+function validatePricingTiers(tiers, methodName) {
+  if (!Array.isArray(tiers) || tiers.length === 0) {
+    throw new Error(`${methodName}() requires at least one pricing tier.`);
+  }
+  let previousUpTo = 0;
+  for (let index = 0; index < tiers.length; index += 1) {
+    const tier = tiers[index];
+    const hasUnitPrice = tier.unitPrice !== void 0;
+    const hasFlatFee = tier.flatFee !== void 0;
+    if (!hasUnitPrice && !hasFlatFee) {
+      throw new Error(
+        `${methodName}() tier ${index + 1} must define unitPrice, flatFee, or both.`
+      );
+    }
+    if (hasUnitPrice && (!Number.isFinite(tier.unitPrice) || tier.unitPrice < 0)) {
+      throw new Error(
+        `${methodName}() tier ${index + 1} must have a non-negative unitPrice.`
+      );
+    }
+    if (tier.flatFee !== void 0 && (!Number.isFinite(tier.flatFee) || tier.flatFee < 0)) {
+      throw new Error(
+        `${methodName}() tier ${index + 1} must have a non-negative flatFee.`
+      );
+    }
+    if (tier.upTo === null) {
+      if (index !== tiers.length - 1) {
+        throw new Error(
+          `${methodName}() only allows the last tier to use upTo: null.`
+        );
+      }
+      continue;
+    }
+    if (!Number.isFinite(tier.upTo) || tier.upTo <= previousUpTo) {
+      throw new Error(
+        `${methodName}() tiers must be in ascending order by upTo.`
+      );
+    }
+    previousUpTo = tier.upTo;
+  }
+}
+function validateMeteredFeaturePricing(config, featureSlug) {
+  if (!config) return;
+  if (config.pricePerUnit !== void 0) {
+    validateUnitPrice(config.pricePerUnit, `${featureSlug} pricePerUnit`);
+  }
+  const ratingModel = config.ratingModel || "package";
+  if (ratingModel === "graduated" || ratingModel === "volume") {
+    validatePricingTiers(config.tiers || [], ratingModel);
+  } else if (config.tiers && config.tiers.length > 0) {
+    throw new Error(
+      `Feature '${featureSlug}' cannot define tiers with ratingModel "package".`
+    );
+  }
+  if (config.usageModel === "usage_based" && ratingModel === "package" && config.pricePerUnit === void 0) {
+    throw new Error(
+      `Feature '${featureSlug}' must define pricePerUnit for usage-based package pricing.`
+    );
+  }
+}
+function normalizeUsageBasedOverage(usageModel, overage) {
+  if (usageModel === "usage_based") return "charge";
+  return overage;
+}
 function metered(slug, opts) {
   const callable = (creditCost) => ({ feature: slug, creditCost });
   const handleProps = {
@@ -92,6 +160,61 @@ function metered(slug, opts) {
         config: { limit: null, reset: "monthly", overage: "block", ...config }
       };
     },
+    perUnit(unitPrice, config) {
+      validateUnitPrice(unitPrice, "perUnit");
+      return {
+        _type: "plan_feature",
+        slug,
+        featureType: "metered",
+        name: opts?.name,
+        enabled: true,
+        config: {
+          limit: null,
+          reset: config?.reset || "monthly",
+          usageModel: "usage_based",
+          ratingModel: "package",
+          pricePerUnit: unitPrice,
+          billingUnits: 1,
+          overage: "charge"
+        }
+      };
+    },
+    graduated(tiers, config) {
+      validatePricingTiers(tiers, "graduated");
+      return {
+        _type: "plan_feature",
+        slug,
+        featureType: "metered",
+        name: opts?.name,
+        enabled: true,
+        config: {
+          limit: null,
+          reset: config?.reset || "monthly",
+          usageModel: "usage_based",
+          ratingModel: "graduated",
+          tiers: tiers.map((tier) => ({ ...tier })),
+          overage: "charge"
+        }
+      };
+    },
+    volume(tiers, config) {
+      validatePricingTiers(tiers, "volume");
+      return {
+        _type: "plan_feature",
+        slug,
+        featureType: "metered",
+        name: opts?.name,
+        enabled: true,
+        config: {
+          limit: null,
+          reset: config?.reset || "monthly",
+          usageModel: "usage_based",
+          ratingModel: "volume",
+          tiers: tiers.map((tier) => ({ ...tier })),
+          overage: "charge"
+        }
+      };
+    },
     config(configOpts) {
       const isEnabled = configOpts.enabled !== false;
       return {
@@ -321,29 +444,48 @@ function buildSyncPayload(catalog, defaultProvider) {
     metadata: p.metadata ?? void 0,
     autoEnable: p.autoEnable ?? void 0,
     isAddon: p.isAddon ?? void 0,
-    features: p.features.map((f) => ({
-      slug: f.slug,
-      enabled: f.enabled,
-      // Boolean features have no limit concept (null), metered features use limit from config
-      limit: f.featureType === "boolean" ? null : f.config?.limit ?? null,
-      // Boolean features have no reset interval
-      ...f.featureType !== "boolean" && {
-        reset: f.config?.reset || "monthly"
-      },
-      ...f.config?.overage && { overage: f.config.overage },
-      ...f.config?.overagePrice !== void 0 && {
-        overagePrice: f.config.overagePrice
-      },
-      ...f.config?.maxOverageUnits !== void 0 && {
-        maxOverageUnits: f.config.maxOverageUnits
-      },
-      ...f.config?.billingUnits !== void 0 && {
-        billingUnits: f.config.billingUnits
-      },
-      ...f.config?.creditCost !== void 0 && {
-        creditCost: f.config.creditCost
+    features: p.features.map((f) => {
+      if (f.featureType !== "boolean") {
+        validateMeteredFeaturePricing(f.config, f.slug);
       }
-    }))
+      return {
+        slug: f.slug,
+        enabled: f.enabled,
+        // Boolean features have no limit concept (null), metered features use limit from config
+        limit: f.featureType === "boolean" ? null : f.config?.limit ?? null,
+        // Boolean features have no reset interval
+        ...f.featureType !== "boolean" && {
+          reset: f.config?.reset || "monthly"
+        },
+        ...f.config?.usageModel && { usageModel: f.config.usageModel },
+        ...f.config?.pricePerUnit !== void 0 && {
+          pricePerUnit: f.config.pricePerUnit
+        },
+        ...f.config?.ratingModel && { ratingModel: f.config.ratingModel },
+        ...f.config?.tiers && { tiers: f.config.tiers },
+        ...normalizeUsageBasedOverage(
+          f.config?.usageModel,
+          f.config?.overage
+        ) && {
+          overage: normalizeUsageBasedOverage(
+            f.config?.usageModel,
+            f.config?.overage
+          )
+        },
+        ...f.config?.overagePrice !== void 0 && {
+          overagePrice: f.config.overagePrice
+        },
+        ...f.config?.maxOverageUnits !== void 0 && {
+          maxOverageUnits: f.config.maxOverageUnits
+        },
+        ...f.config?.billingUnits !== void 0 && {
+          billingUnits: f.config.billingUnits
+        },
+        ...f.config?.creditCost !== void 0 && {
+          creditCost: f.config.creditCost
+        }
+      };
+    })
   }));
   const creditPacks = catalog.filter((e) => e._type === "credit_pack").map((cp) => ({
     slug: cp.slug,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owostack",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Core SDK for Owostack billing infrastructure",
   "license": "Apache-2.0",
   "repository": {
@@ -30,7 +30,7 @@
     "payments"
   ],
   "dependencies": {
-    "@owostack/types": "0.2.0"
+    "@owostack/types": "0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.3.6",