userplex 0.1.0

data/lib/userplex/internal.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Internal
+    extend Userplex::Internal::Util::SorbetRuntimeSupport
+
+    OMIT =
+      Object.new.tap do
+        _1.define_singleton_method(:inspect) { "#<#{Userplex::Internal}::OMIT>" }
+      end
+        .freeze
+
+    define_sorbet_constant!(:AnyHash) do
+      T.type_alias { T::Hash[Symbol, T.anything] }
+    end
+    define_sorbet_constant!(:FileInput) do
+      T.type_alias { T.any(Pathname, StringIO, IO, String, Userplex::FilePart) }
+    end
+  end
+end

data/lib/userplex/models/event_track_params.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Models
+    # @see Userplex::Resources::Events#track
+    class EventTrackParams < Userplex::Internal::Type::BaseModel
+      extend Userplex::Internal::Type::RequestParameters::Converter
+      include Userplex::Internal::Type::RequestParameters
+
+      # @!attribute event
+      #   Event name
+      #
+      #   @return [String]
+      required :event, String
+
+      # @!attribute user_id
+      #   External user ID
+      #
+      #   @return [String]
+      required :user_id, String, api_name: :userId
+
+      # @!attribute properties
+      #   Event metadata
+      #
+      #   @return [Hash{Symbol=>Object, nil}, nil]
+      optional :properties, Userplex::Internal::Type::HashOf[Userplex::Internal::Type::Unknown, nil?: true]
+
+      # @!attribute timestamp
+      #   Event timestamp (ISO 8601)
+      #
+      #   @return [Time, nil]
+      optional :timestamp, Time
+
+      # @!method initialize(event:, user_id:, properties: nil, timestamp: nil, request_options: {})
+      #   @param event [String] Event name
+      #
+      #   @param user_id [String] External user ID
+      #
+      #   @param properties [Hash{Symbol=>Object, nil}] Event metadata
+      #
+      #   @param timestamp [Time] Event timestamp (ISO 8601)
+      #
+      #   @param request_options [Userplex::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/userplex/models/event_track_response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Models
+    # @see Userplex::Resources::Events#track
+    class EventTrackResponse < Userplex::Internal::Type::BaseModel
+      # @!attribute event_id
+      #   The event ID
+      #
+      #   @return [String]
+      required :event_id, String, api_name: :eventId
+
+      # @!attribute occurrence_id
+      #   The event occurrence ID
+      #
+      #   @return [String]
+      required :occurrence_id, String, api_name: :occurrenceId
+
+      # @!attribute success
+      #   Whether the operation was successful
+      #
+      #   @return [Boolean]
+      required :success, Userplex::Internal::Type::Boolean
+
+      # @!method initialize(event_id:, occurrence_id:, success:)
+      #   @param event_id [String] The event ID
+      #
+      #   @param occurrence_id [String] The event occurrence ID
+      #
+      #   @param success [Boolean] Whether the operation was successful
+    end
+  end
+end

