Skip to content

README.md

Latest commit

 

History

History
156 lines (124 loc) · 20 KB

README.md

File metadata and controls

156 lines (124 loc) · 20 KB

Xminds

Ruby client for Crossing Minds API

Installation

Add this line to your application's Gemfile:

gem 'xminds'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install xminds

Usage

By default, the library is configured to use Crossing Minds primary endpoint - https://api.crossingminds.com - as the endpoint and accepts configuration values needed for the specific account type to create the client: endpoint, email, password, database ID, service name, and frontend user ID from the following environment variables: XMINDS_API_ENDPOINT, XMINDS_API_EMAIL, XMINDS_API_PWD, XMINDS_API_DATABASE_ID, XMINDS_API_SERVICE_NAME, XMINDS_API_FRONTEND_USER_ID and XMINDS_API_FRONTEND_SESSION_ID. To configure the library differently:

Xminds.configure do |config|
  config.endpoint         = 'https://api.crossingminds.com' # overwrites defaults of https://api.crossingminds.com and $XMINDS_API_ENDPOINT
  config.email            = 'example.user@xminds.com'       # overwrites default of $XMINDS_API_EMAIL
  config.password         = 'MyP@ssw0rd'                    # overwrites default of $XMINDS_API_PWD
  config.database_id      = 'wSSZQbPxKvBrk_n2B_m6ZA'        # overwrites default of $XMINDS_API_DATABASE_ID
  config.service_name     = 'Example DB name'               # overwrites default of $XMINDS_API_SERVICE_NAME
  config.frontend_user_id = 12358                           # overwrites default of $XMINDS_API_FRONTEND_USER_ID
  config.frontend_session_id       = 85321                           # overwrites default of $XMINDS_API_FRONTEND_SESSION_ID
end

Examples

Here is an example on how to setup the configuration with an initializer, then create a root client and list all accounts.

# global initializer
Xminds.configure do |config|
  config.email = 'root.account@example.com'
  password     = 'MyP@ssw0rd'
end

# client creation (defaults to root) and usage
client = Xminds::Client.new

client.list_all_accounts

Here is an example on how to setup an individual client without a configuration.

client = Xminds::Client.new(
  type: :individual,
  email: 'individual.account@example.com',
  password: 'MyP@ssw0rd',
  database_id: 'wSSZQbPxKvBrk_n2B_m6ZA',
  frontend_user_id: '5906d464-7ef1-4377-96e3-529f2ed6721d', # optional
  frontend_session_id: '6306d431-6fe4-9877-12e3-412f2ed6832d' # optional
)

client.list_all_accounts

Or a service account without a configuration.

client = Xminds::Client.new(
  type: :service,
  service_name: 'myapp-web',
  password: 'MyP@ssw0rd',
  database_id: 'wSSZQbPxKvBrk_n2B_m6ZA',
  frontend_user_id: '5906d464-7ef1-4377-96e3-529f2ed6721d', # optional
  frontend_session_id: '6306d431-6fe4-9877-12e3-412f2ed6832d' # optional
)

client.list_all_accounts

Supported Endpoints

All of Crossing Minds endpoints are supported by this gem.

