attio 0.4.0 → 0.5.0

data/lib/attio/resources/attributes.rb

@@ -9,6 +9,20 @@ module Attio
     #
     # @example Listing attributes
     #   client.attributes.list(object: "people")
+    #
+    # @example Creating a custom attribute
+    #   client.attributes.create(
+    #     object: "deals",
+    #     data: {
+    #       title: "Deal Stage",
+    #       api_slug: "deal_stage",
+    #       type: "select",
+    #       options: [
+    #         { title: "Lead", value: "lead" },
+    #         { title: "Qualified", value: "qualified" }
+    #       ]
+    #     }
+    #   )
     class Attributes < Base
       def list(object:, **params)
         validate_object!(object)
@@ -21,6 +35,228 @@ module Attio
         request(:get, "objects/#{object}/attributes/#{id_or_slug}")
       end
 
+      # Create a custom attribute for an object
+      #
+      # @param object [String] The object type or slug
+      # @param data [Hash] The attribute configuration
+      # @option data [String] :title The display title of the attribute
+      # @option data [String] :api_slug The API slug for the attribute
+      # @option data [String] :type The attribute type (text, number, select, date, etc.)
+      # @option data [String] :description Optional description
+      # @option data [Boolean] :is_required Whether the attribute is required
+      # @option data [Boolean] :is_unique Whether the attribute must be unique
+      # @option data [Boolean] :is_multiselect For select types, whether multiple values are allowed
+      # @option data [Array<Hash>] :options For select types, the available options
+      # @return [Hash] The created attribute
+      # @example Create a select attribute
+      #   client.attributes.create(
+      #     object: "trips",
+      #     data: {
+      #       title: "Status",
+      #       api_slug: "status",
+      #       type: "select",
+      #       options: [
+      #         { title: "Pending", value: "pending" },
+      #         { title: "Active", value: "active" }
+      #       ]
+      #     }
+      #   )
+      def create(object:, data:)
+        validate_object!(object)
+        validate_required_hash!(data, "Attribute data")
+
+        # Wrap data in the expected format
+        payload = { data: data }
+
+        request(:post, "objects/#{object}/attributes", payload)
+      end
+
+      # Update an existing attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param data [Hash] The attribute configuration updates
+      # @option data [String] :title The display title of the attribute
+      # @option data [String] :api_slug The API slug for the attribute
+      # @option data [String] :description Optional description
+      # @option data [Boolean] :is_required Whether the attribute is required
+      # @option data [Boolean] :is_unique Whether the attribute must be unique
+      # @option data [Boolean] :is_multiselect For select types, whether multiple values are allowed
+      # @return [Hash] The updated attribute
+      # @example Update an attribute's title
+      #   client.attributes.update(
+      #     object: "contacts",
+      #     id_or_slug: "status",
+      #     data: {
+      #       title: "Contact Status",
+      #       description: "The current status of the contact"
+      #     }
+      #   )
+      def update(object:, id_or_slug:, data:)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        validate_required_hash!(data, "Attribute data")
+
+        # Wrap data in the expected format
+        payload = { data: data }
+
+        request(:patch, "objects/#{object}/attributes/#{id_or_slug}", payload)
+      end
+
+      # List options for a select attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param params [Hash] Additional query parameters
+      # @option params [Integer] :limit Number of results to return
+      # @option params [Integer] :offset Number of results to skip
+      # @return [Hash] The list of attribute options
+      # @example List options for a select attribute
+      #   client.attributes.list_options(
+      #     object: "deals",
+      #     id_or_slug: "deal_stage"
+      #   )
+      def list_options(object:, id_or_slug:, **params)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        request(:get, "objects/#{object}/attributes/#{id_or_slug}/options", params)
+      end
+
+      # Create a new option for a select attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param data [Hash] The option configuration
+      # @option data [String] :title The display title of the option
+      # @option data [String] :value The value of the option
+      # @option data [String] :color Optional color for the option
+      # @option data [Integer] :order Optional order for the option
+      # @return [Hash] The created option
+      # @example Create a new option
+      #   client.attributes.create_option(
+      #     object: "deals",
+      #     id_or_slug: "deal_stage",
+      #     data: {
+      #       title: "Negotiation",
+      #       value: "negotiation",
+      #       color: "blue"
+      #     }
+      #   )
+      def create_option(object:, id_or_slug:, data:)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        validate_required_hash!(data, "Option data")
+
+        request(:post, "objects/#{object}/attributes/#{id_or_slug}/options", data)
+      end
+
+      # Update an option for a select attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param option [String] The option ID or value
+      # @param data [Hash] The option configuration updates
+      # @option data [String] :title The display title of the option
+      # @option data [String] :value The value of the option
+      # @option data [String] :color Optional color for the option
+      # @option data [Integer] :order Optional order for the option
+      # @return [Hash] The updated option
+      # @example Update an option's title
+      #   client.attributes.update_option(
+      #     object: "deals",
+      #     id_or_slug: "deal_stage",
+      #     option: "negotiation",
+      #     data: {
+      #       title: "In Negotiation",
+      #       color: "orange"
+      #     }
+      #   )
+      def update_option(object:, id_or_slug:, option:, data:)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        validate_option_id!(option)
+        validate_required_hash!(data, "Option data")
+
+        request(:patch, "objects/#{object}/attributes/#{id_or_slug}/options/#{option}", data)
+      end
+
+      # List statuses for a status attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param params [Hash] Additional query parameters
+      # @option params [Integer] :limit Number of results to return
+      # @option params [Integer] :offset Number of results to skip
+      # @return [Hash] The list of attribute statuses
+      # @example List statuses for a status attribute
+      #   client.attributes.list_statuses(
+      #     object: "deals",
+      #     id_or_slug: "deal_status"
+      #   )
+      def list_statuses(object:, id_or_slug:, **params)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        request(:get, "objects/#{object}/attributes/#{id_or_slug}/statuses", params)
+      end
+
+      # Create a new status for a status attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param data [Hash] The status configuration
+      # @option data [String] :title The display title of the status
+      # @option data [String] :value The value of the status
+      # @option data [String] :color Optional color for the status
+      # @option data [Integer] :order Optional order for the status
+      # @return [Hash] The created status
+      # @example Create a new status
+      #   client.attributes.create_status(
+      #     object: "deals",
+      #     id_or_slug: "deal_status",
+      #     data: {
+      #       title: "Under Review",
+      #       value: "under_review",
+      #       color: "yellow"
+      #     }
+      #   )
+      def create_status(object:, id_or_slug:, data:)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        validate_required_hash!(data, "Status data")
+
+        request(:post, "objects/#{object}/attributes/#{id_or_slug}/statuses", data)
+      end
+
+      # Update a status for a status attribute
+      #
+      # @param object [String] The object type or slug
+      # @param id_or_slug [String] The attribute ID or API slug
+      # @param status [String] The status ID or value
+      # @param data [Hash] The status configuration updates
+      # @option data [String] :title The display title of the status
+      # @option data [String] :value The value of the status
+      # @option data [String] :color Optional color for the status
+      # @option data [Integer] :order Optional order for the status
+      # @return [Hash] The updated status
+      # @example Update a status's title
+      #   client.attributes.update_status(
+      #     object: "deals",
+      #     id_or_slug: "deal_status",
+      #     status: "under_review",
+      #     data: {
+      #       title: "Pending Review",
+      #       color: "orange"
+      #     }
+      #   )
+      def update_status(object:, id_or_slug:, status:, data:)
+        validate_object!(object)
+        validate_id_or_slug!(id_or_slug)
+        validate_status_id!(status)
+        validate_required_hash!(data, "Status data")
+
+        request(:patch, "objects/#{object}/attributes/#{id_or_slug}/statuses/#{status}", data)
+      end
+
       private def validate_object!(object)
         raise ArgumentError, "Object type is required" if object.nil? || object.to_s.strip.empty?
       end
