bitly 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '095c28dc60c45e049f9fde01119376322ea8438ca0b9074479de7bd903af55ed'
-  data.tar.gz: 59df185cab7f082fbdfedc7bc857c79a4bba69b9913d3b91e40effb4852e852e
+  metadata.gz: c3f7e8ce05cc1176818efa7b83c94fd1e6f6bcc7ce4caefdfc7f719aab18bbd9
+  data.tar.gz: 38593047cf4f4b02b6e45a457cce9d698e3f11b3bc06337d1ebcc0953ba1cb28
 SHA512:
-  metadata.gz: dc18dd77b07180334af8adb1961fcefc32b56b2920c7400d6d6e04e33fff054cf1086499defae0cf0c88388afbc4cddd167d365ba87ca3be553d0508a3dc104a
-  data.tar.gz: 77b804e7d11ba3f82ca7a5329357261a75b592e94b3eb761f120fd0380a0ddca62ee1f717601885e936b5f5e081d6f01f086ef3b4e04d464237167f535497359
+  metadata.gz: 34f1f1d76f0f984f4ba22069aee1280332c1fe5deead1bb2572257dad0ebbb8a97e9c7e642d4270bc495fe5aafde7ba6ce7e98980685e4a37ecbec58b74ad074
+  data.tar.gz: 4f772f32325b0fc59c76ceef45634aee7ea0f0c4a81985051ca09286b4c570c92077cb1e05b233c2d8287987ffb3636f6386a125e214810b20837adc86509662

data/.github/workflows/sonarcloud.yml

@@ -4,9 +4,9 @@ on:
       - main
   pull_request:
     types: [opened, synchronize, reopened]
-name: SonarCloud Analysis
+name: SonarQube Analysis
 jobs:
-  sonarcloud:
+  sonarqube:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
@@ -23,12 +23,8 @@ jobs:
         run: bundle exec rspec
         env:
           COVERAGE: json
-      - name: fix code coverage paths
-        working-directory: ./coverage
-        run: |
-          sed -i 's@'$GITHUB_WORKSPACE'@/github/workspace/@g' coverage.json
-      - name: SonarCloud Scan
-        uses: sonarsource/sonarcloud-github-action@master
+      - name: SonarQube Scan
+        uses: SonarSource/sonarqube-scan-action@v5.0.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

data/.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: [2.5, 2.6, 2.7, "3.0", 3.1, head]
+        ruby: [2.5, 2.6, 2.7, "3.0", 3.1, 3.2, 3.3, 3.4, head]
     continue-on-error: ${{ endsWith(matrix.ruby, 'head') }}
     steps:
       - uses: actions/checkout@v2

data/History.txt

@@ -1,5 +1,11 @@
 === Ongoing
 
+=== 3.1.0 / 2025-02-18
+
+* Adds `Qrcode` class and methods to fetch qrcodes and list qrcodes by group as well as get a summary of scans and retrieve an image
+* Adds Ruby 3.4 to test matrix
+* Updates to latest SonarQube scanner
+
 === 3.0.0 / 2022-11-08
 
 * **Breaking** Removes Group DELETE and Oauth Apps endpoints

data/README.md

