mural-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 35d1d5b409d40946faea660284f87875d36785f57278c967c93a645effe6fa24
+  data.tar.gz: 589cdad5b6ef75573fbca62b86de32b43bc084723c4c3a4a8a7589d46e81b82d
+SHA512:
+  metadata.gz: a2ed7a6155ab38a55199c17442a07dfb23db5e2191df44096668b1ec73d52a860b80abd0e62439611d726b0f4e95e8eb29e6e75c8b72b840a0ee684fb5d74cf8
+  data.tar.gz: 7ca63988d68d1f4c3e9099121229582244295aa605e4928c71cdee185432aad202c3206ba457299ddaf41de40112703340158033a0ab3da183ab05b45e3f0201

data/.github/workflows/ruby.yml

@@ -0,0 +1,28 @@
+name: Ruby
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['3.2', '3.3', '3.4']
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run tests
+      run: bundle exec rake

data/.ruby-version

@@ -0,0 +1 @@
+3.2.9

data/README.md

@@ -0,0 +1,126 @@
+# Mural Ruby
+
+Ruby library for the [Mural](https://app.mural.co) public API.
+
+## Installation
+
+```sh
+git checkout https://github.com/mickaelpham/mural-ruby
+cd mural-ruby
+bundle install
+```
+
+## Authorization
+
+1. [Register a new app][register-app] and gather your `client_id` and
+   `client_secret`. For the scopes, pick the minimum required for your
+   application.
+
+2. Create a `.env` file with the following template and fill in
+   `MURAL_CLIENT_ID` and `MURAL_CLIENT_SECRET` with those values:
+
+```
+MURAL_CLIENT_ID=
+MURAL_CLIENT_SECRET=
+MURAL_SCOPE=
+MURAL_REDIRECT_URI=http://localhost:4567/callback
+MURAL_HOST=app.mural.co
+```
+
+3. Run the script to request your access and refresh tokens:
+
+```sh
+bin/authorize
+```
+
+4. Start the console:
+
+```sh
+bin/console
+```
+
+5. From the console, create a client instance and start using it, e.g.:
+
+```sh
+irb(main):001> mural = Mural::Client.from_env
+=>
+#<Mural::Client:0x0000000120baa740
+...
+irb(main):002> mural.users.current_user
+=>
+#<Mural::CurrentUser:0x0000000124614bd8
+ @avatar="<AVATAR_URL>",
+ @company_id=nil,
+ @company_name=nil,
+ @created_on=1753301275000,
+ @email="<USER_EMAIL>",
+ @first_name="<USER_FIRST_NAME>",
+ @id="=<USER_ID>",
+ @last_active_workspace="<USER_WORKSPACE>",
+ @last_name="<USER_LAST_NAME>",
+ @type="member">
+```
+
+## Usage
+
+### Upload a file to a mural
+
+To upload a `my.pdf` file that's located in the same directory as where you
+are running the script:
+
+```rb
+MURAL_ID = 'workspace-1.mural-1'
+
+client = Mural::Client.from_env
+
+# Create an asset, receive an URL to upload the content to.
+asset = client.mural_content.create_asset(
+  MURAL_ID,
+  file_extension: 'pdf',
+  asset_type: 'file'
+)
+
+# Upload the asset to the received URL.
+request = Net::HTTP::Put.new(uri)
+request['x-ms-blob-type'] = asset.headers.blob_type
+
+path = File.expand_path('./my.pdf', __dir__)
+request.body = File.read(path)
+
+Net::HTTP.start(
+  uri.hostname, uri.port, use_ssl: uri.scheme == 'https'
+) do |http|
+  http.request request
+end
+
+# Create a `file` widget on the mural to display the asset preview.
+params = Mural::Widget::CreateFileParams.new.tap do |params|
+  params.name = asset.name
+  params.x = 250
+  params.y = 0
+end
+
+client.mural_content.create_file(MURAL_ID, params)
+```
+
+## Known limitations
+
+- `DrawWidget`, AKA sketches, are not returned by the `GET widgets` endpoint.
+
+![draw widget example](./img/draw-widget.png)
+
+- Similarly, `InkingWidget`, AKA drawings, are not returned by the endpoint.
+
+![inking widget example](./img/inking-widget.png)
+
+- Mind maps are smart widgets, they are simply a collection of text and arrow
+  widgets. There are no specific `type` for a mind map in the API.
+
+![mind map example](./img/mind-map.png)
+
+- Likewise, smart planners are collection of widgets, and the API doesn't
+  specify anything about them.
+
+![smart planner example](./img/smart-planner.png)
+
+[register-app]: https://developers.mural.co/public/docs/register-your-app

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+require 'rubocop/rake_task'
+
+Minitest::TestTask.create
+RuboCop::RakeTask.new
+
+desc 'Run the test suite and gather code coverage'
+task :coverage do
+  ENV['COVERAGE'] = '1'
+  Rake::Task['test'].invoke
+end
+
+task default: %i[test rubocop]

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org/>

data/lib/mural/asset.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mural
+  class Asset
+    include Mural::Codec
+
+    # https://developers.mural.co/public/reference/createasset
+    define_attributes(
+      name: 'name',
+      url: 'url',
+      headers: 'headers'
+    )
+
+    def self.decode(json)
+      super.tap do |asset_url|
+        asset_url.headers = Headers.decode(asset_url.headers)
+      end
+    end
+
+    class Headers
+      include Mural::Codec
+
+      define_attributes(blob_type: 'x-ms-blob-type')
+    end
+  end
+end

data/lib/mural/client/authentication.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    module Authentication
+      def authorize_url
+        URI::HTTPS.build(
+          host: host,
+          path: '/api/public/v1/authorization/oauth2/',
+          query: URI.encode_www_form(authorize_query)
+        ).to_s
+      end
+
+      def request_token(code)
+        uri = URI::HTTPS.build(
+          host: host,
+          path: '/api/public/v1/authorization/oauth2/token'
+        )
+
+        res = Net::HTTP.post_form(uri, request_token_payload(code))
+        data = JSON.parse res.body
+
+        @access_token = data['access_token']
+        @refresh_token = data['refresh_token']
+
+        data
+      end
+
+      def refresh
+        uri = URI::HTTPS.build(
+          host: host,
+          path: '/api/public/v1/authorization/oauth2/token'
+        )
+
+        res = Net::HTTP.post_form(uri, refresh_token_payload)
+        json = JSON.parse res.body
+
+        @access_token = json['access_token']
+        @refresh_token = json['refresh_token']
+
+        nil
+      end
+
+      private
+
+      def authorize_query
+        {
+          client_id: client_id,
+          redirect_uri: redirect_uri,
+          scope: scope,
+          response_type: 'code'
+        }
+      end
+
+      def request_token_payload(code)
+        {
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          code: code,
+          grant_type: 'authorization_code'
+        }
+      end
+
+      def refresh_token_payload
+        {
+          client_id: client_id,
+          client_secret: client_secret,
+          refresh_token: refresh_token,
+          grant_type: 'refresh_token'
+        }
+      end
+    end
+  end
+end

data/lib/mural/client/mural_content/files.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    class MuralContent
+      module Files
+        # https://developers.mural.co/public/reference/createfile
+        def create_file(mural_id, params)
+          json = post(
+            "/api/public/v1/murals/#{mural_id}/widgets/file",
+            params.encode
+          )
+
+          Mural::Widget::File.decode(json['value'])
+        end
+
+        # https://developers.mural.co/public/reference/getmuralfilewidgets
+        def list_files(mural_id, next_page: nil)
+          json = get(
+            "/api/public/v1/murals/#{mural_id}/widgets/files",
+            { next: next_page }
+          )
+
+          files = json['value'].map { |f| Mural::Widget::File.decode(f) }
+          [files, json['next']]
+        end
+
+        # https://developers.mural.co/public/reference/updatefile
+        def update_file(mural_id, widget_id:, update_file_params:)
+          json = patch(
+            "/api/public/v1/murals/#{mural_id}/widgets/file/#{widget_id}",
+            update_file_params.encode
+          )
+
+          Mural::Widget::File.decode(json['value'])
+        end
+      end
+    end
+  end
+end

data/lib/mural/client/mural_content/sticky_notes.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    class MuralContent
+      module StickyNotes
+        # https://developers.mural.co/public/reference/createstickynote
+        def create_sticky_notes(mural_id, create_sticky_note_params)
+          json = post(
+            "/api/public/v1/murals/#{mural_id}/widgets/sticky-note",
+            [*create_sticky_note_params].map(&:encode)
+          )
+
+          json['value'].map { |s| Mural::Widget::StickyNote.decode(s) }
+        end
+
+        # https://developers.mural.co/public/reference/updatestickynote
+        def update_sticky_note(mural_id, widget_id, update_sticky_note_params)
+          json = patch(
+            "/api/public/v1/murals/#{mural_id}/widgets/sticky-note" \
+            "/#{widget_id}",
+            update_sticky_note_params.encode
+          )
+
+          Mural::Widget::StickyNote.decode(json['value'])
+        end
+      end
+    end
+  end
+end

data/lib/mural/client/mural_content/tags.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    class MuralContent
+      module Tags
+        # https://developers.mural.co/public/reference/getmuraltags
+        def list_tags(mural_id)
+          json = get("/api/public/v1/murals/#{mural_id}/tags")
+
+          json['value'].map { |tag| Mural::Tag.decode(tag) }
+        end
+
+        # https://developers.mural.co/public/reference/gettagbyid
+        def retrieve_tag(mural_id, tag_id)
+          json = get("/api/public/v1/murals/#{mural_id}/tags/#{tag_id}")
+
+          Mural::Tag.decode(json['value'])
+        end
+
+        # https://developers.mural.co/public/reference/createmuraltag
+        def create_tag(mural_id, create_tag_params)
+          json = post(
+            "/api/public/v1/murals/#{mural_id}/tags",
+            create_tag_params.encode
+          )
+
+          Mural::Tag.decode(json['value'])
+        end
+
+        # https://developers.mural.co/public/reference/updatetagbyid
+        def update_tag(mural_id, tag_id, update_tag_params)
+          json = patch(
+            "/api/public/v1/murals/#{mural_id}/tags/#{tag_id}",
+            update_tag_params.encode
+          )
+
+          Mural::Tag.decode(json['value'])
+        end
+
+        # https://developers.mural.co/public/reference/deletetagbyid
+        def destroy_tag(mural_id, tag_id)
+          delete("/api/public/v1/murals/#{mural_id}/tags/#{tag_id}")
+        end
+      end
+    end
+  end
+end

data/lib/mural/client/mural_content/widgets.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    class MuralContent
+      module Widgets
+        # https://developers.mural.co/public/reference/getmuralwidgets
+        def list_widgets(mural_id, type: nil, parent_id: nil, next_page: nil)
+          json = get(
+            "/api/public/v1/murals/#{mural_id}/widgets",
+            { type: type, parentId: parent_id, next: next_page }
+          )
+
+          widgets = json['value'].map { |w| Mural::Widget.decode(w) }
+
+          [widgets, json['next']]
+        end
+
+        # https://developers.mural.co/public/reference/getmuralwidget
+        def retrieve_widget(mural_id, widget_id)
+          json = get("/api/public/v1/murals/#{mural_id}/widgets/#{widget_id}")
+
+          Mural::Widget.decode(json['value'])
+        end
+
+        # https://developers.mural.co/public/reference/deletewidgetbyid
+        def destroy_widget(mural_id, widget_id)
+          delete("/api/public/v1/murals/#{mural_id}/widgets/#{widget_id}")
+        end
+      end
+    end
+  end
+end

data/lib/mural/client/mural_content.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    class MuralContent
+      extend Forwardable
+
+      include Files
+      include StickyNotes
+      include Tags
+      include Widgets
+
+      def_delegators :@client, :get, :post, :patch, :delete
+
+      def initialize(client)
+        @client = client
+      end
+
+      # https://developers.mural.co/public/reference/createasset
+      def create_asset(mural_id, file_extension:, asset_type: nil)
+        json = post(
+          "/api/public/v1/murals/#{mural_id}/assets",
+          { assetType: asset_type, fileExtension: file_extension }
+        )
+
+        Mural::Asset.decode(json['value'])
+      end
+    end
+  end
+end

data/lib/mural/client/murals.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Mural
+  class Client
+    class Murals
+      extend Forwardable
+
+      def_delegators :@client, :get, :post, :patch, :delete
+
+      def initialize(client)
+        @client = client
+      end
+
+      # https://developers.mural.co/public/reference/getmuralbyid
+      def retrieve(mural_id)
+        json = get("/api/public/v1/murals/#{mural_id}")
+
+        ::Mural::MuralBoard.decode(json['value'])
+      end
+
+      # https://developers.mural.co/public/reference/createmural
+      def create(create_params)
+        json = post('/api/public/v1/murals', create_params.encode)
+
+        ::Mural::MuralBoard.decode(json['value'])
+      end
+
+      # https://developers.mural.co/public/reference/updatemuralbyid
+      def update(mural_id, update_params)
+        json = patch("/api/public/v1/murals/#{mural_id}", update_params.encode)
+
+        ::Mural::MuralBoard.decode(json['value'])
+      end
+
+      # https://developers.mural.co/public/reference/deletemuralbyid
+      def destroy(mural_id)
+        delete("/api/public/v1/murals/#{mural_id}")
+      end
+
+      # https://developers.mural.co/public/reference/exportmural
+      def export(mural_id, download_format: 'pdf')
+        json = post(
+          "/api/public/v1/murals/#{mural_id}/export",
+          { downloadFormat: download_format }
+        )
+
+        json.dig('value', 'exportId')
+      end
+
+      # https://developers.mural.co/public/reference/exporturlmural
+      def export_url(mural_id, export_id)
+        json = get("/api/public/v1/murals/#{mural_id}/exports/#{export_id}")
+
+        ::Mural::MuralExport.decode(json['value'])
+      end
+
+      # https://developers.mural.co/public/reference/duplicatemural
+      def duplicate(mural_id, duplicate_params)
+        json = post(
+          "/api/public/v1/murals/#{mural_id}/duplicate", duplicate_params.encode
+        )
+
+        ::Mural::MuralBoard.decode(json['value'])
+      end
+
+      # https://developers.mural.co/public/reference/getworkspacemurals
+      def for_workspace(workspace_id, status: nil, sort_by: nil, next_page: nil)
+        json = get(
+          "/api/public/v1/workspaces/#{workspace_id}/murals",
+          { status: status, sortBy: sort_by, next: next_page }
+        )
+
+        murals = json['value'].map do |json_mural|
+          ::Mural::MuralBoard.decode(json_mural)
+        end
+
+        [murals, json['next']]
+      end
+
+      # https://developers.mural.co/public/reference/getworkspacerecentmurals
+      def recently_opened_in_workspace(workspace_id, next_page: nil)
+        json = get(
+          "/api/public/v1/workspaces/#{workspace_id}/murals/recent",
+          { next: next_page }
+        )
+
+        murals = json['value'].map do |json_mural|
+          ::Mural::MuralBoard.decode(json_mural)
+        end
+
+        [murals, json['next']]
+      end
+
+      # https://developers.mural.co/public/reference/getroommurals
+      def for_room( # rubocop:disable Metrics/MethodLength
+        room_id,
+        folder_id: nil,
+        status: nil,
+        sort_by: nil,
+        next_page: nil
+      )
+        json = get(
+          "/api/public/v1/rooms/#{room_id}/murals",
+          {
+            folderId: folder_id,
+            status: status,
+            sortBy: sort_by,
+            next: next_page
+          }
+        )
+
+        murals = json['value'].map do |json_mural|
+          ::Mural::MuralBoard.decode(json_mural)
+        end
+
+        [murals, json['next']]
+      end
+
+      # https://developers.mural.co/public/reference/muralaccessinfo
+      def access_information(mural_id, mural_state:)
+        json = post(
+          "/api/public/v1/murals/#{mural_id}/access-info",
+          { muralState: mural_state }
+        )
+
+        ::Mural::MuralBoard::AccessInformation.decode(json['value'])
+      end
+
+      # https://developers.mural.co/public/reference/resetvisitorlink
+      def reset_visitor_link(mural_id)
+        json =
+          post("/api/public/v1/murals/#{mural_id}/visitor-settings/reset-link")
+
+        ::Mural::MuralBoard::VisitorsSettings.decode(json['value'])
+      end
+    end
+  end
+end