@spec create(
  map(),
  keyword()
) ::
  {:ok, PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t())}

Creates a supplier-info row.

When the item has no primary supplier yet, the newly linked row is auto-promoted to primary (an item with suppliers but no primary is a valid state only when the user explicitly demotes it).

@spec delete(
  PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t(),
  keyword()
) ::
  {:ok, PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t())}

Deletes a supplier-info row.

@spec get(Ecto.UUID.t()) :: PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t() | nil

Fetches a supplier-info row by UUID. Returns nil if not found.

@spec history_for_pair(Ecto.UUID.t(), Ecto.UUID.t()) :: [
  PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()
]

Returns all rows for an item/supplier pair ordered newest-first.

Includes both current (valid_to: nil) and closed rows so callers can display a full price revision history. Ordered by valid_from descending (nulls last), then inserted_at descending.

@spec list_for_item(Ecto.UUID.t()) :: [
  PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()
]

Lists current supplier-info rows for an item, ordered by position then inserted_at.

A row is current when valid_to is nil. Closed rows (produced by revise_unit_cost/3) are excluded; use history_for_pair/2 to retrieve the full history for a specific item/supplier pair.

@spec primary_for_item(Ecto.UUID.t()) ::
  PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t() | nil

Returns the current primary supplier-info row for an item, or nil if none is marked primary.

Only current rows (valid_to: nil) are considered — closed revision rows carry is_primary: false by construction and are excluded.

@spec revise_unit_cost(
  PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t(),
  Decimal.t(),
  keyword()
) ::
  {:ok, PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()}
  | {:error, :not_current | Ecto.Changeset.t()}

Closes the current junction row and inserts a successor with the new unit cost, creating an append-only price revision history.

Guards

• {:error, :not_current} — info.valid_to is not nil; only the current row can be revised.
• {:ok, info} (no-op) — new_cost equals info.unit_cost (or both effectively zero when unit_cost is nil), and opts[:currency] is either absent or matches the row's current currency. A currency-only change (same cost, different :currency) still creates a revision.

Transaction

Within a single Ecto.Multi transaction:

1. The current row is closed: valid_to is set to today and is_primary is forced to false via force_change/3, freeing the partial-unique index inside the tx so the successor can inherit the primary flag.
2. A successor row is inserted copying item_uuid, supplier_uuid, supplier_source, supplier_name_snapshot, supplier_sku, currency, lead_time_days, min_order_qty, position, and metadata from the closed row. unit_cost is set to new_cost; valid_from is today; valid_to is nil; is_primary inherits the original row's value.

Options

• :actor_uuid — UUID of the user performing the revision (persisted in the activity log).
• :source — free-form source label (e.g. "goods_receipt").
• :source_uuid — UUID of the originating resource (e.g. receipt UUID).
• :currency — when provided and different from the row's currency, the successor stores the new currency; both old and new currencies are recorded in the activity metadata.

Currency awareness

The successor always keeps the row's own currency unless opts[:currency] is given and differs, in which case the new currency is stored and the activity log captures both.

@spec set_primary(
  PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t(),
  keyword()
) :: {:ok, PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()} | {:error, any()}

Promotes a supplier-info row to primary for its item.

Runs in a transaction: clears is_primary on all sibling rows first, then sets is_primary: true on the target. Respects the partial unique index — concurrent callers produce a constraint violation rather than double-marking.

@spec update(PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t(), map(), keyword()) ::
  {:ok, PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t()}
  | {:error, Ecto.Changeset.t(PhoenixKitCatalogue.Schemas.ItemSupplierInfo.t())}

Updates a supplier-info row.