attio 0.3.0 → 0.5.0

data/lib/attio/resources/base.rb

@@ -104,6 +104,59 @@ module Attio
       private def handle_delete_request(connection, path, params)
         params.empty? ? connection.delete(path) : connection.delete(path, params)
       end
+
+      # Paginate through all results for a given endpoint
+      # @param path [String] The API endpoint path
+      # @param params [Hash] Query parameters including filters
+      # @param page_size [Integer] Number of items per page (default: 50)
+      # @return [Enumerator] Yields each item from all pages
+      private def paginate(path, params = {}, page_size: 50)
+        Enumerator.new do |yielder|
+          offset = 0
+          loop do
+            page_params = params.merge(limit: page_size, offset: offset)
+            # Use POST for query endpoints, GET for others
+            method = path.end_with?("/query") ? :post : :get
+            response = request(method, path, page_params)
+
+            data = response["data"] || []
+            data.each { |item| yielder << item }
+
+            # Stop if we got fewer items than requested (last page)
+            break if data.size < page_size
+
+            offset += page_size
+          end
+        end
+      end
+
+      # Build query parameters with filtering and sorting support
+      # @param options [Hash] Options including filter, sort, limit, offset
+      # @return [Hash] Formatted query parameters
+      private def build_query_params(options = {})
+        params = {}
+
+        # Add filtering
+        add_filter_param(params, options[:filter]) if options[:filter]
+
+        # Add standard parameters
+        %i[sort limit offset].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        # Add any other parameters
+        options.each do |key, value|
+          next if %i[filter sort limit offset].include?(key)
+
+          params[key] = value
+        end
+
+        params
+      end
+
+      private def add_filter_param(params, filter)
+        params[:filter] = filter.is_a?(String) ? filter : filter.to_json
+      end
     end
   end
 end

data/lib/attio/resources/bulk.rb

@@ -196,7 +196,7 @@ module Attio
         raise ArgumentError, "Records array is required for bulk #{operation}" if records.nil?
         raise ArgumentError, "Records must be an array for bulk #{operation}" unless records.is_a?(Array)
         raise ArgumentError, "Records array cannot be empty for bulk #{operation}" if records.empty?
-        raise ArgumentError, "Too many records (max #{MAX_BATCH_SIZE * 10})" if records.size > MAX_BATCH_SIZE * 10
+        raise ArgumentError, "Too many records (max 1000)" if records.size > MAX_BATCH_SIZE * 10
 
         records.each_with_index do |record, index|
           raise ArgumentError, "Record at index #{index} must be a hash" unless record.is_a?(Hash)

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

@@ -2,70 +2,131 @@
 
 module Attio
   module Resources
-    # Meta resource for API metadata and identification
+    # Meta resource for getting information about the API token and workspace
     #
-    # @example Identify the current API key
-    #   client.meta.identify
-    #   # => { "workspace" => { "id" => "...", "name" => "..." }, "user" => { ... } }
+    # The Meta resource provides a single endpoint (/v2/self) that returns
+    # information about the current access token, workspace, and permissions.
     #
-    # @example Get API status
-    #   client.meta.status
-    #   # => { "status" => "operational", "version" => "v2" }
+    # @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
-      # Identify the current API key and get workspace/user information
+      # 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] Information about the authenticated workspace and user
+      # @return [Hash] Token and workspace information
+      # @example
+      #   info = client.meta.identify
+      #   # => { "data" => { "active" => true, "workspace_name" => "My Workspace", ... } }
       def identify
-        request(:get, "meta/identify")
+        request(:get, "self")
       end
 
-      # Get API status and version information
-      #
-      # @return [Hash] API status and version details
-      def status
-        request(:get, "meta/status")
-      end
+      # Alias methods for convenience and clarity
+      alias self identify
+      alias get identify
 
-      # Get rate limit information for the current API key
+      # Check if the current token is active
       #
-      # @return [Hash] Current rate limit status
-      def rate_limits
-        request(:get, "meta/rate_limits")
+      # @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 workspace configuration and settings
+      # Get the workspace information
       #
-      # @return [Hash] Workspace configuration details
-      def workspace_config
-        request(:get, "meta/workspace_config")
-      end
-
-      # Validate an API key without making changes
+      # Returns workspace details if token is active, nil otherwise.
       #
-      # @return [Hash] Validation result with key permissions
-      def validate_key
-        request(:post, "meta/validate", {})
+      # @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 available API endpoints and their documentation
+      # Get the token's permissions/scopes
+      #
+      # Parses the space-separated scope string into an array.
       #
