zelf-sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be165e235f7671006c27aae0337edc329110bf9258cd05605cc94a870ff1a3b0
-  data.tar.gz: 740b0f1f5d79af41e7372b7ca334512f994814ee60b78416593dbcd783554fb1
+  metadata.gz: d948897bb81022c440c848f71c2ce80b9584399ba05f71c116851872dd02da00
+  data.tar.gz: 527540f8d27cbf861e2f0ce5074ac3c0dac4e63df46066adcbcf6b001bdee478
 SHA512:
-  metadata.gz: a9ec10f087875657afc2b048aea894699ea106046927c241ecfd88b661e75deeb73146fa23d45ca78ebb3bb5c3ce50ef3efef0fe7d59443d1877a30283dea3c1
-  data.tar.gz: dd02c43770515f577e624e7847072edc71e49f0920774ebd3e7b1667d9098dc522e404fb0eefe3276d9d75b72171acf156ab6fda5021b1c7d0c18ba75f8fbd26
+  metadata.gz: 24a574903b9793393e2d1bee281af5c79bd160204bbb1371e4daadaf81a13fbe0299e86cdd369be6bc2f85f59f83ff860db329a531795633bc964e759f7fa60f
+  data.tar.gz: 0ab78f10d9af08b4b357405fd2503a1a8d9dbefca7b93fdbca5c1f688c91b52d852fd8e1546d2dfc55cab6589d3a5fab047bcac4476097c935e5af90f1cc7c3f

data/README.md

@@ -1,8 +1,7 @@
 # zelf-sdk (Ruby)
 
 Official client for the Zelf API. Part of
