attio-ruby 0.1.0 → 0.1.1

data/lib/attio/resources/deal.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require_relative "typed_record"
+
+module Attio
+  # Represents a Deal record in Attio
+  #
+  # @example Create a deal
+  #   deal = Attio::Deal.create(
+  #     name: "Enterprise Deal",
+  #     value: 50000,
+  #     stage: "In Progress"
+  #   )
+  #
+  # @example Find deals by status
+  #   open_deals = Attio::Deal.find_by(status: "open")
+  #   won_deals = Attio::Deal.find_by(status: "won")
+  #
+  # @example Find high-value deals
+  #   big_deals = Attio::Deal.find_by_value_range(min: 100000)
+  #
+  # @example Update deal status
+  #   deal.update_status("won")
+  #
+  class Deal < TypedRecord
+    object_type "deals"
+
+    class << self
+      # Create a deal with a simplified interface
+      # @param attributes [Hash] Deal attributes
+      # @option attributes [String] :name Deal name (recommended)
+      # @option attributes [Numeric] :value Deal value (recommended)
+      # @option attributes [String] :stage Deal stage (recommended) - defaults: "Lead", "In Progress", "Won 🎉", "Lost"
+      # @option attributes [String] :status Deal status (alias for stage)
+      # @option attributes [String] :owner Owner email or workspace member (recommended)
+      # @option attributes [Array<String>] :associated_people Email addresses of associated people
+      # @option attributes [Array<String>] :associated_company Domains of associated companies
+      # @option attributes [Hash] :values Raw values hash (for advanced use)
+      def create(name:, value: nil, stage: nil, status: nil, owner: nil,
+                 associated_people: nil, associated_company: nil, values: {}, **opts)
+        # Name is required and simple
+        values[:name] = name if name && !values[:name]
+        
+        # Add optional fields
+        values[:value] = value if value && !values[:value]
+        
+        # Handle stage vs status - API uses "stage" but we support both
+        if (stage || status) && !values[:stage]
+          values[:stage] = stage || status
+        end
+        
+        
+        # Handle owner - can be email address or workspace member reference
+        if owner && !values[:owner]
+          values[:owner] = owner
+        end
+        
+        # Handle associated people - convert email array to proper format
+        if associated_people && !values[:associated_people]
+          values[:associated_people] = associated_people.map do |email|
+            {
+              target_object: "people",
+              email_addresses: [
+                { email_address: email }
+              ]
+            }
+          end
+        end
+        
+        # Handle associated company - convert domain array to proper format
+        if associated_company && !values[:associated_company]
+          # associated_company can be array of domains or single domain
+          domains = associated_company.is_a?(Array) ? associated_company : [associated_company]
+          values[:associated_company] = {
+            target_object: "companies",
+            domains: domains.map { |domain| { domain: domain } }
+          }
+        end
+        
+        super(values: values, **opts)
+      end
+
+      # Find deals within a value range
+      # @param min [Numeric] Minimum value (optional)
+      # @param max [Numeric] Maximum value (optional)
+      # @return [Attio::ListObject] List of matching deals
+      def find_by_value_range(min: nil, max: nil, **opts)
+        filters = []
+        filters << {value: {"$gte": min}} if min
+        filters << {value: {"$lte": max}} if max
+        
+        filter = if filters.length == 1
+          filters.first
+        elsif filters.length > 1
+          {"$and": filters}
+        else
+          {}
+        end
+        
+        list(**opts.merge(params: {filter: filter}))
+      end
+
+      # # Find deals closing soon (requires close_date attribute)
+      # # @param days [Integer] Number of days from today
+      # # @return [Attio::ListObject] List of deals closing soon
+      # def closing_soon(days: 30, **opts)
+      #   today = Date.today
+      #   end_date = today + days
+      #   
+      #   list(**opts.merge(params: {
+      #     filter: {
+      #       "$and": [
+      #         {close_date: {"$gte": today.iso8601}},
+      #         {close_date: {"$lte": end_date.iso8601}},
+      #         {stage: {"$ne": "Won 🎉"}},
+      #         {stage: {"$ne": "Lost"}}
+      #       ]
+      #     }
+      #   }))
+      # end
+
+      # Find deals by owner
+      # @param owner_id [String] The workspace member ID
+      # @return [Attio::ListObject] List of deals owned by the member
+      def find_by_owner(owner_id, **opts)
+        list(**opts.merge(params: {
+          filter: {
+            owner: {
+              target_object: "workspace_members",
+              target_record_id: owner_id
+            }
+          }
+        }))
+      end
+      
+      private
+      
+      # Build filter for status field (maps to stage)
+      def filter_by_status(value)
+        { stage: value }
+      end
+    end
+
+    # Get the deal name
+    # @return [String, nil] The deal name
+    def name
+      self[:name]
+    end
+
+    # Get the deal value
+    # @return [Numeric, nil] The deal value
+    def value
+      self[:value]
+    end
+
+    # Get the deal stage (API uses "stage" but we provide status for compatibility)
+    # @return [String, nil] The deal stage
+    def stage
+      self[:stage]
+    end
+    
+    # Alias for stage (for compatibility)
+    # @return [String, nil] The deal stage
+    def status
+      self[:stage]
+    end
+
+    # # Get the close date (if attribute exists)
+    # # @return [String, nil] The close date
+    # def close_date
+    #   self[:close_date]
+    # end
+
+    # # Get the probability (if attribute exists)
+    # # @return [Numeric, nil] The win probability
+    # def probability
+    #   self[:probability]
+    # end
+
+    # Get the owner reference
+    # @return [Hash, nil] The owner reference
+    def owner
+      self[:owner]
+    end
+
+    # Get the company reference
+    # @return [Hash, nil] The company reference
+    def company
+      self[:company]
+    end
+
+    # Update the deal stage
+    # @param new_stage [String] The new stage
+    # @return [Attio::Deal] The updated deal
+    def update_stage(new_stage, **opts)
+      self.class.update(id, values: {stage: new_stage}, **opts)
+    end
+    
+    # Alias for update_stage (for compatibility)
+    # @param new_status [String] The new status/stage
+    # @return [Attio::Deal] The updated deal
+    def update_status(new_status, **opts)
+      update_stage(new_status, **opts)
+    end
+
+    # # Update the deal probability (if attribute exists)
+    # # @param new_probability [Numeric] The new probability (0-100)
+    # # @return [Attio::Deal] The updated deal
+    # def update_probability(new_probability, **opts)
+    #   self.class.update(id, values: {probability: new_probability}, **opts)
+    # end
+
+    # Update the deal value
+    # @param new_value [Numeric] The new value
+    # @return [Attio::Deal] The updated deal
+    def update_value(new_value, **opts)
+      self.class.update(id, values: {value: new_value}, **opts)
+    end
+
+    # Get the associated company record
+    # @return [Attio::Company, nil] The company record if associated
+    def company_record(**opts)
+      return nil unless company
+      
+      company_id = company.is_a?(Hash) ? company["target_record_id"] : company
+      Company.retrieve(company_id, **opts) if company_id
+    end
+
+    # Get the owner workspace member record
+    # @return [Attio::WorkspaceMember, nil] The owner record if assigned
+    def owner_record(**opts)
+      return nil unless owner
+      
+      owner_id = if owner.is_a?(Hash)
+        owner["referenced_actor_id"] || owner["target_record_id"]
+      else
+        owner
+      end
+      WorkspaceMember.retrieve(owner_id, **opts) if owner_id
+    end
+
+    # # Calculate expected revenue (value * probability / 100)
+    # # @return [Numeric, nil] The expected revenue
+    # def expected_revenue
+    #   return nil unless value && probability
+    #   (value * probability / 100.0).round(2)
+    # end
+
+    # Check if the deal is open
+    # @return [Boolean] True if the deal is open
+    def open?
+      return false unless stage
+      
+      stage_title = stage.is_a?(Hash) ? stage.dig("status", "title") : stage
+      stage_title && !["won 🎉", "lost"].include?(stage_title.downcase)
+    end
+
+    # Check if the deal is won
+    # @return [Boolean] True if the deal is won
+    def won?
+      return false unless stage
+      
+      stage_title = stage.is_a?(Hash) ? stage.dig("status", "title") : stage
+      stage_title && stage_title.downcase.include?("won")
+    end
+
+    # Check if the deal is lost
+    # @return [Boolean] True if the deal is lost
+    def lost?
+      return false unless stage
+      
+      stage_title = stage.is_a?(Hash) ? stage.dig("status", "title") : stage
+      stage_title && stage_title.downcase == "lost"
+    end
+
+    # # Check if the deal is overdue
+    # # @return [Boolean] True if close date has passed and deal is still open
+    # def overdue?
+    #   return false unless close_date && open?
+    #   Date.parse(close_date) < Date.today
+    # end
+  end
+
+  # Alias for Deal (plural form)
+  # @example
+  #   Attio::Deals.create(name: "New Deal", value: 10000)
+  Deals = Deal
+end

