posthubify 0.1.0

data/lib/posthubify/resources/ads.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Posthubify
+  # Ads lifecycle (Node sdk .ads): accounts, campaigns, audiences,
+  # lead-gen, conversions (CAPI), targeting, ad-set/ad hierarchy, comments, catalogs.
+  class AdsResource
+    def initialize(http)
+      @http = http
+    end
+
+    # Connected ad accounts.
+    def accounts
+      @http.data('GET', '/ads/accounts')
+    end
+
+    # ── Headless ADS OAuth connect (D8 cp4) — tempToken start/status. ──
+    # Start headless ADS OAuth → {tempToken, authUrl}: open authUrl in a browser, then poll status.
+    def connect_oauth_start(platform, profile_id: nil, label: nil)
+      @http.data('POST', '/ads/connect/oauth/start', body: { 'platform' => platform, 'profileId' => profile_id, 'label' => label })
+    end
+
+    # Headless ADS OAuth status (poll): pending | connected (+account) | error.
+    def connect_oauth_status(temp_token)
+      @http.data('GET', '/ads/connect/oauth/status', query: { 'tempToken' => temp_token })
+    end
+
+    # This ad account's platform capabilities (pre-discovery instead of trial-and-error).
+    def capabilities(id)
+      @http.data('GET', "/ads/accounts/#{id}/capabilities")
+    end
+
+    # Platform-side ad accounts (one login → multiple accounts; for select).
+    def customers(id)
+      @http.data('GET', "/ads/accounts/#{id}/customers")
+    end
+
+    # Select the active ad account for this login.
+    def select(id, ad_account_id)
+      @http.data('POST', "/ads/accounts/#{id}/select", body: { 'adAccountId' => ad_account_id })
+    end
+
+    # Billing/publishing readiness — check before promote.
+    def readiness(id)
+      @http.data('GET', "/ads/accounts/#{id}/readiness")
+    end
+
+    # List campaigns (optional status filter).
+    def campaigns(id, status: nil)
+      @http.data('GET', "/ads/accounts/#{id}/campaigns", query: { 'status' => status })
+    end
+
+    # Create a campaign. input is a camelCase-keyed Hash (name/budget/budgetType/objective/status).
+    def create_campaign(id, input, idempotency_key: nil)
+      @http.data('POST', "/ads/accounts/#{id}/campaigns", body: input, idempotency_key: idempotency_key)
+    end
+
+    # Single campaign status (enabled/paused).
+    def set_campaign_status(id, campaign_id, status)
+      @http.data('POST', "/ads/accounts/#{id}/campaigns/#{campaign_id}/status", body: { 'status' => status })
+    end
+
+    # Bulk status (≤50 campaigns) — returns a per-campaign ok/error result.
+    def bulk_campaign_status(id, campaign_ids, status)
+      @http.data('POST', "/ads/accounts/#{id}/campaigns/bulk-status", body: { 'campaignIds' => campaign_ids, 'status' => status })
+    end
+
+    # Duplicate a campaign — the copy starts PAUSED (to avoid accidental spend).
+    def duplicate_campaign(id, campaign_id, name = nil)
+      body = name ? { 'name' => name } : {}
+      @http.data('POST', "/ads/accounts/#{id}/campaigns/#{campaign_id}/duplicate", body: body)
+    end
+
+    # Delete a campaign.
+    def delete_campaign(id, campaign_id)
+      @http.data('DELETE', "/ads/accounts/#{id}/campaigns/#{campaign_id}")
+    end
+
+    # Campaign's daily performance timeline (from report rows).
+    def campaign_timeline(id, campaign_id, since: nil, until_: nil)
+      @http.data('GET', "/ads/accounts/#{id}/campaigns/#{campaign_id}/timeline", query: { 'since' => since, 'until' => until_ })
+    end
+
+    # Account report rows (optional date range).
+    def report(id, since: nil, until_: nil)
+      @http.data('GET', "/ads/accounts/#{id}/report", query: { 'since' => since, 'until' => until_ })
+    end
+
+    # Creative targets (pages/boards).
+    def creative_targets(id)
+      @http.data('GET', "/ads/accounts/#{id}/creative-targets")
+    end
+
+    # Create an ad with a creative. mediaUrl may only come from your own media store (SSRF protection).
+    def promote(id, input, idempotency_key: nil)
+      @http.data('POST', "/ads/accounts/#{id}/promote", body: input, idempotency_key: idempotency_key)
+    end
+
+    # ---- Audiences / Lead-gen / Conversions / Pixels / Targeting (Meta ilk) ----
+
+    # Custom audiences.
+    def audiences(id)
+      @http.data('GET', "/ads/accounts/#{id}/audiences")
+    end
+
+    # Create an audience (name/description).
+    def create_audience(id, input)
+      @http.data('POST', "/ads/accounts/#{id}/audiences", body: input)
+    end
+
+    # Delete an audience.
+    def delete_audience(id, audience_id)
+      @http.data('DELETE', "/ads/accounts/#{id}/audiences/#{audience_id}")
+    end
+
+    # Upload members to an audience (≤10k/request). Raw emails/phones → server SHA-256; if pre-hashed, use the hashed* fields.
+    def upload_audience_users(id, audience_id, input)
+      @http.data('POST', "/ads/accounts/#{id}/audiences/#{audience_id}/users", body: input)
+    end
+
+    # Lead-gen forms.
+    def lead_forms(id)
+      @http.data('GET', "/ads/accounts/#{id}/lead-forms")
+    end
+
+    # A form's lead records (optional limit).
+    def leads(id, form_id, limit: nil)
+      @http.data('GET', "/ads/accounts/#{id}/lead-forms/#{form_id}/leads", query: { 'limit' => limit })
+    end
+
+    # Conversion pixels.
+    def pixels(id)
+      @http.data('GET', "/ads/accounts/#{id}/pixels")
+    end
+
+    # CAPI relay (≤1000 events) — raw email/phone is hashed on the server; use testEventCode for a safe trial.
+    def send_conversions(id, input)
+      @http.data('POST', "/ads/accounts/#{id}/conversions", body: input)
+    end
+
+    # Interest targeting search.
+    def search_interests(id, q)
+      @http.data('GET', "/ads/accounts/#{id}/targeting/interests", query: { 'q' => q })
+    end
+
+    # Reach estimate (targeting is a camelCase-keyed Hash).
+    def reach_estimate(id, targeting)
+      @http.data('POST', "/ads/accounts/#{id}/reach-estimate", body: targeting)
+    end
+
+    # ---- Campaign update + ad-set/ad hierarchy (C-T3) ----
+
+    # Update a campaign (patch: name/budget/budgetType/bidAmount/status).
+    def update_campaign(id, campaign_id, patch)
+      @http.data('PATCH', "/ads/accounts/#{id}/campaigns/#{campaign_id}", body: patch)
+    end
+
+    # A campaign's ad sets.
+    def ad_sets(id, campaign_id)
+      @http.data('GET', "/ads/accounts/#{id}/campaigns/#{campaign_id}/adsets")
+    end
+
+    # Campaign → ad sets → ads hierarchy (single call).
+    def campaign_tree(id, campaign_id)
+      @http.data('GET', "/ads/accounts/#{id}/campaigns/#{campaign_id}/tree")
+    end
+
+    # An ad set's ads.
+    def ads(id, ad_set_id)
+      @http.data('GET', "/ads/accounts/#{id}/adsets/#{ad_set_id}/ads")
+    end
+
+    # Ad set status (enabled/paused).
+    def set_ad_set_status(id, ad_set_id, status)
+      @http.data('POST', "/ads/accounts/#{id}/adsets/#{ad_set_id}/status", body: { 'status' => status })
+    end
+
+    # Delete an ad set.
+    def delete_ad_set(id, ad_set_id)
+      @http.data('DELETE', "/ads/accounts/#{id}/adsets/#{ad_set_id}")
+    end
+
+    # Ad status (enabled/paused).
+    def set_ad_status(id, ad_id, status)
+      @http.data('POST', "/ads/accounts/#{id}/ads/#{ad_id}/status", body: { 'status' => status })
+    end
+
+    # Delete an ad.
+    def delete_ad(id, ad_id)
+      @http.data('DELETE', "/ads/accounts/#{id}/ads/#{ad_id}")
+    end
+
+    # ---- Ads-comment moderation (C-T4) ----
+
+    # An ad's comments.
+    def ad_comments(id, ad_id)
+      @http.data('GET', "/ads/accounts/#{id}/ads/#{ad_id}/comments")
+    end
+
+    # Reply to an ad comment.
+    def reply_ad_comment(id, comment_id, message)
+      @http.data('POST', "/ads/accounts/#{id}/comments/#{comment_id}/reply", body: { 'message' => message })
+    end
+
+    # Hide/show an ad comment (default hide).
+    def hide_ad_comment(id, comment_id, hidden = true)
+      @http.data('POST', "/ads/accounts/#{id}/comments/#{comment_id}/hide", body: { 'hidden' => hidden })
+    end
+
+    # Delete an ad comment.
+    def delete_ad_comment(id, comment_id)
+      @http.data('DELETE', "/ads/accounts/#{id}/comments/#{comment_id}")
+    end
+
+    # ---- Catalogs (C-T5) ----
+
+    # Product catalogs.
+    def catalogs(id)
+      @http.data('GET', "/ads/accounts/#{id}/catalogs")
+    end
+
+    # A catalog's product sets.
+    def product_sets(id, catalog_id)
+      @http.data('GET', "/ads/accounts/#{id}/catalogs/#{catalog_id}/product-sets")
+    end
+  end
+end

