late-sdk 0.0.613 → 0.0.615

data/openapi.yaml

@@ -1871,6 +1871,14 @@ components:
           description: |
             Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
             For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).
+
+            Monetary metrics additionally carry "unit" and "currency". Zernio never rescales money:
+            "total" and every "values[].value" are the platform's raw numbers in the stated unit.
+            Monetary metrics also keep "values" on metricType=total_value, because their "total" is the
+            sum of the daily buckets the platform returned over the range: keep the series so you can
+            reconcile that sum against the platform's own reporting before invoicing on it.
+            A metric that could not be served is absent from this object and listed in
+            "unavailableMetrics" instead, so an unavailable metric is never reported as a zero.
           additionalProperties:
             type: object
             properties:
@@ -1879,7 +1887,7 @@ components:
                 description: Sum or aggregate value for the metric
               values:
                 type: array
-                description: Daily values (only for time_series)
+                description: Daily values (for time_series, and always on monetary metrics)
                 items:
                   type: object
                   properties:
@@ -1898,9 +1906,149 @@ components:
                       type: string
                     value:
                       type: number
+              unit:
+                type: string
+                enum: [micro_amount, unspecified]
+                description: |
+                  Present on monetary metrics only. The scale of "total" and of every "values[].value",
+                  exactly as the platform returned them.
+
+                  "micro_amount": the platform returned an object shape carrying a micro amount, and the
+                  values are that integer, summed, unconverted. Zernio does not publish a divisor because
+                  Meta does not document one; divide by the scale you have verified against the Page's own
+                  Meta Business Suite export. On Facebook Page insights this is always
+                  content_monetization_earnings.
+
+                  "unspecified": the platform returned a bare number with no unit metadata. It is passed
+                  through as-is; the platform does not state whether it is major or minor currency units.
+                  On Facebook Page insights this is always monetization_approximate_earnings.
+              currency:
+                type: [string, "null"]
+                description: |
+                  ISO 4217 currency of a monetary metric, or null when the platform omitted it.
+                  Always null on monetization_approximate_earnings, which Meta returns as a bare number
+                  with no currency; always present on content_monetization_earnings.
+                example: "USD"
+        unavailableMetrics:
+          type: array
+          description: |
+            Requested metrics that could not be served. Present only when at least one metric is
+            unavailable, and absent otherwise. Each listed metric is OMITTED from "metrics" rather than
+            reported as 0, which is how an unavailable metric is distinguished from a genuine zero.
+            The request itself still succeeds with HTTP 200.
+          items:
+            type: object
+            properties:
+              metric:
+                type: string
+                description: The requested metric name.
+              reason:
+                type: string
+                enum: [not_enrolled, permission_missing, unsupported_metric, no_data, unreadable_value, mixed_currency, upstream_error]
+                description: |
+                  "not_enrolled": the account is not enrolled in the program behind this metric.
+                  "permission_missing": the connected user lacks access to this metric.
+                  "unsupported_metric": the platform does not accept this metric name on the API version Zernio uses.
+                  "no_data": the platform returned no bucket for this metric over the requested range.
+                  "unreadable_value": the platform returned a value shape Zernio cannot read, so no total is reported.
+                  "mixed_currency": readable values disagree on currency or unit within the range.
+                  "upstream_error": any other platform failure.
+
+                  "no_data" is the common case in practice. The others are defensive: "not_enrolled" and
+                  "unsupported_metric" in particular have not been observed on live Facebook traffic, since
+                  a non-enrolled Page returns zeros rather than an error and metric names are validated
+                  before any platform call.
+              message:
+                type: string
+                description: 'Platform-provided explanation when available (access tokens redacted), otherwise Zernio copy.'
         dataDelay:
           type: string
           example: "Data may be delayed up to 48 hours"
