<?php
namespace boru\ai\Asset;

interface AssetStoreInterface
{
    /**
     * Persist or update the core asset record.
     *
     * @param Asset $asset
     * @return Asset
     */
    public function saveAsset(Asset $asset);

    /**
     * Retrieve a core asset by its library id.
     *
     * @param string $assetId
     * @return Asset|false
     */
    public function loadAsset($assetId);

    /**
     * Optionally find an asset by a stable hash.
     *
     * @param string $sha256
     * @return Asset|false
     */
    public function findAssetBySha256($sha256);

    /**
     * Persist or update a provider-specific asset binding.
     *
     * @param ProviderAssetBinding $binding
     * @return ProviderAssetBinding
     */
    public function saveBinding(ProviderAssetBinding $binding);

    /**
     * Find a binding for one asset/provider pair, optionally constrained by purpose.
     *
     * @param string $assetId
     * @param string $provider
     * @param string|null $purpose
     * @return ProviderAssetBinding|false
     */
    public function findBinding($assetId, $provider, $purpose = null);

    /**
     * Return all bindings for an asset.
     *
     * @param string $assetId
     * @return ProviderAssetBinding[]
     */
    public function listBindings($assetId);
}
