@spec add_customer(ExPlain.Client.t(), map()) ::
  {:ok, :added} | {:error, ExPlain.Error.t()}

Adds a customer to one or more tenants.

The input map must include :customer_identifier and :tenant_identifiers.

@spec get_by_id(ExPlain.Client.t(), String.t()) ::
  {:ok, ExPlain.Tenants.Tenant.t() | nil} | {:error, ExPlain.Error.t()}

Fetches a tenant by its Plain ID. Returns {:ok, nil} if not found.

@spec list(
  ExPlain.Client.t(),
  keyword()
) ::
  {:ok, %{nodes: [ExPlain.Tenants.Tenant.t()], page_info: ExPlain.PageInfo.t()}}
  | {:error, ExPlain.Error.t()}

Returns a paginated list of tenants.

@spec remove_customer(ExPlain.Client.t(), map()) ::
  {:ok, :removed} | {:error, ExPlain.Error.t()}

Removes a customer from one or more tenants.

The input map must include :customer_identifier and :tenant_identifiers.

@spec search(ExPlain.Client.t(), map(), keyword()) ::
  {:ok, %{nodes: [ExPlain.Tenants.Tenant.t()], page_info: ExPlain.PageInfo.t()}}
  | {:error, ExPlain.Error.t()}

Searches tenants by name or external ID.

The search_query map must include :name or :external_id.

@spec set_customer_tenants(ExPlain.Client.t(), map()) ::
  {:ok, :set} | {:error, ExPlain.Error.t()}

Sets the exact list of tenants a customer belongs to, replacing any existing memberships.

The input map must include :customer_identifier and :tenant_identifiers.

@spec update_tier(ExPlain.Client.t(), map()) ::
  {:ok, map()} | {:error, ExPlain.Error.t()}

Updates the tier associated with a tenant.

The input map must include :tenant_identifier and :tier_identifier.

@spec upsert(ExPlain.Client.t(), map()) ::
  {:ok, ExPlain.Tenants.Tenant.t()} | {:error, ExPlain.Error.t()}

Creates or updates a tenant.

The input map must include :external_id and :name.