+    FacebookPostEarningsResponse:
+      type: object
+      description: |
+        Lifetime monetization earnings for one Facebook post. Same "unit" / "currency" contract and
+        same unavailable-vs-zero contract as the Page-level response; there is no date range, no
+        metricType, and no daily "values", because the single lifetime bucket IS the total.
+      properties:
+        success:
+          type: boolean
+          example: true
+        accountId:
+          type: string
+          example: "64e1a2b3c4d5e6f7a8b9c0d1"
+        postId:
+          type: string
+          description: 'The platform post ID that was queried, echoed back.'
+          example: "123456789_987654321"
+        platform:
+          type: string
+          example: "facebook"
+        period:
+          type: string
+          enum: [lifetime]
+          description: |
+            Always "lifetime": the total is cumulative since publication and must not be summed
+            across dates or across posts.
+        metrics:
+          type: object
+          description: |
+            One entry per served metric. A metric reported here with "total": 0 genuinely earned
+            nothing (or its Page is not enrolled, which Meta reports identically).
+          additionalProperties:
+            type: object
+            properties:
+              total:
+                type: number
+                description: 'Lifetime earnings in "unit", exactly as Meta returned them. Never rescaled.'
+              unit:
+                type: string
+                enum: [micro_amount, unspecified]
+                description: |
+                  "micro_amount": Meta returned an object shape carrying a micro amount, and "total" is
+                  that integer, unconverted. Zernio does not publish a divisor because Meta does not
+                  document one; divide by the scale you have verified against the Page's own Meta
+                  Business Suite export. This is always content_monetization_earnings.
+
+                  "unspecified": Meta returned a bare number with no unit metadata, passed through as-is;
+                  Meta does not state whether it is major or minor currency units. This is always
+                  monetization_approximate_earnings.
+              currency:
+                type: [string, "null"]
+                description: |
+                  ISO 4217 currency, or null when Meta omitted it. Always null on
+                  monetization_approximate_earnings; always present on content_monetization_earnings.
+                example: "USD"
+        unavailableMetrics:
+          type: array
+          description: |
+            Requested metrics Meta could not serve. Present only when at least one metric is
+            unavailable, and absent otherwise. Each listed metric is OMITTED from "metrics" rather than
+            reported as 0. The request itself still succeeds with HTTP 200.
+          items:
+            type: object
+            properties:
+              metric:
+                type: string
+                description: The requested metric name.
+              reason:
+                type: string
+                enum: [not_enrolled, permission_missing, unsupported_metric, no_data, unreadable_value, mixed_currency, upstream_error]
+                description: |
+                  "not_enrolled": the account is not enrolled in the program behind this metric.
+                  "permission_missing": the connected user lacks access to this metric.
+                  "unsupported_metric": Meta does not accept this metric name on the API version Zernio uses.
+                  "no_data": Meta returned no bucket for this metric.
+                  "unreadable_value": Meta returned a value shape Zernio cannot read, so no total is reported.
+                  "mixed_currency": readable values disagree on currency or unit.
+                  "upstream_error": any other platform failure.
+
+                  "no_data" is the common case in practice; the others are defensive.
+              message:
+                type: string
+                description: 'Platform-provided explanation when available (access tokens redacted), otherwise Zernio copy.'
+        dataDelay:
+          type: string
     InstagramDemographicsResponse:
       type: object
       properties:
@@ -6733,6 +6881,7 @@ components:
             objectType: { type: string, description: "Meta creative object_type (e.g. SHARE, VIDEO, PRIVACY_CHECK_FAIL, POST_DELETED). Use this to render state-aware previews — when Meta moderation strips image/video fields, only thumbnailUrl at 64x64 is available." }
             objectStoryId: { type: [string, "null"], description: "Meta creative `object_story_id` (the SHARE reference). Frequently absent — Meta omits it for SHARE creatives. Use effectiveObjectStoryId instead." }
             effectiveObjectStoryId: { type: [string, "null"], description: "Meta `effective_object_story_id` — `{pageId}_{postId}` of the Facebook post the ad's engagement (comments) lives on. Pass to GET /v1/ads?effectiveObjectStoryId= to map a Business-Manager-visible post back to this ad; GET /v1/ads/{adId}/comments resolves comments against it." }
+            pageId: { type: [string, "null"], description: "Facebook Page backing the creative (Meta only). What the `pageId` filter on /v1/ads, /v1/ads/campaigns and /v1/ads/tree matches against. Absent for non-Meta ads and rare Meta creatives with no page signal." }
             effectiveInstagramMediaId: { type: [string, "null"], description: "Meta `effective_instagram_media_id` — the Instagram media ID of the boosted post the ad's engagement lives on. Pass to GET /v1/ads?effectiveInstagramMediaId= to map a Business-Manager-visible IG post back to this ad." }
             instagramUserId: { type: [string, "null"], description: "Meta `instagram_user_id` — the Instagram-scoped business ID that owns the boosted media." }
             instagramPermalinkUrl: { type: [string, "null"], description: "Meta `instagram_permalink_url` — public Instagram post URL of the boosted media." }
