attio-ruby 0.1.0

data/lib/attio/resources/attribute.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+require_relative "../api_resource"
+
+module Attio
+  # Represents a custom attribute on an Attio object
+  # Attributes define the schema for data stored on records
+  class Attribute < APIResource
+    api_operations :list, :retrieve, :create, :update
+
+    # Attribute types
+    TYPES = %w[
+      text
+      number
+      checkbox
+      date
+      timestamp
+      rating
+      currency
+      status
+      select
+      multiselect
+      email
+      phone
+      url
+      user
+      record_reference
+      location
+    ].freeze
+
+    # Type configurations
+    TYPE_CONFIGS = {
+      "text" => {supports_default: true, supports_required: true},
+      "number" => {supports_default: true, supports_required: true, supports_unique: true},
+      "checkbox" => {supports_default: true},
+      "date" => {supports_default: true, supports_required: true},
+      "timestamp" => {supports_default: true, supports_required: true},
+      "rating" => {supports_default: true, max_value: 5},
+      "currency" => {supports_default: true, supports_required: true},
+      "status" => {requires_options: true},
+      "select" => {requires_options: true, supports_default: true},
+      "multiselect" => {requires_options: true},
+      "email" => {supports_unique: true, supports_required: true},
+      "phone" => {supports_required: true},
+      "url" => {supports_required: true},
+      "user" => {supports_required: true},
+      "record_reference" => {requires_target_object: true, supports_required: true},
+      "location" => {supports_required: true}
+    }.freeze
+
+    # API endpoint path for attributes
+    # @return [String] The API path
+    def self.resource_path
+      "attributes"
+    end
+
+    # Define known attributes with proper accessors
+    attr_attio :name, :description, :is_required, :is_unique,
+      :is_default_value_enabled, :default_value, :options
+
+    # Read-only attributes
+    attr_reader :api_slug, :type, :attio_object_id, :object_api_slug,
+      :parent_object_id, :created_by_actor, :is_archived, :archived_at,
+      :title
+
+    def initialize(attributes = {}, opts = {})
+      super
+      normalized_attrs = normalize_attributes(attributes)
+      @api_slug = normalized_attrs[:api_slug]
+      @type = normalized_attrs[:type]
+      @attio_object_id = normalized_attrs[:object_id]
+      @object_api_slug = normalized_attrs[:object_api_slug]
+      @parent_object_id = normalized_attrs[:parent_object_id]
+      @created_by_actor = normalized_attrs[:created_by_actor]
+      @is_archived = normalized_attrs[:is_archived] || false
+      @archived_at = parse_timestamp(normalized_attrs[:archived_at])
+      @title = normalized_attrs[:title]
+    end
+
+    # Archive this attribute
+    def archive(**opts)
+      raise InvalidRequestError, "Cannot archive an attribute without an ID" unless persisted?
+
+      response = self.class.send(:execute_request, :POST, "#{resource_path}/archive", {}, opts)
+      update_from(response[:data] || response)
+      self
+    end
+
+    # Unarchive this attribute
+    def unarchive(**opts)
+      raise InvalidRequestError, "Cannot unarchive an attribute without an ID" unless persisted?
+
+      response = self.class.send(:execute_request, :POST, "#{resource_path}/unarchive", {}, opts)
+      update_from(response[:data] || response)
+      self
+    end
+
+    def archived?
+      @is_archived == true
+    end
+
+    def required?
+      is_required == true
+    end
+
+    def unique?
+      is_unique == true
+    end
+
+    def has_default?
+      is_default_value_enabled == true
+    end
+
+    # Convert attribute to hash representation
+    # @return [Hash] Attribute data as a hash
+    def to_h
+      super.merge(
+        api_slug: api_slug,
+        name: name,
+        description: description,
+        type: type,
+        is_required: is_required,
+        is_unique: is_unique,
+        is_default_value_enabled: is_default_value_enabled,
+        default_value: default_value,
+        options: options,
+        object_id: attio_object_id,
+        object_api_slug: object_api_slug,
+        parent_object_id: parent_object_id,
+        created_by_actor: created_by_actor,
+        is_archived: is_archived,
+        archived_at: archived_at&.iso8601
+      ).compact
+    end
+
+    def resource_path
+      raise InvalidRequestError, "Cannot generate path without an ID" unless persisted?
+      attribute_id = Util::IdExtractor.extract_for_resource(id, :attribute)
+      "#{self.class.resource_path}/#{attribute_id}"
+    end
+
+    # Override save to handle nested ID
+    def save(**)
+      raise InvalidRequestError, "Cannot save an attribute without an ID" unless persisted?
+      return self unless changed?
+
+      # Pass the full ID (including object context) to update method
+      self.class.update(id, changed_attributes, **)
+    end
+
+    class << self
+      # Override retrieve to handle object-scoped attributes
+      def retrieve(id, **opts)
+        # Extract simple ID if it's a nested hash
+        attribute_id = Util::IdExtractor.extract_for_resource(id, :attribute)
+        validate_id!(attribute_id)
+
+        # For attributes, we need the object context - check if it's in the nested ID
+        if id.is_a?(Hash) && id["object_id"]
+          object_id = id["object_id"]
+          response = execute_request(:GET, "objects/#{object_id}/attributes/#{attribute_id}", {}, opts)
+        else
+          # Fall back to regular attributes endpoint
+          response = execute_request(:GET, "#{resource_path}/#{attribute_id}", {}, opts)
+        end
+
+        new(response["data"] || response, opts)
+      end
+
+      # Override update to handle object-scoped attributes
+      def update(id, params = {}, **opts)
+        # Extract simple ID if it's a nested hash
+        attribute_id = Util::IdExtractor.extract_for_resource(id, :attribute)
+        validate_id!(attribute_id)
+
+        # For attributes, we need the object context
+        if id.is_a?(Hash) && id["object_id"]
+          object_id = id["object_id"]
+          prepared_params = prepare_params_for_update(params)
+          response = execute_request(:PATCH, "objects/#{object_id}/attributes/#{attribute_id}", prepared_params, opts)
+        else
+          # Fall back to regular attributes endpoint
+          prepared_params = prepare_params_for_update(params)
+          response = execute_request(:PATCH, "#{resource_path}/#{attribute_id}", prepared_params, opts)
+        end
+
+        new(response["data"] || response, opts)
+      end
+
+      # Override create to handle validation and object parameter
+      def prepare_params_for_create(params)
+        validate_type!(params[:type])
+        validate_type_config!(params)
+
+        # Generate api_slug from name if not provided
+        api_slug = params[:api_slug] || params[:name].downcase.gsub(/[^a-z0-9]+/, "_")
+
+        {
+          data: {
+            title: params[:name] || params[:title],
+            api_slug: api_slug,
+            type: params[:type],
+            description: params[:description],
+            is_required: params[:is_required] || false,
+            is_unique: params[:is_unique] || false,
+            is_multiselect: params[:is_multiselect] || false,
+            default_value: params[:default_value],
+            config: params[:config] || {}
+          }.compact
+        }
+      end
+
+      # Override update params preparation
+      def prepare_params_for_update(params)
+        # Only certain fields can be updated
+        updateable_fields = %i[
+          name
+          title
+          description
+          is_required
+          is_unique
+          default_value
+          options
+        ]
+
+        update_params = params.slice(*updateable_fields)
+        update_params[:options] = prepare_options(update_params[:options]) if update_params[:options]
+
+        # Wrap in data for API
+        {
+          data: update_params
+        }
+      end
+
+      # Override list to handle object-specific attributes
+      def list(params = {}, **opts)
+        if params[:object]
+          object = params.delete(:object)
+          validate_object_identifier!(object)
+
+          response = execute_request(:GET, "objects/#{object}/attributes", params, opts)
+          APIResource::ListObject.new(response, self, params.merge(object: object), opts)
+        else
+          raise ArgumentError, "Attributes must be listed for a specific object. Use Attribute.for_object(object_slug) or pass object: parameter"
+        end
+      end
+
+      # Override create to handle object-specific attributes
+      def create(params = {}, **opts)
+        object = params[:object]
+        validate_object_identifier!(object)
+
+        prepared_params = prepare_params_for_create(params)
+        response = execute_request(:POST, "objects/#{object}/attributes", prepared_params, opts)
+        new(response["data"] || response, opts)
+      end
+
+      # List attributes for a specific object
+      def for_object(object, params = {}, **)
+        list(params.merge(object: object), **)
+      end
+
+      private
+
+      def validate_object_identifier!(object)
+        raise ArgumentError, "Object identifier is required" if object.nil? || object.to_s.empty?
+      end
+
+      def validate_type!(type)
+        raise ArgumentError, "Attribute type is required" if type.nil? || type.to_s.empty?
+        unless TYPES.include?(type.to_s)
+          raise ArgumentError, "Invalid attribute type: #{type}. Valid types: #{TYPES.join(", ")}"
+        end
+      end
+
+      def validate_type_config!(params)
+        type = params[:type]
+        config = TYPE_CONFIGS[type.to_s]
+        return unless config
+
+        # Check required options
+        if config[:requires_options]
+          options = params[:options]
+          if options.nil? || (options.is_a?(Array) && options.empty?)
+            raise ArgumentError, "Attribute type '#{type}' requires options"
+          end
+        end
+
+        # Check required target object
+        if config[:requires_target_object]
+          target = params[:target_object]
+          if target.nil? || target.to_s.empty?
+            raise ArgumentError, "Attribute type '#{type}' requires target_object"
+          end
+        end
+
+        # Validate unsupported features
+        if params[:is_unique] && !config[:supports_unique]
+          raise ArgumentError, "Attribute type '#{type}' does not support unique constraint"
+        end
+
+        if params[:is_required] && !config[:supports_required]
+          raise ArgumentError, "Attribute type '#{type}' does not support required constraint"
+        end
+
+        if params[:is_default_value_enabled] && !config[:supports_default]
+          raise ArgumentError, "Attribute type '#{type}' does not support default values"
+        end
+      end
+
+      def prepare_options(options)
+        return nil unless options
+
+        case options
+        when Array
+          options.map do |opt|
+            case opt
+            when String
+              {title: opt}
+            when Hash
+              opt
+            else
+              {title: opt.to_s}
+            end
+          end
+        else
+          options
+        end
+      end
+    end
+  end
+end

