async-vikunja 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d1420cbccb11b7d3c779e16482c9e2e7181d924eb148f15abb8d663d2776047
-  data.tar.gz: 409c2841ca1b637ff139b48ff0cadd35ab27b29c1fa2727847a00dcf0a97b691
+  metadata.gz: 542a774d84fa94455ddbe6fad372b4af80be46ba16d792598efcd921af1a5b8d
+  data.tar.gz: c88c89e32e48806172a5329c4684b224bc7ef7f76636167bff3c58eededc1122
 SHA512:
-  metadata.gz: a6332a41f269ff1df2d09747524b04934eec02165b530b4d9b189a08e977442523b62aef0e500de019f0d3c0f4a761841b8f460bb9ab98c7e5aee1012f40df2d
-  data.tar.gz: 1f75d82c9811c6f9518c2999808850e97a146f524b16653a10fcc95874c561e5c9a4a525490a9c33c03f2bb16471bc773d996d2ce33b4662dc861d7bdc2430ec
+  metadata.gz: a1f4eff3b457265fef50003cb8e98be725a219648bb5b2f0a268288e1e17177ed129a7c573dd9682114dc1ee8b2ede58c44219da785cdcec20008cd8a8a2b47a
+  data.tar.gz: d14784601ab95bef94f217bbba4a86b83ec97fd4cacfd811573082e746d1dfc4e27f59bc2467410fdefffe2f3fd06621ff3264c09a075024cce5967a54f7ff49

data/README.md

@@ -175,21 +175,69 @@ vikunja.project(1).search_users("test").map(&:username)
 vikunja.project(1).remove_user("tester")
 ```
 
+Bytes go up as they are, so read a file in binary and say what it is. Several parts may share
+one field name.
+
 ```ruby
 result = vikunja.task(7).upload_attachments([
-  {name: "files", filename: "notes.txt", content_type: "text/plain", body: File.read("notes.txt")},
+  {name: "files", filename: "notes.txt", content_type: "text/plain", body: File.binread("notes.txt")},
+  {name: "files", filename: "diagram.png", content_type: "image/png", body: File.binread("diagram.png")},
 ])
 
 result.success.map{|attachment| attachment.file.name}
 result.errors.map(&:message)
+```
+
+An attachment knows its own address wherever it arrived, so it downloads and deletes itself.
+
+```ruby
+stored = result.success.first
+
+stored.download.bytes
+stored.delete
 
 vikunja.task(7).task_attachments.map{|attachment| attachment.file.size}
-vikunja.task(7).download_attachment(3).bytes
+vikunja.task(7).attachments.map{|attachment| attachment.download.bytes.bytesize}
+```
+
+A download is the bytes the API answered with, not a document. It is fetched when it is first
+read, and the headers arrive with it.
+
+```ruby
+file = vikunja.task(7).download_attachment(3)
+
+file.media_type
+file.bytes
+
+vikunja.task(7).attachment(3).preview("sm").bytes
 vikunja.task(7).attachment(3).delete
 ```
 
+A file is as large as it is. Give a download a block and the body arrives a chunk at a time, so
+nothing holds the whole of it:
+
+```ruby
+File.open("notes.txt", "wb") do |out|
+  vikunja.task(7).download_attachment(3) do |response|
+    response.body.each{|chunk| out.write(chunk)}
+  end
+end
+```
+
+Every download takes a block the same way: `avatar`, `background`, `preview`, `totp_qrcode`,
+`notifications_atom` and `download_export`.
+
+An upload streams the other way. Hand a part an open file rather than its bytes, and it is read
+from disk as it goes on the wire:
+
+```ruby
+vikunja.task(7).upload_attachments([
+  {name: "files", filename: "recording.mp4", content_type: "video/mp4", body: File.open("recording.mp4", "rb")},
+])
+```
+
 ```ruby
-vikunja.project(1).upload_background({name: "background", filename: "wall.jpg", content_type: "image/jpeg", body: File.read("wall.jpg")})
+vikunja.project(1).upload_background({name: "background", filename: "wall.jpg", content_type: "image/jpeg", body: File.binread("wall.jpg")})
 
 background = vikunja.project(1).background
 