@@ -9349,6 +9498,31 @@ paths:
             left by the page_fan_adds / page_fan_removes deprecation):
               - followers_gained
               - followers_lost
+
+            Monetization (opt-in, not in the defaults):
+              - content_monetization_earnings
+              - monetization_approximate_earnings
+
+            Each monetization metric is fetched with its own separate Graph call, so requesting both
+            adds two calls. Values are approximate and Meta restates them after the fact.
+
+            content_monetization_earnings returns an object per day and always carries unit
+            "micro_amount" plus an ISO 4217 "currency". monetization_approximate_earnings returns a bare
+            number per day, so its unit is always "unspecified" and its "currency" is always null. The two
+            are on different scales and are not comparable to each other. Both keep their daily "values"
+            on every metricType and are never rescaled by Zernio.
+
+            Earnings here are Page-level daily buckets and "total" is their sum. Meta does not
+            document whether a bucket carries that day's earnings or a running total, and every
+            Page measured so far earned exactly 0, so reconcile "total" against the Page's own Meta
+            export before relying on it; the daily "values" are always returned for that purpose.
+            Per-post lifetime earnings are served by GET /v1/analytics/facebook/post-earnings.
+
+            A Page that is not enrolled in monetization, or that earned nothing, returns normal daily
+            buckets of 0 in "metrics": Meta does not distinguish the two, so a 0 total here does NOT mean
+            the Page is enrolled. "unavailableMetrics" covers the narrower case where Meta returned no
+            bucket for the metric at all ("no_data") or rejected the request outright, and the metric is
+            then omitted from "metrics" rather than reported as 0.
         - name: since
           in: query
           schema: { type: string, format: date }
@@ -9398,7 +9572,49 @@ paths:
                         values:
                           - { date: "2026-03-01", value: 1 }
                           - { date: "2026-03-02", value: 0 }
-                    dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names."
+                    dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."
+                monetization:
+                  summary: 'Both monetization metrics, each at its own scale'
+                  value:
+                    success: true
+                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
+                    platform: "facebook"
+                    dateRange: { since: "2026-06-01", until: "2026-06-30" }
+                    metricType: "total_value"
+                    metrics:
+                      page_media_view:
+                        total: 125000
+                      content_monetization_earnings:
+                        total: 1234000000
+                        unit: "micro_amount"
+                        currency: "USD"
+                        values:
+                          - { date: "2026-06-01", value: 634000000 }
+                          - { date: "2026-06-02", value: 600000000 }
+                      monetization_approximate_earnings:
+                        total: 1234
+                        unit: "unspecified"
+                        currency: null
+                        values:
+                          - { date: "2026-06-01", value: 700 }
+                          - { date: "2026-06-02", value: 534 }
+                    dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."
+                monetizationUnavailable:
+                  summary: 'A monetization metric Meta returned no bucket for'
+                  value:
+                    success: true
+                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
+                    platform: "facebook"
+                    dateRange: { since: "2026-06-01", until: "2026-06-30" }
+                    metricType: "total_value"
+                    metrics:
+                      page_media_view:
+                        total: 125000
+                    unavailableMetrics:
+                      - metric: "content_monetization_earnings"
+                        reason: "no_data"
+                        message: "Meta returned no data for this monetization metric."
+                    dataDelay: "Meta page insights may be delayed up to 24 hours. Metrics reflect the current (post-November 2025) Graph API names. Monetization earnings are approximate and Meta restates them after the fact."
         '400':
           description: |
             Bad request. Common cases:
@@ -9412,6 +9628,111 @@ paths:
         '404':
           description: Account not found
 
