fix: treat vague fal billing units as unknown pricing (#4730)

Author: georgi

packages/fal-nodes/src/fal-cost.ts

@@ -159,9 +159,14 @@ function inferQuantity(
   return 1;
 }
 
+function isVagueBillingUnit(unit: string): boolean {
+  return /\bunits?\b|\bcredits?\b/i.test(unit.trim());
+}
+
 /**
  * Estimate the cost of a completed FAL call. Returns `null` when no pricing is
- * known for the node type.
+ * known for the node type, or when the billing unit is vague (e.g. "units" or
+ * "credits") and the unit_price doesn't represent a meaningful per-output cost.
  */
 export function estimateFalCost(
   nodeType: string,
@@ -174,6 +179,8 @@ export function estimateFalCost(
   const unitPrice = finiteNumber(pricing.unit_price);
   if (unitPrice == null) return null;
 
+  if (isVagueBillingUnit(pricing.billing_unit)) return null;
+
   const quantity = inferQuantity(pricing.billing_unit, res, args);
   const cost = unitPrice * quantity;
 

packages/fal-nodes/tests/fal-cost.test.ts

@@ -18,6 +18,14 @@ describe("estimateFalCost", () => {
     expect(estimateFalCost("fal.nope.DoesNotExist", {})).toBeNull();
   });
 
+  it("returns null for vague billing units (units/credits)", () => {
+    // fal.3d_to_3d.Sam33DAlign has billing_unit: "units"
+    const pricing = getFalPricing("fal.3d_to_3d.Sam33DAlign");
+    expect(pricing).not.toBeNull();
+    expect(pricing!.billing_unit).toBe("units");
+    expect(estimateFalCost("fal.3d_to_3d.Sam33DAlign", {})).toBeNull();
+  });
+
   it("treats per-generation calls as a single unit", () => {
     const pricing = getFalPricing(GENERATIONS)!;
     expect(pricing.billing_unit).toBe("generations");

packages/node-sdk/src/cost-estimate.ts

@@ -125,6 +125,10 @@ interface ResolvedPrice {
   confidence: CostConfidence;
 }
 
+function isVagueBillingUnit(unit: string): boolean {
+  return /\bunits?\b|\bcredits?\b/i.test(unit.trim());
+}
+
 /**
  * The model selected on a generic node, read from the value of its first
  * provider-model property (e.g. `model` on TextToImage). Returns null when the
@@ -172,6 +176,9 @@ function resolvePrice(
 ): ResolvedPrice | null {
   const fal = metadata?.fal_unit_pricing;
   if (fal && Number.isFinite(fal.unit_price)) {
+    if (isVagueBillingUnit(fal.billing_unit)) {
+      return null;
+    }
     return {
       provider: "fal",
       model: fal.endpoint_id ?? null,

packages/node-sdk/tests/cost-estimate.test.ts

@@ -6,6 +6,7 @@ import {
 } from "../src/cost-estimate.js";
 
 const FAL_TYPE = "fal.image.FluxSchnell";
+const FAL_VAGUE_TYPE = "fal.text_to_image.GptImage2";
 const KIE_TYPE = "kie.video.Veo";
 const LLM_TYPE = "nodetool.agents.Agent";
 const GENERIC_TYPE = "nodetool.image.TextToImage";
@@ -20,6 +21,15 @@ const metadataByType: Record<string, NodeMetadataLike> = {
       source: "bundle"
     }
   },
+  [FAL_VAGUE_TYPE]: {
+    fal_unit_pricing: {
+      endpoint_id: "openai/gpt-image-2",
+      unit_price: 1,
+      billing_unit: "units",
+      currency: "USD",
+      source: "bundle"
+    }
+  },
   [KIE_TYPE]: {
     kie_unit_pricing: {
       model_id: "veo3",
@@ -90,6 +100,21 @@ describe("estimateWorkflowCost", () => {
     expect(estimate.total).toBeCloseTo(2.5, 10);
   });
 
+  it("treats fal nodes with vague billing (units/credits) as unknown", () => {
+    const estimate = estimateWorkflowCost({
+      nodes: [{ id: "v1", type: FAL_VAGUE_TYPE }],
+      getMetadata
+    });
+
+    expect(estimate.unknown_count).toBe(1);
+    expect(estimate.total).toBe(0);
+
+    const item = estimate.items[0];
+    expect(item.confidence).toBe("unknown");
+    expect(item.estimated_cost).toBe(0);
+    expect(item.provider).toBeNull();
+  });
+
   it("reports unpriced nodes as unknown without affecting the total", () => {
     const estimate = estimateWorkflowCost({
       nodes: [

web/src/utils/__tests__/formatFalUnitPricing.test.ts

@@ -16,6 +16,12 @@ describe("isFalVagueBillingSummary", () => {
     expect(isFalVagueBillingSummary({ billing_unit: "Units" })).toBe(true);
   });
 
+  it('returns true for "credit" and "credits"', () => {
+    expect(isFalVagueBillingSummary({ billing_unit: "credit" })).toBe(true);
+    expect(isFalVagueBillingSummary({ billing_unit: "credits" })).toBe(true);
+    expect(isFalVagueBillingSummary({ billing_unit: "Credits" })).toBe(true);
+  });
+
   it("returns false for specific billing units", () => {
     expect(isFalVagueBillingSummary({ billing_unit: "image" })).toBe(false);
     expect(isFalVagueBillingSummary({ billing_unit: "second" })).toBe(false);
@@ -24,6 +30,7 @@ describe("isFalVagueBillingSummary", () => {
 
   it("handles whitespace-padded values", () => {
     expect(isFalVagueBillingSummary({ billing_unit: "  units  " })).toBe(true);
+    expect(isFalVagueBillingSummary({ billing_unit: "  credits  " })).toBe(true);
   });
 });
 
@@ -60,6 +67,26 @@ describe("formatFalUnitPricingShort", () => {
     const result = formatFalUnitPricingShort(p);
     expect(result).toContain("0.00");
   });
+
+  it('returns "pricing varies" for vague billing units', () => {
+    const p = {
+      unit_price: 1,
+      currency: "USD",
+      billing_unit: "units",
+      endpoint_id: "openai/gpt-image-2",
+    } as FalUnitPricing;
+    expect(formatFalUnitPricingShort(p)).toBe("pricing varies");
+  });
+
+  it('returns "pricing varies" for credits billing', () => {
+    const p = {
+      unit_price: 1,
+      currency: "USD",
+      billing_unit: "credits",
+      endpoint_id: "fal-ai/gpt-image-1-mini",
+    } as FalUnitPricing;
+    expect(formatFalUnitPricingShort(p)).toBe("pricing varies");
+  });
 });
 
 describe("formatFalUnitPricingTooltip", () => {

web/src/utils/formatFalUnitPricing.test.ts

@@ -31,6 +31,12 @@ describe("isFalVagueBillingSummary", () => {
 
   it("is case-insensitive", () => {
     expect(isFalVagueBillingSummary({ billing_unit: "Units" })).toBe(true);
+    expect(isFalVagueBillingSummary({ billing_unit: "Credits" })).toBe(true);
+  });
+
+  it("returns true when billing_unit is 'credits'", () => {
+    expect(isFalVagueBillingSummary({ billing_unit: "credits" })).toBe(true);
+    expect(isFalVagueBillingSummary({ billing_unit: "credit" })).toBe(true);
   });
 
   it("returns false for 'megapixel'", () => {
@@ -63,6 +69,16 @@ describe("formatFalUnitPricingShort", () => {
     const result = formatFalUnitPricingShort(makePricing({ unit_price: 0 }));
     expect(result).toContain("$");
   });
+
+  it('returns "pricing varies" for vague billing (units)', () => {
+    const result = formatFalUnitPricingShort(makePricing({ billing_unit: "units", unit_price: 1 }));
+    expect(result).toBe("pricing varies");
+  });
+
+  it('returns "pricing varies" for vague billing (credits)', () => {
+    const result = formatFalUnitPricingShort(makePricing({ billing_unit: "credits", unit_price: 1 }));
+    expect(result).toBe("pricing varies");
+  });
 });
 
 describe("formatFalUnitPricingTooltip", () => {

web/src/utils/formatFalUnitPricing.ts

@@ -30,7 +30,7 @@ function formatMoney(amount: number, currency: string): string {
  * proportional billing may diverge strongly from what users expect one image/run to cost.
  */
 export function isFalVagueBillingSummary(p: { billing_unit: string }): boolean {
-  return /\bunits?\b/i.test(p.billing_unit.trim());
+  return /\bunits?\b|\bcredits?\b/i.test(p.billing_unit.trim());
 }
 
 /** Label for historical per-run estimate from fal.ai pricing/estimate API. */
@@ -40,6 +40,9 @@ export function formatFalPerRunEstimate(totalCost: number, currency: string): st
 
 /** Compact label for node chrome (fal monetary `unit_price`). */
 export function formatFalUnitPricingShort(p: FalUnitPricing): string {
+  if (isFalVagueBillingSummary(p)) {
+    return "pricing varies";
+  }
   return formatMoney(p.unit_price, p.currency);
 }