knievel 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a60381b28c6db8b19d340cd8c5f702aa1831fb5d360e12cb373a67df55776e7
-  data.tar.gz: bed2c614631031e1e56cd2a8ecba46ccacacee369acce7e30e08ed554c253b13
+  metadata.gz: 76508b7a3c559ea20c2c3e693db94332b6ba8f7fc8059705b32d869240e8166f
+  data.tar.gz: 0f34f12b4a0e45193769e98d018ff688ca5392c6664a63a888fa67f5a0791c4f
 SHA512:
-  metadata.gz: 9e19b85b28a9295d69d93f6116c24df8075e4f7164aaab717b62bd38c314f8045d4a110cff56a38f17b187b734e5b01fbd31d5d09a2bff5c4c2d6379ebc81976
-  data.tar.gz: a2d48eb90031f3ea85d5131015d4ea3a8efb887a9ba3a556a17429a6a22cfc8e18e99c35c5501dcbecd40dbf053244d5ad5b1c0a3ee7233f71b720cf9efe60c8
+  metadata.gz: 64e02e131435fcb3d5a2154469cbcee417456140f5045688ade9cd8531cfa2a0fb10f08c138689f992575f7729acf0c6dbc340ed6da915e36b6691e84d6ee5bd
+  data.tar.gz: 42640a24ba684d28147f83a234f859f1842eb22057d6103853953ce5e7808c57a81a7267c36eb91d1be021c1b5883fb86d736d04154cb64066ed9d16d6e41ac0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    knievel (0.1.4)
+    knievel (0.1.5)
       faraday (>= 1.0.1, < 3.0)
       faraday-multipart
       marcel

data/README.md

