CirroIOV2::Client

This gem provides access to the Cirro REST API v2.

Installation

Add this line to your application's Gemfile:

gem 'cirro-ruby-client'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install cirro-ruby-client

Configuration

# with key path
client = CirroIOV2::Client.new(private_key_path: "./storage/cirro_key.pem", client_id: "WULnc6Y0rlaTBCSiHAb0kGWKFuIxPWBXJysyZeG3Rtw", site: "https://api.staging.cirro.io")

# with key string
client = CirroIOV2::Client.new(private_key: Rails.application.credentials.cirro_private_key, client_id: "WULnc6Y0rlaTBCSiHAb0kGWKFuIxPWBXJysyZeG3Rtw", site: "https://api.staging.cirro.io")

Usage

User

Get user info

user = client.User.find(1)
# => User object

user.first_name
# => 'Grazyna'

user.worker
# => { billable: false, document: {...} }

Create or update a worker document for a user

Will automatically create a worker account if not existing

user = client.User.worker(1, document: { foo: :bar })
# => User object

user.worker.document
# => { foo: :bar }

Get notification preference of a user

client.User.notification_preference(1)
# => NotificationPreference object

Create or Update notification preferences for a user

client.User.notification_preferences(1, {
  locale: 'de',
  topics: [
    { id: '1', preferences: { email: 'immediately' } },
    { id: '2', preferences: { email: 'digest_daily' } }
  ]
})

Seed user (staging/dev only)

# With params (all of them optional)
# Password must include at least: 2 letters, 2 digits, 2 special characters
# Email must be unique
client.User.create(
  first_name: 'Human',
  last_name: 'Being',
  email: 'iamhuman@test.io',
  time_zone: 'Berlin',
  country_code: 'DE',
  birthday: '1975-11-22',
  password: '@123456abc@'
)
# => User object

# Without params (nimbus-style, all params are seeded by Cirro)
client.User.create
# => User object

Gig

Find a gig

client.Gig.find(ID)
# => Gig object

Create a gig

client.Gig.create(
  title: "Favourite programming language?",
  description: "Description of gig ...",
  url: "http://heathcote.co/zina.gibson",
  start_at: 1652285764,
  end_at: 1653412329,
  seats_min: 2,
  seats_max: 2,
  invitation_mode: "auto",
  filter_query: {
    status: "active",
    segment: "my_favorite_testers"
  },
  tasks: [
    { title: "Ah, Wilderness!", base_price: 300 }
  ],
  notification_payload: {
    project_title: "Corporate Tax",
    task_title: "Add dataset",
    task_type: "Review"
  },
  epam_options: {
    extra_mile: true
  }
)
# => Gig object

Update a gig

When your gig is already started, you can not update start_at anymore

gig_id = 1
client.Gig.update(gig_id,
  title: "Favourite programming language?",
  description: "Description of gig ...",
  url: "http://heathcote.co/zina.gibson",
  start_at: 1652285764,
  end_at: 1653412329,
  seats_min: 2,
  seats_max: 2,
  invitation_mode: "auto",
  filter_query: {
    status: "active",
    segment: "my_favorite_testers"
  },
  notification_payload: {
    project_title: "Corporate Tax",
    task_title: "Add dataset",
    task_type: "Review"
  },
  epam_options: {
    extra_mile: true
  }
)
# => Gig object

Archive a gig

gig_id = 1

# archive now
client.Gig.archive(gig_id)

# archive later
client.Gig.archive(gig_id, archive_at: 1.day.from_now)

Delete a gig

gig_id = 1

client.Gig.delete(gig_id)

Manually invite user to a gig

Invite single user

gig_id = 1
app_user_id = 1

client.Gig.invite(gig_id, { user_id: app_user_id })
# => GigInvitation object

Invite multiple users and overwrite no_reward

gig_id = 1
users = [{ id: 1, no_reward: true }, { id: 2, no_reward: true }]

client.Gig.invite(gig_id, { users: users })
# => GigInvitationList object

GigTask

Add a new gig task to gig

gig_id = 1

client.Gig.tasks(gig_id, { title: "Critical Bug", base_price: 100 })
# => GigTask object

Update a gig task

gig_id = 1
gig_task_id = 1

