todoist_rest_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 599001423d712e315184e5ce3b5bad778d95c9b4ea7cbd16e867f040eaadcc1a
+  data.tar.gz: eb3fbdbd38a3b8d7a080aaf36119375f22c10db8158147e250c59d96ed965ffd
+SHA512:
+  metadata.gz: 4f136159a0b8814302c469e0fe0d99e075d83a78a9749ea1abf3395ffc2f48877a34ff81837af83c2c38cb8c95459a37a666c8d48960570f85f2e9ce7fbe0361
+  data.tar.gz: c6890c8bf08ea4852141a437da075885abe1706c75afa9da522f25cc871fc4238c6d22411a795851d74a8efbb06f1e68dfd31231b2130b54e906a2d465311851

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Wright
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/lib/todoist/comment.rb

@@ -0,0 +1,37 @@
+class Todoist
+  Comment = Struct.new(
+    :id,
+    :content,
+    :item_id,
+    :project_id,
+    :file_attachment,
+    :is_deleted,
+    :posted_at,
+    :posted_uid,
+    :reactions,
+    :uids_to_notify,
+    :jsw_ignored_keys,
+    keyword_init: true
+  ) do
+    include StructCleanup
+
+    def initialize(*arg_hashes)
+      args = arg_hashes.first
+      fields_to_date_time(args, %w[posted_at])
+      ignore_undefined_keys(args)
+      super
+    end
+
+    alias_method :task_id, :item_id
+
+    def file_attachment?
+      file_attachment.blank?
+    end
+
+    def deleted?
+      is_deleted.present?
+    end
+
+    alias_method :attachment?, :file_attachment?
+  end
+end

data/lib/todoist/current_time.rb

@@ -0,0 +1,13 @@
+class Todoist
+  # Todoist due dates are all interpreted in UTC, regardless of the host
+  # machine's local timezone, so "today"/"now" are pinned to UTC here.
+  class << self
+    def now
+      Time.now.utc
+    end
+
+    def today
+      now.to_date
+    end
+  end
+end

data/lib/todoist/date_parser.rb

@@ -0,0 +1,26 @@
+class Todoist
+  class DateParser
+    attr_reader :due_parts, :dates
+
+    def initialize(due_str)
+      due_str.downcase!
+      @due_parts = due_str.match(due_regex)
+      return if @due_parts.nil?
+      @dates = @due_parts[:dates].split(",").map(&:strip)
+    end
+
+    def parse
+    end
+
+    def due_regex
+      %r{^(?:ev(?:ery)? # string must start with ev or every
+        (?<bang>!)?) # optional bang
+        \s+(?<dates>.+?) # all valid strings must have some kind of date
+        (?:\s+(?:at\s+)? # the keyword at is optional in front of a time
+        (?<time>\d{1,2}(?::\d{1,2})?))? # a time is optional and pretty permissive by personal convention should be hh:mm
+        (?:\s+starting\s+(?<starting>.+?))? # optional starting date
+        (?:\s+ending\s+(?<ending>.+?))? # optional ending date
+        $}x
+    end
+  end
+end

data/lib/todoist/due.rb

@@ -0,0 +1,83 @@
+class Todoist
+  RECURRING_REGEX = /ev(?:ery)?\s+(\d+)\s+(minutes|hours|days|weeks|months|years)/i
+  HOURS_PER_UNIT = {"minutes" => 1 / 60.0, "hours" => 1.0, "days" => 24.0, "weeks" => 24.0 * 7, "months" => 24.0 * 30, "years" => 24.0 * 365.25}.freeze
+
+  Due = Struct.new(:date_obj, :date, :lang, :is_recurring, :string, :timezone, keyword_init: true) do
+    attr_accessor :orig_date_str
+
+    def initialize(*arg_hashes)
+      if arg_hashes.is_a?(Array)
+        arg_hash = arg_hashes.first
+      end
+      if arg_hash.nil?
+        super()
+        return
+      end
+      @orig_date_str = arg_hash&.dig("date").freeze
+      arg_hash[:date_obj] = if arg_hash&.dig("date").nil?
+        nil
+      elsif arg_hash&.dig("date")&.to_s&.upcase&.include?("T")
+        Time.parse(arg_hash["date"]).utc
+      else
+        Date.parse(arg_hash["date"])
+      end
+      super(arg_hash)
+    end
+
+    def blank?
+      date.blank? && string.blank?
+    end
+
+    def bump
+      if string.blank?
+        TodoistClient.logger.error { "You can only bump recurring tasks" }
+        return nil
+      end
+      mm = string.match(RECURRING_REGEX)
+      unless mm
+        TodoistClient.logger.error { "Cannot parse the string of this due obj: #{string}" }
+        return nil
+      end
+      hours = mm[1].to_i * HOURS_PER_UNIT.fetch(mm[2].downcase)
+      if date_obj.is_a?(Date) && hours % 24 == 0
+        days = (hours / 24).to_i
+        date_today = Todoist.today
+        if date_today + days > date_obj
+          self.date_obj = date_today + days
+          date_obj.to_s
+        end
+      else
+        bumped = time_at_next_qarter_hour + hours * 3600
+        if bumped > date_obj
+          self.date_obj = Time.utc(bumped.year, bumped.month, bumped.day, bumped.hour, bumped.min)
+          date_obj.strftime("%Y-%m-%dT%H:%M:%S")
+        end
+      end
+    end
+
+    def days_until
+      (Date.parse(date) - Todoist.today).to_i
+    end
+
+    def present?
+      !blank?
+    end
+
+    def recurring?
+      is_recurring.present?
+    end
+
+    def parse_due
+      regex = /^(?:ev(?:ery)?(?<bang>!)?)\s+(?<dates>.+?)(?:\s+(?:at\s+)?(?<time>\d{1,2}(?::\d{1,2})?))?(?:\s+starting\s+(?<starting>.+?))?(?:\s+ending\s+(?<ending>.+?))?$/i
+      date_parts = string.match(regex)
+      date_parts[:dates].split(/,\s/)
+    end
+
+    def time_at_next_qarter_hour(start_time = nil)
+      start_time ||= Todoist.now
+      minutes = ((start_time.min + 14) / 15) * 15
+      top_of_hour = Time.utc(start_time.year, start_time.month, start_time.day, start_time.hour, 0, 0)
+      top_of_hour + minutes * 60
+    end
+  end
+end

