{"id":20814624,"url":"https://github.com/erdnaxeli/caridina","last_synced_at":"2025-05-07T12:02:15.372Z","repository":{"id":48478037,"uuid":"304663117","full_name":"erdnaxeli/caridina","owner":"erdnaxeli","description":"A Matrix client for Crystal","archived":false,"fork":false,"pushed_at":"2022-12-06T16:32:22.000Z","size":324,"stargazers_count":12,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-06T20:49:36.765Z","etag":null,"topics":["crystal-lang","matrix","matrix-library"],"latest_commit_sha":null,"homepage":"https://erdnaxeli.github.io/caridina/","language":"Crystal","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/erdnaxeli.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}},"created_at":"2020-10-16T15:14:00.000Z","updated_at":"2025-01-28T22:13:04.000Z","dependencies_parsed_at":"2023-01-24T07:31:13.323Z","dependency_job_id":null,"html_url":"https://github.com/erdnaxeli/caridina","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdnaxeli%2Fcaridina","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdnaxeli%2Fcaridina/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdnaxeli%2Fcaridina/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erdnaxeli%2Fcaridina/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erdnaxeli","download_url":"https://codeload.github.com/erdnaxeli/caridina/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252873951,"owners_count":21817712,"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":["crystal-lang","matrix","matrix-library"],"created_at":"2024-11-17T21:17:29.339Z","updated_at":"2025-05-07T12:02:15.325Z","avatar_url":"https://github.com/erdnaxeli.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# caridina 🦐\n\nA [Matrix](https://matrix.org) client library written in [Crystal](https://crystal-lang.org).\n\nIt is also a species of shrimp, one of them being named \"crystal red\". Crystal for the language, red for the Matrix's red pill.\n\n\u003cimg alt=\"a crystal red shrimp\" src=\"https://upload.wikimedia.org/wikipedia/commons/4/46/Caridina-cf-cantonensis-red-bee.jpg\" width=250/\u003e\n\n## Installation\n\n1. Add the dependency to your `shard.yml`:\n\n   ```yaml\n   dependencies:\n     caridina:\n       github: erdnaxeli/caridina\n   ```\n\n2. Run `shards install`\n\n## Usage\n\nThe API documentation is available [here](https://erdnaxeli.github.io/caridina/Caridina/Connection.html).\n\n### Connecting\n\nCreate a new connection object:\n\n```crystal\nrequire \"caridina\"\n\nconn = Caridina::Connection.new(\n  \"https://my-favorite-hs.example.org\",\n  \"my access token\",\n)\n```\n\nYou can also login to get a new access token:\n\n```crystal\naccess_token = Caridina::Connection.login(\n  \"https://my-favorite-hs.example.org\",\n  \"@mybotuserid:my-favorite-hs.example.org\",\n  \"my secret password\",\n)\n```\n\n### Sync\n\nNow we can create a new channel, and tell the connection object to start syncing.\nThe sync responses will be streamed in the channel.\n\n```Crystal\nmatrix = Channel(Caridina::Responses::Sync).new\nconn.sync(matrix)\n\nsync = matrix.receive\n```\n\nYou have now a [sync response](src/response/sync.cr).\n\nIf you don't want to go through the whole sync response by yourself (which is\nunderstandable), we provide you a [Caridina::Syncer](src/syncer.cr) object.\n\n```Crystal\nrequire \"caridina/syncer\"\n\nsyncer = Caridina::Syncer.new\nsyncer.on(Caridina::Events::Message) do |event|\n  event = event.as(Caridina::Events::Message)\n  # TODO: actually do something\nend\n\nsyncer.process_response(sync)\n```\n\n\u003e :warning: The syncer is a new feature still in development.\n\u003e It currently only supports events in the joined rooms timeline.\n\u003e To access to other events, you need to go through the sync response.\n\n### Read event\n\nThe events in the sync response are all `Caridina::Events::Event` objects.\nYou need to restrict the type of an event object to access all its fields.\n\n```Crystal\nsync.rooms.try \u0026.join.each do |room_id, room|\n  room.timeline.events.each do |event|\n    case event\n    when Caridina::Events::Member\n      # someone's membership changed\n    when Caridina::Events::PowerLevels\n      # some authorization changed\n    when Caridina::Events::Message\n      # someone talked\n    else\n      # unknown event\n    end\n  end\nend\n```\n\nSometimes the event's content can be polymorphic too.\nThat is especially the case for message events.\nBy using again a `case` clause to `event.content` you can restrict its type to access all its fields.\n\n### Send events\n\nThere is not a single method to send an event.\nInstead this library provides a set of methods that correspond to different\nactions you may want to do.\nYou usually do not need to worry about crafting the event to send.\n\n\u003e :warning: This part is in a early stage.\n\u003e Only a few methods are currently provided.\n\n```Crystal\n# join a room\nconn.join(\"!room_id:matrix.org\")\n# send a message\nevent_id = conn.send_message(\"!room_id:matrix.org\", \"Hello, world!\")\n# edit a message\nconn.edit_message(\"!room_id:matrix.org\", event_id, \"Hello, world!\")\n# send a read receipt\nconn.send_receipt(\"!room_id:matrix.org\", \"$event_id:matrix.org\")\n# Use the typing notification as a loader\nconn.typing(\"!room_id:matrix.org\") do\n  # Do some processing.\n  # While we are in the block, a typing notification will be shown on the given\n  # room.\n  conn.send_message(\"!room_id:matrix.org\", \"All done!\")\nend\n```\n\n## Development\n\nInstall the dependencies with `shards install`.\n\n* `make test` runs the tests\n* `make lint` runs the formater plus a linter\n\n## Contributing\n\n1. Fork it (\u003chttps://github.com/erdnaxeli/caridina/fork\u003e)\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## Contributors\n\n- [erdnaxeli](https://github.com/erdnaxeli) - creator and maintainer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferdnaxeli%2Fcaridina","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferdnaxeli%2Fcaridina","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferdnaxeli%2Fcaridina/lists"}