data/lib/attio/resources/meta.rb

@@ -23,47 +23,78 @@ module Attio
       alias_method :current, :identify
     end
 
-    # Define attribute accessors
-    attr_attio :workspace, :token, :actor
+    # Build workspace object from flat attributes
+    def workspace
+      return nil unless self[:workspace_id]
+      
+      {
+        id: self[:workspace_id],
+        name: self[:workspace_name],
+        slug: self[:workspace_slug],
+        logo_url: self[:workspace_logo_url]
+      }.compact
+    end
+    
+    # Build token object from flat attributes
+    def token
+      return nil unless self[:client_id]
+      
+      {
+        id: self[:client_id],
+        type: self[:token_type] || "Bearer",
+        scope: self[:scope]
+      }.compact
+    end
+    
+    # Build actor object from flat attributes
+    def actor
+      return nil unless self[:authorized_by_workspace_member_id]
+      
+      {
+        type: "workspace-member",
+        id: self[:authorized_by_workspace_member_id]
+      }
+    end
 
     # Convenience methods for workspace info
     def workspace_id
-      workspace&.dig(:id)
+      self[:workspace_id]
     end
 
     # Get the workspace name
     # @return [String, nil] The workspace name
     def workspace_name
-      workspace&.dig(:name)
+      self[:workspace_name]
     end
 
     # Get the workspace slug
     # @return [String, nil] The workspace slug
     def workspace_slug
