zelf-sdk 1.0.0

data/lib/zelf/transport.rb

@@ -0,0 +1,170 @@
+require 'json'
+require 'net/http'
+require 'uri'
+require 'time'
+
+module Zelf
+  # The production ZelfAI API.
+  DEFAULT_BASE_URL = 'https://api.hellozelf.com'.freeze
+  # Read when no key is passed explicitly.
+  API_KEY_ENV = 'ZELF_API_KEY'.freeze
+  # Read when no base URL is passed explicitly.
+  BASE_URL_ENV = 'ZELF_BASE_URL'.freeze
+
+  # Carries out the HTTP work: auth, retries, and envelope decoding.
+  class Transport
+    RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+    # The API documents no Idempotency-Key header, so a retried write could
+    # create a second analysis, vetting, or sync job.
+    RETRY_SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+    MAX_BACKOFF = 8.0
+
+    attr_reader :base_url, :max_retries, :retry_writes
+
+    def initialize(api_key: nil, base_url: nil, timeout: 60,
+                   max_retries: 2, retry_writes: false, headers: {})
+      base_url ||= ENV[BASE_URL_ENV]
+      base_url = DEFAULT_BASE_URL if base_url.nil? || base_url.empty?
+      key = api_key || ENV[API_KEY_ENV]
+      raise ArgumentError, "an API key is required; pass api_key: or set #{API_KEY_ENV}" if key.nil? || key.empty?
+      raise ArgumentError, 'max_retries must be zero or greater' if max_retries.negative?
+
+      @api_key = key
+      @base_url = base_url.sub(%r{/+\z}, '')
+      @timeout = timeout
+      @max_retries = max_retries
+      @retry_writes = retry_writes
+      # A caller's copy of the API key is dropped whatever its casing, so it
+      # cannot replace the client's own.
+      @headers = headers.reject { |name, _| name.to_s.casecmp?('x-api-key') }
+    end
+
+    # The key must never reach a log line.
+    def inspect
+      "#<Zelf::Transport base_url=#{@base_url.inspect} api_key=\"***\">"
+    end
+
+    def resolve_path(path, path_params)
+      path_params.each do |name, value|
+        if value.nil? || value.to_s.empty?
+          raise ArgumentError, "#{name} is required and must not be empty"
+        end
+
+        path = path.sub("{#{name}}", URI.encode_www_form_component(value.to_s).gsub('+', '%20'))
+      end
+      path
+    end
+
+    def self.encode_query(query)
+      pairs = []
+      query.each do |key, value|
+        next if value.nil?
+
+        Array(value).each do |item|
+          next if item.nil?
+
+          pairs << [key.to_s, stringify(item)]
+        end
+      end
+      pairs
+    end
+
+    def self.stringify(value)
+      case value
+      when true then 'true'
+      when false then 'false'
+      when Time then value.iso8601
+      when Date then value.iso8601
+      else value.to_s
+      end
+    end
+
+    def request(method, path, path_params: {}, query: {}, body: nil)
+      resolved = resolve_path(path.dup, path_params)
+      pairs = self.class.encode_query(query)
+      last = nil
+
+      (0..@max_retries).each do |attempt|
+        response = nil
+        begin
+          response = send_once(method, resolved, pairs, body)
+          return decode(response) if response.code.to_i < 400
+
+          last = Errors.from_response(response)
+        rescue Timeout::Error, Net::OpenTimeout, Net::ReadTimeout => e
+          last = TimeoutError.new(e.message)
+        rescue SystemCallError, SocketError, IOError => e
+          last = ConnectionError.new(e.message)
+        end
+
+        break if attempt == @max_retries || !retry?(method, response)
+
+        sleep(backoff(attempt, response))
+      end
+
+      raise(last || ConnectionError.new('the request was never sent'))
+    end
+
+    private
+
+    def retry?(method, response)
+      return false unless RETRY_SAFE_METHODS.include?(method.to_s.upcase) || @retry_writes
+      return true if response.nil?
+
+      RETRY_STATUSES.include?(response.code.to_i)
+    end
+
+    def backoff(attempt, response)
+      header = response && response['retry-after']
+      if header
+        seconds = Float(header, exception: false)
+        return [seconds, 60.0].min if seconds && seconds >= 0
+      end
+      base = [MAX_BACKOFF, 0.5 * (2**attempt)].min
+      base * (0.5 + (rand / 2))
+    end
+
+    def send_once(method, path, pairs, body)
+      uri = URI.parse("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+
+      request_class = Net::HTTP.const_get(method.to_s.capitalize)
+      request = request_class.new(uri)
+      request['accept'] = 'application/json'
+      request['user-agent'] = "zelf-ruby/#{Zelf::VERSION}"
+      @headers.each { |name, value| request[name.to_s] = value.to_s }
+      # Last, so the client's own key always wins.
+      request['x-api-key'] = @api_key
+      if body
+        request['content-type'] = 'application/json'
+        request.body = JSON.generate(body)
+      end
+
+      Net::HTTP.start(uri.hostname, uri.port,
+                      use_ssl: uri.scheme == 'https',
+                      open_timeout: @timeout,
+                      read_timeout: @timeout) do |http|
+        http.request(request)
+      end
+    end
+
+    def decode(response)
+      return {} if response.code.to_i == 204
+
+      raw = response.body.to_s
+      return {} if raw.strip.empty?
+
+      parsed = begin
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raise APIError.new('the API returned a response that is not valid JSON',
+                           status: response.code.to_i)
+      end
+      unless parsed.is_a?(Hash)
+        raise APIError.new('the API returned a response envelope that is not an object',
+                           status: response.code.to_i)
+      end
+      parsed
+    end
+  end
+end

data/lib/zelf/version.rb

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

data/lib/zelf/webhooks.rb

@@ -0,0 +1,293 @@
+# Generated by codegen. Do not edit by hand.
+
+require 'digest'
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'uri'
+
+module Zelf
+  # Verifies and routes the deliveries ZelfAI posts to a receiver.
+  module Webhooks
+    SIGNATURE_HEADER = 'Webhook-Signature'.freeze
+    TIMESTAMP_HEADER = 'Webhook-Timestamp'.freeze
+    ID_HEADER = 'Webhook-Id'.freeze
+
+    # How far a delivery's timestamp may sit from now before it reads as a replay.
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    # Event types the API can deliver, one per `webhooks` declaration.
+    module EventType
+      # Fires when an AI analysis run reaches a terminal state (COMPLETED or FAILED)
+      AI_ANALYSIS_COMPLETED = "ai_analysis.completed".freeze
+      # Scheduled snapshot of the content set that a subscription matches
+      CONTENT_SNAPSHOT = "content.snapshot".freeze
+      # Scheduled snapshot of the creator set that a subscription matches
+      CREATOR_SNAPSHOT = "creator.snapshot".freeze
+      # Fires when a creator vetting analysis run reaches a terminal state (COMPLETED or...
+      CREATOR_VETTING_COMPLETED = "creator_vetting.completed".freeze
+
+      ALL = [AI_ANALYSIS_COMPLETED, CONTENT_SNAPSHOT, CREATOR_SNAPSHOT, CREATOR_VETTING_COMPLETED].freeze
+
+      # Whether the API declares this event type.
+      def self.known?(value)
+        ALL.include?(value.to_s)
+      end
+    end
+
+    # Raised for every failed verification. Answer one with a 400 and never
+    # process the body.
+    class VerificationError < StandardError; end
+
+    module_function
+
+    def header(headers, name)
+      wanted = name.downcase
+      headers.each do |key, value|
+        return Array(value).first if key.to_s.downcase == wanted
+      end
+      nil
+    end
+
+    def parse_signature(raw)
+      timestamp = nil
+      digests = []
+      raw.to_s.split(',').each do |part|
+        key, _, value = part.strip.partition('=')
+        if key == 't' && timestamp.nil?
+          timestamp = Integer(value, exception: false)
+          raise VerificationError, 'signature timestamp is not an integer' if timestamp.nil?
+        elsif key == 'v1'
+          digests << value
+        end
+      end
+      raise VerificationError, 'signature header is missing a t or v1 component' if timestamp.nil? || digests.empty?
+
+      [timestamp, digests]
+    end
+
+    # Verify a delivery and return the decoded payload as a plain hash.
+    #
+    # +payload+ must be the exact bytes received: re-encoding the JSON changes
+    # the bytes and the signature will not match.
+    #
+    # A rotation switches at once: the API signs the next delivery with the new
+    # secret only and rejects the old one immediately. An array of secrets is
+    # accepted, so both can be held during a rollout.
+    #
+    # The comparison runs through OpenSSL.secure_compare, which is constant
+    # time, so a wrong signature cannot be recovered from response timing.
+    def verify(payload, headers, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      secrets = Array(secret)
+      raise ArgumentError, 'at least one signing secret is required' if secrets.empty?
+
+      raw = header(headers, SIGNATURE_HEADER)
+      raise VerificationError, "missing #{SIGNATURE_HEADER} header" if raw.nil? || raw.empty?
+
+      timestamp, digests = parse_signature(raw)
+
+      if tolerance_seconds.positive?
+        age = ((now || Time.now.to_f) - timestamp).abs
+        if age > tolerance_seconds
+          raise VerificationError,
+                "timestamp is #{age.round}s away from now, outside the " \
+                "#{tolerance_seconds}s tolerance, so this is a replay"
+        end
+      end
+
+      signed = "#{timestamp}.#{payload}"
+      matched = false
+      secrets.each do |candidate|
+        want = OpenSSL::HMAC.hexdigest('SHA256', candidate, signed)
+        digests.each do |got|
+          matched = true if secure_compare(want, got)
+        end
+      end
+      raise VerificationError, 'no signature matched the supplied secrets' unless matched
+
+      body = begin
+        JSON.parse(payload)
+      rescue JSON::ParserError
+        raise VerificationError, 'body is not valid JSON'
+      end
+      raise VerificationError, 'body is not a JSON object' unless body.is_a?(Hash)
+
+      body
+    end
+
+    def secure_compare(left, right)
+      if OpenSSL.respond_to?(:secure_compare)
+        OpenSSL.secure_compare(left, right)
+      else
+        # Ruby 2.6 has no OpenSSL.secure_compare; compare fixed-width digests
+        # byte by byte without an early exit.
+        return false unless left.bytesize == right.bytesize
+
+        left.bytes.zip(right.bytes).reduce(0) { |acc, (a, b)| acc | (a ^ b) }.zero?
+      end
+    end
+
+    # Verify a delivery and return it as a typed Event.
+    def parse(payload, headers, secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS, now: nil)
+      Event.new(verify(payload, headers, secret,
+                       tolerance_seconds: tolerance_seconds, now: now))
+    end
+
+    # A delivery whose signature has already been checked.
+    class Event
+      attr_reader :raw
+
+      def initialize(raw)
+        @raw = raw
+      end
+
+      def id
+        @raw['id']
+      end
+
+      # The wire value, which may be newer than this SDK's EVENT_TYPES.
+      def type
+        @raw['type']
+      end
+
+      # The declared event type, or nil for one the SDK predates.
+      def event_type
+        EventType.known?(type) ? type : nil
+      end
+
+      def subscription_id
+        @raw['subscription_id']
+      end
+
+      def livemode
+        @raw['livemode'] ? true : false
+      end
+
+      def delivered_at
+        Time.at(@raw['delivered_at'].to_i).utc
+      end
+
+      def delivery_mode
+        @raw['delivery_mode']
+      end
+
+      def data
+        @raw['data'] || {}
+      end
+
+      def item_count
+        data['item_count'].to_i
+      end
+
+      # Downloadable snapshot files. Populated in +manifest+ mode only.
+      def files
+        Array(data['files'])
+      end
+
+      # Rows carried in the body. Populated in +inline+ mode only.
+      def items
+        Array(data['items'])
+      end
+
+      def statistics
+        data['statistics']
+      end
+
+      def inspect
+        "#<Zelf::Webhooks::Event #{type} id=#{id} items=#{item_count}>"
+      end
+
+      # Download the manifest files and yield one decoded row per line.
+      #
+      # Each download_url is signed and expires, so fetch soon after delivery.
+      # With +verify_checksum+ the published SHA-256 is recomputed over the
+      # body, and a mismatch or a missing digest raises before any row is
+      # yielded.
+      def rows(verify_checksum: true, http_get: nil)
+        return enum_for(:rows, verify_checksum: verify_checksum, http_get: http_get) unless block_given?
+
+        files.each do |handle|
+          body = (http_get || method(:fetch)).call(handle['download_url'])
+          if verify_checksum
+            published = handle['sha256'].to_s
+            if published.empty?
+              raise VerificationError,
+                    "the manifest published no sha256 for #{handle['download_url']}, so the " \
+                    'file cannot be verified; pass verify_checksum: false to read it unchecked'
+            end
+            digest = Digest::SHA256.hexdigest(body)
+            unless Webhooks.secure_compare(digest, published)
+              raise VerificationError,
+                    "downloaded file digest #{digest} does not match the published #{published}"
+            end
+          end
+          body.each_line do |line|
+            next if line.strip.empty?
+
+            yield JSON.parse(line)
+          end
+        end
+        nil
+      end
+
+      private
+
+      def fetch(url)
+        uri = URI.parse(url)
+        response = Net::HTTP.get_response(uri)
+        unless response.code.to_i < 400
+          raise VerificationError, "downloading the snapshot failed with HTTP #{response.code}"
+        end
+
+        response.body.to_s
+      end
+    end
+
+    # Verify a delivery once, then route it to the listener for its type.
+    #
+    # Framework agnostic: hand it the raw body and the request headers from
+    # whatever server is in front of it.
+    class Handler
+      def initialize(secret, tolerance_seconds: DEFAULT_TOLERANCE_SECONDS)
+        @secret = secret
+        @tolerance_seconds = tolerance_seconds
+        @listeners = {}
+        @fallback = nil
+      end
+
+      # Register a listener for one or more event types.
+      def on(*event_types, &listener)
+        raise ArgumentError, 'pass at least one event type to listen for' if event_types.empty?
+
+        unknown = event_types.map(&:to_s).reject { |name| EventType.known?(name) }
+        unless unknown.empty?
+          raise ArgumentError,
+                "unknown event type(s) #{unknown.join(', ')}. " \
+                "Known types: #{EventType::ALL.join(', ')}"
+        end
+
+        event_types.each { |name| (@listeners[name.to_s] ||= []) << listener }
+        self
+      end
+
+      # Register the listener used when no type specific one matched.
+      def on_any(&listener)
+        @fallback = listener
+        self
+      end
+
+      # Verify, then call every listener registered for the event type. Raises
+      # before any listener runs if the delivery does not check out.
+      def handle(payload, headers, now: nil)
+        event = Webhooks.parse(payload, headers, @secret,
+                               tolerance_seconds: @tolerance_seconds, now: now)
+        listeners = @listeners[event.type]
+        if listeners.nil? || listeners.empty?
+          return @fallback ? [@fallback.call(event)] : []
+        end
+
+        listeners.map { |listener| listener.call(event) }
+      end
+    end
+  end
+end

data/lib/zelf.rb

@@ -0,0 +1,59 @@
+# Generated by codegen. Do not edit by hand.
+require_relative 'zelf/version'
+require_relative 'zelf/errors'
+require_relative 'zelf/model'
+require_relative 'zelf/models'
+require_relative 'zelf/transport'
+require_relative 'zelf/page'
+require_relative 'zelf/webhooks'
+require_relative 'zelf/resources/ai_analysis'
+require_relative 'zelf/resources/brand_accounts'
+require_relative 'zelf/resources/brands'
+require_relative 'zelf/resources/comments'
+require_relative 'zelf/resources/content'
+require_relative 'zelf/resources/creator_sync'
+require_relative 'zelf/resources/creator_vetting'
+require_relative 'zelf/resources/creators'
+require_relative 'zelf/resources/detection'
+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).
+module Zelf
+  # Client for the ZelfAI APIs.
+  #
+  # The key comes from the api_key: argument, falling back to the
+  # 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
+
+    def initialize(api_key: nil, base_url: nil, timeout: 60,
+                   max_retries: 2, retry_writes: false, headers: {})
+      @transport = Transport.new(api_key: api_key, base_url: base_url, timeout: timeout,
+                                 max_retries: max_retries, retry_writes: retry_writes,
+                                 headers: headers)
+      @ai_analysis = Resources::AiAnalysis.new(@transport)
+      @brand_accounts = Resources::BrandAccounts.new(@transport)
+      @brands = Resources::Brands.new(@transport)
+      @comments = Resources::Comments.new(@transport)
+      @content = Resources::Content.new(@transport)
+      @creator_sync = Resources::CreatorSync.new(@transport)
+      @creator_vetting = Resources::CreatorVetting.new(@transport)
+      @creators = Resources::Creators.new(@transport)
+      @detection = Resources::Detection.new(@transport)
+      @sub_brands = Resources::SubBrands.new(@transport)
+      @usage = Resources::Usage.new(@transport)
+      @webhooks = Resources::Webhooks.new(@transport)
+    end
+
+    def base_url
+      @transport.base_url
+    end
+
+    def inspect
+      "#<Zelf::Client base_url=#{base_url.inspect} api_key=\"***\">"
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: zelf-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Zelf
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Official Ruby client for the Zelf API.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/zelf.rb
+- lib/zelf/errors.rb
+- lib/zelf/model.rb
+- lib/zelf/models.rb
+- lib/zelf/page.rb
+- lib/zelf/resources/ai_analysis.rb
+- lib/zelf/resources/brand_accounts.rb
+- lib/zelf/resources/brands.rb
+- lib/zelf/resources/comments.rb
+- lib/zelf/resources/content.rb
+- lib/zelf/resources/creator_sync.rb
+- lib/zelf/resources/creator_vetting.rb
+- lib/zelf/resources/creators.rb
+- lib/zelf/resources/detection.rb
+- lib/zelf/resources/sub_brands.rb
+- lib/zelf/resources/usage.rb
+- lib/zelf/resources/webhooks.rb
+- lib/zelf/transport.rb
+- lib/zelf/version.rb
+- lib/zelf/webhooks.rb
+homepage: https://github.com/hellozelf/zelf-sdk
+licenses:
+- Apache-2.0
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/hellozelf/zelf-sdk
+  changelog_uri: https://github.com/hellozelf/zelf-sdk/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/hellozelf/zelf-sdk/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the ZelfAI APIs
+test_files: []