<?php

namespace App\Contracts;

use App\Exceptions\PlatformNotImplementedException;
use App\Models\AdCopy;
use App\Models\Campaign;
use App\Models\Creative;

interface PlatformAdapter
{
    /**
     * Create the campaign on the platform and return the platform's external campaign id.
     *
     * @throws PlatformNotImplementedException if this platform isn't wired up yet.
     */
    public function createCampaign(Campaign $campaign): string;

    /**
     * Attach a creative (and optional ad copy) to an already-created platform campaign,
     * returning the platform's external ad reference id.
     */
    public function attachCreative(Campaign $campaign, Creative $creative, ?AdCopy $adCopy = null): string;

    /**
     * Start the campaign on the platform.
     *
     * Called publish() and described as "publish/activate", which is the
     * conflation this product has just stopped making: createCampaign() above
     * builds everything paused, and this is the separate, separately approved act
     * of letting it spend. One verb covering both is how LinkedIn came to go live
     * as a side effect of publishing.
     */
    public function activate(Campaign $campaign): void;
}