{"id":19353526,"url":"https://github.com/elldritch/pokemon-showdown-api","last_synced_at":"2025-04-23T07:31:29.440Z","repository":{"id":44936512,"uuid":"43189736","full_name":"elldritch/pokemon-showdown-api","owner":"elldritch","description":"An API for Pokemon Showdown.","archived":false,"fork":false,"pushed_at":"2022-01-17T14:59:50.000Z","size":50,"stargazers_count":4,"open_issues_count":2,"forks_count":6,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-04-02T10:12:48.376Z","etag":null,"topics":["pokemon","pokemon-showdown"],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elldritch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-26T03:16:48.000Z","updated_at":"2024-07-23T15:45:49.000Z","dependencies_parsed_at":"2022-09-26T21:41:17.295Z","dependency_job_id":null,"html_url":"https://github.com/elldritch/pokemon-showdown-api","commit_stats":null,"previous_names":["ilikebits/pokemon-showdown-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elldritch%2Fpokemon-showdown-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elldritch%2Fpokemon-showdown-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elldritch%2Fpokemon-showdown-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elldritch%2Fpokemon-showdown-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elldritch","download_url":"https://codeload.github.com/elldritch/pokemon-showdown-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250391280,"owners_count":21422870,"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":["pokemon","pokemon-showdown"],"created_at":"2024-11-10T04:43:11.068Z","updated_at":"2025-04-23T07:31:28.976Z","avatar_url":"https://github.com/elldritch.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pokemon-showdown-api\n\n`pokemon-showdown-api` is a low-level library for connecting to and interacting\nwith the Pokemon Showdown server.\n\n**This package is under development. Its documentation is not complete and there\nremain additional events to be added, but it is mostly API-stable.**\n\n## Overview\n\nThis package presents a low-level API for interacting with Pokemon Showdown\nservers, and tries to avoid making any assumptions about the consumer's goals.\nIn particular, this API is designed so that _other_ APIs can be built on top of\nit (for example, to add logic for handling rooms or battles).\n\nExplicit goals:\n\n1. Don't leak memory over time (this is critical for long-running consumers).\n2. Be fast.\n\n(Goal 1 implies that no O(n) logs can be stored, precluding the storing of\nmessages or rooms. If a consumer needs these features, they should implement\nthis on their own.)\n\nThese lead to two explicit non-goals:\n\n1. No handling logic for rooms.\n2. No handling logic for battles.\n\nInstead, this API is built to enable additional libraries to provide such\nfunctionality.\n\n## Usage\n\nTo install, run `npm install pokemon-showdown-api`.\n\n(If you want to use a REPL to try and interact with Pokemon Showdown from the\ncommand line, try out `npm install --global pokemon-showdown-api` and use\n`pokerepl`.)\n\nIn order to instantiate a client, pass the server websocket URL and login server\nURL. Both are optional, defaulting to the official Pokemon Showdown servers.\n\n```js\nvar PokeClient = require('pokemon-showdown-api');\n\nvar client = new PokeClient();\n// By default, this is equivalent to:\n// var client = new PokeClient('ws://sim.smogon.com:8000/showdown/websocket', 'https://play.pokemonshowdown.com/action.php');\n```\n\nThe client will emit events for consumers to listen on. The client does not\nstore any messages, instead delegating this responsibility to consumers.\n(Storing messages uses memory over time, and not all consumers may need this.)\n\n```js\nclient.connect();\n\n// Websocket has connected.\nclient.on('ready', function() {\n  client.login('username', 'password');\n});\n\n// Successful login.\nclient.on('login', function(user) {\n  console.log('Logged in as:', user);\n});\n\n// A battle challenge from another user has been received.\nclient.on('challenge', function(user) {\n  console.log(user, 'would like to battle!');\n});\n\n// Login failed.\nclient.on('error:login', function(err) {\n  console.log('Error encountered while logging in:', err.message);\n});\n```\n\nIn general, any sort of message can be sent using `client.send`. This package\nalso provides a convenience method authentication using\n`client.login(username, password)`.\n\nFor more details, see [the API docs](./docs/API.md).\n\nFor notes on protocol specifics, see\n[Pokemon Showdown Protocol](https://github.com/Zarel/Pokemon-Showdown/blob/master/PROTOCOL.md),\n[command parsing source code](https://github.com/Zarel/Pokemon-Showdown-Client/blob/b3ab4374444c52eaf8064353f6b7497ac9e022d4/js/client-chat.js#L341),\nand\n[socket message parsing source code](https://github.com/Zarel/Pokemon-Showdown-Client/blob/05c89b54d74aca2f39ff7539bffe414d88b610e5/js/client.js#L734).\n\n## Notes about Pokemon Showdown's implementation\n\nPokemon Showdown is effectively implemented as a fancy chat room. Some of these\nare considered regular \"chat\" rooms, and others are considered \"battle\" rooms.\nWithin battle rooms, a battle is conducted by sending special chat messages back\nand forth, with the server validating each message.\n\nAuthentication occurs by talking to a separate authentication server. The\nprocess is as follows:\n\n1. Get the challenge string (`challstr`) upon connecting to the main server\n2. Pass the `challstr` along with a proposed username (and password, if needed)\n   to the login server\n3. The login server returns an `assertion`, which is passed to the main server\n   to prove ownership of a username.\n\n## Roadmap\n\n### Ongoing\n1. Additional documentation\n2. Additional events\n\n### Next up\n1. An adapter taking JSON or MessagePack commands on `stdin` and emitting output\n   on `stdout` to allow this library to be embedded in other projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felldritch%2Fpokemon-showdown-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felldritch%2Fpokemon-showdown-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felldritch%2Fpokemon-showdown-api/lists"}