fmrest-rails 0.22.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8252ef182909d4dc2175c7d33ab64a3450054d093a95d8021966eb9841e4cbb6
+  data.tar.gz: bd810bccbdc3f4fbaba17f325158ae25294ebd4bb48f41699bf05e86f0a1fdaa
+SHA512:
+  metadata.gz: e915feb3a290fc7e3a9464f7b94fa67d3cb58617152684a6209a138fcfc1dd4eb6e7c45a996232b35c14ed360887dfdad814e28ddde428afacf50838f7d85a88
+  data.tar.gz: 420fe28f935ee3a1f970ccb9127c2f506471d3b088d304dec40868a2feeb49386db48c1c6a963cf5f4197cfe05c984de86f8961f58f3efb19b77d5f48b7ce3e0

data/.yardopts

@@ -0,0 +1,5 @@
+--markup markdown
+--plugin activesupport-concern
+lib/**/*.rb
+-
+docs/*

data/CHANGELOG.md

@@ -0,0 +1,188 @@
+## Changelog
+
+### 0.21.0
+
+* Support for Spyke 7 and Faraday 2
+* Drop support for Faraday 1
+* Drop support for Ruby 2.5
+
+### 0.20.0
+
+* Forward proxy options to AWS Client when using `fmrest-cloud` gem
+
+### 0.19.0
+
+* Added native support for FileMaker Cloud through the `fmrest-cloud` gem
+
+### 0.18.0
+
+* Better support for portals with mismatching field qualifiers
+* Better ergonomics for script execution, improved documentation
+* Defining an attribute on a model that would collide with an existing method
+  now raises an error
+* Cleared Faraday deprecation messages on authentication methods
+* Handle FileMaker Cloud case where HTTP 401 Unauthorized with content-type
+  text/html is returned after token expiry
+* Add retry option to Rescuable mixin
+* Added fmrest-ruby/VERSION to User-Agent headers
+
+### 0.17.1
+
+* Fixed crash when `fmid_token` is set but `username` isn't
+
+### 0.17.0
+
+* Added support for Claris ID token login
+* Added ability to use procs in settings
+* Added `Rescuable` mixin
+
+### 0.16.0
+
+* Added `FmRest.logger=`
+* Handle serialization of `nil`, `true` and `false` values
+
+### 0.15.2
+
+* Fixed autoloading of `FmRest::Layout`
+
+### 0.15.0
+
+* Much improved querying API (see documentation on querying), adding new
+  `.query` capabilities, as well as two new methods: `.match` and `.or`
+
+### 0.14.0
+
+* Aliased `FmRest::Spyke::Base` as `FmRest::Layout` (now preferred), and
+  provided a shortcut version for setting the layout name (e.g.  `class Foo <
+  FmRest::Layout("LayoutName")`)
+* Made `layout` class setting subclass-inheritable
+
+### 0.13.1
+
+* Fixed downloading of container field data from FMS19+
+
+### 0.13.0
+
+* Split `fmrest` gem into `fmrest-core` and `fmrest-spyke`. `fmrest` becomes a
+  wrapper for the two new gems.
+* Fixed bug preventing connection databases with spaces in their names.
+* Improved portal support with ability to delete portal records, and better
+  refreshing of portal records after saving the parent.
+* `FmRest::Spyke::Base#__record_id` and `FmRest::Spyke::Base#__mod_id` now
+  always return integers if set.
+
+### 0.12.0
+
+* Rename `FmRest::Spyke::Base#id=` to `FmRest::Spyke::Base#__record_id=` to
+  prevent clobbering of FileMaker layout-defined fields
+* Removed previously deprecated `FmRest::Spyke::Base(config)` syntax
+* Better yard documentation
+
+### 0.11.1
+
+* Fixed a couple crashes due to missing constants
+
+### 0.11.0
+
+* Added custom class for connection settings, providing indifferent access
+  (i.e. keys can be strings or symbols), and centralized default values and
+  validations
+* Added `:autologin`, `:token` and `:token_store` connection settings
+* Added `FmRest::Base.fmrest_config_overlay=` and related methods
+* Added `FmRest::V1.request_auth_token` and
+  `FmRest::Spyke::Base.request_auth_token` (as well as `!`-suffixed versions
+  which raise exceptions on failure)
+
+### 0.10.1
+
+* Fixed `URI.escape` obsolete warning messages in Ruby 2.7 by replacing it with
+  `URI.encode_www_form_component`
+  ([PR#40](https://github.com/beezwax/fmrest-ruby/pull/40))
+
+### 0.10.0
+
+* Added `FmRest::StringDateAwareness` module to correct some issues when using
+  `FmRest::StringDate`
+* Added basic timezones support
+* Deprecated `class < FmRest::Spyke::Base(config_hash)` syntax in favor of
+  using `self.fmrest_config=`
+
+### 0.9.0
+
+* Added `FmRest::Spyke::Base.set_globals`
+
+### 0.8.0
+
+* Improved metadata when using `FmRest::Spyke::Model`. Metadata now uses
+  Struct/OpenStruct, so properties are accessible through `.property`, as well
+  as `[:property]`
+* Added batch-finders `.find_in_batches` and `.find_each` for
+* `FmRest::Spyke::Base`
+
+### 0.7.1
+
+* Made sure `Model.find_one` and `Model.find_some` work without needing to call
+  `Model.all` in between
+
+### 0.7.0
+
+* Added date coercion feature
+
+### 0.6.0
+
+* Implemented session logout
+  ([#16](https://github.com/beezwax/fmrest-ruby/issues/16))
+
+### 0.5.2
+
+* Improved support for legacy ActiveModel 4.x
+
+### 0.5.1
+
+* Alias `:username` option as `:account_name` for ginjo-rfm gem
+  cross-compatibility
+
+### 0.5.0
+
+* Much improved script execution support
+  ([#20](https://github.com/beezwax/fmrest-ruby/issues/20))
+* Fixed bug when setting `default_limi` and trying to find a record
+  ([35](https://github.com/beezwax/fmrest-ruby/issues/35))
+
+### 0.4.1
+
+* Prevent raising an exception when a /\_find request yields no results
+  ([#33](https://github.com/beezwax/fmrest-ruby/issues/33) and
+  [#34](https://github.com/beezwax/fmrest-ruby/issues/34))
+
+### 0.4.0
+
+* Implement ability to set limit and offset for portals
+* Implement disabling and requesting all portals
+
+### 0.3.3
+
+* Fix encoding of paths for layouts with brackets in them (e.g. `"\[Very Ugly\]
+  Layout"`)
+* Raise an error if `"id"` is assigned as an attribute on a model, as it's
+  currently a reserved method name by Spyke
+
+### 0.3.2
+
+* Fixed support for ActiveSupport < 5.2
+  ([#27](https://github.com/beezwax/fmrest-ruby/issues/27))
+
+### 0.3.0
+
+* Added Moneta token store
+
+### 0.2.5
+
+* Fixed crash in `fetch_container_data` when no proxy options were set
+
+### 0.2.4
+
+* Use `String#=~` instead of `String#match?` for Ruby <2.4 compatibility (Fixes
+  [#26](https://github.com/beezwax/fmrest-ruby/issues/26))
+* Deprecated `FmRest.config` in favor of `FmRest.default_connection_settings`
+* Honor Faraday SSL and proxy settings when fetching container files

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Pedro Carbajal and Beezwax Datatools, Inc.
+
+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,579 @@
+# fmrest-ruby
+
+[![Gem Version](https://badge.fury.io/rb/fmrest.svg?style=flat)](https://rubygems.org/gems/fmrest)
+![CI](https://github.com/beezwax/fmrest-ruby/workflows/CI/badge.svg)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/beezwax/fmrest-ruby)
+[![Powered by Beezwax](https://img.shields.io/badge/Powered%20By-Beezwax-gold?logo=data:image/svg+xml;charset=utf-8;base64,PHN2ZyB3aWR0aD0iMTA5IiBoZWlnaHQ9IjEwOSIgdmlld0JveD0iMCAwIDEwOSAxMDkiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+DQogICA8Zz4NCiAgICAgIDxwYXRoIGQ9Ik01MC44IDEwNi42MjVDNTkuMSA5OS4zMjUgNjEuOSA5MS42MjUgNjEuOSA5MS42MjVDNjMuMiA4Ny43MjUgNjQuNyA4NC41MjUgNjQuNyA2OS4zMjVDNjQuNyA0Ni40MjUgNTYuMiAzOC45MjUgNDcgMzIuMDI1QzQwLjggMjcuMzI1IDI0LjkgMjEuMTI1IDE1LjUgMTcuNjI1TDIuMjk5OTggMjUuMTI1QzEuNDk5OTggMjUuNzI1IDAuOTk5OTc2IDI2LjIyNSAwLjU5OTk3NiAyNi44MjVDMjQuNCAzMi4xMjUgNDEuNSA0OC4wMjUgNDEuNSA2Ni44MjVDNDEuNSA3OC4yMjUgMzUuMSA4OC42MjUgMjQuOSA5Ni4xMjVMNDQuNyAxMDcuNTI1QzQ1LjEgMTA3LjcyNSA0NiAxMDguMTI1IDQ3LjMgMTA4LjEyNUM0Ny45IDEwOC4xMjUgNDkgMTA3LjkyNSA1MC4zIDEwNi44MjVMNTAuOCAxMDYuNjI1WiIgZmlsbD0iI0ZGRDkzOSI+PC9wYXRoPg0KICAgICAgPHBhdGggZD0iTTIyLjkgMTMuMzI0OEw0NCAyMC40MjQ4QzY0LjYgMjcuNzI0OCA3My4yIDM3LjgyNDggNzMuMiAzNy44MjQ4Qzg0LjUgNDkuMTI0OCA4My4yIDYxLjYyNDggODMuMiA3Ni44MjQ4QzgzLjIgODAuNjI0OCA4Mi42IDg0LjkyNDggODEuNyA4OS4wMjQ4TDkzIDgyLjYyNDhDOTUuNiA4MS4xMjQ4IDk1LjYgNzcuOTI0OCA5NS42IDc3LjkyNDhWMjkuMzI0OEM5NS42IDI2LjEyNDggOTMgMjQuNjI0OCA5MyAyNC42MjQ4TDcyLjUgMTMuMjI0OEw1MC42IDAuNjI0ODQ1QzQ4LjEgLTAuNjc1MTU1IDQ1LjUgMC40MjQ4NDUgNDUuMyAwLjYyNDg0NUwyMy4xIDEzLjMyNDhIMjIuOVoiIGZpbGw9IiNGRkQ5MzkiPjwvcGF0aD4NCiAgICAgIDxwYXRoIGQ9Ik0wLjEgMzEuNTI0NFY3OC4yMjQ0QzAuMSA4MC44MjQ0IDIuMiA4Mi4zMjQ0IDIuNyA4Mi43MjQ0TDE0LjggODkuNjI0NEwxNy44IDkxLjMyNDRDMjQuNCA4NC43MjQ0IDI4LjQgNzYuMzI0NCAyOC41IDY3LjEyNDRDMjguNSA1MS41MjQ0IDE2LjggMzguMDI0NCAwIDMxLjUyNDRIMC4xWiIgZmlsbD0iI0ZGRDkzOSI+PC9wYXRoPg0KICAgPC9nPg0KPC9zdmc+)](https://beezwax.net/)
+
+A Ruby client for
+[FileMaker's Data API](https://help.claris.com/en/data-api-guide)
+with ActiveRecord-ish ORM features.
+
+While pretty feature-rich, fmrest-ruby doesn't yet support 100% of FileMaker
+19's Data API features. See the [implementation completeness
+table](#api-implementation-completeness-table) to check if a feature you need
+is natively supported by the gem.
+
+Need Ruby or FileMaker consulting? Contact us at
+[Beezwax.net](https://beezwax.net/)
+
+## Gems
+
+The `fmrest` gem is a wrapper for these gems:
+
+* `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
+  of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
+* `fmrest-core`, providing the core
+  [Faraday](https://github.com/lostisland/faraday) connection builder, session
+  management, and other core utilities.
+* `fmrest-rails`, providing Rails integration.
+
+In addition, the optional `fmrest-cloud` gem adds support for FileMaker Cloud.
+See the [main document on connecting to FileMaker
+Cloud](docs/FileMakerCloud.md).
+
+## Installation
+
+In your Gemfile:
+
+```ruby
+gem 'fmrest'
+
+# Optional: if your files are hosted on FileMaker Cloud
+gem 'fmrest-cloud'
+```
+
+If you're using Rails you can now run:
+
+```
+rails generate fmrest:config
+```
+
+## Simple example
+
+```ruby
+# A Layout model connecting to the "Honeybees Web" FileMaker layout
+class Honeybee < FmRest::Layout("Honeybees Web")
+  # Connection settings
+  self.fmrest_config = {
+    host:     "…",
+    database: "…",
+    username: "…",
+    password: "…"
+  }
+
+  # Mapped attributes
+  attributes name: "Bee Name", age: "Bee Age", created_on: "Created On"
+
+  # Portal associations
+  has_portal :tasks
+
+  # File containers
+  container :photo, field_name: "Bee Photo"
+
+  # Scopes
+  scope :can_legally_fly, -> { query(age: ">18") }
+
+  # Client-side validations
+  validates :name, presence: true
+
+  # Callbacks
+  before_save :set_created_on
+
+  private
+
+  def set_created_on
+    self.created_on = Date.today
+  end
+end
+
+# Find a record by id
+bee = Honeybee.find(9)
+
+bee.name = "Hutch"
+
+# Add a new record to portal
+bee.tasks.build(urgency: "Today")
+
+bee.save
+```
+
+In case you don't want the ORM features (i.e. you only need authentication and
+JSON parsing, and are comfortable writing the API requests manually without the
+ORM overhead) you can use the Faraday connection provided by `fmrest-core`.
+See the [main document on using the base
+connection](docs/BaseConnectionUsage.md) for more.
+
+## Connection settings
+
+The minimum required connection settings are `:host`, `:database`, `:username`
+and `:password`, but fmrest-ruby has many other options you can pass when
+setting up a connection (see [full list](#full-list-of-available-options) below).
+
+`:ssl` and `:proxy` are forwarded to the underlying
+[Faraday](https://github.com/lostisland/faraday) connection. You can use this
+to, for instance, disable SSL verification:
+
+```ruby
+{
+  host: "…",
+  …
+  ssl:  { verify: false },
+  proxy: "http://user:password@proxy.host:4321"
+}
+```
+
+You can also pass a `:log` option for basic request logging, see the section on
+[Logging](#Logging) below.
+
+### Full list of available options
+
+Option              | Description                                | Format                      | Default
+--------------------|--------------------------------------------|-----------------------------|--------
+`:host`             | Hostname with optional port, e.g. `example.com:9000` | String          | None
+`:database`         | The name of the database to connect to     | String                      | None
+`:username`         | A Data API-ready account                   | String                      | None
+`:password`         | Your password                              | String                      | None
+`:account_name`     | Alias of `:username`                       | String                      | None
+`:ssl`              | SSL options to be forwarded to Faraday     | [Faraday SSL options](https://www.rubydoc.info/gems/faraday/Faraday/SSLOptions) hash | None
+`:proxy`            | Proxy URI, e.g. `http://user:password@proxy.host:4321` | String          | None
+`:log`              | Log JSON responses to STDOUT               | Boolean                     | `false`
+`:log_level`        | Which log level to log into                | Values accepted by `Logger#level=` | `:debug`
+`:coerce_dates`     | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
+`:date_format`      | Date parsing format                        | String (FM date format)     | `"MM/dd/yyyy"`
+`:timestamp_format` | Timestmap parsing format                   | String (FM date format)     | `"MM/dd/yyyy HH:mm:ss"`
+`:time_format`      | Time parsing format                        | String (FM date format)     | `"HH:mm:ss"`
+`:timezone`         | The timezone for the FM server             | `:local` \| `:utc` \| `nil` | `nil`
+`:autologin`        | Whether to automatically start Data API sessions | Boolean               | `true`
+`:token`            | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
+`:fmid_token`       | Claris ID token (only needed if manually obtaining the token) | String   | None
+`:cloud`            | Specifies whether the host is using FileMaker Cloud | `:auto` \| Boolean | `:auto`
+`:cognito_client_id`| Overwrites the hardcoded FileMaker Cloud Cognito Client ID | String      | None
+`:cognito_pool_id`  | Overwrites the hardcoded FileMaker Cloud Cognito Pool ID | String        | None
+`:aws_region`       | Overwrites the hardcoded FileMaker Cloud AWS Region | String             | None
+
+### Default connection settings
+
+If you're only connecting to a single FM database you can configure it globally
+through `FmRest.default_connection_settings=`. E.g.:
+
+```ruby
+FmRest.default_connection_settings = {
+  host:     "…",
+  database: "…",
+  username: "…",
+  password: "…"
+}
+```
+
+These settings will be used by default by `FmRest::Layout` models whenever you
+don't set `fmrest_config=` explicitly, as well as by
+`FmRest::V1.build_connection` in case you're setting up your Faraday connection
+manually.
+
+## Session token store
+
+fmrest-ruby includes a number of options for storing session tokens:
+
+* Memory
+* ActiveRecord
+* Redis
+* Moneta
+
+See the [main document on token stores](docs/TokenStore.md) for detailed info
+on how to set up each store.
+
+## Date fields and timezones
+
+fmrest-ruby has automatic detection and coercion of date fields to and from
+Ruby date/time objects. Basic timezone support is also provided.
+
+See the [main document on date fields](docs/DateFields.md) for more info.
+
+## ActiveRecord-like ORM (fmrest-spyke)
+
+[Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
+building REST ORM models. fmrest-ruby uses it to build its ORM features,
+bundled in the `fmrest-spyke` gem (already included if you're using the
+`fmrest` gem).
+
+To create a model you can inherit directly from `FmRest::Layout` (itself a
+subclass of `Spyke::Base`).
+
+```ruby
+class Honeybee < FmRest::Layout
+end
+```
+
+All of Spyke's basic ORM operations work as expected:
+
+```ruby
+bee = Honeybee.new
+
+bee.name = "Hutch"
+bee.save # POST request (creates new record)
+
+bee.name = "ハッチ"
+bee.save # PATCH request (updates existing record)
+
+bee.reload # GET request
+
+bee.destroy # DELETE request
+
+bee = Honeybee.find(9) # GET request
+```
+
+It's recommended that you read Spyke's documentation for more information on
+these basic features. If you've used ActiveRecord or similar ORM libraries
+you'll find it quite familiar.
+
+Notice that `FmRest::Layout` is aliased as `FmRest::Spyke::Base`. Previous
+versions of fmrest-ruby only provided the latter version, so if you're already
+using `FmRest::Spyke::Base` there's no need to rename your classes to
+`FmRest::Layout`, both will continue to work interchangeably.
+
+In addition, `FmRest::Layout` extends `Spyke::Base` with the following
+features:
+
+### FmRest::Layout.fmrest_config=
+
+This allows you to set Data API connection settings specific to your model
+class:
+
+```ruby
+class Honeybee < FmRest::Layout
+  self.fmrest_config = {
+    host:     "…",
+    database: "…",
+    username: "…",
+    password: "…"
+  }
+end
+```
+
+These settings are class-inheritable, so you could create a base class that
+does the initial connection setup and then inherit from it in models using that
+same connection. E.g.:
+
+```ruby
+class ApplicationFmLayout < FmRest::Layout
+  self.fmrest_config = { host: "…", database: "…", … }
+end
+
+class Honeybee < ApplicationFmLayout
+  # This model will use the same connection as ApplicationFmLayout
+end
+```
+
+If `fmrest_config` is not set, your model will try to use
+`FmRest.default_connection_settings` instead.
+
+#### Connection settings overlays
+
+There may be cases where you want to use a different set of connection settings
+depending on context. For example, if you want to use username and password
+provided by the user in a web application. Since `.fmrest_config` is set at the
+class level, changing the username/password for the model in one context would
+also change it in all other contexts, leading to security issues.
+
+To solve this scenario, fmrest-ruby provides a way of defining thread-local,
+reversible connection settings overlays through `.fmrest_config_overlay=`.
+
+See the [main document on connection setting overlays](docs/ConfigOverlays.md)
+for details on how it works.
+
+### FmRest::Layout.layout
+
+Use `layout` to set the layout name for your model.
+
+```ruby
+class Honeybee < FmRest::Layout
+  layout "Honeybees Web"
+end
+```
+
+Alternatively, if you're inheriting from `FmRest::Layout` directly you can set
+the layout name in the class definition line:
+
+```ruby
+class Honeybee < FmRest::Layout("Honeybees Web")
+```
+
+Note that you only need to manually set the layout name if the name of the
+class and the name of the layout differ, otherwise fmrest-ruby will just use
+the name of the class.
+
+### FmRest::Layout.request_auth_token
+
+Requests a Data API session token using the connection settings in
+`fmrest_config` and returns it if successful, otherwise returns `false`.
+
+You normally don't need to use this method as fmrest-ruby will automatically
+request and store session tokens for you (provided that `:autologin` is
+`true` in the connection settings, which it is by default).
+
+### FmRest::Layout.logout
+
+Use `.logout` to log out from the database session (you may call it on any
+model that uses the database session you want to log out from).
+
+```ruby
+Honeybee.logout
+```
+
+### Mapped FmRest::Layout.attributes
+
+Spyke allows you to define your model's attributes using `attributes`, however
+sometimes FileMaker's field names aren't very Ruby-ORM-friendly, especially
+since they may sometimes contain spaces and other special characters, so
+fmrest-ruby extends `attributes`' functionality to allow you to map
+Ruby-friendly attribute names to FileMaker field names. E.g.:
+
+```ruby
+class Honeybee < FmRest::Layout
+  attributes first_name: "First Name", last_name: "Last Name"
+end
+```
+
+You can then simply use the pretty attribute names whenever working with your
+model and they will get mapped to their FileMaker fields:
+
+```ruby
+bee = Honeybee.find(1)
+
+bee.first_name # => "Princess"
+bee.last_name  # => "Buzz"
+
+bee.first_name = "Queen"
+
+bee.attributes # => { "First Name": "Queen", "Last Name": "Buzz" }
+```
+
+### FmRest::Layout.has_portal
+
+You can define portal associations on your model wth `has_portal`, as such:
+
+```ruby
+class Honeybee < FmRest::Layout
+  has_portal :flowers
+end
+
+class Flower < FmRest::Layout
+  attributes :color, :species
+end
+```
+
+See the [main document on portal associations](docs/Portals.md) for details.
+
+### Dirty attributes
+
+fmrest-ruby includes support for ActiveModel's Dirty mixin out of the box,
+providing methods like:
+
+```ruby
+bee = Honeybee.new
+
+bee.changed? # => false
+
+bee.name = "Maya"
+
+bee.changed? # => true
+
+bee.name_changed? # => true
+```
+
+fmrest-ruby uses the Dirty functionality to only send changed attributes back
+to the server on save.
+
+You can read more about [ActiveModel's Dirty in Rails
+Guides](https://guides.rubyonrails.org/active_model_basics.html#dirty).
+
+### Query API
+
+Since Spyke is API-agnostic it only provides a wide-purpose `.where` method for
+passing arbitrary parameters to the REST backend. fmrest-ruby however is well
+aware of its backend API, so it extends Spkye models with a bunch of useful
+querying methods: `.query`, `.match`, `.omit`, `.limit`, `.offset`, `.sort`,
+`.portal`, `.script`, etc.
+
+See the [main document on querying](docs/Querying.md) for detailed information
+on the query API methods.
+
+### Finding records in batches
+
+Sometimes you want to iterate over a very large number of records to do some
+processing, but requesting them all at once would result in one huge request to
+the Data API, and loading too many records in memory all at once.
+
+To mitigate this problem you can use `.find_in_batches` and `.find_each`.
+
+See the [main document on finding in batches](docs/FindInBatches.md) for
+detailed information on how those work.
+
+### Container fields
+
+You can define container fields on your model class with `container`:
+
+```ruby
+class Honeybee < FmRest::Layout
+  container :photo, field_name: "Beehive Photo ID"
+end
+```
+
+See the [main document on container fields](docs/ContainerFields.md) for
+details on how to use it.
+
+### Script execution
+
+The FM Data API allows running scripts as part of many types of requests, and
+`fmrest-spyke` provides mechanisms for all of them.
+
+See the [main document on script execution](docs/ScriptExecution.md) for
+details.
+
+### Setting global field values
+
+You can call `.set_globals` on any `FmRest::Layout` model to set global
+field values on the database that model is configured for.
+
+See the [main document on setting global field values](docs/GlobalFields.md)
+for details.
+
+### Rescuable mixin
+
+Sometimes you may want to handle Data API errors at the model level. For such
+cases fmrest-ruby provides an off-by-default mixin called `Rescuable` that
+provides convenience macros for that. If you've used Ruby on Rails you may be
+familiar with its syntax from controllers. E.g.
+
+```ruby
+class BeeBase < FmRest::Layout
+  include FmRest::Spyke::Model::Rescuable
+
+  rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
+
+  def self.notify_admin_of_system_error(e)
+    # Shoot an email to the FM admin...
+  end
+end
+```
+
+Since `Rescuable` uses `ActiveSupport::Rescuable` internally, you may want to
+check [Rails'
+documentation](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html)
+too for details on how it works.
+
+One caveat of using `rescue_from` is that it always catches exceptions at the
+class level, so if you pass a method name to `with:` that method has to be a
+class method. Also note that this will only catch exceptions raised during an
+API call to the Data API server (in other words, only on actions that perform
+an HTTP request).
+
+## Logging
+
+If using `fmrest-spyke` with Rails then pretty log output will be set up for
+you automatically by Spyke (see [their
+README](https://github.com/balvig/spyke#log-output)).
+
+You can also enable simple Faraday logging of raw requests (useful for
+debugging) by passing `log: true` in the options hash for either
+`FmRest.default_connection_settings=` or your models' `fmrest_config=`, e.g.:
+
+```ruby
+FmRest.default_connection_settings = {
+  host: "…",
+  …
+  log:  true
+}
+
+# Or in your model
+class LoggyBee < FmRest::Layout
+  self.fmrest_config = {
+    host: "…",
+    …
+    log:  true
+  }
+end
+```
+
+You can also pass `log_level` to connection settings to change the severity of
+log output (defaults to `:debug`).
+
+By default fmrest-ruby logs to STDOUT or to Rails' logger object if available.
+You can change this by providing your own logger object to `FmRest.logger=`:
+
+```ruby
+FmRest.logger = Logger.new("fmrest.log")
+```
+
+If you need to set up more complex logging for your models you can use the
+`faraday` block inside your class to inject your own logger middleware into the
+Faraday connection, e.g.:
+
+```ruby
+class LoggyBee < FmRest::Layout
+  faraday do |conn|
+    conn.response :logger, MyApp.logger, bodies: true
+  end
+end
+```
+
+## Gotchas
+
+Read about unexpected scenarios in the [gotchas doc](docs/Gotchas.md).
+
+## API implementation completeness table
+
+FM Data API reference: https://help.claris.com/en/data-api-guide/
+
+| FM 19 Data API feature              | Supported by basic connection | Supported by FmRest::Layout |
+|-------------------------------------|-------------------------------|-----------------------------|
+| Log in using HTTP Basic Auth        | Yes                           | Yes                         |
+| Log in using OAuth                  | No                            | No                          |
+| Log in to an external data source   | No                            | No                          |
+| Log in using Claris ID account (FileMaker Cloud) | Yes              | Yes                         |
+| Log out                             | Yes                           | Yes                         |
+| Get product information             | Manual*                       | No                          |
+| Get database names                  | Manual*                       | No                          |
+| Get script names                    | Manual*                       | No                          |
+| Get layout names                    | Manual*                       | No                          |
+| Get layout metadata                 | Manual*                       | No                          |
+| Create a record                     | Manual*                       | Yes                         |
+| Edit a record                       | Manual*                       | Yes                         |
+| Duplicate a record                  | Manual*                       | No                          |
+| Delete a record                     | Manual*                       | Yes                         |
+| Edit portal records                 | Manual*                       | Yes                         |
+| Get a single record                 | Manual*                       | Yes                         |
+| Get a range of records              | Manual*                       | Yes                         |
+| Get container data                  | Manual*                       | Yes                         |
+| Upload container data               | Manual*                       | Yes                         |
+| Perform a find request              | Manual*                       | Yes                         |
+| Set global field values             | Manual*                       | Yes                         |
+| Run a script                        | Manual*                       | Yes                         |
+| Run a script with another request   | Manual*                       | Yes                         |
+
+\* You can manually supply the URL and JSON to a `FmRest` connection.
+
+## Supported Ruby versions
+
+fmrest-ruby is [tested against](https://github.com/beezwax/fmrest-ruby/actions?query=workflow%3ACI)
+Ruby 2.6 through 3.1.
+
+## Gem development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rspec` to run the specs. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment (it will auto-load all
+fixtures in spec/fixtures).
+
+To install all gems onto your local machine, run
+`bundle exec rake all:install`. To release a new version, update the version
+number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
+which will create a git tag for the version, push git commits and tags, and
+push the `.gem` files to [rubygems.org](https://rubygems.org).
+
+## Disclaimer
+
+This project is not sponsored by or otherwise affiliated with Claris
+International Inc., an Apple Inc. subsidiary. FileMaker is a trademark of
+Claris International Inc., registered in the U.S. and other countries.

data/lib/fmrest/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "fmrest"
+
+module Rails
+  module FmRest
+    class Railtie < Rails::Railtie
+      initializer "fmrest.load_config" do
+        ::FmRest.default_connection_settings = Rails.application.config_for("fmrest")
+      end
+    end
+  end
+end

data/lib/fmrest-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "fmrest"

data/lib/generators/fmrest/config/config_generator.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# This is capitalized differently (Fmrest vs FmRest) on purpose, so the
+# generator can be found as "fmrest:config"
+module Fmrest
+  module Generators
+    class ConfigGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def copy_config_file
+        copy_file "fmrest.yml", "config/fmrest.yml"
+      end
+
+      def copy_initializer_file
+        copy_file "fmrest_initializer.rb", "config/initializers/fmrest.rb"
+      end
+    end
+  end
+end

data/lib/generators/fmrest/config/templates/fmrest.yml

@@ -0,0 +1,18 @@
+development:
+  host: 
+  database: 
+  username: 
+  password: 
+
+  # Additional options
+  #
+  # log: false
+  #
+  # ssl:
+  #   verify: true
+
+test:
+  host: 
+  database: 
+  username: 
+  password: 

data/lib/generators/fmrest/config/templates/fmrest_initializer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Use ActiveRecord token store
+FmRest.token_store = FmRest::TokenStore::ActiveRecord
+
+# Use ActiveRecord token store with custom table name
+# FmRest.token_store = FmRest::TokenStore::ActiveRecord.new(table_name: "my_token_store")
+
+# Use Redis token store (requires redis gem)
+# FmRest.token_store = FmRest::TokenStore::Redis
+
+# Use Redis token store with custom prefix
+# FmRest.token_store = FmRest::TokenStore::Redis.new(prefix: "my-fmrest-token:")
+
+# Use Moneta token store (requires moneta gem)
+# FmRest.token_store = FmRest::TokenStore::Moneta.new(backend: )
+
+# Use Memory token store (not suitable for production)
+# FmRest.token_store = FmRest::TokenStore::Memory

data/lib/generators/fmrest/model/model_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# This is capitalized differently (Fmrest vs FmRest) on purpose, so the
+# generator can be found as "fmrest:config"
+module Fmrest
+  module Generators
+    class ModelGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      def create_model_file
+        template "model.rb", "app/models/#{file_name}.rb"
+      end
+    end
+  end
+end

data/lib/generators/fmrest/model/templates/model.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < FmRest::Layout
+  # Uncomment if your layout name isn't "<%= class_name %>", or delete:
+  # layout "<%= plural_name %>"
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: fmrest-rails
+version: !ruby/object:Gem::Version
+  version: 0.22.0
+platform: ruby
+authors:
+- Pedro Carbajal
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-06-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fmrest-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+description: fmrest-rails provides Rails integration for the fmrest gem.
+email:
+- pedro_c@beezwax.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/fmrest-rails.rb
+- lib/fmrest/railtie.rb
+- lib/generators/fmrest/config/config_generator.rb
+- lib/generators/fmrest/config/templates/fmrest.yml
+- lib/generators/fmrest/config/templates/fmrest_initializer.rb
+- lib/generators/fmrest/model/model_generator.rb
+- lib/generators/fmrest/model/templates/model.rb
+homepage: https://github.com/beezwax/fmrest-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key:
+specification_version: 4
+summary: Rails ties and generators for fmrest gem
+test_files: []