data/lib/userplex/models/user_identify_params.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Models
+    # @see Userplex::Resources::Users#identify
+    class UserIdentifyParams < Userplex::Internal::Type::BaseModel
+      extend Userplex::Internal::Type::RequestParameters::Converter
+      include Userplex::Internal::Type::RequestParameters
+
+      # @!attribute email
+      #   User email address
+      #
+      #   @return [String]
+      required :email, String
+
+      # @!attribute name
+      #   User full name
+      #
+      #   @return [String]
+      required :name, String
+
+      # @!attribute user_id
+      #   Unique identifier for the user
+      #
+      #   @return [String]
+      required :user_id, String, api_name: :userId
+
+      # @!attribute properties
+      #   Additional user properties
+      #
+      #   @return [Hash{Symbol=>Object, nil}, nil]
+      optional :properties, Userplex::Internal::Type::HashOf[Userplex::Internal::Type::Unknown, nil?: true]
+
+      # @!method initialize(email:, name:, user_id:, properties: nil, request_options: {})
+      #   @param email [String] User email address
+      #
+      #   @param name [String] User full name
+      #
+      #   @param user_id [String] Unique identifier for the user
+      #
+      #   @param properties [Hash{Symbol=>Object, nil}] Additional user properties
+      #
+      #   @param request_options [Userplex::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/userplex/models/user_identify_response.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Models
+    # @see Userplex::Resources::Users#identify
+    class UserIdentifyResponse < Userplex::Internal::Type::BaseModel
+      # @!attribute success
+      #   Whether the operation was successful
+      #
+      #   @return [Boolean]
+      required :success, Userplex::Internal::Type::Boolean
+
+      # @!attribute user_id
+      #   The identified user ID
+      #
+      #   @return [String]
+      required :user_id, String, api_name: :userId
+
+      # @!method initialize(success:, user_id:)
+      #   @param success [Boolean] Whether the operation was successful
+      #
+      #   @param user_id [String] The identified user ID
+    end
+  end
+end

data/lib/userplex/models.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Userplex
+  [Userplex::Internal::Type::BaseModel, *Userplex::Internal::Type::BaseModel.subclasses].each do |cls|
+    cls.define_sorbet_constant!(:OrHash) { T.type_alias { T.any(cls, Userplex::Internal::AnyHash) } }
+  end
+
+  Userplex::Internal::Util.walk_namespaces(Userplex::Models).each do |mod|
+    case mod
+    in Userplex::Internal::Type::Enum | Userplex::Internal::Type::Union
+      mod.constants.each do |name|
+        case mod.const_get(name)
+        in true | false
+          mod.define_sorbet_constant!(:TaggedBoolean) { T.type_alias { T::Boolean } }
+          mod.define_sorbet_constant!(:OrBoolean) { T.type_alias { T::Boolean } }
+        in Integer
+          mod.define_sorbet_constant!(:TaggedInteger) { T.type_alias { Integer } }
+          mod.define_sorbet_constant!(:OrInteger) { T.type_alias { Integer } }
+        in Float
+          mod.define_sorbet_constant!(:TaggedFloat) { T.type_alias { Float } }
+          mod.define_sorbet_constant!(:OrFloat) { T.type_alias { Float } }
+        in Symbol
+          mod.define_sorbet_constant!(:TaggedSymbol) { T.type_alias { Symbol } }
+          mod.define_sorbet_constant!(:OrSymbol) { T.type_alias { T.any(Symbol, String) } }
+        else
+        end
+      end
+    else
+    end
+  end
+
+  Userplex::Internal::Util.walk_namespaces(Userplex::Models)
+                          .lazy
+                          .grep(Userplex::Internal::Type::Union)
+                          .each do |mod|
+    const = :Variants
+    next if mod.sorbet_constant_defined?(const)
+
+    mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
+  end
+
+  EventTrackParams = Userplex::Models::EventTrackParams
+
+  UserIdentifyParams = Userplex::Models::UserIdentifyParams
+end