@@ -248,7 +296,7 @@ vikunja.create_caldav_token.token
 ```ruby
 vikunja.user.settings.timezone
 vikunja.update_settings({name: "Tester", week_start: 1, timezone: "Europe/London"}).message
-vikunja.upload_avatar({name: "avatar", filename: "me.png", content_type: "image/png", body: File.read("me.png")})
+vikunja.upload_avatar({name: "avatar", filename: "me.png", content_type: "image/png", body: File.binread("me.png")})
 vikunja.avatar("tester", size: 64).bytes
 vikunja.set_avatar_provider(avatar_provider: "initials")
 

data/lib/async/vikunja/attachments.rb

@@ -25,9 +25,9 @@ module Async
 
       def file = self.nested(File, self.value[:file])
 
-      def download = Download.new(@resource)
+      def download(&block) = Download.open(@resource, &block)
 
-      def preview(size) = Download.new(@resource.with(parameters: {preview_size: size}))
+      def preview(size, &block) = Download.open(@resource.with(parameters: {preview_size: size}), &block)
 
       def delete = self.discard(@resource)
     end
@@ -39,7 +39,7 @@ module Async
     end
 
     class AttachmentUploadResult < Representation
-      def success = self.nested_list(TaskAttachment, self.value[:success])
+      def success = self.nested_list(TaskAttachment, self.value[:success], identify: true)
 
       def errors = self.nested_list(AttachmentUploadError, self.value[:errors])
     end

data/lib/async/vikunja/auth.rb

@@ -38,6 +38,8 @@ module Async
 
       def refresh_token = self.submit(AuthToken, self.with(path: "user/token/refresh"), nil)
 
+      def register(payload) = self.submit(User, self.with(path: "register"), payload, identify: nil)
+
       def confirm_email(payload) = self.submit(Message, self.with(path: "user/confirm"), payload)
 
       def reset_password(payload) = self.submit(Message, self.with(path: "user/password/reset"), payload)

data/lib/async/vikunja/client.rb

@@ -9,7 +9,9 @@ require_relative "buckets"
 require_relative "comments"
 require_relative "error"
 require_relative "filters"
+require_relative "invite_links"
 require_relative "labels"
+require_relative "mcp"
 require_relative "migration"
 require_relative "notifications"
 require_relative "page"
@@ -43,7 +45,9 @@ module Async
       include Auth
       include Bots
       include Filters
+      include InviteLinks
       include Labels
+      include MCP
       include Migration
       include Notifications
       include Projects

data/lib/async/vikunja/invite_links.rb

@@ -0,0 +1,69 @@
+require_relative "page"
+
+module Async
+  module Vikunja
+    class InviteLinkTeam < Representation
+      def id = self.value[:id]
+
+      def name = self.value[:name]
+    end
+
+    class UserInviteLink < Representation
+      def id = self.value[:id]
+
+      def name = self.value[:name]
+
+      def token = self.value[:token]
+
+      def max_uses = self.value[:max_uses]
+
+      def uses = self.value[:uses]
+
+      def expires_at = self.value[:expires_at]
+
+      def skip_email_confirm = self.value[:skip_email_confirm]
+
+      def created = self.value[:created]
+
+      def updated = self.value[:updated]
+
+      def created_by = self.nested(User, self.value[:created_by])
+
+      def teams = self.nested_list(InviteLinkTeam, self.value[:teams])
+
+      def spent? = self.max_uses.to_i.positive? && self.uses.to_i >= self.max_uses.to_i
+
+      def delete = self.discard(@resource)
+    end
+
+    class PublicInviteLink < Representation
+      def name = self.value[:name]
+
+      def skip_email_confirm = self.value[:skip_email_confirm]
+
+      def teams = self.nested_list(InviteLinkTeam, self.value[:teams])
+    end
+
+    class UserInviteLinkPage < Page
+      MEMBER = UserInviteLink
+    end
+
+    class InviteLinkTeamPage < Page
+      MEMBER = InviteLinkTeam
+
+      def member_resource(record) = @resource
+    end
+
+    module InviteLinks
+      def invite_links(**parameters) = Collection.for(self, "admin/invite-links", UserInviteLinkPage, **parameters)
+
+      def create_invite_link(payload) = self.submit(UserInviteLink, self.with(path: "admin/invite-links"), payload, identify: true)
+
+      def remove_invite_link(id) = self.discard(self.with(path: "admin/invite-links/" + Vikunja.escape(id)))
+
+      def invite_link_teams(**parameters) = Collection.for(self, "admin/teams", InviteLinkTeamPage, **parameters)
+
+      def check_invite_link(token) = self.submit(PublicInviteLink, self.with(path: "invite-links/check"), {token: token})
+    end
+  end
+end

data/lib/async/vikunja/mcp.rb

@@ -0,0 +1,25 @@
+require_relative "page"
+
+module Async
+  module Vikunja
+    class TokenPresets < Representation
+      def full = self.value[:full]
+
+      def read_only = self.value[:read_only]
+
+      def typed = self.value[:typed]
+    end
+
+    class ConnectionSettings < Representation
+      def endpoint = self.value[:endpoint]
+
+      def routes = self.value[:routes]
+
+      def presets = self.nested(TokenPresets, self.value[:presets])
+    end
+
+    module MCP
+      def mcp_info = ConnectionSettings.new(self.with(path: "mcp/info"))
+    end
+  end
+end

data/lib/async/vikunja/migration.rb

@@ -58,6 +58,12 @@ module Async
       def started_at = self.value[:started_at]
 
       def finished_at = self.value[:finished_at]
+
+      def error_kind = self.value[:error_kind]
+
+      def error_message = self.value[:error_message]
+
+      def failed? = !self.error_kind.nil?
     end
 
     module Migration

data/lib/async/vikunja/projects.rb

@@ -61,7 +61,7 @@ module Async
 
       def task_by_index(index) = TaskReadOneBody.new(@resource.with(path: "tasks/by-index/" + Vikunja.escape(index)))
 
-      def background = Download.new(@resource.with(path: "background"))
+      def background(&block) = Download.open(@resource.with(path: "background"), &block)
 
       def search_users(query) = UserSearchPage.new(@resource.with(path: "users/search", parameters: {q: query}))
 

data/lib/async/vikunja/representation.rb

@@ -41,15 +41,15 @@ module Async
         end
       end
 
-      def nested(klass, value)
+      def nested(klass, value, identify: nil)
         if value
-          klass.new(@resource, value: value, metadata: self.metadata)
+          klass.new(self.identified(@resource, identify, value), value: value, metadata: self.metadata)
         end
       end
 
-      def nested_list(klass, values)
+      def nested_list(klass, values, identify: nil)
         Array(values).map do |value|
-          self.nested(klass, value)
+          self.nested(klass, value, identify: identify)
         end
       end
     end
@@ -63,11 +63,25 @@ module Async
     end
 
     class Download < Representation
-      WRAPPER = Wrapper.new
+      WRAPPER = Transfer.new
+
+      def self.open(resource, &block)
+        if block
+          self.get(resource) do |_resource, response, _klass|
+            block.call(response)
+          end
+        else
+          self.new(resource)
+        end
+      end
 
       def bytes = self.value
 
-      def media_type = self.metadata["content-type"]
+      def media_type
+        self.bytes
+
+        self.metadata["content-type"]
+      end
     end
   end
 end

data/lib/async/vikunja/service.rb

@@ -131,7 +131,7 @@ module Async
 
       def routes = Representation.new(self.with(path: "routes"))
 
-      def notifications_atom = Download.new(self.with(path: "notifications.atom"))
+      def notifications_atom(&block) = Download.open(self.with(path: "notifications.atom"), &block)
     end
   end
 end

data/lib/async/vikunja/settings.rb

@@ -43,8 +43,12 @@ module Async
     end
 
     module Settings
+      def settings = UserGeneralSettings.new(self.with(path: "user/settings/general"))
+
       def update_settings(payload) = self.submit(UserActionMessageBody, self.with(path: "user/settings/general"), payload, method: :put)
 
+      def patch_settings(payload) = self.merge_patch(UserActionMessageBody, self.with(path: "user/settings/general"), payload)
+
       def avatar_provider = UserAvatarProviderBody.new(self.with(path: "user/settings/avatar/provider"))
 
       def set_avatar_provider(avatar_provider:) = self.submit(UserAvatarProviderBody, self.with(path: "user/settings/avatar/provider"), {avatar_provider: avatar_provider}, method: :put)
@@ -61,7 +65,7 @@ module Async
 
       def disable_totp(password:) = self.submit(Message, self.with(path: "user/settings/totp/disable"), {password: password})
 
-      def totp_qrcode = Download.new(self.with(path: "user/settings/totp/qrcode"))
+      def totp_qrcode(&block) = Download.open(self.with(path: "user/settings/totp/qrcode"), &block)
     end
   end
 end

data/lib/async/vikunja/submit.rb

@@ -53,6 +53,18 @@ module Async
         self.submit(klass, resource, parts, method: method, through: UploadRepresentation)
       end
 
+      def fetch(klass, resource, payload = nil, method: :post, &block)
+        if block
+          self.with_retry do
+            klass.public_send(method, resource, payload) do |_target, response|
+              block.call(response)
+            end
+          end
+        else
+          self.submit(klass, resource, payload, method: method)
+        end
+      end
+
       def discard(resource, payload = nil, method: :delete)
         self.with_retry do
           Representation.public_send(method, resource, payload) do |target, response|

data/lib/async/vikunja/tasks.rb

@@ -65,7 +65,7 @@ module Async
 
       def assignees = self.nested_list(User, self.value[:assignees])
 
-      def attachments = self.nested_list(TaskAttachment, self.value[:attachments])
+      def attachments = self.nested_list(TaskAttachment, self.value[:attachments], identify: "attachments/")
 
       def buckets = self.nested_list(Bucket, self.value[:buckets])
 
@@ -97,7 +97,7 @@ module Async
 
       def attachment(id) = TaskAttachment.new(@resource.with(path: "attachments/" + Vikunja.escape(id)))
 
-      def download_attachment(id) = Download.new(@resource.with(path: "attachments/" + Vikunja.escape(id)))
+      def download_attachment(id, &block) = Download.open(@resource.with(path: "attachments/" + Vikunja.escape(id)), &block)
 
       def create_comment(payload) = self.submit(TaskComment, @resource.with(path: "comments"), payload, identify: true)
 

data/lib/async/vikunja/users.rb

@@ -79,7 +79,7 @@ module Async
 
       def users(query) = UserSearchPage.new(self.with(path: "users", parameters: {q: query}))
 
-      def avatar(username, **parameters) = Download.new(self.with(path: "avatar/" + Vikunja.escape(username), parameters: parameters))
+      def avatar(username, **parameters, &block) = Download.open(self.with(path: "avatar/" + Vikunja.escape(username), parameters: parameters), &block)
 
       def timezones = Representation.new(self.with(path: "user/timezones"))
 
@@ -95,7 +95,7 @@ module Async
 
       def request_export(password:) = self.submit(Message, self.with(path: "user/export/request"), {password: password})
 
-      def download_export(password:) = self.submit(Download, self.with(path: "user/export/download"), {password: password})
+      def download_export(password:, &block) = self.fetch(Download, self.with(path: "user/export/download"), {password: password}, &block)
 
       def request_deletion(password:) = self.discard(self.with(path: "user/deletion/request"), {password: password}, method: :post)
 

data/lib/async/vikunja/version.rb

@@ -5,6 +5,6 @@
 
 module Async
   module Vikunja
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/async/vikunja/wrapper.rb

@@ -1,5 +1,9 @@
 require "async/rest/wrapper/json"
 require "protocol/http/body/buffered"
+require "protocol/http/body/file"
+require "protocol/http/body/readable"
+
+require_relative "error"
 
 module Async
   module Vikunja
@@ -30,6 +34,29 @@ module Async
       end
     end
 
+    class Transfer < Wrapper
+      ANY = "*/*"
+
+      def prepare_request(request, payload)
+        request.headers["accept"] ||= ANY
+
+        if payload
+          request.headers["content-type"] = self.content_type
+          request.body = ::Protocol::HTTP::Body::Buffered.new([::JSON.dump(payload)])
+        end
+      end
+
+      def process_response(request, response)
+        super
+
+        unless response.success?
+          raise Failure.for(response)
+        end
+
+        response
+      end
+    end
+
     class Multipart < Wrapper
       MULTIPART_FORM_DATA = "multipart/form-data"
 
@@ -39,30 +66,103 @@ module Async
 
       CRLF = "\r\n"
 
+      class Body < ::Protocol::HTTP::Body::Readable
+        def initialize(bodies)
+          @bodies = bodies
+          @index = 0
+        end
+
+        def length
+          lengths = @bodies.map(&:length)
+
+          if lengths.include?(nil)
+            nil
+          else
+            lengths.sum
+          end
+        end
+
+        def empty? = @index >= @bodies.size
+
+        def ready? = true
+
+        def read
+          chunk = nil
+
+          while chunk.nil? && @index < @bodies.size
+            chunk = @bodies[@index].read
+
+            if chunk.nil?
+              @index += 1
+            end
+          end
+
+          chunk
+        end
+
+        def close(error = nil)
+          @bodies.each do |body|
+            body.close(error)
+          end
+
+          @index = @bodies.size
+
+          super
+        end
+      end
+
       def prepare_request(request, payload)
         request.headers["accept"] ||= self.content_type
 
         if payload
           request.headers["content-type"] = MULTIPART_FORM_DATA + "; boundary=" + BOUNDARY
-          request.body = ::Protocol::HTTP::Body::Buffered.new([self.encode(payload)])
+          request.body = Body.new(self.bodies_for(payload))
         end
       end
 
-      def encode(parts)
-        String.new.tap do |encoded|
+      def bodies_for(parts)
+        [].tap do |bodies|
           Array(parts).each do |part|
-            encoded << "--" + BOUNDARY + CRLF
-            encoded << "content-disposition: form-data; " + self.disposition_of(part) + CRLF
-            encoded << "content-type: " + (part[:content_type] || OCTET_STREAM) + CRLF
-            encoded << CRLF
-            encoded << part.fetch(:body).to_s
-            encoded << CRLF
+            bodies << self.buffered(self.preamble_of(part))
+            bodies << self.body_of(part)
+            bodies << self.buffered(CRLF)
           end
 
-          encoded << "--" + BOUNDARY + "--" + CRLF
+          bodies << self.buffered("--" + BOUNDARY + "--" + CRLF)
+        end
+      end
+
+      def buffered(text) = ::Protocol::HTTP::Body::Buffered.new([self.binary(text)])
+
+      def binary(text)
+        case text.encoding
+        when ::Encoding::BINARY
+          text
+        else
+          text.b
         end
       end
 
+      def body_of(part)
+        body = part.fetch(:body)
+
+        case body
+        when ::Protocol::HTTP::Body::Readable
+          body
+        when ::IO, ::StringIO
+          ::Protocol::HTTP::Body::File.new(body)
+        else
+          self.buffered(body.to_s)
+        end
+      end
+
+      def preamble_of(part)
+        "--" + BOUNDARY + CRLF +
+          "content-disposition: form-data; " + self.disposition_of(part) + CRLF +
+          "content-type: " + (part[:content_type] || OCTET_STREAM) + CRLF +
+          CRLF
+      end
+
       def disposition_of(part)
         ("name=" + part.fetch(:name).to_s.inspect).tap do |disposition|
           if part[:filename]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-vikunja
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nathan Kidd
@@ -56,7 +56,9 @@ files:
 - lib/async/vikunja/error.rb
 - lib/async/vikunja/escape.rb
 - lib/async/vikunja/filters.rb
+- lib/async/vikunja/invite_links.rb
 - lib/async/vikunja/labels.rb
+- lib/async/vikunja/mcp.rb
 - lib/async/vikunja/migration.rb
 - lib/async/vikunja/notifications.rb
 - lib/async/vikunja/page.rb