calendav 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6bae509ffc0254b00db9e4380a76278770a0868093ff69b597b6b10fcf9ecd01
-  data.tar.gz: 26cfe5ccbc19dba770cf2d255cbb36bc3529039903af8d28281536f70cb55c49
+  metadata.gz: 5f622fc58cda7b2c94bf7c6eff0056db4532e281bfd1e556a43f16ba8edac222
+  data.tar.gz: 075b5acb58221171aec66d8e9d0234410fa3f30cd0c790776ca0f023187f0d27
 SHA512:
-  metadata.gz: 56fd5c731ad0d4b05d29a68df6624bad4809a6a146806c8190ba765b233e39598572711ff6f5f61a59df09a8d919090b45641bfbc2214a1ad746f4a7f5bf8662
-  data.tar.gz: fa897448f63e9c5a04f8c97acebb950d0213fbc8aa10eb8d4069aaaafbe9849148dafe526de9c78a6d947c4a43eaaa78260665dfd05d66b429c21d5e1caf5a7e
+  metadata.gz: 596ecccf27b7cd0aeb697b4863f3c10c79e9ec8aaf2ca66786e2f31a94e5cf865a5835a8942a4c0189f7bfe040f5cde540ee7f10a09e0ec3cb693ae152923d09
+  data.tar.gz: 0ff81da9e901dfe16081a31a4df72319a6462ef939aa4aa83ebcb74792684e9b26b9999430159300192816e9ce9fdd31edbf04f57c6b0b28aa0cd85e9d9fe726

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## Unreleased
 
