wip-ruby 0.2.0

data/lib/wip/models/collection.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Wip
+  module Models
+    # Represents a paginated collection of items
+    class Collection
+      include Enumerable
+
+      # @return [Array<Base>] The items in the collection
+      attr_reader :data
+
+      # @return [Boolean] Whether there are more items
+      attr_reader :has_more
+
+      # @return [Integer] The total count of items
+      attr_reader :total_count
+
+      # Initialize a new collection
+      # @param data [Array<Base>] The items in the collection
+      # @param has_more [Boolean] Whether there are more items
+      # @param total_count [Integer] The total count of items
+      def initialize(data:, has_more:, total_count:)
+        @data = data
+        @has_more = has_more
+        @total_count = total_count
+      end
+
+      # Create a new collection from a JSON response
+      # @param json [Hash] The JSON response
+      # @param item_class [Class] The class to instantiate items as
+      # @return [Collection] The new collection
+      # @raise [ArgumentError] If json is nil or not a Hash
+      def self.from_json(json, item_class:)
+        raise ArgumentError, "Expected Hash, got #{json.class}" unless json.is_a?(Hash)
+
+        data = json["data"]
+        raise ArgumentError, "Missing 'data' key in response" unless data.is_a?(Array)
+
+        new(
+          data: data.map { |item| item_class.from_json(item) },
+          has_more: json.fetch("has_more", false),
+          total_count: json["total_count"]
+        )
+      end
+
+      # Iterate over the items in the collection
+      # @yield [item] Each item in the collection
+      # @return [Enumerator] If no block is given
+      def each(&block)
+        data.each(&block)
+      end
+
+      # @return [Integer] The number of items in the collection
+      def size
+        data.size
+      end
+      alias length size
+      alias count size
+
+      # @return [Boolean] Whether the collection is empty
+      def empty?
+        data.empty?
+      end
+
+      # @return [Base, nil] The first item in the collection
+      def first
+        data.first
+      end
+
+      # @return [Base, nil] The last item in the collection
+      def last
+        data.last
+      end
+
+      # @return [String, nil] The ID of the last item (for pagination)
+      def last_id
+        last&.id
+      end
+    end
+  end
+end

data/lib/wip/models/comment.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "user"
+require_relative "concerns/reactable"
+
+module Wip
+  module Models
+    # Represents a comment on a todo
+    class Comment < Base
+      include Concerns::Reactable
+
+      attribute :id, type: :string
+      attribute :body, type: :string
+      attribute :created_at, type: :time
+      attribute :updated_at, type: :time
+      attribute :url, type: :string
+      attribute :reactions_count, type: :integer
+      attribute :viewer, type: Hash # Hash with reactions array
+      attribute :creator, type: User
+
+      # @return [String] String representation of the comment
+      def to_s
+        body
+      end
+    end
+  end
+end

data/lib/wip/models/concerns/reactable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Wip
+  module Models
+    module Concerns
+      # Shared behavior for models that can have reactions (Todo, Comment)
+      module Reactable
+        # @return [Boolean] Whether this resource has any reactions
+        def reactions?
+          reactions_count&.positive?
+        end
+
+        # @return [Array<Hash>] The viewer's reactions on this resource (empty if none)
+        def viewer_reactions
+          viewer&.dig("reactions") || []
+        end
+
+        # @return [Boolean] Whether the authenticated user has reacted to this resource
+        def reacted_by_viewer?
+          viewer_reactions.any?
+        end
+      end
+    end
+  end
+end

