attio 0.4.0 → 0.5.0

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

@@ -153,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

data/lib/attio/resources/workspaces.rb

@@ -5,16 +5,25 @@ module Attio
     # API resource for managing workspace information
     #
     # Workspaces are the top-level organizational unit in Attio.
+    # Note: The workspace information is retrieved via the Meta API (/v2/self)
     #
     # @example Getting workspace information
     #   client.workspaces.get
     class Workspaces < Base
+      # Get current workspace information
+      #
+      # This method retrieves workspace info from the /v2/self endpoint
+      # which provides workspace context along with token information.
+      #
+      # @return [Hash] Workspace information from the self endpoint
       def get
-        request(:get, "workspace")
+        request(:get, "self")
       end
 
+      # @deprecated Use client.workspace_members.list instead
       def members(**params)
-        request(:get, "workspace/members", params)
+        warn "[DEPRECATION] `workspaces.members` is deprecated. Use `workspace_members.list` instead."
+        request(:get, "workspace_members", params)
       end
     end
   end

data/lib/attio/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Attio
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/attio.rb

@@ -9,6 +9,7 @@ require "attio/client"
 
 # Resources
 require "attio/resources/base"
+require "attio/resources/meta"
 require "attio/resources/records"
 require "attio/resources/objects"
 require "attio/resources/lists"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attio
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Ernest Sim
@@ -55,6 +55,7 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- META_IMPLEMENTATION_PLAN.md
 - README.md
 - Rakefile
 - SECURITY.md
@@ -125,6 +126,7 @@ files:
 - lib/attio/resources/comments.rb
 - lib/attio/resources/deals.rb
 - lib/attio/resources/lists.rb
+- lib/attio/resources/meta.rb
 - lib/attio/resources/notes.rb
 - lib/attio/resources/objects.rb
 - lib/attio/resources/records.rb