{"id":17300857,"url":"https://github.com/chtjonas/camdram-ruby","last_synced_at":"2025-03-26T21:45:02.733Z","repository":{"id":32921815,"uuid":"139245343","full_name":"CHTJonas/camdram-ruby","owner":"CHTJonas","description":"A lovely API wrapper for Camdram written in Ruby","archived":false,"fork":false,"pushed_at":"2023-08-18T13:29:36.000Z","size":261,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T18:39:01.959Z","etag":null,"topics":["api-wrapper","cambridge","drama","ruby","student-theatre","theatre"],"latest_commit_sha":null,"homepage":"https://www.rubydoc.info/gems/camdram","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CHTJonas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-30T11:51:50.000Z","updated_at":"2023-08-18T13:37:27.000Z","dependencies_parsed_at":"2024-10-15T11:30:48.916Z","dependency_job_id":"7fcebef8-6ebd-49a4-b511-e8f138b039a9","html_url":"https://github.com/CHTJonas/camdram-ruby","commit_stats":{"total_commits":155,"total_committers":3,"mean_commits":"51.666666666666664","dds":0.4580645161290322,"last_synced_commit":"8fd88329f30a3b235d6aeeda6ee1260ed62e54fc"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CHTJonas%2Fcamdram-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CHTJonas%2Fcamdram-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CHTJonas%2Fcamdram-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CHTJonas%2Fcamdram-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CHTJonas","download_url":"https://codeload.github.com/CHTJonas/camdram-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245743341,"owners_count":20665090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","cambridge","drama","ruby","student-theatre","theatre"],"created_at":"2024-10-15T11:30:41.565Z","updated_at":"2025-03-26T21:45:02.703Z","avatar_url":"https://github.com/CHTJonas.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Warning**\n\u003e If you are viewing this README on the `main` branch then please note that this may contain as yet unreleased changes.\n\u003e You probably want to checkout a tag using the GitHub interface and view documentation for that specific version.\n\n# The Camdram Ruby Gem\n\n[![Gem Version](https://badge.fury.io/rb/camdram.svg)](https://badge.fury.io/rb/camdram)\n[![Build Status](https://github.com/CHTJonas/camdram-ruby/workflows/CI/badge.svg)](https://github.com/CHTJonas/camdram-ruby/actions?query=workflow%3ACI)\n\nThe Camdram gem is an API wrapper and interface for [Camdram](https://www.camdram.net) 🎭 that's made with love ❤️ and written in Ruby 💎.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'camdram'\n```\n\nAnd then run `bundle install`.\n\nOr install it yourself as:\n\n```shell\ngem install camdram\n```\n\n## Usage\n\nVersion 2 comes with significant backend changes which now allows you to use the [client credentials](http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4) OAuth strategy in addition to [authorisation code](http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1).\n\n### Client Credentials\n\nUse this strategy if you are writing a server-side application that accesses the Camdram API itself or on the behalf of the user who created it.\n\n```ruby\nrequire 'camdram/client'\nclient = Camdram::Client.new do |config|\n  config.client_credentials(app_id, app_secret)\n  config.user_agent = \"MyApp v1.0.0\"\n  config.base_url = \"https://www.camdram.net\"\nend\n```\n\n### Authorisation Code\n\nUse this strategy if you are authenticating a user via Camdram login and then acting on that user's behalf with an access token you already have from eg. [omniauth-camdram](https://github.com/camdram/omniauth-camdram).\nYou will need a hash of the access token and optionally, if you want to refresh the token after it expires, the refresh token and [Unix time](https://en.wikipedia.org/wiki/Unix_time) when the access token expires.\n\n```ruby\nrequire 'camdram/client'\ntoken_hash = {access_token: \"mytoken\", refresh_token: nil, expires_at: nil}\nclient = Camdram::Client.new do |config|\n  config.auth_code(token_hash, app_id, app_secret)\n  config.user_agent = \"MyApp v1.0.0\"\n  config.base_url = \"https://www.camdram.net\"\nend\n```\n\n### Read only\n\nIt's also possible to perform read-only requests to the Camdram API without API credentials, however this is *strongly* discouraged.\n\n```ruby\nrequire 'camdram/client'\nclient = Camdram::Client.new do |config|\n  config.read_only\n  config.user_agent = \"MyApp v1.0.0\"\n  config.base_url = \"https://www.camdram.net\"\nend\n```\n\n## Documentation\n\nFull documentation is generated automatically from the source code by [YARD](https://yardoc.org) and is available to view on\n[RubyDocs](https://www.rubydoc.info/gems/camdram).\n\n## Examples\n\nJust some of the things you can do after configuring a `client` object:\n```ruby\nclient.user.get_shows\nclient.user.get_shows[0].society\nclient.user.get_shows[0].venue\nclient.user.get_shows[0].performances\nclient.user.get_societies\nclient.user.get_societies[0].name\nclient.user.get_societies[0].twitter_id\nclient.user.get_venues\nclient.user.get_venues[0].slug\nclient.user.get_venues[0].facebook_id\n```\n\nThese public read-only actions don't require an access token (although you are still strongly advised to use one anyway):\n\n```ruby\nclient.get_show(6171)\nclient.get_show(\"2018-lucky\")\n\nclient.get_society(1)\nclient.get_society(\"cambridge-university-amateur-dramatic-club\")\n\nclient.get_venue(29)\nclient.get_venue(\"adc-theatre\")\n\nclient.get_person(13865)\nclient.get_person(\"charlie-jonas\")\n\nclient.get_society(\"cambridge-footlights\").shows\nclient.get_society(\"cambridge-footlights\").news\nclient.get_venue(\"cambridge-arts-theatre\").shows\nclient.get_venue(\"cambridge-arts-theatre\").news\n```\n\nIt's always a good idea to handle exceptions gracefully within your application. To that end, the Camdram gem raises the following:\n\n```ruby\nbegin\n  blargh\nresuce Camdram::Error::Timeout =\u003e e\n  # Handle HTTP socket and DNS lookup timeouts\nrescue Camdram::Error::ClientError =\u003e e\n  # Handle HTTP 4xx errors\nrescue Camdram::Error::ServerError =\u003e e\n  # Handle HTTP 5xx errors\nrescue Camdram::Error::GenericException =\u003e e\n  # Handle any other kind of error\n  # (note that all of the above classes inherit from GenericException)\nend\n```\n\n## Advanced Config\n\nNeed control of the HTTP backend, timeouts, redirects, headers, logging, proxying, client certificates etc.?\nThe Camdram gem uses the [OAuth2](https://github.com/oauth-xx/oauth2) gem as it's backend,\nwhich in turn uses [Faraday](https://github.com/lostisland/faraday) for making HTTP requests.\nTo that end, you can pass a block when instantiating a client that will be passed to the Faraday connection builder:\n\n```ruby\nrequire 'camdram/client'\nclient = Camdram::Client.new do |config|\n  config.client_credentials(app_id, app_secret) do |faraday|\n    faraday.request  :url_encoded          # form-encode POST params\n    faraday.response :logger               # log requests to $stdout\n    faraday.adapter  :patron do |session|  # make requests with Patron\n      session.connect_timeout = 1\n      session.timeout = 1\n      session.max_redirects = 1\n      session.proxy = 'hostname:8080'\n      # et cetera\n    end\n  end\nend\n```\n\nBe sure to checkout the documentation for Faraday and the adapter you want to use for more complex setups than the above.\nIf you don't give any block when instantiating then the OAuth2/Faraday defaults will be used (Net::HTTP at the time of writing).\n\n## Development\n\nFirst download a copy of the source code:\n\n```shell\ngit clone https://github.com/CHTJonas/camdram-ruby.git \u0026\u0026 cd camdram-ruby\n```\n\nOnce you've made a few changes you can test that things are still working as expected:\n\n```shell\nAPP_ID=yourappid APP_SECRET=yourappsecret rake test\n```\n\n## Contributing\n\nBug reports, enhancements and pull requests are welcome on [GitHub](https://github.com/CHTJonas/camdram-ruby)!\nIf you think this is something you can do yourself:\n1. Fork it ( https://github.com/CHTJonas/camdram-ruby/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Versioning\n\nThis library aims to adhere to [Semantic Versioning 2.0.0](http://semver.org/).\nViolations of this scheme should be reported as bugs.\nSpecifically, if a minor or patch version is released that breaks backward compatibility,\nthat version should be immediately yanked and/or a new version should be immediately released that restores compatibility.\nBreaking changes to the public API will only be introduced with new major versions.\nAs a result of this policy, you can (and should) specify a dependency on this gem using the\n[Pessimistic Version Constraint](http://guides.rubygems.org/patterns/#pessimistic-version-constraint) with two digits of precision.\n\n## Copyright\n\nCopyright (c) 2018 Charlie Jonas.\nSee [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchtjonas%2Fcamdram-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchtjonas%2Fcamdram-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchtjonas%2Fcamdram-ruby/lists"}