mobiscroll-connect 1.1.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49b200acf379cde0578e8f4b74e414b7a9fc5c71209f76e564654c74ece51959
-  data.tar.gz: 8462c4b2e4ad3c41f29d69ccd6010c21c5b598a1eb7a319d7502fd0ee6186da4
+  metadata.gz: b741101bdf4d7452a820bd7b988d9dff51f02cf4683d867fb332292ab0a4177e
+  data.tar.gz: 1516abffa7aea7972ebaf558c77bcd8999c397606bf66b9cf27f7519bc5198ea
 SHA512:
-  metadata.gz: 76adf999c8a02d7ef85a7f06e6cc537dde75b9d689ba9be0608489040a4f05b696fc1cf8002fabab6b3086deff6a3f54080ff8e83191a12b8532368c47168c94
-  data.tar.gz: '09b3556482b18761984dfa400dbe11b26288c98176afb662bbdd4ca41a2ace1768636806cab1a63a21ec1b536d16ac088b49982134d03b1ef33bb7e437c3ed2e'
+  metadata.gz: 5778815c08e0d3cda4217a0c0b559ef6ad9e840b7c83760409875a446c9bcfcd9d26ee96caa18c74ef4ba194e9d51e6974e1b32d3ce58daec68fbb2ab510b52c
+  data.tar.gz: '089dd3ea229d309050d63097ce83bc2b4f74a2c2513b1668a716154563b5a9d01e9e9a4ebe4ab384f1c9f9d83a3f7f804ac2dcbbc8681d831817f26a18412934'

data/README.md