data/lib/userplex/request_options.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Userplex
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  # or override those provided at the client level.
+  #
+  # When making a request, you can pass an actual {RequestOptions} instance, or
+  # simply pass a Hash with symbol keys matching the attributes on this class.
+  class RequestOptions < Userplex::Internal::Type::BaseModel
+    # @api private
+    #
+    # @param opts [Userplex::RequestOptions, Hash{Symbol=>Object}]
+    #
+    # @raise [ArgumentError]
+    def self.validate!(opts)
+      case opts
+      in Userplex::RequestOptions | Hash
+        opts.to_h.each_key do |k|
+          unless fields.include?(k)
+            raise ArgumentError.new("Request `opts` keys must be one of #{fields.keys}, got #{k.inspect}")
+          end
+        end
+      else
+        raise ArgumentError.new("Request `opts` must be a Hash or RequestOptions, got #{opts.inspect}")
+      end
+    end
+
+    # @!attribute idempotency_key
+    #   Idempotency key to send with request and all associated retries. Will only be
+    #   sent for write requests.
+    #
+    #   @return [String, nil]
+    optional :idempotency_key, String
+
+    # @!attribute extra_query
+    #   Extra query params to send with the request. These are `.merge`’d into any
+    #   `query` given at the client level.
+    #
+    #   @return [Hash{String=>Array<String>, String, nil}, nil]
+    optional :extra_query, Userplex::Internal::Type::HashOf[Userplex::Internal::Type::ArrayOf[String]]
+
+    # @!attribute extra_headers
+    #   Extra headers to send with the request. These are `.merged`’d into any
+    #   `extra_headers` given at the client level.
+    #
+    #   @return [Hash{String=>String, nil}, nil]
+    optional :extra_headers, Userplex::Internal::Type::HashOf[String, nil?: true]
+
+    # @!attribute extra_body
+    #   Extra data to send with the request. These are deep merged into any data
+    #   generated as part of the normal request.
+    #
+    #   @return [Object, nil]
+    optional :extra_body, Userplex::Internal::Type::HashOf[Userplex::Internal::Type::Unknown]
+
+    # @!attribute max_retries
+    #   Maximum number of retries to attempt after a failed initial request.
+    #
+    #   @return [Integer, nil]
+    optional :max_retries, Integer
+
+    # @!attribute timeout
+    #   Request timeout in seconds.
+    #
+    #   @return [Float, nil]
+    optional :timeout, Float
+
+    # @!method initialize(values = {})
+    #   Returns a new instance of RequestOptions.
+    #
+    #   @param values [Hash{Symbol=>Object}]
+
+    define_sorbet_constant!(:OrHash) do
+      T.type_alias { T.any(Userplex::RequestOptions, Userplex::Internal::AnyHash) }
+    end
+  end
+end

data/lib/userplex/resources/events.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Resources
+    class Events
+      # Creates or uses an existing event and records an event occurrence for an end
+      # user. Requires a valid API key for authentication.
+      #
+      # @overload track(event:, user_id:, properties: nil, timestamp: nil, request_options: {})
+      #
+      # @param event [String] Event name
+      #
+      # @param user_id [String] External user ID
+      #
+      # @param properties [Hash{Symbol=>Object, nil}] Event metadata
+      #
+      # @param timestamp [Time] Event timestamp (ISO 8601)
+      #
+      # @param request_options [Userplex::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Userplex::Models::EventTrackResponse]
+      #
+      # @see Userplex::Models::EventTrackParams
+      def track(params)
+        parsed, options = Userplex::EventTrackParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "api/event",
+          body: parsed,
+          model: Userplex::Models::EventTrackResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Userplex::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/userplex/resources/users.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Userplex
+  module Resources
+    class Users
+      # Creates or updates an end user in InstantDB with the provided information.
+      # Requires a valid API key for authentication.
+      #
+      # @overload identify(email:, name:, user_id:, properties: nil, request_options: {})
+      #
+      # @param email [String] User email address
+      #
+      # @param name [String] User full name
+      #
+      # @param user_id [String] Unique identifier for the user
+      #
+      # @param properties [Hash{Symbol=>Object, nil}] Additional user properties
+      #
+      # @param request_options [Userplex::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Userplex::Models::UserIdentifyResponse]
+      #
+      # @see Userplex::Models::UserIdentifyParams
+      def identify(params)
+        parsed, options = Userplex::UserIdentifyParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "api/identify",
+          body: parsed,
+          model: Userplex::Models::UserIdentifyResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Userplex::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/userplex/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Userplex
+  VERSION = "0.1.0"
+end