data/lib/wip/models/project.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "user"
+
+module Wip
+  module Models
+    # Represents a project
+    class Project < Base
+      attribute :id, type: :string
+      attribute :slug, type: :string
+      attribute :name, type: :string
+      attribute :pitch, type: :string
+      attribute :description, type: :string
+      attribute :created_at, type: :time
+      attribute :updated_at, type: :time
+      attribute :hashtag, type: :string
+      attribute :website_url, type: :string
+      attribute :protected, type: :boolean
+      attribute :archived, type: :boolean
+      attribute :url, type: :string
+      attribute :logo, type: Hash # Hash with small, medium, large URLs
+      attribute :owner, type: User
+      attribute :makers, type: [User]
+
+      # @return [String] String representation of the project
+      def to_s
+        name
+      end
+
+      # @return [Boolean] Whether this project has a logo
+      def logo?
+        logo&.any?
+      end
+
+      # @return [Boolean] Whether this project has multiple makers
+      def team_project?
+        makers&.length.to_i > 1
+      end
+
+      # @return [String, nil] The logo URL for the given size
+      # @param size [Symbol] The size of the logo (:small, :medium, :large)
+      def logo_url(size = :medium)
+        logo&.dig(size.to_s)
+      end
+    end
+  end
+end

data/lib/wip/models/reaction.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "user"
+
+module Wip
+  module Models
+    # Represents a reaction (like) on a todo or comment
+    class Reaction < Base
+      attribute :id, type: :string
+      attribute :created_at, type: :time
+      attribute :reactable_type, type: :string
+      attribute :reactable_id, type: :string
+      attribute :reactor, type: User
+
+      # @return [String] String representation of the reaction
+      def to_s
+        "Reaction by #{reactor} on #{reactable_type} #{reactable_id}"
+      end
+
+      # @return [Boolean] Whether this reaction is on a todo
+      def on_todo?
+        reactable_type == "Todo"
+      end
+
+      # @return [Boolean] Whether this reaction is on a comment
+      def on_comment?
+        reactable_type == "Comment"
+      end
+    end
+  end
+end

data/lib/wip/models/todo.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "project"
+require_relative "concerns/reactable"
+
+module Wip
+  module Models
+    # Represents a todo item
+    class Todo < Base
+      include Concerns::Reactable
+
+      attribute :id, type: :string
+      attribute :created_at, type: :time
+      attribute :updated_at, type: :time
+      attribute :body, type: :string
+      attribute :url, type: :string
+      attribute :attachments, type: [Hash] # Array of attachment objects
+      attribute :creator_id, type: :string
+      attribute :user_id, type: :string # @deprecated Use creator_id instead
+      attribute :projects, type: [Project]
+      attribute :reactions_count, type: :integer
+      attribute :comments_count, type: :integer
+      attribute :viewer, type: Hash # Hash with reactions and comments arrays
+
+      # @return [String] String representation of the todo
+      def to_s
+        body
+      end
+
+      # @return [Boolean] Whether this todo has any attachments
+      def attachments?
+        attachments&.any?
+      end
+
+      # @return [Boolean] Whether this todo belongs to any projects
+      def projects?
+        projects&.any?
+      end
+
+      # @return [Boolean] Whether this todo has any comments
+      def comments?
+        comments_count&.positive?
+      end
+
+      # @return [Array<Hash>] The viewer's comments on this todo (empty if none)
+      def viewer_comments
+        viewer&.dig("comments") || []
+      end
+
+      # @return [Boolean] Whether the authenticated user has commented on this todo
+      def commented_by_viewer?
+        viewer_comments.any?
+      end
+    end
+  end
+end

data/lib/wip/models/user.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module Wip
+  module Models
+    # Represents a user
+    class User < Base
+      attribute :id, type: :string
+      attribute :username, type: :string
+      attribute :streak, type: :integer
+      attribute :created_at, type: :time
+      attribute :updated_at, type: :time
+      attribute :protected, type: :boolean
+      attribute :first_name, type: :string
+      attribute :last_name, type: :string
+      attribute :todos_count, type: :integer
+      attribute :time_zone, type: :string
+      attribute :url, type: :string
+      attribute :avatar, type: Hash # Hash with small, medium, large URLs
+      attribute :best_streak, type: :integer
+      attribute :streaking, type: :boolean
+
+      # @return [String] The user's full name
+      def full_name
+        [first_name, last_name].compact.join(" ").strip
+      end
+
+      # @return [String] String representation of the user
+      def to_s
+        full_name.empty? ? username : full_name
+      end
+
+      # @return [String, nil] The avatar URL for the given size
+      # @param size [Symbol] The size of the avatar (:small, :medium, :large)
+      def avatar_url(size = :medium)
+        avatar&.dig(size.to_s)
+      end
+
+      # @return [Boolean] Whether the user has completed any todos
+      def todos?
+        todos_count&.positive?
+      end
+
+      # @return [Boolean] Whether the user is currently on a streak
+      def on_streak?
+        streak&.positive? && streaking?
+      end
+    end
+  end
+end

