mobiscroll-connect 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9fad1da025f19a473c5c77e9ed4b671153e27b4e632f6401d5b0d4a5f9ef9762
+  data.tar.gz: 5701c68a5e0a91f639d9fc929d59808004b4097ce84eee9fb7d9a13bf5d7c2e1
+SHA512:
+  metadata.gz: 0760023c86467c57dcd1581d85350238a2dda83a2b5d0e9ad44e46bf62d76fd7988f2892c8fc8d62a5918c71f8f5fbc77c70cd05b8c7d73e815ef6a84ea37b7f
+  data.tar.gz: f119340a29e9d1f24660c823a83702a60951275c46f81f89fc6cf5d6e8dfe07d0c066638fc51aeef0eefcfb6ec8cf35385040ea983da85fd0f96eec5bbfe0f39

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mobiscroll
+
+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/README.md

@@ -0,0 +1,222 @@
+# Mobiscroll Connect Ruby SDK
+
+Official Ruby client for the [Mobiscroll Connect API](https://connect.mobiscroll.com). Sync calendar events across Google Calendar, Microsoft Outlook, Apple Calendar, and CalDAV.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'mobiscroll-connect', '~> 1.0'
+```
+
+Or install directly:
+
+```bash
+gem install mobiscroll-connect
+```
+
+## Quick start
+
+```ruby
+require 'mobiscroll-connect'
+
+client = Mobiscroll::Connect::Client.new(
+  client_id:     ENV['MOBISCROLL_CLIENT_ID'],
+  client_secret: ENV['MOBISCROLL_CLIENT_SECRET'],
+  redirect_uri:  'https://yourapp.com/oauth/callback'
+)
+```
+
+## OAuth flow
+
+### 1. Generate the authorization URL
+
+```ruby
+url = client.auth.generate_auth_url(
+  user_id:   'user-123',
+  providers: [
+    Mobiscroll::Connect::Provider::GOOGLE,
+    Mobiscroll::Connect::Provider::MICROSOFT
+  ]
+)
+# Redirect the user to `url`
+```
+
+### 2. Exchange the code for tokens
+
+```ruby
+# In your /oauth/callback handler:
+tokens = client.auth.get_token(params[:code])
+# tokens.access_token, tokens.refresh_token, tokens.expires_in
+```
+
+### 3. Restore credentials on subsequent requests
+
+```ruby
+client.set_credentials(
+  Mobiscroll::Connect::TokenResponse.new(
+    access_token:  session[:access_token],
+    refresh_token: session[:refresh_token],
+    token_type:    'Bearer'
+  )
+)
+```
+
+### 4. Check connection status
+
+```ruby
+status = client.auth.get_connection_status
+status.connections.each do |provider, accounts|
+  accounts.each { |a| puts "#{provider}: #{a.display}" }
+end
+```
+
+### 5. Disconnect a provider
+
+```ruby
+client.auth.disconnect(provider: Mobiscroll::Connect::Provider::GOOGLE)
+```
+
+## Token refresh
+
+The SDK automatically refreshes expired access tokens. When a request returns 401 and a `refresh_token` is available, the SDK:
+
+1. Calls `POST /oauth/token` with `grant_type=refresh_token` (exactly once).
+2. Retries the original request with the new token.
+3. Raises `AuthenticationError` if the refresh also fails.
+
+Concurrent 401s share a single in-flight refresh — only one `POST /oauth/token` is ever issued per `Client` instance at a time.
+
+To persist refreshed tokens (e.g., back to a session or database):
+
+```ruby
+client.on_tokens_refreshed do |tokens|
+  session[:access_token]  = tokens.access_token
+  session[:refresh_token] = tokens.refresh_token if tokens.refresh_token
+end
+```
+
+## Calendars
+
+```ruby
+calendars = client.calendars.list
+calendars.each do |cal|
+  puts "#{cal.provider} / #{cal.title} (#{cal.id})"
+end
+```
+
+## Events
+
+### List events
+
+```ruby
+result = client.events.list(
+  start:         '2024-01-01T00:00:00Z',
+  end:           '2024-03-31T23:59:59Z',
+  page_size:     50,
+  single_events: true,
+  calendar_ids:  { 'google' => ['primary'] }
+)
+result.events.each { |e| puts e.title }
+# result.next_page_token for pagination
+```
+
+### Create an event
+
+```ruby
+event = client.events.create(
+  provider:    Mobiscroll::Connect::Provider::GOOGLE,
+  calendar_id: 'primary',
+  title:       'Team Meeting',
+  start:       '2024-02-01T10:00:00Z',
+  end:         '2024-02-01T11:00:00Z',
+  description: 'Quarterly review',
+  recurrence:  Mobiscroll::Connect::RecurrenceRule.new(
+    frequency: 'WEEKLY',
+    interval:  1,
+    count:     10
+  )
+)
+puts event.id
+```
+
+### Update an event
+
+```ruby
+client.events.update(
+  provider:    'google',
+  calendar_id: 'primary',
+  event_id:    'evt-123',
+  title:       'Updated Title',
+  update_mode: 'this'
+)
+```
+
+### Delete an event
+
+```ruby
+client.events.delete(
+  provider:    'google',
+  calendar_id: 'primary',
+  event_id:    'evt-123',
+  delete_mode: 'all'
+)
+```
+
+## Error handling
+
+All errors are subclasses of `Mobiscroll::Connect::Error`:
+
+```ruby
+begin
+  client.calendars.list
+rescue Mobiscroll::Connect::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue Mobiscroll::Connect::RateLimitError => e
+  puts "Rate limited — retry after #{e.retry_after}s"
+rescue Mobiscroll::Connect::ValidationError => e
+  puts "Bad request: #{e.message}, details: #{e.details}"
+rescue Mobiscroll::Connect::NotFoundError
+  puts 'Resource not found'
+rescue Mobiscroll::Connect::ServerError => e
+  puts "Server error #{e.status_code}"
+rescue Mobiscroll::Connect::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Mobiscroll::Connect::Error => e
+  puts "SDK error: #{e.message} (#{e.code})"
+end
+```
+
+| Error class | HTTP status | Extra attributes |
+|---|---|---|
+| `AuthenticationError` | 401, 403 | — |
+| `ValidationError` | 400, 422 | `details` |
+| `NotFoundError` | 404 | — |
+| `RateLimitError` | 429 | `retry_after` (seconds) |
+| `ServerError` | 5xx | `status_code` |
+| `NetworkError` | transport | `cause` |
+
+## Minimal demo app
+
+See [`minimal-app/`](minimal-app/) for a Sinatra web app demonstrating the full OAuth flow. Run it with:
+
+```bash
+cd minimal-app
+bundle install
+cp .env.example .env
+bundle exec rackup -p 8080
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # tests
+bundle exec rubocop      # lint
+gem build mobiscroll-connect.gemspec
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/mobiscroll/connect/api_client.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'faraday'
+require 'json'
+require 'monitor'
+
+module Mobiscroll
+  module Connect
+    # Internal HTTP layer. Mirrors sdks/node/src/client.ts and sdks/go/transport.go:
+    # - injects `Authorization: Bearer <access_token>` on every API request
+    # - on 401 with a stored refresh_token, refreshes once and retries the original
+    #   call exactly once. Concurrent 401s share a single in-flight refresh.
+    # - maps non-2xx responses to typed errors via `Connect.map_response_error`.
+    #
+    # The token-exchange / refresh Faraday connection is held separately so it
+    # cannot recurse into the 401 retry loop.
+    class ApiClient
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+        @credentials = nil
+        @monitor = Monitor.new
+        @refresh_cond = @monitor.new_cond
+        @refresh_in_flight = false
+        @refresh_result = nil
+        @refresh_error = nil
+        @on_tokens_refreshed = config.on_tokens_refreshed
+
+        @api_conn = build_connection(api: true)
+        @token_conn = build_connection(api: false)
+      end
+
+      def set_credentials(tokens)
+        @monitor.synchronize { @credentials = tokens }
+      end
+
+      def credentials
+        @monitor.synchronize { @credentials }
+      end
+
+      def on_tokens_refreshed(&block)
+        @on_tokens_refreshed = block
+      end
+
+      def get(path, query: nil, headers: nil)
+        execute(:get, path, query: query, body: nil, headers: headers)
+      end
+
+      def post(path, body: nil, query: nil, headers: nil)
+        execute(:post, path, query: query, body: body, headers: headers)
+      end
+
+      def put(path, body: nil, query: nil, headers: nil)
+        execute(:put, path, query: query, body: body, headers: headers)
+      end
+
+      def delete(path, query: nil, headers: nil)
+        execute(:delete, path, query: query, body: nil, headers: headers)
+      end
+
+      # POST application/x-www-form-urlencoded against the token endpoint with
+      # Basic auth + CLIENT_ID header. Does not participate in the 401 retry
+      # loop because it uses `@token_conn`.
+      def post_form(path, form)
+        creds = Base64.strict_encode64("#{@config.client_id}:#{@config.client_secret}")
+        response = @token_conn.post(path.sub(%r{\A/}, '')) do |req|
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.headers['Authorization'] = "Basic #{creds}"
+          req.headers['CLIENT_ID'] = @config.client_id
+          req.body = URI.encode_www_form(form)
+        end
+        parsed = parse_body(response.body)
+        raise_for_status(response, parsed)
+        parsed
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+        raise NetworkError.new(e.message, cause: e)
+      end
+
+      private
+
+      def execute(method, path, query:, body:, headers:, retried: false)
+        response = perform(method, path, query: query, body: body, headers: headers)
+        parsed = parse_body(response.body)
+
+        if response.status == 401 && @credentials&.refresh_token && !retried
+          new_tokens = refresh_access_token!
+          raise AuthenticationError, 'Failed to refresh token' if new_tokens.nil?
+
+          return execute(method, path, query: query, body: body, headers: headers, retried: true)
+        end
+
+        raise_for_status(response, parsed)
+        parsed
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+        raise NetworkError.new(e.message, cause: e)
+      end
+
+      def perform(method, path, query:, body:, headers:)
+        @api_conn.public_send(method, path.sub(%r{\A/}, '')) do |req|
+          req.params.update(query) if query.is_a?(Hash) && !query.empty?
+          token = @credentials&.access_token
+          req.headers['Authorization'] = "Bearer #{token}" if token && !token.empty?
+          headers&.each { |k, v| req.headers[k] = v }
+          req.body = body.is_a?(String) ? body : JSON.generate(body) if body
+        end
+      end
+
+      def parse_body(body)
+        return nil if body.nil? || (body.respond_to?(:empty?) && body.empty?)
+        return body if body.is_a?(Hash) || body.is_a?(Array)
+
+        JSON.parse(body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def raise_for_status(response, parsed)
+        return if response.status < 400
+
+        err = Connect.map_response_error(response.status, parsed, response.headers)
+        raise(err) if err
+
+        raise Error, "HTTP #{response.status}"
+      end
+
+      # Refreshes the access token. Concurrent callers share one in-flight
+      # request — the first caller does the work, subsequent callers wait on
+      # the same condition variable and read the cached result. Returns the
+      # refreshed TokenResponse, or nil if refresh failed.
+      def refresh_access_token!
+        do_refresh = false
+        @monitor.synchronize do
+          if @refresh_in_flight
+            @refresh_cond.wait_while { @refresh_in_flight }
+            raise @refresh_error if @refresh_error
+
+            return @refresh_result
+          end
+
+          @refresh_in_flight = true
+          @refresh_result = nil
+          @refresh_error = nil
+          do_refresh = true
+        end
+
+        return unless do_refresh
+
+        begin
+          new_tokens = perform_refresh
+          @monitor.synchronize do
+            @credentials = (@credentials ? @credentials.merged_with(new_tokens) : new_tokens)
+            @refresh_result = @credentials
+          end
+          @on_tokens_refreshed&.call(@credentials)
+          @credentials
+        rescue StandardError => e
+          @monitor.synchronize { @refresh_error = e }
+          nil
+        ensure
+          @monitor.synchronize do
+            @refresh_in_flight = false
+            @refresh_cond.broadcast
+          end
+        end
+      end
+
+      def perform_refresh
+        rt = @credentials&.refresh_token
+        raise AuthenticationError, 'No refresh token available' if rt.nil? || rt.empty?
+
+        form = {
+          'grant_type' => 'refresh_token',
+          'refresh_token' => rt,
+          'redirect_uri' => @config.redirect_uri
+        }
+        parsed = post_form('/oauth/token', form)
+        TokenResponse.from_h(parsed)
+      end
+
+      def build_connection(api:)
+        Faraday.new(url: @config.base_url) do |f|
+          f.options.timeout = @config.timeout
+          f.options.open_timeout = @config.timeout
+          f.headers['Content-Type'] = 'application/json' if api
+          f.headers['Accept'] = 'application/json'
+        end
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/client.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    class Client
+      attr_reader :auth, :calendars, :events
+
+      def initialize(client_id:, client_secret:, redirect_uri:,
+                     base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                     on_tokens_refreshed: nil)
+        @config = Config.new(
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          base_url: base_url,
+          timeout: timeout,
+          on_tokens_refreshed: on_tokens_refreshed
+        )
+        @api_client = ApiClient.new(@config)
+        @auth = Resources::Auth.new(@config, @api_client)
+        @calendars = Resources::Calendars.new(@config, @api_client)
+        @events = Resources::Events.new(@config, @api_client)
+      end
+
+      def set_credentials(tokens)
+        @api_client.set_credentials(tokens)
+      end
+
+      def credentials
+        @api_client.credentials
+      end
+
+      def on_tokens_refreshed(&)
+        @api_client.on_tokens_refreshed(&)
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    DEFAULT_BASE_URL = 'https://connect.mobiscroll.com/api'
+    DEFAULT_TIMEOUT = 30
+
+    class Config
+      attr_reader :client_id, :client_secret, :redirect_uri, :base_url, :timeout
+      attr_accessor :on_tokens_refreshed
+
+      def initialize(client_id:, client_secret:, redirect_uri:,
+                     base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                     on_tokens_refreshed: nil)
+        raise Error, 'client_id is required' if client_id.nil? || client_id.empty?
+        raise Error, 'client_secret is required' if client_secret.nil? || client_secret.empty?
+        raise Error, 'redirect_uri is required' if redirect_uri.nil? || redirect_uri.empty?
+
+        @client_id = client_id
+        @client_secret = client_secret
+        @redirect_uri = redirect_uri
+        @base_url = base_url
+        @timeout = timeout
+        @on_tokens_refreshed = on_tokens_refreshed
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/errors.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    class Error < StandardError
+      attr_reader :code
+
+      def initialize(message = nil, code: nil)
+        super(message)
+        @code = code
+      end
+    end
+
+    class AuthenticationError < Error
+      def initialize(message = 'Authentication failed')
+        super(message, code: 'AUTHENTICATION_ERROR')
+      end
+    end
+
+    class NotFoundError < Error
+      def initialize(message = 'Resource not found')
+        super(message, code: 'NOT_FOUND_ERROR')
+      end
+    end
+
+    class ValidationError < Error
+      attr_reader :details
+
+      def initialize(message = 'Validation failed', details: nil)
+        super(message, code: 'VALIDATION_ERROR')
+        @details = details
+      end
+    end
+
+    class RateLimitError < Error
+      attr_reader :retry_after
+
+      def initialize(message = 'Rate limit exceeded', retry_after: nil)
+        super(message, code: 'RATE_LIMIT_ERROR')
+        @retry_after = retry_after
+      end
+    end
+
+    class ServerError < Error
+      attr_reader :status_code
+
+      def initialize(message = 'Server error', status_code: nil)
+        super(message, code: 'SERVER_ERROR')
+        @status_code = status_code
+      end
+    end
+
+    class NetworkError < Error
+      attr_reader :cause
+
+      def initialize(message = 'Network error', cause: nil)
+        super(message, code: 'NETWORK_ERROR')
+        @cause = cause
+      end
+    end
+
+    # Maps an HTTP response (status + body hash + headers) to the matching
+    # typed error. Returns nil for 2xx responses.
+    def self.map_response_error(status, body, headers)
+      message = body.is_a?(Hash) ? (body['message'] || body[:message]) : nil
+      message ||= "HTTP #{status}"
+
+      case status
+      when 401, 403
+        AuthenticationError.new(message)
+      when 404
+        NotFoundError.new(message)
+      when 400, 422
+        details = body.is_a?(Hash) ? (body['details'] || body[:details]) : nil
+        ValidationError.new(message, details: details)
+      when 429
+        retry_after = headers && (headers['retry-after'] || headers['Retry-After'])
+        retry_after_int = retry_after&.to_i
+        RateLimitError.new(message, retry_after: retry_after_int)
+      when 500..599
+        ServerError.new(message, status_code: status)
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/models.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    # OAuth2 token payload returned by the API.
+    TokenResponse = Struct.new(:access_token, :token_type, :expires_in, :refresh_token, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(
+          access_token: hash['access_token'] || hash[:access_token],
+          token_type: hash['token_type'] || hash[:token_type],
+          expires_in: hash['expires_in'] || hash[:expires_in],
+          refresh_token: hash['refresh_token'] || hash[:refresh_token]
+        )
+      end
+
+      # Overlay `incoming` on top of self, preserving the existing
+      # refresh_token if `incoming` omits one.
+      def merged_with(incoming)
+        return incoming if nil?
+
+        rt = incoming.refresh_token
+        rt = refresh_token if rt.nil? || rt.empty?
+        TokenResponse.new(
+          access_token: incoming.access_token,
+          token_type: incoming.token_type || token_type,
+          expires_in: incoming.expires_in || expires_in,
+          refresh_token: rt
+        )
+      end
+
+      def to_h
+        super.compact
+      end
+    end
+
+    # One connected account under a provider.
+    ConnectedAccount = Struct.new(:id, :display, 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])
+      end
+    end
+
+    # Result of Auth#get_connection_status. `connections` is keyed by lowercase
+    # provider name to match the API wire form.
+    ConnectionStatus = Struct.new(:connections, :limit_reached, keyword_init: true) do
+      def self.from_h(hash)
+        return new(connections: {}, limit_reached: false) if hash.nil?
+
+        raw = hash['connections'] || hash[:connections] || {}
+        connections = raw.each_with_object({}) do |(provider, accounts), acc|
+          acc[provider.to_s] = Array(accounts).map { |a| ConnectedAccount.from_h(a) }
+        end
+        new(connections: connections, limit_reached: hash['limitReached'] || hash[:limitReached] || false)
+      end
+    end
+
+    DisconnectResponse = 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
+
+    # A calendar exposed by one of the supported providers.
+    Calendar = Struct.new(:provider, :id, :title, :time_zone, :color, :description, :original, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(
+          provider: hash['provider'] || hash[:provider],
+          id: hash['id'] || hash[:id],
+          title: hash['title'] || hash[:title],
+          time_zone: hash['timeZone'] || hash[:timeZone] || hash['time_zone'],
+          color: hash['color'] || hash[:color],
+          description: hash['description'] || hash[:description],
+          original: hash['original'] || hash[:original]
+        )
+      end
+    end
+
+    Attendee = Struct.new(:email, :status, :organizer, keyword_init: true) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        new(
+          email: hash['email'] || hash[:email],
+          status: hash['status'] || hash[:status],
+          organizer: hash['organizer'] || hash[:organizer]
+        )
+      end
+
+      def to_h
+        result = { 'email' => email }
+        result['status'] = status unless status.nil?
+        result['organizer'] = organizer unless organizer.nil?
+        result
+      end
+    end
+
+    # An event returned by the API. Field set mirrors the Node SDK exactly.
+    CalendarEvent = Struct.new(
+      :provider, :id, :calendar_id, :title, :description, :start, :end_time, :all_day,
+      :recurring_event_id, :color, :location, :attendees, :custom, :conference,
+      :conference_data, :availability, :privacy, :status, :last_modified, :link, :original,
+      keyword_init: true
+    ) do
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        attendees = hash['attendees'] || hash[:attendees]
+        attendees = attendees.map { |a| Attendee.from_h(a) } if attendees.is_a?(Array)
+
+        new(
+          provider: hash['provider'] || hash[:provider],
+          id: hash['id'] || hash[:id],
+          calendar_id: hash['calendarId'] || hash[:calendarId],
+          title: hash['title'] || hash[:title],
+          description: hash['description'] || hash[:description],
+          start: hash['start'] || hash[:start],
+          end_time: hash['end'] || hash[:end],
+          all_day: hash['allDay'] || hash[:allDay],
+          recurring_event_id: hash['recurringEventId'] || hash[:recurringEventId],
+          color: hash['color'] || hash[:color],
+          location: hash['location'] || hash[:location],
+          attendees: attendees,
+          custom: hash['custom'] || hash[:custom],
+          conference: hash['conference'] || hash[:conference],
+          conference_data: hash['conferenceData'] || hash[:conferenceData],
+          availability: hash['availability'] || hash[:availability],
+          privacy: hash['privacy'] || hash[:privacy],
+          status: hash['status'] || hash[:status],
+          last_modified: hash['lastModified'] || hash[:lastModified],
+          link: hash['link'] || hash[:link],
+          original: hash['original'] || hash[:original]
+        )
+      end
+    end
+
+    # iCal-style recurrence rule. `frequency` is one of "DAILY", "WEEKLY",
+    # "MONTHLY", "YEARLY".
+    RecurrenceRule = Struct.new(
+      :frequency, :interval, :count, :until, :by_day, :by_month_day, :by_month,
+      keyword_init: true
+    ) do
+      def to_wire
+        wire = { 'frequency' => frequency }
+        wire['interval'] = interval unless interval.nil?
+        wire['count'] = count unless count.nil?
+        wire['until'] = self[:until] unless self[:until].nil?
+        wire['byDay'] = by_day unless by_day.nil?
+        wire['byMonthDay'] = by_month_day unless by_month_day.nil?
+        wire['byMonth'] = by_month unless by_month.nil?
+        wire
+      end
+    end
+
+    # Paginated response from Events#list.
+    EventsListResponse = Struct.new(:events, :page_size, :next_page_token, keyword_init: true) do
+      def self.from_h(hash)
+        return new(events: [], page_size: nil, next_page_token: nil) if hash.nil?
+
+        events = (hash['events'] || hash[:events] || []).map { |e| CalendarEvent.from_h(e) }
+        new(
+          events: events,
+          page_size: hash['pageSize'] || hash[:pageSize],
+          next_page_token: hash['nextPageToken'] || hash[:nextPageToken]
+        )
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/provider.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    module Provider
+      GOOGLE = 'google'
+      MICROSOFT = 'microsoft'
+      APPLE = 'apple'
+      CALDAV = 'caldav'
+
+      ALL = [GOOGLE, MICROSOFT, APPLE, CALDAV].freeze
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Mobiscroll
+  module Connect
+    module Resources
+      class Auth
+        def initialize(config, api_client)
+          @config = config
+          @api_client = api_client
+        end
+
+        def generate_auth_url(user_id:, scope: nil, state: nil, providers: nil)
+          params = {
+            'response_type' => 'code',
+            'client_id' => @config.client_id,
+            'redirect_uri' => @config.redirect_uri,
+            'user_id' => user_id
+          }
+          params['scope'] = scope if scope
+          params['state'] = state if state
+
+          query = URI.encode_www_form(params)
+
+          if providers && !providers.empty?
+            provider_params = providers.map { |p| "providers=#{URI.encode_www_form_component(p)}" }.join('&')
+            query = "#{query}&#{provider_params}"
+          end
+
+          "#{@config.base_url}/oauth/authorize?#{query}"
+        end
+
+        def get_token(code)
+          form = {
+            'grant_type' => 'authorization_code',
+            'code' => code,
+            'redirect_uri' => @config.redirect_uri
+          }
+          parsed = @api_client.post_form('/oauth/token', form)
+          tokens = TokenResponse.from_h(parsed)
+          @api_client.set_credentials(tokens)
+          tokens
+        end
+
+        def set_credentials(tokens)
+          @api_client.set_credentials(tokens)
+        end
+
+        def get_connection_status
+          begin
+            parsed = @api_client.get('/oauth/connection-status')
+          rescue NotFoundError
+            parsed = @api_client.get('/connection-status')
+          end
+          ConnectionStatus.from_h(parsed)
+        end
+
+        def disconnect(provider:, account: nil)
+          query = { 'provider' => provider }
+          query['account'] = account if account
+
+          begin
+            parsed = @api_client.post('/oauth/disconnect', query: query, body: {})
+          rescue NotFoundError
+            parsed = @api_client.post('/disconnect', query: query, body: {})
+          end
+          DisconnectResponse.from_h(parsed)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    module Resources
+      class Calendars
+        def initialize(_config, api_client)
+          @api_client = api_client
+        end
+
+        def list
+          parsed = @api_client.get('/calendars')
+          return [] if parsed.nil?
+
+          Array(parsed).map { |c| Calendar.from_h(c) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Mobiscroll
+  module Connect
+    module Resources
+      class Events
+        def initialize(_config, api_client)
+          @api_client = api_client
+        end
+
+        def list(start: nil, end: nil, calendar_ids: nil, page_size: nil,
+                 next_page_token: nil, single_events: nil)
+          end_time = binding.local_variable_get(:end)
+          query = {}
+          query['start'] = start if start
+          query['end'] = end_time if end_time
+          query['pageSize'] = page_size if page_size
+          query['nextPageToken'] = next_page_token if next_page_token
+          query['singleEvents'] = single_events.to_s unless single_events.nil?
+
+          if calendar_ids && !calendar_ids.empty?
+            wire = calendar_ids.transform_keys(&:to_s)
+            query['calendarIds'] = JSON.generate(wire)
+          end
+
+          parsed = @api_client.get('/events', query: query)
+          EventsListResponse.from_h(parsed)
+        end
+
+        def create(provider:, calendar_id:, title:, start:, end:, **opts)
+          end_time = binding.local_variable_get(:end)
+          body = build_event_body(opts.merge(
+                                    provider: provider,
+                                    calendar_id: calendar_id,
+                                    title: title,
+                                    start: start,
+                                    end: end_time
+                                  ))
+          parsed = @api_client.post('/event', body: JSON.generate(body))
+          CalendarEvent.from_h(parsed)
+        end
+
+        def update(provider:, calendar_id:, event_id:, **opts)
+          body = build_event_body(opts.merge(
+                                    provider: provider,
+                                    calendar_id: calendar_id,
+                                    event_id: event_id
+                                  ))
+          parsed = @api_client.put('/event', body: JSON.generate(body))
+          CalendarEvent.from_h(parsed)
+        end
+
+        def delete(provider:, calendar_id:, event_id:, recurring_event_id: nil, delete_mode: nil)
+          query = {
+            'provider' => provider,
+            'calendarId' => calendar_id,
+            'eventId' => event_id
+          }
+          query['recurringEventId'] = recurring_event_id if recurring_event_id
+          query['deleteMode'] = delete_mode if delete_mode
+
+          @api_client.delete('/event', query: query)
+          nil
+        end
+
+        private
+
+        def build_event_body(params)
+          body = {}
+          body['provider'] = params[:provider] if params.key?(:provider)
+          body['calendarId'] = params[:calendar_id] if params.key?(:calendar_id)
+          body['eventId'] = params[:event_id] if params.key?(:event_id)
+          body['title'] = params[:title] if params.key?(:title)
+          body['start'] = params[:start] if params.key?(:start)
+          body['end'] = params[:end] if params.key?(:end)
+          body['allDay'] = params[:all_day] if params.key?(:all_day)
+          body['description'] = params[:description] if params.key?(:description)
+          body['color'] = params[:color] if params.key?(:color)
+          body['location'] = params[:location] if params.key?(:location)
+          body['recurringEventId'] = params[:recurring_event_id] if params.key?(:recurring_event_id)
+          body['updateMode'] = params[:update_mode] if params.key?(:update_mode)
+          body['availability'] = params[:availability] if params.key?(:availability)
+          body['privacy'] = params[:privacy] if params.key?(:privacy)
+
+          if params.key?(:recurrence)
+            body['recurrence'] =
+              params[:recurrence].is_a?(RecurrenceRule) ? params[:recurrence].to_wire : params[:recurrence]
+          end
+
+          if params.key?(:attendees)
+            body['attendees'] = params[:attendees].map { |a| a.is_a?(Attendee) ? a.to_h : a }
+          end
+
+          body['conference'] = params[:conference] if params.key?(:conference)
+          body['custom'] = params[:custom] if params.key?(:custom)
+          body
+        end
+      end
+    end
+  end
+end

data/lib/mobiscroll/connect/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mobiscroll
+  module Connect
+    VERSION = '1.0.0'
+  end
+end

data/lib/mobiscroll/connect.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'connect/version'
+require_relative 'connect/errors'
+require_relative 'connect/provider'
+require_relative 'connect/config'
+require_relative 'connect/models'
+require_relative 'connect/api_client'
+require_relative 'connect/resources/auth'
+require_relative 'connect/resources/calendars'
+require_relative 'connect/resources/events'
+require_relative 'connect/client'
+
+module Mobiscroll
+  module Connect
+  end
+end

data/lib/mobiscroll-connect.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'mobiscroll/connect'

data/mobiscroll-connect.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'lib/mobiscroll/connect/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'mobiscroll-connect'
+  spec.version     = Mobiscroll::Connect::VERSION
+  spec.authors     = ['Mobiscroll']
+  spec.email       = ['support@mobiscroll.com']
+
+  spec.summary     = 'Official Ruby SDK for the Mobiscroll Connect API.'
+  spec.description = 'Ruby client for the Mobiscroll Connect API. Unified ' \
+                     'OAuth, calendars, and events across Google Calendar, ' \
+                     'Microsoft Outlook, Apple Calendar, and CalDAV.'
+  spec.homepage    = 'https://mobiscroll.com/connect'
+  spec.license     = 'MIT'
+
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks',
+    'bug_tracker_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/issues',
+    'changelog_uri' => 'https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  spec.files = Dir[
+    'lib/**/*.rb',
+    'README.md',
+    'LICENSE',
+    'mobiscroll-connect.gemspec'
+  ]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'base64', '~> 0.2'
+  spec.add_dependency 'faraday', '~> 2.9'
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.65'
+  spec.add_development_dependency 'webmock', '~> 3.23'
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: mobiscroll-connect
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mobiscroll
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Ruby client for the Mobiscroll Connect API. Unified OAuth, calendars,
+  and events across Google Calendar, Microsoft Outlook, Apple Calendar, and CalDAV.
+email:
+- support@mobiscroll.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mobiscroll-connect.rb
+- lib/mobiscroll/connect.rb
+- lib/mobiscroll/connect/api_client.rb
+- lib/mobiscroll/connect/client.rb
+- lib/mobiscroll/connect/config.rb
+- lib/mobiscroll/connect/errors.rb
+- lib/mobiscroll/connect/models.rb
+- lib/mobiscroll/connect/provider.rb
+- lib/mobiscroll/connect/resources/auth.rb
+- lib/mobiscroll/connect/resources/calendars.rb
+- lib/mobiscroll/connect/resources/events.rb
+- lib/mobiscroll/connect/version.rb
+- mobiscroll-connect.gemspec
+homepage: https://mobiscroll.com/connect
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://mobiscroll.com/connect
+  source_code_uri: https://github.com/acidb/mobiscroll-connect-sdks
+  bug_tracker_uri: https://github.com/acidb/mobiscroll-connect-sdks/issues
+  changelog_uri: https://github.com/acidb/mobiscroll-connect-sdks/blob/main/sdks/ruby/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+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: 3.5.3
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Mobiscroll Connect API.
+test_files: []