+  /v1/analytics/facebook/post-earnings:
+    get:
+      operationId: getFacebookPostEarnings
+      tags: [Analytics]
+      summary: Get Facebook post monetization earnings
+      description: |
+        Returns lifetime monetization earnings for ONE Facebook post, read live from Meta on every
+        request. Requires the Analytics add-on.
+
+        Earnings are CUMULATIVE since the post was published, not earnings within a date range, so
+        this endpoint takes no since/until and the totals must not be summed across dates or across
+        posts. Page-level daily earnings live on /v1/analytics/facebook/page-insights.
+
+        A post on a Page that is not enrolled in monetization, or that earned nothing, returns
+        "total": 0 rather than an error: Meta does not distinguish the two. A metric Meta returned no
+        bucket for at all is reported in "unavailableMetrics" and omitted from "metrics", never as a 0.
+
+        Amounts are the platform's raw numbers in the stated "unit" and are never rescaled by Zernio.
+        Breakdown dimensions are not exposed and a "breakdown" param is rejected with 400. So are
+        "since", "until", "period", and "metricType": scoping this endpoint to a window is not
+        possible, and silently returning the lifetime total for one would let a caller sum a year of
+        weekly requests into a figure ~52x the post's real earnings.
+      parameters:
+        - name: accountId
+          in: query
+          required: true
+          schema: { type: string }
+          description: The Zernio SocialAccount ID for the connected Facebook Page.
+        - name: postId
+          in: query
+          required: true
+          schema: { type: string }
+          description: |
+            The platform post ID, exactly as returned in platformAnalytics[].platformPostId by
+            /v1/analytics: "{pageId}_{postId}", or the bare video ID for Reels.
+        - name: metrics
+          in: query
+          schema: { type: string }
+          description: |
+            Comma-separated list of monetization metrics. Defaults to both:
+              - content_monetization_earnings
+              - monetization_approximate_earnings
+
+            content_monetization_earnings always carries unit "micro_amount" plus an ISO 4217
+            "currency". monetization_approximate_earnings is always a bare number, so its unit is
+            "unspecified" and its "currency" is null. The two are on different scales and are not
+            comparable to each other. Any other metric name is rejected with 400.
+      responses:
+        '200':
+          description: Lifetime per-post monetization earnings
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FacebookPostEarningsResponse'
+              examples:
+                served:
+                  summary: 'Both metrics served, each at its own scale'
+                  value:
+                    success: true
+                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
+                    postId: "123456789_987654321"
+                    platform: "facebook"
+                    period: "lifetime"
+                    metrics:
+                      content_monetization_earnings:
+                        total: 1234000000
+                        unit: "micro_amount"
+                        currency: "USD"
+                      monetization_approximate_earnings:
+                        total: 1234
+                        unit: "unspecified"
+                        currency: null
+                    dataDelay: "Meta restates monetization earnings after the fact. Per-post earnings are lifetime cumulative: they are the total since publication, not earnings within a date range, and must not be summed across dates."
+                partiallyUnavailable:
+                  summary: 'One metric served, one with no bucket returned by Meta'
+                  value:
+                    success: true
+                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
+                    postId: "123456789_987654321"
+                    platform: "facebook"
+                    period: "lifetime"
+                    metrics:
+                      monetization_approximate_earnings:
+                        total: 0
+                        unit: "unspecified"
+                        currency: null
+                    unavailableMetrics:
+                      - metric: "content_monetization_earnings"
+                        reason: "no_data"
+                        message: "Meta returned no data for this monetization metric."
+                    dataDelay: "Meta restates monetization earnings after the fact. Per-post earnings are lifetime cumulative: they are the total since publication, not earnings within a date range, and must not be summed across dates."
+        '400':
+          description: |
+            Bad request. Common cases:
+              - Invalid accountId format, or a metric name that is not a monetization metric
+              - A "breakdown" param was supplied (breakdown dimensions are not exposed)
+              - A "since", "until", "period", or "metricType" param was supplied (this endpoint returns a lifetime total and takes no date range)
+              - Account has no Page access token (metadata.pageAccessToken missing)
+              - Account is not a Facebook account
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '402':
+          description: Analytics access required. Legacy plans need the Analytics add-on; included by default on usage-based plans.
+        '404':
+          description: Account not found
+
   /v1/analytics/instagram/account-insights:
     get:
       operationId: getInstagramAccountInsights
@@ -34083,6 +34404,7 @@ paths:
         - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai] } }
         - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
         - { name: adAccountId, in: query, schema: { type: string }, description: "Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree." }
+        - { name: pageId, in: query, schema: { type: string }, description: "Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's `creative.pageId`; ads with no page signal (rare IG-only creatives) never match. Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree." }
         - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
         - { name: campaignId, in: query, schema: { type: string }, description: Platform campaign ID (filter ads within a campaign) }
         - { name: platformAdId, in: query, schema: { type: string }, description: "Meta ad ID. Returns the ad with this platform-side ad ID." }
@@ -34197,6 +34519,7 @@ paths:
         - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai] } }
         - { name: status, in: query, schema: { $ref: '#/components/schemas/AdStatus' }, description: Filter by derived campaign status (post-aggregation) }
         - { name: adAccountId, in: query, schema: { type: string }, description: Platform ad account ID (e.g. act_123 for Meta) }