data/lib/attio/resources/comment.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "../api_resource"
+
+module Attio
+  # Represents a comment in an Attio thread
+  # Comments are immutable once created
+  class Comment < APIResource
+    # Comments only support create, retrieve, and delete (no list or update)
+    api_operations :retrieve, :delete
+
+    # API endpoint path for comments
+    # @return [String] The API path
+    def self.resource_path
+      "comments"
+    end
+
+    # Custom create implementation
+    def self.create(content: nil, format: "plaintext", author: nil, thread_id: nil, created_at: nil, **opts)
+      raise ArgumentError, "Content is required" if content.nil? || content.to_s.empty?
+      raise ArgumentError, "Thread ID is required" if thread_id.nil? || thread_id.to_s.empty?
+      raise ArgumentError, "Author is required" if author.nil?
+
+      request_params = {
+        data: {
+          format: format,
+          content: content,
+          author: author,
+          thread_id: thread_id
+        }
+      }
+
+      # Only add created_at if provided
+      request_params[:data][:created_at] = created_at if created_at
+
+      response = execute_request(:POST, resource_path, request_params, opts)
+      new(response["data"] || response, opts)
+    end
+
+    # Define attribute accessors
+    attr_attio :content_plaintext, :thread_id, :author, :record, :entry, :resolved_by
+
+    # Parse resolved_at as Time
+    def resolved_at
+      value = @attributes[:resolved_at]
+      return nil if value.nil?
+
+      case value
+      when Time
+        value
+      when String
+        Time.parse(value)
+      else
+        value
+      end
+    end
+
+    # Comments are immutable
+    def immutable?
+      true
+    end
+
+    # Override save to raise error since comments are immutable
+    def save(**opts)
+      raise InvalidRequestError, "Comments are immutable and cannot be updated"
+    end
+
+    # Override destroy to use the correct comment ID
+    def destroy(**opts)
+      raise InvalidRequestError, "Cannot destroy a comment without an ID" unless persisted?
+
+      comment_id = extract_comment_id
+      self.class.send(:execute_request, :DELETE, "#{self.class.resource_path}/#{comment_id}", {}, opts)
+      @attributes.clear
+      @changed_attributes.clear
+      @id = nil
+      true
+    end
+
+    private
+
+    def extract_comment_id
+      case id
+      when Hash
+        id[:comment_id] || id["comment_id"]
+      else
+        id
+      end
+    end
+
+    def resource_path
+      comment_id = extract_comment_id
+      "#{self.class.resource_path}/#{comment_id}"
+    end
+
+    def to_h
+      {
+        id: id,
+        thread_id: thread_id,
+        content_plaintext: content_plaintext,
+        entry: entry,
+        record: record,
+        resolved_at: resolved_at&.iso8601,
+        resolved_by: resolved_by,
+        created_at: created_at&.iso8601,
+        author: author
+      }.compact
+    end
+
+    def inspect
+      "#<#{self.class.name}:#{object_id} id=#{id.inspect} thread=#{thread_id} content=#{content_plaintext&.truncate(30).inspect}>"
+    end
+  end
+end

