hanko-ruby 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73c45486ef99cb5a9cabbdfaa4fa4900eb336f5cd96f9699c0f8e5cbff32d7f1
+  data.tar.gz: 46eacc55fd29afc575bd7bb4c829ab878c84c4d73d9e811087b124bcbbede268
+SHA512:
+  metadata.gz: d929d9d4647418c5e4ff0aa947cedac5dced6b50cb26bb22c4746c0a09489cee4071a18ee748becfaea22d991a852ed9ee3a3686904968910ad1f89e1fca6f67
+  data.tar.gz: ef0ff26d1c4febd94375452e482e79b2758681bd1db83780f8ec46da11bb5a91e3d701f7d4be88450ffd8a5b0c241293ec539ceccf239f11bd27a2bb19173c3a

data/lib/hanko/api/admin/audit_logs.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for querying audit logs.
+      # Inherits list, get, create, update, delete from {BaseResource}.
+      class AuditLogs < BaseResource
+        # Initialize the audit logs resource.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @return [AuditLogs] a new AuditLogs instance
+        def initialize(connection)
+          super(connection, "/audit_logs")
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/emails.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing a user's email addresses.
+      # Inherits list, get, create, update, delete from {BaseResource}.
+      class Emails < BaseResource
+        # Initialize the emails resource scoped to a user.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @param user_base_path [String] the base path for the parent user (e.g. "/users/:id")
+        # @return [Emails] a new Emails instance
+        def initialize(connection, user_base_path)
+          super(connection, "#{user_base_path}/emails")
+          @connection = connection
+        end
+
+        # Set an email address as the primary email for the user.
+        #
+        # @param email_id [String] the unique identifier of the email to make primary
+        # @return [Resource] the updated email resource
+        def set_primary(email_id)
+          response = @connection.post("#{@base_path}/#{email_id}/set_primary")
+          parse_resource(response.body)
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/metadata.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing a user's metadata.
+      class Metadata
+        # Initialize the metadata resource scoped to a user.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @param user_base_path [String] the base path for the parent user (e.g. "/users/:id")
+        # @return [Metadata] a new Metadata instance
+        def initialize(connection, user_base_path)
+          @connection = connection
+          @base_path = "#{user_base_path}/metadata"
+        end
+
+        # Fetch the user's metadata.
+        #
+        # @return [Resource] the metadata resource
+        def get
+          response = @connection.get(@base_path)
+          Resource.new(JSON.parse(response.body))
+        end
+
+        # Update the user's metadata via PATCH.
+        #
+        # @param params [Hash] the metadata attributes to update
+        # @return [Resource] the updated metadata resource
+        def update(**params)
+          response = @connection.patch(@base_path, params)
+          Resource.new(JSON.parse(response.body))
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/passwords.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing a user's password.
+      class Passwords
+        # Initialize the passwords resource scoped to a user.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @param user_base_path [String] the base path for the parent user (e.g. "/users/:id")
+        # @return [Passwords] a new Passwords instance
+        def initialize(connection, user_base_path)
+          @connection = connection
+          @base_path = "#{user_base_path}/password"
+        end
+
+        # Create a password for the user.
+        #
+        # @param params [Hash] the password attributes
+        # @return [Resource] the created password resource
+        def create(**params)
+          response = @connection.post(@base_path, params)
+          Resource.new(JSON.parse(response.body))
+        end
+
+        # Fetch the user's password resource.
+        #
+        # @return [Resource] the password resource
+        def get
+          response = @connection.get(@base_path)
+          Resource.new(JSON.parse(response.body))
+        end
+
+        # Update the user's password.
+        #
+        # @param params [Hash] the password attributes to update
+        # @return [Resource] the updated password resource
+        def update(**params)
+          response = @connection.put(@base_path, params)
+          Resource.new(JSON.parse(response.body))
+        end
+
+        # Delete the user's password.
+        #
+        # @return [Boolean] true if deletion was successful
+        def delete
+          @connection.delete(@base_path)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/sessions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing a user's sessions.
+      # Inherits list, get, create, update, delete from {BaseResource}.
+      class Sessions < BaseResource
+        # Initialize the sessions resource scoped to a user.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @param user_base_path [String] the base path for the parent user (e.g. "/users/:id")
+        # @return [Sessions] a new Sessions instance
+        def initialize(connection, user_base_path)
+          super(connection, "#{user_base_path}/sessions")
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/users.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing users.
+      # Inherits list, get, create, update, delete from {BaseResource}.
+      class Users < BaseResource
+        # Initialize the users resource.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @return [Users] a new Users instance
+        def initialize(connection)
+          super(connection, "/users")
+          @connection = connection
+        end
+
+        # Return a user-scoped context for accessing sub-resources.
+        #
+        # @param user_id [String] the unique identifier of the user
+        # @return [UserContext] a context scoped to the given user
+        def call(user_id)
+          UserContext.new(@connection, user_id)
+        end
+
+        # Provides access to sub-resources scoped to a specific user.
+        class UserContext
+          # Initialize a user-scoped context.
+          #
+          # @param connection [Hanko::Connection] the HTTP connection to use
+          # @param user_id [String] the unique identifier of the user
+          # @return [UserContext] a new UserContext instance
+          def initialize(connection, user_id)
+            @connection = connection
+            @user_id = user_id
+            @base_path = "/users/#{user_id}"
+          end
+
+          # Access the emails sub-resource for this user.
+          #
+          # @return [Emails] the emails resource scoped to this user
+          def emails
+            Emails.new(@connection, @base_path)
+          end
+
+          # Access the passwords sub-resource for this user.
+          #
+          # @return [Passwords] the passwords resource scoped to this user
+          def passwords
+            Passwords.new(@connection, @base_path)
+          end
+
+          # Access the sessions sub-resource for this user.
+          #
+          # @return [Sessions] the sessions resource scoped to this user
+          def sessions
+            Sessions.new(@connection, @base_path)
+          end
+
+          # Access the WebAuthn credentials sub-resource for this user.
+          #
+          # @return [WebauthnCredentials] the WebAuthn credentials resource scoped to this user
+          def webauthn_credentials
+            WebauthnCredentials.new(@connection, @base_path)
+          end
+
+          # Access the metadata sub-resource for this user.
+          #
+          # @return [Metadata] the metadata resource scoped to this user
+          def metadata
+            Metadata.new(@connection, @base_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/webauthn_credentials.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing a user's WebAuthn credentials.
+      # Inherits list, get, create, update, delete from {BaseResource}.
+      class WebauthnCredentials < BaseResource
+        # Initialize the WebAuthn credentials resource scoped to a user.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @param user_base_path [String] the base path for the parent user (e.g. "/users/:id")
+        # @return [WebauthnCredentials] a new WebauthnCredentials instance
+        def initialize(connection, user_base_path)
+          super(connection, "#{user_base_path}/webauthn_credentials")
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin/webhooks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Admin
+      # Admin resource for managing webhooks.
+      # Inherits list, get, create, update, delete from {BaseResource}.
+      class Webhooks < BaseResource
+        # Initialize the webhooks resource.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @return [Webhooks] a new Webhooks instance
+        def initialize(connection)
+          super(connection, "/webhooks")
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/admin.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "admin/users"
+require_relative "admin/emails"
+require_relative "admin/passwords"
+require_relative "admin/sessions"
+require_relative "admin/webauthn_credentials"
+require_relative "admin/metadata"
+require_relative "admin/webhooks"
+require_relative "admin/audit_logs"
+
+module Hanko
+  module Api
+    # Namespace module for Hanko Admin API resource classes.
+    module Admin
+    end
+
+    # Entry point for the Hanko Admin API, providing access to admin sub-resources.
+    class AdminNamespace
+      # Initialize the admin namespace.
+      #
+      # @param connection [Hanko::Connection] the HTTP connection to use
+      # @return [AdminNamespace] a new AdminNamespace instance
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Access the users resource, optionally scoped to a specific user.
+      #
+      # @param user_id [String, nil] optional user ID to scope to a single user context
+      # @return [Admin::Users, Admin::Users::UserContext] the users resource or a user-scoped context
+      def users(user_id = nil)
+        users_resource = Admin::Users.new(@connection)
+        user_id ? users_resource.call(user_id) : users_resource
+      end
+
+      # Access the webhooks resource.
+      #
+      # @return [Admin::Webhooks] the webhooks resource
+      def webhooks
+        Admin::Webhooks.new(@connection)
+      end
+
+      # Access the audit logs resource.
+      #
+      # @return [Admin::AuditLogs] the audit logs resource
+      def audit_logs
+        Admin::AuditLogs.new(@connection)
+      end
+    end
+  end
+end

data/lib/hanko/api/base_resource.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hanko
+  module Api
+    # Base class for RESTful API resources providing standard CRUD operations.
+    # Subclasses inherit {#list}, {#get}, {#create}, {#update}, and {#delete}.
+    class BaseResource
+      # Initialize a new resource endpoint.
+      #
+      # @param connection [Hanko::Connection] the HTTP connection to use
+      # @param base_path [String] the base API path for this resource
+      # @return [BaseResource] a new BaseResource instance
+      def initialize(connection, base_path)
+        @connection = connection
+        @base_path = base_path
+      end
+
+      # List all resources, optionally filtered by query parameters.
+      #
+      # @param params [Hash] optional query parameters for filtering
+      # @return [Array<Resource>] an array of Resource objects
+      def list(params = {})
+        response = @connection.get(@base_path, params)
+        parse_array(response.body)
+      end
+
+      # Fetch a single resource by its ID.
+      #
+      # @param id [String] the unique identifier of the resource
+      # @return [Resource] the requested resource
+      def get(id)
+        response = @connection.get("#{@base_path}/#{id}")
+        parse_resource(response.body)
+      end
+
+      # Create a new resource with the given attributes.
+      #
+      # @param params [Hash] the attributes for the new resource
+      # @return [Resource] the newly created resource
+      def create(**params)
+        response = @connection.post(@base_path, params)
+        parse_resource(response.body)
+      end
+
+      # Update an existing resource by its ID.
+      #
+      # @param id [String] the unique identifier of the resource
+      # @param params [Hash] the attributes to update
+      # @return [Resource] the updated resource
+      def update(id, **params)
+        response = @connection.put("#{@base_path}/#{id}", params)
+        parse_resource(response.body)
+      end
+
+      # Delete a resource by its ID.
+      #
+      # @param id [String] the unique identifier of the resource
+      # @return [Boolean] true if deletion was successful
+      def delete(id)
+        @connection.delete("#{@base_path}/#{id}")
+        true
+      end
+
+      private
+
+      def parse_resource(body)
+        data = body.is_a?(String) ? JSON.parse(body) : body
+        Resource.new(data)
+      end
+
+      def parse_array(body)
+        data = body.is_a?(String) ? JSON.parse(body) : body
+        Resource.from_array(data)
+      end
+    end
+  end
+end

data/lib/hanko/api/public/flow.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Public
+      # Public resource for initiating authentication and profile flows.
+      class Flow
+        # Initialize the flow resource.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @return [Flow] a new Flow instance
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # Initiate a login flow.
+        #
+        # @param params [Hash] optional parameters for the login flow
+        # @return [FlowResponse] the login flow response
+        def login(**params)
+          post_flow("/login", params)
+        end
+
+        # Initiate a registration flow.
+        #
+        # @param params [Hash] optional parameters for the registration flow
+        # @return [FlowResponse] the registration flow response
+        def registration(**params)
+          post_flow("/registration", params)
+        end
+
+        # Initiate a profile management flow.
+        #
+        # @param params [Hash] optional parameters for the profile flow
+        # @return [FlowResponse] the profile flow response
+        def profile(**params)
+          post_flow("/profile", params)
+        end
+
+        private
+
+        def post_flow(path, params)
+          body = params.empty? ? {} : params
+          response = @connection.post(path, body)
+          FlowResponse.new(JSON.parse(response.body))
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/public/sessions.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Public
+      # Public resource for validating Hanko sessions.
+      class Sessions
+        # Initialize the public sessions resource.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @return [Sessions] a new Sessions instance
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # Validate the current session using cookies/headers from the connection.
+        #
+        # @return [Resource] the validated session resource
+        def validate
+          response = @connection.get("/sessions/validate")
+          Resource.new(JSON.parse(response.body))
+        end
+
+        # Validate a session by providing an explicit session token.
+        #
+        # @param session_token [String] the session token to validate
+        # @return [Resource] the validated session resource
+        def validate_token(session_token)
+          response = @connection.post("/sessions/validate", session_token: session_token)
+          Resource.new(JSON.parse(response.body))
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/public/well_known.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Hanko
+  module Api
+    module Public
+      # Public resource for accessing .well-known discovery endpoints.
+      class WellKnown
+        # Initialize the well-known resource.
+        #
+        # @param connection [Hanko::Connection] the HTTP connection to use
+        # @return [WellKnown] a new WellKnown instance
+        def initialize(connection)
+          @connection = connection
+        end
+
+        # Fetch the JSON Web Key Set (JWKS) for token verification.
+        #
+        # @return [Resource] the JWKS resource
+        def jwks
+          response = @connection.get("/.well-known/jwks.json")
+          Resource.new(JSON.parse(response.body))
+        end
+
+        # Fetch the Hanko server configuration.
+        #
+        # @return [Resource] the configuration resource
+        def config
+          response = @connection.get("/.well-known/config")
+          Resource.new(JSON.parse(response.body))
+        end
+      end
+    end
+  end
+end

data/lib/hanko/api/public.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "public/sessions"
+require_relative "public/well_known"
+require_relative "public/flow"
+
+module Hanko
+  module Api
+    # Namespace module for Hanko Public API resource classes.
+    module Public
+    end
+
+    # Entry point for the Hanko Public API, providing access to public sub-resources.
+    class PublicNamespace
+      # Initialize the public namespace.
+      #
+      # @param connection [Hanko::Connection] the HTTP connection to use
+      # @return [PublicNamespace] a new PublicNamespace instance
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Access the sessions resource for session validation.
+      #
+      # @return [Public::Sessions] the sessions resource
+      def sessions
+        Public::Sessions.new(@connection)
+      end
+
+      # Access the .well-known resource for JWKS and configuration discovery.
+      #
+      # @return [Public::WellKnown] the well-known resource
+      def well_known
+        Public::WellKnown.new(@connection)
+      end
+
+      # Access the flow resource for login, registration, and profile flows.
+      #
+      # @return [Public::Flow] the flow resource
+      def flow
+        Public::Flow.new(@connection)
+      end
+    end
+  end
+end

data/lib/hanko/client.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Hanko
+  # Main entry point for interacting with the Hanko API.
+  #
+  # A client merges any per-instance options with the global {Configuration},
+  # then exposes admin and public API namespaces.
+  #
+  # @example Create a client with inline options
+  #   client = Hanko::Client.new(api_url: "https://example.hanko.io", api_key: "key")
+  #   client.admin.users.list
+  #
+  # @example Create a client using global configuration
+  #   Hanko.configure { |c| c.api_url = "https://example.hanko.io" }
+  #   client = Hanko::Client.new
+  class Client
+    # @return [Configuration] the resolved configuration for this client
+    attr_reader :config
+
+    # Creates a new Hanko API client.
+    #
+    # Options override values from the global {Hanko.configuration}.
+    #
+    # @param options [Hash] configuration overrides
+    # @option options [String] :api_url the Hanko API base URL
+    # @option options [String] :api_key the API key for admin endpoints
+    # @option options [Integer] :timeout request timeout in seconds
+    # @option options [Integer] :open_timeout connection open timeout in seconds
+    # @option options [Integer] :retry_count number of retries on failure
+    # @option options [Array] :adapter Faraday adapter (for testing)
+    # @raise [ConfigurationError] if api_url is not set
+    def initialize(**options)
+      @adapter = options.delete(:adapter)
+      @config = build_config(options)
+      validate_config!
+      @connection = Connection.new(@config, adapter: @adapter)
+    end
+
+    # Returns the admin API namespace for managing users, emails, etc.
+    #
+    # @return [Api::AdminNamespace]
+    def admin
+      @admin ||= Api::AdminNamespace.new(@connection)
+    end
+
+    # Returns the public API namespace for flows, well-known endpoints, etc.
+    #
+    # @return [Api::PublicNamespace]
+    def public
+      @public ||= Api::PublicNamespace.new(@connection)
+    end
+
+    # Returns a human-readable representation with the API key redacted.
+    #
+    # @return [String]
+    def inspect
+      "#<#{self.class} api_url=#{config.api_url.inspect} api_key=[REDACTED]>"
+    end
+
+    private
+
+    def build_config(options)
+      base = Hanko.configuration
+      Configuration.new.tap do |c|
+        Configuration::ATTRIBUTES.each do |attr|
+          value = options.fetch(attr, base.send(attr))
+          c.send(:"#{attr}=", value)
+        end
+      end
+    end
+
+    def validate_config!
+      raise ConfigurationError, 'api_url is required' unless config.api_url
+    end
+  end
+end