client.Gig.update_task(gig_id, gig_task_id, { base_price: 100 })
# => GigTask object

GigInvitation

Get list of gig invitations

By default the response is paginated with 10 per page. The has_more attribute indicates whether there're more records to be fetched or not. You can move from page to page using after or before.

# return all with max limit
client.GigInvitation.list(limit: 100)

# return paginated after gig invitation ID 100
client.GigInvitation.list(limit: 100, after: 100)

# return paginated before gig invitation ID 100
client.GigInvitation.list(limit: 100, before: 100)

# filter by user with ID 1 and gig with ID 1
client.GigInvitation.list(user_id: 1, gig_id: 1)

# filter by status
client.GigInvitation.list(status: ['pending', 'accepted'])
client.GigInvitation.list(status: 'accepted')

list = client.GigInvitation.list(limit: 100)
# => ListObject

list.has_more?
# => true

list.data
# => Array of GigInvitation objects

Accept a gig invitation

client.GigInvitation.accept(1)

# overwrite no_reward
client.GigInvitation.accept(1, no_reward: true)

Reject a gig invitation

client.GigInvitation.reject(1)

Expire a gig invitation

client.GigInvitation.expire(1)

Reset an accepted or expired gig invitation

client.GigInvitation.reset(1)

# prevent reset notification
client.GigInvitation.reset(1, silent: true)

GigTimeActivity

List all gig time activities

list = client.GigTimeActivity.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of GigTimeActivity objects

# filters
client.GigTimeActivity.list(gig_id: 1, user_id: 1)

# pagination
client.GigTimeActivity.list(limit: 100, after: 100)

Create a gig time activity

You can't create gig time activity if the given user is not in your space or for the given user the gig invitation is set to no_reward

client.GigTimeActivity.create(
  gig_id: 1,
  user_id: 1,
  date: "2023-04-10",
  description: "Time Report for Space XYZ",
  duration_in_ms: 1.hour.in_seconds * 1000 # make sure not to report > 8h per day
)

GigResult

List all gig results

list = client.GigResult.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of GigResult objects

# filters
client.GigResult.list(gig_id: 1, user_id: 1)

# pagination
client.GigResult.list(limit: 100, after: 100)

Create a gig result

You can't create gig result if the given user is not in your space or for the given user the gig invitation is set to no_reward

client.GigResult.create(
  gig_task_id: 1,
  user_id: 1,
  title: "Work for task1",
  escription: "Good work for task1",
  quantity: 2,
  multiplier: 1.2,
  delivery_date: "2023-04-10",
  cost_center_key: "EPMTIO"
)

BonusPayout

List all payouts

list = client.Payout.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of Payout objects

# filters
client.Payout.list(reference_id: 1, reference_type: 'Gig', user_id: 1)

# pagination
client.Payout.list(limit: 100, after: 100)

Create a bonus payout

client.Payout.create(
  user_id: 1,
  title: "Bonus Payment",
  description: "Good work!",
  amount: 1000,
  billing_date: "2023-04-10",
  cost_center_key: "EPMTIO"
)

Delete a bonus payout

Only allowed for unbilled ones

client.Payout.delete(1)

Notifications

Notification Locale

Create a notification locale

locale = client.NotificationLocale.create(locale: 'de')
# => NotificationLocale object

locale.locale
# => 'de'

locale.configurations
# => Array of NotificationConfiguration objects

List all notification locales

list = client.NotificationLocale.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of NotificationLocale objects

client.NotificationLocale.list(default: true) # filter by default

Notification Configuration

List all notification configurations

list = client.NotificationConfiguration.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of NotificationConfiguration objects

client.NotificationConfiguration.list(locale: 'de') # filter by locale

client.NotificationConfiguration.list(limit: 100, after: 100) # pagination

Notification Layout

List all notification layouts

list = client.NotificationLayout.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of NotificationLayout objects

client.NotificationLayout.list(limit: 100, after: 100) # pagination

Create a notification layout

client.NotificationLayout.create(
  name: 'custom_layout',
  templates: [
    { notification_configuration_id: '1', body: '<p>hello {{recipient}}</p>' },
    { notification_configuration_id: '2', body: '<p>hallo {{recipient}}</p>' }
  ]
)

Update a notification layout

client.NotificationLayout.update('1', name: 'custom_layout')