@@ -28,6 +264,14 @@ module Attio
       private def validate_id_or_slug!(id_or_slug)
         raise ArgumentError, "Attribute ID or slug is required" if id_or_slug.nil? || id_or_slug.to_s.strip.empty?
       end
+
+      private def validate_option_id!(option)
+        raise ArgumentError, "Option ID is required" if option.nil? || option.to_s.strip.empty?
+      end
+
+      private def validate_status_id!(status)
+        raise ArgumentError, "Status ID is required" if status.nil? || status.to_s.strip.empty?
+      end
     end
   end
 end

data/lib/attio/resources/lists.rb

@@ -44,10 +44,205 @@ module Attio
         request(:delete, "lists/#{list_id}/entries/#{entry_id}")
       end
 
+      # Create a new list.
+      #
+      # Creates a new list with the specified configuration. The list can be
+      # associated with a parent object type and configured with various options.
+      #
+      # @param data [Hash] The list configuration data
+      # @option data [String] :name The name of the list (required)
+      # @option data [String] :parent_object The parent object type for the list
+      # @option data [Boolean] :is_public Whether the list is publicly accessible
+      # @option data [String] :description Optional description for the list
+      #
+      # @return [Hash] The created list data
+      # @raise [ArgumentError] if data is invalid
+      #
+      # @example Create a simple list
+      #   list = client.lists.create(
+      #     data: {
+      #       name: "VIP Customers",
+      #       parent_object: "people",
+      #       is_public: true
+      #     }
+      #   )
+      def create(data:)
+        validate_list_data!(data)
+        request(:post, "lists", { data: data })
+      end
+
+      # Update an existing list.
+      #
+      # Updates the configuration of an existing list. You can modify the name,
+      # description, visibility, and other list properties.
+      #
+      # @param id_or_slug [String] The list ID or slug
+      # @param data [Hash] The list configuration updates
+      # @option data [String] :name New name for the list
+      # @option data [Boolean] :is_public New visibility setting
+      # @option data [String] :description New description for the list
+      #
+      # @return [Hash] The updated list data
+      # @raise [ArgumentError] if id_or_slug or data is invalid
+      #
+      # @example Update list name and visibility
+      #   list = client.lists.update(
+      #     id_or_slug: "list_123",
+      #     data: {
+      #       name: "Premium Customers",
+      #       is_public: false
+      #     }
+      #   )
+      def update(id_or_slug:, data:)
+        validate_id!(id_or_slug, "List")
+        validate_list_data!(data)
+        request(:patch, "lists/#{id_or_slug}", { data: data })
+      end
+
+      # Query list entries with advanced filtering and sorting.
+      #
+      # Provides advanced querying capabilities for list entries, supporting
+      # complex filters, sorting, and pagination. This is more powerful than
+      # the basic entries method as it supports structured queries.
+      #
+      # @param id_or_slug [String] The list ID or slug
+      # @param filter [Hash, String, nil] Optional filter criteria for querying entries
+      # @param sort [Hash, Array, String, nil] Optional sorting configuration
+      # @param limit [Integer, nil] Maximum number of entries to return
+      # @param offset [Integer, nil] Number of entries to skip for pagination
+      #
+      # @return [Hash] Query results with entries and pagination info
+      # @raise [ArgumentError] if id_or_slug is invalid
+      #
+      # @example Query with filters
+      #   entries = client.lists.query_entries(
+      #     id_or_slug: "vip_customers",
+      #     filter: { created_at: { gte: "2023-01-01" } },
+      #     sort: { created_at: "desc" },
+      #     limit: 50
+      #   )
+      #
+      # @example Query all entries without filters
+      #   entries = client.lists.query_entries(id_or_slug: "list_123")
+      def query_entries(id_or_slug:, filter: nil, sort: nil, limit: nil, offset: nil)
+        validate_id!(id_or_slug, "List")
+
+        query_params = build_query_params({
+          filter: filter,
+          sort: sort,
+          limit: limit,
+          offset: offset,
+        })
+
+        request(:post, "lists/#{id_or_slug}/entries/query", query_params)
+      end
+
+      # Assert (upsert) a list entry.
+      #
+      # Creates or updates a list entry based on a matching attribute. This is an
+      # upsert operation that will create a new entry if no match is found, or update
+      # an existing entry if a match is found based on the specified matching attribute.
+      #
+      # Required scopes: list_entry:read-write, list_configuration:read
+      #
+      # @param id_or_slug [String] The list ID or slug
+      # @param matching_attribute [String] The attribute to match against for upsert
+      # @param data [Hash] The entry data to create or update
+      # @option data [String] :record_id The ID of the record to add to the list
+      # @option data [Hash] :values Optional field values for the entry
+      # @option data [String] :notes Optional notes for the entry
+      #
+      # @return [Hash] The created or updated entry data
+      # @raise [ArgumentError] if parameters are invalid
+      #
+      # @example Assert entry with record ID
+      #   entry = client.lists.assert_entry(
+      #     id_or_slug: "vip_customers",
+      #     matching_attribute: "record_id",
+      #     data: {
+      #       record_id: "rec_123",
+      #       values: { priority: "high" },
+      #       notes: "Premium customer"
+      #     }
+      #   )
+      #
+      # @example Assert entry with custom matching
+      #   entry = client.lists.assert_entry(
+      #     id_or_slug: "lead_list",
+      #     matching_attribute: "email",
+      #     data: {
+      #       email: "john@example.com",
+      #       values: { status: "qualified" }
+      #     }
+      #   )
+      def assert_entry(id_or_slug:, matching_attribute:, data:)
+        validate_id!(id_or_slug, "List")
+        validate_required_string!(matching_attribute, "Matching attribute")
+        validate_list_entry_data!(data)
+
+        request_body = {
+          data: data,
+          matching_attribute: matching_attribute,
+        }
+
+        request(:put, "lists/#{id_or_slug}/entries", request_body)
+      end
+
+      # Update an existing list entry.
+      #
+      # Updates the data for an existing list entry. This method requires the
+      # entry ID and will update only the provided fields, leaving other fields
+      # unchanged.
+      #
+      # @param id_or_slug [String] The list ID or slug
+      # @param entry_id [String] The entry ID to update
+      # @param data [Hash] The entry data to update
+      # @option data [Hash] :values Field values to update
+      # @option data [String] :notes Updated notes for the entry
+      #
+      # @return [Hash] The updated entry data
+      # @raise [ArgumentError] if parameters are invalid
+      #
+      # @example Update entry values
+      #   entry = client.lists.update_entry(
+      #     id_or_slug: "vip_customers",
+      #     entry_id: "ent_456",
+      #     data: {
+      #       values: { priority: "medium", last_contacted: "2024-01-15" },
+      #       notes: "Updated contact information"
+      #     }
+      #   )
+      #
+      # @example Update only notes
+      #   entry = client.lists.update_entry(
+      #     id_or_slug: "lead_list",
+      #     entry_id: "ent_789",
+      #     data: { notes: "Follow up scheduled" }
+      #   )
+      def update_entry(id_or_slug:, entry_id:, data:)
+        validate_id!(id_or_slug, "List")
+        validate_id!(entry_id, "Entry")
+        validate_list_entry_data!(data)
+
+        request_body = { data: data }
+
+        request(:patch, "lists/#{id_or_slug}/entries/#{entry_id}", request_body)
+      end
+
       private def validate_list_entry_data!(data)
         raise ArgumentError, "Data is required" if data.nil?
         raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
       end
