mirror of
https://github.com/hanzo-cpp/sdk.git
synced 2026-11-20 19:55:32 +00:00
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.
182 lines
12 KiB
C++
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's org and answers 204 with no body.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Removes one campaign of the caller'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's server-minted handle, \"cmp_\"-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's campaigns, newest first, optionally narrowed to one status.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns the org'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'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(""))</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'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'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's server-minted handle, \"cmp_\"-prefixed.</param>
|
|
pplx::task<std::shared_ptr<CampaignRecord>> getCampaignById(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Returns a campaign's results over a window: the analytics funnel (impressions, clicks, conversions, revenue, visitors), the spend each channel's connector reports, and the derived growth KPIs — CTR, CVR, CAC and ROAS.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Returns a campaign's results over a window: the analytics funnel (impressions, clicks, conversions, revenue, visitors), the spend each channel'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's utm_campaign-tagged events, and the spend is each provider's own number read through the org'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(""))</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(""))</param>
|
|
/// <param name="end">End is an explicit RFC3339 window end. (optional, default to utility::conversions::to_string_t(""))</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'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'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's honest capability, not a wish: a kind missing from it is one a launch will record as \"unavailable\" 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 \"pending\" 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 \"paid\" channel would mean two ad accounts running one campaign with no way to tell their results apart. The new channel starts \"pending\" — 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'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 `live`, `failed` or `unavailable` status and detail, and a paid launch can be live while an email launch failed. The campaign itself is `live` when AT LEAST ONE channel launched and `failed` only when none did — `live` 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 `utm_content`. Org-scoped and fails closed: a valid bearer is required (403 without one), the campaign is read under the caller's OWN org so another tenant'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's connector token from the org passed to it, so a launch can never spend through another tenant'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 `paused`, 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 `unavailable` and one whose pause errored is marked `failed`, with the reason on the row. The campaign still reports `paused` 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's OWN org, so another tenant's id is a 404.
|
|
/// </remarks>
|
|
/// <param name="id"></param>
|
|
pplx::task<void> postCampaignByIdPause(
|
|
utility::string_t id
|
|
) const;
|
|
/// <summary>
|
|
/// Rewrites a campaign's core fields — name, audience, creatives, schedule and budget — and returns the updated campaign.
|
|
/// </summary>
|
|
/// <remarks>
|
|
/// Rewrites a campaign'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_ */
|
|
|