{"id":13410330,"url":"https://github.com/mewna/catnip","last_synced_at":"2025-09-29T07:32:15.116Z","repository":{"id":33266204,"uuid":"147063521","full_name":"mewna/catnip","owner":"mewna","description":"A reactive, fully-async Discord API wrapper for the JVM, built on RxJava 3.","archived":true,"fork":false,"pushed_at":"2023-04-17T23:10:08.000Z","size":98869,"stargazers_count":151,"open_issues_count":54,"forks_count":33,"subscribers_count":4,"default_branch":"mistress","last_synced_at":"2024-09-27T07:40:57.442Z","etag":null,"topics":["discord","discord-api","discord-api-wrapper","discord-bot","hacktoberfest","java","reactive","vertx"],"latest_commit_sha":null,"homepage":"https://discord.gg/yeF2HpP","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mewna.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-09-02T07:16:40.000Z","updated_at":"2024-09-14T02:49:26.000Z","dependencies_parsed_at":"2024-09-16T12:35:59.071Z","dependency_job_id":"4a221166-71ab-4514-9f0e-2cbc02ba1a23","html_url":"https://github.com/mewna/catnip","commit_stats":null,"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mewna%2Fcatnip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mewna%2Fcatnip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mewna%2Fcatnip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mewna%2Fcatnip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mewna","download_url":"https://codeload.github.com/mewna/catnip/tar.gz/refs/heads/mistress","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234600846,"owners_count":18858545,"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":["discord","discord-api","discord-api-wrapper","discord-bot","hacktoberfest","java","reactive","vertx"],"created_at":"2024-07-30T20:01:06.266Z","updated_at":"2025-09-29T07:32:09.743Z","avatar_url":"https://github.com/mewna.png","language":"Java","funding_links":[],"categories":["API Libraries","Libraries"],"sub_categories":["Java"],"readme":"# PROJECT STATUS\n\n**This project is no longer maintained.** I don't have time to maintain it anymore, and I don't really use Discord's API much anymore anyway. If you want to maintain this library, please see issue [#729](https://github.com/mewna/catnip/issues/729).\n\n# catnip\n\n![Github Actions -- tests](https://github.com/mewna/catnip/workflows/Run%20all%20tests/badge.svg)\n![Github Actions -- docs](https://github.com/mewna/catnip/workflows/Build%20docs/badge.svg)\n[![powered by potato](https://img.shields.io/badge/powered%20by-potato-%23db325c.svg)](https://mewna.com/)\n![GitHub tag (latest by date)](https://img.shields.io/github/tag-date/mewna/catnip.svg?style=popout)\n![LGTM Grade](https://img.shields.io/lgtm/grade/java/github/mewna/catnip)\n\nA Discord API wrapper in Java. Fully async / reactive, built on top of\n[RxJava](http://reactivex.io). catnip tries to map roughly 1:1 to how the Discord \nAPI works, both in terms of events and REST methods available. catnip uses Java 17+.\n\ncatnip is part of the [amyware Discord server](https://discord.gg/yeF2HpP).\n\nLicensed under the [BSD 3-Clause License](https://tldrlegal.com/license/bsd-3-clause-license-(revised)).\n\n## Installation\n\n[Get it on Jitpack](https://jitpack.io/#com.mewna/catnip)\n\nCurrent version: ![GitHub tag (latest by date)](https://img.shields.io/github/tag-date/mewna/catnip.svg?style=popout)\n\n### Can I just download a JAR directly?\n\nNo. Use a real build tool like [Maven](https://maven.apache.org/) or [Gradle](https://gradle.org/).\n\n### Javadocs?\n\n[Get them here.](https://mewna.github.io/catnip)\n\n## Features\n\n- Automatic sharding\n- Very customizable - you can write [extensions](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/extension/Extension.java)\n  for the library, as well as [options](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/CatnipOptions.java)\n  for most anything you could want to change. See `EXTENSIONS.md` for more.\n- Modular - REST / shards can be used independently. See `MODULAR_USAGE.md` for more.\n- Customizable caching - Can run with [no cache](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/cache/NoopEntityCache.java),\n  [partial caching](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/cache/CacheFlag.java),\n  or [write your own cache handler](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/cache/EntityCacheWorker.java).\n  See `CACHING.md` for more.\n- Asynchronous cache accesses.\n- You can disable individual events.\n- You can disable all events, and handle gateway events directly.\n- Customizable ratelimit/session data handling - wanna store your \n  [sessions/seqnums](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/shard/session/SessionManager.java) \n  and [REST ratelimit data](https://github.com/mewna/catnip/tree/mistress/src/main/java/com/mewna/catnip/rest/ratelimit)\n  in Redis, but [gateway ratelimits](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/shard/ratelimit/Ratelimiter.java)\n  in memory? You can do that!\n- [Customizable shard management](https://github.com/mewna/catnip/blob/mistress/src/main/java/com/mewna/catnip/shard/manager/ShardManager.java)\n\n## Basic usage\n\nThis is the simplest possible bot you can make right now:\n\n```Java\nfinal Catnip catnip = Catnip.catnip(\"your token goes here\");\ncatnip.observable(DiscordEvent.MESSAGE_CREATE)\n    .filter(msg -\u003e msg.content().equals(\"!ping\"))\n    .subscribe(msg -\u003e {\n        msg.respond(\"pong!\");\n    }, error -\u003e error.printStackTrace());\ncatnip.connect();\n```\n\ncatnip returns RxJava operators (`Completable`/`Observable`/`Single`/...) from\nall REST methods. For example, editing your ping message to include time it\ntook to create the message:\n\n```Java\nfinal Catnip catnip = Catnip.catnip(\"your token goes here\");\ncatnip.observable(DiscordEvent.MESSAGE_CREATE)\n        .filter(msg -\u003e msg.content().equals(\"!ping\"))\n        .subscribe(msg -\u003e {\n            long start = System.currentTimeMillis();\n            msg.respond(\"pong!\")\n                    .subscribe(ping -\u003e {\n                        long end = System.currentTimeMillis();\n                        ping.edit(\"pong! (took \" + (end - start) + \"ms).\");\n                    });\n        }, error -\u003e error.printStackTrace());\ncatnip.connect();\n```\n\nYou can also create a catnip instance asynchronously:\n\n```Java\nCatnip.catnipAsync(\"your token here\").subscribe(catnip -\u003e {\n    catnip.observable(DiscordEvent.MESSAGE_CREATE)\n        .filter(msg -\u003e msg.content().equals(\"!ping\"))\n        .subscribe(msg -\u003e {\n            msg.respond(\"pong!\");\n        }, error -\u003e error.printStackTrace());\n    catnip.connect();\n});\n```\n\nAlso check out the [examples](https://github.com/mewna/catnip/tree/mistress/src/main/example/basic) for Kotlin and Scala usage.\n\n### A note on Observable#subscribe vs. Observable#forEach\n\n`Observable#forEach` seems like the obvious way to use the reactive methods, but as it turns out,\nit's also the wrong thing to do. `Observable#forEach` is generally intended for finite streams of\ndata; the events that catnip emits aren't finite, and as such, `Observable#forEach` isn't the\ncorrect tool to use. In addition, **`Observable#forEach` will stop processing events if an uncaught\nexception is thrown.** Instead, you should use `Observable#subscribe(eventCallback, exceptionCallback)`,\nwhich will handle exceptions properly.\n\n### Modular usage\n\ncatnip supports being used in REST-only or shards-only configurations. The nice thing about catnip\nis that using it like this is **exactly the same** as using it normally. The only difference is\nthat to use catnip in REST-only mode, you don't call `catnip.connect()` and use \n`catnip.rest().whatever()` instead. \n\n### RxJava schedulers\n\nBy default, RxJava's `Observable#subscribe()` and related methods will not operate on any\nparticular scheduler by default. That is, they will run on the calling thread. catnip will\nautomatically subscribe RxJava objects onto a scheduler provided by catnip, that defaults\nto being a ForkJoinPool-based scheduler. You can customize the scheduler used with the\ncorresponding option in `CatnipOptions`.\n\n## Useful extensions\n\n- `catnip-voice` - Voice support for your catnip bot. \n  https://github.com/natanbc/catnip-voice\n- `catnip-utilities` - Some extensions for typesafe commands, event waiters, reaction menus, \n  and more. https://github.com/queer/catnip-utilities \n- `discordbotlist-stats-catnip` - Wrapper aiming at combining all Discord Bot Lists AND Wrappers into one artifact.\n  Automatically handles pushing bot stats to bot lists. https://github.com/burdoto/discordbotlist-stats#using-with-catnip--\n\n## Why write a fourth Java lib?\n\n- I didn't want ten billion events for every possible case. catnip maps more/less 1:1 with the\n  Discord API, and any \"extra\" events on top of that need to be user-provided via extensions or\n  other means. I guess really I just didn't want my lib to be as \"high-level\" as other libs are.\n- I wanted to try to maximize extensibility / customizability, beyond just making it modular. Things\n  like being able to intercept raw websocket messages (as JSON), write custom distributed cache handlers,\n  ... are incredibly useful.\n- I like everything returning Rx classes instead of custom `Future`-like classes. I do get why other libs\n  have them, I just wanted to not.\n- I wanted modular usage to be exactly the same more / less no matter what; everything\n  should be doable through the catnip instance that you create.\n- I wanted to make a lib built on RxJava.\n- To take over the world and convert all Java bots. :^)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmewna%2Fcatnip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmewna%2Fcatnip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmewna%2Fcatnip/lists"}