attio-ruby 0.1.0

data/lib/attio/resources/note.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "../api_resource"
+
+module Attio
+  # Represents a note attached to a record in Attio
+  class Note < APIResource
+    api_operations :list, :retrieve, :create, :delete
+
+    # API endpoint path for notes
+    # @return [String] The API path
+    def self.resource_path
+      "notes"
+    end
+
+    # Read-only attributes - notes are immutable
+    attr_reader :parent_object, :parent_record_id, :title, :format,
+      :created_by_actor, :content_plaintext, :content_markdown, :tags, :metadata
+
+    # Alias for compatibility
+    alias_method :created_by, :created_by_actor
+
+    # Convenience method to get content based on format
+    def content
+      case format
+      when "plaintext"
+        content_plaintext
+      when "html", "markdown"
+        content_markdown
+      else
+        content_plaintext
+      end
+    end
+
+    def initialize(attributes = {}, opts = {})
+      super
+      normalized_attrs = normalize_attributes(attributes)
+      @parent_object = normalized_attrs[:parent_object]
+      @parent_record_id = normalized_attrs[:parent_record_id]
+      @title = normalized_attrs[:title]
+      @content_plaintext = normalized_attrs[:content_plaintext]
+      @content_markdown = normalized_attrs[:content_markdown]
+      @tags = normalized_attrs[:tags] || []
+      @metadata = normalized_attrs[:metadata] || {}
+      @format = normalized_attrs[:format] || "plaintext"
+      @created_by_actor = normalized_attrs[:created_by_actor]
+    end
+
+    # Get the parent record
+    def parent_record(**)
+      return nil unless parent_object && parent_record_id
+
+      Internal::Record.retrieve(
+        object: parent_object,
+        record_id: parent_record_id,
+        **
+      )
+    end
+
+    # Check if note is in HTML format
+    def html?
+      format == "html"
+    end
+
+    # Check if note is in plaintext format
+    def plaintext?
+      format == "plaintext"
+    end
+
+    # Get plaintext version of content
+    def to_plaintext
+      return content_plaintext if content_plaintext
+
+      # If no plaintext, try to get markdown/html content and strip HTML
+      html_content = content_markdown || content
+      return nil unless html_content
+
+      strip_html(html_content)
+    end
+
+    def resource_path
+      raise InvalidRequestError, "Cannot generate path without an ID" unless persisted?
+      note_id = id.is_a?(Hash) ? (id[:note_id] || id["note_id"]) : id
+      "#{self.class.resource_path}/#{note_id}"
+    end
+
+    # Override destroy to handle nested ID
+    def destroy(**opts)
+      raise InvalidRequestError, "Cannot destroy a note without an ID" unless persisted?
+
+      note_id = id.is_a?(Hash) ? (id[:note_id] || id["note_id"]) : id
+      self.class.delete(note_id, **opts)
+      freeze
+      true
+    end
+
+    # Notes cannot be updated
+    def save(*)
+      raise NotImplementedError, "Notes cannot be updated. Create a new note instead."
+    end
+
+    def update(*)
+      raise NotImplementedError, "Notes cannot be updated. Create a new note instead."
+    end
+
+    # Convert note to hash representation
+    # @return [Hash] Note data as a hash
+    def to_h
+      super.merge(
+        parent_object: parent_object,
+        parent_record_id: parent_record_id,
+        content: content,
+        format: format,
+        created_by_actor: created_by_actor,
+        content_plaintext: content_plaintext
+      ).compact
+    end
+
+    class << self
+      # Override retrieve to handle nested ID
+      def retrieve(id, **opts)
+        note_id = id.is_a?(Hash) ? (id[:note_id] || id["note_id"]) : id
+        validate_id!(note_id)
+        response = execute_request(:GET, "#{resource_path}/#{note_id}", {}, opts)
+        new(response["data"] || response, opts)
+      end
+
+      # Override create to handle validation and parameter mapping
+      def create(**kwargs)
+        # Extract options from kwargs
+        opts = {}
+        opts[:api_key] = kwargs.delete(:api_key) if kwargs.key?(:api_key)
+
+        # Map object/record_id to parent_object/parent_record_id
+        normalized_params = {
+          parent_object: kwargs[:object] || kwargs[:parent_object],
+          parent_record_id: kwargs[:record_id] || kwargs[:parent_record_id],
+          title: kwargs[:title] || kwargs[:content] || "Note",
+          content: kwargs[:content],
+          format: kwargs[:format]
+        }
+
+        prepared_params = prepare_params_for_create(normalized_params)
+        response = execute_request(:POST, resource_path, prepared_params, opts)
+        new(response["data"] || response, opts)
+      end
+
+      # Override create to handle validation
+      def prepare_params_for_create(params)
+        validate_parent!(params[:parent_object], params[:parent_record_id])
+        validate_content!(params[:content])
+        validate_format!(params[:format]) if params[:format]
+
+        {
+          data: {
+            title: params[:title],
+            parent_object: params[:parent_object],
+            parent_record_id: params[:parent_record_id],
+            content: params[:content],
+            format: params[:format] || "plaintext"
+          }
+        }
+      end
+
+      # Get notes for a record
+      def for_record(params = {}, object:, record_id:, **)
+        list(
+          params.merge(
+            parent_object: object,
+            parent_record_id: record_id
+          ),
+          **
+        )
+      end
+
+      private
+
+      def validate_parent!(parent_object, parent_record_id)
+        if parent_object.nil? || parent_object.to_s.empty?
+          raise ArgumentError, "parent_object is required"
+        end
+
+        if parent_record_id.nil? || parent_record_id.to_s.empty?
+          raise ArgumentError, "parent_record_id is required"
+        end
+      end
+
+      def validate_content!(content)
+        if content.nil? || content.to_s.strip.empty?
+          raise ArgumentError, "content cannot be empty"
+        end
+      end
+
+      def validate_format!(format)
+        valid_formats = %w[plaintext html]
+        unless valid_formats.include?(format.to_s)
+          raise ArgumentError, "Invalid format: #{format}. Valid formats: #{valid_formats.join(", ")}"
+        end
+      end
+    end
+
+    private
+
+    def strip_html(html)
+      return html unless html.is_a?(String)
+
+      # Basic HTML stripping (production apps should use a proper HTML parser)
+      html.gsub(/<[^>]+>/, " ")
+        .gsub(/\s+/, " ")
+        .strip
+    end
+  end
+end