-[hellozelf/zelf-sdk](https://github.com/hellozelf/zelf-sdk), which holds the
-same client in eight languages.
+[hellozelf/zelf-sdk](https://github.com/hellozelf/zelf-sdk).
 
 ## Install
 

data/lib/zelf/models.rb

@@ -94,14 +94,18 @@ module Zelf
     class AiAnalysisCreateRequest < Zelf::Model; end
     class AiAnalysisResult < Zelf::Model; end
     class AiAnalysisRun < Zelf::Model; end
+    class AnalyticsBrand < Zelf::Model; end
     class Brand < Zelf::Model; end
     class BrandAccount < Zelf::Model; end
     class BrandAccountGroups < Zelf::Model; end
     class BrandAccountsWriteRequest < Zelf::Model; end
     class BrandCatalog < Zelf::Model; end
     class BrandCatalogItem < Zelf::Model; end
+    class BrandComparison < Zelf::Model; end
     class BrandCreateSubBrandRequest < Zelf::Model; end
+    class BrandFollowers < Zelf::Model; end
     class BrandKeywords < Zelf::Model; end
+    class BrandStatistics < Zelf::Model; end
     class Comment < Zelf::Model; end
     class CommentAuthor < Zelf::Model; end
     class Content < Zelf::Model; end
@@ -134,11 +138,18 @@ module Zelf
     class DetectionResult < Zelf::Model; end
     class DetectionSummary < Zelf::Model; end
     class DetectionVideo < Zelf::Model; end
+    class FollowerAccount < Zelf::Model; end
+    class FollowerPeriod < Zelf::Model; end
+    class FollowerTimeseries < Zelf::Model; end
     class PatchedBrandUpdateRequest < Zelf::Model; end
     class PatchedWebhookSubscriptionUpdateRequest < Zelf::Model; end
+    class PostedCommentCategory < Zelf::Model; end
+    class PostedComments < Zelf::Model; end
     class ResultFile < Zelf::Model; end
     class SafetyCheckRequest < Zelf::Model; end
     class Usage < Zelf::Model; end
+    class UsageDay < Zelf::Model; end
+    class UsageHistory < Zelf::Model; end
     class UsageScope < Zelf::Model; end
     class UsageWindow < Zelf::Model; end
     class WebhookAvailableEvent < Zelf::Model; end
@@ -213,6 +224,18 @@ module Zelf
       field :status, "status"
     end
 
+    # The brand a row of analytics belongs to.
+    class AnalyticsBrand
+      # Unique identifier for the brand
+      field :id, "id"
+      # Display name of the brand
+      field :title, "title"
+      # true for the brand the request named, false for a sub-brand
+      field :is_primary, "is_primary"
+      # COMPETITIVE or THEME for a sub-brand; null for the top-level brand the request named
+      field :sub_brand_type, "sub_brand_type"
+    end
+
     # A brand you can reach.
     class Brand
       # Unique identifier for the brand
@@ -233,7 +256,7 @@ module Zelf
     class BrandAccount
       # The account's handle
       field :username, "username"
-      # instagram or tiktok
+      # instagram, tiktok or youtube
       field :platform, "platform"
       # The account's profile URL, when available
       field :external_url, "external_url"
@@ -256,7 +279,7 @@ module Zelf
       field :brand_id, "brand_id"
       # The list to modify: tracked, influencer, or owned for the brand's own profiles
       field :account_type, "account_type"
-      # Profile URLs on a supported platform (instagram or tiktok)
+      # Profile URLs on a supported platform (instagram, tiktok or youtube)
       field :profile_urls, "profile_urls"
     end
 
@@ -290,6 +313,16 @@ module Zelf
       field :parent_id, "parent_id"
     end
 
+    # One brand's performance in the comparison.
+    class BrandComparison
+      # The brand this row covers
+      field :brand, "brand", cast: AnalyticsBrand
+      # Totals over the window
+      field :statistics, "statistics", cast: BrandStatistics
+      # Follower counts as they stand now, not over the window
+      field :followers, "followers", cast: BrandFollowers
+    end
+
     # Create a sub-brand under the workspace brand.
     class BrandCreateSubBrandRequest
       # Plain keywords the brand monitors across platforms, matched as-is (case-...
@@ -312,6 +345,14 @@ module Zelf
       field :sub_brand_type, "sub_brand_type"
     end
 
+    # Followers across the handles a brand owns.
+    class BrandFollowers
+      # Followers across every owned handle
+      field :total, "total"
+      # Per handle counts that add up to total
+      field :accounts, "accounts", cast: [FollowerAccount]
+    end
+
     # The terms this brand uses to monitor social platforms.
     class BrandKeywords
       # Plain keywords the brand monitors across platforms, matched as-is (case-...
@@ -330,13 +371,41 @@ module Zelf
       field :boolean_query, "boolean_query"
     end
 
+    # Totals over the content matched to a brand in the window.
+    class BrandStatistics
+      # Number of posts matched to the brand
+      field :post_count, "post_count"
+      # Total views across those posts
+      field :total_views, "total_views"
+      # Total likes across those posts
+      field :total_likes, "total_likes"
+      # Total comments across those posts
+      field :total_comments, "total_comments"
+      # Total shares across those posts
+      field :total_shares, "total_shares"
+      # Likes, comments and shares across those posts
+      field :total_engagement, "total_engagement"
+      # Estimated marketing value across those posts, in US cents
+      field :total_earned_media_value_cents, "total_earned_media_value_cents"
+      # Total engagement divided by total views
+      field :engagement_rate, "engagement_rate"
+      # Number of distinct creators who posted
+      field :unique_creator_count, "unique_creator_count"
+      # Engagement on positive posts
+      field :total_positive_nps, "total_positive_nps"
+      # Engagement on neutral posts
+      field :total_neutral_nps, "total_neutral_nps"
+      # Engagement on negative posts
+      field :total_negative_nps, "total_negative_nps"
+    end
+
     # A comment left on a piece of content.
     class Comment
       # Unique identifier for the comment
       field :id, "id"
       # The comment's text content
       field :text, "text"
-      # The platform the comment was posted on
+      # The platform the comment was posted on: instagram, tiktok or youtube
       field :platform, "platform"
       # Number of likes the comment has received
       field :like_count, "like_count"
@@ -370,7 +439,7 @@ module Zelf
       field :id, "id"
       # The post's identifier on its platform
       field :platform_post_id, "platform_post_id"
-      # The platform the content was published on
+      # The platform the content was published on: instagram, tiktok or youtube
       field :platform, "platform"
       # Whether the content is a video or an image
       field :content_form, "content_form"
@@ -875,6 +944,36 @@ module Zelf
       field :duration_s, "duration_s"
     end
 
+    # One owned handle and the followers it carries.
+    class FollowerAccount
+      # The platform the handle is on
+      field :platform, "platform"
+      # The handle
+      field :username, "username"
+      # Follower count for this handle
+      field :followers, "followers"
+    end
+
+    # Followers at the end of one period.
+    class FollowerPeriod
+      # Followers across every owned handle
+      field :followers, "followers"
+      # First day of the period
+      field :start_date, "start_date"
+      # Last day of the period
+      field :end_date, "end_date"
+      # Per handle counts that add up to followers
+      field :accounts, "accounts", cast: [FollowerAccount]
+    end
+
+    # One brand's follower history.
+    class FollowerTimeseries
+      # The brand this row covers
+      field :brand, "brand", cast: AnalyticsBrand
+      # One entry per period, oldest first
+      field :periods, "periods", cast: [FollowerPeriod]
+    end
+
     # Partial update for a brand's monitoring keywords. Every field is optional, and only
     # the supplied fields are changed, but at least one field is required.
     class PatchedBrandUpdateRequest
@@ -912,6 +1011,26 @@ module Zelf
       field :enabled, "enabled"
     end
 
+    # Comments the brand posted on one category of content.
+    class PostedCommentCategory
+      # brand, owned, competitors, themes or other
+      field :category, "category"
+      # Comments posted on this category
+      field :comments, "comments"
+      # Likes those comments received
+      field :likes, "likes"
+      # Replies those comments received
+      field :replies, "replies"
+    end
+
+    # Comments the brand posted, split by the content they were posted on.
+    class PostedComments
+      # Comments the brand posted in the window, across every category
+      field :total_comments_posted, "total_comments_posted"
+      # One entry per category
+      field :categories, "categories", cast: [PostedCommentCategory]
+    end
+
     # Signed, time-limited download of an analysis run's result payload.
     class ResultFile
       # Unix epoch seconds after which download_url expires
@@ -938,24 +1057,58 @@ module Zelf
       field :brand_id, "brand_id"
       # api_key or mcp, whichever made this call
       field :authenticated_as, "authenticated_as"
-      # Keyed by group
-      field :scopes, "scopes"
+      # One entry per metered group
+      field :scopes, "scopes", cast: [UsageScope]
+      # What was actually spent, day by day, from the usage ledger
+      field :history, "history", cast: UsageHistory
+    end
+
+    # One day of consumption for one source.
+    class UsageDay
+      # api for direct requests, mcp for AI clients
+      field :source, "source"
+      # Every counted call that day
+      field :general, "general"
+      # Calls counted against the AI analysis group
+      field :ai_analysis, "ai_analysis"
+      # Calls counted against creator vetting
+      field :creator_vetting, "creator_vetting"
+      # Calls counted against data records
+      field :data_records, "data_records"
+      # Records those calls returned
+      field :data_records_items, "data_records_items"
+      # The day, in the brand's billing timezone
+      field :date, "date"
+    end
+
+    # Daily consumption over the window the ledger keeps.
+    class UsageHistory
+      # First day covered
+      field :start_date, "start_date"
+      # Last day covered
+      field :end_date, "end_date"
+      # One entry per day and source that saw usage, oldest first
+      field :days, "days", cast: [UsageDay]
     end
 
     # One metered group, with every window that has a limit.
     class UsageScope
+      # Identifier of the metered group
+      field :scope, "scope"
       # Name of the group, as an admin sees it
       field :human_name, "human_name"
       # request counts calls; item counts rows returned
       field :kind, "kind"
       # Which product the group meters: api for direct requests, mcp for AI clients
       field :section, "section"
-      # Keyed by window: rps, rpm, rph, rpd, rpmonth, or the item windows
-      field :windows, "windows"
+      # Every window that has a limit configured
+      field :windows, "windows", cast: [UsageWindow]
     end
 
     # Consumption of one window, e.g. requests in the current hour.
     class UsageWindow
+      # Which window this is: rps, rpm, rph, rpd, rpmonth, or an item window
+      field :window, "window"
       # Most that may be spent in this window
       field :limit, "limit"
       # Spent so far in this window
@@ -966,7 +1119,7 @@ module Zelf
       field :reset_in, "reset_in"
     end
 
-    # The WebhookAvailableEvent object.
+    # An event type a subscription may ask for.
     class WebhookAvailableEvent
       # Event type identifier, e.g
       field :event, "event"
@@ -991,7 +1144,7 @@ module Zelf
       field :items, "items"
     end
 
-    # The WebhookDeleteAcknowledgement object.
+    # Confirmation that a webhook resource was deleted.
     class WebhookDeleteAcknowledgement
       # Always true; confirms the webhook resource delete was acknowledged
       field :acknowledged, "acknowledged"
@@ -1001,7 +1154,7 @@ module Zelf
       field :status, "status"
     end
 
-    # The WebhookDelivery object.
+    # One attempt to deliver one push, with its outcome.
     class WebhookDelivery
       # Encoded identifier of the webhook delivery
       field :id, "id"
@@ -1033,9 +1186,8 @@ module Zelf
       field :modified, "modified", cast: :time
     end
 
-    # One downloadable snapshot file in a manifest push. A delivery currently consists of
-    # a single file, so `files` carries one entry. The array shape allows a snapshot to be
-    # sharded across several files in the future without changing the envelope.
+    # One downloadable snapshot file in a manifest push. `files` is an array, so read
+    # every entry rather than assuming one.
     class WebhookFile
       # File encoding
       field :format, "format"
@@ -1077,7 +1229,7 @@ module Zelf
       field :data, "data", cast: WebhookData
     end
 
-    # The WebhookSecret object.
+    # A signing secret, identified by its prefix rather than its value.
     class WebhookSecret
       # Encoded identifier of the webhook secret
       field :id, "id"
@@ -1103,7 +1255,8 @@ module Zelf
       field :make_default, "make_default"
     end
 
-    # The WebhookSecretCreated object.
+    # A secret just created or rotated, carrying the value once. Store it now: later reads
+    # return the prefix alone.
     class WebhookSecretCreated
       # Encoded identifier of the webhook secret
       field :id, "id"
@@ -1123,7 +1276,7 @@ module Zelf
       field :secret, "secret"
     end
 
-    # The WebhookSubscription object.
+    # A registered endpoint and the events it receives.
     class WebhookSubscription
       # Encoded identifier of the webhook subscription
       field :id, "id"
@@ -1179,7 +1332,8 @@ module Zelf
       field :secret_type, "secret_type"
     end
 
-    # The WebhookSubscriptionCreated object.
+    # A subscription just created, with the signing secret attached. The secret is shown
+    # on this response only and never again.
     class WebhookSubscriptionCreated
       # Encoded identifier of the webhook subscription
       field :id, "id"

data/lib/zelf/resources/analytics.rb

@@ -0,0 +1,72 @@
+# Generated by codegen. Do not edit by hand.
+module Zelf
+  module Resources
+    # The analytics endpoints.
+    class Analytics
+      def initialize(transport)
+        @transport = transport
+      end
+
+      # Compare Brand Performance. Returns one row of totals per brand: the top-level brand
+      # named by `brand_id`, followed by each of its competitor sub-brands. The statistics
+      # block matches `content.statistics`, so the same parsing works for both. `brand_id`
+      # must name a top-level brand. A sub-brand is refused with the id of the parent to use
+      # instead.
+      #
+      # Calls GET /api/v1/analytics/brand_comparison/ (analytics.brand_comparison).
+      def brand_comparison(brand_id:, platform: nil, posted_after: nil, posted_before: nil, posted_within_days: nil, posted_within_hours: nil)
+        query = {
+          "brand_id" => brand_id,
+          "platform" => platform,
+          "posted_after" => posted_after,
+          "posted_before" => posted_before,
+          "posted_within_days" => posted_within_days,
+          "posted_within_hours" => posted_within_hours,
+        }.reject { |_, value| value.nil? }
+        envelope = @transport.request(:get, "/api/v1/analytics/brand_comparison/", query: query)
+        Zelf.one(envelope, Models::BrandComparison, "BrandComparison")
+      end
+
+      # Get Brand Follower Time Series. Returns follower history for the top-level brand
+      # named by `brand_id` and each of its competitor sub-brands, bucketed by `period`. A
+      # brand appears only for the periods in which one of its owned handles was measured.
+      # Follower counts carry forward: a handle with no reading in a period keeps the last
+      # one recorded before it.
+      #
+      # Calls GET /api/v1/analytics/follower_timeseries/ (analytics.follower_timeseries).
+      def follower_timeseries(brand_id:, period: nil, platform: nil, posted_after: nil, posted_before: nil, posted_within_days: nil, posted_within_hours: nil)
+        query = {
+          "brand_id" => brand_id,
+          "period" => period,
+          "platform" => platform,
+          "posted_after" => posted_after,
+          "posted_before" => posted_before,
+          "posted_within_days" => posted_within_days,
+          "posted_within_hours" => posted_within_hours,
+        }.reject { |_, value| value.nil? }
+        envelope = @transport.request(:get, "/api/v1/analytics/follower_timeseries/", query: query)
+        Zelf.one(envelope, Models::FollowerTimeseries, "FollowerTimeseries")
+      end
+
+      # Get Posted Comment Analytics. Returns the comments the brand posted in the window,
+      # grouped by the kind of content they were posted on, together with the likes and
+      # replies those comments received. These are comments the brand wrote, not comments
+      # left on its content; `comments.list` returns the latter. The five categories add up
+      # to `total_comments_posted`.
+      #
+      # Calls GET /api/v1/analytics/posted_comments/ (analytics.posted_comments).
+      def posted_comments(brand_id:, platform: nil, posted_after: nil, posted_before: nil, posted_within_days: nil, posted_within_hours: nil)
+        query = {
+          "brand_id" => brand_id,
+          "platform" => platform,
+          "posted_after" => posted_after,
+          "posted_before" => posted_before,
+          "posted_within_days" => posted_within_days,
+          "posted_within_hours" => posted_within_hours,
+        }.reject { |_, value| value.nil? }
+        envelope = @transport.request(:get, "/api/v1/analytics/posted_comments/", query: query)
+        Zelf.one(envelope, Models::PostedComments, "PostedComments")
+      end
+    end
+  end
+end

data/lib/zelf/resources/creator_vetting.rb

@@ -39,16 +39,16 @@ module Zelf
         Zelf::Page.new(envelope, Models::Content, @transport, path, query)
       end
 
-      # Create Creator Vetting. Vets a creator identified by `profile_url`, running or
-      # reusing the profile scrape and the AI safety and brand-fit analysis. Runs complete
-      # asynchronously, so this method returns immediately with the created vetting. The
-      # vetting analyzes up to 150 of the creator's posts per connection type, or the limit
-      # configured for your workspace. The created vetting is returned as the single item in
-      # `results`. Take its `id` and poll `creator_vetting.list` until a run reports
-      # `COMPLETED`. A vetting can take an hour or more to complete, so prefer the
-      # `creator_vetting.completed` webhook over frequent polling, which can trigger
-      # `RATE_LIMIT_EXCEEDED`. Once a run is complete, retrieve the payload from
-      # `creator_vetting.results`, passing `vetting_id=<id>`.
+      # Create Creator Vetting. Vets a creator identified by `profile_url`, retrieving the
+      # profile and scoring its safety and brand fit. Runs complete asynchronously, so this
+      # method returns immediately with the created vetting. The vetting analyzes up to 150
+      # of the creator's posts per connection type, or the limit configured for your
+      # workspace. The created vetting is returned as the single item in `results`. Take its
+      # `id` and poll `creator_vetting.list` until a run reports `COMPLETED`. A vetting can
+      # take an hour or more to complete, so prefer the `creator_vetting.completed` webhook
+      # over frequent polling, which can trigger `RATE_LIMIT_EXCEEDED`. Once a run is
+      # complete, retrieve the payload from `creator_vetting.results`, passing
+      # `vetting_id=<id>`.
       #
       # Calls POST /api/v1/creator/vetting/ (creator_vetting.create).
       def create(profile_url:, resync_profile: nil, content_scope: nil, safety_checks: nil)

data/lib/zelf/version.rb

@@ -1,5 +1,5 @@
 # Generated by codegen. Do not edit by hand.
 
 module Zelf
-  VERSION = '1.0.0'.freeze
+  VERSION = '1.1.0'.freeze
 end

data/lib/zelf.rb

@@ -7,6 +7,7 @@ require_relative 'zelf/transport'
 require_relative 'zelf/page'
 require_relative 'zelf/webhooks'
 require_relative 'zelf/resources/ai_analysis'
+require_relative 'zelf/resources/analytics'
 require_relative 'zelf/resources/brand_accounts'
 require_relative 'zelf/resources/brands'
 require_relative 'zelf/resources/comments'
@@ -19,7 +20,7 @@ require_relative 'zelf/resources/sub_brands'
 require_relative 'zelf/resources/usage'
 require_relative 'zelf/resources/webhooks'
 
-# Ruby client for the ZelfAI APIs (spec version 1.0.0).
+# Ruby client for the ZelfAI APIs (spec version 1.1.0).
 module Zelf
   # Client for the ZelfAI APIs.
   #
@@ -27,7 +28,7 @@ module Zelf
   # ZELF_API_KEY environment variable. It is sent as the x-api-key header
   # and is kept out of inspect output.
   class Client
-    attr_reader :ai_analysis, :brand_accounts, :brands, :comments, :content, :creator_sync, :creator_vetting, :creators, :detection, :sub_brands, :usage, :webhooks
+    attr_reader :ai_analysis, :analytics, :brand_accounts, :brands, :comments, :content, :creator_sync, :creator_vetting, :creators, :detection, :sub_brands, :usage, :webhooks
 
     def initialize(api_key: nil, base_url: nil, timeout: 60,
                    max_retries: 2, retry_writes: false, headers: {})
@@ -35,6 +36,7 @@ module Zelf
                                  max_retries: max_retries, retry_writes: retry_writes,
                                  headers: headers)
       @ai_analysis = Resources::AiAnalysis.new(@transport)
+      @analytics = Resources::Analytics.new(@transport)
       @brand_accounts = Resources::BrandAccounts.new(@transport)
       @brands = Resources::Brands.new(@transport)
       @comments = Resources::Comments.new(@transport)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zelf-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Zelf
@@ -22,6 +22,7 @@ files:
 - lib/zelf/models.rb
 - lib/zelf/page.rb
 - lib/zelf/resources/ai_analysis.rb
+- lib/zelf/resources/analytics.rb
 - lib/zelf/resources/brand_accounts.rb
 - lib/zelf/resources/brands.rb
 - lib/zelf/resources/comments.rb