sharepoint_api 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f8c46ee759a2cb1b84211e88137406512de21a48a4a759d109097c54273259f
+  data.tar.gz: 444dbfaee8eff930e0a030ad5cb5450cedc71268eb0ff05ab346af8297c032c9
+SHA512:
+  metadata.gz: e1f6ff11efc7b37027928325908e1b05cb5318d1ff4f84fb0a0a10b2253544e54606c7c7043ea1d40257469443412dddebb268629a9cd118331fa4453702b5cb
+  data.tar.gz: 9f7b3f87f4eaeaf4271a4266ae5f4a054805a5967c471bffde71ca10649e099ce917db9c1aede8e3d8e8dd099ce091f510149ef110a0df3276cf1189bb505b55

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+sharepoint_api-*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,90 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  Exclude:
+    - bin/*
+  TargetRubyVersion: 2.6
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: false
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundMethodBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude: ['**/*.rake']
+  IgnoredMethods: ['describe', 'context', 'it', 'FactoryBot.define', 'factory']
+
+Metrics/MethodLength:
+  Max: 20
+
+Style/AndOr:
+  EnforcedStyle: conditionals
+
+Style/BlockDelimiters:
+  EnforcedStyle: braces_for_chaining
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/ExponentialNotation:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/SlicingWithRange:
+  Enabled: true
+
+RSpec/LetSetup:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 4

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+## [1.0.0] - 2020-12-07
+  * Initial Release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at andrew.kalek@anlek.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in sharepoint_api.gemspec
+gemspec
+
+gem 'faker'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.6'
+gem 'rspec-collection_matchers'
+gem 'rubocop', '~> 1.5'
+gem 'rubocop-rspec', '~> 2.0'

data/Gemfile.lock