data/lib/attio/resources/company.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require_relative "typed_record"
+
+module Attio
+  # Represents a company record in Attio
+  # Provides convenient methods for working with companies and their attributes
+  class Company < TypedRecord
+    object_type "companies"
+
+    # Set the company name (much simpler than person names!)
+    # @param name [String] The company name
+    def name=(name)
+      self[:name] = name
+    end
+
+    # Get the company name
+    # @return [String, nil] The company name or nil if not set
+    def name
+      self[:name]
+    end
+
+    # Add a domain
+    # @param domain [String] The domain to add (e.g., "example.com")
+    def add_domain(domain)
+      domains = self[:domains] || []
+      # Ensure it's an array
+      domains = [domains] unless domains.is_a?(Array)
+
+      # Normalize domain (remove protocol if present)
+      domain = domain.sub(/^https?:\/\//, "")
+
+      # Check if domain already exists
+      exists = domains.any? { |d|
+        d.is_a?(Hash) ? (d["domain"] == domain || d[:domain] == domain) : d == domain
+      }
+
+      unless exists
+        # Extract just the domain strings if we have hashes
+        domain_strings = domains.filter_map { |d|
+          d.is_a?(Hash) ? (d["domain"] || d[:domain]) : d
+        }
+
+        # Add the new domain
+        domain_strings << domain
+
+        # Set as simple array of strings
+        self[:domains] = domain_strings
+      end
+    end
+
+    # Get the primary domain
+    # @return [String, nil] The primary domain or nil if not set
+    def domain
+      domains = self[:domains]
+      return nil unless domains
+
+      extract_primary_value(domains, "domain")
+    end
+
+    # Get all domains
+    # @return [Array<String>] Array of domain strings
+    def domains_list
+      domains = self[:domains]
+      return [] unless domains
+
+      case domains
+      when Array
+        domains.filter_map { |d| extract_field_value(d, "domain") }
+      else
+        [domain].compact
+      end
+    end
+
+    private
+
+    # Extract primary value from various data structures
+    # @param value [Array, Hash, Object] The value to extract from
+    # @param field [String] The field name for hash extraction
+    # @return [String, nil] The extracted value
+    def extract_primary_value(value, field)
+      case value
+      when Array
+        return nil if value.empty?
+        extract_field_value(value.first, field)
+      when Hash
+        value[field] || value[field.to_sym]
+      else
+        value.to_s
+      end
+    end
+
+    # Extract a value from a hash or convert to string
+    # @param item [Hash, Object] The item to extract from
+    # @param field [String] The field name for hash extraction
+    # @return [String] The extracted value
+    def extract_field_value(item, field)
+      case item
+      when Hash
+        item[field] || item[field.to_sym]
+      else
+        item.to_s
+      end
+    end
+
+    public
+
+    # Set the company description
+    # @param description [String] The company description
+    def description=(desc)
+      self[:description] = desc
+    end
+
+    # Set the employee count
+    # @param count [Integer, String] The employee count or range (e.g., "10-50")
+    def employee_count=(count)
+      self[:employee_count] = count.to_s
+    end
+
+    # Add a team member (person) to this company
+    # @param person [Person, String] A Person instance or person ID
+    def add_team_member(person)
+      # This would typically be done from the Person side
+      # but we can provide a convenience method
+      if person.is_a?(Person)
+        person.company = self
+        person.save
+      elsif person.is_a?(String)
+        # If it's an ID, we need to fetch and update the person
+        retrieved_person = Person.retrieve(person)
+        retrieved_person.company = self
+        retrieved_person.save
+      else
+        raise ArgumentError, "Team member must be a Person instance or ID string"
+      end
+    end
+
+    # Get all people associated with this company
+    # @return [Attio::ListObject] List of people
+    def team_members(**opts)
+      company_id = id.is_a?(Hash) ? id["record_id"] : id
+      Person.list(**opts.merge(params: {
+        filter: {
+          company: {"$references": company_id}
+        }
+      }))
+    end
+
+    class << self
+      # Create a company with a simplified interface
+      # @param attributes [Hash] Company attributes
+      # @option attributes [String] :name Company name (required)
+      # @option attributes [String, Array<String>] :domain Domain(s)
+      # @option attributes [String] :description Company description
+      # @option attributes [String, Integer] :employee_count Employee count
+      # @option attributes [Hash] :values Raw values hash (for advanced use)
+      def create(name:, domain: nil, domains: nil, description: nil,
+        employee_count: nil, values: {}, **opts)
+        # Name is required and simple for companies
+        values[:name] = name
+
+        # Handle domains
+        if domain || domains
+          domain_list = []
+          domain_list << domain if domain
+          domain_list += Array(domains) if domains
+          values[:domains] = domain_list.uniq unless domain_list.empty?
+        end
+
+        values[:description] = description if description
+        values[:employee_count] = employee_count.to_s if employee_count
+
+        super(values: values, **opts)
+      end
+
+      # Find a company by domain
+      # @param domain [String] Domain to search for
+      def find_by_domain(domain, **opts)
+        # Normalize domain
+        domain = domain.sub(/^https?:\/\//, "")
+
+        list(**opts.merge(
+          filter: {
+            domains: {
+              domain: {
+                "$eq": domain
+              }
+            }
+          }
+        )).first
+      end
+
+      # Find companies by name
+      # @param name [String] Name to search for
+      def find_by_name(name, **opts)
+        results = search(name, **opts)
+        results.first
+      end
+
+      # Find companies by employee count range
+      # @param min [Integer] Minimum employee count
+      # @param max [Integer] Maximum employee count (optional)
+      def find_by_size(min, max = nil, **opts)
+        filter = if max
+          {
+            employee_count: {
+              "$gte": min.to_s,
+              "$lte": max.to_s
+            }
+          }
+        else
+          {
+            employee_count: {"$gte": min.to_s}
+          }
+        end
+
+        list(**opts.merge(params: {filter: filter}))
+      end
+    end
+  end
+
+  # Convenience alias
+  Companies = Company
+end