@@ -35,7 +35,7 @@ client = Mobiscroll::Connect::Client.new(
 ```ruby
 url = client.auth.generate_auth_url(
   user_id:   'user-123',
-  lng:       'es', # optional: Connect page language ('en', 'es', 'fr', 'ar')
+  lng:       'es', # optional: Connect page language, see https://mobiscroll.com/docs/connect/localization#supported-languages
   providers: [
     Mobiscroll::Connect::Provider::GOOGLE,
     Mobiscroll::Connect::Provider::MICROSOFT
@@ -69,7 +69,12 @@ client.set_credentials(
 ```ruby
 status = client.auth.get_connection_status
 status.connections.each do |provider, accounts|
-  accounts.each { |a| puts "#{provider}: #{a.display}" }
+  accounts.each do |a|
+    puts "#{provider}: #{a.display}"
+    # Google's consent screen lets the user untick the calendar permission and still
+    # finish signing in. Such an account is connected but lists no calendars.
+    puts "  #{a.id} must reconnect and allow calendar access" if a.calendar_permission_granted == false
+  end
 end
 ```
 
@@ -165,6 +170,29 @@ client.events.delete(
 )
 ```
 
+## Webhooks
+
+### Subscribe to calendar change notifications
+
+```ruby
+result = client.webhooks.subscribe_webhook(
+  provider:    Mobiscroll::Connect::Provider::GOOGLE,
+  calendar_id: 'primary'
+)
+puts result.channel_id
+puts result.server_webhook_url
+```
+
+### Unsubscribe
+
+```ruby
+client.webhooks.unsubscribe_webhook(
+  provider:    'google',
+  channel_id:  result.channel_id,
+  resource_id: result.subscription.resource_id
+)
+```
+
 ## Error handling
 
 All errors are subclasses of `Mobiscroll::Connect::Error`:

data/lib/mobiscroll/connect/client.rb

@@ -3,7 +3,7 @@
 module Mobiscroll
   module Connect
     class Client
-      attr_reader :auth, :calendars, :events
+      attr_reader :auth, :calendars, :events, :webhooks
 
       def initialize(client_id:, client_secret:, redirect_uri:,
                      base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
@@ -20,6 +20,7 @@ module Mobiscroll
         @auth = Resources::Auth.new(@config, @api_client)
         @calendars = Resources::Calendars.new(@config, @api_client)
         @events = Resources::Events.new(@config, @api_client)
+        @webhooks = Resources::Webhooks.new(@config, @api_client)
       end
 
       def set_credentials(tokens)

data/lib/mobiscroll/connect/errors.rb

@@ -17,6 +17,25 @@ module Mobiscroll
       end
     end
 
+    # Raised when no connected account has the calendar access the request needs.
+    #
+    # The user completed sign-in but did not grant the calendar permission — Google's
+    # consent screen presents it as a separate checkbox. This cannot be repaired
+    # server-side, because providers only issue permissions at consent time: the
+    # accounts in +accounts+ have to run the connect flow again and allow access.
+    #
+    # Subclasses AuthenticationError, so existing rescue clauses keep working.
+    class CalendarPermissionError < AuthenticationError
+      # Array of BlockedAccount structs that must reconnect.
+      attr_reader :accounts
+
+      def initialize(message = 'No connected account has calendar access', accounts: [])
+        super(message)
+        @code = 'CALENDAR_PERMISSION_REQUIRED'
+        @accounts = accounts
+      end
+    end
+
     class NotFoundError < Error
       def initialize(message = 'Resource not found')
         super(message, code: 'NOT_FOUND_ERROR')
@@ -67,7 +86,15 @@ module Mobiscroll
 
       case status
       when 401, 403
-        AuthenticationError.new(message)
+        # A 403 the caller can act on: the account connected but never granted
+        # calendar access, so it is raised as its own type naming the accounts.
+        hash = body.is_a?(Hash) ? body : {}
+        if status == 403 && (hash['code'] || hash[:code]) == 'calendar_permission_required'
+          raw = hash['accounts'] || hash[:accounts]
+          CalendarPermissionError.new(message, accounts: Array(raw).filter_map { |a| BlockedAccount.from_h(a) })
+        else
+          AuthenticationError.new(message)
+        end
       when 404
         NotFoundError.new(message)
       when 400, 422

data/lib/mobiscroll/connect/models.rb

@@ -35,12 +35,50 @@ module Mobiscroll
       end
     end
 
-    # One connected account under a provider.
-    ConnectedAccount = Struct.new(:id, :display, keyword_init: true) do
+    # A connected account that withheld calendar access on its provider's consent screen.
+    BlockedAccount = Struct.new(:provider, :account, keyword_init: true) do
       def self.from_h(hash)
         return nil if hash.nil?
 
-        new(id: hash['id'] || hash[:id], display: hash['display'] || hash[:display])
+        new(
+          provider: hash['provider'] || hash[:provider],
+          account: hash['account'] || hash[:account]
+        )
+      end
+    end
+
+    # One connected calendar account.
+    #
+    # `granted_scopes` are the scopes the provider actually granted, which are not
+    # necessarily the ones Connect asked for: Google's consent screen lets the user untick
+    # the calendar permission and still complete sign-in.
+    #
+    # `calendar_permission_granted` is false for exactly those accounts — connected, but
+    # no calendars can be read from them until the user reconnects and allows access. It
+    # is nil when the question does not apply (Apple and CalDav authenticate with a
+    # username and app password) or no scopes were recorded for the account.
+    # `sync_state` reports whether the stored credentials still work: 'active', or
+    # 'reauth_required' once the provider has rejected them. It answers a different question
+    # from `calendar_permission_granted`, which records what was agreed at consent time and
+    # never changes afterwards. An account with no observed failure is 'active'. Recovery is
+    # the same reconnect — it cannot be repaired server-side.
+    ConnectedAccount = Struct.new(
+      :id, :display, :granted_scopes, :calendar_permission_granted, :sync_state, :sync_state_updated_at,
+      keyword_init: true
+    ) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        key = 'calendarPermissionGranted'
+        granted = hash.key?(key) ? hash[key] : hash[key.to_sym]
+        new(
+          id: hash['id'] || hash[:id],
+          display: hash['display'] || hash[:display],
+          granted_scopes: Array(hash['grantedScopes'] || hash[:grantedScopes]),
+          calendar_permission_granted: granted,
+          sync_state: hash['syncState'] || hash[:syncState] || 'active',
+          sync_state_updated_at: hash['syncStateUpdatedAt'] || hash[:syncStateUpdatedAt]
+        )
       end
     end
 
@@ -172,5 +210,47 @@ module Mobiscroll
         )
       end
     end
+
+    # The channel details returned by Webhooks#subscribe_webhook. `resource_id` is
+    # present for Google; `expiration` is an ISO date string, present for some providers.
+    WebhookSubscription = Struct.new(:channel_id, :resource_id, :expiration, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(
+          channel_id: hash['channelId'] || hash[:channelId],
+          resource_id: hash['resourceId'] || hash[:resourceId],
+          expiration: hash['expiration'] || hash[:expiration]
+        )
+      end
+    end
+
+    # Response from Webhooks#subscribe_webhook.
+    SubscribeWebhookResponse = Struct.new(
+      :success, :provider, :subscription, :server_webhook_url, :channel_id, keyword_init: true
+    ) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(
+          success: hash['success'] || hash[:success],
+          provider: hash['provider'] || hash[:provider],
+          subscription: WebhookSubscription.from_h(hash['subscription'] || hash[:subscription]),
+          server_webhook_url: hash['serverWebhookUrl'] || hash[:serverWebhookUrl],
+          channel_id: hash['channelId'] || hash[:channelId]
+        )
+      end
+    end
+
+    # Response from Webhooks#unsubscribe_webhook. `success` is true whenever the local
+    # mapping was removed, even if the provider-side unsubscribe itself failed — `message`
+    # explains what happened in that case.
+    UnsubscribeWebhookResponse = Struct.new(:success, :message, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(success: hash['success'] || hash[:success], message: hash['message'] || hash[:message])
+      end
+    end
   end
 end

data/lib/mobiscroll/connect/resources/webhooks.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Mobiscroll
+  module Connect
+    module Resources
+      class Webhooks
+        def initialize(_config, api_client)
+          @api_client = api_client
+        end
+
+        # Subscribes to push notifications for changes on a calendar.
+        #
+        # `channel_id` is auto-generated server-side when omitted. `expiration` is a
+        # provider-specific timestamp (ms epoch) the caller can suggest.
+        def subscribe_webhook(provider:, calendar_id:, channel_id: nil, expiration: nil)
+          body = { 'provider' => provider, 'calendarId' => calendar_id }
+          body['channelId'] = channel_id if channel_id
+          body['expiration'] = expiration if expiration
+
+          parsed = @api_client.post('/subscribe-webhook', body: JSON.generate(body))
+          SubscribeWebhookResponse.from_h(parsed)
+        end
+
+        # Unsubscribes a previously created webhook channel. `resource_id` is required by
+        # some providers (e.g. Google) to fully unsubscribe.
+        #
+        # The backend treats a 200 response as final even when the provider-side
+        # unsubscribe itself failed (e.g. an already-expired subscription) — the local
+        # mapping is removed either way, and `message` explains what happened.
+        def unsubscribe_webhook(provider:, channel_id:, resource_id: nil)
+          body = { 'provider' => provider, 'channelId' => channel_id }
+          body['resourceId'] = resource_id if resource_id
+
+          parsed = @api_client.post('/unsubscribe-webhook', body: JSON.generate(body))
+          UnsubscribeWebhookResponse.from_h(parsed)
+        end
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/version.rb

@@ -2,6 +2,6 @@
 
 module Mobiscroll
   module Connect
-    VERSION = '1.1.0'
+    VERSION = '1.5.0'
   end
 end

data/lib/mobiscroll/connect.rb

@@ -9,6 +9,7 @@ require_relative 'connect/api_client'
 require_relative 'connect/resources/auth'
 require_relative 'connect/resources/calendars'
 require_relative 'connect/resources/events'
+require_relative 'connect/resources/webhooks'
 require_relative 'connect/client'
 
 module Mobiscroll

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mobiscroll-connect
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Mobiscroll
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -101,6 +101,7 @@ files:
 - lib/mobiscroll/connect/resources/auth.rb
 - lib/mobiscroll/connect/resources/calendars.rb
 - lib/mobiscroll/connect/resources/events.rb
+- lib/mobiscroll/connect/resources/webhooks.rb
 - lib/mobiscroll/connect/version.rb
 - mobiscroll-connect.gemspec
 homepage: https://mobiscroll.com/connect