+        - { name: pageId, in: query, schema: { type: string }, description: "Meta only: Facebook Page ID. Campaigns have no Page of their own, so this keeps campaigns having at least one ad backed by this Page, with adCount and metrics computed over those ads only. Mirrors the same filter on /v1/ads and /v1/ads/tree." }
         - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
         - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
         - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted." }
@@ -34866,6 +35189,7 @@ paths:
         - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter, openai] } }
         - { name: status, in: query, schema: { $ref: '#/components/schemas/AdStatus' }, description: Filter by derived campaign status (post-aggregation) }
         - { name: adAccountId, in: query, schema: { type: string }, description: Platform ad account ID }
+        - { name: pageId, in: query, schema: { type: string }, description: "Meta only: Facebook Page ID. Prunes the tree to ads whose creative is backed by this Page — campaigns and ad sets with no ad on the Page drop out, and rolled-up metrics cover only the Page's ads. Mirrors the same filter on /v1/ads and /v1/ads/campaigns." }
         - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
         - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
         - { name: campaignId, in: query, schema: { type: string }, description: "Restrict the tree to a single campaign by its platform campaign id (the id the platform assigns, e.g. Meta's numeric campaign id). Filters the campaign set itself, so it works regardless of account size and pagination — pass this when you already hold a campaign id instead of paging the tree to find it. Mirrors the `campaignId` filter on GET /v1/ads." }

data/spec/api/ad_campaigns_api_spec.rb

@@ -181,6 +181,7 @@ describe 'AdCampaignsApi' do
   # @option opts [String] :platform 
   # @option opts [AdStatus] :status Filter by derived campaign status (post-aggregation)
   # @option opts [String] :ad_account_id Platform ad account ID
+  # @option opts [String] :page_id Meta only: Facebook Page ID. Prunes the tree to ads whose creative is backed by this Page — campaigns and ad sets with no ad on the Page drop out, and rolled-up metrics cover only the Page's ads. Mirrors the same filter on /v1/ads and /v1/ads/campaigns.
   # @option opts [String] :account_id Social account ID
   # @option opts [String] :profile_id Profile ID
   # @option opts [String] :campaign_id Restrict the tree to a single campaign by its platform campaign id (the id the platform assigns, e.g. Meta's numeric campaign id). Filters the campaign set itself, so it works regardless of account size and pagination — pass this when you already hold a campaign id instead of paging the tree to find it. Mirrors the `campaignId` filter on GET /v1/ads.
@@ -222,6 +223,7 @@ describe 'AdCampaignsApi' do
   # @option opts [String] :platform 
   # @option opts [AdStatus] :status Filter by derived campaign status (post-aggregation)
   # @option opts [String] :ad_account_id Platform ad account ID (e.g. act_123 for Meta)
+  # @option opts [String] :page_id Meta only: Facebook Page ID. Campaigns have no Page of their own, so this keeps campaigns having at least one ad backed by this Page, with adCount and metrics computed over those ads only. Mirrors the same filter on /v1/ads and /v1/ads/tree.
   # @option opts [String] :account_id Social account ID
   # @option opts [String] :profile_id Profile ID
   # @option opts [Date] :from_date Start of metrics date range (YYYY-MM-DD, inclusive). Defaults to 90 days ago when both date params are omitted.
@@ -266,6 +268,7 @@ describe 'AdCampaignsApi' do
   # @option opts [String] :platform 
   # @option opts [String] :account_id Social account ID
   # @option opts [String] :ad_account_id Platform ad account ID (e.g. act_123 for Meta). Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.
+  # @option opts [String] :page_id Meta only: Facebook Page ID. Returns only ads whose creative is backed by this Page (a Meta ad account serves ads for every Page in the Business Manager). Matches each ad's `creative.pageId`; ads with no page signal (rare IG-only creatives) never match. Mirrors the same filter on /v1/ads/campaigns and /v1/ads/tree.
   # @option opts [String] :profile_id Profile ID
   # @option opts [String] :campaign_id Platform campaign ID (filter ads within a campaign)
   # @option opts [String] :platform_ad_id Meta ad ID. Returns the ad with this platform-side ad ID.

data/spec/api/analytics_api_spec.rb