data/lib/wip/resources/base.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Wip
+  module Resources
+    # Base class for all API resources
+    # @api private
+    class Base
+      # @return [HTTPClient] The HTTP client instance
+      attr_reader :client
+
+      # Initialize a new resource
+      # @param client [HTTPClient] The HTTP client instance
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      # Build a path with parameters
+      # @param path [String] The path template
+      # @param params [Hash] The parameters to interpolate
+      # @return [String] The built path
+      def build_path(path, params = {})
+        path.gsub(/\{([^}]+)\}/) do |match|
+          key = Regexp.last_match(1)
+          value = params[key.to_sym] || params[key.to_s]
+          raise ArgumentError, "Missing parameter: #{key}" unless value
+          value.to_s
+        end
+      end
+
+      # Extract pagination parameters from options
+      # @param options [Hash] The options hash
+      # @return [Hash] The pagination parameters
+      def extract_pagination_params(options)
+        {
+          limit: options[:limit],
+          starting_after: options[:starting_after]
+        }.compact
+      end
+
+      # Extract pagination and date filter parameters for todo endpoints
+      # @param options [Hash] The options hash
+      # @option options [Integer] :limit Number of items to return
+      # @option options [String] :starting_after Cursor for pagination
+      # @option options [Time, Date, String, Integer] :since Filter todos created since this date
+      # @option options [Time, Date, String, Integer] :before Filter todos created before this date
+      # @return [Hash] The query parameters
+      def extract_todo_params(options)
+        params = extract_pagination_params(options)
+        params[:since] = format_date_param(options[:since]) if options[:since]
+        params[:until] = format_date_param(options[:before]) if options[:before]
+        params
+      end
+
+      # Format a date parameter for the API
+      # Accepts: Time, Date, String (ISO 8601, YYYY, YYYY-MM, YYYY-MM-DD), or Integer (Unix timestamp)
+      # @param value [Time, Date, String, Integer] The date value
+      # @return [String] The formatted date string
+      def format_date_param(value)
+        case value
+        when Time
+          value.utc.iso8601
+        when Date
+          value.iso8601
+        when Integer
+          # Unix timestamp
+          value.to_s
+        when String
+          # Pass through strings as-is (API accepts multiple formats)
+          value
+        else
+          raise ArgumentError, "Invalid date value: #{value.inspect}. Expected Time, Date, String, or Integer (Unix timestamp)"
+        end
+      end
+    end
+  end
+end