data/lib/todoist/file_attachment.rb

@@ -0,0 +1,5 @@
+class Todoist
+  FileAttachment = Struct.new(:file_name, :file_size, :file_type, :file_url, :resource_type, :upload_state,
+    :image, :image_height, :image_width, keyword_init: true) do
+  end
+end

data/lib/todoist/label.rb

@@ -0,0 +1,29 @@
+class Todoist
+  Label = Struct.new(
+    :name,
+    :id,
+    :color,
+    :is_deleted,
+    :is_favorite,
+    :order,
+    :jsw_ignored_keys,
+    keyword_init: true
+  ) do
+    include StructCleanup
+
+    def initialize(*arg_hashes)
+      args = arg_hashes.first
+      ignore_undefined_keys(args)
+      replace_keys(args, {item_order: :order})
+      super
+    end
+
+    def deleted?
+      is_deleted.present?
+    end
+
+    def favorite?
+      is_favorite.present?
+    end
+  end
+end

data/lib/todoist/project.rb

@@ -0,0 +1,103 @@
+class Todoist
+  Project =
+    Struct.new(
+      :id,
+      :name,
+      :root_name,
+      :description,
+      :p_num,
+      :access,
+      :can_assign_tasks,
+      :child_order,
+      :color,
+      :created_at,
+      :creator_uid,
+      :default_order,
+      :inbox_project,
+      :is_archived,
+      :is_collapsed,
+      :is_deleted,
+      :is_favorite,
+      :is_frozen,
+      :is_shared,
+      :parent_id,
+      :public_access,
+      :role,
+      :updated_at,
+      :view_style,
+      :jsw_ignored_keys,
+      keyword_init: true
+    ) do
+      include StructCleanup
+
+      def initialize(*arg_hashes)
+        args = arg_hashes.first
+        fields_to_date_time(args, %w[created_at updated_at])
+        ignore_undefined_keys(args)
+        get_root_name(args)
+        super
+      end
+
+      def get_root_name(args)
+        if (m = args["name"].match(/(?<root>.*?)\s*(?<num>\d)*\s*$/))
+          args[:root_name] = m[:root].downcase
+          args[:p_num] = [m[:num].to_i, 1].max
+        else
+          args[:root_name] = args["name"]
+          args[:p_num] = 1
+        end
+      end
+
+      def inspect(short_view: true)
+        if short_view
+          {name: name, id: id, root_name: root_name, p_num: p_num}
+        else
+          super()
+        end
+      end
+
+      alias_method :order, :child_order
+
+      def rules(td_client)
+        r = td_client.tasks.find { |t| t.project_id == id && t.content == "PROJECT RULES" }
+        return if r.nil?
+        begin
+          JSON.parse(r.description)
+        rescue
+          nil
+        end
+      end
+
+      def archived?
+        is_archived.present?
+      end
+
+      def collapsed
+        is_collapsed.present?
+      end
+
+      def deleted?
+        is_deleted.present?
+      end
+
+      def favorite?
+        is_favorite.present?
+      end
+
+      def frozen?
+        is_frozen.present?
+      end
+
+      def inbox?
+        inbox_project.present?
+      end
+
+      def shared?
+        is_shared.present?
+      end
+
+      def url
+        "https://todoist.com/showProject?id=#{id}"
+      end
+    end
+end

