Neptunium, Promethium, Manganese

    detritus-client
    TypeScript icon, indicating that this package has built-in type declarations

    0.15.3 • Public • Published

    Detritus

    npm

    A wheels-attached, pure-TypeScript library for the Discord API.

    Installation

    Detritus is distributed via npm. A high-level wrapper over the Discord API is provided in this package, detritus-client. Low-level wrappers over Discord's REST API and Gateway are provided through detritus-client-rest and detritus-client-socket.

    • $ npm i detritus-client
    • $ yarn add detritus-client

    Usage

    Detritus is operated through the Clients classes:

    • ShardClient provides a base client for connecting to the Discord API and receiving events.
    • ClusterClient provides a client that creates ShardClient classes inside of it for easier sharding
    • CommandClient wraps over the ClusterClient or ShardClient to provide support for bot commands.
    • ClusterManager provides a manager that'll spawn in multiple ClusterClient processes for big shardings

    More Examples are provided under the examples/ directory.

    Command Client Sample

    const { CommandClient } = require('detritus-client');
    
    // Note: it is not advised to hard-code your bot token directly into the bot source.
    //
    // Tokens should be considered secrets and stored in a configuration file that is not
    // part of your version control system, or an environment variable.
    // By default, the CommandClient will use the ClusterClient
    // The ShardClient/ClusterClient will be under CommandClient.client as soon as you create the object
    const token = '';
    const commandClient = new CommandClient(token, {
      // Prefix `..`, if you want multiple prefixes pass in `prefixes: ['..', '...']`
      prefix: '..',
    });
    
    // Simple ping/pong command
    commandClient.add({
      // name describes the command trigger; in this case, ..ping
      name: 'ping',
      run: (context, args) => {
        // Commands should return a promise to ensure that errors are handled
        return context.reply('pong!');
      },
    });
    
    // Command demonstrating command pipelines
    commandClient.add({
      name: 'owner',
      // onBefore should return a boolean to indicate whether or not the command should proceed
      onBefore: (context) => context.client.isOwner(context.userId),
      onCancel: (context) => context.reply('This command is only available to the bot owner.'),
      run: async (context) => {
        // Commands may also run asynchronously.
        await context.reply('You are the owner of the bot!');
      },
    });
    
    // Spawn the client in an async context
    //
    // Note: Due to how Node handles tasks, the script will block until the Detritus client
    // is killed.
    (async () => {
      const client = await commandClient.run();
      // client has received the READY payload, do stuff now
      console.log(`Client has loaded with a shard count of ${client.shardCount}`);
    })();

    Shard Client Sample

    const { ShardClient } = require('detritus-client');
    
    // Note: it is not advised to hard-code your bot token directly into the bot source.
    //
    // Tokens should be considered secrets and stored in a configuration file that is not
    // part of your version control system, or an environment variable.
    const token = '';
    const client = new ShardClient(token, {
      gateway: {
        // 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)
        loadAllMembers: true,
      },
    });
    
    // listen to our client's eventemitter
    client.on('guildCreate', async ({fromUnavailable, guild}) => {
      if (fromUnavailable) {
        console.log(`Guild ${guild.name} has just came back from being unavailable`);
      } else {
        console.log(`Joined Guild ${guild.name}, bringing us up to ${client.guilds.length} guilds.`);
      }
    });
    
    // listen to our client's eventemitter
    client.on('messageCreate', async ({message}) => {
      if (message.content === '!ping') {
        const reply = await message.reply('pong!, deleting message in 5 seconds...');
        setTimeout(async () => {
          await reply.delete();
        }, 5000);
      }
    });
    
    (async () => {
      await client.run();
      console.log('Successfully connected to Discord!');
      console.log(`Currently have ${client.guilds.length} guilds in cache.`);
      // set our presence, we can pass this into the client's options too under `gateway.presence`
      client.gateway.setPresence({
        activity: {
          // What comes after our activity type, x.
          name: 'with Detritus',
          // Type 0 sets our message to `Playing x`
          type: 0,
        },
        // do-not-disturb us
        status: 'dnd',
      });
    })();

    Cluster Client Sample

    const { ClusterClient } = require('detritus-client');
    
    // Note: it is not advised to hard-code your bot token directly into the bot source.
    //
    // Tokens should be considered secrets and stored in a configuration file that is not
    // part of your version control system, or an environment variable.
    const token = '';
    const cluster = new ClusterClient(token, {
      gateway: {
        // Pass in a presence we will send with the identify payload
        presence: {
          activity: {
            // What comes after our activity type, x.
            name: 'with Detritus ClusterClient',
            // Type 0 sets our message to `Playing x`
            type: 0,
          },
          // do-not-disturb us
          status: 'dnd',
        },
      },
    });
    
    // listen to our client's eventemitter
    // `shard` (which is the ShardClient the event originated from) is added onto EVERY event that you listen to on the cluster client
    cluster.on('guildCreate', async ({fromUnavailable, guild, shard}) => {
      if (fromUnavailable) {
        console.log(`Shard #${shard.shardId}:`, `Guild ${guild.name} has just came back from being unavailable`);
      } else {
        console.log(`Shard #${shard.shardId}:`, `Joined Guild ${guild.name}, bringing us up to ${client.guilds.length} guilds.`);
      }
    });
    
    // listen to our client's eventemitter
    // `shard` (which is the ShardClient the event originated from) is added onto EVERY event that you listen to on the cluster client
    cluster.on('messageCreate', async ({message, shard}) => {
      if (message.content === '!ping') {
        const reply = await message.reply(`pong on shard #${shard.shardId}!, deleting message in 5 seconds...`);
        setTimeout(async () => {
          await reply.delete();
        }, 5000);
      }
    });
    
    (async () => {
      // shards are made after the cluster is ran, found in `ClusterClient.shards`.
      await cluster.run();
      console.log(`Successfully launched shards ${cluster.shardStart} to ${cluster.shardEnd} with a shardCount of ${cluster.shardCount}`);
    })();

    Contributing

    Detritus is licensed under the BSD-2 license; see the LICENSE.

    To contribute, please first open an issue describing your requested changes, and then open a pull request.

    Install

    npm i detritus-client

    DownloadsWeekly Downloads

    609

    Version

    0.15.3

    License

    BSD-2-Clause

    Unpacked Size

    1.4 MB

    Total Files

    212

    Last publish

    Collaborators

    • avatar