@@ -4,27 +4,29 @@ A Ruby gem for using the version 4 [Bitly API](https://dev.bitly.com/) to shorte
 
 [![Gem version](https://badge.fury.io/rb/bitly.svg)](https://rubygems.org/gems/bitly) ![Build status](https://github.com/philnash/bitly/workflows/tests/badge.svg) [![Maintainability](https://api.codeclimate.com/v1/badges/f8e078b468c1f2aeca53/maintainability)](https://codeclimate.com/github/philnash/bitly/maintainability) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=philnash_bitly&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=philnash_bitly) [![Inline docs](https://inch-ci.org/github/philnash/bitly.svg?branch=master)](https://inch-ci.org/github/philnash/bitly)
 
-* [Installation](#installation)
-* [Usage](#usage)
-  * [Authentication](#authentication)
-  * [Creating an API client](#creating-an-api-client)
-  * [Shorten a link](#shorten-a-link)
-  * [Expand a link](#expand-a-link)
-* [Available API Endpoints](#available-api-endpoints)
-  * [Groups](#groups)
-  * [Organizations](#organizations)
-  * [Users](#users)
-  * [Bitlinks](#bitlinks)
-  * [Custom Bitlinks](#custom-bitlinks)
-  * [Campaigns](#campaigns)
-  * [BSDs (Branded Short Domains)](#bsds-branded-short-domains)
-  * [Webhooks](#webhooks)
-* [Customising HTTP requests](#customising-http-requests)
-  * [Build your own adapter](#build-your-own-adapter)
-* [Development](#development)
-* [Contributing](#contributing)
-* [License](#license)
-* [Code of Conduct](#code-of-conduct)
+* [Bitly](#bitly)
+  * [Installation](#installation)
+  * [Usage](#usage)
+    * [Authentication](#authentication)
+    * [Creating an API client](#creating-an-api-client)
+    * [Shorten a link](#shorten-a-link)
+    * [Expand a link](#expand-a-link)
+  * [Available API Endpoints](#available-api-endpoints)
+    * [Groups](#groups)
+    * [Organizations](#organizations)
+    * [Users](#users)
+    * [Bitlinks](#bitlinks)
+    * [QR codes](#qr-codes)
+    * [Custom Bitlinks](#custom-bitlinks)
+    * [Campaigns](#campaigns)
+    * [BSDs (Branded Short Domains)](#bsds-branded-short-domains)
+    * [Webhooks](#webhooks)
+  * [Customising HTTP requests](#customising-http-requests)
+    * [Build your own adapter](#build-your-own-adapter)
+  * [Development](#development)
+  * [Contributing](#contributing)
+  * [License](#license)
+  * [Code of Conduct](#code-of-conduct)
 
 ## Installation
 
@@ -48,6 +50,8 @@ $ gem install bitly
 
 ## Usage
 
+For a quick introduction, read this blog post on [how to use the Bitly API in Ruby](https://philna.sh/blog/2022/11/09/how-to-use-the-bitly-api-in-ruby/).
+
 ### Authentication
 
 All API endpoints require authentication with an OAuth token. You can get your own OAuth token from the [Bitly console](https://app.bitly.com/). Click on the account drop down menu, then _Profile Settings_ then _Generic Access Token_. Fill in your password and you can generate an OAuth access token.
@@ -105,6 +109,7 @@ This gem supports the following active v4 API endpoints for the[Bitly API](https
 - [x] [Retrieve group shorten counts (`GET /v4/groups/{group_guid}/shorten_counts`)](https://dev.bitly.com/api-reference/#getGroupShortenCounts)
 - [x] [Retrieve click metrics for a group by referring networks (`GET /v4/groups/{group_guid}/referring_networks`)](https://dev.bitly.com/api-reference/#GetGroupMetricsByReferringNetworks)
 - [x] [Retrieve click metrics for a group by countries (`GET /v4/groups/{group_guid}/countries`)](https://dev.bitly.com/api-reference/#getGroupMetricsByCountries)
+- [X] [Retrieve QR codes for a group (`GET /v4/groups/{group_guid}/qr-codes`)](https://dev.bitly.com/api-reference/#listQRMinimal)
 - [ ] __[premium]__ [Retrieve click metrics for a group by city (`GET /v4/groups/{group_guid}/cities`)](https://dev.bitly.com/api-reference/#getGroupMetricsByCities)
 - [ ] __[premium]__ [Get group overrides (`GET /v4/groups/{group_guid}/overrides`)](https://dev.bitly.com/api-reference/#getOverridesForGroups)
 
@@ -141,9 +146,14 @@ This gem supports the following active v4 API endpoints for the[Bitly API](https
 - [x] [Get metrics for a Bitlink by referrers by domain (`GET /v4/bitlinks/{bitlink}/referrers_by_domains`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByReferrersByDomains)
 - [ ] __[premium]__ [Get metrics for a Bitlink by city (`GET /v4/bitlinks/{bitlink}/cities`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByCities)
 - [ ] __[premium]__ [Get metrics for a Bitlink by device type (`GET /v4/bitlinks/{bitlink}/devices`)](https://dev.bitly.com/api-reference/#getMetricsForBitlinkByDevices)
-- [ ] __[premium]__ [Retrieve a QR code for a Bitlink (`GET /v4/bitlinks/{bitlink}/qr`)](https://dev.bitly.com/api-reference/#getBitlinkQRCode)
-- [ ] __[premium]__ [Update a QR code (`PATCH /v4/bitlinks/{bitlink}/qr`)](https://dev.bitly.com/api-reference/#updateBitlinkQRCode)
-- [ ] __[premium]__ [Create a QR code (`POST /v4/bitlinks/{bitlink}/qr`)](https://dev.bitly.com/api-reference/#createBitlinkQRCode)
+
+### QR codes
+
+[QR codes documentation](docs/qrcodes.md)
+
+- [x] [Retrieve a QR code (`GET /v4/qr-codes/{qrcode_id}`)](https://dev.bitly.com/api-reference/#getQRCodeByIdPublic)
+- [x] [Retrieve the scans summary for a QR code (`GET /v4/qr-codes/{qrcode_id}/scans/summary`)](https://dev.bitly.com/api-reference/#getScanMetricsSummaryForQRCode)
+- [x] [Retrieve a QR code image (`GET /v4/qr-codes/{qrcode_id}/image`)](https://dev.bitly.com/api-reference/#getQRCodeImagePublic)
 
 ### Custom Bitlinks
 

data/lib/bitly/api/base.rb

@@ -20,4 +20,4 @@ module Bitly
       end
     end
   end
-end
+end

data/lib/bitly/api/bitlink/paginated_list.rb

@@ -1,52 +1,18 @@
 # frozen_string_literal: true
-require "cgi"
-require "uri"
+require_relative "../paginated_list"
 
 module Bitly
   module API
     class Bitlink
-      class PaginatedList < Bitly::API::List
-        attr_reader :next_url, :prev_url, :size, :page, :total
-
-        def initialize(items:, response: , client:)
-          super(items: items, response: response)
-          @client = client
-          if response.body["pagination"]
-            pagination = response.body["pagination"]
-            @next_url = pagination["next"]
-            @prev_url = pagination["prev"]
-            @size = pagination["size"]
-            @page = pagination["page"]
-            @total = pagination["total"]
-          end
-        end
-
-        def has_next_page?
-          !next_url.nil? && !next_url.empty?
-        end
-
-        def has_prev_page?
-          !prev_url.nil? && !prev_url.empty?
+      class PaginatedList < Bitly::API::PaginatedList
+        def item_key
+          "links"
         end
 
-        def next_page
-          has_next_page? ? get_page(uri: URI(next_url)) : nil
-        end
-
-        def prev_page
-          has_prev_page? ? get_page(uri: URI(prev_url)) : nil
-        end
-
-        private
-
-        def get_page(uri:)
-          response = @client.request(path: uri.path.gsub(/\/v4/, ""), params: CGI.parse(uri.query))
-          bitlinks = response.body["links"].map do |link|
-            Bitlink.new(data: link, client: @client)
-          end
-          self.class.new(items: bitlinks, response: response, client: @client)
+        def item_factory(data)
+          Bitlink.new(data: data, client: @client)
         end
       end
     end
   end
-end
+end

data/lib/bitly/api/bitlink.rb

@@ -184,10 +184,7 @@ module Bitly
           "encoding_login" => encoding_login
         }
         response = client.request(path: "/groups/#{group_guid}/bitlinks", params: params)
-        bitlinks = response.body["links"].map do |link|
-          new(data: link, client: client)
-        end
-        PaginatedList.new(items: bitlinks, response: response, client: client)
+        PaginatedList.new(response: response, client: client)
       end
 
       ##
@@ -361,4 +358,4 @@ module Bitly
       end
     end
   end
-end
+end

data/lib/bitly/api/client.rb

@@ -548,6 +548,18 @@ module Bitly
         BSD.list(client: self)
       end
 
+      ##
+      # Fetch a qr code by ID
+      # [`GET /v4/qr-codes/{qrcode_id}`](https://dev.bitly.com/api-reference/#getQRCodeByIdPublic)
+      # 
+      # @example
+      #    qrcode = client.qrcode(qrcode_id: "a1b2c3")
+      #    
+      # @return [Bitly::API::Qrcode]
+      def qrcode(qrcode_id:)
+        Qrcode.fetch(client: self, qrcode_id: qrcode_id)
+      end
+
       private
 
       def default_headers

data/lib/bitly/api/group.rb

@@ -165,6 +165,15 @@ module Bitly
         Bitly::API::Bitlink.list(client: @client, group_guid: guid)
       end
 
+      ##
+      # Gets the QR Codes for the group.
+      # [`GET /v4/groups/{group_guid}/qr-codes`](https://dev.bitly.com/api-reference/#listQRMinimal)
+      #
+      # @return [Bitly::API::Qrcode::List]
+      def qrcodes
+        Bitly::API::Qrcode.list_by_group(client: @client, group_guid: guid)
+      end
+
       ##
       # Gets the referring networks for the group.
       # [`GET /v4/groups/{group_guid}/referring_networks`](https://dev.bitly.com/api-reference/#GetGroupMetricsByReferringNetworks)
@@ -216,4 +225,4 @@ module Bitly
       end
     end
   end
-end
+end

data/lib/bitly/api/paginated_list.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+require "cgi"
+require "uri"
+
+module Bitly
+  module API
+    class PaginatedList < Bitly::API::List
+      attr_reader :next_url, :prev_url, :size, :page, :total
+
+      def initialize(response: , client:)
+        @client = client
+        super(items: items_from_response(response: response), response: response)
+        if response.body["pagination"]
+          pagination = response.body["pagination"]
+          @next_url = pagination["next"]
+          @prev_url = pagination["prev"]
+          @size = pagination["size"]
+          @page = pagination["page"]
+          @total = pagination["total"]
+        end
+      end
+
+      def has_next_page?
+        !next_url.nil? && !next_url.empty?
+      end
+
+      def has_prev_page?
+        !prev_url.nil? && !prev_url.empty?
+      end
+
+      def next_page
+        has_next_page? ? get_page(uri: URI(next_url)) : nil
+      end
+
+      def prev_page
+        has_prev_page? ? get_page(uri: URI(prev_url)) : nil
+      end
+
+      def item_key
+        raise NotImplementedError
+      end
+
+      def item_factory(item)
+        raise NotImplementedError
+      end
+
+      private
+
+      def get_page(uri:)
+        response = @client.request(path: uri.path.gsub(/\/v4/, ""), params: CGI.parse(uri.query))
+        self.class.new(response: response, client: @client)
+      end
+
+      def items_from_response(response:)
+        response.body[item_key].map do |item|
+          item_factory(item)
+        end
+      end
+    end
+  end
+end

data/lib/bitly/api/qrcode/paginated_list.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+require_relative "../paginated_list"
+
+module Bitly
+  module API
+    class Qrcode
+      class PaginatedList < Bitly::API::PaginatedList
+        def item_key
+          "qr_codes"
+        end
+
+        def item_factory(data)
+          Qrcode.new(data: data, client: @client)
+        end
+      end
+    end
+  end
+end

data/lib/bitly/api/qrcode/scans_summary.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+require_relative "../base"
+
+module Bitly
+  module API
+    class Qrcode
+      class ScansSummary
+        include Base
+
+        def self.fetch(client:, qrcode_id:, unit: nil, units: nil, unit_reference: nil)
+          response = client.request(
+            path: "/qr-codes/#{qrcode_id}/scans/summary",
+            params: {
+              "unit" => unit,
+              "units" => units,
+              "unit_reference" => unit_reference
+            }
+          )
+          new(data: response.body, response: response)
+        end
+
+        def self.attributes
+          [:units, :unit, :unit_reference, :total_scans]
+        end
+        attr_reader(*attributes)
+
+        def initialize(data:, response: nil)
+          assign_attributes(data)
+          @response = response
+        end
+      end
+    end
+  end
+end

data/lib/bitly/api/qrcode.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "./base"
+require_relative "./list"
+
+module Bitly
+  module API
+    class Qrcode
+      autoload :PaginatedList, File.join(File.dirname(__FILE__), "qrcode/paginated_list.rb")
+      autoload :ScansSummary, File.join(File.dirname(__FILE__), "qrcode/scans_summary.rb")
+
+      include Base
+
+      class List < Bitly::API::List ; end
+
+      def self.attributes
+        [:qrcode_id, :title, :archived, :serialized_content, :long_urls, :bitlink_id, :qr_code_type, :render_customizations]
+      end
+      def self.time_attributes
+        [:created, :updated]
+      end
+      attr_reader(*(attributes + time_attributes))
+
+      ##
+      # Retrieves a list of QR codes matching the filter settings. Values are in reverse chronological order. The pagination occurs by calling the next link in the pagination response object.
+      # [`GET /v4/groups/{group_guid}/qr-codes`](https://dev.bitly.com/api-reference/#listQRMinimal)
+      #
+      # @example
+      #     qrcodes = Bitly::API::Qrcode.list(client: client, group_guid: guid)
+      #
+      # @param client [Bitly::API::Client] An authorized API client
+      # @param group_guid [String] The group guid for which you want qr codes
+      # @param size [Integer] The number of QR Codes to return, default 50.
+      # @param archived [String] Whether or not to include archived QRCodes.
+      #     One of "on", "off" or "both". Defaults to "off".
+      # @param archived [String] a filter value if the QRCode has any render customizations (like color or shape changes).
+      #     One of "on", "off" or "both". Defaults to "both".
+      #
+      # @return [Bitly::API::Qrcode::PaginatedList]
+      def self.list_by_group(
+        client:,
+        group_guid:,
+        size: nil,
+        archived: nil,
+        has_render_customizations: nil
+      )
+        params = {
+          "size" => size,
+          "archived" => archived,
+          "has_render_customizations" => has_render_customizations
+        }
+        response = client.request(path: "/groups/#{group_guid}/qr-codes", params: params)
+        PaginatedList.new(response: response, client: client)
+      end
+
+      ##
+      # Return information about a QR Code
+      # [`GET /v4/qr-codes/{qrcode_id}`](https://dev.bitly.com/api-reference/#getQRCodeByIdPublic)
+      #
+      # @example
+      #     qrcode = Bitly::API::Qrcode.fetch(client: client, qrcode_id: "a1b2c3")
+      #
+      # @param client [Bitly::API::Client] An authorized API client
+      # @param qrcode_id [String] The qrcode id you want information about
+      #
+      # @return [Bitly::API::Qrcode]
+      def self.fetch(client:, qrcode_id:)
+        response = client.request(path: "/qr-codes/#{qrcode_id}")
+        new(data: response.body, client: client, response: response)
+      end
+
+      # [`GET /v4/qr-codes/{qrcode_id}/scans/summary`](https://dev.bitly.com/api-reference/#getScanMetricsForQRCode)
+      #
+      # @return [Bitly::API::Qrcode::ScansSummary]
+      def scans_summary(unit: nil, units: nil, unit_reference: nil)
+        ScansSummary.fetch(client: @client, qrcode_id: @qrcode_id, unit: unit, units: units, unit_reference: unit_reference)
+      end
+
+      ##
+      # Return the SVG or PNG image of a QR Code
+      # [`GET /v4/qr-codes/{qrcode_id}/image`](https://dev.bitly.com/api-reference/#getQRCodeImagePublic)
+      #
+      # @param client [Bitly::API::Client] An authorized API client
+      # @param format [String] "svg" or "png". Default "svg"
+      #
+      # @return [String]
+      def image(format: nil)
+        params = format.nil? ? {} : {format: format}
+        response = @client.request(path: "/qr-codes/#{qrcode_id}/image", params: params)
+        response.body["qr_code_image"]
+      end
+
+      def initialize(data:, client:, response: nil)
+        assign_attributes(data)
+        @client = client
+        @response = response
+      end
+
+      def bitlink
+        Bitlink.fetch(client: @client, bitlink: @bitlink_id)
+      end
+    end
+  end
+end

data/lib/bitly/api.rb

@@ -9,6 +9,7 @@ module Bitly
     autoload :Client, File.join(File.dirname(__FILE__), "api/client.rb")
     autoload :ClickMetric, File.join(File.dirname(__FILE__), "api/click_metric.rb")
     autoload :Bitlink, File.join(File.dirname(__FILE__), "api/bitlink.rb")
+    autoload :Qrcode, File.join(File.dirname(__FILE__), "api/qrcode.rb")
     autoload :Organization, File.join(File.dirname(__FILE__), "api/organization.rb")
     autoload :Group, File.join(File.dirname(__FILE__), "api/group.rb")
     autoload :User, File.join(File.dirname(__FILE__), "api/user.rb")

data/lib/bitly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitly
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bitly
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Phil Nash
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-08 00:00:00.000000000 Z
+date: 2025-02-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: oauth2
@@ -179,6 +179,10 @@ files:
 - lib/bitly/api/group/preferences.rb
 - lib/bitly/api/list.rb
 - lib/bitly/api/organization.rb
+- lib/bitly/api/paginated_list.rb
+- lib/bitly/api/qrcode.rb
+- lib/bitly/api/qrcode/paginated_list.rb
+- lib/bitly/api/qrcode/scans_summary.rb
 - lib/bitly/api/shorten_counts.rb
 - lib/bitly/api/user.rb
 - lib/bitly/error.rb
@@ -215,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Use the Bitly API to shorten or expand URLs