-      workspace&.dig(:slug)
+      self[:workspace_slug]
     end
 
     # Convenience methods for token info
     def token_id
-      token&.dig(:id)
+      self[:client_id]
     end
 
     # Get the token name
-    # @return [String, nil] The token name
+    # @return [String, nil] The token name (not available in flat format)
     def token_name
-      token&.dig(:name)
+      nil
     end
 
     # Get the token type
     # @return [String, nil] The token type
     def token_type
-      token&.dig(:type)
+      self[:token_type]
     end
 
     # Get the token's OAuth scopes
     # @return [Array<String>] Array of scope strings
     def scopes
-      token&.dig(:scopes) || []
+      return [] unless self[:scope]
+      self[:scope].split(" ")
     end
 
     # Check if token has a specific scope
@@ -96,8 +127,6 @@ module Attio
       raise InvalidRequestError, "Meta information is read-only"
     end
 
-    private
-
     def to_h
       {
         workspace: workspace,
@@ -109,5 +138,7 @@ module Attio
     def inspect
       "#<#{self.class.name}:#{object_id} workspace=#{workspace_slug.inspect} token=#{token_name.inspect}>"
     end
+
+    private
   end
 end

data/lib/attio/resources/object.rb

@@ -45,11 +45,31 @@ module Attio
       Internal::Record.create(object: api_slug || id, values: values, **)
     end
 
-    # Find by API slug
+    # Find by attribute using Rails-style syntax
+    def self.find_by(**conditions)
+      # Extract any opts that aren't conditions
+      opts = {}
+      known_opts = [:api_key, :timeout, :idempotency_key]
+      known_opts.each do |opt|
+        opts[opt] = conditions.delete(opt) if conditions.key?(opt)
+      end
+      
+      # Currently only supports slug
+      if conditions.key?(:slug)
+        slug = conditions[:slug]
+        begin
+          retrieve(slug, **opts)
+        rescue NotFoundError
+          list(**opts).find { |obj| obj.api_slug == slug }
+        end
+      else
+        raise ArgumentError, "find_by only supports slug attribute for objects"
+      end
+    end
+    
+    # Find by API slug (deprecated - use find_by(slug: ...) instead)
     def self.find_by_slug(slug, **opts)
-      retrieve(slug, **opts)
-    rescue NotFoundError
-      list(**opts).find { |obj| obj.api_slug == slug }
+      find_by(slug: slug, **opts)
     end
 
     # Get standard objects

data/lib/attio/resources/person.rb

@@ -251,19 +251,6 @@ module Attio
         super(values: values, **opts)
       end
 
-      # Find people by email
-      # @param email [String] Email address to search for
-      def find_by_email(email, **opts)
-        list(**opts.merge(
-          filter: {
-            email_addresses: {
-              email_address: {
-                "$eq": email
-              }
-            }
-          }
-        )).first
-      end
 
       # Search people by query
       # @param query [String] Query to search for
@@ -280,11 +267,28 @@ module Attio
         ))
       end
 