@@ -7,7 +7,7 @@ No description provided (generated by Openapi Generator https://github.com/opena
 This SDK is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:
 
 - API version: 0.1.0
-- Package version: 0.1.4
+- Package version: 0.1.5
 - Generator version: 7.23.0-SNAPSHOT
 - Build package: org.openapitools.codegen.languages.RubyClientCodegen
 
@@ -24,16 +24,16 @@ gem build knievel.gemspec
 Then either install the gem locally:
 
 ```shell
-gem install ./knievel-0.1.4.gem
+gem install ./knievel-0.1.5.gem
 ```
 
-(for development, run `gem install --dev ./knievel-0.1.4.gem` to install the development dependencies)
+(for development, run `gem install --dev ./knievel-0.1.5.gem` to install the development dependencies)
 
 or publish the gem to a gem hosting service, e.g. [RubyGems](https://rubygems.org/).
 
 Finally add this to the Gemfile:
 
-    gem 'knievel', '~> 0.1.4'
+    gem 'knievel', '~> 0.1.5'
 
 ### Install from Git
 

data/lib/knievel/client.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "uri"
+require "knievel"
+require_relative "resources"
+
+module Knievel
+  # Convenience facade around the generated transport
+  # (`Knievel::ApiClient` + `Knievel::Configuration`) and the
+  # hand-written `Knievel::Resources::*` wrappers.
+  #
+  # Typical usage:
+  #
+  #   client = Knievel::Client.new(
+  #     host: "https://api.knievel-ads.example",
+  #     access_token: ENV.fetch("KNIEVEL_TOKEN"),
+  #   )
+  #
+  #   client.advertisers("pj_abc").each { |adv| puts adv.name }
+  #   client.advertisers("pj_abc").first(10)
+  #   client.advertisers("pj_abc").lazy.select(&:is_active).first(20)
+  #   client.advertisers("pj_abc").each_page { |page| process(page) }
+  #
+  # Pass `page_size:` to a resource accessor to override the
+  # default 500-row page size:
+  #
+  #   client.advertisers("pj_abc", page_size: 50).each { ... }
+  class Client
+    # `host` is the API base URL — accepts either a full URL
+    # (`https://api.knievel-ads.example`,
+    # `http://localhost:8080`) or a bare hostname. The
+    # generated `Configuration#host=` setter strips the scheme
+    # silently, so we parse the URL ourselves to keep the
+    # scheme/port the caller intended. Falls back to the
+    # spec-stamped default (`http://localhost:8080`) when
+    # omitted — handy for local dev against compose.
+    #
+    # `access_token` is the bearer token. The `Configuration`
+    # block is a convenience for callers that need to twiddle
+    # other settings (timeouts, custom headers, etc.) before
+    # the underlying `ApiClient` materializes.
+    def initialize(host: nil, access_token: nil)
+      @config = Knievel::Configuration.new
+      apply_host(host) if host
+      @config.access_token = access_token if access_token
+      yield @config if block_given?
+      @api_client = Knievel::ApiClient.new(@config)
+    end
+
+    private def apply_host(host)
+      uri = URI.parse(host)
+      if uri.scheme && uri.host
+        @config.scheme = uri.scheme
+        @config.host = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+      else
+        # Bare hostname (no scheme). Trust the configured default
+        # scheme and let `Configuration#host=` do its sanitization.
+        @config.host = host
+      end
+    end
+
+    public
+
+    # Underlying generated transport. Reach for this when you
+    # need the non-paginated endpoints (single `get_*`,
+    # `create_*`, `update_*`) — the hand-written wrappers only
+    # cover list operations.
+    attr_reader :api_client
+
+    def advertisers(project_id, **opts)
+      Resources::Advertisers.new(@api_client, project_id, **opts)
+    end
+
+    def campaigns(project_id, **opts)
+      Resources::Campaigns.new(@api_client, project_id, **opts)
+    end
+
+    def flights(project_id, **opts)
+      Resources::Flights.new(@api_client, project_id, **opts)
+    end
+
+    def ads(project_id, **opts)
+      Resources::Ads.new(@api_client, project_id, **opts)
+    end
+
+    def creatives(project_id, **opts)
+      Resources::Creatives.new(@api_client, project_id, **opts)
+    end
+
+    def creative_templates(project_id, **opts)
+      Resources::CreativeTemplates.new(@api_client, project_id, **opts)
+    end
+
+    def sites(project_id, **opts)
+      Resources::Sites.new(@api_client, project_id, **opts)
+    end
+
+    def zones(project_id, **opts)
+      Resources::Zones.new(@api_client, project_id, **opts)
+    end
+  end
+end

data/lib/knievel/resources/ads.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Ads < Base
+      def list_method
+        :list_ads
+      end
+
+      def api_class
+        Knievel::AdsApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/advertisers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Advertisers < Base
+      def list_method
+        :list_advertisers
+      end
+
+      def api_class
+        Knievel::AdvertisersApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/base.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "knievel"
+
+module Knievel
+  module Resources
+    # Base class for hand-written list-endpoint wrappers that
+    # turn a paginated `list_*` API method into an `Enumerable`.
+    #
+    # Subclasses declare `list_method` (the snake_case method
+    # on the generated `*Api` class) and `api_class` (the
+    # generated class itself); this base handles the cursor
+    # walk and limit defaulting.
+    #
+    # See `REQUIREMENTS.md` § 8 item 3 ("idiomatic Ruby use
+    # including each, each_page, lazy, first(n), and
+    # short-circuiting iteration — all without the caller
+    # writing pagination loops") and `API.md` § "Pagination"
+    # (limit defaults 50, max 500; cursor is opaque, only
+    # valid for the endpoint that minted it).
+    #
+    # The default `each_page` walks the maximum 500-row page
+    # size to minimize HTTP round-trips. Callers that want
+    # smaller pages (e.g. low-latency progress reporting) can
+    # override via `page_size:` on the subclass constructor.
+    class Base
+      include Enumerable
+
+      # Server cap. Larger values fail with `400 invalid_limit`.
+      MAX_PAGE_SIZE = 500
+
+      # Subclasses override:
+      #   def list_method = :list_<resource>
+      #   def api_class   = Knievel::<Resource>Api
+      def list_method
+        raise NotImplementedError
+      end
+
+      def api_class
+        raise NotImplementedError
+      end
+
+      # `api_client` is a `Knievel::ApiClient` (the generated
+      # transport, holds the base URL + auth). `project_id` is
+      # the path scope. `**filters` are forwarded to the
+      # generated `list_*` method as `opts` — once the server
+      # implements query-param filtering (e.g. `external_id=`)
+      # those keys flow through unchanged.
+      def initialize(api_client, project_id, page_size: MAX_PAGE_SIZE, **filters)
+        if page_size < 1 || page_size > MAX_PAGE_SIZE
+          raise ArgumentError, "page_size must be between 1 and #{MAX_PAGE_SIZE}"
+        end
+        @api_client = api_client
+        @project_id = project_id
+        @page_size = page_size
+        @filters = filters
+      end
+
+      # `Enumerable` plumbing — yields rows one at a time
+      # across the entire cursor walk. Returns an `Enumerator`
+      # when called without a block (so `lazy`, `first(n)`,
+      # `take_while`, etc. work).
+      def each(&block)
+        return enum_for(:each) unless block_given?
+
+        each_page do |page_items|
+          page_items.each(&block)
+        end
+      end
+
+      # Yields one array per page. Useful for batch-style
+      # processing where per-row work has setup overhead worth
+      # amortizing. Returns an `Enumerator` without a block.
+      def each_page
+        return enum_for(:each_page) unless block_given?
+
+        cursor = nil
+        api = api_class.new(@api_client)
+        loop do
+          opts = @filters.merge(limit: @page_size)
+          opts[:cursor] = cursor unless cursor.nil?
+          response = api.public_send(list_method, @project_id, opts)
+          yield response.items
+          cursor = response.next_cursor
+          break if cursor.nil?
+        end
+      end
+    end
+  end
+end

data/lib/knievel/resources/campaigns.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Campaigns < Base
+      def list_method
+        :list_campaigns
+      end
+
+      def api_class
+        Knievel::CampaignsApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/creative_templates.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class CreativeTemplates < Base
+      def list_method
+        :list_creative_templates
+      end
+
+      def api_class
+        Knievel::CreativeTemplatesApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/creatives.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Creatives < Base
+      def list_method
+        :list_creatives
+      end
+
+      def api_class
+        Knievel::CreativesApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/flights.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Flights < Base
+      def list_method
+        :list_flights
+      end
+
+      def api_class
+        Knievel::FlightsApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/sites.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Sites < Base
+      def list_method
+        :list_sites
+      end
+
+      def api_class
+        Knievel::SitesApi
+      end
+    end
+  end
+end

data/lib/knievel/resources/zones.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Knievel
+  module Resources
+    class Zones < Base
+      def list_method
+        :list_zones
+      end
+
+      def api_class
+        Knievel::ZonesApi
+      end
+    end
+  end
+end

data/lib/knievel/resources.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Hand-written `Enumerable` wrappers over the generated `*Api`
+# classes. See `REQUIREMENTS.md` § 8 item 3 and `Knievel::Client`
+# for the typical entry point. Each subclass is one paginated
+# resource; cursor walks are uniform across all of them via
+# `Knievel::Resources::Base`.
+
+require_relative "resources/base"
+require_relative "resources/advertisers"
+require_relative "resources/campaigns"
+require_relative "resources/flights"
+require_relative "resources/ads"
+require_relative "resources/creatives"
+require_relative "resources/creative_templates"
+require_relative "resources/sites"
+require_relative "resources/zones"

data/lib/knievel/version.rb

@@ -11,5 +11,5 @@ Generator version: 7.23.0-SNAPSHOT
 =end
 
 module Knievel
-  VERSION = '0.1.4'
+  VERSION = '0.1.5'
 end

data/spec/client_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ostruct"
+require "knievel/client"
+
+RSpec.describe Knievel::Client do
+  describe "#initialize" do
+    it "splits a full URL into scheme/host on the underlying Configuration" do
+      client = described_class.new(host: "https://example.test", access_token: "kvl_xyz")
+      expect(client.api_client.config.scheme).to eq("https")
+      expect(client.api_client.config.host).to eq("example.test")
+      expect(client.api_client.config.access_token).to eq("kvl_xyz")
+    end
+
+    it "preserves a non-default port on the host" do
+      client = described_class.new(host: "http://localhost:8080")
+      expect(client.api_client.config.scheme).to eq("http")
+      expect(client.api_client.config.host).to eq("localhost:8080")
+    end
+
+    it "accepts a bare hostname (no scheme) and trusts the configured default scheme" do
+      client = described_class.new(host: "example.test")
+      expect(client.api_client.config.host).to eq("example.test")
+    end
+
+    it "yields the configuration block for advanced tweaks" do
+      client = described_class.new(host: "https://example.test") do |config|
+        config.access_token = "kvl_via_block"
+      end
+      expect(client.api_client.config.access_token).to eq("kvl_via_block")
+    end
+
+    it "leaves the configuration default host alone when host: omitted" do
+      default = Knievel::Configuration.new.host
+      client = described_class.new(access_token: "kvl_xyz")
+      expect(client.api_client.config.host).to eq(default)
+    end
+  end
+
+  describe "resource accessors" do
+    let(:client) { described_class.new(access_token: "kvl_xyz") }
+
+    {
+      advertisers: Knievel::Resources::Advertisers,
+      campaigns: Knievel::Resources::Campaigns,
+      flights: Knievel::Resources::Flights,
+      ads: Knievel::Resources::Ads,
+      creatives: Knievel::Resources::Creatives,
+      creative_templates: Knievel::Resources::CreativeTemplates,
+      sites: Knievel::Resources::Sites,
+      zones: Knievel::Resources::Zones,
+    }.each do |method, klass|
+      it "##{method} returns a #{klass.name.split('::').last} bound to the project" do
+        resource = client.public_send(method, "pj_abc")
+        expect(resource).to be_a(klass)
+        expect(resource).to be_a(Enumerable)
+      end
+    end
+
+    it "forwards page_size + filter kwargs to the resource constructor" do
+      resource = client.advertisers("pj_abc", page_size: 25, external_id: "acme")
+      # Stub out the api_class so calling #to_a doesn't try real HTTP.
+      api = instance_double(Knievel::AdvertisersApi)
+      allow(Knievel::AdvertisersApi).to receive(:new).and_return(api)
+      expect(api).to receive(:list_advertisers)
+        .with("pj_abc", { external_id: "acme", limit: 25 })
+        .and_return(OpenStruct.new(items: [], next_cursor: nil))
+      resource.to_a
+    end
+  end
+end

data/spec/resources/advertisers_spec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "ostruct"
+require "knievel/client"
+
+# Exercises the wrapper contract via the Advertisers resource —
+# representative of all eight `Knievel::Resources::*` classes
+# (they share `Resources::Base`, so per-class divergence is
+# only the constants).
+
+RSpec.describe Knievel::Resources::Advertisers do
+  let(:api_client) { instance_double(Knievel::ApiClient) }
+  let(:api) { instance_double(Knievel::AdvertisersApi) }
+  let(:project_id) { "pj_abc" }
+
+  before do
+    allow(Knievel::AdvertisersApi).to receive(:new).with(api_client).and_return(api)
+  end
+
+  def page(item_ids, next_cursor:)
+    items = item_ids.map { |id| OpenStruct.new(id: id, name: "adv-#{id}") }
+    OpenStruct.new(items: items, next_cursor: next_cursor)
+  end
+
+  describe "#each" do
+    it "walks every page and yields rows in order until next_cursor is nil" do
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { limit: 500 })
+        .and_return(page([1, 2, 3], next_cursor: "c1"))
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { limit: 500, cursor: "c1" })
+        .and_return(page([4, 5], next_cursor: "c2"))
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { limit: 500, cursor: "c2" })
+        .and_return(page([6], next_cursor: nil))
+
+      collected = described_class.new(api_client, project_id).map(&:id)
+      expect(collected).to eq([1, 2, 3, 4, 5, 6])
+    end
+
+    it "honors a non-default page_size on the underlying limit param" do
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { limit: 50 })
+        .and_return(page([1], next_cursor: nil))
+
+      described_class.new(api_client, project_id, page_size: 50).to_a
+    end
+
+    it "passes filter kwargs through to the generated API call" do
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { external_id: "acme", limit: 500 })
+        .and_return(page([1], next_cursor: nil))
+
+      described_class.new(api_client, project_id, external_id: "acme").to_a
+    end
+
+    it "returns an Enumerator without a block" do
+      enumerator = described_class.new(api_client, project_id).each
+      expect(enumerator).to be_a(Enumerator)
+    end
+  end
+
+  describe "Enumerable laziness" do
+    it "stops fetching pages once `first(n)` is satisfied" do
+      expect(api).to receive(:list_advertisers)
+        .once
+        .with(project_id, { limit: 500 })
+        .and_return(page([1, 2, 3], next_cursor: "should-not-be-followed"))
+
+      result = described_class.new(api_client, project_id).lazy.first(2)
+      expect(result.map(&:id)).to eq([1, 2])
+    end
+
+    it "supports short-circuiting `take_while` over the lazy walk" do
+      expect(api).to receive(:list_advertisers)
+        .once
+        .with(project_id, { limit: 500 })
+        .and_return(page([1, 2, 3, 4], next_cursor: "should-not-be-followed"))
+
+      result = described_class.new(api_client, project_id).lazy.take_while { |a| a.id < 3 }.to_a
+      expect(result.map(&:id)).to eq([1, 2])
+    end
+  end
+
+  describe "#each_page" do
+    it "yields one array per cursor hop" do
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { limit: 500 })
+        .and_return(page([1, 2], next_cursor: "c1"))
+      expect(api).to receive(:list_advertisers)
+        .with(project_id, { limit: 500, cursor: "c1" })
+        .and_return(page([3], next_cursor: nil))
+
+      pages = []
+      described_class.new(api_client, project_id).each_page { |p| pages << p.map(&:id) }
+      expect(pages).to eq([[1, 2], [3]])
+    end
+  end
+
+  describe "page_size validation" do
+    it "rejects page_size < 1" do
+      expect {
+        described_class.new(api_client, project_id, page_size: 0)
+      }.to raise_error(ArgumentError, /between 1 and 500/)
+    end
+
+    it "rejects page_size > 500" do
+      expect {
+        described_class.new(api_client, project_id, page_size: 501)
+      }.to raise_error(ArgumentError, /between 1 and 500/)
+    end
+
+    it "accepts page_size at the boundary" do
+      expect {
+        described_class.new(api_client, project_id, page_size: 500)
+      }.not_to raise_error
+      expect {
+        described_class.new(api_client, project_id, page_size: 1)
+      }.not_to raise_error
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: knievel
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Knievel Ads
@@ -211,6 +211,7 @@ files:
 - lib/knievel/api_client.rb
 - lib/knievel/api_error.rb
 - lib/knievel/api_model_base.rb