+
+      # Validates that the list data parameter is present and valid.
+      #
+      # @param data [Hash, nil] The data to validate
+      # @raise [ArgumentError] if data is nil or not a hash
+      # @api private
+      private def validate_list_data!(data)
+        raise ArgumentError, "Data is required" if data.nil?
+        raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
+      end
     end
   end
 end

data/lib/attio/resources/meta.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # Meta resource for getting information about the API token and workspace
+    #
+    # The Meta resource provides a single endpoint (/v2/self) that returns
+    # information about the current access token, workspace, and permissions.
+    #
+    # @example Get token and workspace information
+    #   meta_info = client.meta.identify
+    #   puts "Workspace: #{meta_info['data']['workspace_name']}"
+    #   puts "Token active: #{meta_info['data']['active']}"
+    #
+    # @example Check if token is active
+    #   if client.meta.active?
+    #     puts "Token is valid and active"
+    #   end
+    #
+    # @example Get workspace details
+    #   workspace = client.meta.workspace
+    #   puts "Working in: #{workspace['name']} (#{workspace['id']})"
+    #
+    # @example Check permissions
+    #   if client.meta.permission?("record_permission:read-write")
+    #     # Can read and write records
+    #   end
+    class Meta < Base
+      # Get information about the current access token and workspace
+      #
+      # This is the primary method that calls the /v2/self endpoint.
+      # Returns full token metadata including workspace info and permissions.
+      #
+      # @return [Hash] Token and workspace information
+      # @example
+      #   info = client.meta.identify
+      #   # => { "data" => { "active" => true, "workspace_name" => "My Workspace", ... } }
+      def identify
+        request(:get, "self")
+      end
+
+      # Alias methods for convenience and clarity
+      alias self identify
+      alias get identify
+
+      # Check if the current token is active
+      #
+      # @return [Boolean] true if token is active, false otherwise
+      # @example
+      #   if client.meta.active?
+      #     # Proceed with API calls
+      #   else
+      #     # Token is inactive or invalid
+      #   end
+      def active?
+        response = identify
+        response.dig("data", "active") || false
+      end
+
+      # Get the workspace information
+      #
+      # Returns workspace details if token is active, nil otherwise.
+      #
+      # @return [Hash, nil] Workspace details or nil if token inactive
+      # @example
+      #   workspace = client.meta.workspace
+      #   # => { "id" => "uuid", "name" => "My Workspace", "slug" => "my-workspace", "logo_url" => nil }
+      def workspace
+        response = identify
+        return nil unless response.dig("data", "active")
+
+        {
+          "id" => response.dig("data", "workspace_id"),
+          "name" => response.dig("data", "workspace_name"),
+          "slug" => response.dig("data", "workspace_slug"),
+          "logo_url" => response.dig("data", "workspace_logo_url"),
+        }
+      end
+
+      # Get the token's permissions/scopes
+      #
+      # Parses the space-separated scope string into an array.
+      #
+      # @return [Array<String>] List of permission scopes
+      # @example
+      #   permissions = client.meta.permissions
+      #   # => ["comment:read-write", "list_configuration:read", "note:read-write"]
+      def permissions
+        response = identify
+        scope = response.dig("data", "scope") || ""
+        scope.split
+      end
+
+      # Check if token has a specific permission
+      #
+      # @param permission [String] The permission to check (e.g., "comment:read-write")
+      # @return [Boolean] true if permission is granted
+      # @example
+      #   if client.meta.permission?("record_permission:read-write")
+      #     # Can manage records
+      #   end
+      def permission?(permission)
+        permissions.include?(permission)
+      end
+
+      # Alias for backward compatibility
+      alias has_permission? permission?
+
+      # Get token expiration and metadata
+      #
+      # Returns detailed token information including expiration,
+      # issue time, client ID, and who authorized it.
+      #
+      # @return [Hash] Token metadata
+      # @example
+      #   info = client.meta.token_info
+      #   # => { "active" => true, "type" => "Bearer", "expires_at" => nil, ... }
+      def token_info
+        response = identify
+        return { "active" => false } unless response.dig("data", "active")
+
+        {
+          "active" => true,
+          "type" => response.dig("data", "token_type"),
+          "expires_at" => response.dig("data", "exp"),
+          "issued_at" => response.dig("data", "iat"),
+          "client_id" => response.dig("data", "client_id"),
+          "authorized_by" => response.dig("data", "authorized_by_workspace_member_id"),
+        }
+      end
+    end
+  end
+end