Create a new template

client.NotificationLayout.create_template(
  '1',
  { notification_configuration_id: '1', body: '<p>hello {{recipient}}</p>' }
)
# => NotificationLayoutTemplate object

Notification Layout Template

Update a notification layout template

client.NotificationLayoutTemplate.update(
  '1',
  { notification_configuration_id: '1', body: '<p>hello {{recipient}}</p>' }
)

Delete a notification layout template

client.NotificationLayoutTemplate.delete('1')

Notification Topic

List all notification topics

list = client.NotificationTopic.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of NotificationTopic objects

# filter by layout_id
client.NotificationTopic.list(notification_layout_id: 1)

# pagination
client.NotificationTopic.list(limit: 10, after: 10)

Create a notification topic

client.NotificationTopic.create(
  name: 'new_bug_comment',
  notification_layout_id: 1,
  preferences: {
    email: 'immediately'
  },
  templates: [
    {
      "notification_configuration_id": "1",
      "subject": "New Bug Comment",
      "body": "Hello {{recipient_first_name}}, you got {{pluralize count, 'new comment', 'new comments'}}"
    },
    {
      "notification_configuration_id": "2",
      "subject": "Neuer Kommentar",
      "body": "Hallo {{recipient_first_name}}, Du hast {{pluralize count, 'neuen Kommentar', 'neue Kommentare'}}"
    }
  ]
)

Find a notification topic

client.NotificationTopic.find(1)
# => NotificationTopic object

Update a notification topic

client.NotificationTopic.update(1, { name: "NewTopicName", preferences: { email: "daily" } })
# => NotificationTopic object

Delete a notification topic

topic = client.NotificationTopic.delete(1)
# => NotificationTopicDelete object

topic.deleted
# => true

Notification (Topic) Template

List all

list = client.NotificationTemplate.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of NotificationTemplate objects

# filter by topic id
client.NotificationTemplate.list(notification_topic_id: 1)

# filter by configuration id
client.NotificationTemplate.list(notification_configuration_id: 1)

# pagination
client.NotificationTemplate.list(limit: 10, after: 10)

Update a notification template

client.NotificationTemplate.update(
  '1',
  "subject": "New Bug Comment",
  "body": "Hello {{recipient_first_name}}, you got {{pluralize count, 'new comment', 'new comments'}}"
)

Delete a notification template

client.NotificationTemplate.delete(1)

Notifcation Topic Preference

List all

list = client.NotificationTopicPreference.list
# => ListObject

list.has_more?
# => true

list.data
# => Array of NotificationTopicPreference objects

# filter by topic id
client.NotificationTopicPreference.list(notification_topic_id: 1)

# filter by user id
client.NotificationTopicPreference.list(user_id: 1)

# pagination
client.NotificationTopicPreference.list(limit: 10, after: 10)

Notifcation Broadcast

Create a notifcation broadcast

client.NotificationBroadcast.create(
  payload: {
    foo: 'bar',
    key: 'value'
  },
  recipients: {
    user_ids: [1, 2, 3]
  },
  notification_topic_id: 1
)

CirroIO::Client (DEPRECATED)

Configuration

You need to create an initializer file in config/initializers.

CirroIO::Client.configure do |c|
  c.app_id 'WULnc6Y0rlaTBCSiHAb0kGWKFuIxPWBXJysyZeG3Rtw'
  c.private_key_path './storage/cirro.pem'
  c.site 'https://api.staging.cirro.io'
end

Usage

Bulk create gig invitations

gig = CirroIO::Client::Gig.load(id: 1)
filter = CirroIO::Client::WorkerFilter.new(filter_query: '{ "app_worker_id": { "$in": [1,2,3] } }')
invitation = CirroIO::Client::GigInvitation.new(gig: gig)

invitation.bulk_create_with(filter, auto_accept: true) # by default auto_accept is false

Creating Payouts for workers

app_worker = CirroIO::Client::AppWorker.load(id: 1234)

CirroIO::Client::Payout.create(
  app_worker: app_worker,
  amount: 100, # € 1.00
  title: "Bonus for something",
  description: "Description of the bonus.",
  cost_center_key: "PROJECT-CODE",
  billing_date: DateTime.now
)

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 wait for circle CI to complete, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

License

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