+- lib/knievel/client.rb
 - lib/knievel/configuration.rb
 - lib/knievel/models/ad.rb
 - lib/knievel/models/ad_library_item.rb
@@ -297,6 +298,16 @@ files:
 - lib/knievel/models/version_response.rb
 - lib/knievel/models/zone.rb
 - lib/knievel/models/zone_list.rb
+- lib/knievel/resources.rb
+- lib/knievel/resources/ads.rb
+- lib/knievel/resources/advertisers.rb
+- lib/knievel/resources/base.rb
+- lib/knievel/resources/campaigns.rb
+- lib/knievel/resources/creative_templates.rb
+- lib/knievel/resources/creatives.rb
+- lib/knievel/resources/flights.rb
+- lib/knievel/resources/sites.rb
+- lib/knievel/resources/zones.rb
 - lib/knievel/version.rb
 - openapi-generator-config.json
 - spec/api/ad_library_api_spec.rb
@@ -315,6 +326,7 @@ files:
 - spec/api/taxonomy_api_spec.rb
 - spec/api/tokens_api_spec.rb
 - spec/api/zones_api_spec.rb
+- spec/client_spec.rb
 - spec/models/ad_library_item_list_spec.rb
 - spec/models/ad_library_item_spec.rb
 - spec/models/ad_list_spec.rb
@@ -400,6 +412,7 @@ files:
 - spec/models/version_response_spec.rb
 - spec/models/zone_list_spec.rb
 - spec/models/zone_spec.rb
+- spec/resources/advertisers_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/knievel-ads/knievel-ruby
 licenses:
@@ -441,6 +454,7 @@ test_files:
 - spec/api/flights_api_spec.rb
 - spec/api/ads_api_spec.rb
 - spec/api/tokens_api_spec.rb
+- spec/client_spec.rb
 - spec/models/error_envelope_spec.rb
 - spec/models/create_ad_library_item_request_spec.rb
 - spec/models/ad_type_list_spec.rb
@@ -526,4 +540,5 @@ test_files:
 - spec/models/force_override_spec.rb
 - spec/models/create_zone_request_spec.rb
 - spec/models/batch_upsert_sites_request_spec.rb
+- spec/resources/advertisers_spec.rb
 - spec/spec_helper.rb