{"id":13410996,"url":"https://github.com/detritusjs/client","last_synced_at":"2025-03-14T16:33:34.952Z","repository":{"id":32533652,"uuid":"120081455","full_name":"detritusjs/client","owner":"detritusjs","description":"A Typescript NodeJS library to interact with Discord's API, both Rest and Gateway.","archived":false,"fork":false,"pushed_at":"2024-11-28T15:12:15.000Z","size":8536,"stargazers_count":207,"open_issues_count":16,"forks_count":22,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-06T09:18:40.354Z","etag":null,"topics":["bot","detritus","discord","discord-api","node","typescript"],"latest_commit_sha":null,"homepage":"https://detritusjs.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/detritusjs.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-02-03T10:30:47.000Z","updated_at":"2024-11-05T19:07:20.000Z","dependencies_parsed_at":"2024-01-21T09:48:00.647Z","dependency_job_id":"2dc15615-7ce5-42d6-8ed6-2b4201d62e21","html_url":"https://github.com/detritusjs/client","commit_stats":{"total_commits":318,"total_committers":11,"mean_commits":28.90909090909091,"dds":0.1132075471698113,"last_synced_commit":"b27cbaa5bfb48506b059be178da0e871b83ba95e"},"previous_names":["cakedan/detritus"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detritusjs%2Fclient","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detritusjs%2Fclient/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detritusjs%2Fclient/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/detritusjs%2Fclient/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/detritusjs","download_url":"https://codeload.github.com/detritusjs/client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243610691,"owners_count":20319010,"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":["bot","detritus","discord","discord-api","node","typescript"],"created_at":"2024-07-30T20:01:10.725Z","updated_at":"2025-03-14T16:33:34.523Z","avatar_url":"https://github.com/detritusjs.png","language":"TypeScript","funding_links":[],"categories":["API Libraries","Libraries"],"sub_categories":["TypeScript"],"readme":"# Detritus\n![npm](https://img.shields.io/npm/v/detritus-client?style=flat-square)\n\nA wheels-attached, pure-TypeScript library for the Discord API.\n\n- [API Documentation](https://detritusjs.com)\n- [Discord Help Server](https://discord.gg/NEq6wws)\n- [npm](https://www.npmjs.com/package/detritus-client)\n\n## Installation\n\nDetritus is distributed via npm. A high-level wrapper over the Discord API is provided\nin this package, `detritus-client`. Low-level wrappers over Discord's REST API and Gateway\nare provided through [`detritus-client-rest`](https://github.com/detritusjs/client-rest) and\n[`detritus-client-socket`](https://github.com/detritusjs/client-socket).\n\n- `$ npm i detritus-client`\n- `$ yarn add detritus-client`\n\n## Usage\n\nDetritus is operated through the Clients classes:\n\n- `ShardClient` provides a base client for connecting to the Discord API and receiving events.\n- `ClusterClient` provides a client that creates `ShardClient` classes inside of it for easier sharding\n- `CommandClient` wraps over the `ClusterClient` or `ShardClient` to provide support for bot commands.\n- `InteractionCommandClient` wraps over the `ClusterClient` or `ShardClient` to provide support for interaction commands.\n- `ClusterManager` provides a manager that'll spawn in multiple `ClusterClient` processes for big shardings\n\nMore Examples are provided under the [`examples/`](https://github.com/detritusjs/client/tree/master/examples)\ndirectory.\n\n### Command Client Sample\n\n```js\nconst { CommandClient } = require('detritus-client');\n\n// Note: it is not advised to hard-code your bot token directly into the bot source.\n//\n// Tokens should be considered secrets and stored in a configuration file that is not\n// part of your version control system, or an environment variable.\n// By default, the CommandClient will use the ClusterClient\n// The ShardClient/ClusterClient will be under CommandClient.client as soon as you create the object\nconst token = '';\nconst commandClient = new CommandClient(token, {\n  // Prefix `..`, if you want multiple prefixes pass in `prefixes: ['..', '...']`\n  prefix: '..',\n});\n\n// Simple ping/pong command\ncommandClient.add({\n  // name describes the command trigger; in this case, ..ping\n  name: 'ping',\n  run: (context, args) =\u003e {\n    // Commands should return a promise to ensure that errors are handled\n    return context.reply('pong!');\n  },\n});\n\n// Command demonstrating command pipelines\ncommandClient.add({\n  name: 'owner',\n  // onBefore should return a boolean to indicate whether or not the command should proceed\n  onBefore: (context) =\u003e context.client.isOwner(context.userId),\n  onCancel: (context) =\u003e context.reply('This command is only available to the bot owner.'),\n  run: async (context) =\u003e {\n    // Commands may also run asynchronously.\n    await context.reply('You are the owner of the bot!');\n  },\n});\n\n// Spawn the client in an async context\n//\n// Note: Due to how Node handles tasks, the script will block until the Detritus client\n// is killed.\n(async () =\u003e {\n  const client = await commandClient.run();\n  console.log(`Client has loaded with a shard count of ${client.shardCount}`);\n})();\n```\n\n### InteractionCommand Client Sample\n\n```js\nconst { Constants, InteractionCommandClient } = require('detritus-client');\nconst { ApplicationCommandTypes, InteractionCallbackTypes, MessageFlags } = Constants;\n\n// Note: it is not advised to hard-code your bot token directly into the bot source.\n//\n// Tokens should be considered secrets and stored in a configuration file that is not\n// part of your version control system, or an environment variable.\n// By default, the InteractionCommandClient will use the ClusterClient\n// The ShardClient/ClusterClient will be under InteractionCommandClient.client as soon as you create the object\nconst token = '';\nconst interactionClient = new InteractionCommandClient(token);\n\n// Simple ping/pong command\ninteractionClient.add({\n  description: 'Ping!',\n  name: 'ping',\n  run: (context, args) =\u003e {\n    // Commands should return a promise to ensure that errors are handled\n    return context.respond(InteractionCallbackTypes.CHANNEL_MESSAGE_WITH_SOURCE, 'pong!');\n  },\n});\n\n// Command demonstrating command pipelines\ninteractionClient.add({\n  description: 'Are you the owner or part of the team for this application?',\n  name: 'owner',\n  // onBefore should return a boolean to indicate whether or not the command should proceed\n  onBefore: (context) =\u003e context.client.isOwner(context.userId),\n  // we want the error to only show to the user to not clunk up the chat\n  onCancel: (context) =\u003e {\n    return context.respond(InteractionCallbackTypes.CHANNEL_MESSAGE_WITH_SOURCE, {\n      content: 'This command is only available to the bot owner.'),\n      flags: MessageFlags.EPHEMERAL,\n    });\n  },\n  run: async (context) =\u003e {\n    // Commands may also run asynchronously.\n    await context.respond(InteractionCallbackTypes.CHANNEL_MESSAGE_WITH_SOURCE, 'You are the owner of the bot!');\n  },\n});\n\n// Context Menu User Command\ninteractionClient.add({\n  name: 'Poke',\n  type: ApplicationCommandTypes.USER,\n  run: async (context, args) =\u003e {\n    await context.respond(InteractionCallbackTypes.CHANNEL_MESSAGE_WITH_SOURCE, {\n      content: `You poked ${args.member || args.user}`,\n      flags: MessageFlags.EPHEMERAL,\n    });\n  },\n});\n\n// Context Menu Message Command (tells you when the message was created)\ninteractionClient.add({\n  name: 'Creation Date',\n  guildIds: [], // you can make it a guild command\n  type: ApplicationCommandTypes.MESSAGE,\n  run: async (context, args) =\u003e {\n    const { message } = args;\n    await context.respond(InteractionCallbackTypes.CHANNEL_MESSAGE_WITH_SOURCE, {\n      content: `${message.id} was made at ${message.createdAt}`,\n      flags: MessageFlags.EPHEMERAL,\n    });\n  },\n});\n\n// Spawn the client in an async context\n//\n// Note: Due to how Node handles tasks, the script will block until the Detritus client\n// is killed.\n(async () =\u003e {\n  // Interaction Client will compare the local commands w/ commands stored on discord\n  // If any of them differ, it will call `.bulkOverwriteApplicationCommands()` with the local commands\n  // Guild-specific Interaction commands are not supported right now\n  const client = await interactionClient.run();\n  console.log(`Client has loaded with a shard count of ${client.shardCount}`);\n})();\n```\n\n### Shard Client Sample\n\n```js\nconst { ShardClient } = require('detritus-client');\n\n// Note: it is not advised to hard-code your bot token directly into the bot source.\n//\n// Tokens should be considered secrets and stored in a configuration file that is not\n// part of your version control system, or an environment variable.\nconst token = '';\nconst client = new ShardClient(token, {\n  gateway: {\n    // This will tell our client to fill our Members cache on any of our guilds that are larger than the large threshold you pass in (default 250)\n    loadAllMembers: true,\n  },\n});\n\n// listen to our client's eventemitter\nclient.on('guildCreate', async ({fromUnavailable, guild}) =\u003e {\n  if (fromUnavailable) {\n    console.log(`Guild ${guild.name} has just came back from being unavailable`);\n  } else {\n    console.log(`Joined Guild ${guild.name}, bringing us up to ${client.guilds.length} guilds.`);\n  }\n});\n\n// listen to our client's eventemitter\nclient.on('messageCreate', async ({message}) =\u003e {\n  if (message.content === '!ping') {\n    const reply = await message.reply('pong!, deleting message in 5 seconds...');\n    setTimeout(async () =\u003e {\n      await reply.delete();\n    }, 5000);\n  }\n});\n\n(async () =\u003e {\n  await client.run();\n  console.log('Successfully connected to Discord!');\n  console.log(`Currently have ${client.guilds.length} guilds in cache.`);\n  // set our presence, we can pass this into the client's options too under `gateway.presence`\n  client.gateway.setPresence({\n    activity: {\n      // What comes after our activity type, x.\n      name: 'with Detritus',\n      // Type 0 sets our message to `Playing x`\n      type: 0,\n    },\n    // do-not-disturb us\n    status: 'dnd',\n  });\n})();\n```\n\n### Cluster Client Sample\n\n```js\nconst { ClusterClient } = require('detritus-client');\n\n// Note: it is not advised to hard-code your bot token directly into the bot source.\n//\n// Tokens should be considered secrets and stored in a configuration file that is not\n// part of your version control system, or an environment variable.\nconst token = '';\nconst cluster = new ClusterClient(token, {\n  gateway: {\n    // Pass in a presence we will send with the identify payload\n    presence: {\n      activity: {\n        // What comes after our activity type, x.\n        name: 'with Detritus ClusterClient',\n        // Type 0 sets our message to `Playing x`\n        type: 0,\n      },\n      // do-not-disturb us\n      status: 'dnd',\n    },\n  },\n});\n\n// listen to our client's eventemitter\n// `shard` (which is the ShardClient the event originated from) is added onto EVERY event that you listen to on the cluster client\ncluster.on('guildCreate', async ({fromUnavailable, guild, shard}) =\u003e {\n  if (fromUnavailable) {\n    console.log(`Shard #${shard.shardId}:`, `Guild ${guild.name} has just came back from being unavailable`);\n  } else {\n    console.log(`Shard #${shard.shardId}:`, `Joined Guild ${guild.name}, bringing us up to ${client.guilds.length} guilds.`);\n  }\n});\n\n// listen to our client's eventemitter\n// `shard` (which is the ShardClient the event originated from) is added onto EVERY event that you listen to on the cluster client\ncluster.on('messageCreate', async ({message, shard}) =\u003e {\n  if (message.content === '!ping') {\n    const reply = await message.reply(`pong on shard #${shard.shardId}!, deleting message in 5 seconds...`);\n    setTimeout(async () =\u003e {\n      await reply.delete();\n    }, 5000);\n  }\n});\n\n(async () =\u003e {\n  // shards are made after the cluster is ran, found in `ClusterClient.shards`.\n  await cluster.run();\n  console.log(`Successfully launched shards ${cluster.shardStart} to ${cluster.shardEnd} with a shardCount of ${cluster.shardCount}`);\n})();\n```\n\n## Contributing\n\nDetritus is licensed under the BSD-2 license; see the [LICENSE](LICENSE).\n\nTo contribute, please first open an issue describing your requested changes,\nand then open a pull request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetritusjs%2Fclient","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdetritusjs%2Fclient","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdetritusjs%2Fclient/lists"}