unitysvc-core 0.2.26__tar.gz → 0.2.27__tar.gz

{unitysvc_core-0.2.26/src/unitysvc_core.egg-info → unitysvc_core-0.2.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.26
+Version: 0.2.27
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.26"
+version = "0.2.27"
 description = "Shared data models and validation helpers for UnitySVC packages"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/src/unitysvc_core/models/offering_data.py

@@ -74,8 +74,7 @@ class ServiceOfferingData(BaseModel):
         ),
     )
 
-    description: str | None = Field(
-        default=None,
+    description: str = Field(
         description="Service description (long-form; the summary carries the teaser)",
     )
 

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/src/unitysvc_core/models/offering_v1.py

@@ -29,14 +29,6 @@ class OfferingV1(ServiceOfferingData):
     # File-specific fields for validation
     time_created: datetime
 
-    # Override to make required in file validation (base has Optional for API
-    # flexibility). ``summary`` needs no override — it is required on the base
-    # itself: the teaser replaces the retired two-mode description convention
-    # (unitysvc/unitysvc#1838), and the description is free-form long-form text.
-    description: str = Field(  # type: ignore[assignment]
-        description="Service description (long-form; the summary carries the teaser)",
-    )
-
     # Static information (optional — not all service types have meaningful details)
     details: dict[str, Any] = Field(  # type: ignore[assignment]
         default_factory=dict,

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/src/unitysvc_core/models/pricing.py

@@ -110,6 +110,7 @@ class UsageData(BaseModel):
     - **tokens**: one_token, one_thousand_tokens, one_million_tokens
     - **data**: one_byte, one_kilobyte, one_megabyte, one_gigabyte
     - **count**: count, one_thousand, one_million
+    - **characters**: characters, one_character, one_thousand_characters, one_million_characters
 
     Only one field per group should be set per usage instance.
 
@@ -145,6 +146,24 @@ class UsageData(BaseModel):
     one_megabyte: float | None = None
     one_gigabyte: float | None = None
 
+    # Names the GATEWAY actually ships (usage_event.lua), kept as aliases so they
+    # survive ``extra="ignore"``. ``images_generated`` and ``duration_seconds``
+    # join their equivalence groups below; the byte counters deliberately do
+    # NOT — see DataPriceData.based_on.
+    images_generated: int | None = None
+    duration_seconds: float | None = None
+    bytes_in: int | None = None
+    bytes_out: int | None = None
+
+    # Character-based usage (text-to-speech and similar).
+    # ``characters`` is what providers actually report — DashScope's TTS answers
+    # ``usage: {"characters": N}`` — and is the group's base unit, the way
+    # ``seconds`` is for time.
+    characters: int | None = None
+    one_character: int | None = None
+    one_thousand_characters: float | None = None
+    one_million_characters: float | None = None
+
     # Count-based usage (images, steps, requests)
     # count + scaled variants form an equivalence group.
     count: int | None = None
@@ -400,10 +419,13 @@ class ImagePriceData(BasePriceData):
         Returns:
             Calculated cost based on image count
         """
-        if usage.count is None:
+        # Via the equivalence group, so the gateway's ``images_generated`` counts
+        # as well as an explicit ``count``.
+        units = _resolve_equivalent_metric("count", usage)
+        if units is None:
             raise ValueError("Image pricing requires 'count' in usage data")
 
-        return Decimal(self.price) * usage.count
+        return Decimal(self.price) * units
 
 
 class StepPriceData(BasePriceData):
@@ -452,10 +474,23 @@ class DataPriceData(BasePriceData):
 
     Usage can be provided in **any** data unit — cross-unit conversion is
     handled automatically via equivalence groups.
+
+    The gateway ships ``bytes_in`` and ``bytes_out`` on every request. Those are
+    two directions of one dimension, so they are deliberately NOT both in the
+    data equivalence group: a group lookup returns whichever field the dict
+    happens to yield first, which would make the billed direction depend on
+    iteration order. ``based_on`` names the direction instead, so it is a
+    property of the price rather than an accident of the payload.
     """
 
     type: Literal["one_byte", "one_kilobyte", "one_megabyte", "one_gigabyte"] = "one_megabyte"
 
+    based_on: Literal["bytes_out", "bytes_in", "bytes_total"] = Field(
+        default="bytes_out",
+        description="Which byte counter to price. Defaults to egress, the "
+        "conventional billable direction; 'bytes_total' sums both.",
+    )
+
     price: PriceStr = Field(
         description="Price per one unit of the specified type",
     )
@@ -477,7 +512,24 @@ class DataPriceData(BasePriceData):
         Returns:
             Calculated cost based on data usage
         """
-        units = _resolve_equivalent_metric(self.type, usage)
+        # The named byte counter wins when present — it is what the gateway
+        # actually sends. Fall back to the canonical one_byte..one_gigabyte
+        # units so a caller supplying those directly is unaffected.
+        raw_bytes: Decimal | None = None
+        if self.based_on == "bytes_total":
+            if usage.bytes_in is not None or usage.bytes_out is not None:
+                raw_bytes = Decimal(usage.bytes_in or 0) + Decimal(usage.bytes_out or 0)
+        else:
+            value = getattr(usage, self.based_on, None)
+            if value is not None:
+                raw_bytes = Decimal(str(value))
+
+        units: Decimal | None
+        if raw_bytes is not None:
+            units = raw_bytes / EQUIVALENCE_GROUPS["data"][self.type]
+        else:
+            units = _resolve_equivalent_metric(self.type, usage)
+
         if units is None:
             raise ValueError(f"Data pricing ({self.type}) requires a data field in usage data")
 
@@ -528,6 +580,57 @@ class CountPriceData(BasePriceData):
         return Decimal(self.price) * units
 
 
+class CharacterPriceData(BasePriceData):
+    """
+    Price data for character-scaled pricing (text-to-speech and similar).
+
+    Supported types: ``one_character``, ``one_thousand_characters``,
+    ``one_million_characters``. The ``characters`` equivalence-group field is
+    the base unit, and it is the name providers actually report — DashScope's
+    TTS answers ``usage: {"characters": N}``.
+
+    Usage may be given in any unit of the group; conversion is automatic.
+
+    Separate from ``CountPriceData`` on purpose: characters and counts are
+    different dimensions, and collapsing them would let "per 1M characters" and
+    "per 1M images" resolve against each other's usage.
+    """
+
+    type: Literal["one_character", "one_thousand_characters", "one_million_characters"] = "one_million_characters"
+
+    price: PriceStr = Field(
+        description="Price per one unit of the specified type",
+    )
+
+    def calculate_cost(
+        self,
+        usage: UsageData,
+        customer_charge: Decimal | None = None,
+        request_count: int | None = None,
+        channel: str | None = None,
+    ) -> Decimal:
+        """Calculate cost for character-scaled pricing.
+
+        Args:
+            usage: Usage data with any character field
+            customer_charge: Not used (ignored)
+            request_count: Not used (ignored)
+
+        Returns:
+            Calculated cost based on character usage
+
+        Raises:
+            ValueError: if no character field is populated. Raising rather than
+                treating absence as zero is deliberate — a silent zero here is a
+                charge of nothing for work actually done.
+        """
+        units = _resolve_equivalent_metric(self.type, usage)
+        if units is None:
+            raise ValueError(f"Character pricing ({self.type}) requires a character field in usage data")
+
+        return Decimal(self.price) * units
+
+
 def _validate_percentage_string(v: Any) -> str:
     """Validate that percentage values are strings representing valid decimals in range 0-100."""
     # First use the standard price validation
@@ -940,6 +1043,7 @@ class FirstPriceData(BasePriceData):
 EQUIVALENCE_GROUPS: dict[str, dict[str, Decimal]] = {
     "time": {
         "seconds": Decimal(1),
+        "duration_seconds": Decimal(1),  # what usage_event.lua ships
         "one_second": Decimal(1),
         "one_minute": Decimal(60),
         "one_hour": Decimal(3600),
@@ -959,9 +1063,16 @@ EQUIVALENCE_GROUPS: dict[str, dict[str, Decimal]] = {
     },
     "count": {
         "count": Decimal(1),
+        "images_generated": Decimal(1),  # what usage_event.lua ships
         "one_thousand": Decimal(1000),
         "one_million": Decimal(1_000_000),
     },
+    "characters": {
+        "characters": Decimal(1),
+        "one_character": Decimal(1),
+        "one_thousand_characters": Decimal(1000),
+        "one_million_characters": Decimal(1_000_000),
+    },
 }
 
 # Reverse lookup: unit_name → (group_name, base_factor)
@@ -1448,6 +1559,7 @@ Pricing = Annotated[
     | TimePriceData
     | DataPriceData
     | CountPriceData
+    | CharacterPriceData
     | ImagePriceData
     | StepPriceData
     | RevenueSharePriceData
@@ -1472,6 +1584,7 @@ def validate_pricing(
     | TimePriceData
     | DataPriceData
     | CountPriceData
+    | CharacterPriceData
     | ImagePriceData
     | StepPriceData
     | RevenueSharePriceData

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/src/unitysvc_core/schema/listing_v1.json

@@ -217,6 +217,58 @@
       "title": "ChannelPriceData",
       "type": "object"
     },
+    "CharacterPriceData": {
+      "additionalProperties": false,
+      "description": "Price data for character-scaled pricing (text-to-speech and similar).\n\nSupported types: ``one_character``, ``one_thousand_characters``,\n``one_million_characters``. The ``characters`` equivalence-group field is\nthe base unit, and it is the name providers actually report — DashScope's\nTTS answers ``usage: {\"characters\": N}``.\n\nUsage may be given in any unit of the group; conversion is automatic.\n\nSeparate from ``CountPriceData`` on purpose: characters and counts are\ndifferent dimensions, and collapsing them would let \"per 1M characters\" and\n\"per 1M images\" resolve against each other's usage.",
+      "properties": {
+        "description": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Human-readable description of the pricing model",
+          "title": "Description"
+        },
+        "price": {
+          "description": "Price per one unit of the specified type",
+          "title": "Price",
+          "type": "string"
+        },
+        "reference": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL to upstream provider's pricing page",
+          "title": "Reference"
+        },
+        "type": {
+          "default": "one_million_characters",
+          "enum": [
+            "one_character",
+            "one_thousand_characters",
+            "one_million_characters"
+          ],
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "price"
+      ],
+      "title": "CharacterPriceData",
+      "type": "object"
+    },
     "ConstantPriceData": {
       "additionalProperties": false,
       "description": "Price data for a constant/fixed price.\n\nUsed for fixed fees, discounts, or adjustments that don't depend on usage.\nPrice can be positive (charge) or negative (discount/credit).",
@@ -341,8 +393,19 @@
     },
     "DataPriceData": {
       "additionalProperties": false,
-      "description": "Price data for data-volume pricing (bandwidth, storage, transfer).\n\nSupported types: ``one_byte``, ``one_kilobyte``, ``one_megabyte``,\n``one_gigabyte``.  Uses binary units (1 KB = 1024 bytes).\n\nUsage can be provided in **any** data unit — cross-unit conversion is\nhandled automatically via equivalence groups.",
+      "description": "Price data for data-volume pricing (bandwidth, storage, transfer).\n\nSupported types: ``one_byte``, ``one_kilobyte``, ``one_megabyte``,\n``one_gigabyte``.  Uses binary units (1 KB = 1024 bytes).\n\nUsage can be provided in **any** data unit — cross-unit conversion is\nhandled automatically via equivalence groups.\n\nThe gateway ships ``bytes_in`` and ``bytes_out`` on every request. Those are\ntwo directions of one dimension, so they are deliberately NOT both in the\ndata equivalence group: a group lookup returns whichever field the dict\nhappens to yield first, which would make the billed direction depend on\niteration order. ``based_on`` names the direction instead, so it is a\nproperty of the price rather than an accident of the payload.",
       "properties": {
+        "based_on": {
+          "default": "bytes_out",
+          "description": "Which byte counter to price. Defaults to egress, the conventional billable direction; 'bytes_total' sums both.",
+          "enum": [
+            "bytes_out",
+            "bytes_in",
+            "bytes_total"
+          ],
+          "title": "Based On",
+          "type": "string"
+        },
         "description": {
           "anyOf": [
             {
@@ -1447,17 +1510,20 @@
               "min": "#/$defs/MinPriceData",
               "multiply": "#/$defs/MultiplyPriceData",
               "one_byte": "#/$defs/DataPriceData",
+              "one_character": "#/$defs/CharacterPriceData",
               "one_day": "#/$defs/TimePriceData",
               "one_gigabyte": "#/$defs/DataPriceData",
               "one_hour": "#/$defs/TimePriceData",
               "one_kilobyte": "#/$defs/DataPriceData",
               "one_megabyte": "#/$defs/DataPriceData",
               "one_million": "#/$defs/CountPriceData",
+              "one_million_characters": "#/$defs/CharacterPriceData",
               "one_million_tokens": "#/$defs/TokenPriceData",
               "one_minute": "#/$defs/TimePriceData",
               "one_month": "#/$defs/TimePriceData",
               "one_second": "#/$defs/TimePriceData",
               "one_thousand": "#/$defs/CountPriceData",
+              "one_thousand_characters": "#/$defs/CharacterPriceData",
               "one_thousand_tokens": "#/$defs/TokenPriceData",
               "one_token": "#/$defs/TokenPriceData",
               "revenue_share": "#/$defs/RevenueSharePriceData",
@@ -1479,6 +1545,9 @@
             {
               "$ref": "#/$defs/CountPriceData"
             },
+            {
+              "$ref": "#/$defs/CharacterPriceData"
+            },
             {
               "$ref": "#/$defs/ImagePriceData"
             },

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/src/unitysvc_core/schema/offering_v1.json

@@ -138,6 +138,58 @@
       "title": "ChannelPriceData",
       "type": "object"
     },
+    "CharacterPriceData": {
+      "additionalProperties": false,
+      "description": "Price data for character-scaled pricing (text-to-speech and similar).\n\nSupported types: ``one_character``, ``one_thousand_characters``,\n``one_million_characters``. The ``characters`` equivalence-group field is\nthe base unit, and it is the name providers actually report — DashScope's\nTTS answers ``usage: {\"characters\": N}``.\n\nUsage may be given in any unit of the group; conversion is automatic.\n\nSeparate from ``CountPriceData`` on purpose: characters and counts are\ndifferent dimensions, and collapsing them would let \"per 1M characters\" and\n\"per 1M images\" resolve against each other's usage.",
+      "properties": {
+        "description": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Human-readable description of the pricing model",
+          "title": "Description"
+        },
+        "price": {
+          "description": "Price per one unit of the specified type",
+          "title": "Price",
+          "type": "string"
+        },
+        "reference": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL to upstream provider's pricing page",
+          "title": "Reference"
+        },
+        "type": {
+          "default": "one_million_characters",
+          "enum": [
+            "one_character",
+            "one_thousand_characters",
+            "one_million_characters"
+          ],
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "price"
+      ],
+      "title": "CharacterPriceData",
+      "type": "object"
+    },
     "ConstantPriceData": {
       "additionalProperties": false,
       "description": "Price data for a constant/fixed price.\n\nUsed for fixed fees, discounts, or adjustments that don't depend on usage.\nPrice can be positive (charge) or negative (discount/credit).",
@@ -262,8 +314,19 @@
     },
     "DataPriceData": {
       "additionalProperties": false,
-      "description": "Price data for data-volume pricing (bandwidth, storage, transfer).\n\nSupported types: ``one_byte``, ``one_kilobyte``, ``one_megabyte``,\n``one_gigabyte``.  Uses binary units (1 KB = 1024 bytes).\n\nUsage can be provided in **any** data unit — cross-unit conversion is\nhandled automatically via equivalence groups.",
+      "description": "Price data for data-volume pricing (bandwidth, storage, transfer).\n\nSupported types: ``one_byte``, ``one_kilobyte``, ``one_megabyte``,\n``one_gigabyte``.  Uses binary units (1 KB = 1024 bytes).\n\nUsage can be provided in **any** data unit — cross-unit conversion is\nhandled automatically via equivalence groups.\n\nThe gateway ships ``bytes_in`` and ``bytes_out`` on every request. Those are\ntwo directions of one dimension, so they are deliberately NOT both in the\ndata equivalence group: a group lookup returns whichever field the dict\nhappens to yield first, which would make the billed direction depend on\niteration order. ``based_on`` names the direction instead, so it is a\nproperty of the price rather than an accident of the payload.",
       "properties": {
+        "based_on": {
+          "default": "bytes_out",
+          "description": "Which byte counter to price. Defaults to egress, the conventional billable direction; 'bytes_total' sums both.",
+          "enum": [
+            "bytes_out",
+            "bytes_in",
+            "bytes_total"
+          ],
+          "title": "Based On",
+          "type": "string"
+        },
         "description": {
           "anyOf": [
             {
@@ -1432,17 +1495,20 @@
               "min": "#/$defs/MinPriceData",
               "multiply": "#/$defs/MultiplyPriceData",
               "one_byte": "#/$defs/DataPriceData",
+              "one_character": "#/$defs/CharacterPriceData",
               "one_day": "#/$defs/TimePriceData",
               "one_gigabyte": "#/$defs/DataPriceData",
               "one_hour": "#/$defs/TimePriceData",
               "one_kilobyte": "#/$defs/DataPriceData",
               "one_megabyte": "#/$defs/DataPriceData",
               "one_million": "#/$defs/CountPriceData",
+              "one_million_characters": "#/$defs/CharacterPriceData",
               "one_million_tokens": "#/$defs/TokenPriceData",
               "one_minute": "#/$defs/TimePriceData",
               "one_month": "#/$defs/TimePriceData",
               "one_second": "#/$defs/TimePriceData",
               "one_thousand": "#/$defs/CountPriceData",
+              "one_thousand_characters": "#/$defs/CharacterPriceData",
               "one_thousand_tokens": "#/$defs/TokenPriceData",
               "one_token": "#/$defs/TokenPriceData",
               "revenue_share": "#/$defs/RevenueSharePriceData",
@@ -1464,6 +1530,9 @@
             {
               "$ref": "#/$defs/CountPriceData"
             },
+            {
+              "$ref": "#/$defs/CharacterPriceData"
+            },
             {
               "$ref": "#/$defs/ImagePriceData"
             },

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27/src/unitysvc_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.26
+Version: 0.2.27
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/src/unitysvc_core.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/unitysvc_core/schema/provider_v1.json
 src/unitysvc_core/schema/service_group_v1.json
 tests/test_access_interface_routing.py
 tests/test_hidden_path_skip.py
+tests/test_offering_data.py
 tests/test_pricing.py
 tests/test_provider_account_rate_limits.py
 tests/test_service_group.py

unitysvc_core-0.2.27/tests/test_offering_data.py

@@ -0,0 +1,14 @@
+"""Validation tests for shared service-offering data."""
+
+import pytest
+from pydantic import ValidationError
+
+from unitysvc_core.models import ServiceOfferingData
+
+
+def test_service_offering_requires_description() -> None:
+    with pytest.raises(ValidationError) as exc_info:
+        ServiceOfferingData(name="missing-description", summary="No description")
+
+    assert exc_info.value.errors()[0]["loc"] == ("description",)
+    assert exc_info.value.errors()[0]["type"] == "missing"

{unitysvc_core-0.2.26 → unitysvc_core-0.2.27}/tests/test_pricing.py

@@ -246,6 +246,157 @@ class TestDataPriceData:
             pricing.calculate_cost(usage)
 
 
+class TestCharacterPriceData:
+    """Character-scaled pricing (text-to-speech and similar).
+
+    Providers that bill per character report it as ``usage: {"characters": N}``
+    — DashScope's TTS does, for example. Before this unit existed the value was
+    dropped at the ``UsageData`` boundary (``extra="ignore"``), so a service
+    could pass its ``min_expected_metrics`` floor, which reads the raw metrics
+    dict, and still be charged nothing.
+    """
+
+    def test_per_million_characters(self) -> None:
+        pricing = validate_pricing({"type": "one_million_characters", "price": "30.00"})
+        usage = UsageData(characters=1_000_000)
+
+        assert pricing.calculate_cost(usage) == Decimal("30.00")
+
+    def test_per_thousand_characters(self) -> None:
+        pricing = validate_pricing({"type": "one_thousand_characters", "price": "0.05"})
+        usage = UsageData(characters=2000)
+
+        assert pricing.calculate_cost(usage) == Decimal("0.10")
+
+    def test_per_character(self) -> None:
+        pricing = validate_pricing({"type": "one_character", "price": "0.001"})
+        usage = UsageData(characters=44)
+
+        assert pricing.calculate_cost(usage) == Decimal("0.044")
+
+    def test_cross_unit_conversion(self) -> None:
+        """A provider reporting raw characters prices against any scaled unit."""
+        pricing = validate_pricing({"type": "one_million_characters", "price": "30.00"})
+
+        # 44 characters at $30 per 1M
+        assert pricing.calculate_cost(UsageData(characters=44)) == Decimal("0.00132")
+
+    def test_scaled_usage_field_also_works(self) -> None:
+        pricing = validate_pricing({"type": "one_character", "price": "0.001"})
+
+        assert pricing.calculate_cost(UsageData(one_thousand_characters=2)) == Decimal("2")
+
+    def test_characters_survive_construction(self) -> None:
+        """The regression this unit exists for.
+
+        ``UsageData`` is ``extra="ignore"``, so before the field existed
+        ``UsageData(characters=44)`` silently produced an empty object and any
+        charge computed from it was zero.
+        """
+        usage = UsageData(**{"characters": 44, "input_tokens": 13})
+
+        assert usage.characters == 44
+        assert usage.input_tokens == 13
+
+    def test_missing_usage_is_an_error_not_a_zero(self) -> None:
+        """Never bill zero for absent usage — raise so the caller notices."""
+        pricing = validate_pricing({"type": "one_million_characters", "price": "30.00"})
+
+        with pytest.raises(ValueError, match="[Cc]haracter"):
+            pricing.calculate_cost(UsageData())
+
+
+class TestGatewayEmittedMetricNames:
+    """The names the gateway actually ships must survive into UsageData.
+
+    ``UsageData`` is ``extra="ignore"``, and the gateway's metric names had
+    drifted from the pricing model's field names. Measured against what
+    ``usage_event.lua`` writes: ``images_generated``, ``duration_seconds``,
+    ``bytes_in`` and ``bytes_out`` were all dropped, so image-, time- and
+    data-priced services could not be billed at all.
+
+    Latent rather than live — only ``one_million_tokens``, ``constant`` and
+    ``revenue_share`` are in use across the seller repos today — but it blocks
+    exactly the modalities being onboarded.
+    """
+
+    def test_images_generated_prices_as_a_count(self) -> None:
+        """The gateway sends images_generated; ImagePriceData resolves count."""
+        pricing = validate_pricing({"type": "image", "price": "0.04"})
+        usage = UsageData(**{"images_generated": 4, "bytes_in": 100, "bytes_out": 2000})
+
+        assert pricing.calculate_cost(usage) == Decimal("0.16")
+
+    def test_duration_seconds_prices_as_time(self) -> None:
+        pricing = validate_pricing({"type": "one_second", "price": "0.01"})
+        usage = UsageData(**{"duration_seconds": 12.5})
+
+        assert pricing.calculate_cost(usage) == Decimal("0.125")
+
+    def test_duration_seconds_converts_across_the_time_group(self) -> None:
+        pricing = validate_pricing({"type": "one_minute", "price": "0.60"})
+        usage = UsageData(**{"duration_seconds": 120})
+
+        assert pricing.calculate_cost(usage) == Decimal("1.20")
+
+    def test_data_pricing_defaults_to_egress(self) -> None:
+        pricing = validate_pricing({"type": "one_megabyte", "price": "0.10"})
+        usage = UsageData(**{"bytes_in": 1_048_576, "bytes_out": 5_242_880})
+
+        # 5 MiB egress at $0.10/MiB — NOT the 1 MiB ingress.
+        assert pricing.calculate_cost(usage) == Decimal("0.50")
+
+    def test_data_pricing_direction_is_explicit_not_incidental(self) -> None:
+        """The reason bytes_in/bytes_out are not both in the equivalence group.
+
+        With both populated, a group lookup would return whichever the dict
+        happened to yield first. The direction must come from the price.
+        """
+        usage = UsageData(**{"bytes_in": 1_048_576, "bytes_out": 5_242_880})
+
+        egress = validate_pricing({"type": "one_megabyte", "price": "0.10", "based_on": "bytes_out"})
+        ingress = validate_pricing({"type": "one_megabyte", "price": "0.10", "based_on": "bytes_in"})
+        both = validate_pricing({"type": "one_megabyte", "price": "0.10", "based_on": "bytes_total"})
+
+        assert egress.calculate_cost(usage) == Decimal("0.50")
+        assert ingress.calculate_cost(usage) == Decimal("0.10")
+        assert both.calculate_cost(usage) == Decimal("0.60")
+
+    def test_explicit_data_units_still_work(self) -> None:
+        """Back-compat: a caller supplying the canonical unit is unaffected."""
+        pricing = validate_pricing({"type": "one_megabyte", "price": "0.10"})
+
+        assert pricing.calculate_cost(UsageData(one_megabyte=3)) == Decimal("0.30")
+
+    def test_a_full_gateway_payload_survives(self) -> None:
+        """Every name usage_event.lua can ship, in one object."""
+        usage = UsageData(
+            **{
+                "input_tokens": 13,
+                "output_tokens": 10,
+                "total_tokens": 23,
+                "images_generated": 2,
+                "duration_seconds": 1.5,
+                "characters": 44,
+                "bytes_in": 100,
+                "bytes_out": 2000,
+            }
+        )
+
+        kept = usage.model_dump(exclude_none=True)
+        for name in (
+            "input_tokens",
+            "output_tokens",
+            "total_tokens",
+            "images_generated",
+            "duration_seconds",
+            "characters",
+            "bytes_in",
+            "bytes_out",
+        ):
+            assert name in kept, f"{name} was dropped by UsageData"
+
+
 class TestCountPriceData:
     """Tests for count-scaled pricing."""