-      # Find people by name
-      # @param name [String] Name to search for
-      def find_by_name(name, **opts)
-        results = search(name, **opts)
-        results.first
+      private
+      
+      # Build filter for email field
+      def filter_by_email(value)
+        {
+          email_addresses: {
+            email_address: {
+              "$eq": value
+            }
+          }
+        }
+      end
+      
+      # Build filter for name field (searches across first, last, and full name)
+      def filter_by_name(value)
+        {
+          "$or": [
+            {name: {first_name: {"$contains": value}}},
+            {name: {last_name: {"$contains": value}}},
+            {name: {full_name: {"$contains": value}}}
+          ]
+        }
       end
     end
   end

data/lib/attio/resources/typed_record.rb

@@ -61,12 +61,55 @@ module Attio
       end
 
       # Find by a specific attribute value
-      def find_by(attribute, value, **opts)
-        list(**opts.merge(params: {
-          filter: {
-            attribute => value
-          }
-        })).first
+      # Supports Rails-style hash syntax: find_by(name: "Test")
+      def find_by(**conditions)
+        raise ArgumentError, "find_by requires at least one condition" if conditions.empty?
+        
+        # Extract any opts that aren't conditions (like api_key)
+        opts = {}
+        known_opts = [:api_key, :timeout, :idempotency_key]
+        known_opts.each do |opt|
+          opts[opt] = conditions.delete(opt) if conditions.key?(opt)
+        end
+        
+        # Build filter from conditions
+        filters = []
+        search_query = nil
+        
+        conditions.each do |field, value|
+          # Check if there's a special filter method for this field
+          filter_method = "filter_by_#{field}"
+          if respond_to?(filter_method, true) # true = include private methods
+            result = send(filter_method, value)
+            # Check if this should be a search instead of a filter
+            if result == :use_search
+              search_query = value
+            else
+              filters << result
+            end
+          else
+            # Use the field as-is
+            filters << {field => value}
+          end
+        end
+        
+        # If we have a search query, use search instead of filter
+        if search_query
+          search(search_query, **opts).first
+        else
+          # Combine multiple filters with $and if needed
+          final_filter = if filters.length == 1
+            filters.first
+          elsif filters.length > 1
+            {"$and": filters}
+          else
+            {}
+          end
+          
+          list(**opts.merge(params: {
+            filter: final_filter
+          })).first
+        end
       end
     end
 

data/lib/attio/resources/workspace_member.rb

@@ -103,10 +103,23 @@ module Attio
       end
       alias_method :current, :me
 