data/lib/wip/resources/comments.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/comment"
+require_relative "../models/collection"
+
+module Wip
+  module Resources
+    # Resource for interacting with comments
+    #
+    # Comments can be added to todos. The authenticated user can create, update,
+    # and delete their own comments.
+    #
+    # @example Create a comment on a todo
+    #   client.comments.create(
+    #     commentable_type: "Todo",
+    #     commentable_id: "todo_123",
+    #     body: "Great progress!"
+    #   )
+    #
+    # @example List comments for a todo
+    #   client.comments.for_todo("todo_123")
+    class Comments < Base
+      # Valid commentable types
+      COMMENTABLE_TYPES = %w[Todo].freeze
+
+      # List comments for a todo
+      # @param todo_id [String] The todo ID
+      # @param limit [Integer] Number of items to return (default: 25)
+      # @param starting_after [String] Cursor for pagination
+      # @return [Models::Collection<Models::Comment>] The paginated comments
+      def for_todo(todo_id, limit: nil, starting_after: nil)
+        path = build_path("/v1/todos/{todo_id}/comments", todo_id: todo_id)
+        params = extract_pagination_params(limit: limit, starting_after: starting_after)
+        response = client.get(path, params)
+        Models::Collection.from_json(response.extract_resource, item_class: Models::Comment)
+      end
+
+      # Create a comment on a resource
+      # @param commentable_type [String] The type of resource to comment on ("Todo")
+      # @param commentable_id [String] The ID of the resource to comment on
+      # @param body [String] The content of the comment
+      # @return [Models::Comment] The created comment
+      # @raise [ArgumentError] If commentable_type is invalid
+      def create(commentable_type:, commentable_id:, body:)
+        validate_commentable_type!(commentable_type)
+        validate_body!(body)
+
+        response = client.post("/v1/comments", {
+          commentable_type: commentable_type,
+          commentable_id: commentable_id,
+          body: body
+        })
+        Models::Comment.from_json(response.extract_resource)
+      end
+
+      # Update a comment
+      # @param comment_id [String] The comment ID
+      # @param body [String] The new content of the comment
+      # @return [Models::Comment] The updated comment
+      # @note You can only update your own comments
+      def update(comment_id, body:)
+        validate_body!(body)
+
+        path = build_path("/v1/comments/{comment_id}", comment_id: comment_id)
+        response = client.patch(path, { body: body })
+        Models::Comment.from_json(response.extract_resource)
+      end
+
+      # Delete a comment
+      # @param comment_id [String] The comment ID
+      # @return [Boolean] True if deletion was successful
+      # @note You can only delete your own comments
+      def delete(comment_id)
+        path = build_path("/v1/comments/{comment_id}", comment_id: comment_id)
+        client.delete(path)
+        true
+      end
+
+      private
+
+      def validate_commentable_type!(type)
+        return if COMMENTABLE_TYPES.include?(type)
+
+        raise ArgumentError, "Invalid commentable_type '#{type}'. Must be one of: #{COMMENTABLE_TYPES.join(', ')}"
+      end
+
+      def validate_body!(body)
+        raise ArgumentError, "Comment body cannot be empty" if body.nil? || body.strip.empty?
+      end
+    end
+  end
+end

data/lib/wip/resources/projects.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/project"
+require_relative "../models/todo"
+require_relative "../models/collection"
+
+module Wip
+  module Resources
+    # Resource for interacting with projects
+    #
+    # @example Get a project
+    #   client.projects.find("project_123")
+    #
+    # @example List todos for a project
+    #   client.projects.todos("project_123", limit: 10)
+    class Projects < Base
+      # Get a single project by ID
+      # @param project_id [String] The project ID
+      # @return [Models::Project] The project
+      def find(project_id)
+        path = build_path("/v1/projects/{project_id}", project_id: project_id)
+        response = client.get(path)
+        Models::Project.from_json(response.extract_resource)
+      end
+
+      # List todos for a project
+      # @param project_id [String] The project ID
+      # @param limit [Integer] Number of items to return (default: 25)
+      # @param starting_after [String] Cursor for pagination
+      # @param since [Time, Date, String, Integer] Filter todos created since this date
+      # @param before [Time, Date, String, Integer] Filter todos created before this date (maps to API's `until` param)
+      # @return [Models::Collection<Models::Todo>] The paginated todos
+      def todos(project_id, limit: nil, starting_after: nil, since: nil, before: nil)
+        path = build_path("/v1/projects/{project_id}/todos", project_id: project_id)
+        params = extract_todo_params(limit: limit, starting_after: starting_after, since: since, before: before)
+        response = client.get(path, params)
+        Models::Collection.from_json(response.extract_resource, item_class: Models::Todo)
+      end
+    end
+  end
+end

