omnisocials 0.14.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1817 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OmniSocials
4
+ module Resources
5
+ # Ads resource: boosts, campaigns and "Create an ad" drafts on Meta,
6
+ # Pinterest, TikTok, LinkedIn, X and Google.
7
+ #
8
+ # Ads spend real money once a campaign starts. Boosts and drafts are
9
+ # created as drafts (no spend). Starting or raising spend needs a key with
10
+ # the opt-in ads:spend scope ("Start ads", a second switch under "Ads";
11
+ # its creator needs manage_ads): activate, activate_multi, resume, the
12
+ # draft launch (drafts.launch), a budget raise or any change of a campaign
13
+ # that reached the network through update, and the parity calls that
14
+ # switch something on or raise a budget. Each repeats the amount. Without
15
+ # ads:spend these calls answer 403 start_in_app with the page in the app
16
+ # where a person does it; on Google (api_draft_only) they always do, also
17
+ # with ads:spend. Pause and delete stay open, except on the networks in
18
+ # api_stop_in_app (Google). The calls that start or raise spend are never
19
+ # retried after a 5xx, a timeout or a lost connection (only a 429),
20
+ # because the first attempt may have started the ad. Budgets are in major
21
+ # currency units (10 = 10 EUR) in the ad account's currency. An Ads error
22
+ # may carry "param" (the field at fault) in its body. Ad accounts are
23
+ # connected and picked in the OmniSocials dashboard. The scopes ads:read
24
+ # and ads:write are opt-in on the API key (the Ads switch).
25
+ #
26
+ # The Ads API parity sub-resources (objects, campaign_ads, comments,
27
+ # targeting, audiences, lead_forms, leads, conversions, insights, reports,
28
+ # rules, results, media, previews, partnership, accounts, reach_frequency,
29
+ # studies, budget_schedules, google) are a thin passthrough. Every call
30
+ # there that switches something on or can raise spend (objects.update,
31
+ # objects.set_status, objects.duplicate, bulk_status, campaign_ads.add,
32
+ # campaign_ads.set_status, rules.create, rules.update, rules.undo,
33
+ # accounts.update_settings, reach_frequency.reserve, studies.create,
34
+ # budget_schedules.create) needs a key with ads:spend (rules: else 403
35
+ # rule_raises_spend), takes the person's own amount where it raises spend
36
+ # (confirm_budget_amount, rules confirm_max_daily_budget) and follows the
37
+ # same no-retry rule. Pausing, deleting and archiving stay open, except on
38
+ # Google.
39
+ class Ads
40
+ # "Create an ad" drafts (an OmniSocials::Resources::AdDrafts).
41
+ attr_reader :drafts
42
+ # The Ads API parity sub-resource for campaigns, ad sets and ads of an ad account, also the ones made outside OmniSocials, and their import (an
43
+ # OmniSocials::Resources::AdObjects).
44
+ attr_reader :objects
45
+ # The Ads API parity sub-resource for the ads of an OmniSocials campaign (an
46
+ # OmniSocials::Resources::AdCampaignAds).
47
+ attr_reader :campaign_ads
48
+ # The Ads API parity sub-resource for comments on ads (an
49
+ # OmniSocials::Resources::AdComments).
50
+ attr_reader :comments
51
+ # The Ads API parity sub-resource for targeting search, browse, reach estimate and bid suggestions (an
52
+ # OmniSocials::Resources::AdTargeting).
53
+ attr_reader :targeting
54
+ # The Ads API parity sub-resource for custom audiences (an
55
+ # OmniSocials::Resources::AdAudiences).
56
+ attr_reader :audiences
57
+ # The Ads API parity sub-resource for lead forms (an
58
+ # OmniSocials::Resources::AdLeadForms).
59
+ attr_reader :lead_forms
60
+ # The Ads API parity sub-resource for leads copied from the lead forms (an
61
+ # OmniSocials::Resources::AdLeads).
62
+ attr_reader :leads
63
+ # The Ads API parity sub-resource for pixels, conversion goals, custom conversions, server-side events (an
64
+ # OmniSocials::Resources::AdConversions).
65
+ attr_reader :conversions
66
+ # The Ads API parity sub-resource for live numbers, analytics, timeline, ranking, alerts (an
67
+ # OmniSocials::Resources::AdInsights).
68
+ attr_reader :insights
69
+ # The Ads API parity sub-resource for background reports (an
70
+ # OmniSocials::Resources::AdReports).
71
+ attr_reader :reports
72
+ # The Ads API parity sub-resource for automated rules (an
73
+ # OmniSocials::Resources::AdRules).
74
+ attr_reader :rules
75
+ # The Ads API parity sub-resource for your own numbers per campaign and day (an
76
+ # OmniSocials::Resources::AdResults).
77
+ attr_reader :results
78
+ # The Ads API parity sub-resource for the network's own image and video library (an
79
+ # OmniSocials::Resources::AdMedia).
80
+ attr_reader :media
81
+ # The Ads API parity sub-resource for previews drawn by the network (an
82
+ # OmniSocials::Resources::AdPreviews).
83
+ attr_reader :previews
84
+ # The Ads API parity sub-resource for partnership ads (Meta) (an
85
+ # OmniSocials::Resources::AdPartnership).
86
+ attr_reader :partnership
87
+ # The Ads API parity sub-resource for ad account admin (health, finance, settings, people, change log) (an
88
+ # OmniSocials::Resources::AdAccountsAdmin).
89
+ attr_reader :accounts
90
+ # The Ads API parity sub-resource for Meta reach and frequency (an
91
+ # OmniSocials::Resources::AdReachFrequency).
92
+ attr_reader :reach_frequency
93
+ # The Ads API parity sub-resource for A/B tests and lift studies (Meta) (an
94
+ # OmniSocials::Resources::AdStudies).
95
+ attr_reader :studies
96
+ # The Ads API parity sub-resource for planned budget increases (Meta) (an
97
+ # OmniSocials::Resources::AdBudgetSchedules).
98
+ attr_reader :budget_schedules
99
+ # The Ads API parity sub-resource for Google reports (an
100
+ # OmniSocials::Resources::AdGoogle).
101
+ attr_reader :google
102
+
103
+ def initialize(client)
104
+ @client = client
105
+ @drafts = AdDrafts.new(client)
106
+ @objects = AdObjects.new(client)
107
+ @campaign_ads = AdCampaignAds.new(client)
108
+ @comments = AdComments.new(client)
109
+ @targeting = AdTargeting.new(client)
110
+ @audiences = AdAudiences.new(client)
111
+ @lead_forms = AdLeadForms.new(client)
112
+ @leads = AdLeads.new(client)
113
+ @conversions = AdConversions.new(client)
114
+ @insights = AdInsights.new(client)
115
+ @reports = AdReports.new(client)
116
+ @rules = AdRules.new(client)
117
+ @results = AdResults.new(client)
118
+ @media = AdMedia.new(client)
119
+ @previews = AdPreviews.new(client)
120
+ @partnership = AdPartnership.new(client)
121
+ @accounts = AdAccountsAdmin.new(client)
122
+ @reach_frequency = AdReachFrequency.new(client)
123
+ @studies = AdStudies.new(client)
124
+ @budget_schedules = AdBudgetSchedules.new(client)
125
+ @google = AdGoogle.new(client)
126
+ end
127
+
128
+ # GET /ads/accounts - the connected ad accounts, as { "data" => [...],
129
+ # "platforms_available" => [...] }. Accounts are connected and picked in
130
+ # the dashboard; only is_selected accounts can run campaigns. Requires
131
+ # ads:read (opt-in on the API key).
132
+ def list_accounts
133
+ @client.request("GET", "/ads/accounts")
134
+ end
135
+
136
+ # GET /ads/capabilities - what each network accepts for a new ad (goals,
137
+ # media, text limits, buttons, minimum daily budget), create_networks
138
+ # and network_states ("live", "preview" or "coming_soon"), and per
139
+ # network the "features" its API offers, "targeting_types",
140
+ # "bid_strategies", "settings" and "ad_fields", plus "api_goals",
141
+ # "api_draft_only" (networks where every API caller stops at the draft,
142
+ # also a key with ads:spend: Google) and "api_stop_in_app" (networks
143
+ # where the API may not even pause or delete a campaign that reached the
144
+ # network: Google). Requires ads:read.
145
+ def capabilities
146
+ @client.request("GET", "/ads/capabilities")
147
+ end
148
+
149
+ # GET /ads/campaigns - list campaigns and boosts, optionally by status,
150
+ # platform or campaign_type ("campaign" or "boost"); limit is 1..100
151
+ # (default 25). Requires ads:read.
152
+ def list(status: nil, platform: nil, campaign_type: nil, limit: nil, offset: nil)
153
+ @client.request(
154
+ "GET", "/ads/campaigns",
155
+ query: {
156
+ "status" => status, "platform" => platform, "campaign_type" => campaign_type,
157
+ "limit" => limit, "offset" => offset
158
+ }
159
+ )
160
+ end
161
+
162
+ # GET /ads/campaigns/{id} - one campaign with its latest numbers.
163
+ # Requires ads:read.
164
+ def get(campaign_id)
165
+ @client.request("GET", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
166
+ end
167
+
168
+ # POST /ads/boost - boost a published post. Creates a DRAFT boost that
169
+ # spends nothing; the person starts it in the app. budget is
170
+ # { "type" => "daily", "amount" => 5, "currency" => "EUR" } in the ad
171
+ # account's currency. TikTok needs creative "spark_auth_code", Google
172
+ # needs "headlines", "descriptions" and "logo_url". Requires ads:write.
173
+ def boost(post_id:, ad_account_id:, budget:, objective: nil, targeting: nil,
174
+ schedule: nil, creative: nil, name: nil)
175
+ body = Internal.drop_nil(
176
+ {
177
+ "post_id" => post_id, "ad_account_id" => ad_account_id, "budget" => budget,
178
+ "objective" => objective, "targeting" => targeting, "schedule" => schedule,
179
+ "creative" => creative, "name" => name
180
+ }
181
+ )
182
+ @client.request("POST", "/ads/boost", json: body)
183
+ end
184
+
185
+ # POST /ads/boost-multi - one DRAFT boost per ad account (up to 10),
186
+ # each with the same budget, so the total is amount x accounts. Answers
187
+ # { "results" => [...] }; one failed account never stops the others.
188
+ # Requires ads:write.
189
+ def boost_multi(post_id:, ad_account_ids:, budget:, objective: nil, targeting: nil,
190
+ schedule: nil, creative: nil, name: nil)
191
+ body = Internal.drop_nil(
192
+ {
193
+ "post_id" => post_id, "ad_account_ids" => ad_account_ids.to_a, "budget" => budget,
194
+ "objective" => objective, "targeting" => targeting, "schedule" => schedule,
195
+ "creative" => creative, "name" => name
196
+ }
197
+ )
198
+ @client.request("POST", "/ads/boost-multi", json: body)
199
+ end
200
+
201
+ # PATCH /ads/campaigns/{id} - change the name, budget, targeting or
202
+ # schedule of a draft; objective and settings only while the campaign is
203
+ # a draft (400 settings_locked after the start: duplicate it).
204
+ #
205
+ # A campaign that reached the network changes only with a key that has
206
+ # ads:spend; without it, and on Google always, the call answers 403
207
+ # start_in_app and a person changes it in the app. A higher budget on a
208
+ # running campaign RAISES REAL AD SPEND: show the person the new amount
209
+ # and get their yes first, then pass it again as confirm_budget_amount.
210
+ # Not retried after a 5xx, a timeout or a lost connection: read the
211
+ # campaign with get to see what happened. Requires ads:write.
212
+ def update(campaign_id, name: nil, budget: nil, confirm_budget_amount: nil,
213
+ targeting: nil, schedule: nil, objective: nil, settings: nil)
214
+ body = Internal.drop_nil(
215
+ {
216
+ "name" => name,
217
+ "budget" => budget,
218
+ "confirm_budget_amount" => confirm_budget_amount,
219
+ "targeting" => targeting,
220
+ "schedule" => schedule,
221
+ "objective" => objective,
222
+ "settings" => settings
223
+ }
224
+ )
225
+ @client.request(
226
+ "PATCH", "/ads/campaigns/#{Internal.path_segment(campaign_id)}",
227
+ json: body, retry_on: :rate_limit
228
+ )
229
+ end
230
+
231
+ # POST /ads/campaigns/{id}/activate - START REAL AD SPEND.
232
+ #
233
+ # Needs a key with the opt-in ads:spend scope ("Start ads"); without it,
234
+ # and on Google (api_draft_only) always, the call answers 403
235
+ # start_in_app with the page where a person does it in the app. Show the
236
+ # person the budget (amount, currency, daily or lifetime) and get their
237
+ # yes first; confirm_budget_amount must equal the campaign's budget
238
+ # amount. A campaign of a draft group answers 409 use_draft_launch: use
239
+ # ads.drafts.launch. Not retried after a 5xx, a timeout or a lost
240
+ # connection: read the campaign with get to see what happened. Requires
241
+ # ads:write.
242
+ def activate(campaign_id, confirm_budget_amount)
243
+ @client.request(
244
+ "POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/activate",
245
+ json: { "confirm_budget_amount" => confirm_budget_amount }, retry_on: :rate_limit
246
+ )
247
+ end
248
+
249
+ # POST /ads/campaigns/activate-multi - START REAL AD SPEND on up to 10
250
+ # campaigns.
251
+ #
252
+ # Needs a key with ads:spend: without it, and on Google always, a result
253
+ # answers "ok" => false with code start_in_app and the page where a
254
+ # person starts it. Every campaign's budget must equal
255
+ # confirm_budget_amount; show the person the total (amount x campaigns)
256
+ # and get their yes first. Answers { "results" => [...] }. Not retried
257
+ # after a 5xx, a timeout or a lost connection: read the campaigns with
258
+ # get to see what happened. Requires ads:write.
259
+ def activate_multi(campaign_ids, confirm_budget_amount)
260
+ @client.request(
261
+ "POST", "/ads/campaigns/activate-multi",
262
+ json: {
263
+ "campaign_ids" => campaign_ids.to_a,
264
+ "confirm_budget_amount" => confirm_budget_amount
265
+ },
266
+ retry_on: :rate_limit
267
+ )
268
+ end
269
+
270
+ # POST /ads/campaigns/{id}/pause - pause a campaign (also while in
271
+ # review). Open with ads:write, except on the networks in
272
+ # api_stop_in_app (Google): there a campaign that reached the network
273
+ # answers 403 start_in_app. Requires ads:write.
274
+ def pause(campaign_id)
275
+ @client.request("POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/pause")
276
+ end
277
+
278
+ # POST /ads/campaigns/{id}/resume - resume a paused campaign: it STARTS
279
+ # REAL AD SPEND again. Needs a key with the opt-in ads:spend scope
280
+ # ("Start ads"); without it, and on Google (api_draft_only) always, the
281
+ # call answers 403 start_in_app with the page where a person does it in
282
+ # the app. Only a paused campaign resumes (409 not_paused). Show the
283
+ # person the budget and get their yes first. Not retried after a 5xx, a
284
+ # timeout or a lost connection: read the campaign with get to see what
285
+ # happened. Requires ads:write.
286
+ def resume(campaign_id)
287
+ @client.request(
288
+ "POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/resume",
289
+ retry_on: :rate_limit
290
+ )
291
+ end
292
+
293
+ # POST /ads/campaigns/bulk-status - pause or resume up to 50 campaigns
294
+ # (status "paused" or "active").
295
+ #
296
+ # Resuming RESTARTS REAL AD SPEND: every campaign's budget must equal
297
+ # confirm_budget_amount (one amount for all), checked before any change;
298
+ # show the person the total and get their yes first. Resuming needs a
299
+ # key with ads:spend: without it, and on Google always, a result answers
300
+ # start_in_app. Pausing stays open (Google: start_in_app). Answers
301
+ # { "data" => { "results" => [...] } }. Not retried after a 5xx, a
302
+ # timeout or a lost connection. Requires ads:write.
303
+ def bulk_status(campaign_ids:, status:, confirm_budget_amount: nil)
304
+ @client.request(
305
+ "POST", "/ads/campaigns/bulk-status",
306
+ json: Internal.drop_nil(
307
+ {
308
+ "campaign_ids" => campaign_ids.to_a, "status" => status,
309
+ "confirm_budget_amount" => confirm_budget_amount
310
+ }
311
+ ),
312
+ retry_on: :rate_limit
313
+ )
314
+ end
315
+
316
+ # POST /ads/campaigns/{id}/duplicate - copy a campaign as a new draft
317
+ # (same ad account, goal, budget, targeting, settings and ads). A draft
318
+ # never spends. Requires ads:write.
319
+ def duplicate(campaign_id, name: nil)
320
+ @client.request(
321
+ "POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/duplicate",
322
+ json: Internal.drop_nil({ "name" => name })
323
+ )
324
+ end
325
+
326
+ # DELETE /ads/campaigns/{id} - delete a campaign on the network too. A
327
+ # campaign that spent is archived: its spend stays in the totals. Open
328
+ # with ads:write, except on the networks in api_stop_in_app (Google):
329
+ # there a campaign that reached the network answers 403 start_in_app.
330
+ # Requires ads:write.
331
+ def delete(campaign_id)
332
+ @client.request("DELETE", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
333
+ end
334
+
335
+ # GET /ads/overview - accounts, campaigns per status and the totals.
336
+ # totals["spend"] is nil when the campaigns use more than one currency
337
+ # (totals["currency"] names the one currency): read totals_by_currency
338
+ # then, one row per currency with "currency", "spend", "impressions" and
339
+ # "clicks" (spend is never added across currencies). Requires ads:read.
340
+ def overview
341
+ @client.request("GET", "/ads/overview")
342
+ end
343
+
344
+ # GET /ads/suggestions - organic posts that do better than the
345
+ # workspace median: boost candidates. Read-only. Requires ads:read.
346
+ def suggestions
347
+ @client.request("GET", "/ads/suggestions")
348
+ end
349
+
350
+ # POST /ads/research/keywords - keyword ideas from seed keywords (up to
351
+ # 20), a url or both, through the connected Google Ads account. country
352
+ # defaults to "US", language to "en", limit is 1..500 (default 100);
353
+ # ad_account_id only when the workspace has more than one Google Ads
354
+ # account. Read-only and free. Requires ads:read.
355
+ def research_keywords(keywords: nil, url: nil, country: nil, language: nil, limit: nil,
356
+ ad_account_id: nil)
357
+ body = Internal.drop_nil(
358
+ {
359
+ "keywords" => keywords&.to_a,
360
+ "url" => url,
361
+ "country" => country,
362
+ "language" => language,
363
+ "limit" => limit,
364
+ "ad_account_id" => ad_account_id
365
+ }
366
+ )
367
+ @client.request("POST", "/ads/research/keywords", json: body)
368
+ end
369
+
370
+ # POST /ads/research/keywords/metrics - search numbers for an exact
371
+ # keyword list. Read-only. Requires ads:read.
372
+ def keyword_metrics(keywords:, country: nil, language: nil, ad_account_id: nil)
373
+ body = Internal.drop_nil(
374
+ {
375
+ "keywords" => keywords.to_a,
376
+ "country" => country,
377
+ "language" => language,
378
+ "ad_account_id" => ad_account_id
379
+ }
380
+ )
381
+ @client.request("POST", "/ads/research/keywords/metrics", json: body)
382
+ end
383
+ end
384
+
385
+ # "Create an ad" drafts: one campaign per network in platforms, each with
386
+ # the same ads. A draft never spends; launch starts it (a key with
387
+ # ads:spend), or a person does in the app from its review_url.
388
+ class AdDrafts
389
+ def initialize(client)
390
+ @client = client
391
+ end
392
+
393
+ # GET /ads/drafts/defaults - suggested countries (where the Instagram
394
+ # followers are), the currency and the workspace's ad account per
395
+ # network. Requires ads:read.
396
+ def defaults
397
+ @client.request("GET", "/ads/drafts/defaults")
398
+ end
399
+
400
+ # POST /ads/drafts - save a new ad as a draft group. It needs no ad
401
+ # account and spends nothing.
402
+ #
403
+ # objective is "traffic", "engagement", "awareness" or "video_views";
404
+ # through the API also "lead_generation", "conversions", "messages" or
405
+ # "calls" (each network's goal in ads.capabilities says what it
406
+ # "needs"). platforms lists network keys ("meta", "pinterest",
407
+ # "tiktok", "linkedin", "x", "google") or { "platform" => ...,
408
+ # "budget_amount" => ..., "ad_account_id" => ..., "settings" => {...} }
409
+ # per network (settings: bidding, conversion goal, lead form,
410
+ # messaging). budget is the daily amount
411
+ # per network, { "amount" => 10, "currency" => "EUR" }. schedule is
412
+ # { "duration_days" => 7 } (nil runs until it is stopped). targeting
413
+ # needs "countries"; "automatic_audience" => true lets the network find
414
+ # the audience; "networks" => { "meta" => { "include" => {...},
415
+ # "exclude" => {...}, "audiences" => {...} } } adds each network's own
416
+ # targeting (ids from ads.targeting.search). Each of ads has "media",
417
+ # "primary_text", "link" and optionally "headline", "description",
418
+ # "cta", "primary_text_b" (an A/B test), "network" (per network extras
419
+ # such as "lead_form_id", "media_ref", "spark_auth_code" or Google's
420
+ # "responsive_search_ad") and, on Meta, "placement_media" => { "stories_reels" => {...} }
421
+ # (an upright 9:16 file for Stories and Reels).
422
+ #
423
+ # Read ads.capabilities first for what each network accepts. The answer
424
+ # carries review_url (the builder in the dashboard, where the person
425
+ # checks and starts the ad: hand it over) and per network readiness. A
426
+ # budget["currency"] other than the attached ad account's currency
427
+ # answers 400 currency_mismatch with param "budget.currency". Requires
428
+ # ads:write.
429
+ def create(objective:, platforms:, budget:, targeting:, ads:, name: nil, schedule: nil)
430
+ body = draft_body(
431
+ objective: objective, platforms: platforms, budget: budget,
432
+ targeting: targeting, ads: ads, name: name, schedule: schedule
433
+ )
434
+ @client.request("POST", "/ads/drafts", json: body)
435
+ end
436
+
437
+ # GET /ads/drafts/{group_id} - one draft group. Requires ads:read.
438
+ def get(group_id)
439
+ @client.request("GET", "/ads/drafts/#{Internal.path_segment(group_id)}")
440
+ end
441
+
442
+ # PUT /ads/drafts/{group_id} - replace the draft with the full body (the
443
+ # same fields as create). Networks that already started are left alone
444
+ # (campaigns[].editable). A budget["currency"] other than the attached
445
+ # ad account's currency answers 400 currency_mismatch with param
446
+ # "budget.currency". Requires ads:write.
447
+ def update(group_id, objective:, platforms:, budget:, targeting:, ads:, name: nil,
448
+ schedule: nil)
449
+ body = draft_body(
450
+ objective: objective, platforms: platforms, budget: budget,
451
+ targeting: targeting, ads: ads, name: name, schedule: schedule
452
+ )
453
+ @client.request("PUT", "/ads/drafts/#{Internal.path_segment(group_id)}", json: body)
454
+ end
455
+
456
+ # DELETE /ads/drafts/{group_id} - delete a draft group that never
457
+ # started. Requires ads:write.
458
+ def delete(group_id)
459
+ @client.request("DELETE", "/ads/drafts/#{Internal.path_segment(group_id)}")
460
+ end
461
+
462
+ # POST /ads/drafts/{group_id}/account - set the ad account of one
463
+ # network in the draft (from ads.list_accounts, same network). Requires
464
+ # ads:write.
465
+ def attach_account(group_id, platform:, ad_account_id:)
466
+ @client.request(
467
+ "POST", "/ads/drafts/#{Internal.path_segment(group_id)}/account",
468
+ json: { "platform" => platform, "ad_account_id" => ad_account_id }
469
+ )
470
+ end
471
+
472
+ # POST /ads/drafts/{group_id}/launch - START REAL AD SPEND for every
473
+ # network of the draft that never started.
474
+ #
475
+ # Needs a key with the opt-in ads:spend scope ("Start ads"): without it
476
+ # the call answers 403 start_in_app with the draft's page (its
477
+ # review_url), and a network in api_draft_only (Google) is always
478
+ # skipped with code start_in_app. Show the person the daily amount per
479
+ # network and get their yes first, then pass it as confirm_budget_amount
480
+ # (or per campaign id as confirm_budget_amounts). A wrong or missing
481
+ # amount answers 400 budget_confirmation_required and writes nothing.
482
+ # The answer is { "data" => { "group" => ..., "results" => [...] } }
483
+ # with a result per network ("campaign_id" is a string); one failed
484
+ # network never stops the others. Not retried after a 5xx, a timeout or
485
+ # a lost connection: read the draft with get to see what started.
486
+ # Requires ads:write.
487
+ def launch(group_id, confirm_budget_amount: nil, confirm_budget_amounts: nil)
488
+ body = Internal.drop_nil(
489
+ {
490
+ "confirm_budget_amount" => confirm_budget_amount,
491
+ "confirm_budget_amounts" => confirm_budget_amounts
492
+ }
493
+ )
494
+ @client.request(
495
+ "POST", "/ads/drafts/#{Internal.path_segment(group_id)}/launch",
496
+ json: body, retry_on: :rate_limit
497
+ )
498
+ end
499
+
500
+ private
501
+
502
+ def draft_body(objective:, platforms:, budget:, targeting:, ads:, name:, schedule:)
503
+ Internal.drop_nil(
504
+ {
505
+ "name" => name,
506
+ "objective" => objective,
507
+ "platforms" => platforms.to_a,
508
+ "budget" => budget,
509
+ "schedule" => schedule,
510
+ "targeting" => targeting,
511
+ "ads" => ads.to_a
512
+ }
513
+ )
514
+ end
515
+ end
516
+
517
+ # -------------------------------------------------------------------------
518
+ # Ads API parity (2026-11-05). Thin passthrough: the API checks every
519
+ # field. A network without the feature answers 400
520
+ # not_supported_on_network (ads.capabilities lists "features" per
521
+ # network); a missing permission on the network side answers 403
522
+ # network_permission_missing. Every call that switches something on or can
523
+ # raise spend needs a key with ads:spend (without it, and on Google
524
+ # always, 403 start_in_app; rules: 403 rule_raises_spend), takes the
525
+ # person's own amount and is sent with retry_on: :rate_limit (never again
526
+ # after a 5xx, a timeout or a lost connection). Pausing, deleting and
527
+ # archiving stay open, except on Google.
528
+ # -------------------------------------------------------------------------
529
+
530
+ # Shared path helpers of the ads sub-resources.
531
+ module AdPaths
532
+ private
533
+
534
+ def seg(value)
535
+ Internal.path_segment(value)
536
+ end
537
+
538
+ def object_path(account_id, level, external_id)
539
+ "/ads/accounts/#{seg(account_id)}/objects/#{seg(level)}/#{seg(external_id)}"
540
+ end
541
+
542
+ def ad_path(campaign_id, ad_id)
543
+ "/ads/campaigns/#{seg(campaign_id)}/ads/#{seg(ad_id)}"
544
+ end
545
+
546
+ def account_path(account_id, rest)
547
+ "/ads/accounts/#{seg(account_id)}/#{rest}"
548
+ end
549
+
550
+ def list_param(value)
551
+ Internal.join_list(value)
552
+ end
553
+ end
554
+
555
+ # Campaigns, ad sets and ads of an ad account as the network has them,
556
+ # also the ones made outside OmniSocials, and the import of those
557
+ # campaigns. level is "campaign", "ad_set" or "ad". Objects of OmniSocials
558
+ # campaigns answer 409 use_campaign_routes: change those with the
559
+ # campaign methods.
560
+ class AdObjects
561
+ include AdPaths
562
+
563
+ def initialize(client)
564
+ @client = client
565
+ end
566
+
567
+ # GET /ads/accounts/{accountId}/tree - campaigns, ad sets and ads with
568
+ # the numbers of the date range (from / to, ISO dates; at most 90 days,
569
+ # default the last 30). Each campaign says "source" ("omnisocials" or
570
+ # "external"). status is an Array or a comma list. Requires ads:read.
571
+ def tree(account_id, from: nil, to: nil, status: nil, limit: nil, cursor: nil)
572
+ @client.request(
573
+ "GET", account_path(account_id, "tree"),
574
+ query: {
575
+ "from" => from, "to" => to, "status" => list_param(status),
576
+ "limit" => limit, "cursor" => cursor
577
+ }
578
+ )
579
+ end
580
+
581
+ # GET /ads/accounts/{accountId}/objects/{level}/{externalId} - live
582
+ # details of one object. Requires ads:read.
583
+ def get(account_id, level, external_id)
584
+ @client.request("GET", object_path(account_id, level, external_id))
585
+ end
586
+
587
+ # PATCH /ads/accounts/{accountId}/objects/{level}/{externalId} - change
588
+ # the name, budget or end date (end_at: nil removes it) of a campaign
589
+ # or ad set made outside OmniSocials.
590
+ #
591
+ # A higher budget RAISES REAL AD SPEND: show the person the new amount
592
+ # and get their yes first, then pass it as confirm_budget_amount. It
593
+ # changes the campaign on the network: needs a key with the opt-in
594
+ # ads:spend scope ("Start ads"); without it, and on Google
595
+ # (api_draft_only) always, the call answers 403 start_in_app with the
596
+ # page where a person does it in the app. Not retried after a 5xx, a
597
+ # timeout or a lost connection: read the object with get. Requires
598
+ # ads:write.
599
+ def update(account_id, level, external_id, name: nil, budget: nil, end_at: OmniSocials::NOT_GIVEN,
600
+ confirm_budget_amount: nil)
601
+ body = Internal.drop_nil(
602
+ { "name" => name, "budget" => budget, "confirm_budget_amount" => confirm_budget_amount }
603
+ )
604
+ body["end_at"] = end_at unless end_at.is_a?(NotGiven)
605
+ @client.request(
606
+ "PATCH", object_path(account_id, level, external_id),
607
+ json: body, retry_on: :rate_limit
608
+ )
609
+ end
610
+
611
+ # PUT /ads/accounts/{accountId}/objects/{level}/{externalId}/status -
612
+ # status is "paused" or "active".
613
+ #
614
+ # Switching on STARTS REAL AD SPEND: pass the budget that pays (the
615
+ # object's own or its parent's) as confirm_budget_amount after the
616
+ # person agreed. Switching on: needs a key with the opt-in ads:spend
617
+ # scope ("Start ads"); without it, and on Google (api_draft_only)
618
+ # always, the call answers 403 start_in_app with the page where a person
619
+ # does it in the app. Pausing needs nothing and stays open (Google:
620
+ # start_in_app). Not retried after a 5xx, a timeout or a lost
621
+ # connection. Requires ads:write.
622
+ def set_status(account_id, level, external_id, status:, confirm_budget_amount: nil)
623
+ @client.request(
624
+ "PUT", "#{object_path(account_id, level, external_id)}/status",
625
+ json: Internal.drop_nil(
626
+ { "status" => status, "confirm_budget_amount" => confirm_budget_amount }
627
+ ),
628
+ retry_on: :rate_limit
629
+ )
630
+ end
631
+
632
+ # POST /ads/accounts/{accountId}/objects/{level}/{externalId}/duplicate -
633
+ # copy an object made outside OmniSocials; the copy is paused (Meta
634
+ # today). It changes the ad account on the network: needs a key with the
635
+ # opt-in ads:spend scope ("Start ads"); without it, and on Google
636
+ # (api_draft_only) always, the call answers 403 start_in_app with the
637
+ # page where a person does it in the app. Requires ads:write.
638
+ def duplicate(account_id, level, external_id, deep: nil, rename: nil)
639
+ @client.request(
640
+ "POST", "#{object_path(account_id, level, external_id)}/duplicate",
641
+ json: Internal.drop_nil({ "deep" => deep, "rename" => rename })
642
+ )
643
+ end
644
+
645
+ # GET /ads/accounts/{accountId}/import - the import state of the
646
+ # campaigns made outside OmniSocials. Requires ads:read.
647
+ def import_status(account_id)
648
+ @client.request("GET", account_path(account_id, "import"))
649
+ end
650
+
651
+ # POST /ads/accounts/{accountId}/import - read the ad account again at
652
+ # the next sync (within 15 minutes). The first import reads 90 days;
653
+ # webhook ads.initial_sync_completed when it is done. Requires
654
+ # ads:write.
655
+ def start_import(account_id)
656
+ @client.request("POST", account_path(account_id, "import"))
657
+ end
658
+
659
+ # GET /ads/external-campaigns - the imported campaigns (limit at most
660
+ # 200). Requires ads:read.
661
+ def list_external(ad_account_id: nil, platform: nil, status: nil, limit: nil, offset: nil)
662
+ @client.request(
663
+ "GET", "/ads/external-campaigns",
664
+ query: {
665
+ "ad_account_id" => ad_account_id, "platform" => platform, "status" => status,
666
+ "limit" => limit, "offset" => offset
667
+ }
668
+ )
669
+ end
670
+
671
+ # GET /ads/external-campaigns/{id} - one imported campaign with its
672
+ # daily numbers. Requires ads:read.
673
+ def get_external(campaign_id, from: nil, to: nil)
674
+ @client.request(
675
+ "GET", "/ads/external-campaigns/#{seg(campaign_id)}",
676
+ query: { "from" => from, "to" => to }
677
+ )
678
+ end
679
+ end
680
+
681
+ # The ads of an OmniSocials campaign.
682
+ class AdCampaignAds
683
+ include AdPaths
684
+
685
+ def initialize(client)
686
+ @client = client
687
+ end
688
+
689
+ # GET /ads/campaigns/{id}/ads - the ads with their status, review and
690
+ # latest numbers. Requires ads:read.
691
+ def list(campaign_id)
692
+ @client.request("GET", "/ads/campaigns/#{seg(campaign_id)}/ads")
693
+ end
694
+
695
+ # POST /ads/campaigns/{id}/ads - add up to 6 ads (the shape of a draft
696
+ # ad) to a campaign that runs. They are created PAUSED on the network;
697
+ # switch each one on with set_status. Needs a key with the opt-in
698
+ # ads:spend scope ("Start ads"); without it, and on Google
699
+ # (api_draft_only) always, the call answers 403 start_in_app with the
700
+ # page where a person does it in the app. Webhook ad.created. Requires
701
+ # ads:write.
702
+ def add(campaign_id, ads)
703
+ @client.request("POST", "/ads/campaigns/#{seg(campaign_id)}/ads", json: { "ads" => ads.to_a })
704
+ end
705
+
706
+ # GET /ads/campaigns/{id}/ads/{adId} - one ad. Requires ads:read.
707
+ def get(campaign_id, ad_id)
708
+ @client.request("GET", ad_path(campaign_id, ad_id))
709
+ end
710
+
711
+ # PUT /ads/campaigns/{id}/ads/{adId}/status - "paused" or "active".
712
+ #
713
+ # Switching on STARTS REAL AD SPEND: pass the campaign budget as
714
+ # confirm_budget_amount after the person agreed. Switching on: needs a
715
+ # key with the opt-in ads:spend scope ("Start ads"); without it, and on
716
+ # Google (api_draft_only) always, the call answers 403 start_in_app with
717
+ # the page where a person does it in the app. Pausing stays open
718
+ # (Google: start_in_app). Not retried after a 5xx, a timeout or a lost
719
+ # connection. Webhook ad.updated. Requires ads:write.
720
+ def set_status(campaign_id, ad_id, status:, confirm_budget_amount: nil)
721
+ @client.request(
722
+ "PUT", "#{ad_path(campaign_id, ad_id)}/status",
723
+ json: Internal.drop_nil(
724
+ { "status" => status, "confirm_budget_amount" => confirm_budget_amount }
725
+ ),
726
+ retry_on: :rate_limit
727
+ )
728
+ end
729
+
730
+ # GET /ads/campaigns/{id}/ads/{adId}/review - the network's review
731
+ # verdict ("in_review", "approved" or "rejected" with reasons).
732
+ # Requires ads:read.
733
+ def review(campaign_id, ad_id)
734
+ @client.request("GET", "#{ad_path(campaign_id, ad_id)}/review")
735
+ end
736
+ end
737
+
738
+ # Comments on an ad of an OmniSocials campaign.
739
+ class AdComments
740
+ include AdPaths
741
+
742
+ def initialize(client)
743
+ @client = client
744
+ end
745
+
746
+ # GET /ads/campaigns/{id}/ads/{adId}/comments. Requires ads:read.
747
+ def list(campaign_id, ad_id, cursor: nil)
748
+ @client.request("GET", "#{ad_path(campaign_id, ad_id)}/comments", query: { "cursor" => cursor })
749
+ end
750
+
751
+ # POST /ads/campaigns/{id}/ads/{adId}/comments/{commentId}/reply -
752
+ # answer a comment. Requires ads:write.
753
+ def reply(campaign_id, ad_id, comment_id, text)
754
+ @client.request(
755
+ "POST", "#{ad_path(campaign_id, ad_id)}/comments/#{seg(comment_id)}/reply",
756
+ json: { "text" => text }
757
+ )
758
+ end
759
+
760
+ # POST /ads/campaigns/{id}/ads/{adId}/comments/{commentId}/hide - hide
761
+ # (default) or show a comment. Requires ads:write.
762
+ def hide(campaign_id, ad_id, comment_id, hidden: true)
763
+ @client.request(
764
+ "POST", "#{ad_path(campaign_id, ad_id)}/comments/#{seg(comment_id)}/hide",
765
+ json: { "hidden" => hidden }
766
+ )
767
+ end
768
+
769
+ # DELETE /ads/campaigns/{id}/ads/{adId}/comments/{commentId}. Requires
770
+ # ads:write.
771
+ def delete(campaign_id, ad_id, comment_id)
772
+ @client.request("DELETE", "#{ad_path(campaign_id, ad_id)}/comments/#{seg(comment_id)}")
773
+ end
774
+ end
775
+
776
+ # Targeting options of a network. The ids go in
777
+ # targeting["networks"][<network>]["include"] of a draft (or
778
+ # targeting["network"] of a campaign); the types per network are
779
+ # ads.capabilities "targeting_types".
780
+ class AdTargeting
781
+ def initialize(client)
782
+ @client = client
783
+ end
784
+
785
+ # GET /ads/targeting/search - interests, places, languages, job titles
786
+ # ... (limit at most 100). Requires ads:read.
787
+ def search(ad_account_id:, type:, q:, limit: nil, country: nil)
788
+ @client.request(
789
+ "GET", "/ads/targeting/search",
790
+ query: {
791
+ "ad_account_id" => ad_account_id, "type" => type, "q" => q,
792
+ "limit" => limit, "country" => country
793
+ }
794
+ )
795
+ end
796
+
797
+ # GET /ads/targeting/browse - the categories as a tree. Requires
798
+ # ads:read.
799
+ def browse(ad_account_id:, type:)
800
+ @client.request(
801
+ "GET", "/ads/targeting/browse", query: { "ad_account_id" => ad_account_id, "type" => type }
802
+ )
803
+ end
804
+
805
+ # POST /ads/targeting/reach-estimate - the audience size of a targeting
806
+ # ("countries", "age_min", "age_max", "genders", "network"). Read-only.
807
+ # Requires ads:read.
808
+ def reach_estimate(ad_account_id:, targeting:, objective: nil)
809
+ @client.request(
810
+ "POST", "/ads/targeting/reach-estimate",
811
+ json: Internal.drop_nil(
812
+ { "ad_account_id" => ad_account_id, "objective" => objective, "targeting" => targeting }
813
+ )
814
+ )
815
+ end
816
+
817
+ # POST /ads/targeting/bid-suggestions - a suggested bid and daily
818
+ # budget. Read-only. Requires ads:read.
819
+ def bid_suggestions(ad_account_id:, targeting:, objective: nil, budget: nil)
820
+ @client.request(
821
+ "POST", "/ads/targeting/bid-suggestions",
822
+ json: Internal.drop_nil(
823
+ {
824
+ "ad_account_id" => ad_account_id, "objective" => objective,
825
+ "targeting" => targeting, "budget" => budget
826
+ }
827
+ )
828
+ )
829
+ end
830
+ end
831
+
832
+ # Custom audiences of an ad account: customer lists, lookalikes and
833
+ # company lists. audience_id is the network's audience id.
834
+ class AdAudiences
835
+ include AdPaths
836
+
837
+ def initialize(client)
838
+ @client = client
839
+ end
840
+
841
+ # GET /ads/audiences. Requires ads:read.
842
+ def list(ad_account_id:, cursor: nil)
843
+ @client.request(
844
+ "GET", "/ads/audiences", query: { "ad_account_id" => ad_account_id, "cursor" => cursor }
845
+ )
846
+ end
847
+
848
+ # POST /ads/audiences - kind is "customer_list", "lookalike" (lookalike:
849
+ # { "source_audience_id", "country", "ratio" }, ratio 0.01 to 0.2) or
850
+ # "company_list". customer_file_source (Meta: "user_provided",
851
+ # "partner_provided" or "both") is what the person says. schema + rows
852
+ # are optional first members of a customer list (Pinterest needs
853
+ # them); raw values are hashed with SHA-256 before they leave.
854
+ # Requires ads:write.
855
+ def create(ad_account_id:, name:, description: nil, kind: nil, lookalike: nil,
856
+ customer_file_source: nil, schema: nil, rows: nil)
857
+ @client.request(
858
+ "POST", "/ads/audiences",
859
+ json: Internal.drop_nil(
860
+ {
861
+ "ad_account_id" => ad_account_id, "name" => name, "description" => description,
862
+ "kind" => kind, "lookalike" => lookalike,
863
+ "customer_file_source" => customer_file_source,
864
+ "schema" => schema&.to_a, "rows" => rows&.to_a
865
+ }
866
+ )
867
+ )
868
+ end
869
+
870
+ # GET /ads/audiences/{audienceId}. Requires ads:read.
871
+ def get(audience_id, ad_account_id:)
872
+ @client.request(
873
+ "GET", "/ads/audiences/#{seg(audience_id)}", query: { "ad_account_id" => ad_account_id }
874
+ )
875
+ end
876
+
877
+ # PATCH /ads/audiences/{audienceId} - rename. Requires ads:write.
878
+ def update(audience_id, ad_account_id:, name: nil, description: nil)
879
+ @client.request(
880
+ "PATCH", "/ads/audiences/#{seg(audience_id)}",
881
+ json: Internal.drop_nil(
882
+ { "ad_account_id" => ad_account_id, "name" => name, "description" => description }
883
+ )
884
+ )
885
+ end
886
+
887
+ # DELETE /ads/audiences/{audienceId}. Requires ads:write.
888
+ def delete(audience_id, ad_account_id:)
889
+ @client.request(
890
+ "DELETE", "/ads/audiences/#{seg(audience_id)}", query: { "ad_account_id" => ad_account_id }
891
+ )
892
+ end
893
+
894
+ # POST /ads/audiences/{audienceId}/members - add people to a customer
895
+ # list. Send the raw values: OmniSocials normalizes them and hashes
896
+ # them with SHA-256 before they leave and stores nothing. At most
897
+ # 10,000 rows. schema keys: email, phone, first_name, last_name, city,
898
+ # state, zip, country, external_id, dob_year, gender, maid. Requires
899
+ # ads:write.
900
+ def add_members(audience_id, ad_account_id:, schema:, rows:)
901
+ @client.request(
902
+ "POST", "/ads/audiences/#{seg(audience_id)}/members",
903
+ json: { "ad_account_id" => ad_account_id, "schema" => schema.to_a, "rows" => rows.to_a }
904
+ )
905
+ end
906
+
907
+ # DELETE /ads/audiences/{audienceId}/members - remove people (the same
908
+ # body as add_members). Requires ads:write.
909
+ def remove_members(audience_id, ad_account_id:, schema:, rows:)
910
+ @client.request(
911
+ "DELETE", "/ads/audiences/#{seg(audience_id)}/members",
912
+ json: { "ad_account_id" => ad_account_id, "schema" => schema.to_a, "rows" => rows.to_a }
913
+ )
914
+ end
915
+
916
+ # POST /ads/audiences/{audienceId}/companies - add companies ("name",
917
+ # "domain", "linkedin_url") to a company list (LinkedIn). Requires
918
+ # ads:write.
919
+ def add_companies(audience_id, ad_account_id:, companies:)
920
+ @client.request(
921
+ "POST", "/ads/audiences/#{seg(audience_id)}/companies",
922
+ json: { "ad_account_id" => ad_account_id, "companies" => companies.to_a }
923
+ )
924
+ end
925
+ end
926
+
927
+ # Lead forms (Meta: the workspace's Page). form_id is the OmniSocials
928
+ # form id; a form's "external_id" goes in settings "lead_form_id".
929
+ class AdLeadForms
930
+ include AdPaths
931
+
932
+ def initialize(client)
933
+ @client = client
934
+ end
935
+
936
+ # GET /ads/lead-forms. Requires ads:read.
937
+ def list(ad_account_id:)
938
+ @client.request("GET", "/ads/lead-forms", query: { "ad_account_id" => ad_account_id })
939
+ end
940
+
941
+ # POST /ads/lead-forms. accept_terms: true says the person accepts the
942
+ # network's lead ad terms (Pinterest refuses a form without it): only
943
+ # send it after the person said yes. Requires ads:write.
944
+ def create(ad_account_id:, name:, privacy_policy_url:, questions:, thank_you:, locale: nil,
945
+ headline: nil, description: nil, accept_terms: nil)
946
+ @client.request(
947
+ "POST", "/ads/lead-forms",
948
+ json: Internal.drop_nil(
949
+ {
950
+ "ad_account_id" => ad_account_id, "name" => name,
951
+ "privacy_policy_url" => privacy_policy_url, "locale" => locale,
952
+ "headline" => headline, "description" => description,
953
+ "questions" => questions.to_a, "thank_you" => thank_you,
954
+ "accept_terms" => accept_terms
955
+ }
956
+ )
957
+ )
958
+ end
959
+
960
+ # GET /ads/lead-forms/{formId}. Requires ads:read.
961
+ def get(form_id)
962
+ @client.request("GET", "/ads/lead-forms/#{seg(form_id)}")
963
+ end
964
+
965
+ # PATCH /ads/lead-forms/{formId} - archive or open a form (status
966
+ # "archived" or "active"), or switch its lead sync. Requires ads:write.
967
+ def update(form_id, status: nil, sync_enabled: nil)
968
+ @client.request(
969
+ "PATCH", "/ads/lead-forms/#{seg(form_id)}",
970
+ json: Internal.drop_nil({ "status" => status, "sync_enabled" => sync_enabled })
971
+ )
972
+ end
973
+
974
+ # DELETE /ads/lead-forms/{formId} - archive a form (the leads already
975
+ # copied stay). Requires ads:write.
976
+ def delete(form_id)
977
+ @client.request("DELETE", "/ads/lead-forms/#{seg(form_id)}")
978
+ end
979
+
980
+ # POST /ads/lead-forms/{formId}/test-leads - a test lead (the next sync
981
+ # copies it, marked is_test). Requires ads:write.
982
+ def send_test_lead(form_id, fields: nil)
983
+ @client.request(
984
+ "POST", "/ads/lead-forms/#{seg(form_id)}/test-leads",
985
+ json: Internal.drop_nil({ "fields" => fields })
986
+ )
987
+ end
988
+ end
989
+
990
+ # Leads of the workspace, copied from the networks every 15 minutes
991
+ # (webhook lead.received). The answers are personal data.
992
+ class AdLeads
993
+ include AdPaths
994
+
995
+ def initialize(client)
996
+ @client = client
997
+ end
998
+
999
+ # GET /ads/leads - newest first (limit at most 200). Requires ads:read.
1000
+ def list(form_id: nil, status: nil, since: nil, until_time: nil, limit: nil, cursor: nil)
1001
+ @client.request(
1002
+ "GET", "/ads/leads",
1003
+ query: {
1004
+ "form_id" => form_id, "status" => status, "since" => since,
1005
+ "until" => until_time, "limit" => limit, "cursor" => cursor
1006
+ }
1007
+ )
1008
+ end
1009
+
1010
+ # GET /ads/leads/counts - "total" and "by_status". Requires ads:read.
1011
+ def counts(form_id: nil)
1012
+ @client.request("GET", "/ads/leads/counts", query: { "form_id" => form_id })
1013
+ end
1014
+
1015
+ # PATCH /ads/leads/{leadId} - status is "new", "contacted",
1016
+ # "qualified", "won", "lost" or "spam". Requires ads:write.
1017
+ def update(lead_id, status: nil, note: nil)
1018
+ @client.request(
1019
+ "PATCH", "/ads/leads/#{seg(lead_id)}",
1020
+ json: Internal.drop_nil({ "status" => status, "note" => note })
1021
+ )
1022
+ end
1023
+ end
1024
+
1025
+ # Pixels, conversion goals, custom conversions and server-side
1026
+ # conversion events.
1027
+ class AdConversions
1028
+ def initialize(client)
1029
+ @client = client
1030
+ end
1031
+
1032
+ # GET /ads/conversions/destinations - pixels, datasets, conversion tags
1033
+ # and conversion actions. Requires ads:read.
1034
+ def destinations(ad_account_id:)
1035
+ @client.request(
1036
+ "GET", "/ads/conversions/destinations", query: { "ad_account_id" => ad_account_id }
1037
+ )
1038
+ end
1039
+
1040
+ # GET /ads/conversions/goals - the events a campaign can optimise for.
1041
+ # Requires ads:read.
1042
+ def goals(ad_account_id:)
1043
+ @client.request("GET", "/ads/conversions/goals", query: { "ad_account_id" => ad_account_id })
1044
+ end
1045
+
1046
+ # POST /ads/conversions/custom - a custom conversion (a URL rule and/or
1047
+ # an event on a pixel). Requires ads:write.
1048
+ def create_custom(ad_account_id:, name:, destination_id:, event: nil, url_contains: nil)
1049
+ @client.request(
1050
+ "POST", "/ads/conversions/custom",
1051
+ json: Internal.drop_nil(
1052
+ {
1053
+ "ad_account_id" => ad_account_id, "name" => name,
1054
+ "destination_id" => destination_id, "event" => event,
1055
+ "url_contains" => url_contains
1056
+ }
1057
+ )
1058
+ )
1059
+ end
1060
+
1061
+ # POST /ads/conversions/events - up to 1,000 conversion events from
1062
+ # your server. Send the raw email and phone: OmniSocials normalizes
1063
+ # and SHA-256 hashes them before they leave and stores nothing.
1064
+ # Requires ads:write.
1065
+ def send_events(ad_account_id:, destination_id:, events:)
1066
+ @client.request(
1067
+ "POST", "/ads/conversions/events",
1068
+ json: {
1069
+ "ad_account_id" => ad_account_id, "destination_id" => destination_id,
1070
+ "events" => events.to_a
1071
+ }
1072
+ )
1073
+ end
1074
+ end
1075
+
1076
+ # Body of ads.insights.query and ads.reports.start.
1077
+ module AdInsightsBody
1078
+ private
1079
+
1080
+ def insights_body(ad_account_id:, level:, ids:, metrics:, breakdowns:, from:, to:, time_increment:)
1081
+ Internal.drop_nil(
1082
+ {
1083
+ "ad_account_id" => ad_account_id, "level" => level, "ids" => ids&.to_a,
1084
+ "metrics" => metrics&.to_a, "breakdowns" => breakdowns&.to_a,
1085
+ "from" => from, "to" => to, "time_increment" => time_increment
1086
+ }
1087
+ )
1088
+ end
1089
+ end
1090
+
1091
+ # Numbers: live from the network, per campaign or ad, over time, ranked,
1092
+ # and what needs attention.
1093
+ class AdInsights
1094
+ include AdPaths
1095
+ include AdInsightsBody
1096
+
1097
+ def initialize(client)
1098
+ @client = client
1099
+ end
1100
+
1101
+ # POST /ads/insights - live numbers from the network by day, ad,
1102
+ # country, age, gender, placement, device or platform (at most 2
1103
+ # breakdowns). Read-only. Requires ads:read.
1104
+ def query(ad_account_id:, level: nil, ids: nil, metrics: nil, breakdowns: nil, from: nil,
1105
+ to: nil, time_increment: nil)
1106
+ @client.request(
1107
+ "POST", "/ads/insights",
1108
+ json: insights_body(
1109
+ ad_account_id: ad_account_id, level: level, ids: ids, metrics: metrics,
1110
+ breakdowns: breakdowns, from: from, to: to, time_increment: time_increment
1111
+ )
1112
+ )
1113
+ end
1114
+
1115
+ # GET /ads/campaigns/{id}/analytics - numbers of an OmniSocials campaign
1116
+ # (breakdown: "ad" gives one row per ad). Requires ads:read.
1117
+ def campaign(campaign_id, from: nil, to: nil, breakdown: nil, time_increment: nil, metrics: nil)
1118
+ @client.request(
1119
+ "GET", "/ads/campaigns/#{seg(campaign_id)}/analytics",
1120
+ query: {
1121
+ "from" => from, "to" => to, "breakdown" => breakdown,
1122
+ "time_increment" => time_increment, "metrics" => list_param(metrics)
1123
+ }
1124
+ )
1125
+ end
1126
+
1127
+ # GET /ads/campaigns/{id}/ads/{adId}/analytics - numbers of one ad.
1128
+ # Requires ads:read.
1129
+ def ad(campaign_id, ad_id, from: nil, to: nil, breakdown: nil)
1130
+ @client.request(
1131
+ "GET", "#{ad_path(campaign_id, ad_id)}/analytics",
1132
+ query: { "from" => from, "to" => to, "breakdown" => breakdown }
1133
+ )
1134
+ end
1135
+
1136
+ # GET /ads/timeline - daily totals of the workspace (source "all",
1137
+ # "omnisocials" or "external"). Requires ads:read.
1138
+ def timeline(from: nil, to: nil, platform: nil, source: nil)
1139
+ @client.request(
1140
+ "GET", "/ads/timeline",
1141
+ query: { "from" => from, "to" => to, "platform" => platform, "source" => source }
1142
+ )
1143
+ end
1144
+
1145
+ # GET /ads/performance - campaigns or ads ranked by one metric.
1146
+ # Requires ads:read.
1147
+ def performance(level: nil, metric: nil, order: nil, limit: nil, min_impressions: nil,
1148
+ from: nil, to: nil, platform: nil)
1149
+ @client.request(
1150
+ "GET", "/ads/performance",
1151
+ query: {
1152
+ "level" => level, "metric" => metric, "order" => order, "limit" => limit,
1153
+ "min_impressions" => min_impressions, "from" => from, "to" => to,
1154
+ "platform" => platform
1155
+ }
1156
+ )
1157
+ end
1158
+
1159
+ # GET /ads/alerts - rejected ads, held campaigns, sign-in or payment
1160
+ # problems, no delivery. Requires ads:read.
1161
+ def alerts
1162
+ @client.request("GET", "/ads/alerts")
1163
+ end
1164
+ end
1165
+
1166
+ # Long reports that run in the background (up to 730 days).
1167
+ class AdReports
1168
+ include AdPaths
1169
+ include AdInsightsBody
1170
+
1171
+ def initialize(client)
1172
+ @client = client
1173
+ end
1174
+
1175
+ # GET /ads/insights/reports. Requires ads:read.
1176
+ def list
1177
+ @client.request("GET", "/ads/insights/reports")
1178
+ end
1179
+
1180
+ # POST /ads/insights/reports - start a report with the fields of
1181
+ # ads.insights.query; poll get. Requires ads:read.
1182
+ def start(ad_account_id:, level: nil, ids: nil, metrics: nil, breakdowns: nil, from: nil,
1183
+ to: nil, time_increment: nil)
1184
+ @client.request(
1185
+ "POST", "/ads/insights/reports",
1186
+ json: insights_body(
1187
+ ad_account_id: ad_account_id, level: level, ids: ids, metrics: metrics,
1188
+ breakdowns: breakdowns, from: from, to: to, time_increment: time_increment
1189
+ )
1190
+ )
1191
+ end
1192
+
1193
+ # GET /ads/insights/reports/{reportId} - "running", "done" (with rows)
1194
+ # or "failed". Requires ads:read.
1195
+ def get(report_id)
1196
+ @client.request("GET", "/ads/insights/reports/#{seg(report_id)}")
1197
+ end
1198
+ end
1199
+
1200
+ # Automated rules: check campaigns on a schedule and notify, pause,
1201
+ # activate or adjust the budget. A rule that notifies, pauses or lowers a
1202
+ # budget works with ads:write. A rule that can raise spend ("activate", a
1203
+ # positive "adjust_budget") needs a key with ads:spend (else 403
1204
+ # rule_raises_spend) and action "max_daily_budget", confirmed by the
1205
+ # person as confirm_max_daily_budget; it never acts on Google. create,
1206
+ # update and undo are not retried after a 5xx, a timeout or a lost
1207
+ # connection.
1208
+ class AdRules
1209
+ include AdPaths
1210
+
1211
+ def initialize(client)
1212
+ @client = client
1213
+ end
1214
+
1215
+ # GET /ads/rules. Requires ads:read.
1216
+ def list
1217
+ @client.request("GET", "/ads/rules")
1218
+ end
1219
+
1220
+ # POST /ads/rules - a new rule, off until enabled: true.
1221
+ #
1222
+ # A rule that can RAISE REAL AD SPEND ("activate", a positive
1223
+ # "adjust_budget") needs the person's own ceiling as
1224
+ # confirm_max_daily_budget and a key with ads:spend (else 403
1225
+ # rule_raises_spend). Preview it first with preview. Not retried after a
1226
+ # 5xx, a timeout or a lost connection: read the rules with list.
1227
+ # Requires ads:write.
1228
+ def create(name:, conditions:, action:, ad_account_id: nil, enabled: nil, scope: nil,
1229
+ every_minutes: nil, cooldown_minutes: nil, max_actions_per_run: nil,
1230
+ confirm_max_daily_budget: nil)
1231
+ @client.request(
1232
+ "POST", "/ads/rules",
1233
+ json: rule_body(
1234
+ name: name, conditions: conditions, action: action, ad_account_id: ad_account_id,
1235
+ enabled: enabled, scope: scope, every_minutes: every_minutes,
1236
+ cooldown_minutes: cooldown_minutes, max_actions_per_run: max_actions_per_run,
1237
+ confirm_max_daily_budget: confirm_max_daily_budget
1238
+ ),
1239
+ retry_on: :rate_limit
1240
+ )
1241
+ end
1242
+
1243
+ # GET /ads/rules/templates - ready-made rules. Requires ads:read.
1244
+ def templates
1245
+ @client.request("GET", "/ads/rules/templates")
1246
+ end
1247
+
1248
+ # POST /ads/rules/preview - what an unsaved rule would match and do
1249
+ # now. Requires ads:read.
1250
+ def preview(conditions:, action:, name: nil, ad_account_id: nil, scope: nil)
1251
+ @client.request(
1252
+ "POST", "/ads/rules/preview",
1253
+ json: Internal.drop_nil(
1254
+ {
1255
+ "name" => name, "ad_account_id" => ad_account_id, "scope" => scope,
1256
+ "conditions" => conditions.to_a, "action" => action
1257
+ }
1258
+ )
1259
+ )
1260
+ end
1261
+
1262
+ # GET /ads/rules/activity - every change the rules made, with before
1263
+ # and after. Requires ads:read.
1264
+ def activity(rule_id: nil, limit: nil)
1265
+ @client.request("GET", "/ads/rules/activity", query: { "rule_id" => rule_id, "limit" => limit })
1266
+ end
1267
+
1268
+ # POST /ads/rules/activity/{activityId}/undo - undo a change a rule
1269
+ # made.
1270
+ #
1271
+ # Undo of a pause or of a budget cut RESTARTS or RAISES REAL AD SPEND:
1272
+ # pass the amount as confirm_budget_amount after the person agreed, with
1273
+ # a key that has ads:spend (else, and on Google always, 403
1274
+ # start_in_app). Not retried after a 5xx, a timeout or a lost
1275
+ # connection. Requires ads:write.
1276
+ def undo(activity_id, confirm_budget_amount: nil)
1277
+ @client.request(
1278
+ "POST", "/ads/rules/activity/#{seg(activity_id)}/undo",
1279
+ json: Internal.drop_nil({ "confirm_budget_amount" => confirm_budget_amount }),
1280
+ retry_on: :rate_limit
1281
+ )
1282
+ end
1283
+
1284
+ # GET /ads/rules/{ruleId}. Requires ads:read.
1285
+ def get(rule_id)
1286
+ @client.request("GET", "/ads/rules/#{seg(rule_id)}")
1287
+ end
1288
+
1289
+ # PATCH /ads/rules/{ruleId} - change a rule (also enabled). A changed
1290
+ # action that can raise spend needs confirm_max_daily_budget again and a
1291
+ # key with ads:spend (else 403 rule_raises_spend). Not retried after a
1292
+ # 5xx, a timeout or a lost connection. Requires ads:write.
1293
+ def update(rule_id, name: nil, conditions: nil, action: nil, ad_account_id: nil, enabled: nil,
1294
+ scope: nil, every_minutes: nil, cooldown_minutes: nil, max_actions_per_run: nil,
1295
+ confirm_max_daily_budget: nil)
1296
+ @client.request(
1297
+ "PATCH", "/ads/rules/#{seg(rule_id)}",
1298
+ json: rule_body(
1299
+ name: name, conditions: conditions, action: action, ad_account_id: ad_account_id,
1300
+ enabled: enabled, scope: scope, every_minutes: every_minutes,
1301
+ cooldown_minutes: cooldown_minutes, max_actions_per_run: max_actions_per_run,
1302
+ confirm_max_daily_budget: confirm_max_daily_budget
1303
+ ),
1304
+ retry_on: :rate_limit
1305
+ )
1306
+ end
1307
+
1308
+ # DELETE /ads/rules/{ruleId}. Requires ads:write.
1309
+ def delete(rule_id)
1310
+ @client.request("DELETE", "/ads/rules/#{seg(rule_id)}")
1311
+ end
1312
+
1313
+ # POST /ads/rules/{ruleId}/preview - what a saved rule would match and
1314
+ # do now. Requires ads:read.
1315
+ def preview_saved(rule_id)
1316
+ @client.request("POST", "/ads/rules/#{seg(rule_id)}/preview")
1317
+ end
1318
+
1319
+ # GET /ads/rules/{ruleId}/runs. Requires ads:read.
1320
+ def runs(rule_id, limit: nil)
1321
+ @client.request("GET", "/ads/rules/#{seg(rule_id)}/runs", query: { "limit" => limit })
1322
+ end
1323
+
1324
+ private
1325
+
1326
+ def rule_body(name:, conditions:, action:, ad_account_id:, enabled:, scope:, every_minutes:,
1327
+ cooldown_minutes:, max_actions_per_run:, confirm_max_daily_budget:)
1328
+ Internal.drop_nil(
1329
+ {
1330
+ "name" => name, "ad_account_id" => ad_account_id, "enabled" => enabled,
1331
+ "scope" => scope, "conditions" => conditions&.to_a, "action" => action,
1332
+ "every_minutes" => every_minutes, "cooldown_minutes" => cooldown_minutes,
1333
+ "max_actions_per_run" => max_actions_per_run,
1334
+ "confirm_max_daily_budget" => confirm_max_daily_budget
1335
+ }
1336
+ )
1337
+ end
1338
+ end
1339
+
1340
+ # Your own numbers per campaign and day (qualified leads, sales,
1341
+ # revenue). Rules read them as results.<metric>.
1342
+ class AdResults
1343
+ include AdPaths
1344
+
1345
+ def initialize(client)
1346
+ @client = client
1347
+ end
1348
+
1349
+ # GET /ads/campaign-results. Requires ads:read.
1350
+ def list(from: nil, to: nil, campaign_id: nil, metric: nil)
1351
+ @client.request(
1352
+ "GET", "/ads/campaign-results",
1353
+ query: { "from" => from, "to" => to, "campaign_id" => campaign_id, "metric" => metric }
1354
+ )
1355
+ end
1356
+
1357
+ # POST /ads/campaign-results - up to 5,000 rows of "day", "metric",
1358
+ # "value" and the campaign ("campaign_id", "external_campaign_id" +
1359
+ # "platform", "utm_campaign" or "campaign_name"). Sending a day again
1360
+ # replaces it. Requires ads:write.
1361
+ def upload(rows)
1362
+ @client.request("POST", "/ads/campaign-results", json: { "rows" => rows.to_a })
1363
+ end
1364
+
1365
+ # GET /ads/campaign-results/totals - totals over a period, with the
1366
+ # formulas. Requires ads:read.
1367
+ def totals(from: nil, to: nil, campaign_id: nil)
1368
+ @client.request(
1369
+ "GET", "/ads/campaign-results/totals",
1370
+ query: { "from" => from, "to" => to, "campaign_id" => campaign_id }
1371
+ )
1372
+ end
1373
+
1374
+ # GET /ads/campaign-results/metrics - your metric names and formulas.
1375
+ # Requires ads:read.
1376
+ def metrics
1377
+ @client.request("GET", "/ads/campaign-results/metrics")
1378
+ end
1379
+
1380
+ # PUT /ads/campaign-results/metrics/{key} - name a metric or define a
1381
+ # formula (unit "number", "money" or "percent"). Requires ads:write.
1382
+ def put_metric(key, label: nil, unit: nil, formula: nil)
1383
+ @client.request(
1384
+ "PUT", "/ads/campaign-results/metrics/#{seg(key)}",
1385
+ json: Internal.drop_nil({ "label" => label, "unit" => unit, "formula" => formula })
1386
+ )
1387
+ end
1388
+ end
1389
+
1390
+ # The network's own image and video library of an ad account. Use an id
1391
+ # in an ad as network[<network>]["media_ref"].
1392
+ class AdMedia
1393
+ include AdPaths
1394
+
1395
+ def initialize(client)
1396
+ @client = client
1397
+ end
1398
+
1399
+ # GET /ads/media. Requires ads:read.
1400
+ def list(ad_account_id:, type: nil, cursor: nil)
1401
+ @client.request(
1402
+ "GET", "/ads/media",
1403
+ query: { "ad_account_id" => ad_account_id, "type" => type, "cursor" => cursor }
1404
+ )
1405
+ end
1406
+
1407
+ # POST /ads/media - upload an image or video to the network ahead of an
1408
+ # ad. Requires ads:write.
1409
+ def upload(ad_account_id:, type:, url:, name: nil)
1410
+ @client.request(
1411
+ "POST", "/ads/media",
1412
+ json: Internal.drop_nil(
1413
+ { "ad_account_id" => ad_account_id, "type" => type, "url" => url, "name" => name }
1414
+ )
1415
+ )
1416
+ end
1417
+
1418
+ # GET /ads/media/{mediaId} - the processing status of an upload.
1419
+ # Requires ads:read.
1420
+ def get(media_id, ad_account_id:, type: nil)
1421
+ @client.request(
1422
+ "GET", "/ads/media/#{seg(media_id)}",
1423
+ query: { "ad_account_id" => ad_account_id, "type" => type }
1424
+ )
1425
+ end
1426
+
1427
+ # DELETE /ads/media/{mediaId}. Requires ads:write.
1428
+ def delete(media_id, ad_account_id:, type:)
1429
+ @client.request(
1430
+ "DELETE", "/ads/media/#{seg(media_id)}",
1431
+ query: { "ad_account_id" => ad_account_id, "type" => type }
1432
+ )
1433
+ end
1434
+ end
1435
+
1436
+ # Previews drawn by the network.
1437
+ class AdPreviews
1438
+ include AdPaths
1439
+
1440
+ def initialize(client)
1441
+ @client = client
1442
+ end
1443
+
1444
+ # POST /ads/previews - previews of a new ad (the shape of a draft ad).
1445
+ # Read-only. Requires ads:read.
1446
+ def create(ad_account_id:, ad:, placements: nil, objective: nil)
1447
+ @client.request(
1448
+ "POST", "/ads/previews",
1449
+ json: Internal.drop_nil(
1450
+ {
1451
+ "ad_account_id" => ad_account_id, "ad" => ad,
1452
+ "placements" => placements&.to_a, "objective" => objective
1453
+ }
1454
+ )
1455
+ )
1456
+ end
1457
+
1458
+ # GET /ads/campaigns/{id}/ads/{adId}/previews - previews of an existing
1459
+ # ad. Requires ads:read.
1460
+ def for_ad(campaign_id, ad_id, placements: nil)
1461
+ @client.request(
1462
+ "GET", "#{ad_path(campaign_id, ad_id)}/previews",
1463
+ query: { "placements" => list_param(placements) }
1464
+ )
1465
+ end
1466
+ end
1467
+
1468
+ # Partnership ads with creators (Meta).
1469
+ class AdPartnership
1470
+ def initialize(client)
1471
+ @client = client
1472
+ end
1473
+
1474
+ # GET /ads/partnership/content - creator posts you may run as
1475
+ # partnership ads. Requires ads:read.
1476
+ def list_content(ad_account_id:)
1477
+ @client.request("GET", "/ads/partnership/content", query: { "ad_account_id" => ad_account_id })
1478
+ end
1479
+
1480
+ # GET /ads/partnership/permissions. Requires ads:read.
1481
+ def list_permissions(ad_account_id:)
1482
+ @client.request(
1483
+ "GET", "/ads/partnership/permissions", query: { "ad_account_id" => ad_account_id }
1484
+ )
1485
+ end
1486
+
1487
+ # POST /ads/partnership/permissions - ask for or set a permission;
1488
+ # Meta's fields pass through as keyword arguments. Requires ads:write.
1489
+ def set_permission(ad_account_id:, **fields)
1490
+ @client.request(
1491
+ "POST", "/ads/partnership/permissions",
1492
+ json: stringify(fields).merge("ad_account_id" => ad_account_id)
1493
+ )
1494
+ end
1495
+
1496
+ private
1497
+
1498
+ def stringify(fields)
1499
+ fields.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
1500
+ end
1501
+ end
1502
+
1503
+ # Ad account admin: identities, health, finance, settings, people,
1504
+ # change log, businesses, DSA and the manager hierarchy. account_id is
1505
+ # the OmniSocials ad account id.
1506
+ class AdAccountsAdmin
1507
+ include AdPaths
1508
+
1509
+ def initialize(client)
1510
+ @client = client
1511
+ end
1512
+
1513
+ # GET /ads/accounts/{accountId}/identities - Pages, profiles and
1514
+ # identities an ad can run as. Requires ads:read.
1515
+ def identities(account_id)
1516
+ @client.request("GET", account_path(account_id, "identities"))
1517
+ end
1518
+
1519
+ # GET /ads/accounts/{accountId}/health - status, payment, spend limit,
1520
+ # Page and pixel before an ad starts. A check that cannot be read is
1521
+ # "unknown"; failed checks carry a "fix_url". Requires ads:read.
1522
+ def health(account_id)
1523
+ @client.request("GET", account_path(account_id, "health"))
1524
+ end
1525
+
1526
+ # GET /ads/accounts/{accountId}/finance - spend limit, amount spent,
1527
+ # balance and payment method. Requires ads:read.
1528
+ def finance(account_id)
1529
+ @client.request("GET", account_path(account_id, "finance"))
1530
+ end
1531
+
1532
+ # PATCH /ads/accounts/{accountId}/settings - spend cap, DSA payer and
1533
+ # beneficiary, name.
1534
+ #
1535
+ # A higher spend_cap ALLOWS MORE REAL AD SPEND: pass the new cap as
1536
+ # confirm_budget_amount after the person agreed; spend_cap: nil removes
1537
+ # the cap and needs confirm_budget_amount: "remove". A spend cap change:
1538
+ # needs a key with the opt-in ads:spend scope ("Start ads"); without it,
1539
+ # and on Google (api_draft_only) always, the call answers 403
1540
+ # start_in_app with the page where a person does it in the app. The name
1541
+ # and the DSA names stay open. Not retried after a 5xx, a timeout or a
1542
+ # lost connection. Requires ads:write.
1543
+ def update_settings(account_id, spend_cap: OmniSocials::NOT_GIVEN, dsa_beneficiary: nil, dsa_payor: nil,
1544
+ name: nil, confirm_budget_amount: nil)
1545
+ body = Internal.drop_nil(
1546
+ {
1547
+ "dsa_beneficiary" => dsa_beneficiary, "dsa_payor" => dsa_payor, "name" => name,
1548
+ "confirm_budget_amount" => confirm_budget_amount
1549
+ }
1550
+ )
1551
+ body["spend_cap"] = spend_cap unless spend_cap.is_a?(NotGiven)
1552
+ @client.request(
1553
+ "PATCH", account_path(account_id, "settings"), json: body, retry_on: :rate_limit
1554
+ )
1555
+ end
1556
+
1557
+ # GET /ads/accounts/{accountId}/users - people with access. Requires
1558
+ # ads:read.
1559
+ def list_users(account_id)
1560
+ @client.request("GET", account_path(account_id, "users"))
1561
+ end
1562
+
1563
+ # POST /ads/accounts/{accountId}/users - give a person access
1564
+ # (LinkedIn). Requires ads:write.
1565
+ def add_user(account_id, role:, email: nil, member_id: nil)
1566
+ @client.request(
1567
+ "POST", account_path(account_id, "users"),
1568
+ json: Internal.drop_nil({ "email" => email, "member_id" => member_id, "role" => role })
1569
+ )
1570
+ end
1571
+
1572
+ # DELETE /ads/accounts/{accountId}/users/{userId} - remove a person's
1573
+ # access. Requires ads:write.
1574
+ def remove_user(account_id, user_id)
1575
+ @client.request("DELETE", account_path(account_id, "users/#{seg(user_id)}"))
1576
+ end
1577
+
1578
+ # GET /ads/accounts/{accountId}/activity - the change log of the ad
1579
+ # account. Requires ads:read.
1580
+ def activity(account_id, since: nil, until_time: nil, cursor: nil)
1581
+ @client.request(
1582
+ "GET", account_path(account_id, "activity"),
1583
+ query: { "since" => since, "until" => until_time, "cursor" => cursor }
1584
+ )
1585
+ end
1586
+
1587
+ # GET /ads/accounts/{accountId}/businesses - Meta business portfolios
1588
+ # and TikTok Business Centers. Requires ads:read.
1589
+ def businesses(account_id)
1590
+ @client.request("GET", account_path(account_id, "businesses"))
1591
+ end
1592
+
1593
+ # GET /ads/accounts/{accountId}/dsa - the EU DSA payer and beneficiary
1594
+ # (Meta). Requires ads:read.
1595
+ def dsa(account_id)
1596
+ @client.request("GET", account_path(account_id, "dsa"))
1597
+ end
1598
+
1599
+ # GET /ads/accounts/{accountId}/hierarchy - the manager account
1600
+ # hierarchy (Google). Requires ads:read.
1601
+ def hierarchy(account_id)
1602
+ @client.request("GET", account_path(account_id, "hierarchy"))
1603
+ end
1604
+ end
1605
+
1606
+ # Meta reach and frequency buying. A prediction spends nothing; a
1607
+ # reservation does.
1608
+ class AdReachFrequency
1609
+ include AdPaths
1610
+
1611
+ def initialize(client)
1612
+ @client = client
1613
+ end
1614
+
1615
+ # POST /ads/reach-frequency - a prediction (objective "awareness",
1616
+ # "engagement" or "video_views"; exactly one country in targeting;
1617
+ # budget in major units or reach). It spends nothing; Meta needs the
1618
+ # reach and frequency capability on the ad account. Requires
1619
+ # ads:write.
1620
+ def create(ad_account_id:, objective:, targeting:, start_at:, end_at:, budget: nil, reach: nil,
1621
+ frequency_cap: nil, frequency_interval_days: nil)
1622
+ @client.request(
1623
+ "POST", "/ads/reach-frequency",
1624
+ json: Internal.drop_nil(
1625
+ {
1626
+ "ad_account_id" => ad_account_id, "objective" => objective, "targeting" => targeting,
1627
+ "start_at" => start_at, "end_at" => end_at, "budget" => budget, "reach" => reach,
1628
+ "frequency_cap" => frequency_cap, "frequency_interval_days" => frequency_interval_days
1629
+ }
1630
+ )
1631
+ )
1632
+ end
1633
+
1634
+ # GET /ads/reach-frequency/{predictionId}. Requires ads:read.
1635
+ def get(prediction_id, ad_account_id:)
1636
+ @client.request(
1637
+ "GET", "/ads/reach-frequency/#{seg(prediction_id)}",
1638
+ query: { "ad_account_id" => ad_account_id }
1639
+ )
1640
+ end
1641
+
1642
+ # DELETE /ads/reach-frequency/{predictionId} - cancel a prediction or a
1643
+ # reservation. Requires ads:write.
1644
+ def cancel(prediction_id, ad_account_id:)
1645
+ @client.request(
1646
+ "DELETE", "/ads/reach-frequency/#{seg(prediction_id)}",
1647
+ query: { "ad_account_id" => ad_account_id }
1648
+ )
1649
+ end
1650
+
1651
+ # POST /ads/reach-frequency/{predictionId}/reserve - COMMITS REAL AD
1652
+ # SPEND: pass the prediction's budget as confirm_budget_amount after the
1653
+ # person agreed. Needs a key with the opt-in ads:spend scope ("Start
1654
+ # ads"); without it, and on Google (api_draft_only) always, the call
1655
+ # answers 403 start_in_app with the page where a person does it in the
1656
+ # app. Not retried after a 5xx, a timeout or a lost connection: read the
1657
+ # prediction with get. Requires ads:write.
1658
+ def reserve(prediction_id, ad_account_id:, confirm_budget_amount:)
1659
+ @client.request(
1660
+ "POST", "/ads/reach-frequency/#{seg(prediction_id)}/reserve",
1661
+ json: { "ad_account_id" => ad_account_id, "confirm_budget_amount" => confirm_budget_amount },
1662
+ retry_on: :rate_limit
1663
+ )
1664
+ end
1665
+ end
1666
+
1667
+ # A/B tests and lift studies (Meta).
1668
+ class AdStudies
1669
+ def initialize(client)
1670
+ @client = client
1671
+ end
1672
+
1673
+ # GET /ads/studies. Requires ads:read.
1674
+ def list(ad_account_id:)
1675
+ @client.request("GET", "/ads/studies", query: { "ad_account_id" => ad_account_id })
1676
+ end
1677
+
1678
+ # POST /ads/studies - an A/B test between existing campaigns or ad sets;
1679
+ # Meta's fields pass through as keyword arguments. Needs a key with the
1680
+ # opt-in ads:spend scope ("Start ads"); without it, and on Google
1681
+ # (api_draft_only) always, the call answers 403 start_in_app with the
1682
+ # page where a person does it in the app. Requires ads:write.
1683
+ def create(ad_account_id:, **fields)
1684
+ body = fields.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
1685
+ @client.request("POST", "/ads/studies", json: body.merge("ad_account_id" => ad_account_id))
1686
+ end
1687
+ end
1688
+
1689
+ # Planned budget increases of a campaign for high-demand periods (Meta).
1690
+ class AdBudgetSchedules
1691
+ include AdPaths
1692
+
1693
+ def initialize(client)
1694
+ @client = client
1695
+ end
1696
+
1697
+ # GET /ads/campaigns/{id}/budget-schedules. Requires ads:read.
1698
+ def list(campaign_id)
1699
+ @client.request("GET", "/ads/campaigns/#{seg(campaign_id)}/budget-schedules")
1700
+ end
1701
+
1702
+ # POST /ads/campaigns/{id}/budget-schedules - plan a budget increase
1703
+ # (budget_increase: { "type" => "absolute" | "multiplier", "value" =>
1704
+ # ... }).
1705
+ #
1706
+ # NEW REAL AD SPEND in that period: pass the increase per day (absolute)
1707
+ # or the campaign budget times the multiplier as confirm_budget_amount
1708
+ # after the person agreed. Needs a key with the opt-in ads:spend scope
1709
+ # ("Start ads"); without it, and on Google (api_draft_only) always, the
1710
+ # call answers 403 start_in_app with the page where a person does it in
1711
+ # the app. Not retried after a 5xx, a timeout or a lost connection: read
1712
+ # the schedules with list. Requires ads:write.
1713
+ def create(campaign_id, start_at:, end_at:, budget_increase:, confirm_budget_amount:)
1714
+ @client.request(
1715
+ "POST", "/ads/campaigns/#{seg(campaign_id)}/budget-schedules",
1716
+ json: {
1717
+ "start_at" => start_at, "end_at" => end_at, "budget_increase" => budget_increase,
1718
+ "confirm_budget_amount" => confirm_budget_amount
1719
+ },
1720
+ retry_on: :rate_limit
1721
+ )
1722
+ end
1723
+
1724
+ # DELETE /ads/campaigns/{id}/budget-schedules/{scheduleId}. Requires
1725
+ # ads:write.
1726
+ def delete(campaign_id, schedule_id)
1727
+ @client.request(
1728
+ "DELETE", "/ads/campaigns/#{seg(campaign_id)}/budget-schedules/#{seg(schedule_id)}"
1729
+ )
1730
+ end
1731
+ end
1732
+
1733
+ # Google reports (read-only; every API caller stops at the draft on
1734
+ # Google).
1735
+ class AdGoogle
1736
+ include AdPaths
1737
+
1738
+ def initialize(client)
1739
+ @client = client
1740
+ end
1741
+
1742
+ # GET /ads/google/search-terms. Requires ads:read.
1743
+ def search_terms(ad_account_id:, campaign_id: nil, external_campaign_id: nil, from: nil,
1744
+ to: nil, limit: nil)
1745
+ @client.request(
1746
+ "GET", "/ads/google/search-terms",
1747
+ query: {
1748
+ "ad_account_id" => ad_account_id, "campaign_id" => campaign_id,
1749
+ "external_campaign_id" => external_campaign_id, "from" => from, "to" => to,
1750
+ "limit" => limit
1751
+ }
1752
+ )
1753
+ end
1754
+
1755
+ # GET /ads/google/recommendations. Requires ads:read.
1756
+ def recommendations(ad_account_id:, types: nil)
1757
+ @client.request(
1758
+ "GET", "/ads/google/recommendations",
1759
+ query: { "ad_account_id" => ad_account_id, "types" => list_param(types) }
1760
+ )
1761
+ end
1762
+
1763
+ # GET /ads/google/keywords - search keywords and negative keywords.
1764
+ # Requires ads:read.
1765
+ def keywords(ad_account_id:, external_campaign_id: nil, external_ad_set_id: nil)
1766
+ @client.request(
1767
+ "GET", "/ads/google/keywords",
1768
+ query: {
1769
+ "ad_account_id" => ad_account_id, "external_campaign_id" => external_campaign_id,
1770
+ "external_ad_set_id" => external_ad_set_id
1771
+ }
1772
+ )
1773
+ end
1774
+
1775
+ # GET /ads/google/assets - sitelinks, callouts and structured snippets.
1776
+ # Requires ads:read.
1777
+ def assets(ad_account_id:, type: nil)
1778
+ @client.request(
1779
+ "GET", "/ads/google/assets", query: { "ad_account_id" => ad_account_id, "type" => type }
1780
+ )
1781
+ end
1782
+
1783
+ # GET /ads/google/shared-budgets. Requires ads:read.
1784
+ def shared_budgets(ad_account_id:)
1785
+ @client.request("GET", "/ads/google/shared-budgets", query: { "ad_account_id" => ad_account_id })
1786
+ end
1787
+
1788
+ # GET /ads/google/bid-strategies - portfolio bid strategies. Requires
1789
+ # ads:read.
1790
+ def bid_strategies(ad_account_id:)
1791
+ @client.request("GET", "/ads/google/bid-strategies", query: { "ad_account_id" => ad_account_id })
1792
+ end
1793
+
1794
+ # GET /ads/google/ad-schedule - the days and hours of a Google
1795
+ # campaign. Requires ads:read.
1796
+ def ad_schedule(ad_account_id:, external_campaign_id:)
1797
+ @client.request(
1798
+ "GET", "/ads/google/ad-schedule",
1799
+ query: { "ad_account_id" => ad_account_id, "external_campaign_id" => external_campaign_id }
1800
+ )
1801
+ end
1802
+
1803
+ # GET /ads/google/labels. Requires ads:read.
1804
+ def labels(ad_account_id:)
1805
+ @client.request("GET", "/ads/google/labels", query: { "ad_account_id" => ad_account_id })
1806
+ end
1807
+
1808
+ # GET /ads/google/local-services-leads. Requires ads:read.
1809
+ def local_services_leads(ad_account_id:, since: nil)
1810
+ @client.request(
1811
+ "GET", "/ads/google/local-services-leads",
1812
+ query: { "ad_account_id" => ad_account_id, "since" => since }
1813
+ )
1814
+ end
1815
+ end
1816
+ end
1817
+ end