@@ -107,7 +107,7 @@ describe 'AnalyticsApi' do
   # Returns page-level Facebook insights (media views, views, post engagements, video metrics, follower counts). Response shape matches /v1/analytics/instagram/account-insights so the same client handling works across platforms.  Metric names track the current (post-November 2025) Meta Graph API. The legacy page_impressions / page_fans / page_fan_adds / page_fan_removes metrics were deprecated by Meta on November 15, 2025 and are NOT accepted by this endpoint. Use the replacements below. Because Meta did not provide direct adds/removes replacements, Zernio synthesizes followers_gained / followers_lost from the daily follower snapshotter.  Max 89 days, defaults to last 30 days. Requires the Analytics add-on. 
   # @param account_id The Zernio SocialAccount ID for the connected Facebook Page.
   # @param [Hash] opts the optional parameters
-  # @option opts [String] :metrics Comma-separated list of metrics. Defaults to \"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost\".  Live Meta metrics (current names, post-Nov-2025):   - page_media_view       (replaces deprecated page_impressions)   - page_views_total   - page_post_engagements   - page_video_views   - page_video_view_time   - page_follows          (replaces deprecated page_fans)  Zernio-synthesized from daily follower snapshots (filling the Nov-2025 gap left by the page_fan_adds / page_fan_removes deprecation):   - followers_gained   - followers_lost 
+  # @option opts [String] :metrics Comma-separated list of metrics. Defaults to \"page_media_view,page_post_engagements,page_follows,followers_gained,followers_lost\".  Live Meta metrics (current names, post-Nov-2025):   - page_media_view       (replaces deprecated page_impressions)   - page_views_total   - page_post_engagements   - page_video_views   - page_video_view_time   - page_follows          (replaces deprecated page_fans)  Zernio-synthesized from daily follower snapshots (filling the Nov-2025 gap left by the page_fan_adds / page_fan_removes deprecation):   - followers_gained   - followers_lost  Monetization (opt-in, not in the defaults):   - content_monetization_earnings   - monetization_approximate_earnings  Each monetization metric is fetched with its own separate Graph call, so requesting both adds two calls. Values are approximate and Meta restates them after the fact.  content_monetization_earnings returns an object per day and always carries unit \"micro_amount\" plus an ISO 4217 \"currency\". monetization_approximate_earnings returns a bare number per day, so its unit is always \"unspecified\" and its \"currency\" is always null. The two are on different scales and are not comparable to each other. Both keep their daily \"values\" on every metricType and are never rescaled by Zernio.  Earnings here are Page-level daily buckets and \"total\" is their sum. Meta does not document whether a bucket carries that day's earnings or a running total, and every Page measured so far earned exactly 0, so reconcile \"total\" against the Page's own Meta export before relying on it; the daily \"values\" are always returned for that purpose. Per-post lifetime earnings are served by GET /v1/analytics/facebook/post-earnings.  A Page that is not enrolled in monetization, or that earned nothing, returns normal daily buckets of 0 in \"metrics\": Meta does not distinguish the two, so a 0 total here does NOT mean the Page is enrolled. \"unavailableMetrics\" covers the narrower case where Meta returned no bucket for the metric at all (\"no_data\") or rejected the request outright, and the metric is then omitted from \"metrics\" rather than reported as 0. 
   # @option opts [Date] :since Start date (YYYY-MM-DD). Defaults to 30 days ago.
   # @option opts [Date] :_until End date (YYYY-MM-DD). Defaults to today.
   # @option opts [String] :metric_type \"total_value\" (default) returns aggregated totals only. \"time_series\" returns daily values in the \"values\" array. 
@@ -118,6 +118,20 @@ describe 'AnalyticsApi' do
     end
   end
 