data/lib/wip/resources/reactions.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/reaction"
+
+module Wip
+  module Resources
+    # Resource for interacting with reactions (likes)
+    #
+    # Reactions can be added to todos and comments. Each user can only have one
+    # reaction per resource. If the user has already reacted, the existing
+    # reaction is returned.
+    #
+    # @example React to a todo
+    #   client.reactions.create(
+    #     reactable_type: "Todo",
+    #     reactable_id: "todo_123"
+    #   )
+    #
+    # @example Remove a reaction
+    #   client.reactions.delete("reaction_123")
+    class Reactions < Base
+      # Valid reactable types
+      REACTABLE_TYPES = %w[Todo Comment].freeze
+
+      # Create a reaction on a resource
+      # @param reactable_type [String] The type of resource to react to ("Todo" or "Comment")
+      # @param reactable_id [String] The ID of the resource to react to
+      # @return [Models::Reaction] The created reaction (or existing if already reacted)
+      # @raise [ArgumentError] If reactable_type is invalid
+      def create(reactable_type:, reactable_id:)
+        validate_reactable_type!(reactable_type)
+
+        response = client.post("/v1/reactions", {
+          reactable_type: reactable_type,
+          reactable_id: reactable_id
+        })
+        Models::Reaction.from_json(response.extract_resource)
+      end
+
+      # Delete a reaction
+      # @param reaction_id [String] The reaction ID
+      # @return [Boolean] True if deletion was successful
+      # @note You can only delete your own reactions
+      def delete(reaction_id)
+        path = build_path("/v1/reactions/{reaction_id}", reaction_id: reaction_id)
+        client.delete(path)
+        true
+      end
+
+      # Convenience method to react to a todo
+      # @param todo_id [String] The todo ID
+      # @return [Models::Reaction] The created reaction
+      def react_to_todo(todo_id)
+        create(reactable_type: "Todo", reactable_id: todo_id)
+      end
+
+      # Convenience method to react to a comment
+      # @param comment_id [String] The comment ID
+      # @return [Models::Reaction] The created reaction
+      def react_to_comment(comment_id)
+        create(reactable_type: "Comment", reactable_id: comment_id)
+      end
+
+      private
+
+      def validate_reactable_type!(type)
+        return if REACTABLE_TYPES.include?(type)
+
+        raise ArgumentError, "Invalid reactable_type '#{type}'. Must be one of: #{REACTABLE_TYPES.join(', ')}"
+      end
+    end
+  end
+end

data/lib/wip/resources/todos.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../models/todo"
+require_relative "../models/collection"
+
+module Wip
+  module Resources
+    # Resource for interacting with todos
+    #
+    # @example Create a todo
+    #   client.todos.create(body: "Shipped new feature!")
+    #
+    # @example Get a specific todo
+    #   client.todos.find("todo_123")
+    #
+    # @note To list todos, use the appropriate resource:
+    #   - `client.users.todos("username")` for a user's todos
+    #   - `client.projects.todos("project_id")` for a project's todos
+    #   - `client.viewer.todos` for your own todos
+    class Todos < Base
+      # Create a new completed todo
+      # @param body [String] The content of the todo
+      # @param attachments [Array<String>] List of attachment signed IDs
+      # @return [Models::Todo] The created todo
+      # @raise [ArgumentError] If body is empty
+      def create(body:, attachments: [])
+        raise ArgumentError, "Todo body cannot be empty" if body.nil? || body.strip.empty?
+
+        response = client.post("/v1/todos", {
+          body: body,
+          attachments: attachments
+        })
+        Models::Todo.from_json(response.extract_resource(:todo))
+      end
+
+      # Get a single todo by ID
+      # @param todo_id [String] The todo ID
+      # @return [Models::Todo] The todo
+      def find(todo_id)
+        path = build_path("/v1/todos/{todo_id}", todo_id: todo_id)
+        response = client.get(path)
+        Models::Todo.from_json(response.extract_resource)
+      end
+    end
+  end
+end