feat(ads): support a second ad network

README.md

@@ -114,7 +114,7 @@ long failed = client.posts().stream(PostListParams.create().workspaceId(workspac
 | `knowledge()`   | `list`, `create`, `createText`, `createUrl`, `createFile`, `update`, `delete`, `sync`, `search`                                                                                                |
 | `ads()`         | `list`, `external`, `boostable`, `connections`, `sources`, `authorizeMeta`, `deleteConnection`, `boost`, `create`, `refresh`, `setStatus`, `delete`, `accountTree`, `createCampaign`, `campaign`, `updateCampaign`, `deleteCampaign`, `duplicateCampaign`, `createAdSet`, `adSet`, `updateAdSet`, `deleteAdSet`, `duplicateAdSet`, `createNetworkAd`, `networkAd`, `updateNetworkAd`, `deleteNetworkAd`, `duplicateNetworkAd`, `bulkSetStatus`, `creatives`, `createCreative`, `creative`, `deleteCreative`, `estimateReach`, `insights`, `adInsights`, `audiences`, `createAudience`, `audience`, `updateAudience`, `deleteAudience`, `addAudienceUsers`, `searchTargeting`, `leadForms`, `createLeadForm`, `leadForm`, `archiveLeadForm`, `leads`, `leadsFeed`, `leadPages`, `subscribeLeadPage`, `unsubscribeLeadPage`, `goals`, `catalogs`, `createCatalog`, `catalog`, `updateCatalog`, `deleteCatalog`, `catalogProducts`, `writeCatalogProducts`, `productFeeds`, `createProductFeed`, `deleteProductFeed`, `feedUploads`, `startFeedUpload`, `productSets`, `createProductSet`, `updateProductSet`, `deleteProductSet`, `reachFrequency`, `createReachFrequency`, `reachFrequencyPrediction`, `reserveReachFrequency`, `cancelReachFrequency`, `library`, `partnershipCreators`, `requestPartnership`, `revokePartnership`, `accountActivity`, `labels`, `createLabel`, `updateLabel`, `deleteLabel`, `applyLabel`, `studies`, `createStudy`, `study`, `deleteStudy`, `iosCampaignLimits`, `highDemandPeriods`, `createHighDemandPeriod`, `deleteHighDemandPeriod`, `valueRuleSets`, `createValueRuleSet`, `deleteValueRuleSet` |
 | `inbox()`       | `list`, `threads`, `conversations`, `unreadCount`, `accounts`, `platforms`, `markThreadRead`, `markConversationRead`, `refresh`, `update`, `editComment`, `reply`, `hide`, `unhide`, `delete`, `like`, `unlike`, `pin`, `unpin`, `react`, `startConversation`, `setTyping`, `listApprovals`, `approveReply`, `rejectReply` |
-| `ads()`         | `list`, `external`, `boostable`, `connections`, `sources`, `authorizeMeta`, `deleteConnection`, `boost`, `create`, `refresh`, `setStatus`, `delete`, `accountTree`, `createCampaign`, `campaign`, `updateCampaign`, `deleteCampaign`, `duplicateCampaign`, `createAdSet`, `adSet`, `updateAdSet`, `deleteAdSet`, `duplicateAdSet`, `createNetworkAd`, `networkAd`, `updateNetworkAd`, `deleteNetworkAd`, `duplicateNetworkAd`, `bulkSetStatus`, `creatives`, `createCreative`, `creative`, `deleteCreative`, `estimateReach`, `insights`, `adInsights`, `audiences`, `createAudience`, `audience`, `updateAudience`, `deleteAudience`, `addAudienceUsers`, `searchTargeting`, `leadForms`, `createLeadForm`, `leadForm`, `archiveLeadForm`, `leads`, `leadsFeed`, `leadPages`, `subscribeLeadPage`, `unsubscribeLeadPage` |
+| `ads()`         | `list`, `external`, `boostable`, `connections`, `sources`, `providers`, `authorize`, `deleteConnection`, `boost`, `create`, `refresh`, `setStatus`, `delete`, `accountTree`, `createCampaign`, `campaign`, `updateCampaign`, `deleteCampaign`, `duplicateCampaign`, `createAdSet`, `adSet`, `updateAdSet`, `deleteAdSet`, `duplicateAdSet`, `createNetworkAd`, `networkAd`, `updateNetworkAd`, `deleteNetworkAd`, `duplicateNetworkAd`, `bulkSetStatus`, `creatives`, `createCreative`, `creative`, `deleteCreative`, `estimateReach`, `insights`, `adInsights`, `audiences`, `createAudience`, `audience`, `updateAudience`, `deleteAudience`, `addAudienceUsers`, `addAudienceCompanies`, `searchTargeting`, `leadForms`, `createLeadForm`, `leadForm`, `archiveLeadForm`, `leads`, `leadsFeed`, `leadPages`, `subscribeLeadPage`, `unsubscribeLeadPage`, `bidPricing`, `supplyForecast`, `conversionRules`, `createConversionRule`, `conversionRule`, `updateConversionRule`, `deleteConversionRule`, `attachConversionRule`, `detachConversionRule`, `conversionMetrics`, `sendConversionEvents` |
 | `googleBusiness()` | `getLocation`, `updateLocation`, `getAttributes`, `updateAttributes`, `getMenus`, `replaceMenus`, `getServices`, `replaceServices`, `listMedia`, `addMedia`, `deleteMedia`, `listPlaceActions`, `createPlaceAction`, `updatePlaceAction`, `deletePlaceAction`, `getVerificationOptions`, `startVerification`, `completeVerification`, `getPerformance`, `getSearchKeywords`, `assign` |
 | `validate()`    | `post`, `length`, `media`                                                                                                                                                                   |
 | `activity()`    | `list`                                                                                                                                                                                      |

src/main/java/com/fopost/sdk/model/AdProvider.java

@@ -0,0 +1,21 @@
+package com.fopost.sdk.model;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * An ad network from the API's registry. {@code configured} false cannot be connected yet.
+ *
+ * <p>{@code capabilities} says what the network supports — campaigns, audiences, conversions,
+ * forecasts, adLibrary and so on. {@code targetingFacets} is what {@code searchTargeting} accepts
+ * here, and {@code trackingMacros} what the network expands in a creative's tracking parameters.
+ */
+public record AdProvider(
+        String id,
+        String name,
+        String logo,
+        Boolean configured,
+        List<String> connectMethods,
+        Map<String, Boolean> capabilities,
+        List<String> targetingFacets,
+        List<AdTrackingMacro> trackingMacros) {}

src/main/java/com/fopost/sdk/model/AdTrackingMacro.java

@@ -0,0 +1,4 @@
+package com.fopost.sdk.model;
+
+/** A token a network expands in a link's tracking parameters at delivery time. */
+public record AdTrackingMacro(String token, String description) {}

src/main/java/com/fopost/sdk/model/BidPricing.java

@@ -0,0 +1,9 @@
+package com.fopost.sdk.model;
+
+/** What the auction costs, in minor units of the ad account currency. */
+public record BidPricing(
+        String currency,
+        Long suggestedBidMinor,
+        Long minBidMinor,
+        Long maxBidMinor,
+        Long dailyBudgetFloorMinor) {}

src/main/java/com/fopost/sdk/model/ConversionMetrics.java

@@ -0,0 +1,9 @@
+package com.fopost.sdk.model;
+
+/** What a conversion rule recorded over a date range. */
+public record ConversionMetrics(
+        Integer conversions,
+        Integer postClickConversions,
+        Integer viewThroughConversions,
+        Long valueMinor,
+        Long costPerConversionMinor) {}

src/main/java/com/fopost/sdk/model/ConversionRule.java

@@ -0,0 +1,21 @@
+package com.fopost.sdk.model;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import java.util.List;
+
+/**
+ * How the network attributes a sale or a sign-up back to an ad set. {@code campaignIds} are the ad
+ * sets this rule is attached to.
+ */
+public record ConversionRule(
+        String id,
+        String name,
+        @JsonProperty("type") String conversionType,
+        String attribution,
+        Integer postClickWindowDays,
+        Integer viewThroughWindowDays,
+        Long valueMinor,
+        String currency,
+        Boolean enabled,
+        String createdAt,
+        List<String> campaignIds) {}

src/main/java/com/fopost/sdk/model/SupplyForecast.java

@@ -0,0 +1,13 @@
+package com.fopost.sdk.model;
+
+/**
+ * What an audience would deliver at a budget, over the network's own window. {@code ready} is
+ * false while the network has no answer for that audience.
+ */
+public record SupplyForecast(
+        String currency,
+        Long impressions,
+        Long clicks,
+        Long spendMinor,
+        Long windowDays,
+        Boolean ready) {}

src/main/java/com/fopost/sdk/param/AdCompanyParams.java

@@ -0,0 +1,59 @@
+package com.fopost.sdk.param;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * One row of a company-list upload. At least one of name, domain, page url or ticker is required;
+ * the rows travel with the request and are never stored.
+ */
+public final class AdCompanyParams {
+
+    private final Map<String, Object> body = new LinkedHashMap<>();
+
+    private AdCompanyParams() {}
+
+    public static AdCompanyParams named(String name) {
+        AdCompanyParams params = new AdCompanyParams();
+        params.body.put("name", name);
+        return params;
+    }
+
+    public static AdCompanyParams domain(String domain) {
+        AdCompanyParams params = new AdCompanyParams();
+        params.body.put("domain", domain);
+        return params;
+    }
+
+    /** The company's page on the network. */
+    public static AdCompanyParams pageUrl(String pageUrl) {
+        AdCompanyParams params = new AdCompanyParams();
+        params.body.put("pageUrl", pageUrl);
+        return params;
+    }
+
+    public AdCompanyParams withName(String name) {
+        body.put("name", name);
+        return this;
+    }
+
+    public AdCompanyParams withDomain(String domain) {
+        body.put("domain", domain);
+        return this;
+    }
+
+    /** Stock ticker, where the network matches on one. */
+    public AdCompanyParams withTicker(String ticker) {
+        body.put("ticker", ticker);
+        return this;
+    }
+
+    public AdCompanyParams withCountry(String country) {
+        body.put("country", country);
+        return this;
+    }
+
+    public Map<String, Object> toMap() {
+        return new LinkedHashMap<>(body);
+    }
+}

src/main/java/com/fopost/sdk/param/AdForecastParams.java

@@ -0,0 +1,53 @@
+package com.fopost.sdk.param;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * The shared body of a bid-pricing or supply-forecast request. {@code bidType} applies to bid
+ * pricing only, {@code budgetMinor} to the supply forecast only.
+ */
+public final class AdForecastParams {
+
+    private final Map<String, Object> body = new LinkedHashMap<>();
+
+    private AdForecastParams() {}
+
+    /** {@code goal} is engagement, traffic, awareness or video_views. */
+    public static AdForecastParams of(
+            String workspaceId,
+            String connectionId,
+            String adAccountId,
+            String goal,
+            AdTargetingParams targeting) {
+        AdForecastParams params = new AdForecastParams();
+        params.body.put("workspaceId", workspaceId);
+        params.body.put("connectionId", connectionId);
+        params.body.put("adAccountId", adAccountId);
+        params.body.put("goal", goal);
+        params.body.put("targeting", targeting.toMap());
+        return params;
+    }
+
+    public AdForecastParams placements(List<String> placements) {
+        body.put("placements", List.copyOf(placements));
+        return this;
+    }
+
+    /** CPC, CPM or CPV. Bid pricing only. */
+    public AdForecastParams bidType(String bidType) {
+        body.put("bidType", bidType);
+        return this;
+    }
+
+    /** The budget for the forecast window, minor units. Supply forecast only. */
+    public AdForecastParams budgetMinor(long budgetMinor) {
+        body.put("budgetMinor", budgetMinor);
+        return this;
+    }
+
+    public Map<String, Object> toMap() {
+        return new LinkedHashMap<>(body);
+    }
+}

src/main/java/com/fopost/sdk/param/ConversionEventParams.java

@@ -0,0 +1,49 @@
+package com.fopost.sdk.param;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * One conversion sent back to the network. It needs an email or a click id; the address is hashed
+ * inside the API, so the network never receives it and nothing about an event is stored.
+ */
+public final class ConversionEventParams {
+
+    private final Map<String, Object> body = new LinkedHashMap<>();
+
+    private ConversionEventParams() {}
+
+    /** {@code happenedAt} is epoch milliseconds. */
+    public static ConversionEventParams at(long happenedAt) {
+        ConversionEventParams params = new ConversionEventParams();
+        params.body.put("happenedAt", happenedAt);
+        return params;
+    }
+
+    public ConversionEventParams email(String email) {
+        body.put("email", email);
+        return this;
+    }
+
+    /** The network's click id, as the landing page received it. */
+    public ConversionEventParams clickId(String clickId) {
+        body.put("clickId", clickId);
+        return this;
+    }
+
+    public ConversionEventParams value(long valueMinor, String currency) {
+        body.put("valueMinor", valueMinor);
+        body.put("currency", currency);
+        return this;
+    }
+
+    /** Your own id for the event, so a replay is counted once. */
+    public ConversionEventParams eventId(String eventId) {
+        body.put("eventId", eventId);
+        return this;
+    }
+
+    public Map<String, Object> toMap() {
+        return new LinkedHashMap<>(body);
+    }
+}

src/main/java/com/fopost/sdk/param/CreateConversionRuleParams.java

@@ -0,0 +1,54 @@
+package com.fopost.sdk.param;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** A new conversion rule on one ad account. */
+public final class CreateConversionRuleParams {
+
+    private final Map<String, Object> body = new LinkedHashMap<>();
+
+    private CreateConversionRuleParams() {}
+
+    /**
+     * {@code type} is purchase, lead, sign_up, add_to_cart, download, install, key_page_view or
+     * other; {@code attribution} is last_touch or each_campaign.
+     */
+    public static CreateConversionRuleParams of(
+            String workspaceId,
+            String connectionId,
+            String adAccountId,
+            String name,
+            String type,
+            String attribution) {
+        CreateConversionRuleParams params = new CreateConversionRuleParams();
+        params.body.put("workspaceId", workspaceId);
+        params.body.put("connectionId", connectionId);
+        params.body.put("adAccountId", adAccountId);
+        params.body.put("name", name);
+        params.body.put("type", type);
+        params.body.put("attribution", attribution);
+        return params;
+    }
+
+    public CreateConversionRuleParams postClickWindowDays(int days) {
+        body.put("postClickWindowDays", days);
+        return this;
+    }
+
+    public CreateConversionRuleParams viewThroughWindowDays(int days) {
+        body.put("viewThroughWindowDays", days);
+        return this;
+    }
+
+    /** What one conversion is worth, minor units. */
+    public CreateConversionRuleParams value(long valueMinor, String currency) {
+        body.put("valueMinor", valueMinor);
+        body.put("currency", currency);
+        return this;
+    }
+
+    public Map<String, Object> toMap() {
+        return new LinkedHashMap<>(body);
+    }
+}

src/main/java/com/fopost/sdk/param/UpdateConversionRuleParams.java

@@ -0,0 +1,54 @@
+package com.fopost.sdk.param;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** Changes to a conversion rule. Only the fields you set move. */
+public final class UpdateConversionRuleParams {
+
+    private final Map<String, Object> body = new LinkedHashMap<>();
+
+    public static UpdateConversionRuleParams create() {
+        return new UpdateConversionRuleParams();
+    }
+
+    public UpdateConversionRuleParams name(String name) {
+        body.put("name", name);
+        return this;
+    }
+
+    public UpdateConversionRuleParams type(String type) {
+        body.put("type", type);
+        return this;
+    }
+
+    public UpdateConversionRuleParams attribution(String attribution) {
+        body.put("attribution", attribution);
+        return this;
+    }
+
+    public UpdateConversionRuleParams postClickWindowDays(int days) {
+        body.put("postClickWindowDays", days);
+        return this;
+    }
+
+    public UpdateConversionRuleParams viewThroughWindowDays(int days) {
+        body.put("viewThroughWindowDays", days);
+        return this;
+    }
+
+    public UpdateConversionRuleParams value(long valueMinor, String currency) {
+        body.put("valueMinor", valueMinor);
+        body.put("currency", currency);
+        return this;
+    }
+
+    public UpdateConversionRuleParams enabled(boolean enabled) {
+        body.put("enabled", enabled);
+        return this;
+    }
+
+    public Map<String, Object> toMap() {
+        return new LinkedHashMap<>(body);
+    }
+}