spotted 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e1ad1df8e63d25d83161a691c8b44f5806e197caeaec2ab2be59fcfe20b705
-  data.tar.gz: c42b9da1fe7f6a1bcc7d5dcd9f9eaf8a86b7af6e1d8889eab6889a0080fa4863
+  metadata.gz: 53171d2924e8b65667348df43a8315b13834283411bcc57260a3dee25ed1b5bb
+  data.tar.gz: 4a987cf805446e513e6d977a00aa999f48d64ca881e7adc6f7a3ae9352169348
 SHA512:
-  metadata.gz: bbc654721de4db44e31f987e312f63413c3df4a147e9c185dc7f296c18437ad95330f76f915ef0386c0045a1b51d691b4ae5796d2ffbe1a1f2a2eaf46a13e689
-  data.tar.gz: 2a2412d27f2c20cf7b807deaf9e2a766ee46db29782f06bf8c45424895ffc89815817b6af4a91f8b15729d3749a59f8b558e0b8485962e6000679addb5ca986f
+  metadata.gz: 13b3fab4d5ead1e934399769d8556ba0521e2bebcbe5a0da61fc4cefba97ebd92801afc3d4136bc70f7efea09b7a3ac0689e41e8633968d4f983d11a7f4bc1b2
+  data.tar.gz: 0ce09546710593e818c08530438f4ab6918fd9e103ad54d3376af6362da5bb197298bdec2a931cc6868259aa49eacd08a827108d4375a5075922a1295594667e

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.11.0 (2025-11-10)
+
+Full Changelog: [v0.10.0...v0.11.0](https://github.com/cjavdev/spotted/compare/v0.10.0...v0.11.0)
+
+### Features
+
+* **api:** manual updates ([feb8221](https://github.com/cjavdev/spotted/commit/feb822194d2e961c6469ca5e36c8d0cccdb0cb5a))
+
 ## 0.10.0 (2025-11-10)
 
 Full Changelog: [v0.9.0...v0.10.0](https://github.com/cjavdev/spotted/compare/v0.9.0...v0.10.0)

data/README.md

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

data/lib/spotted/client.rb

@@ -15,12 +15,15 @@ module Spotted
     # Default max retry delay in seconds.
     DEFAULT_MAX_RETRY_DELAY = 8.0
 
-    # @return [String]
+    # @return [String, nil]
     attr_reader :client_id
 
-    # @return [String]
+    # @return [String, nil]
     attr_reader :client_secret
 
+    # @return [String, nil]
+    attr_reader :access_token
+
     # @return [Spotted::Resources::Albums]
     attr_reader :albums
 
@@ -69,6 +72,22 @@ module Spotted
     # @return [Spotted::Resources::Markets]
     attr_reader :markets
 
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def auth_headers
+      {**bearer_auth, **oauth_2_0}
+    end
+
+    # @api private
+    #
+    # @return [Hash{String=>String}]
+    private def bearer_auth
+      return {} if @access_token.nil?
+
+      {"authorization" => "Bearer #{@access_token}"}
+    end
+
     # @api private
     # @return [Spotted::Internal::OAuth2ClientCredentials]
     attr_reader :oauth_2_0_state
@@ -76,7 +95,7 @@ module Spotted
     # @api private
     #
     # @return [Hash{String=>String}]
-    private def auth_headers
+    private def oauth_2_0
       return @oauth_2_0_state.auth_headers if @oauth_2_0_state
 
       return {} unless @client_id && @client_secret
@@ -106,6 +125,8 @@ module Spotted
     #
     # @param client_secret [String, nil] Defaults to `ENV["SPOTIFY_CLIENT_SECRET"]`
     #
+    # @param access_token [String, nil] Defaults to `ENV["SPOTIFY_ACCESS_TOKEN"]`
+    #
     # @param base_url [String, nil] Override the default base URL for the API, e.g.,
     # `"https://api.example.com/v2/"`. Defaults to `ENV["SPOTTED_BASE_URL"]`
     #
@@ -119,6 +140,7 @@ module Spotted
     def initialize(
       client_id: ENV["SPOTIFY_CLIENT_ID"],
       client_secret: ENV["SPOTIFY_CLIENT_SECRET"],
+      access_token: ENV["SPOTIFY_ACCESS_TOKEN"],
       base_url: ENV["SPOTTED_BASE_URL"],
       max_retries: self.class::DEFAULT_MAX_RETRIES,
       timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
@@ -127,18 +149,9 @@ module Spotted
     )
       base_url ||= "https://api.spotify.com/v1"
 
-      if client_id.nil?
-        raise ArgumentError.new("client_id is required, and can be set via environ: \"SPOTIFY_CLIENT_ID\"")
-      end
-      if client_secret.nil?
-        # Ignore Layout/LineLength
-        # rubocop:disable Layout/LineLength
-        raise ArgumentError.new("client_secret is required, and can be set via environ: \"SPOTIFY_CLIENT_SECRET\"")
-        # rubocop:enable Layout/LineLength
-      end
-
-      @client_id = client_id.to_s
-      @client_secret = client_secret.to_s
+      @client_id = client_id&.to_s
+      @client_secret = client_secret&.to_s
+      @access_token = access_token&.to_s
 
       super(
         base_url: base_url,
@@ -165,5 +178,39 @@ 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
   end
 end

data/lib/spotted/version.rb

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

data/rbi/spotted/client.rbi

@@ -10,12 +10,15 @@ module Spotted
 
     DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
 
-    sig { returns(String) }
+    sig { returns(T.nilable(String)) }
     attr_reader :client_id
 
-    sig { returns(String) }
+    sig { returns(T.nilable(String)) }
     attr_reader :client_secret
 
+    sig { returns(T.nilable(String)) }
+    attr_reader :access_token
+
     sig { returns(Spotted::Resources::Albums) }
     attr_reader :albums
 
@@ -64,13 +67,23 @@ module Spotted
     sig { returns(Spotted::Resources::Markets) }
     attr_reader :markets
 
+    # @api private
+    sig { override.returns(T::Hash[String, String]) }
+    private def auth_headers
+    end
+
+    # @api private
+    sig { returns(T::Hash[String, String]) }
+    private def bearer_auth
+    end
+
     # @api private
     sig { returns(Spotted::Internal::OAuth2ClientCredentials) }
     attr_reader :oauth_2_0_state
 
     # @api private
-    sig { override.returns(T::Hash[String, String]) }
-    private def auth_headers
+    sig { returns(T::Hash[String, String]) }
+    private def oauth_2_0
     end
 
     # Creates and returns a new client for interacting with the API.
@@ -78,6 +91,7 @@ module Spotted
       params(
         client_id: T.nilable(String),
         client_secret: T.nilable(String),
+        access_token: T.nilable(String),
         base_url: T.nilable(String),
         max_retries: Integer,
         timeout: Float,
@@ -90,6 +104,8 @@ module Spotted
       client_id: ENV["SPOTIFY_CLIENT_ID"],
       # Defaults to `ENV["SPOTIFY_CLIENT_SECRET"]`
       client_secret: ENV["SPOTIFY_CLIENT_SECRET"],
+      # Defaults to `ENV["SPOTIFY_ACCESS_TOKEN"]`
+      access_token: ENV["SPOTIFY_ACCESS_TOKEN"],
       # Override the default base URL for the API, e.g.,
       # `"https://api.example.com/v2/"`. Defaults to `ENV["SPOTTED_BASE_URL"]`
       base_url: ENV["SPOTTED_BASE_URL"],

data/sig/spotted/client.rbs

@@ -8,9 +8,11 @@ module Spotted
 
     DEFAULT_MAX_RETRY_DELAY: Float
 
-    attr_reader client_id: String
+    attr_reader client_id: String?
 
-    attr_reader client_secret: String
+    attr_reader client_secret: String?
+
+    attr_reader access_token: String?
 
     attr_reader albums: Spotted::Resources::Albums
 
@@ -44,14 +46,19 @@ module Spotted
 
     attr_reader markets: Spotted::Resources::Markets
 
+    private def auth_headers: -> ::Hash[String, String]
+
+    private def bearer_auth: -> ::Hash[String, String]
+
     # @api private
     attr_reader oauth_2_0_state: Spotted::Internal::OAuth2ClientCredentials
 
-    private def auth_headers: -> ::Hash[String, String]
+    private def oauth_2_0: -> ::Hash[String, String]
 
     def initialize: (
       ?client_id: String?,
       ?client_secret: String?,
+      ?access_token: String?,
       ?base_url: String?,
       ?max_retries: Integer,
       ?timeout: Float,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spotted
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Spotted