-      # @return [Hash] List of available endpoints with descriptions
-      def endpoints
-        request(:get, "meta/endpoints")
+      # @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
 
-      # Get workspace usage statistics
+      # Check if token has a specific permission
       #
-      # @return [Hash] Usage statistics including record counts, API calls, etc.
-      def usage_stats
-        request(:get, "meta/usage")
+      # @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
 
-      # Get feature flags and capabilities for the workspace
+      # 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] Enabled features and capabilities
-      def features
-        request(:get, "meta/features")
+      # @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

data/lib/attio/resources/objects.rb

@@ -9,16 +9,120 @@ module Attio
     #
     # @example Listing all objects
     #   client.objects.list
+    #
+    # @example Creating a custom object
+    #   client.objects.create(
+    #     api_slug: "projects",
+    #     singular_noun: "Project",
+    #     plural_noun: "Projects"
+    #   )
+    #
+    # @example Updating a custom object
+    #   client.objects.update(
+    #     id_or_slug: "projects",
+    #     plural_noun: "Active Projects"
+    #   )
     class Objects < Base
+      # List all objects in the workspace
+      #
+      # @param params [Hash] Optional query parameters
+      # @return [Hash] List of objects
       def list(**params)
         request(:get, "objects", params)
       end
 
+      # Get a single object by ID or slug
+      #
+      # @param id_or_slug [String] The object ID or slug
+      # @return [Hash] The object details
       def get(id_or_slug:)
         validate_id_or_slug!(id_or_slug)
         request(:get, "objects/#{id_or_slug}")
       end
 
+      # Create a new custom object
+      #
+      # @param api_slug [String] Unique slug for the object (snake_case)
+      # @param singular_noun [String] Singular name of the object
+      # @param plural_noun [String] Plural name of the object
+      # @return [Hash] The created object with ID and timestamps
+      # @raise [ArgumentError] if required parameters are missing
+      # @example
+      #   object = client.objects.create(
+      #     api_slug: "projects",
+      #     singular_noun: "Project",
+      #     plural_noun: "Projects"
+      #   )
+      def create(api_slug:, singular_noun:, plural_noun:)
+        validate_required_string!(api_slug, "API slug")
+        validate_required_string!(singular_noun, "Singular noun")
+        validate_required_string!(plural_noun, "Plural noun")
+
+        data = {
+          api_slug: api_slug,
+          singular_noun: singular_noun,
+          plural_noun: plural_noun,
+        }
+
+        request(:post, "objects", { data: data })
+      end
+
+      # Update an existing custom object
+      #
+      # @param id_or_slug [String] The object ID or slug to update
+      # @param api_slug [String, nil] New API slug (optional)
+      # @param singular_noun [String, nil] New singular noun (optional)
+      # @param plural_noun [String, nil] New plural noun (optional)
+      # @return [Hash] The updated object
+      # @raise [ArgumentError] if no update fields are provided
+      # @example Update just the plural noun
+      #   client.objects.update(
+      #     id_or_slug: "projects",
+      #     plural_noun: "Active Projects"
+      #   )
+      # @example Update multiple fields
+      #   client.objects.update(
+      #     id_or_slug: "old_slug",
+      #     api_slug: "new_slug",
+      #     singular_noun: "New Name",
+      #     plural_noun: "New Names"
+      #   )
+      def update(id_or_slug:, api_slug: nil, singular_noun: nil, plural_noun: nil)
+        validate_id_or_slug!(id_or_slug)
+
+        data = {}
+        data[:api_slug] = api_slug if api_slug
+        data[:singular_noun] = singular_noun if singular_noun
+        data[:plural_noun] = plural_noun if plural_noun
+
+        raise ArgumentError, "At least one field to update is required" if data.empty?
+
+        request(:patch, "objects/#{id_or_slug}", { data: data })
+      end
+
+      # Delete a custom object
+      #
+      # NOTE: The Attio API v2.0.0 does not currently support deleting custom objects.
+      # To delete a custom object, please visit your Attio settings at:
+      # Settings > Data Model > Objects
+      #
+      # @param id_or_slug [String] The object ID or slug to delete
+      # @raise [NotImplementedError] Always raised as the API doesn't support this operation
+      # @example
+      #   client.objects.delete(id_or_slug: "projects")
+      #   # => NotImplementedError: The Attio API does not currently support deleting custom objects.
+      #   #    Please delete objects through the Attio UI at: Settings > Data Model > Objects
+      def delete(id_or_slug:)
+        validate_id_or_slug!(id_or_slug)
+        raise NotImplementedError,
+              "The Attio API does not currently support deleting custom objects. " \
+              "Please delete objects through the Attio UI at: Settings > Data Model > Objects"
+      end
+
+      # Alias for delete method for consistency with other resources
+      # NOTE: See delete method for API limitations
+      alias destroy delete
+
       private def validate_id_or_slug!(id_or_slug)
         raise ArgumentError, "Object ID or slug is required" if id_or_slug.nil? || id_or_slug.to_s.strip.empty?
       end

