Files
zeekay 189ce08e51 Regenerate against the document the deployment answers for
The projection these were generated from was a month old and predated the
compute migration, so every one of them described /v1/visor — which the API
serves at zero paths now. That is why a hand-written console client and a
generated one had drifted the same way at the same time.

No /v1/visor path survives here. The word still appears as a source-plane
value and inside gvisor and supervisor, which are not this rename.
2026-09-05 18:07:13 -07:00

182 lines
12 KiB
C++

/**
* Hanzo Cloud API
* The Hanzo Cloud API as a customer calls it: every operation under /v1/ except the operator's admin product, relay routes, legacy spellings and capabilities still reached by flag. Tagged by product: the first path segment after /v1/.
*
* The version of the OpenAPI document: v1
*
* NOTE: This class is auto generated by OpenAPI-Generator 7.14.0.
* https://openapi-generator.tech
* Do not edit the class manually.
*/
/*
* CampaignApi.h
*
*
*/
#ifndef HANZO_API_CampaignApi_H_
#define HANZO_API_CampaignApi_H_
#include "hanzo/ApiClient.h"
#include "hanzo/model/CampaignPage.h"
#include "hanzo/model/CampaignRecord.h"
#include "hanzo/model/CampaignResults.h"
#include "hanzo/model/CampaignSummary.h"
#include "hanzo/model/CampaignUpdate.h"
#include "hanzo/model/CampaignWrite.h"
#include "hanzo/model/ChannelAdd.h"
#include <cpprest/details/basic_types.h>
#include <boost/optional.hpp>
namespace hanzo {
namespace api {
using namespace hanzo::model;
class CampaignApi
{
public:
explicit CampaignApi( std::shared_ptr<const ApiClient> apiClient );
virtual ~CampaignApi();
/// <summary>
/// Removes one campaign of the caller&#39;s org and answers 204 with no body.
/// </summary>
/// <remarks>
/// Removes one campaign of the caller&#39;s org and answers 204 with no body. 404 when the org has no campaign with that id. It deletes the RECORD, not the executions: a campaign whose channels are live on a provider should be paused first, or those executions keep running with nothing here to report them.
/// </remarks>
/// <param name="id">ID is the campaign&#39;s server-minted handle, \&quot;cmp_\&quot;-prefixed.</param>
pplx::task<void> deleteCampaignById(
utility::string_t id
) const;
/// <summary>
/// Drops one channel from a campaign and returns the updated campaign.
/// </summary>
/// <remarks>
/// Drops one channel from a campaign and returns the updated campaign. 404 when the campaign carries no channel of that kind. It removes the channel from the PLAN. A channel that is live at its provider should be paused first — dropping the row here leaves nothing to pause it with afterwards.
/// </remarks>
/// <param name="id">ID is the campaign, from the path.</param>
/// <param name="kind">Kind is the channel to remove: paid, organic or email.</param>
pplx::task<std::shared_ptr<CampaignRecord>> deleteCampaignByIdChannelsByKind(
utility::string_t id,
utility::string_t kind
) const;
/// <summary>
/// Returns the org&#39;s campaigns, newest first, optionally narrowed to one status.
/// </summary>
/// <remarks>
/// Returns the org&#39;s campaigns, newest first, optionally narrowed to one status. A campaign is the top-level go-to-market object: a value that SPANS channels (paid, organic, email) and fans out to the executor for each. The listing is org-scoped server-side, so one org can never see another&#39;s campaigns.
/// </remarks>
/// <param name="status">Status keeps only campaigns in that state: draft, live, paused or failed. Empty means any. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="limit">Limit bounds the page. 0 or less means the default of 200; anything above 1000 is clamped to 1000. (optional, default to 0L)</param>
pplx::task<std::shared_ptr<CampaignPage>> getCampaign(
boost::optional<utility::string_t> status,
boost::optional<int64_t> limit
) const;
/// <summary>
/// Returns one campaign of the caller&#39;s org — its name, audience, creatives, channels with their per-channel launch state, schedule, budget and status.
/// </summary>
/// <remarks>
/// Returns one campaign of the caller&#39;s org — its name, audience, creatives, channels with their per-channel launch state, schedule, budget and status. 404 when the org has no campaign with that id.
/// </remarks>
/// <param name="id">ID is the campaign&#39;s server-minted handle, \&quot;cmp_\&quot;-prefixed.</param>
pplx::task<std::shared_ptr<CampaignRecord>> getCampaignById(
utility::string_t id
) const;
/// <summary>
/// Returns a campaign&#39;s results over a window: the analytics funnel (impressions, clicks, conversions, revenue, visitors), the spend each channel&#39;s connector reports, and the derived growth KPIs — CTR, CVR, CAC and ROAS.
/// </summary>
/// <remarks>
/// Returns a campaign&#39;s results over a window: the analytics funnel (impressions, clicks, conversions, revenue, visitors), the spend each channel&#39;s connector reports, and the derived growth KPIs — CTR, CVR, CAC and ROAS. There is exactly ONE metrics plane and nothing is stored here: the funnel is an analytics query over the campaign&#39;s utm_campaign-tagged events, and the spend is each provider&#39;s own number read through the org&#39;s connector. A warehouse that is not emitting yet degrades to available:false with zeroes — honest-empty, never a 500 and never a fabricated number. When the campaign runs more than one creative and an experiment is wired, abTest carries the A/B analysis.
/// </remarks>
/// <param name="id">ID is the campaign to report on, from the path.</param>
/// <param name="range">Range is the lookback window: 24h, 7d, 30d or 90d. Anything else, including empty, reads as 30d. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="start">Start is an explicit RFC3339 window start. Honored only together with End, and only when End is after it. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
/// <param name="end">End is an explicit RFC3339 window end. (optional, default to utility::conversions::to_string_t(&quot;&quot;))</param>
pplx::task<std::shared_ptr<CampaignResults>> getCampaignByIdMetrics(
utility::string_t id,
boost::optional<utility::string_t> range,
boost::optional<utility::string_t> start,
boost::optional<utility::string_t> end
) const;
/// <summary>
/// Returns the org&#39;s go-to-market roll-up: how many campaigns exist, how many are live, their total budget in cents, and which channel executors this deployment can actually reach.
/// </summary>
/// <remarks>
/// Returns the org&#39;s go-to-market roll-up: how many campaigns exist, how many are live, their total budget in cents, and which channel executors this deployment can actually reach. The channel list is the deployment&#39;s honest capability, not a wish: a kind missing from it is one a launch will record as \&quot;unavailable\&quot; rather than fail on.
/// </remarks>
pplx::task<std::shared_ptr<CampaignSummary>> getCampaignSummary(
) const;
/// <summary>
/// Creates a campaign as a DRAFT and returns it.
/// </summary>
/// <remarks>
/// Creates a campaign as a DRAFT and returns it. A draft is inert: nothing is sent, no connector is touched and no budget is committed until the campaign is launched. The channels named here are validated and de-duplicated by kind (one executor per kind), and every channel starts \&quot;pending\&quot; whatever the caller claims — a client can never assert a launched state.
/// </remarks>
/// <param name="campaignWrite"></param>
pplx::task<std::shared_ptr<CampaignRecord>> postCampaign(
std::shared_ptr<CampaignWrite> campaignWrite
) const;
/// <summary>
/// Adds a channel to a campaign, or REPLACES the one it already has of that kind, and returns the updated campaign.
/// </summary>
/// <remarks>
/// Adds a channel to a campaign, or REPLACES the one it already has of that kind, and returns the updated campaign. A campaign carries at most one channel per kind, because the kind IS the executor: adding a second \&quot;paid\&quot; channel would mean two ad accounts running one campaign with no way to tell their results apart. The new channel starts \&quot;pending\&quot; — adding it does not launch it.
/// </remarks>
/// <param name="id">ID is the campaign to add the channel to, from the path.</param>
/// <param name="channelAdd"></param>
pplx::task<std::shared_ptr<CampaignRecord>> postCampaignByIdChannels(
utility::string_t id,
std::shared_ptr<ChannelAdd> channelAdd
) const;
/// <summary>
/// Launch a campaign across every channel it declares
/// </summary>
/// <remarks>
/// Pushes the campaign live on each of its channels through that channel&#39;s executor and answers the whole campaign with the per-channel outcome written back onto it. The fan-out is BEST-EFFORT PER CHANNEL, and the honest reading of the result is the rule most callers get wrong: one channel failing never aborts the others, so each channel row carries its own &#x60;live&#x60;, &#x60;failed&#x60; or &#x60;unavailable&#x60; status and detail, and a paid launch can be live while an email launch failed. The campaign itself is &#x60;live&#x60; when AT LEAST ONE channel launched and &#x60;failed&#x60; only when none did — &#x60;live&#x60; is not a claim that every channel launched. Repeating the call is safe: a channel already live is skipped, never re-launched. A campaign carrying more than one creative has its variant assigned here by the experiment client and tagged as &#x60;utm_content&#x60;. Org-scoped and fails closed: a valid bearer is required (403 without one), the campaign is read under the caller&#39;s OWN org so another tenant&#39;s id is a 404, and a campaign with no channels is a 400 — there is nothing to launch. Each executor resolves its own org&#39;s connector token from the org passed to it, so a launch can never spend through another tenant&#39;s connector.
/// </remarks>
/// <param name="id"></param>
pplx::task<void> postCampaignByIdLaunch(
utility::string_t id
) const;
/// <summary>
/// Pause every live channel on a campaign at its provider
/// </summary>
/// <remarks>
/// Pauses each live channel on its provider and answers the whole campaign, moved to &#x60;paused&#x60;, with the per-channel outcome written back onto it. Only channels that are live and carry a provider reference are touched; a channel whose executor is no longer wired is marked &#x60;unavailable&#x60; and one whose pause errored is marked &#x60;failed&#x60;, with the reason on the row. The campaign still reports &#x60;paused&#x60; in both cases, and that is deliberate rather than sloppy: no live channel remains that this process will meter, and the rows say exactly which provider was not reached so it can be settled by hand. Org-scoped and fails closed: a valid bearer is required (403 without one) and the campaign is read under the caller&#39;s OWN org, so another tenant&#39;s id is a 404.
/// </remarks>
/// <param name="id"></param>
pplx::task<void> postCampaignByIdPause(
utility::string_t id
) const;
/// <summary>
/// Rewrites a campaign&#39;s core fields — name, audience, creatives, schedule and budget — and returns the updated campaign.
/// </summary>
/// <remarks>
/// Rewrites a campaign&#39;s core fields — name, audience, creatives, schedule and budget — and returns the updated campaign. Channels are replaced ONLY while the campaign is still a draft. Once it is launched its channels carry provider state (an external id, a live status), so they are added and removed explicitly through the channels sub-resource instead; a whole-object write would silently orphan a running execution.
/// </remarks>
/// <param name="id">ID is the campaign to update, from the path.</param>
/// <param name="campaignUpdate"></param>
pplx::task<std::shared_ptr<CampaignRecord>> putCampaignById(
utility::string_t id,
std::shared_ptr<CampaignUpdate> campaignUpdate
) const;
protected:
std::shared_ptr<const ApiClient> m_ApiClient;
};
}
}
#endif /* HANZO_API_CampaignApi_H_ */