+## 0.5.0 - 2025-08-02
+
+* Support for todos (Josh Huckabee #8, #9)
+* Improved documentation for development/testing environments (Josh Huckabee #7)
+* Support for expanded recurring events (Sayooj Surendran #12)
+* Support for OAuth authentication header (Ilya Nikitenkov #13)
+* Updated tested Ruby versions to 3.1-3.4 (2.7 and 3.0 are no longer officially supported).
+
+## 0.4.0 - 2023-02-27
+
+* **Breaking**: calls to create/update events return event objects that only have a URL and etag populated (so: no calendar data), or nil if the request failed due to an etag precondition. This is instead of returning true on success or false on failure.
+* Removed test files from the gem/gemspec.
+* Increased nuance of error handler, raising a RedirectError (with location method) if the CalDAV server returns a redirect status.
+
 ## 0.3.0 - 2022-03-14
 
 * Add location to event wrapper.

data/README.md

@@ -23,7 +23,7 @@ credentials = Calendav::Credentials::Standard.new(
   host: "https://www.example.com/caldav",
   username: "example",
   password: "secret",
-  authentication: :basic_auth # or :bearer_token
+  authentication: :basic_auth # :bearer_token and :oauth also supported
 )
 ```
 
@@ -100,6 +100,16 @@ end
 
 The returned events have a unique URL (just like calendars), an `etag` (which changes when the event changes), and `calendar_data`, which is stored in the [iCalendar](https://datatracker.ietf.org/doc/html/rfc5545) format. The event objects returned currently parse the summary out of the calendar data, but nothing else - further attributes may be made visible, but for full control it's recommended you use the [icalendar](https://github.com/icalendar/icalendar) gem.
 
+To get recurring events, you can use the optional `expand_recurring_events` argument.
+
+```ruby
+events = client.events.list(
+  calendar_url, from: Time.new(2021, 1, 1), to: Time.new(2022, 1, 1),
+  expand_recurring_events: true
+)
+```
+The recurrent events will be present in the `calendar_data`.
+
 If you have an event's URL, you can fetch the details of just that event directly:
 
 ```ruby
@@ -121,7 +131,8 @@ end
 ics.publish
 
 identifier = "#{SecureRandom.uuid}.ics"
-event_url = client.events.create(calendar.url, identifier, ics.to_ical)
+# The returned event has just the URL and the etag, no calendar data:
+event_scaffold = client.events.create(calendar.url, identifier, ics.to_ical)
 ```
 
 *Please note*: some providers (definitely Google, possibly others) will not keep your supplied event identifier, but generate a new one. So, if you need an ongoing reference to the event, save the returned URL (rather than combining the calendar URL and your identifier).
@@ -129,17 +140,17 @@ event_url = client.events.create(calendar.url, identifier, ics.to_ical)
 Updating events is done in a similar manner - with the event's URL and the updated iCalendar content:
 
 ```ruby
-client.events.update(event_url, ics.to_ical)
+event_scaffold = client.events.update(event_url, ics.to_ical)
 ```
 
-To ensure you're only changing a known version of an event, it's recommended you use that version's etag as a precondition check (the update call will return false if the event on the server has a different etag value):
+To ensure you're only changing a known version of an event, it's recommended you use that version's etag as a precondition check (the update call will return nil if the event on the server has a different etag value):
 
 ```ruby
-event = client.events.find(event_url)
+event = client.events.find(event_scaffold.url)
 
 # figure out the changes you want to make, generate the new ical data, and then:
 
-client.events.update(event_url, modified_ical, etag: event.etag)
+client.events.update(event_scaffold.url, modified_ical, etag: event.etag)
 ```
 
 Deletion of events is done via the event's URL as well - some providers (including Apple) support the etag precondition check for this, but others (including Google) do not. In the latter situation, the deletion will happen regardless of the server event's etag value.
@@ -150,6 +161,55 @@ client.events.delete(event_url)
 client.events.delete(event_url, etag: event.etag)
 ```
 
+### Todos
+
+You can also use a calendar's URL to retrieve its todos.
+
+```ruby
+todos = client.todos.list(calendar_url)
+todos.each do |todo|
+  puts todo.url
+  puts todo.summary
+  puts todo.status
+  puts todo.due
+end
+```
+
+Just like events, returned todos have a unique URL, an `etag` (which changes when the todo changes), and `calendar_data`. The todo objects returned currently parse the summary, status, and due date out of the calendar data.
+
+If you have a todo's URL, you can fetch the details of just that todo directly:
+
+```ruby
+todo = client.todos.find(todo_url)
+```
+
+Creating todos, just like creating events, requires a unique identifier. You will also need to generate the iCalendar data - again, the [icalendar](https://github.com/icalendar/icalendar) gem is very helpful for this.
+
+```ruby
+require "securerandom"
+require "icalendar"
+
+ics = Icalendar::Calendar.new
+ics.todo do |todo|
+# ...
+end
+ics.publish
+
+identifier = "#{SecureRandom.uuid}.ics"
+# The returned todo has just the URL and the etag, no calendar data:
+todo_scaffold = client.todos.create(calendar.url, identifier, ics.to_ical)
+```
+
+Updating and deleting todos is similar to updating events:
+
+```ruby
+# Update the todo
+client.todos.update(todo_url, ics.to_ical)
+
+# Delete the todo
+client.todos.delete(todo_url)
+```
+
 ### Synchronising
 
 If you are maintaining your own copy/history of events from a CalDAV server, then it's highly recommended you take advantage of the WebDAV-Sync protocol (should the calendar provider support it). Using Calendav, the suggested approach is:
@@ -197,7 +257,7 @@ While a lot of the core CalDAV functionality is covered and this gem is useful a
 * Further iCalendar parsing for Event objects.
 * Automated tests against FastMail and possibly other providers (Apple and Google are already covered).
 * Locking/unlocking of events as per the WebCAL RFC.
-* Support for VTODO, VJOURNAL, VFREEBUSY and any other components beyond VEVENT.
+* Support for VJOURNAL, VFREEBUSY and any other components beyond VEVENT.
 
 ## Installation
 
@@ -231,11 +291,21 @@ The work done in previous Ruby CalDAV clients [RubyCaldav](https://github.com/di
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies and configure the required credentials. This will copy the `.env.example` file to a `.env` file. Make sure to configure the `.env` file with your own Apple and Google credentials.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ## Tests
 
-The test suite currently only runs against Google and Apple accounts I've created especially for this purpose - and the credentials are not public. I realise this makes contributions more difficult, and I'm open to finding better ways to handle this. I did look into running a CalDAV server within the test suite, but couldn't find anything small and easy enough for that purpose. But also: testing against common CalDAV servers does help to ensure this gem is truly useful (and has knowledge of their idiosyncrasies).
+The test suite depends on a locally running instance of a CalDAV server to work properly. We prefer [Radicale](https://radicale.org/v3.html) for this. You can run it locally with Docker and the provided configuration in `spec/data/radicale` with the following command:
+
+    docker run -v $PWD/spec/data/radicale:/var/radicale \
+               --name radicale \
+               --publish 8000:8000 \
+               --detach \
+               xlrl/radicale
+
+With the CalDAV server running, you can now run `rake spec` to run the tests.
 
 ## Contributing
 

data/lib/calendav/calendar.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "./contextual_url"
-require_relative "./parsers/calendar_xml"
+require_relative "contextual_url"
+require_relative "parsers/calendar_xml"
 
 module Calendav
   class Calendar

data/lib/calendav/client.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require_relative "./contextual_url"
-require_relative "./endpoint"
-require_relative "./clients/calendars_client"
-require_relative "./clients/events_client"
-require_relative "./requests/current_user_principal"
+require_relative "contextual_url"
+require_relative "endpoint"
+require_relative "clients/calendars_client"
+require_relative "clients/events_client"
+require_relative "clients/todos_client"
+require_relative "requests/current_user_principal"
 
 module Calendav
   class Client
@@ -21,6 +22,10 @@ module Calendav
       @events = Clients::EventsClient.new(self, endpoint, credentials)
     end
 
+    def todos
+      @todos = Clients::TodosClient.new(self, endpoint, credentials)
+    end
+
     def principal_url
       @principal_url ||= begin
         request = Requests::CurrentUserPrincipal.call

data/lib/calendav/clients/calendars_client.rb

@@ -82,7 +82,7 @@ module Calendav
         )
       end
 
-      def update(url, attributes)
+      def update(url, attributes) # rubocop:disable Naming/PredicateMethod
         request = Requests::UpdateCalendar.call(attributes)
         endpoint
           .proppatch(request.to_xml, url: url)

data/lib/calendav/clients/events_client.rb

@@ -17,7 +17,10 @@ module Calendav
         event_url = merged_url(calendar_url, event_identifier)
         result = endpoint.put(ics, url: event_url, content_type: :ics)
 
-        result.headers["Location"] || event_url
+        Event.new(
+          url: result.headers["Location"] || event_url,
+          etag: result.headers["ETag"]
+        )
       end
 
       def delete(event_url, etag: nil)
@@ -36,8 +39,10 @@ module Calendav
         )
       end
 
-      def list(calendar_url, from: nil, to: nil)
-        request = Requests::ListEvents.call(from: from, to: to)
+      def list(calendar_url, from: nil, to: nil, expand_recurring_events: false)
+        request = Requests::ListEvents.call(
+          from: from, to: to, expand_recurring_events: expand_recurring_events
+        )
 
         endpoint
           .report(request.to_xml, url: calendar_url, depth: 1)
@@ -46,13 +51,16 @@ module Calendav
       end
 
       def update(event_url, ics, etag: nil)
-        endpoint.put(
+        result = endpoint.put(
           ics, url: event_url, content_type: :ics, etag: etag
         )
 
-        true
+        Event.new(
+          url: event_url,
+          etag: result.headers["ETag"]
+        )
       rescue PreconditionError
-        false
+        nil
       end
 
       private

data/lib/calendav/clients/todos_client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../todo"
+require_relative "../requests/list_todos"
+
+module Calendav
+  module Clients
+    class TodosClient
+      def initialize(client, endpoint, credentials)
+        @client = client
+        @endpoint = endpoint
+        @credentials = credentials
+      end
+
+      def create(calendar_url, todo_identifier, ics)
+        todo_url = merged_url(calendar_url, todo_identifier)
+        result = endpoint.put(ics, url: todo_url, content_type: :ics)
+
+        Todo.new(
+          url: result.headers["Location"] || todo_url,
+          etag: result.headers["ETag"]
+        )
+      end
+
+      def delete(todo_url, etag: nil)
+        endpoint.delete(url: todo_url, etag: etag)
+      rescue PreconditionError
+        false
+      end
+
+      def find(todo_url)
+        response = endpoint.get(url: todo_url)
+
+        Todo.new(
+          url: todo_url,
+          calendar_data: response.body.to_s,
+          etag: response.headers["ETag"]
+        )
+      end
+
+      def list(calendar_url)
+        request = Requests::ListTodos.call
+
+        endpoint
+          .report(request.to_xml, url: calendar_url, depth: 1)
+          .reject { |node| node.xpath(".//caldav:calendar-data").text.empty? }
+          .collect { |node| Todo.from_xml(calendar_url, node) }
+      end
+
+      def update(todo_url, ics, etag: nil)
+        result = endpoint.put(
+          ics, url: todo_url, content_type: :ics, etag: etag
+        )
+
+        Todo.new(
+          url: todo_url,
+          etag: result.headers["ETag"]
+        )
+      rescue PreconditionError
+        nil
+      end
+
+      private
+
+      attr_reader :client, :endpoint, :credentials
+
+      def merged_url(calendar_url, todo_identifier)
+        "#{calendar_url.delete_suffix('/')}/#{todo_identifier}"
+      end
+    end
+  end
+end

data/lib/calendav/credentials/apple.rb

@@ -3,7 +3,7 @@
 require "http"
 require "uri"
 
-require_relative "./standard"
+require_relative "standard"
 
 module Calendav
   module Credentials

data/lib/calendav/credentials/fastmail.rb

@@ -3,7 +3,7 @@
 require "http"
 require "uri"
 
-require_relative "./standard"
+require_relative "standard"
 
 module Calendav
   module Credentials

data/lib/calendav/credentials/google.rb

@@ -3,7 +3,7 @@
 require "http"
 require "uri"
 
-require_relative "./standard"
+require_relative "standard"
 
 module Calendav
   module Credentials

data/lib/calendav/endpoint.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "./contextual_url"
-require_relative "./errors"
-require_relative "./parsers/response_xml"
+require_relative "contextual_url"
+require_relative "error_handler"
+require_relative "parsers/response_xml"
 
 module Calendav
   class Endpoint
@@ -16,7 +16,7 @@ module Calendav
       @timeout = timeout
     end
 
-    def delete(url:, etag: nil)
+    def delete(url:, etag: nil) # rubocop:disable Naming/PredicateMethod
       request(:delete, url: url, http: with_headers(etag: etag))
         .status
         .success?
@@ -79,12 +79,14 @@ module Calendav
 
     attr_reader :credentials, :timeout
 
-    def authenticated
+    def authenticated # rubocop:disable Metrics/MethodLength
       case credentials.authentication
       when :basic_auth
         HTTP.basic_auth(user: credentials.username, pass: credentials.password)
       when :bearer_token
         HTTP.auth("Bearer #{credentials.password}")
+      when :oauth
+        HTTP.auth("OAuth #{credentials.password}")
       else
         raise "Unexpected authentication approach: " \
               "#{credentials.authentication}"
@@ -109,11 +111,7 @@ module Calendav
         verb, ContextualURL.call(credentials.host, url), body: body
       )
 
-      return response if response.status.success?
-
-      raise PreconditionError, response if response.status.code == 412
-
-      raise RequestError, response
+      response.status.success? ? response : ErrorHandler.call(response)
     end
 
     def parse(response)

data/lib/calendav/error_handler.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Calendav
+  class ErrorHandler
+    def self.call(...)
+      new(...).call
+    end
+
+    def initialize(response)
+      @response = response
+    end
+
+    def call
+      raise PreconditionError, response if status.code == 412
+      raise RedirectError, response if status.redirect?
+
+      raise RequestError, response
+    end
+
+    private
+
+    attr_reader :response
+
+    def headers
+      response.headers
+    end
+
+    def status
+      response.status
+    end
+  end
+end

data/lib/calendav/errors.rb

@@ -7,7 +7,7 @@ module Calendav
     attr_reader :xml, :original
 
     def initialize(xml, original)
-      super original.message
+      super(original.message)
 
       @xml = xml
       @original = original
@@ -18,11 +18,17 @@ module Calendav
     attr_reader :response
 
     def initialize(response)
-      super response.status.to_s
+      super(response.status.to_s)
 
       @response = response
     end
   end
 
+  class RedirectError < RequestError
+    def location
+      response.headers["Location"]
+    end
+  end
+
   PreconditionError = Class.new(RequestError)
 end

data/lib/calendav/event.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "./contextual_url"
-require_relative "./parsers/event_xml"
+require_relative "contextual_url"
+require_relative "parsers/event_xml"
 
 module Calendav
   class Event

data/lib/calendav/parsers/todo_xml.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Calendav
+  module Parsers
+    class TodoXML
+      def self.call(...)
+        new(...).call
+      end
+
+      def initialize(element)
+        @element = element
+      end
+
+      def call
+        {
+          calendar_data: value(".//caldav:calendar-data"),
+          etag: value(".//dav:getetag")
+        }
+      end
+
+      private
+
+      attr_reader :element
+
+      def value(xpath)
+        node = element.xpath(xpath)
+        return nil if node.children.empty?
+
+        if node.children.any?(&:element?)
+          node.children.select(&:element?).collect(&:to_xml).join
+        else
+          node.children.text
+        end
+      end
+    end
+  end
+end

data/lib/calendav/requests/list_events.rb

@@ -11,9 +11,10 @@ module Calendav
         new(...).call
       end
 
-      def initialize(from:, to:)
+      def initialize(from:, to:, expand_recurring_events:)
         @from = from
         @to = to
+        @expand_recurring_events = expand_recurring_events
       end
 
       def call
@@ -21,7 +22,13 @@ module Calendav
           xml["caldav"].public_send("calendar-query", NAMESPACES) do
             xml["dav"].prop do
               xml["dav"].getetag
-              xml["caldav"].public_send(:"calendar-data")
+              if expand_recurring_events? && range?
+                xml["caldav"].public_send(:"calendar-data") do
+                  xml["caldav"].expand(start: from, end: to)
+                end
+              else
+                xml["caldav"].public_send(:"calendar-data")
+              end
             end
             xml["caldav"].filter do
               xml["caldav"].public_send(:"comp-filter", name: "VCALENDAR") do
@@ -40,6 +47,10 @@ module Calendav
 
       private
 
+      def expand_recurring_events?
+        @expand_recurring_events
+      end
+
       def from
         return nil if @from.nil?
 

data/lib/calendav/requests/list_todos.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require_relative "../namespaces"
+
+module Calendav
+  module Requests
+    class ListTodos
+      def self.call(...)
+        new.call
+      end
+
+      def call
+        Nokogiri::XML::Builder.new do |xml|
+          xml["caldav"].public_send("calendar-query", NAMESPACES) do
+            xml["dav"].prop do
+              xml["dav"].getetag
+              xml["caldav"].public_send(:"calendar-data")
+            end
+            xml["caldav"].filter do
+              xml["caldav"].public_send(:"comp-filter", name: "VCALENDAR") do
+                xml["caldav"].public_send(:"comp-filter", name: "VTODO")
+              end
+            end
+          end
+        end
+      end
+
+      private
+
+      def from
+        return nil if @from.nil?
+
+        @from.utc.iso8601.delete(":-")
+      end
+
+      def to
+        return nil if @to.nil?
+
+        @to.utc.iso8601.delete(":-")
+      end
+
+      def range?
+        to || from
+      end
+    end
+  end
+end

data/lib/calendav/requests/make_calendar.rb

@@ -38,6 +38,7 @@ module Calendav
                   :"supported-calendar-component-set"
                 ) do
                   xml["caldav"].comp name: "VEVENT"
+                  xml["caldav"].comp name: "VTODO"
                 end
               end
             end