+  # unit tests for get_facebook_post_earnings
+  # Get Facebook post monetization earnings
+  # Returns lifetime monetization earnings for ONE Facebook post, read live from Meta on every request. Requires the Analytics add-on.  Earnings are CUMULATIVE since the post was published, not earnings within a date range, so this endpoint takes no since/until and the totals must not be summed across dates or across posts. Page-level daily earnings live on /v1/analytics/facebook/page-insights.  A post on a Page that is not enrolled in monetization, or that earned nothing, returns \"total\": 0 rather than an error: Meta does not distinguish the two. A metric Meta returned no bucket for at all is reported in \"unavailableMetrics\" and omitted from \"metrics\", never as a 0.  Amounts are the platform's raw numbers in the stated \"unit\" and are never rescaled by Zernio. Breakdown dimensions are not exposed and a \"breakdown\" param is rejected with 400. So are \"since\", \"until\", \"period\", and \"metricType\": scoping this endpoint to a window is not possible, and silently returning the lifetime total for one would let a caller sum a year of weekly requests into a figure ~52x the post's real earnings. 
+  # @param account_id The Zernio SocialAccount ID for the connected Facebook Page.
+  # @param post_id The platform post ID, exactly as returned in platformAnalytics[].platformPostId by /v1/analytics: \"{pageId}_{postId}\", or the bare video ID for Reels. 
+  # @param [Hash] opts the optional parameters
+  # @option opts [String] :metrics Comma-separated list of monetization metrics. Defaults to both:   - content_monetization_earnings   - monetization_approximate_earnings  content_monetization_earnings always carries unit \"micro_amount\" plus an ISO 4217 \"currency\". monetization_approximate_earnings is always a bare number, so its unit is \"unspecified\" and its \"currency\" is null. The two are on different scales and are not comparable to each other. Any other metric name is rejected with 400. 
+  # @return [FacebookPostEarningsResponse]
+  describe 'get_facebook_post_earnings test' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   # unit tests for get_facebook_post_reactions
   # Get Facebook post reactions
   # Returns the reaction breakdown for a Facebook Page post: a count per reaction type plus the overall total.  The whole breakdown is fetched in a single Graph call. Note that the post analytics endpoint reports only an aggregate reaction count (surfaced there as `likes`), so use this endpoint when you need per-type counts. 

data/spec/models/ad_creative_spec.rb

@@ -69,6 +69,12 @@ describe Zernio::AdCreative do
     end
   end
 
+  describe 'test attribute "page_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   describe 'test attribute "effective_instagram_media_id"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/

data/spec/models/facebook_post_earnings_response_metrics_value_spec.rb

@@ -0,0 +1,52 @@
+=begin
+#Zernio API
+
+#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api 
+
+The version of the OpenAPI document: 1.0.4
+Contact: support@zernio.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.19.0
+
+=end
+
+require 'spec_helper'
+require 'json'
+require 'date'
+
+# Unit tests for Zernio::FacebookPostEarningsResponseMetricsValue
+# Automatically generated by openapi-generator (https://openapi-generator.tech)
+# Please update as you see appropriate
+describe Zernio::FacebookPostEarningsResponseMetricsValue do
+  #let(:instance) { Zernio::FacebookPostEarningsResponseMetricsValue.new }
+
+  describe 'test an instance of FacebookPostEarningsResponseMetricsValue' do
+    it 'should create an instance of FacebookPostEarningsResponseMetricsValue' do
+      # uncomment below to test the instance creation
+      #expect(instance).to be_instance_of(Zernio::FacebookPostEarningsResponseMetricsValue)
+    end
+  end
+
+  describe 'test attribute "total"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "unit"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+      # validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["micro_amount", "unspecified"])
+      # validator.allowable_values.each do |value|
+      #   expect { instance.unit = value }.not_to raise_error
+      # end
+    end
+  end
+
+  describe 'test attribute "currency"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+end

data/spec/models/facebook_post_earnings_response_spec.rb

@@ -0,0 +1,82 @@
+=begin
+#Zernio API
+
+#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api 
+
+The version of the OpenAPI document: 1.0.4
+Contact: support@zernio.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.19.0
+
+=end
+
+require 'spec_helper'
+require 'json'
+require 'date'
+
+# Unit tests for Zernio::FacebookPostEarningsResponse
+# Automatically generated by openapi-generator (https://openapi-generator.tech)
+# Please update as you see appropriate
+describe Zernio::FacebookPostEarningsResponse do
+  #let(:instance) { Zernio::FacebookPostEarningsResponse.new }
+
+  describe 'test an instance of FacebookPostEarningsResponse' do
+    it 'should create an instance of FacebookPostEarningsResponse' do
+      # uncomment below to test the instance creation
+      #expect(instance).to be_instance_of(Zernio::FacebookPostEarningsResponse)
+    end
+  end
+
+  describe 'test attribute "success"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "account_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "post_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "platform"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "period"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+      # validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["lifetime"])
+      # validator.allowable_values.each do |value|
+      #   expect { instance.period = value }.not_to raise_error
+      # end
+    end
+  end
+
+  describe 'test attribute "metrics"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "unavailable_metrics"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "data_delay"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+end