data/lib/attio/resources/object.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "../api_resource"
+
+module Attio
+  # Represents an object type in Attio (e.g., People, Companies)
+  class Object < APIResource
+    api_operations :list, :retrieve, :create, :update, :delete
+
+    # API endpoint path for objects
+    # @return [String] The API path
+    def self.resource_path
+      "objects"
+    end
+
+    # Define known attributes
+    attr_reader :api_slug, :singular_noun, :plural_noun, :created_by_actor
+
+    def initialize(attributes = {}, opts = {})
+      super
+      normalized_attrs = normalize_attributes(attributes)
+      @api_slug = normalized_attrs[:api_slug]
+      @singular_noun = normalized_attrs[:singular_noun]
+      @plural_noun = normalized_attrs[:plural_noun]
+      @created_by_actor = normalized_attrs[:created_by_actor]
+    end
+
+    # Get all attributes for this object
+    def attributes(**)
+      Attribute.list(parent_object: api_slug || id, **)
+    end
+
+    # Create a new attribute for this object
+    def create_attribute(params = {}, **)
+      Attribute.create(params.merge(parent_object: api_slug || id), **)
+    end
+
+    # Get records for this object
+    def records(params = {}, **)
+      Internal::Record.list(object: api_slug || id, **params, **)
+    end
+
+    # Create a record for this object
+    def create_record(values = {}, **)
+      Internal::Record.create(object: api_slug || id, values: values, **)
+    end
+
+    # Find by API slug
+    def self.find_by_slug(slug, **opts)
+      retrieve(slug, **opts)
+    rescue NotFoundError
+      list(**opts).find { |obj| obj.api_slug == slug }
+    end
+
+    # Get standard objects
+    def self.people(**)
+      find_by_slug("people", **)
+    end
+
+    # Get the standard Companies object
+    # @return [Object] The companies object
+    def self.companies(**)
+      find_by_slug("companies", **)
+    end
+  end
+end