data/lib/userplex.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Standard libraries.
+# rubocop:disable Lint/RedundantRequireStatement
+require "English"
+require "cgi"
+require "date"
+require "erb"
+require "etc"
+require "json"
+require "net/http"
+require "pathname"
+require "rbconfig"
+require "securerandom"
+require "set"
+require "stringio"
+require "time"
+require "uri"
+# rubocop:enable Lint/RedundantRequireStatement
+
+# We already ship the preferred sorbet manifests in the package itself.
+# `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
+if Object.const_defined?(:Tapioca) &&
+   caller.chain([$PROGRAM_NAME]).chain(ARGV).any?(/tapioca/) &&
+   ARGV.none?(/dsl/)
+  return
+end
+
+# Gems.
+require "connection_pool"
+
+# Package files.
+require_relative "userplex/version"
+require_relative "userplex/internal/util"
+require_relative "userplex/internal/type/converter"
+require_relative "userplex/internal/type/unknown"
+require_relative "userplex/internal/type/boolean"
+require_relative "userplex/internal/type/file_input"
+require_relative "userplex/internal/type/enum"
+require_relative "userplex/internal/type/union"
+require_relative "userplex/internal/type/array_of"
+require_relative "userplex/internal/type/hash_of"
+require_relative "userplex/internal/type/base_model"
+require_relative "userplex/internal/type/base_page"
+require_relative "userplex/internal/type/request_parameters"
+require_relative "userplex/internal"
+require_relative "userplex/request_options"
+require_relative "userplex/file_part"
+require_relative "userplex/errors"
+require_relative "userplex/internal/transport/base_client"
+require_relative "userplex/internal/transport/pooled_net_requester"
+require_relative "userplex/client"
+require_relative "userplex/models/event_track_params"
+require_relative "userplex/models/event_track_response"
+require_relative "userplex/models/user_identify_params"
+require_relative "userplex/models/user_identify_response"
+require_relative "userplex/models"
+require_relative "userplex/resources/events"
+require_relative "userplex/resources/users"

data/manifest.yaml

@@ -0,0 +1,15 @@
+dependencies:
+  - English
+  - cgi
+  - date
+  - erb
+  - etc
+  - json
+  - net/http
+  - pathname
+  - rbconfig
+  - securerandom
+  - set
+  - stringio
+  - time
+  - uri

data/rbi/userplex/client.rbi

@@ -0,0 +1,54 @@
+# typed: strong
+
+module Userplex
+  class Client < Userplex::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES = 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS = T.let(60.0, Float)
+
+    DEFAULT_INITIAL_RETRY_DELAY = T.let(0.5, Float)
+
+    DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
+
+    # Enter your API key from your project settings
+    sig { returns(String) }
+    attr_reader :api_key
+
+    sig { returns(Userplex::Resources::Users) }
+    attr_reader :users
+
+    sig { returns(Userplex::Resources::Events) }
+    attr_reader :events
+
+    # @api private
+    sig { override.returns(T::Hash[String, String]) }
+    private def auth_headers
+    end
+
+    # Creates and returns a new client for interacting with the API.
+    sig do
+      params(
+        api_key: T.nilable(String),
+        base_url: T.nilable(String),
+        max_retries: Integer,
+        timeout: Float,
+        initial_retry_delay: Float,
+        max_retry_delay: Float
+      ).returns(T.attached_class)
+    end
+    def self.new(
+      # Enter your API key from your project settings Defaults to
+      # `ENV["USERPLEX_API_KEY"]`
+      api_key: ENV["USERPLEX_API_KEY"],
+      # Override the default base URL for the API, e.g.,
+      # `"https://api.example.com/v2/"`. Defaults to `ENV["USERPLEX_BASE_URL"]`
+      base_url: ENV["USERPLEX_BASE_URL"],
+      # Max number of retries to attempt after a failed retryable request.
+      max_retries: Userplex::Client::DEFAULT_MAX_RETRIES,
+      timeout: Userplex::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: Userplex::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: Userplex::Client::DEFAULT_MAX_RETRY_DELAY
+    )
+    end
+  end
+end