keble-data-infra-contract 0.1.0__tar.gz

keble_data_infra_contract-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+target/
+cert/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+*__ignored__*
+
+*.env
+**/.env.docker
+*.DS_Store
+**/.DS_Store
+
+.vscode
+.idea
+
+*.crt
+
+uploads/
+!strapi-v5/public/uploads/
+!strapi-v5/public/uploads/.gitkeep
+test/
+resources/
+Brewfile
+qdrant/
+*.pyc
+**.pyc.*
+*/traefik/certs
+*/traefik/certs/*
+gcp.json
+.history
+
+prod.env.*

keble_data_infra_contract-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: keble-data-infra-contract
+Version: 0.1.0
+Summary: Framework-free raw commerce contracts shared by Keble data providers and the raw API.
+Author-email: zhenhao-ma <bob0103779@gmail.com>
+Requires-Python: <3.14,>=3.13
+Requires-Dist: keble-helpers<2,>=1.50.0
+Requires-Dist: pydantic<3,>=2.10
+Description-Content-Type: text/markdown
+
+# keble-data-infra-contract
+
+Install the provider-neutral public contract with
+`pip install "keble-data-infra-contract>=0.1.0,<1"`.
+
+Framework-free, provider-neutral raw-commerce contracts. This distribution owns
+validated request/response models, provider protocols, operation keys, manifests,
+and typed domain errors. It intentionally has no FastAPI, database, HTTP client,
+provider, platform, or idea dependency.
+
+The distribution declares only registry-resolvable runtime dependencies. Do not
+add workspace-relative `tool.uv.sources` here: downstream Git/subdirectory installs
+must build this contract without inheriting paths outside the repository checkout.
+
+Provider packages own implementations and native DTOs. The raw API consumes
+provider manifests and constructs HTTP paths from their typed operation keys.
+
+```bash
+uv run --package keble-data-infra-contract pytest -q keble-data-infra-contract/tests
+uv run --package keble-data-infra-contract npx --yes pyright keble-data-infra-contract
+uv build --package keble-data-infra-contract
+```
+
+Contract values inherit `ContractModel`, which accepts snake-case Python names
+and camel-case wire aliases, rejects undeclared fields, and is frozen. Persisted
+Mongo shapes do not belong here; provider/API packages own `SchemaBase` /
+`MongoObjectBase` aggregates when durability is required.
+`ContractModel` and the deliberately producer-tolerant Job/Result projection
+both configure Pydantic through `keble-helpers.PydanticModelConfig`; a local
+`ConfigDict` convention would split alias and validation ownership again.
+
+`Money`, `Currency`, and `AmazonMarketplace` are imported from
+`keble-helpers`. Provider-native response details remain inside the provider
+package instead of crossing this boundary through an untyped extension bag.
+
+Video enrichment uses the same framework-free boundary: immutable asset,
+submission, job, completion-event, result, and normalized-projection models plus
+one `VideoEnrichmentGateway` Protocol. HTTP submission and Mongo correlation
+remain implementations owned by `keble-data-infra-api`.
+
+Authorized provider transcripts use one canonical `VideoTranscript`/
+`VideoTranscriptSegment` shape across submission, authoritative result reads, and
+the local projection. Reuse evidence binds the normalized transcript checksum to
+the data-infra source reference and media SHA-256; a title/description such as
+`ShortVideo.caption` is not a spoken transcript and cannot bypass ASR.

keble_data_infra_contract-0.1.0/README.md

@@ -0,0 +1,45 @@
+# keble-data-infra-contract
+
+Install the provider-neutral public contract with
+`pip install "keble-data-infra-contract>=0.1.0,<1"`.
+
+Framework-free, provider-neutral raw-commerce contracts. This distribution owns
+validated request/response models, provider protocols, operation keys, manifests,
+and typed domain errors. It intentionally has no FastAPI, database, HTTP client,
+provider, platform, or idea dependency.
+
+The distribution declares only registry-resolvable runtime dependencies. Do not
+add workspace-relative `tool.uv.sources` here: downstream Git/subdirectory installs
+must build this contract without inheriting paths outside the repository checkout.
+
+Provider packages own implementations and native DTOs. The raw API consumes
+provider manifests and constructs HTTP paths from their typed operation keys.
+
+```bash
+uv run --package keble-data-infra-contract pytest -q keble-data-infra-contract/tests
+uv run --package keble-data-infra-contract npx --yes pyright keble-data-infra-contract
+uv build --package keble-data-infra-contract
+```
+
+Contract values inherit `ContractModel`, which accepts snake-case Python names
+and camel-case wire aliases, rejects undeclared fields, and is frozen. Persisted
+Mongo shapes do not belong here; provider/API packages own `SchemaBase` /
+`MongoObjectBase` aggregates when durability is required.
+`ContractModel` and the deliberately producer-tolerant Job/Result projection
+both configure Pydantic through `keble-helpers.PydanticModelConfig`; a local
+`ConfigDict` convention would split alias and validation ownership again.
+
+`Money`, `Currency`, and `AmazonMarketplace` are imported from
+`keble-helpers`. Provider-native response details remain inside the provider
+package instead of crossing this boundary through an untyped extension bag.
+
+Video enrichment uses the same framework-free boundary: immutable asset,
+submission, job, completion-event, result, and normalized-projection models plus
+one `VideoEnrichmentGateway` Protocol. HTTP submission and Mongo correlation
+remain implementations owned by `keble-data-infra-api`.
+
+Authorized provider transcripts use one canonical `VideoTranscript`/
+`VideoTranscriptSegment` shape across submission, authoritative result reads, and
+the local projection. Reuse evidence binds the normalized transcript checksum to
+the data-infra source reference and media SHA-256; a title/description such as
+`ShortVideo.caption` is not a spoken transcript and cannot bypass ASR.

keble_data_infra_contract-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "keble-data-infra-contract"
+version = "0.1.0"
+description = "Framework-free raw commerce contracts shared by Keble data providers and the raw API."
+readme = "README.md"
+requires-python = ">=3.13,<3.14"
+dependencies = [
+    "keble-helpers>=1.50.0,<2",
+    "pydantic>=2.10,<3",
+]
+
+[[project.authors]]
+name = "zhenhao-ma"
+email = "bob0103779@gmail.com"
+
+[dependency-groups]
+test = [
+    "pytest>=8.2,<9",
+    "pytest-asyncio>=1.4,<2",
+]
+
+[tool.uv]
+default-groups = ["test"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: fast deterministic tests with no network",
+    "contract: recorded or fixture-based external contract tests",
+]

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/__init__.py

@@ -0,0 +1,13 @@
+"""Public framework-free contract surface for Keble raw data providers."""
+
+from .manifests import ProviderManifest, ServiceOperation
+from .operations import CommerceAction, CommerceResource, RouteKey
+
+__all__ = [
+    "CommerceAction",
+    "CommerceResource",
+    "ProviderManifest",
+    "RouteKey",
+    "ServiceOperation",
+]
+

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/errors.py

@@ -0,0 +1,60 @@
+"""Typed errors shared by provider services and the raw API boundary."""
+
+from .operations import RouteKey
+from .models.identity import Channel, ProviderId
+
+
+class DataInfraError(Exception):
+    """Base class for expected raw-data contract and provider failures."""
+
+
+class DuplicateOperationError(DataInfraError):
+    """Raised when two manifests declare the same provider operation key."""
+
+    def __init__(self, *, key: RouteKey) -> None:
+        super().__init__(f"duplicate provider operation: {key.operation_id()}")
+        self.key = key
+
+
+class OperationNotSupportedError(DataInfraError):
+    """Raised when a provider does not declare the requested capability."""
+
+    def __init__(self, *, key: RouteKey) -> None:
+        super().__init__(f"provider operation is not supported: {key.operation_id()}")
+        self.key = key
+
+
+class ProviderNotFoundError(DataInfraError):
+    """Raised when provider discovery targets an unregistered identity."""
+
+    def __init__(self, *, channel: Channel, provider_id: ProviderId) -> None:
+        super().__init__(
+            f"provider is not registered: channel={channel.value}, provider={provider_id.root}"
+        )
+        self.channel = channel
+        self.provider_id = provider_id
+
+
+class ProviderRequestValidationError(DataInfraError):
+    """Raised when a provider capability requires a missing or invalid field."""
+
+    def __init__(self, *, field: str, message: str) -> None:
+        super().__init__(f"invalid provider request field {field}: {message}")
+        self.field = field
+        self.message = message
+
+
+class ProviderUnavailableError(DataInfraError):
+    """Raised when a declared provider cannot complete an upstream request."""
+
+
+class ProviderAuthenticationError(DataInfraError):
+    """Raised when provider credentials are absent or rejected."""
+
+
+class ProviderRateLimitError(DataInfraError):
+    """Raised when an upstream provider rejects work because of a rate limit."""
+
+
+class ProviderTimeoutError(DataInfraError):
+    """Raised when an upstream provider exceeds its configured timeout."""

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/manifests.py

@@ -0,0 +1,84 @@
+"""Strongly typed provider operation manifests without HTTP dependencies."""
+
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Generic, TypeVar, cast
+
+from .errors import DuplicateOperationError
+from .models.base import ContractModel
+from .models.identity import Channel, ProviderId
+from .operations import RouteKey
+
+RequestT = TypeVar("RequestT", bound=ContractModel)
+ResponseT = TypeVar("ResponseT", bound=ContractModel)
+
+
+@dataclass(frozen=True)
+class ServiceOperation(Generic[RequestT, ResponseT]):
+    """Bind one provider-owned service method to a framework-free operation key.
+
+    Side effects if changes:
+    - provider packages construct these bindings in `provider_manifest`;
+    - the API registry validates requests and responses through them;
+    - route generation uses their request and response model classes.
+    """
+
+    key: RouteKey
+    request_model: type[RequestT]
+    response_model: type[ResponseT]
+    handler: Callable[[RequestT], Awaitable[ResponseT]]
+
+    async def invoke(self, request: ContractModel) -> ContractModel:
+        """Validate the erased registry input, invoke, and verify output type."""
+
+        typed_request = self.request_model.model_validate(request)
+        response = await self.handler(typed_request)
+        return self.response_model.model_validate(response)
+
+    def erase(self) -> "ServiceOperation[ContractModel, ContractModel]":
+        """Erase generic parameters only at the heterogeneous registry boundary."""
+
+        return cast("ServiceOperation[ContractModel, ContractModel]", self)
+
+
+@dataclass(frozen=True)
+class ProviderManifest:
+    """Complete, explicit capability set exported by one provider service.
+
+    Steps:
+    1. validate every operation belongs to the manifest channel/provider;
+    2. reject duplicate route keys before API startup;
+    3. expose only registered operations as provider capabilities.
+
+    Side effects if changes:
+    - raw API startup and provider discovery;
+    - Amazon and TikTok service exports;
+    - duplicate route and OpenAPI guards.
+    """
+
+    channel: Channel
+    provider_id: ProviderId
+    operations: tuple[ServiceOperation[ContractModel, ContractModel], ...]
+
+    @classmethod
+    def build(
+        cls,
+        *,
+        channel: Channel,
+        provider_id: ProviderId,
+        operations: Iterable[ServiceOperation[ContractModel, ContractModel]],
+    ) -> "ProviderManifest":
+        """Validate ownership and uniqueness while freezing one manifest."""
+
+        materialized = tuple(operations)
+        seen: set[RouteKey] = set()
+        for operation in materialized:
+            if operation.key.channel is not channel:
+                raise ValueError("manifest operation channel does not match manifest owner")
+            if operation.key.provider_id != provider_id:
+                raise ValueError("manifest operation provider does not match manifest owner")
+            if operation.key in seen:
+                raise DuplicateOperationError(key=operation.key)
+            seen.add(operation.key)
+        return cls(channel=channel, provider_id=provider_id, operations=materialized)
+

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/models/base.py

@@ -0,0 +1,23 @@
+"""Shared model inheritance for framework-free data-infra contracts."""
+
+from pydantic import BaseModel
+
+from keble_helpers.typings import PydanticModelConfig
+
+
+class ContractModel(BaseModel):
+    """Base for immutable camel-case raw-data contracts.
+
+    Steps:
+    1. accept Python snake_case and HTTP camelCase field names;
+    2. reject undeclared provider payload fields;
+    3. keep validated contract values immutable across adapters.
+
+    Side effects if changes:
+    - every provider manifest request and response;
+    - `keble-data-infra-api` OpenAPI generation;
+    - the Stand Out raw HTTP adapter fixtures.
+    """
+
+    model_config = PydanticModelConfig.default(extra="forbid", frozen=True)
+

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/models/creator.py

@@ -0,0 +1,54 @@
+"""CommerceCreator — universal channel creator entity.
+
+A CommerceCreator is a content creator / influencer as they appear on a
+specific commerce channel (TikTok today; other creator-carrying channels
+later). It is the ranked entity of CreatorRankingProvider.rank_creators.
+
+Design rules (mirrors CommerceListing):
+- Provider-native creator details remain internal to the provider package.
+- ``metrics`` is a list of MetricObservation (entity_scope=CREATOR), not a
+  KV bag. Follower counts, follower growth, and attributed GMV all flow
+  through MetricObservation.
+- ``identities`` preserves the provider-native creator ID alongside the
+  channel creator ID for deduplication and provenance.
+- Only the cross-channel universal core lives here (id, handle, display
+  name, avatar, market, metrics). Channel-specific scores/flags remain in
+  the provider package.
+"""
+
+from __future__ import annotations
+
+from keble_data_infra_contract.models.base import ContractModel
+
+from pydantic import Field
+
+from keble_data_infra_contract.models.identity import Channel, ExternalIdentity
+from keble_data_infra_contract.models.metric import MetricObservation
+from keble_data_infra_contract.models.provenance import Provenance
+
+
+class CommerceCreator(ContractModel):
+    """A creator on a specific commerce channel in a specific market.
+
+    FastMoss / TikTok mapping (Phase 2):
+        channel            ← Channel.TIKTOK
+        market             ← item.region  (e.g., "US")
+        channel_creator_id ← creator.uid
+        handle             ← creator.unique_id  (the @handle)
+        display_name       ← creator.nickname
+        avatar_url         ← creator.avatar
+        identities         ← [ExternalIdentity(provider=fastmoss, namespace="tiktok_creator_uid", …)]
+        metrics            ← [MetricObservation(follower_count/follower_growth/gmv, CREATOR scope), …]
+        provenance         ← Provenance(provider=fastmoss, captured_at=…)
+    """
+
+
+    channel: Channel
+    market: str | None = None
+    channel_creator_id: str
+    handle: str | None = None
+    display_name: str | None = None
+    avatar_url: str | None = None
+    identities: list[ExternalIdentity] = Field(default_factory=list)
+    metrics: list[MetricObservation] = Field(default_factory=list)
+    provenance: Provenance | None = None

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/models/creator_link.py

@@ -0,0 +1,56 @@
+"""CreatorProductLink — universal creator↔product promotion relation (Phase 3).
+
+Represents the "creator promotes product" edge in the Product↔Creator
+relation graph.  A single relation type (PROMOTES) is used for both
+directions of the query (product→creators via R7, creator→products via R8).
+
+Design rules (mirrors CommerceListing / CommerceCreator):
+- ``creator`` and ``listing`` hold the universal commerce entities.
+- ``metrics`` carries ONLY the per-pair attributed metrics (units_sold and
+  gmv attributed to THIS creator for THIS product specifically), NOT the
+  creator's all-product totals or the product's all-creator totals.
+- ``entity_scope=LISTING`` is used for attributed sales/gmv metrics on a
+  listing; ``entity_scope=CREATOR`` is used for creator-scoped metrics.
+- ``provenance`` records which provider supplied this relation edge.
+
+Source semantics (carried transparently from the channel layer):
+- R7 (/product/v1/creatorList): snapshot relation, no ``window_days``.
+- R8 (/creator/v1/productList): rolling ``window_days`` ∈ {0,7,14,28,90}.
+  ``window_days=None`` means the channel layer did not supply a window
+  (snapshot or unknown).
+"""
+
+from __future__ import annotations
+
+from keble_data_infra_contract.models.base import ContractModel
+
+from typing import Literal
+
+from pydantic import Field
+
+from keble_data_infra_contract.models.creator import CommerceCreator
+from keble_data_infra_contract.models.listing import CommerceListing
+from keble_data_infra_contract.models.metric import MetricObservation
+from keble_data_infra_contract.models.provenance import Provenance
+
+
+class CreatorProductLink(ContractModel):
+    """A creator↔product promotion relation with attributed metrics.
+
+    ``relation`` is always "PROMOTES" (the only currently verified relation
+    type; other types may be introduced in later phases without breaking this
+    model since it is typed as a Literal).
+    ``metrics`` contains attributed MetricObservation objects only (units_sold
+    and gmv for this specific pair).
+    ``window_days`` is the original R8 ``days`` parameter; None for R7 snapshots.
+    Provider-specific link attribution that lacks a normalized representation
+    stays inside the provider package and is not exposed as an escape hatch.
+    """
+
+
+    creator: CommerceCreator
+    listing: CommerceListing
+    relation: Literal["PROMOTES"] = "PROMOTES"
+    metrics: list[MetricObservation] = Field(default_factory=list)
+    window_days: int | None = None
+    provenance: Provenance | None = None

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/models/identity.py

@@ -0,0 +1,121 @@
+"""Universal identity types for the Commerce layer.
+
+ProviderId   — validated string key for a data provider (open set: fastmoss, echotik, …).
+Channel      — closed enum of buyer-facing commerce channels (TikTok, Amazon, Shopify).
+ExternalIdentity — provider-native identity tuple for a commerce entity.
+
+Design rules:
+- Channel is a closed enum: channels are structurally significant cross-channel keys.
+- ProviderId is an open RootModel[str]: new providers do not require an enum change.
+- ExternalIdentity.identity_key() is deterministic — equal inputs always produce
+  the same string, making it safe to use as a deduplication / merge key.
+"""
+
+from __future__ import annotations
+
+from keble_data_infra_contract.models.base import ContractModel
+
+from enum import Enum
+
+from pydantic import Field, RootModel, field_validator
+from keble_helpers.typings import PydanticModelConfig
+
+
+# ---------------------------------------------------------------------------
+# ProviderId
+# ---------------------------------------------------------------------------
+
+
+class ProviderId(RootModel[str]):
+    """Validated string identity for a commerce data provider.
+
+    Rules: lowercase letters, digits, and underscores only.
+    The set of providers is open — new providers do not need an enum change.
+    """
+
+    model_config = PydanticModelConfig.default(frozen=True)
+
+    @field_validator("root")
+    @classmethod
+    def _validate(cls, value: str) -> str:
+        normalized = value.strip().lower()
+        if not normalized or not normalized.replace("_", "").isalnum():
+            raise ValueError(
+                "ProviderId must contain only lowercase letters, digits, or underscores"
+            )
+        return normalized
+
+    def __str__(self) -> str:
+        return self.root
+
+    def __repr__(self) -> str:
+        return f"ProviderId({self.root!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, ProviderId):
+            return self.root == other.root
+        if isinstance(other, str):
+            return self.root == other
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.root)
+
+
+# Well-known provider constants — the set remains open for extension.
+PROVIDER_FASTMOSS = ProviderId("fastmoss")
+PROVIDER_ECHOTIK = ProviderId("echotik")
+PROVIDER_KEEPA = ProviderId("keepa")
+
+
+# ---------------------------------------------------------------------------
+# Channel
+# ---------------------------------------------------------------------------
+
+
+class Channel(str, Enum):
+    """Closed enum of buyer-facing commerce channels.
+
+    Channels are structural keys in the Universal model (e.g., routing,
+    cross-channel deduplication), so they must be enumerated and compile-time
+    checkable — unlike providers, which are open.
+    """
+
+    TIKTOK = "tiktok"
+    AMAZON = "amazon"
+    SHOPIFY = "shopify"
+
+
+# ---------------------------------------------------------------------------
+# ExternalIdentity
+# ---------------------------------------------------------------------------
+
+
+class ExternalIdentity(ContractModel):
+    """Provider-native identity for a single commerce entity.
+
+    The four-tuple (provider, namespace, value, sorted scope) forms a stable,
+    deterministic key used for deduplication and merge operations.
+
+    Rules:
+    - ``value`` must be the actual external ID string — never a derived or
+      fabricated value.
+    - ``namespace`` distinguishes identity types within a provider
+      (e.g., "tiktok_product_id" vs "tiktok_seller_id").
+    - ``scope`` captures contextual qualifiers such as region; it is optional
+      but must not be used to carry business metrics.
+    """
+
+
+    provider: ProviderId
+    namespace: str
+    value: str
+    scope: dict[str, str] = Field(default_factory=dict)
+
+    def identity_key(self) -> str:
+        """Stable, deterministic key from all four components.
+
+        Suitable for use as a deduplication or merge key across sources.
+        """
+        sorted_scope = "|".join(f"{k}={v}" for k, v in sorted(self.scope.items()))
+        return f"{self.provider}:{self.namespace}:{self.value}:{sorted_scope}"

keble_data_infra_contract-0.1.0/src/keble_data_infra_contract/models/listing.py

@@ -0,0 +1,57 @@
+"""CommerceListing — universal channel listing entity.
+
+A CommerceListing is a product as it appears in a specific channel and market.
+It is the primary cross-channel unit of comparison.
+
+Design rules (§4.3):
+- Provider-native details remain inside the provider package and do not cross
+  the normalized public contract.
+- ``metrics`` is a list of MetricObservation, not a KV bag.
+- ``identities`` preserves the provider-native ID alongside the channel
+  product ID for deduplication and provenance.
+"""
+
+from __future__ import annotations
+
+from keble_data_infra_contract.models.base import ContractModel
+
+from pydantic import Field
+
+from keble_data_infra_contract.models.identity import Channel, ExternalIdentity
+from keble_data_infra_contract.models.metric import MetricObservation
+from keble_data_infra_contract.models.offer import CommerceOffer
+from keble_data_infra_contract.models.provenance import Provenance
+
+
+class CommerceListing(ContractModel):
+    """A product listed on a specific commerce channel in a specific market.
+
+    FastMoss / TikTok mapping (first chain):
+        channel            ← Channel.TIKTOK
+        market             ← item.region  (e.g., "US")
+        channel_product_id ← item.tiktok_product_id
+        identities         ← [ExternalIdentity(provider=fastmoss, …)]
+        store_ref          ← item.seller_id (as string)
+        offer              ← CommerceOffer(current_price=Money(…))
+        metrics            ← [MetricObservation(sales_quantity, D7, …), …]
+        provenance         ← Provenance(provider=fastmoss, captured_at=…)
+    """
+
+
+    channel: Channel
+    market: str | None = None
+    channel_product_id: str
+    # Universal display fields (Phase A). Cross-channel stable semantics only:
+    #   title             ← FastMoss item.title / EchoTik product_name / Keepa title
+    #   primary_image_url ← FastMoss item.cover / EchoTik cover_url / Keepa main image
+    # A provider that does not return them leaves them None (honest absence —
+    # e.g. EchoTik product/ranklist has no cover field). The URL is carried
+    # as-is: it may be a CDN link that expires upstream; it is never rewritten
+    # or fabricated. Channel-specific media fields stay in channel_details.
+    title: str | None = None
+    primary_image_url: str | None = None
+    identities: list[ExternalIdentity] = Field(default_factory=list)
+    store_ref: str | None = None
+    offer: CommerceOffer | None = None
+    metrics: list[MetricObservation] = Field(default_factory=list)
+    provenance: Provenance | None = None