Object Action Method
Authentication [GET] List all accounts Client#list_all_accounts
[POST] Create individual account Client#create_individual_account(email:, password:, role:, first_name:, last_name:)
[DELETE] Delete individual account Client#delete_individual_account(email:)
[POST] Create service account Client#create_service_account(service_name:, password:, role:)
[DELETE] Delete service account Client#delete_service_account(service_name:)
[POST] Login as individual account Client#login_as_individual(email:, password:, database_id:, frontend_user_id: nil, frontend_session_id: nil)
[POST] Login as service account Client#login_as_service(service_name:, password:, database_id:, frontend_user_id: nil, frontend_session_id: nil)
[POST] Login as root account Client#login_as_root(email:, password:)
[POST] Renew login with refresh token Client#renew_login_with_refresh_token(refresh_token:)
[POST] Renew login with refresh token Client#resend_email_verification_code(email:)
[GET] Verify email Client#verify_email(email:, code:)
[DELETE] Delete current account Client#delete_current_account
Database [POST] Create new database Client#create_database(database_name:, description:, item_id_type:, user_id_type:)
[GET] List all databases Client#list_all_databases(page: nil, amount: nil)
[GET] Get current database Client#current_database
[DELETE] Delete current database Client#delete_current_database
[GET] Get current database status Client#current_database_status
UsersDataAndProperties [GET] List all user properties Client#list_all_user_properties
[POST] Create new user property Client#create_user_property(property_name:, value_type:, repeated: false)
[GET] Get a user property Client#get_user_property(property_name:)
[DELETE] Delete a user property Client#delete_user_property(property_name:)
[GET] Get a user Client#get_user(user_id:)
[PUT] Create or update a user Client#create_or_update_user(user_id:, user:)
[PATCH] Partial update one user Client#partial_update_user(user_id:, user:, create_if_missing: false)
[PUT] Create or update users in bulk Client#create_or_update_user_bulk(users:)
[PATCH] Partial update many users in bulk Client#partial_update_user_bulk(users:, create_if_missing: false)
[GET] List all users Client#list_all_users(amount: nil, cursor: nil)
[POST] List all users by user ID Client#list_all_users_by_id(user_ids:)
ItemsDataAndProperties [GET] List all item properties Client#list_all_item_properties
[POST] Create new item property Client#create_item_property(property_name:, value_type:, repeated: false)
[GET] Get a item property Client#get_item_property(property_name:)
[DELETE] Delete a item property Client#delete_item_property(property_name:)
[GET] Get a item Client#get_item(item_id:)
[PUT] Create or update a item Client#create_or_update_item(item_id:, item:)
[PATCH] Partial update one item Client#partial_update_item(item_id:, item:, create_if_missing: false)
[PUT] Create or update items in bulk Client#create_or_update_item_bulk(items:)
[PATCH] Partial update many items in bulk Client#partial_update_item_bulk(items:, create_if_missing: false)
[GET] List all items Client#list_all_items(amount: nil, cursor: nil)
[POST] List all users by item ID Client#list_all_items_by_id(item_ids:)
[UserRatings] [PUT] Create or update a rating Client#create_or_update_rating(user_id:, item_id:, rating:, timestamp: nil)
[DELETE] Delete a rating Client#delete_rating(user_id:, item_id:)
[GET] List all ratings for a user Client#list_all_ratings_for_user(user_id:, page: nil, amount: nil)
[PUT] Create or update ratings for a user in bulk Client#create_or_update_ratings_for_user_bulk(user_id:, ratings:)
[DELETE] Delete a ratings for a user Client#delete_all_ratings_for_user(user_id:)
[PUT] Create or update ratings in bulk Client#create_or_update_ratings_bulk(ratings:)
[GET] List all ratings Client#list_all_ratings(amount: nil, cursor: nil)
UserInteractions [POST] Create one interaction Client#create_user_interaction(user_id:, item_id:, interaction_type:, timestamp: nil)
[POST] Create interactions for many users in bulk Client#create_user_interactions_bulk(interactions:)
Recommendation [GET] List recommendations for similar items Client#list_similar_item_recommendations(item_id:, amount: nil, cursor: nil, filters: nil)
[GET] List recommendations for session based items Client#list_session_based_item_recommendations(amount: nil, cursor: nil, filters: nil, ratings: nil, user_properties: nil, exclude_rated_items: false)
[GET] List recommendations for profile based items Client#list_profile_based_item_recommendations(user_id:, amount: nil, cursor: nil, filters: nil, exclude_rated_items: false)
BackgroundTasks [POST] Trigger a background task Client#trigger_background_task(task_name:)
[GET] List recent background tasks Client#list_recent_background_tasks(task_name:)

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Crossing-Minds/xminds-ruby.

License

The gem is available as open source under the terms of the MIT License.