files.com 1.1.130 → 1.1.131

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e4169efeb72ee02d2d20d7bd0ed7c2e2374765043f7210dc4942ab5596a7856
-  data.tar.gz: eac3fe346a83378aa43975d0916d83c416336ee843f0acd2f4fc3981b07f1d45
+  metadata.gz: 87b62527b02e1b2c1bf9a3ef13de4d0ee943a324006aa9d9cd0cca31cfbef3e2
+  data.tar.gz: 203318579966bd24bb678fc8f8f8d96770b6510dea43ce0183a141fb88132830
 SHA512:
-  metadata.gz: 4691bd6a6d43239fcc5fb4d205d46b44c801fe062cda8ff555f1016aca5499f2bebe144fb81c73813bf8255fbc85b78dc80768548a5b507ea189ee479aed525e
-  data.tar.gz: 69f3f8f83c8d3e3fbef38b0fa519e0d2f8eec280a615cce1ba3dd9efce526d5629f0682edae642f770857fe473b5d27099bd254dd489e2b73c52c7debebd41fe
+  metadata.gz: 946fef63c7906b1455e9ede3f3582701c0663de3a52b37315c113efc900ca8acb7bc3aace91e6484e65ade5ddf71aeb66191c673f58e9b2b608c67d6c545c76a
+  data.tar.gz: eb645b1e5877752256ba09da1fd0697b5496869aad336efe00d3c163aff4e5687afd2b76ae361cd2237fefe92c2a99d20a764064c7a0cdc8158e9bceea4b38ed

data/README.md

@@ -192,6 +192,93 @@ Maximum number of retries. The default value is 3.
 Files.max_network_retries = 5
 ```
 
+## Sort and Filter
+
+Several of the Files.com API resources have list operations that return multiple instances of the resource.  The List operations
+can be sorted and filtered.
+
+### Sorting
+
+The returned data can be sorted by passing in the ```sort_by``` method argument.
+
+The argument value is a Ruby hash that has a key of the resource field name to sort on and a value of either ```"asc"``` or ```"desc"``` to specify the sort order.
+
+Each resource has a set of valid fields for sorting and can be sorted by one field at a time.
+
+### Filters
+
+Filters apply selection criteria to the underlying query that returns the results. Filters can be applied individually to select resource fields
+and/or in a combination with each other.  The results of applying filters and filter combinations can be sorted by a single field.
+
+The passed in argument value is a Ruby hash that has a key of the resource field name to filter on and a passed in value to use in the filter comparison.
+
+Each resource has their own set of valid filters and fields, valid combinations of filters, and sortable fields.
+
+#### Types of Filters
+
+##### Exact Filter
+
+`filter` - find resources that have an exact field value match to a passed in value. (i.e., FIELD_VALUE = PASS_IN_VALUE).
+
+#### Range Filters
+
+`filter_gt` - find resources that have a field value that is greater than the passed in value.  (i.e., FIELD_VALUE > PASS_IN_VALUE).
+
+`filter_gte` - find resources that have a field value that is greater than or equal to the passed in value.  (i.e., FIELD_VALUE >=  PASS_IN_VALUE).
+
+`filter_lt` - find resources that have a field value that is less than the passed in value.  (i.e., FIELD_VALUE < PASS_IN_VALUE).
+
+`filter_lte` - find resources that have a field value that is less than or equal to the passed in value.  (i.e., FIELD_VALUE \<= PASS_IN_VALUE).
+
+##### Pattern Filter
+
+`filter_prefix` - find resources where the specified field is prefixed by the supplied value. This is applicable to values that are strings.
+
+```ruby title="Sort Example"
+## users sorted by username
+Files.api_key = 'YOUR_API_KEY'
+Files::User.list(
+  sort_by: { "username": "asc"}
+)
+```
+
+```ruby title="Exact Filter Example"
+## non admin users
+Files.api_key = 'YOUR_API_KEY'
+Files::User.list(
+  filter: { not_site_admin: true },
+  sort_by: { "username": "asc"}
+)
+```
+
+```ruby title="Range Filter Example"
+#users who haven't logged in since 2024-01-01
+Files.api_key = 'YOUR_API_KEY'
+Files::User.list(
+filter_gte: { "last_login_at": "2024-01-01" },
+  sort_by: { "last_login_at": "asc"}
+)
+```
+
+```ruby title="Pattern Filter Example"
+## users who usernames start with 'test'
+Files.api_key = 'YOUR_API_KEY'
+Files::User.list(
+  filter_pre: { username: "test" },
+  sort_by: { "username": "asc"}
+)
+```
+
+```ruby title="Combined Filter Example"
+## users who usernames start with 'test' and are not admins
+Files.api_key = 'YOUR_API_KEY'
+Files::User.list(
+  filter_prefix: { username: "test" },
+  filter: { not_site_admin: true },
+  sort_by: { "username": "asc"}
+)
+```
+
 ## Errors
 
 The Files.com Ruby SDK will return errors by raising exceptions. There are many exception classes defined in the Files SDK that correspond

data/_VERSION

@@ -1 +1 @@
-1.1.130
+1.1.131

data/lib/files.com/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Files
-  VERSION = "1.1.130"
+  VERSION = "1.1.131"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: files.com
 version: !ruby/object:Gem::Version
-  version: 1.1.130
+  version: 1.1.131
 platform: ruby
 authors:
 - files.com