data/lib/todoist/section.rb

@@ -0,0 +1,16 @@
+class Todoist
+  Section = Struct.new(:name, :id, :project_id,
+    :added_at, :archived_at, :collapsed, :is_archived, :is_deleted, :section_order, :sync_id, :user_id,
+    keyword_init: true) do
+    def initialize(*arg_hashes)
+      arg_hashes.each do |args|
+        if args.key?("order")
+          args[:section_order] = args.delete("order")
+        end
+      end
+      super
+    end
+
+    alias_method :order, :section_order
+  end
+end

data/lib/todoist/struct_cleanup.rb

@@ -0,0 +1,42 @@
+class Todoist
+  module StructCleanup
+    def fields_to_date_time(args, dt_fields)
+      dt_fields.each do |fld|
+        if args[fld].present?
+          begin
+            text_value = args.delete(fld)
+            args[fld.to_sym] = Time.parse(text_value).utc
+          rescue ArgumentError
+            args[fld.to_sym] = text_value
+          end
+        end
+      end
+    end
+
+    def ignore_undefined_keys(args)
+      args[:jsw_ignored_keys] = []
+      args.keys.each do |k|
+        if !respond_to?(k)
+          args.delete(k)
+          args[:jsw_ignored_keys] << k
+        end
+      end
+    end
+
+    def replace_keys(args, replacements)
+      replacements.each do |old_key, new_key|
+        if args.key?(old_key)
+          args[new_key.to_sym] = args.delete(old_key)
+        elsif args.key?(old_key.to_s)
+          args[new_key.to_sym] = args.delete(old_key.to_s)
+        elsif args.key?(old_key.to_sym)
+          args[new_key.to_sym] = args.delete(old_key.to_sym)
+        end
+      end
+    end
+
+    def properties_to_desc
+      self.description = "```~~~begin_yaml~~~\n#{jsw_properties.to_yaml}~~~end_yaml~~~```"
+    end
+  end
+end

data/lib/todoist/sync.rb

@@ -0,0 +1,51 @@
+class Todoist
+  Sync = Struct.new(
+    :elapsed,
+    :resource_types,
+    :stats,
+    :sync_token,
+    :items,
+    :projects,
+    :labels,
+    :filters,
+    :collaborator_states,
+    :collaborators,
+    :completed_info,
+    :day_orders,
+    :day_orders_timestamp,
+    :due_exceptions,
+    :full_sync,
+    :incomplete_item_ids,
+    :incomplete_project_ids,
+    :live_notifications,
+    :live_notifications_last_read_id,
+    :locations,
+    :comments,
+    :project_notes,
+    :reminders,
+    :sections,
+    :temp_id_mapping,
+    :tooltips,
+    :user,
+    :user_plan_limits,
+    :user_settings,
+    :view_options,
+    keyword_init: true
+  ) do
+    def version
+      :v9
+    end
+
+    alias_method :tasks, :items
+
+    def insp
+      res = {}
+      members.each do |mbr|
+        val = send(mbr)
+        val = ":count: #{val.count}" if val.is_a?(Array)
+        res[mbr] = val
+      end
+      res
+    end
+  end
+end

data/lib/todoist/task.rb

@@ -0,0 +1,79 @@
+class Todoist
+  Task = Struct.new(
+    :id,
+    :project_name,
+    :project_id,
+    :content,
+    :added_at,
+    :added_by_uid,
+    :assigned_by_uid,
+    :checked,
+    :child_order,
+    :completed_at,
+    :day_order,
+    :deadline,
+    :description,
+    :due,
+    :duration,
+    :is_collapsed,
+    :is_deleted,
+    :labels,
+    :note_count,
+    :parent_id,
+    :priority,
+    :responsible_uid,
+    :section_id,
+    :updated_at,
+    :user_id,
+    :jsw_properties,
+    :jsw_ignored_keys,
+    keyword_init: true
+  ) do
+    include StructCleanup
+
+    def initialize(*arg_hashes)
+      args = arg_hashes.first
+      get_properties(args)
+      fields_to_date_time(args, %w[added_at updated_at])
+      ignore_undefined_keys(args)
+      due_to_struct(args)
+      super
+    end
+
+    def due_to_struct(args)
+      args["due"] = Due[args["due"]]
+    end
+
+    def to_h
+      self.due = due.to_h
+      super
+    end
+
+    def url
+      "https://todoist.com/showTask?id=#{id}"
+    end
+
+    def get_properties(args)
+      args[:jsw_properties] = {}
+      if (jsw_properties_match = args["description"].match(/(.*)```\s*~~~begin_yaml~~~\s*(.*)\s*~~~end_yaml~~~\s*```(.*)/m))
+        @desc = [jsw_properties_match[1], jsw_properties_match[3]]
+        args[:jsw_properties] = YAML.safe_load(jsw_properties_match[2])
+        if args[:jsw_properties].is_a?(Hash)
+          args[:jsw_properties].deep_symbolize_keys!
+        end
+      end
+    end
+
+    def properties_string(properties = nil)
+      properties ||= jsw_properties
+      <<~HEREDOC
+        #{@desc&.dig(0)}
+        ```
+        ~~~begin_yaml~~~
+        #{properties.to_yaml}~~~end_yaml~~~
+        ```
+        #{@desc&.dig(1)}
+      HEREDOC
+    end
+  end
+end