data/lib/posthubify/resources/analytics.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Posthubify
+  # Derived insights (Node sdk .insights) — from stored history, no live platform call.
+  class InsightsResource
+    def initialize(http)
+      @http = http
+    end
+
+    # Best posting times (slots sorted by average engagement; dayOfWeek 1=Mon..7=Sun, UTC).
+    def best_time(days: nil, platform: nil, account_id: nil)
+      @http.data('GET', '/analytics/best-time',
+                 query: { 'days' => days, 'platform' => platform, 'accountId' => account_id })
+    end
+
+    # Content lifetime curve (day buckets; avgPctOfFinal = average % reached by end of bucket).
+    def content_decay(days: nil, platform: nil, account_id: nil)
+      @http.data('GET', '/analytics/content-decay',
+                 query: { 'days' => days, 'platform' => platform, 'accountId' => account_id })
+    end
+
+    # Weekly posting frequency ↔ engagement correlation (Pearson; <2 weeks → null).
+    def posting_frequency(days: nil, platform: nil, account_id: nil)
+      @http.data('GET', '/analytics/posting-frequency',
+                 query: { 'days' => days, 'platform' => platform, 'accountId' => account_id })
+    end
+
+    # Daily metric timeline for a post (cumulative + delta; post_id = platform post id).
+    def post_timeline(post_id, days: nil)
+      @http.data('GET', "/analytics/posts/#{post_id}/timeline", query: { 'days' => days })
+    end
+  end
+
+  # Platform-specific analytics (Node sdk .platformAnalytics) — live data via the account connector.
+  class PlatformAnalyticsResource
+    def initialize(http)
+      @http = http
+    end
+
+    # Instagram daily follower history (from our own snapshot store; Meta does not provide a historical series).
+    def instagram_follower_history(account_id:, days: nil)
+      @http.data('GET', '/analytics/instagram/follower-history',
+                 query: { 'accountId' => account_id, 'days' => days })
+    end
+
+    # Facebook Page insights (current metric names as of November 2025).
+    def facebook_page_insights(account_id)
+      @http.data('GET', '/analytics/facebook/page-insights', query: { 'accountId' => account_id })
+    end
+
+    # Instagram account insights (reach/views/accounts_engaged/total_interactions…).
+    def instagram_insights(account_id)
+      @http.data('GET', '/analytics/instagram/insights', query: { 'accountId' => account_id })
+    end
+
+    # Instagram audience demographics (age/gender/country/city; Meta requires min 100 followers).
+    def instagram_demographics(account_id)
+      @http.data('GET', '/analytics/instagram/demographics', query: { 'accountId' => account_id })
+    end
+
+    # Active Instagram stories (24-hour window).
+    def instagram_stories(account_id)
+      @http.data('GET', '/analytics/instagram/stories', query: { 'accountId' => account_id })
+    end
+
+    # Story metrics + navigation breakdown (tapsForward/tapsBack/exits/swipesForward).
+    def instagram_story_insights(account_id, story_id)
+      @http.data('GET', "/analytics/instagram/stories/#{story_id}/insights",
+                 query: { 'accountId' => account_id })
+    end
+
+    # TikTok account insights (follower/like/video counts — current totals).
+    def tiktok_account_insights(account_id)
+      @http.data('GET', '/analytics/tiktok/account-insights', query: { 'accountId' => account_id })
+    end
+
+    # YouTube channel insights (cumulative + 28-day Analytics metrics).
+    def youtube_channel_insights(account_id)
+      @http.data('GET', '/analytics/youtube/channel-insights', query: { 'accountId' => account_id })
+    end
+
+    # YouTube viewer demographics (age×gender percentages + country breakdown).
+    def youtube_demographics(account_id)
+      @http.data('GET', '/analytics/youtube/demographics', query: { 'accountId' => account_id })
+    end
+
+    # LinkedIn organization page statistics (12-month window; engagement=rate).
+    def linkedin_org_aggregate(account_id)
+      @http.data('GET', '/analytics/linkedin/org-aggregate', query: { 'accountId' => account_id })
+    end
+
+    # Pinterest account insights (last 30 days: impression/save/pin-click/outbound-click/engagement + followers).
+    def pinterest_account_insights(account_id)
+      @http.data('GET', '/analytics/pinterest/account-insights', query: { 'accountId' => account_id })
+    end
+
+    # LinkedIn post reaction breakdown.
+    def linkedin_post_reactions(account_id, post_id)
+      @http.data('GET', "/analytics/linkedin/post-reactions/#{post_id}",
+                 query: { 'accountId' => account_id })
+    end
+  end
+
+  # Inbox analytics (Node sdk .inboxAnalytics) — dm-based volume/heatmap/response-time/source/leaderboard.
+  # from_date is required (YYYY-MM-DD); common filters to_date/platform/account_id/source.
+  class InboxAnalyticsResource
+    def initialize(http)
+      @http = http
+    end
+
+    # DM volume (summary + daily + platform breakdown).
+    def volume(from_date:, to_date: nil, platform: nil, account_id: nil, source: nil)
+      @http.data('GET', '/analytics/inbox/volume',
+                 query: inbox_query(from_date, to_date, platform, account_id, source))
+    end
+
+    # Activity heatmap (dow 1=Mon..7=Sun, hour 0-23 UTC; only non-empty buckets).
+    def heatmap(from_date:, to_date: nil, platform: nil, account_id: nil, source: nil)
+      @http.data('GET', '/analytics/inbox/heatmap',
+                 query: inbox_query(from_date, to_date, platform, account_id, source))
+    end
+
+    # Response time metrics.
+    def response_time(from_date:, to_date: nil, platform: nil, account_id: nil, source: nil)
+      @http.data('GET', '/analytics/inbox/response-time',
+                 query: inbox_query(from_date, to_date, platform, account_id, source))
+    end
+
+    # Source breakdown.
+    def source_breakdown(from_date:, to_date: nil, platform: nil, account_id: nil, source: nil)
+      @http.data('GET', '/analytics/inbox/source-breakdown',
+                 query: inbox_query(from_date, to_date, platform, account_id, source))
+    end
+
+    # Leaderboard of the most active accounts.
+    def top_accounts(from_date:, to_date: nil, platform: nil, account_id: nil, source: nil)
+      @http.data('GET', '/analytics/inbox/top-accounts',
+                 query: inbox_query(from_date, to_date, platform, account_id, source))
+    end
+
+    # Per-conversation statistics — paginated (Paged envelope; @http.req returns the raw body).
+    def conversations(from_date:, to_date: nil, platform: nil, account_id: nil, source: nil,
+                      limit: nil, cursor: nil)
+      query = inbox_query(from_date, to_date, platform, account_id, source)
+      query['limit'] = limit
+      query['cursor'] = cursor
+      @http.req('GET', '/analytics/inbox/conversations', query: query)
+    end
+
+    # Detail for a single conversation's analytics.
+    def conversation(conversation_id, from_date:, to_date: nil, platform: nil, account_id: nil,
+                     source: nil)
+      @http.data('GET', "/analytics/inbox/conversations/#{conversation_id}",
+                 query: inbox_query(from_date, to_date, platform, account_id, source))
+    end
+
+    private
+
+    # Common inbox query Hash (wire-camelCase keys; nil values are skipped in transport).
+    def inbox_query(from_date, to_date, platform, account_id, source)
+      {
+        'fromDate' => from_date,
+        'toDate' => to_date,
+        'platform' => platform,
+        'accountId' => account_id,
+        'source' => source
+      }
+    end
+  end
+end