data/lib/attio/resources/records.rb

@@ -44,9 +44,36 @@ module Attio
       #     filters: { name: { contains: 'John' } },
       #     limit: 50
       #   )
-      def list(object:, **params)
+      def list(object:, filter: nil, sort: nil, limit: nil, offset: nil, **params)
         validate_required_string!(object, "Object type")
-        request(:post, "objects/#{object}/records/query", params)
+
+        # Build query parameters with filtering and sorting support
+        query_params = build_query_params({
+          filter: filter,
+          sort: sort,
+          limit: limit,
+          offset: offset,
+          **params,
+        })
+
+        request(:post, "objects/#{object}/records/query", query_params)
+      end
+
+      # List all records with automatic pagination
+      # @param object [String] The object type to query
+      # @param filter [Hash] Filtering criteria
+      # @param sort [String] Sorting option
+      # @param page_size [Integer] Number of records per page
+      # @return [Enumerator] Enumerator that yields each record
+      def list_all(object:, filter: nil, sort: nil, page_size: 50)
+        validate_required_string!(object, "Object type")
+
+        query_params = build_query_params({
+          filter: filter,
+          sort: sort,
+        })
+
+        paginate("objects/#{object}/records/query", query_params, page_size: page_size)
       end
 
       # Retrieve a specific record by ID.
@@ -126,6 +153,74 @@ module Attio
         request(:delete, "objects/#{object}/records/#{id}")
       end
 
+      # Assert (upsert) a record based on a matching attribute.
+      #
+      # This method creates or updates a record based on a matching attribute,
+      # providing upsert functionality. If a record with the matching attribute
+      # value exists, it will be updated; otherwise, a new record will be created.
+      #
+      # @param object [String] The object type (e.g., 'people', 'companies')
+      # @param matching_attribute [String] The attribute to match against for upsert
+      # @param data [Hash] The record data to create or update
+      #
+      # @return [Hash] The created or updated record data
+      # @raise [ArgumentError] if object, matching_attribute, or data is invalid
+      #
+      # @example Assert a person by email
+      #   record = client.records.assert(
+      #     object: 'people',
+      #     matching_attribute: 'email',
+      #     data: {
+      #       name: 'Jane Doe',
+      #       email: 'jane@example.com',
+      #       company: { target_object: 'companies', target_record_id: 'company123' }
+      #     }
+      #   )
+      def assert(object:, matching_attribute:, data:)
+        validate_required_string!(object, "Object type")
+        validate_required_string!(matching_attribute, "Matching attribute")
+        validate_record_data!(data)
+
+        request_body = {
+          data: data,
+          matching_attribute: matching_attribute,
+        }
+
+        request(:put, "objects/#{object}/records", request_body)
+      end
+
+      # Update a record using PUT (replace operation).
+      #
+      # This method performs a complete replacement of the record, unlike the
+      # regular update method which uses PATCH. For multiselect fields, this
+      # overwrites the values instead of appending to them.
+      #
+      # @param object [String] The object type (e.g., 'people', 'companies')
+      # @param id [String] The record ID to replace
+      # @param data [Hash] The complete record data to replace with
+      #
+      # @return [Hash] The updated record data
+      # @raise [ArgumentError] if object, id, or data is invalid
+      #
+      # @example Replace a person's data
+      #   record = client.records.update_with_put(
+      #     object: 'people',
+      #     id: 'abc123',
+      #     data: {
+      #       name: 'Jane Smith',
+      #       email: 'jane.smith@example.com',
+      #       tags: ['customer', 'vip']  # This will replace all existing tags
+      #     }
+      #   )
+      def update_with_put(object:, id:, data:)
+        validate_required_string!(object, "Object type")
+        validate_id!(id, "Record")
+        validate_record_data!(data)
+
+        request_body = { data: data }
+        request(:put, "objects/#{object}/records/#{id}", request_body)
+      end
+
       # Validates that the data parameter is present and is a hash.
       #
       # @param data [Hash, nil] The data to validate