owostack 0.1.4 → 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, 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;
@@ -133,7 +142,23 @@ declare function plan(slug: string, config: {
     trialDays?: number;
     provider?: string;
     metadata?: Record<string, unknown>;
+    autoEnable?: boolean;
+    isAddon?: boolean;
 }): PlanDefinition;
+/**
+ * Create a credit pack definition.
+ * Credit packs are one-time purchases that add credits to a customer's balance.
+ */
+declare function creditPack(slug: string, config: {
+    name: string;
+    description?: string;
+    credits: number;
+    price: number;
+    currency: Currency;
+    creditSystem: string;
+    provider?: string;
+    metadata?: Record<string, unknown>;
+}): CreditPackDefinition;
 /**
  * Extract SyncPayload from catalog.
  */
@@ -446,4 +471,4 @@ declare class OwostackError extends Error {
     constructor(code: string, message: string);
 }
 
-export { BooleanHandle, CreditSystemHandle, EntityHandle, type MeteredHandle, Owostack, OwostackError, boolean, buildSyncPayload, creditSystem, entity, metered, plan };
+export { BooleanHandle, CreditSystemHandle, EntityHandle, type MeteredHandle, Owostack, OwostackError, boolean, buildSyncPayload, creditPack, creditSystem, entity, metered, plan };

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 {
@@ -258,6 +381,13 @@ function plan(slug, config) {
     ...config
   };
 }
+function creditPack(slug, config) {
+  return {
+    _type: "credit_pack",
+    slug,
+    ...config
+  };
+}
 function slugToName(slug) {
   return slug.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
@@ -273,7 +403,9 @@ function buildSyncPayload(catalog, defaultProvider) {
           slug: f.slug,
           type: f.featureType,
           name: f.name || slugToName(f.slug),
-          ...handle instanceof EntityHandle && { meterType: "non_consumable" }
+          ...handle instanceof EntityHandle && {
+            meterType: "non_consumable"
+          }
         });
       }
     }
@@ -310,34 +442,67 @@ function buildSyncPayload(catalog, defaultProvider) {
     trialDays: p.trialDays ?? void 0,
     provider: p.provider ?? void 0,
     metadata: p.metadata ?? 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
+    autoEnable: p.autoEnable ?? void 0,
+    isAddon: p.isAddon ?? void 0,
+    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,
+    name: cp.name,
+    description: cp.description ?? void 0,
+    credits: cp.credits,
+    price: cp.price,
+    currency: cp.currency,
+    creditSystem: cp.creditSystem,
+    provider: cp.provider ?? void 0,
+    metadata: cp.metadata ?? void 0
   }));
   return {
     defaultProvider,
     features: Array.from(featureMap.values()),
     creditSystems,
+    creditPacks,
     plans
   };
 }
@@ -428,6 +593,7 @@ var Owostack = class {
         success: true,
         features: { created: [], updated: [], unchanged: [] },
         creditSystems: { created: [], updated: [], unchanged: [] },
+        creditPacks: { created: [], updated: [], unchanged: [] },
         plans: { created: [], updated: [], unchanged: [] },
         warnings: ["No catalog entries to sync."]
       };
@@ -809,6 +975,7 @@ export {
   OwostackError,
   boolean,
   buildSyncPayload,
+  creditPack,
   creditSystem,
   entity,
   metered,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "owostack",
-  "version": "0.1.4",
+  "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.1.4"
+    "@owostack/types": "0.3.0"
   },
   "devDependencies": {
     "tsup": "^8.3.6",