spotted 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b3243cac7dcf0803cbd0bff07b62b0394ac29dfd62c143bc7c1334157f7f9a9
-  data.tar.gz: b59e7369c5fe8604894b0995a0dbdd2ff26d7392d04ca8373ab6b4c1d73e6a4c
+  metadata.gz: 77ec607b5d1456b68fe75d3699286c08d9f73f2962027830cb54fd562f359178
+  data.tar.gz: f4e4925f3af823d98bb5b038d9ed96c508c50f5d4d2aa4439189e586a645404e
 SHA512:
-  metadata.gz: bf009a7418ffbe4bbcbc04eb49c2fc60916b0d0d45013e134673a146852b79d77aad84e79e9a500c8383e3d6ccae1cd5f0ff35a650d39573871854067c07ff18
-  data.tar.gz: 38c5fe4312c8b96e2125aa365064f18580fd144874c0c19b7114d8cea47b1cde3ed501046c963042f89bdd627a6c423646b9b2a4fc879857cfa380fc8160107f
+  metadata.gz: 8016c1af387c5bb1f1318e2170ad24e8454d0dc593d877a314b05630c90ec643cb101c1738be367b2d9a16e4d8ddbcea9a6e10c0f8224ecf1187ecedf623e18a
+  data.tar.gz: 8d8419e329253cebec841027302fd74b784313cb16267a3041e0dfa9afc5997453488b1a250bc6fa37a900a5279d36c57905b7e6ab92dcfaf639705f296ccc12

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.34.0 (2026-01-16)
+
+Full Changelog: [v0.33.0...v0.34.0](https://github.com/cjavdev/spotted/compare/v0.33.0...v0.34.0)
+
+### Features
+
+* **oauth:** Adds OAuth helpers for getting new tokens ([1e4d698](https://github.com/cjavdev/spotted/commit/1e4d69811f02209449eba6bdbcbfcfaaba9530f4))
+
+
+### Chores
+
+* lint ([43c32bd](https://github.com/cjavdev/spotted/commit/43c32bd89d548732e0c35ceefa0f13769d0781cb))
+* types for auth ([5d5c7d1](https://github.com/cjavdev/spotted/commit/5d5c7d1495ab21f0f1aeb14185935a28f77e6deb))
+
 ## 0.33.0 (2026-01-15)
 
 Full Changelog: [v0.32.0...v0.33.0](https://github.com/cjavdev/spotted/compare/v0.32.0...v0.33.0)

data/README.md

@@ -26,7 +26,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "spotted", "~> 0.33.0"
+gem "spotted", "~> 0.34.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/spotted/auth.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Spotted
+  # Handles OAuth 2.0 authorization flows for Spotify API
+  class Auth
+    AUTHORIZE_URL = "https://accounts.spotify.com/authorize"
+    TOKEN_URL = "https://accounts.spotify.com/api/token"
+
+    # @return [String]
+    attr_reader :client_id
+
+    # @return [String]
+    attr_reader :client_secret
+
+    # Creates a new Auth instance for handling OAuth flows
+    #
+    # @param client_id [String] The Spotify application client ID
+    # @param client_secret [String] The Spotify application client secret
+    #
+    # @raise [ArgumentError] if client_id or client_secret is missing
+    def initialize(client_id:, client_secret:)
+      if client_id.nil? || client_id.empty?
+        raise ArgumentError, "client_id is required"
+      end
+
+      if client_secret.nil? || client_secret.empty?
+        raise ArgumentError, "client_secret is required"
+      end
+
+      @client_id = client_id
+      @client_secret = client_secret
+    end
+
+    # Generates the Spotify authorization URL for OAuth2 authorization code flow
+    #
+    # @param redirect_uri [String] The URI to redirect to after authorization
+    # @param scope [String, Array<String>, nil] Space-delimited string or array of authorization scopes
+    # @param state [String, nil] Optional state parameter for CSRF protection
+    # @param show_dialog [Boolean] Whether to force the user to approve the app again
+    #
+    # @return [String] The authorization URL to redirect the user to
+    #
+    # @example Basic usage
+    #   auth = Spotted::Auth.new(client_id: "...", client_secret: "...")
+    #   url = auth.authorization_url(redirect_uri: "http://localhost:3000/callback")
+    #
+    # @example With scopes and state
+    #   url = auth.authorization_url(
+    #     redirect_uri: "http://localhost:3000/callback",
+    #     scope: ["user-read-private", "user-read-email"],
+    #     state: "random_state_string"
+    #   )
+    def authorization_url(redirect_uri:, scope: nil, state: nil, show_dialog: false)
+      params = {
+        client_id: @client_id,
+        response_type: "code",
+        redirect_uri: redirect_uri
+      }
+
+      params[:scope] = scope.is_a?(Array) ? scope.join(" ") : scope if scope
+      params[:state] = state if state
+      params[:show_dialog] = "true" if show_dialog
+
+      query_string = URI.encode_www_form(params)
+      "#{AUTHORIZE_URL}?#{query_string}"
+    end
+
+    # Exchanges an authorization code for an access token
+    #
+    # @param code [String] The authorization code received from the authorization callback
+    # @param redirect_uri [String] The redirect URI used in the authorization request (must match exactly)
+    #
+    # @return [Hash] Token response containing:
+    #   - access_token [String] The access token to use for API requests
+    #   - token_type [String] The type of token (usually "Bearer")
+    #   - expires_in [Integer] Number of seconds until the token expires
+    #   - refresh_token [String] Token to use to refresh the access token
+    #   - scope [String] Space-delimited list of granted scopes
+    #
+    # @raise [Spotted::APIError] if the token exchange fails
+    #
+    # @example
+    #   auth = Spotted::Auth.new(client_id: "...", client_secret: "...")
+    #   credentials = auth.exchange_authorization_code(
+    #     code: params[:code],
+    #     redirect_uri: "http://localhost:3000/callback"
+    #   )
+    #   access_token = credentials[:access_token]
+    def exchange_authorization_code(code:, redirect_uri:)
+      body = URI.encode_www_form(
+        grant_type: "authorization_code",
+        code: code,
+        redirect_uri: redirect_uri
+      )
+
+      make_token_request(body: body)
+    end
+
+    # Refreshes an access token using a refresh token
+    #
+    # @param refresh_token [String] The refresh token received from a previous authorization
+    #
+    # @return [Hash] Token response containing:
+    #   - access_token [String] The new access token to use for API requests
+    #   - token_type [String] The type of token (usually "Bearer")
+    #   - expires_in [Integer] Number of seconds until the token expires
+    #   - scope [String] Space-delimited list of granted scopes
+    #
+    # @raise [Spotted::APIError] if the token refresh fails
+    #
+    # @example
+    #   auth = Spotted::Auth.new(client_id: "...", client_secret: "...")
+    #   credentials = auth.refresh_access_token(refresh_token: stored_refresh_token)
+    #   new_access_token = credentials[:access_token]
+    def refresh_access_token(refresh_token:)
+      body = URI.encode_www_form(
+        grant_type: "refresh_token",
+        refresh_token: refresh_token
+      )
+
+      make_token_request(body: body)
+    end
+
+    private
+
+    # Makes a request to the token endpoint
+    #
+    # @param body [String] The URL-encoded form body
+    # @return [Hash] The parsed JSON response
+    # @raise [Spotted::APIError] if the request fails
+    def make_token_request(body:)
+      uri = URI(TOKEN_URL)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      # Configure SSL to use system certificates
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.cert_store = OpenSSL::X509::Store.new
+      http.cert_store.set_default_paths
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/x-www-form-urlencoded"
+      request["Authorization"] = "Basic #{Base64.strict_encode64("#{@client_id}:#{@client_secret}")}"
+      request.body = body
+
+      response = http.request(request)
+
+      parse_token_response(response)
+    end
+
+    # Parses the token response and handles errors
+    #
+    # @param response [Net::HTTPResponse] The HTTP response from the token endpoint
+    # @return [Hash] The parsed token data with symbolized keys
+    # @raise [Spotted::APIError] if the response indicates an error
+    def parse_token_response(response)
+      body = JSON.parse(response.body)
+
+      case response
+      when Net::HTTPSuccess
+        # Convert string keys to symbols for easier access
+        body.transform_keys(&:to_sym)
+      else
+        error_message = body["error_description"] || body["error"] || "Token request failed"
+        raise Spotted::Errors::APIError.new(
+          url: uri,
+          status: response.code.to_i,
+          body: body,
+          message: error_message
+        )
+      end
+    end
+  end
+end

data/lib/spotted/client.rb

@@ -130,90 +130,5 @@ module Spotted
       @recommendations = Spotted::Resources::Recommendations.new(client: self)
       @markets = Spotted::Resources::Markets.new(client: self)
     end
-
-    # Generates the Spotify authorization URL for OAuth2 authorization code flow.
-    #
-    # @param redirect_uri [String] The URI to redirect to after authorization
-    # @param scope [String, Array<String>, nil] Space-delimited string or array of authorization scopes
-    # @param state [String, nil] Optional state parameter for CSRF protection
-    # @param show_dialog [Boolean] Whether to force the user to approve the app again
-    #
-    # @return [String] The authorization URL to redirect the user to
-    #
-    # @example Basic usage
-    #   client = Spotted::Client.new(client_id: "...", client_secret: "...")
-    #   url = client.authorization_url(redirect_uri: "http://localhost:3000/callback")
-    #
-    # @example With scopes and state
-    #   url = client.authorization_url(
-    #     redirect_uri: "http://localhost:3000/callback",
-    #     scope: ["user-read-private", "user-read-email"],
-    #     state: "random_state_string"
-    #   )
-    def authorization_url(redirect_uri:, scope: nil, state: nil, show_dialog: false)
-      params = {
-        client_id: @client_id,
-        response_type: "code",
-        redirect_uri: redirect_uri
-      }
-
-      params[:scope] = scope.is_a?(Array) ? scope.join(" ") : scope if scope
-      params[:state] = state if state
-      params[:show_dialog] = "true" if show_dialog
-
-      query_string = URI.encode_www_form(params)
-      "https://accounts.spotify.com/authorize?#{query_string}"
-    end
-
-    # Exchanges an authorization code for an access token.
-    #
-    # @param code [String] The authorization code to exchange
-    # @param redirect_uri [String] The redirect URI used to obtain the authorization code
-    #
-    # @return [Object] The access token and refresh token
-    def exchange_authorization_code(code:, redirect_uri:)
-      if @client_id.nil? || @client_secret.nil?
-        raise ArgumentError, "Both client_id and client_secret must be set to exchange an authorization code."
-      end
-      body = URI.encode_www_form(
-        grant_type: "authorization_code",
-        code: code,
-        redirect_uri: redirect_uri
-      )
-      client = Spotted::Client.new(
-        client_id: @client_id,
-        client_secret: @client_secret,
-        base_url: "https://accounts.spotify.com"
-      )
-      client.request(
-        method: :post,
-        headers: {
-          "Content-Type" => "application/x-www-form-urlencoded",
-          "Authorization" => "Basic #{Base64.strict_encode64("#{@client_id}:#{@client_secret}")}"
-        },
-        path: "/api/token",
-        body: body
-      )
-    end
-
-    def refresh_access_token(refresh_token:)
-      if @client_id.nil? || @client_secret.nil?
-        raise ArgumentError, "Both client_id and client_secret must be set to refresh an access token."
-      end
-      body = URI.encode_www_form(
-        grant_type: "refresh_token",
-        refresh_token: refresh_token
-      )
-      client = Spotted::Client.new(client_id: @client_id, client_secret: @client_secret, base_url: "https://accounts.spotify.com")
-      client.request(
-        method: :post,
-        headers: {
-          "Content-Type" => "application/x-www-form-urlencoded",
-          "Authorization" => "Basic #{Base64.strict_encode64("#{@client_id}:#{@client_secret}")}"
-        },
-        path: "/api/token",
-        body: body
-      )
-    end
   end
 end

data/lib/spotted/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spotted
-  VERSION = "0.33.0"
+  VERSION = "0.34.0"
 end

data/lib/spotted.rb

@@ -49,6 +49,7 @@ require_relative "spotted/internal"
 require_relative "spotted/request_options"
 require_relative "spotted/file_part"
 require_relative "spotted/errors"
+require_relative "spotted/auth"
 require_relative "spotted/internal/transport/base_client"
 require_relative "spotted/internal/transport/pooled_net_requester"
 require_relative "spotted/client"

data/rbi/spotted/auth.rbi

@@ -0,0 +1,42 @@
+# typed: strong
+
+module Spotted
+  class Auth
+    AUTHORIZE_URL = T.let("https://accounts.spotify.com/authorize", String)
+    TOKEN_URL = T.let("https://accounts.spotify.com/api/token", String)
+
+    sig { returns(String) }
+    attr_reader :client_id
+
+    sig { returns(String) }
+    attr_reader :client_secret
+
+    sig { params(client_id: String, client_secret: String).void }
+    def initialize(client_id:, client_secret:); end
+
+    sig do
+      params(
+        redirect_uri: String,
+        scope: T.nilable(T.any(String, T::Array[String])),
+        state: T.nilable(String),
+        show_dialog: T::Boolean
+      ).returns(String)
+    end
+    def authorization_url(redirect_uri:, scope: nil, state: nil, show_dialog: false); end
+
+    sig do
+      params(
+        code: String,
+        redirect_uri: String
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def exchange_authorization_code(code:, redirect_uri:); end
+
+    sig do
+      params(
+        refresh_token: String
+      ).returns(T::Hash[Symbol, T.untyped])
+    end
+    def refresh_access_token(refresh_token:); end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spotted
 version: !ruby/object:Gem::Version
-  version: 0.33.0
+  version: 0.34.0
 platform: ruby
 authors:
 - Spotted
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-15 00:00:00.000000000 Z
+date: 2026-01-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -50,6 +50,7 @@ files:
 - README.md
 - SECURITY.md
 - lib/spotted.rb
+- lib/spotted/auth.rb
 - lib/spotted/client.rb
 - lib/spotted/errors.rb
 - lib/spotted/file_part.rb
@@ -275,6 +276,7 @@ files:
 - lib/spotted/resources/users/playlists.rb
 - lib/spotted/version.rb
 - manifest.yaml
+- rbi/spotted/auth.rbi
 - rbi/spotted/client.rbi
 - rbi/spotted/errors.rbi
 - rbi/spotted/file_part.rbi