-      # Find member by email
-      def find_by_email(email, **opts)
-        list(**opts).find { |member| member.email_address == email } ||
-          raise(NotFoundError, "Workspace member with email '#{email}' not found")
+      # Find member by attribute using Rails-style syntax
+      def find_by(**conditions)
+        # Extract any opts that aren't conditions
+        opts = {}
+        known_opts = [:api_key, :timeout, :idempotency_key]
+        known_opts.each do |opt|
+          opts[opt] = conditions.delete(opt) if conditions.key?(opt)
+        end
+        
+        # Currently only supports email
+        if conditions.key?(:email)
+          email = conditions[:email]
+          list(**opts).find { |member| member.email_address == email } ||
+            raise(NotFoundError, "Workspace member with email '#{email}' not found")
+        else
+          raise ArgumentError, "find_by only supports email attribute for workspace members"
+        end
       end
 
       # List active members only

data/lib/attio/version.rb

@@ -2,5 +2,5 @@
 
 module Attio
   # Current version of the Attio Ruby gem
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/attio.rb

@@ -11,6 +11,7 @@ require_relative "attio/resources/object"
 require_relative "attio/resources/typed_record"
 require_relative "attio/resources/person"
 require_relative "attio/resources/company"
+require_relative "attio/resources/deal"
 require_relative "attio/resources/attribute"
 require_relative "attio/resources/list"
 require_relative "attio/resources/webhook"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attio-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Robert Beene
@@ -335,9 +335,10 @@ files:
 - LICENSE
 - README.md
 - Rakefile
-- attio-ruby.gemspec
 - docs/CODECOV_SETUP.md
+- examples/app_specific_typed_record.md
 - examples/basic_usage.rb
+- examples/deals.rb
 - examples/oauth_flow.rb
 - examples/oauth_flow_README.md
 - examples/typed_records_example.rb
@@ -354,6 +355,7 @@ files:
 - lib/attio/resources/attribute.rb
 - lib/attio/resources/comment.rb
 - lib/attio/resources/company.rb
+- lib/attio/resources/deal.rb
 - lib/attio/resources/entry.rb
 - lib/attio/resources/list.rb
 - lib/attio/resources/meta.rb

data/attio-ruby.gemspec

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/attio/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "attio-ruby"
-  spec.version = Attio::VERSION
-  spec.authors = ["Robert Beene"]
-  spec.email = ["robert@ismly.com"]
-
-  spec.summary = "Ruby client library for the Attio API"
-  spec.description = "A comprehensive Ruby client library for the Attio CRM API with OAuth support, type safety, and extensive test coverage"
-  spec.homepage = "https://github.com/rbeene/attio_ruby"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.4.0"
-
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/rbeene/attio_ruby"
-  spec.metadata["changelog_uri"] = "https://github.com/rbeene/attio_ruby/blob/main/CHANGELOG.md"
-  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/attio-ruby"
-  spec.metadata["bug_tracker_uri"] = "https://github.com/rbeene/attio_ruby/issues"
-
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Runtime dependencies
-  spec.add_dependency "faraday", "~> 2.0"
-  spec.add_dependency "faraday-retry", "~> 2.0"
-  spec.add_dependency "ostruct", "~> 0.6"
-
-  # Development dependencies
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.12"
-  spec.add_development_dependency "webmock", "~> 3.18"
-  spec.add_development_dependency "simplecov", "~> 0.22"
-  spec.add_development_dependency "simplecov-cobertura", "~> 2.1"
-  spec.add_development_dependency "yard", "~> 0.9"
-  spec.add_development_dependency "redcarpet", "~> 3.6"
-  spec.add_development_dependency "rubocop", "~> 1.50"
-  spec.add_development_dependency "rubocop-rspec", "~> 2.20"
-  spec.add_development_dependency "rubocop-performance", "~> 1.17"
-  spec.add_development_dependency "standard", "~> 1.28"
-  spec.add_development_dependency "benchmark-ips", "~> 2.12"
-  spec.add_development_dependency "pry", "~> 0.14"
-  spec.add_development_dependency "pry-byebug", "~> 3.10"
-  spec.add_development_dependency "dotenv", "~> 2.8"
-  spec.add_development_dependency "timecop", "~> 0.9"
-  spec.add_development_dependency "bundle-audit", "~> 0.1"
-  spec.add_development_dependency "brakeman", "~> 6.0"
-  spec.metadata["rubygems_mfa_required"] = "true"
-end