data/lib/attio/resources/person.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require_relative "typed_record"
+
+module Attio
+  # Represents a person record in Attio
+  # Provides convenient methods for working with people and their attributes
+  class Person < TypedRecord
+    object_type "people"
+
+    # Set the person's name using a more intuitive interface
+    # @param first [String] First name
+    # @param last [String] Last name
+    # @param middle [String] Middle name (optional)
+    # @param full [String] Full name (optional, will be generated if not provided)
+    def set_name(first: nil, last: nil, middle: nil, full: nil)
+      name_data = {}
+      name_data[:first_name] = first if first
+      name_data[:last_name] = last if last
+      name_data[:middle_name] = middle if middle
+
+      # Generate full name if not provided
+      if full
+        name_data[:full_name] = full
+      elsif first || last
+        parts = [first, middle, last].compact
+        name_data[:full_name] = parts.join(" ") unless parts.empty?
+      end
+
+      # Attio expects name as an array with a single hash
+      self[:name] = [name_data] unless name_data.empty?
+    end
+
+    # Set the person's name using a hash or string
+    # @param name_value [Hash, String] Either a hash with first/last/middle/full keys or a full name string
+    def name=(name_value)
+      case name_value
+      when Hash
+        set_name(**name_value)
+      when String
+        set_name(full: name_value)
+      else
+        raise ArgumentError, "Name must be a Hash or String"
+      end
+    end
+
+    # Get the person's full name
+    # @return [String, nil] The full name or nil if not set
+    def full_name
+      extract_name_field("full_name")
+    end
+
+    # Get the person's first name
+    # @return [String, nil] The first name or nil if not set
+    def first_name
+      extract_name_field("first_name")
+    end
+
+    # Get the person's last name
+    # @return [String, nil] The last name or nil if not set
+    def last_name
+      extract_name_field("last_name")
+    end
+
+    private
+
+    # Extract a field from the name data structure
+    # @param field [String] The field to extract
+    # @return [String, nil] The field value or nil
+    def extract_name_field(field)
+      name_value = self[:name]
+      return nil unless name_value
+
+      name_hash = normalize_to_hash(name_value)
+      name_hash[field] || name_hash[field.to_sym]
+    end
+
+    # 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?
+        first_item = value.first
+        if first_item.is_a?(Hash)
+          first_item[field] || first_item[field.to_sym]
+        else
+          first_item.to_s
+        end
+      when Hash
+        value[field] || value[field.to_sym]
+      else
+        value.to_s
+      end
+    end
+
+    # Normalize various name formats to a hash
+    # @param value [Array, Hash] The value to normalize
+    # @return [Hash] The normalized hash
+    def normalize_to_hash(value)
+      case value
+      when Array
+        value.first.is_a?(Hash) ? value.first : {}
+      when Hash
+        value
+      else
+        {}
+      end
+    end
+
+    public
+
+    # Add an email address
+    # @param email [String] The email address to add
+    def add_email(email)
+      emails = self[:email_addresses] || []
+      # Ensure it's an array
+      emails = [emails] unless emails.is_a?(Array)
+
+      # Add the email if it's not already present
+      emails << email unless emails.include?(email)
+      self[:email_addresses] = emails
+    end
+
+    # Get the primary email address
+    # @return [String, nil] The primary email or nil if not set
+    def email
+      emails = self[:email_addresses]
+      return nil unless emails
+
+      extract_primary_value(emails, "email_address")
+    end
+
+    # Add a phone number
+    # @param number [String] The phone number
+    # @param country_code [String] The country code (e.g., "US")
+    def add_phone(number, country_code: "US")
+      phones = self[:phone_numbers] || []
+      phones = [phones] unless phones.is_a?(Array)
+
+      phone_data = {
+        original_phone_number: number,
+        country_code: country_code
+      }
+
+      phones << phone_data
+      self[:phone_numbers] = phones
+    end
+
+    # Get the primary phone number
+    # @return [String, nil] The primary phone number or nil if not set
+    def phone
+      phones = self[:phone_numbers]
+      return nil unless phones
+
+      extract_primary_value(phones, "original_phone_number")
+    end
+
+    # Set the job title
+    # @param title [String] The job title
+    def job_title=(title)
+      self[:job_title] = title
+    end
+
+    # Associate with a company
+    # @param company [Company, String] A Company instance or company ID
+    def company=(company)
+      if company.is_a?(Company)
+        # Extract ID properly from company instance
+        company_id = company.id.is_a?(Hash) ? company.id["record_id"] : company.id
+        self[:company] = [{
+          target_object: "companies",
+          target_record_id: company_id
+        }]
+      elsif company.is_a?(String)
+        self[:company] = [{
+          target_object: "companies",
+          target_record_id: company
+        }]
+      elsif company.nil?
+        self[:company] = nil
+      else
+        raise ArgumentError, "Company must be a Company instance or ID string"
+      end
+    end
+
+    class << self
+      # Create a person with a simplified interface
+      # @param attributes [Hash] Person attributes
+      # @option attributes [String] :first_name First name
+      # @option attributes [String] :last_name Last name
+      # @option attributes [String] :email Email address
+      # @option attributes [String] :phone Phone number
+      # @option attributes [String] :job_title Job title
+      # @option attributes [Hash] :values Raw values hash (for advanced use)
+      def create(first_name: nil, last_name: nil, full_name: nil, email: nil, phone: nil,
+        job_title: nil, company: nil, values: {}, **opts)
+        # Build the values hash
+        values[:name] ||= []
+        if first_name || last_name || full_name
+          name_data = {}
+
+          # If only full_name is provided, try to parse it
+          if full_name && !first_name && !last_name
+            parts = full_name.split(" ")
+            if parts.length >= 2
+              name_data[:first_name] = parts.first
+              name_data[:last_name] = parts[1..].join(" ")
+            else
+              name_data[:first_name] = full_name
+            end
+            name_data[:full_name] = full_name
+          else
+            name_data[:first_name] = first_name if first_name
+            name_data[:last_name] = last_name if last_name
+            name_data[:full_name] = full_name || [first_name, last_name].compact.join(" ")
+          end
+
+          values[:name] = [name_data]
+        end
+
+        values[:email_addresses] = [email] if email && !values[:email_addresses]
+
+        if phone && !values[:phone_numbers]
+          values[:phone_numbers] = [{
+            original_phone_number: phone,
+            country_code: opts.delete(:country_code) || "US"
+          }]
+        end
+
+        values[:job_title] = job_title if job_title && !values[:job_title]
+
+        if company && !values[:company]
+          company_ref = if company.is_a?(Company)
+            company_id = company.id.is_a?(Hash) ? company.id["record_id"] : company.id
+            {
+              target_object: "companies",
+              target_record_id: company_id
+            }
+          elsif company.is_a?(String)
+            {
+              target_object: "companies",
+              target_record_id: company
+            }
+          end
+          values[:company] = [company_ref] if company_ref
+        end
+
+        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
+      def search(query, **opts)
+        # Search across name fields
+        list(**opts.merge(
+          filter: {
+            "$or": [
+              {name: {first_name: {"$contains": query}}},
+              {name: {last_name: {"$contains": query}}},
+              {name: {full_name: {"$contains": query}}}
+            ]
+          }
+        ))
+      end
+
+      # Find people by name
+      # @param name [String] Name to search for
+      def find_by_name(name, **opts)
+        results = search(name, **opts)
+        results.first
+      end
+    end
+  end
+
+  # Convenience alias
+  People = Person
+end