data/lib/todoist/utilities.rb

@@ -0,0 +1,63 @@
+class Todoist
+  class Utilities
+    mon_opts = (Date::MONTHNAMES + Date::ABBR_MONTHNAMES - [nil] + ["sept"]).map { |w| w.downcase.to_s }.join("|")
+    dow_opts = (Date::DAYNAMES + Date::ABBR_DAYNAMES - [nil]).map { |w| w.downcase.to_s }.join("|")
+    MON_FIRST_REGEX = /(?<mon>#{mon_opts})\s+(?<day>\d{1,2})(?:(?:st\b)|(?:nd\b)|(?:rd\b)|(?:th\b))?/
+    MON_LAST_REGEX = /(?<day>\d{1,2})(?:(?:st\b)|(?:nd\b)|(?:rd\b)|(?:th\b))?\s+(?<mon>#{mon_opts})/
+    DOW_REGEX = /(?<dow>(?:#{dow_opts})s?)/
+    DUE_REGEX = %r{
+        ^ # start of line
+        \s*\bev(?:ery)? # ev or every
+        (?<bang>!)? # possible bang in group bang
+        \s+
+        (?<dates>.*?) # dates in group dates
+        \s*
+        (?:\bat)?\s* # optional keyword at
+        (?<time>\b\d\d:\d\d\b)?\s* # optional time in group time
+        (?:(?:\bstarting)\s+(?<start_date>.*?))?\s* # optional starting keyword followed by starting date in group starting
+        (?:(?:\bending)\s+(?<end_date>.*?))?\s* # optional ending keyword followed by ending date in group ending
+        $ # end of line
+        }xi
+    ORDINAL_REGEX = /\b(\d+) # first capture group which is a string of digits
+      ( # start of 2nd capture group
+      (?:st\b)|(?:nd\b)|(?:rd\b)|(?:th\b) # a series of anonymous capture groups of two letters
+                                          # any of these letter pairs will match
+    )/x
+
+    class << self
+      def normalize_due_string(orig_due_string)
+        orig_due_string = orig_due_string.downcase
+        mm = orig_due_string.match(DUE_REGEX)
+        if mm.nil?
+          raise ArgumentError, "Due String not recognized: #{orig_due_string}"
+        end
+        if mm[:dates]
+          dates = mm[:dates].split(/\s*,\s*/).map(&:downcase)
+          new_dates = []
+          dates.each do |d|
+            if (dm = d.match(/(?<num>\d+)\s+weeks?/))
+              if dm[:num].to_i <= 7
+                d = "#{dm[:num].to_i * 7} days"
+              end
+            elsif (dm = d.match(/(?<mon>\d{1,2})\/(?<day>\d{1,2})/))
+              d = "#{dm[:day]} #{Date::ABBR_MONTHNAMES[dm[:mon].to_i].downcase}"
+            elsif (dm = d.match(MON_FIRST_REGEX) || d.match(MON_LAST_REGEX))
+              d = "#{dm[:day]} #{dm[:mon][0..2]}"
+            elsif (dm = d.match(DOW_REGEX))
+              d = d.gsub(dm[:dow], dm[:dow][0..2])
+            end
+            new_dates << d
+          end
+          new_dates = new_dates.join(", ")
+          new_dates.gsub!(ORDINAL_REGEX, '\1')
+        end
+        new_due = "ev#{mm[:bang]} #{new_dates}"
+        new_due += " at #{mm[:time]}" if mm[:time]
+        new_due += " ending #{mm[:end_date]}" if mm[:end_date]
+        if new_due != orig_due_string
+          new_due.strip
+        end
+      end
+    end
+  end
+end

data/lib/todoist_client/version.rb

@@ -0,0 +1,3 @@
+class TodoistClient
+  VERSION = "0.1.0"
+end

data/lib/todoist_client.rb

@@ -0,0 +1,487 @@
+require "conveniences"
+require "json"
+require "yaml"
+require "logger"
+require "securerandom"
+require "date"
+require "time"
+require "rest_requestor"
+
+require_relative "todoist_client/version"
+require_relative "todoist/current_time"
+require_relative "todoist/struct_cleanup"
+require_relative "todoist/due"
+require_relative "todoist/file_attachment"
+require_relative "todoist/comment"
+require_relative "todoist/label"
+require_relative "todoist/section"
+require_relative "todoist/project"
+require_relative "todoist/task"
+require_relative "todoist/sync"
+require_relative "todoist/date_parser"
+require_relative "todoist/utilities"
+
+class TodoistClient
+  DAYS = %i[sun mon tue wed thu fri sat].freeze
+  BASE = {
+    rest: {v1: "https://api.todoist.com/api/v1/", legacy: "https://api.todoist.com/rest/v2/"},
+    sync: {v1: "https://api.todoist.com/api/v1/sync", legacy: "https://api.todoist.com/sync/v9/sync"}
+  }.freeze
+  AUTO_SCHED_LABELS = ["auto_schedule"]
+
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= Logger.new($stdout)
+    end
+  end
+
+  attr_accessor :jsw_skip_pry, :req, :paged_reqs
+  attr_reader :responses, :request_history, :stats_paginated
+
+  def initialize(bearer_token)
+    @auth = "Bearer #{bearer_token}"
+    @responses = []
+    @req = RestRequestor.new
+    @paged_reqs = []
+    @request_history = []
+    @stats_paginated = []
+  end
+
+  def api_compare(path, verb = :get, q_params: {}, j_params: {}, retries: 0, **kwparams)
+    r_legacy = api_rest_request(path, verb, q_params:, j_params:, retries:, version: :legacy, **kwparams)
+    r_v1 = api_rest_request(path, verb, q_params:, j_params:, retries:, version: :v1, **kwparams)
+    {new: r_v1, legacy: r_legacy}
+  end
+
+  def paginated_request(path, verb = :get, q_params: {}, j_params: {}, retries: 0, **kwparams)
+    q_params[:limit] ||= 200
+    results = []
+    loop do
+      req = api_rest_request(path, verb, q_params:, j_params:, retries:, version: :v1, **kwparams)
+      q_params[:cursor] = req["next_cursor"]
+      @paged_reqs << req
+      puts "Path: #{path}, (#{results.count} + #{req["results"].count}), Next Cursor: [#{req["next_cursor"]}]"
+      results += req["results"]
+      @stats_paginated << {path:, count: results.count, cursor: req["next_cursor"], last_id: results.last&.dig("id")}
+      break if req["next_cursor"].blank?
+    end
+    results
+  end
+
+  def api_rest_request(path, verb = :get, q_params: {}, j_params: {}, retries: 0, version: :v1, **kwparams)
+    q_params.each { |k, v| q_params.delete(k) if v.blank? }
+    if ["get", :get].include?(verb) && q_params["limit"].nil? && q_params[:limit].nil?
+      q_params[:limit] = 200
+    end
+    req_path = "#{BASE[:rest][version]}#{path}"
+    @request_history << {path: req_path, verb:, q_params:, j_params: j_params.merge!(kwparams)}
+    resp = req.request(req_path, verb, q_params:, j_params: j_params.merge!(kwparams), auth: @auth)
+    responses << resp
+    resp
+  end
+
+  def add_due_date(item_id, project_id)
+    proj_root_name = projects.find { |p| p.id == project_id }&.root_name
+    rul = rules.find { |r| r[:name] == proj_root_name }
+    due_str = if rul
+      next_t_date = (next_task_date(rul) || Todoist.now.hour < 16) ? Todoist.today : Todoist.today + 1
+      if rul[:repeat_str].present?
+        "#{rul[:repeat_str]} starting #{next_t_date}"
+      else
+        next_t_date
+      end
+    else
+      (Todoist.now.hour < 16) ? Todoist.today : Todoist.today + 1
+    end
+    update_task(item_id, due_string: due_str, labels: AUTO_SCHED_LABELS)
+  end
+
+  def add_comment(task_id, content)
+    api_rest_request(:comments, :post, j_params: {task_id:, content:})
+  end
+
+  def close_task(idd = nil, id: nil)
+    id ||= idd
+    raise ArgumentError, "You must supply id as an unamed argument or as a named argument" if id.nil?
+    api_rest_request("tasks/#{id}/close", :post)
+    true
+  rescue RestRequestor::StandardError
+    false
+  end
+
+  def comments(project_id: nil, task_id: nil)
+    raise ArgumentError, "project_id or task_id must be supplied" if project_id.nil? && task_id.nil?
+    path = if project_id.present?
+      "comments?project_id=#{project_id}"
+    else
+      "comments?task_id=#{task_id}"
+    end
+    api_request(path).map { |c| build_comment(c) }
+  end
+
+  def create(item, **kwparams)
+    path = item.to_s.pluralize
+    required = []
+    case item
+    when :task
+      required += %i[content]
+    when :section
+      required += %i[name project_id]
+    when :comment
+      required += %i[task_id content]
+      kwparams[:task_id] ||= kwparams.delete(:id)
+    when :project_comment
+      required += %i[project_id content]
+      kwparams[:project_id_id] ||= kwparams.delete(:id)
+      path = "comments"
+      rtn_obj = Todoist::Comment
+    when :label, :project
+      required += %i[name]
+    else
+      raise ArgumentError, "Unable to create item for #{item}"
+    end
+    unless (required - kwparams.keys).empty?
+      raise ArgumentError, "You must supply #{required} to create #{item.to_s.pluralize}"
+    end
+    api_rtn = api_rest_request(path, :post, j_params: kwparams)
+    rtn_obj = (rtn_obj || "Todoist::#{item.to_s.camelcase}".constantize)[api_rtn]
+    case item
+    when :task
+      (@tasks || []) << rtn_obj
+    when :project
+      (@projects || []) << rtn_obj
+    end
+    rtn_obj
+  end
+
+  def delete_task(idd = nil, id: nil)
+    id ||= idd
+    raise ArgumentError, "You must supply id as an unamed argument or as a named argument" if id.nil?
+    api_rest_request("tasks/#{id}", :delete)
+  end
+
+  def edit_rules
+    dflts = {days: [0, 1, 2, 3, 4, 5, 6], look_ahead: 35, repeat_str: "every 35 days", global?: false, repeater?: false}
+    rules.each do |rule|
+      upd = true
+      rule[:obj] = dflts.merge(rule[:obj])
+      rule[:obj].delete(:repeater?)
+      if upd
+        update_task(rule[:t_id], description: rule[:obj].to_json)
+      end
+    end
+  end
+
+  def fix_date(tsk)
+    mm = tsk.due.date.match(/^(.*T.*)T.*/)
+    if mm
+      update_task(tsk.id, due_date: mm[1], due_string: tsk.due.string)
+    end
+  end
+
+  def labels(force: false)
+    if !force && defined?(@labels)
+      @labels
+    else
+      @labels = paginated_request("labels").map { |l| Todoist::Label[l] }
+    end
+  end
+
+  def load_sample_tasks(filename = nil)
+    filename ||= "data/sample_tasks.yml"
+    if @loaded&.dig(filename)
+      return @loaded[filename]
+    end
+    @loaded ||= {}
+    permitted_classes = [Todoist::Task, Todoist::Due, Symbol, Time, Date]
+    @loaded[filename] ||= YAML.load_file(filename, permitted_classes:, aliases: true)
+  end
+
+  def next_project_id(root_name, create_proj: true, max_tasks: 299)
+    root_name = root_name.to_s.downcase.tr("_", " ")
+    if root_name == "inbox"
+      return projects.find { |p| p.root_name == "inbox" }&.id
+    end
+    np_id = project_tasks.find { |pt| pt[:root_name] == root_name && pt[:tasks] < max_tasks }&.dig(:id)
+    return np_id if np_id.present? || !create_proj
+
+    next_proj_num = projects.select { |p| p[:root_name] == root_name }.map { |sp| sp.p_num }.max + 1
+    root_p = projects.find { |pt| pt[:root_name] == root_name && pt[:p_num] == 1 }
+    np = if root_p
+      create(:project, name: "#{root_name.titleize} #{next_proj_num}", color: root_p.color)
+    else
+      create(:project, name: "#{root_name.titleize} #{next_proj_num}")
+    end
+    projects << np
+    np.id
+  end
+
+  def next_task_date(options = {})
+    if options[:due_str].present?
+      if options[:due_str] == "today"
+        if Todoist.now.hour > 15
+          return (Todoist.today + 1).strftime("%Y-%m-%d")
+        else
+          return Todoist.today.strftime("%Y-%m-%d")
+        end
+      else
+        return options[:due_str]
+      end
+    end
+    t_per_day = tasks_per_day(options.slice(:days_out, :days, :root_name))
+    if options[:min_tasks_per_day].present?
+      next_date = t_per_day.find { |t| t[:tasks] < options[:min_tasks_per_day] }&.dig(:date)
+      return next_date if next_date.present?
+    end
+    min_tasks = t_per_day.map { |tpd| tpd[:tasks] }.min
+    if options[:max_tasks_per_day].present? && min_tasks >= options[:max_tasks_per_day]
+      return nil
+    end
+    t_per_day.find { |t| t[:tasks] == min_tasks }&.dig(:date)
+  end
+
+  def no_due_date(status = nil)
+    status ||= self.status
+    status[:items].select { |i| i.dig("due", "date").nil? && i.parent_id.nil? }
+  end
+
+  def projects(force: false)
+    if !force && defined?(@projects)
+      @projects
+    else
+      @projects = paginated_request("projects").map { |p| Todoist::Project[p] }
+    end
+  end
+
+  def project_id(search_name)
+    search_name = search_name.to_s.downcase
+    proj = projects.find { |p| p.name.downcase == search_name } || projects.find { |p| p.root_name == search_name }
+    proj&.id
+  end
+
+  def project_name(proj_id, force: false)
+    proj_id = proj_id.to_s
+    projects(force:).find { |p| p.id == proj_id }&.dig(:name)
+  end
+
+  def project_root_name(proj_id, force: false)
+    proj_id = proj_id.to_s
+    projects(force:).find { |p| p.id == proj_id }&.dig(:name_parts, 0)
+  end
+
+  def project_rules(project_id: nil, root_name: nil)
+    if project_id.nil?
+      raise ArgumentError, "You must provide project_id OR root_name" if root_name.nil?
+      project_id = projects.find { |p| p.root_name == root_name }&.id
+    end
+    rul = tasks.find { |t| t.labels.include?("project_rules") && t.project_id == project_id }
+    return nil if rul.nil?
+    JSON.parse(rul.description)
+  end
+
+  def project_tasks
+    projects.map do |proj|
+      {root_name: proj.root_name, p_num: proj.p_num, id: proj.id, tasks: tasks(:all).count { |tsk| tsk.project_id == proj.id }}
+    end
+  end
+
+  def recurring_tasks(include_annual: false)
+    tasks.select { |t| t.due.is_recurring }
+  end
+
+  def reopen_task(idd = nil, id: nil)
+    id ||= idd
+    raise ArgumentError, "You must supply id as an unamed argument or as a named argument" if id.nil?
+    api_rest_request("tasks/#{id}/reopen", :post)
+  end
+
+  def rules
+    tasks.select { |t| t.labels.include?("project_rules") }.map do |rul|
+      JSON.parse(rul.description).deep_symbolize_keys.merge({t_id: rul.id, t_name: rul.content})
+    end
+  end
+
+  def sections(project_id = nil, force: false)
+    if force || !defined?(@sections)
+      @sections = paginated_request("sections").map { |s| Todoist::Section[s] }
+    end
+    if project_id.nil?
+      @sections
+    else
+      @sections.select { |s| s.project_id == project_id.to_s }
+    end
+  end
+
+  def single_task(idd = nil, id: nil, raw: false)
+    id ||= idd
+    raise ArgumentError, "You must supply id as an unamed argument or as a named argument" if id.nil?
+    build_task(api_rest_request("tasks/#{id}"))
+  end
+
+  def task_comments(task_id, raw: false)
+    resp = api_rest_request(:comments, q_params: {task_id:})
+    if raw
+      resp
+    else
+      resp["results"].map { |r| Todoist::Comment[r] }
+    end
+  end
+
+  def task_from_link(link, raw: false)
+    resp = api_rest_request("tasks/#{link.split("-")[-1]}")
+    return resp if raw
+    build_task(resp)
+  end
+
+  def tasks(incl = :dated, subtasks: nil, force: false)
+    tsks = if !force && defined?(@tasks)
+      case incl
+      when :dated then @tasks.select { |t| !t.due.date.nil? }
+      when :all then @tasks
+      when :undated then @tasks.select { |t| t.due.date.nil? }
+      end
+    else
+      @tasks = paginated_request("tasks/").map { |t| build_task(t) }
+      tasks(incl)
+    end
+    case subtasks
+    when nil then tsks
+    when true then tsks.select { |t| t.parent_id.present? }
+    when false then tsks.select { |t| t.parent_id.blank? }
+    end
+  end
+
+  def tasks_by(criteria, value, include_subtasks: false)
+    case criteria.to_s.downcase
+    when "project"
+      project = projects.find { |p| p["name"].downcase == value.to_s.downcase }
+      return if project.nil?
+      selected_tasks = tasks(:dated).select { |t| t["project_id"] == project["id"] }
+    when "root_name"
+      proj_ids = projects.select { |p| p.root_name == value.to_s.downcase }.map { |sp| sp.id }
+      selected_tasks = tasks(:dated).select { |t| proj_ids.include?(t["project_id"]) }
+    when "project_id"
+      selected_tasks = tasks(:dated).select { |t| t["project_id"] == value.to_s }
+    else
+      return
+    end
+    selected_tasks.select! { |t| t["parent_id"].nil? } unless include_subtasks
+    selected_tasks
+  end
+
+  def tasks_per_day(options = {})
+    days_out = options[:days_out] || 35
+    days = options[:days] || [*0..6]
+    cur_tasks = if options[:root_name].present?
+      tasks_by(:root_name, options[:root_name])
+    else
+      tasks
+    end
+    tasks_per_day = (1..days_out).map { |num| {date: (Date.today + num).to_s, tasks: [], wday: (Date.today + num).wday} }
+    sorted = cur_tasks&.select { |t| t.due.days_until.between?(1, days_out + 1) }
+      &.sort_by { |t| t.due.date }
+      &.group_by { |t| t.due.date_obj.to_date.to_s }
+    tasks_per_day.each { |task_d| task_d[:tasks] += sorted[task_d[:date]] || [] }
+    tasks_per_day.map! { |t| {date: t[:date], tasks: t[:tasks].count, wday: t[:wday]} }
+    tasks_per_day.select { |t| days.include?(t[:wday]) }
+  end
+
+  def test_task(content: nil, due_string: "today")
+    content = "#{content || "Test Task"} - #{Date.today.strftime("%A")}"
+    create(:task, content:, due_string:)
+  end
+
+  def update_comment(comment_id, content)
+    api_rest_request("comments/#{comment_id}", :post, j_params: {content:})
+  end
+
+  def update_task(task_id, **params)
+    raise ArgumentError, "You must provide at least one key / value pair to update a task" if params.empty?
+    api_rest_request("tasks/#{task_id}", :post, j_params: params)
+  end
+
+  # SYNC METHODS
+
+  def api_sync_request(path = nil, verb = :post, f_hash: {}, commands: [], retries: 0, version: :v1)
+    f_hash[:commands] = commands.to_json if commands.present?
+    req.request("#{BASE[:sync][version]}#{path}".freeze, verb, f_hash:, auth: @auth)
+  end
+
+  def delete_duplicates(content, save_ids: [], incl: :all)
+    dups = tasks(incl).select { |t| !save_ids.include?(t.id) && t.content == content }.sort_by { |t| t.added_at }
+    commands = dups[1..].map { |d| {type: :item_delete, uuid: SecureRandom.uuid, args: {id: d.id}} }
+    responses = []
+    while commands.any?
+      batch = commands.shift(100)
+      responses << api_sync_request(commands: batch)
+    end
+    responses
+  end
+
+  def master
+    sync.items.select { |i| i.content.match?(/Master\s*$/) }
+  end
+
+  def move_item(item_id, **kwargs)
+    api_sync_request(commands: [{type: "item_move", uuid: SecureRandom.uuid, args: {id: item_id}.merge(kwargs)}])
+  end
+
+  def multi_move(items, **kwargs)
+    resp = []
+    while items.any?
+      commands = []
+      99.times do
+        commands << {type: "item_move", uuid: SecureRandom.uuid, args: {id: items.pop}.merge(kwargs)}
+      end
+      resp << api_sync_request(commands:)
+    end
+  end
+
+  # The Sync API has no direct way to unset a section; moving the item out of
+  # its project and back in is what clears the section assignment.
+  def remove_section(item, holding_project_id:)
+    api_sync_request(commands: [
+      {type: "item_move", uuid: SecureRandom.uuid, args: {id: item.id, project_id: holding_project_id}},
+      {type: "item_move", uuid: SecureRandom.uuid, args: {id: item.id, project_id: item.project_id}}
+    ])
+  end
+
+  def sync(sync_token = "*", force: false, resource_types: nil, version: :v1)
+    resource_types = if resource_types.nil?
+      %i[filters labels locations projects sync_token stats items comments sections]
+    else
+      [resource_types].flatten
+    end
+    if resource_types.include?(:comments)
+      resource_types.delete(:comments)
+      resource_types << :notes
+    end
+    if !force && defined?(@sync)
+      @sync
+    else
+      api_sync_request(f_hash: {sync_token:, resource_types: resource_types.to_json}, version:)
+    end
+  end
+
+  def debug
+    binding.pry if !@jsw_skip_pry # standard:disable Lint/Debugger
+  end
+
+  # p_rivate
+
+  def build_task(tsk)
+    tsk[:project_name] = projects.find { |p| p.id == tsk["project_id"] }&.name
+    Todoist::Task[tsk]
+  end
+
+  def build_struct(struct, hashed_vals)
+    struct[hashed_vals]
+  end
+
+  def build_comment(cmt)
+    cmt[:file_attachment] = Todoist::FileAttachment[cmt.delete("file_attachment") || cmt.delete("attachment") || {}]
+    Todoist::Comment[cmt]
+  end
+end

metadata

@@ -0,0 +1,155 @@
+--- !ruby/object:Gem::Specification
+name: todoist_rest_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Scott Wright
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: conveniences
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rest_requestor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: Wraps the Todoist REST v1 and Sync v9 APIs with typed domain objects
+  for tasks, projects, labels, sections, and comments, plus scheduling helpers for
+  spreading tasks across days and numbered projects.
+email:
+- scott@wrightzone.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/todoist/comment.rb
+- lib/todoist/current_time.rb
+- lib/todoist/date_parser.rb
+- lib/todoist/due.rb
+- lib/todoist/file_attachment.rb
+- lib/todoist/label.rb
+- lib/todoist/project.rb
+- lib/todoist/section.rb
+- lib/todoist/struct_cleanup.rb
+- lib/todoist/sync.rb
+- lib/todoist/task.rb
+- lib/todoist/utilities.rb
+- lib/todoist_client.rb
+- lib/todoist_client/version.rb
+homepage: https://codeberg.org/jswright61/todoist_client
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: A Ruby client for the Todoist API
+test_files: []