@@ -0,0 +1,76 @@
+PATH
+  remote: .
+  specs:
+    SharepointApi (0.1.0)
+      addressable (~> 2.7)
+      proof-sharepoint-ruby (~> 1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.1)
+    concurrent-ruby (1.1.7)
+    curb (0.9.10)
+    diff-lcs (1.4.4)
+    faker (2.15.1)
+      i18n (>= 1.6, < 2)
+    i18n (1.8.5)
+      concurrent-ruby (~> 1.0)
+    parallel (1.20.1)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    proof-sharepoint-ruby (1.0.0)
+      curb (~> 0.8, <= 0.9.10)
+    public_suffix (4.0.6)
+    rainbow (3.0.0)
+    rake (13.0.1)
+    regexp_parser (2.0.0)
+    rexml (3.2.4)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-collection_matchers (1.2.0)
+      rspec-expectations (>= 2.99.0.beta1)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
+    rubocop (1.5.2)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.2.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.3.0)
+      parser (>= 2.7.1.5)
+    rubocop-rspec (2.0.1)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
+    ruby-progressbar (1.10.1)
+    unicode-display_width (1.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  SharepointApi!
+  faker
+  rake (~> 13.0)
+  rspec (~> 3.6)
+  rspec-collection_matchers
+  rubocop (~> 1.5)
+  rubocop-rspec (~> 2.0)
+
+BUNDLED WITH
+   1.17.2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Andrew Kalek
+
+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,44 @@
+# SharepointApi
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/sharepoint_api`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sharepoint_api'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install sharepoint_api
+
+## Usage
+
+TODO: Write usage instructions here
+
+## 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.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/anlek/sharepoint_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/anlek/sharepoint_api/blob/master/CODE_OF_CONDUCT.md).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the SharepointApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/anlek/sharepoint_api/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "sharepoint_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/sharepoint_api.rb

@@ -0,0 +1,108 @@
+require 'addressable'
+require 'forwardable'
+require 'sharepoint-http-auth'
+require 'logger'
+require 'sharepoint-ruby'
+
+require_relative 'sharepoint_api/sharepoint_error'
+require_relative 'sharepoint_api/version'
+require_relative 'sharepoint_api/items'
+require_relative 'sharepoint_api/file_info'
+require_relative 'sharepoint_api/filename_cleaner'
+require_relative 'sharepoint_api/file_system'
+require_relative 'sharepoint_api/permissions'
+require_relative 'sharepoint_api/users'
+require_relative 'sharepoint_api/version_converter'
+
+class SharepointApi
+  extend Forwardable
+  include SharepointApi::Items
+  include SharepointApi::FileSystem
+  include SharepointApi::Permissions
+  include SharepointApi::Users
+
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= begin
+        logger = Logger.new($stdout)
+        logger.level = Logger::WARN
+        logger
+      end
+    end
+
+    def log_as(method, exception_or_message, level: :info)
+      message = if exception_or_message.respond_to?(:message)
+                  exception_or_message.message
+                else
+                  exception_or_message
+                end
+
+      logger.send(level, "#{name}: #{method}: #{message}")
+    end
+  end
+
+  attr_accessor :library_name
+  attr_reader :site, :host
+
+  def_delegators :site, :protocol
+  def_delegators 'self.class', :logger, :log_as, :logger=
+
+  def initialize(library_name: '', **config)
+    @library_name = library_name
+    @host = config.fetch(:host)
+    @username = config.fetch(:username)
+    @password = config.fetch(:password)
+    @site_name = config[:site_name] || ''
+    @ntlm = config[:ntlm] || false
+    @verbose = config[:verbose] || false
+    @login_name_extractor = config[:login_name_extractor]
+
+    @site = build_connection
+  end
+
+  def site_relative_path(path, preview: false)
+    file_path = [
+      library_name, path
+    ].reject{ |p| p.nil? || p == '' }.join('/')
+    encode_path(file_path, preview: preview)
+  end
+
+  def server_relative_path(path)
+    "/#{site_path}/#{site_relative_path(path)}"
+  end
+
+  def site_path
+    @site.name
+  end
+
+  def base_path
+    "#{protocol}://#{host}/#{site_path}"
+  end
+
+  def encode_path(path, preview: false)
+    path = Addressable::URI.encode(path)
+    path.gsub!(/'/, '%27%27') unless preview
+    path.gsub!('+', '%2B')
+    path
+  end
+
+  def login_name(*args, **kwargs)
+    @login_name_extractor.call(*args, **kwargs)
+  end
+
+  #######
+  private
+  #######
+
+  def build_connection
+    site = Sharepoint::Site.new(@host, @site_name)
+    site.verbose = @verbose
+
+    site.session = Sharepoint::HttpAuth::Session.new(site) if @ntlm
+    site.session.authenticate(@username, @password) # custom STS?
+
+    site
+  end
+end

data/lib/sharepoint_api/file_info.rb

@@ -0,0 +1,67 @@
+class SharepointApi
+  class FileInfo
+    extend Forwardable
+    attr_reader :version, :version_id, :file, :updated_at
+
+    def_delegator :file, :name
+
+    def self.wrap(sharepoint_file)
+      return nil unless sharepoint_file
+
+      new(sharepoint_file)
+    end
+
+    def initialize(file)
+      @version = file.major_version
+      @version_id = SharepointApi::VersionConverter.to_ui(file.major_version)
+      @updated_at = Time.parse(file.time_last_modified)
+      @file = file
+    end
+
+    def list_item_id
+      @list_item_id ||= file.list_item_all_fields.id
+    end
+
+    def versions
+      return @all_versions if @all_versions
+
+      @all_versions = []
+
+      @all_versions << make_version_object(
+        version_id,
+        created_at: updated_at,
+        current: true,
+        creator_login: file.modified_by.login_name
+      )
+
+      return @all_versions unless version > 1
+
+      @all_versions += file.versions.map do |file_version|
+        make_version_object(
+          file_version.id,
+          created_at: Time.parse(file_version.created),
+          current: file_version.is_current_version,
+          creator_login: file_version.creator.login_name
+        )
+      end
+
+      @all_versions = @all_versions.sort_by(&:number)
+    end
+
+    def to_h
+      { version: version, version_id: version_id, name: name, list_item_id: list_item_id }
+    end
+
+    #######
+    private
+    #######
+
+    def make_version_object(version_id, **attrs)
+      OpenStruct.new(
+        number: SharepointApi::VersionConverter.to_major(version_id),
+        version_id: version_id,
+        **attrs
+      )
+    end
+  end
+end

data/lib/sharepoint_api/file_system.rb

@@ -0,0 +1,187 @@
+require_relative 'sharepoint_error'
+require_relative 'items'
+
+class SharepointApi
+  module FileSystem
+    class LockError < SharepointError; end
+    class FileNotFoundError < SharepointError; end
+
+    def add_file(path, content)
+      folder_path = File.dirname(path)
+      file_name = encode_path(File.basename(path))
+      begin
+        retries ||= 0
+        FileInfo.wrap(
+          site.query(
+            :post,
+            "GetFolderByServerRelativeUrl('#{site_relative_path(folder_path)}')/Files" \
+            "/Add(overwrite=true,url='#{file_name}')",
+            content
+          )
+        )
+      rescue Sharepoint::SPException => e
+        reraise_if_lock_error(e)
+
+        log_as(__method__, e)
+        log_as(__method__, "adding folder with path #{folder_path}")
+        add_folder(folder_path)
+        retry if (retries += 1) < 2
+        log_as(__method__, e, level: :warn)
+        nil
+      end
+    end
+
+    def file_exists?(path)
+      server_path = server_relative_path(path)
+      site.query(:get, "GetFileByServerRelativeUrl('#{server_path}')/Exists")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def find_file(path)
+      server_path = server_relative_path(path)
+      FileInfo.wrap(
+        site.query(:get, "GetFileByServerRelativeUrl('#{server_path}')")
+      )
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def find_file_version(path, version_id)
+      server_path = server_relative_path(path)
+      site.query(:get, "GetFileByServerRelativeUrl('#{server_path}')/versions(#{version_id})")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def move_file(path, new_path)
+      server_path = server_relative_path(path)
+      new_server_path = server_relative_path(new_path)
+
+      site.query(
+        :post,
+        "GetFileByServerRelativeUrl(@v)/MoveTo?@v='#{server_path}'&newurl='#{new_server_path}'&flags=0"
+      )
+
+      true
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def rename_file(path, rename_to)
+      validate_update_list_item(
+        path,
+        {
+          'FileLeafRef' => rename_to
+        }
+      )
+    rescue SharepointApi::ItemUpdateError => _e
+      false
+    end
+
+    def remove_file(path)
+      site.query(
+        :post,
+        "GetFileByServerRelativeUrl('#{server_relative_path(path)}')/Recycle"
+      )
+    rescue Sharepoint::SPException => e
+      reraise_if_lock_error(e)
+
+      log_as(__method__, e)
+      nil
+    end
+
+    def remove_file_version(path, version_id)
+      site.query(
+        :post,
+        "GetFileByServerRelativeUrl('#{server_relative_path(path)}')/Versions/DeleteById(vid=#{version_id})"
+      )
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def retrieve_file_content(path)
+      server_path = server_relative_path(path)
+      site.query(:get, "GetFileByServerRelativeUrl('#{server_path}')/$value", { binaryStringResponseBody: true }.to_json, true)
+    rescue Sharepoint::SPException => e
+      reraise_if_lock_error(e)
+
+      log_as(__method__, e)
+      raise FileNotFoundError, "The file #{path} does not exist."
+    end
+
+    def files_in_folder(path)
+      server_path = server_relative_path(path)
+      site.query(:get, "GetFolderByServerRelativeUrl('#{server_path}')/Files").
+        map { |file| FileInfo.new(file) }
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    ##
+    # Perhaps this should support a recursive option to
+    # create all parents as needed?
+    def add_folder(path)
+      site.query(:post, "Folders/Add('#{server_relative_path(path)}')")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def find_folder(path)
+      server_path = server_relative_path(path)
+      site.query(:get, "GetFolderByServerRelativeUrl('#{server_path}')")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def remove_folder(path)
+      server_path = server_relative_path(path)
+      site.query(:post, "GetFolderByServerRelativeUrl('#{server_path}')/Recycle")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def add_library(name, description: nil)
+      site.query(:post, 'lists', {
+        '__metadata' => { 'type' => 'SP.List' },
+        'Title' => name,
+        'Description' => description || "Document library for #{name}.",
+        'BaseTemplate' => Sharepoint::LIST_TEMPLATE_TYPE[:DocumentLibrary],
+        'AllowContentTypes' => true,
+        'ContentTypesEnabled' => true,
+        'EnableVersioning' => true
+      }.to_json)
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def find_library(name)
+      encoded_name = encode_path(name)
+      site.query :get, "Lists/GetByTitle('#{encoded_name}')"
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    #######
+    private
+    #######
+
+    def reraise_if_lock_error(error)
+      return unless error.message =~ /is locked for shared use/
+
+      log_as(__method__, error, level: :warn)
+      raise(LockError, error.message)
+    end
+  end
+end

data/lib/sharepoint_api/filename_cleaner.rb

@@ -0,0 +1,22 @@
+class SharepointApi
+  class FilenameCleaner
+    # Windows doesn't allow these characters in file names.
+    INVALID_CHARS_REGEX = %r([~"#%&*:<>?/\\{\|}]).freeze
+
+    def self.call(filename, invalid_character_regex: nil)
+      new(invalid_character_regex).call(filename)
+    end
+
+    def initialize(invalid_character_regex = nil)
+      @invalid_character_regex = invalid_character_regex || INVALID_CHARS_REGEX
+    end
+
+    def call(filename)
+      if @invalid_character_regex
+        filename.gsub(@invalid_character_regex, '')
+      else
+        filename
+      end
+    end
+  end
+end

data/lib/sharepoint_api/items.rb

@@ -0,0 +1,71 @@
+require_relative 'sharepoint_error'
+
+class SharepointApi
+  module Items
+    class ItemUpdateError < SharepointError; end
+
+    def validate_update_list_item(path, field_name_field_value_pairs)
+      server_path = server_relative_path(path)
+      uri = "GetFolderByServerRelativeUrl('#{server_path}')/ListItemAllFields/" \
+        'ValidateUpdateListItem'
+
+      form_values = field_name_field_value_pairs.map do |key, value|
+        { 'FieldName' => key, 'FieldValue' => value }
+      end
+      body = { 'formValues' => form_values, 'bNewDocumentUpdate' => false }
+
+      response = site.query(:post, uri, body.to_json, true)
+      hoist_complex_errors!(response, uri, body)
+
+      true
+    rescue Sharepoint::SharepointError => e
+      raise SharepointApi::SharepointError, e.message
+    end
+
+    def fetch_content_types
+      encoded_name = encode_path(library_name)
+      response = site.query(
+        :get,
+        "Lists/GetByTitle('#{encoded_name}')/ContentTypes?" \
+        '$select=Name,StringId'
+      )
+      response.map { |type| type.data.except('__metadata') }
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+
+      nil
+    end
+
+    #######
+    private
+    #######
+
+    def hoist_complex_errors!(response, uri, body)
+      data = JSON.parse(response)
+
+      if data['error']
+        error = Sharepoint::SPException.new(data, uri, body)
+        reraise_if_lock_error(error)
+
+        log_as(__method__, error)
+        raise ItemUpdateError, error.message
+      end
+
+      errors = data.dig('d', 'ValidateUpdateListItem', 'results')&.
+        select { |result| result['HasException'] }&.
+        map { |result| result.slice('FieldName', 'FieldValue', 'ErrorMessage') }
+
+      return if errors.nil? || errors.count.zero?
+
+      log_as(__method__, errors)
+      raise ItemUpdateError, errors
+    end
+
+    def reraise_if_lock_error(error)
+      return unless error.message =~ /is locked for shared use/
+
+      log_as(__method__, error, level: :warn)
+      raise(LockError, error.message)
+    end
+  end
+end

data/lib/sharepoint_api/permissions.rb

@@ -0,0 +1,135 @@
+require_relative 'sharepoint_error'
+
+class SharepointApi
+  module Permissions
+    def list_item_for(path)
+      server_path = server_relative_path(path)
+      site.query(:get, "GetFolderByServerRelativeUrl('#{server_path}')/ListItemAllFields")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    ##
+    # NO SPACES in url or Addressable::URI.encode the url.
+    def break_permission_inheritance_for(path, copy_role_assignments: false, clear_subscopes: true)
+      server_path = server_relative_path(path)
+      site.query(
+        :post,
+        "GetFolderByServerRelativeUrl('#{server_path}')/ListItemAllFields/" \
+        "BreakRoleInheritance(CopyRoleAssignments=#{copy_role_assignments},ClearSubscopes=#{clear_subscopes})"
+      )
+
+      true # Anything other than an error is success
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def find_group(group_name)
+      escaped_group_name = encode_path(group_name)
+      site.query(:get, "SiteGroups/GetByName('#{escaped_group_name}')")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def add_group(group_name)
+      site.query(:post, 'SiteGroups', {
+        '__metadata' => { 'type': 'SP.Group' },
+        'Title' => group_name,
+        'Description' => "Access Group for #{group_name}"
+      }.to_json)
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    ##
+    # This also removes any role definitions the groups is using.
+    def remove_group(group_name)
+      site.query(:post, "SiteGroups/RemoveByLoginName('#{group_name}')")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def add_user_to_group(login_name, group_name)
+      user = site.query(:post, "SiteGroups/GetByName('#{group_name}')/Users", {
+        '__metadata' => { 'type' => 'SP.User' }, 'LoginName' => login_name
+      }.to_json)
+
+      !user.nil?
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    ##
+    # Addressable::URI.encode does not encode `:#.` characters,
+    # which is a must for login names.
+    def remove_user_from_group(login_name, group_name)
+      encoded_login_name = ERB::Util.url_encode(login_name)
+      site.query(
+        :post,
+        "SiteGroups/GetByName('#{group_name}')/" \
+        "Users/RemoveByLoginName(@v)?@v='#{encoded_login_name}'"
+      )
+
+      true
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def users_in_group(group_name)
+      site.query(:get, "SiteGroups/GetByName('#{group_name}')/Users")
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def find_role(role_name = 'Edit')
+      escaped_role_name = encode_path(role_name)
+      site.query :get, "RoleDefinitions/GetByName('#{escaped_role_name}')"
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    ##
+    # Alternate version would be:
+    # def add_role_assignment(library_guid:, list_item_id:, principal_id:, role_id:)
+    #   list_item_path = "Lists(guid'#{@library_guid}')/Items(#{@list_item_id})"
+    # You would do it the above way if you had a problem with the file names being too long.
+    def add_role_assignment(path, principal_id, role_id)
+      server_path = server_relative_path(path)
+      list_item_path = "GetFolderByServerRelativeUrl('#{server_path}')/ListItemAllFields"
+
+      site.query( # returns nothing on success
+        :post,
+        "#{list_item_path}/RoleAssignments/AddRoleAssignment(PrincipalId=#{principal_id},RoleDefId=#{role_id})"
+      )
+
+      true
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+
+    def remove_role_assignment(path, principal_id, role_id)
+      server_path = server_relative_path(path)
+      list_item_path = "GetFolderByServerRelativeUrl('#{server_path}')/ListItemAllFields"
+
+      site.query( # returns nothing on success
+        :post,
+        "#{list_item_path}/RoleAssignments/RemoveRoleAssignment(PrincipalId=#{principal_id},RoleDefId=#{role_id})"
+      )
+
+      true
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      false
+    end
+  end
+end

data/lib/sharepoint_api/sharepoint_error.rb

@@ -0,0 +1,3 @@
+class SharepointApi
+  class SharepointError < RuntimeError; end
+end

data/lib/sharepoint_api/users.rb

@@ -0,0 +1,25 @@
+require_relative 'sharepoint_error'
+
+class SharepointApi
+  module Users
+    def ensure_user(login_name)
+      body = {
+        'logonName' => login_name
+      }
+      site.query(:post, 'ensureUser', body.to_json)
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+
+    def fetch_user_id_from_login_name(login_name)
+      encoded_login_name = ERB::Util.url_encode(login_name)
+
+      url = "/SiteUsers/GetByLoginName(@v)?@v='#{encoded_login_name}'&$select=Id"
+      site.query(:get, url)&.id
+    rescue Sharepoint::SPException => e
+      log_as(__method__, e)
+      nil
+    end
+  end
+end

data/lib/sharepoint_api/version.rb

@@ -0,0 +1,3 @@
+class SharepointApi
+  VERSION = '1.0.0'.freeze
+end

data/lib/sharepoint_api/version_converter.rb

@@ -0,0 +1,12 @@
+class SharepointApi
+  class VersionConverter
+    VERSION_UNIT = 512
+    def self.to_major(ui_version)
+      ui_version.to_i / VERSION_UNIT
+    end
+
+    def self.to_ui(major_version)
+      major_version.to_i * VERSION_UNIT
+    end
+  end
+end

data/sharepoint_api.gemspec

@@ -0,0 +1,31 @@
+require_relative 'lib/sharepoint_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'sharepoint_api'
+  spec.version       = SharepointApi::VERSION
+  spec.authors       = ['Andrew Kalek', 'Marlen Brunner']
+  spec.email         = ['akalek@proofgov.com', 'mbrunner@proofgov.com']
+
+  spec.summary       = 'SharepointApi allows you to interact with sharepoint in a simpler DSL.'
+  spec.description   = 'A tool to make it easier to talk to sharepoint (via the proof-sharepoint-ruby gem)'
+  spec.homepage      = 'https://github.com/proofgov/sharepoint_api'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/proofgov/sharepoint_api'
+  spec.metadata['changelog_uri'] = 'https://github.com/proofgov/sharepoint_api/blob/master/CHANGELOG.md'
+
+  spec.add_runtime_dependency('proof-sharepoint-ruby', '~> 1.0')
+  spec.add_runtime_dependency('addressable', '~> 2.7')
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+
+  spec.require_paths = ['lib']
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: sharepoint_api
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Andrew Kalek
+- Marlen Brunner
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2020-12-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: proof-sharepoint-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: A tool to make it easier to talk to sharepoint (via the proof-sharepoint-ruby
+  gem)
+email:
+- akalek@proofgov.com
+- mbrunner@proofgov.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/sharepoint_api.rb
+- lib/sharepoint_api/file_info.rb
+- lib/sharepoint_api/file_system.rb
+- lib/sharepoint_api/filename_cleaner.rb
+- lib/sharepoint_api/items.rb
+- lib/sharepoint_api/permissions.rb
+- lib/sharepoint_api/sharepoint_error.rb
+- lib/sharepoint_api/users.rb
+- lib/sharepoint_api/version.rb
+- lib/sharepoint_api/version_converter.rb
+- sharepoint_api.gemspec
+homepage: https://github.com/proofgov/sharepoint_api
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/proofgov/sharepoint_api
+  source_code_uri: https://github.com/proofgov/sharepoint_api
+  changelog_uri: https://github.com/proofgov/sharepoint_api/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: SharepointApi allows you to interact with sharepoint in a simpler DSL.
+test_files: []