@beret.27/discord-app-emojis

Gérer, synchroniser, réparer et télécharger les emojis d'application Discord depuis Node.js et discord.js.

ReadMe rédigé avec l'aide d'une IA — des erreurs sont possibles. En cas de souci : Discord levraiberet.

Sommaire

• Installation
• Démarrage rapide
• Création du module
• API
  • getemoji(name, options)
  • getallemoji({ name })
  • getemojinumber()
  • downloadEmojis(options)
  • downloadEmoji(name, options)
• Options de configuration
• Cas d'usage
• Structure du projet

Installation

npm install @beret.27/discord-app-emojis

Prérequis : Node.js >= 18. Les dépendances axios et sharp sont installées automatiquement.

Démarrage rapide

const { createEmojiModule } = require('@beret.27/discord-app-emojis');

const emoji = await createEmojiModule({
  token: process.env.DISCORD_BOT_TOKEN,
  emojiDir: './emojis',
}).init();

// Récupérer la mention d'un emoji (le crée si le fichier local existe)
const yes = await emoji.getemoji('yes', { update: true });

// Télécharger tous les emojis du bot dans un dossier
await emoji.downloadEmojis({ dir: './backup' });

Création du module

Deux façons d'initialiser le module.

1) Avec un client discord.js (recommandé)

const emoji = await createEmojiModule({
  client, // client discord.js déjà connecté (login effectué)
  emojiDir: './emojis',
}).init();

2) Avec un token (sans discord.js)

const emoji = await createEmojiModule({
  token: process.env.DISCORD_BOT_TOKEN,
  appId: process.env.DISCORD_APP_ID, // optionnel : déduit du token si absent
  emojiDir: './emojis',
}).init();

init() charge le cache des emojis distants et, si syncOnInit est actif, reconstruit les emojis manquants à partir du dossier local.

API

getemoji(name, options)

Retourne la mention <:name:id> (ou <a:name:id> si animé), prête à être envoyée dans un message.

| Option | Type | Description | |---|---|---| | update | boolean | Crée l'emoji s'il est absent (fichier local requis) et le met à jour si le visuel local diffère du distant. | | delete | boolean | Supprime l'emoji distant portant ce nom. | | default | string | Valeur de repli renvoyée en cas d'erreur ou d'emoji introuvable (défaut ❓). |

upload est accepté comme alias de update.

const v = await emoji.getemoji('yes', {
  update: true,
  default: '❓',
});

getallemoji({ name })

Retourne la liste de tous les emojis, ou seulement ceux dont le nom contient name.

const all = await emoji.getallemoji();          // tout
const para = await emoji.getallemoji({ name: 'para' }); // filtré

Chaque emoji renvoyé a la forme :

{ id, name, animated, mention, url }

getemojinumber()

Retourne le nombre total d'emojis d'application du bot.

const count = await emoji.getemojinumber();

downloadEmojis(options)

Télécharge les emojis au format Discord (.webp pour les statiques, .gif pour les animés) dans un dossier. Chaque fichier prend le nom de l'emoji + l'extension correspondante.

| Option | Type | Défaut | Description | |---|---|---|---| | dir | string | downloadDir | Dossier cible (créé s'il n'existe pas). | | names | string[] | (tous) | Sous-ensemble de noms à télécharger. Si absent, télécharge tout. | | overwrite | boolean | true | false pour ignorer les fichiers déjà présents. | | concurrency | number | syncConcurrency | Nombre de téléchargements en parallèle. |

// Tout télécharger
await emoji.downloadEmojis({ dir: './backup' });

// Télécharger seulement certains emojis par leur nom
await emoji.downloadEmojis({
  dir: './pack',
  names: ['yes', 'no', 'para_swag'],
});

// Sauvegarde incrémentale (ne re-télécharge pas l'existant)
await emoji.downloadEmojis({ dir: './backup', overwrite: false });

Valeur de retour : un tableau de résultats, un par emoji.

[
  { name: 'yes', path: '.../backup/yes.webp', skipped: false, bytes: 4821 },
  { name: 'wave', path: '.../backup/wave.gif', skipped: false, bytes: 19233 },
  { name: 'broken', error: 'CDN 404 pour broken' },
]

downloadEmoji(name, options)

Télécharge un seul emoji par son nom. Mêmes options que downloadEmojis (hors names). Retourne le résultat unique (ou null si le nom n'existe pas).

const res = await emoji.downloadEmoji('yes', { dir: './pack' });
// { name: 'yes', path: '.../pack/yes.webp', skipped: false, bytes: 4821 }

Options de configuration

Passées à createEmojiModule(options).

Connexion

| Option | Type | Défaut | Description | |---|---|---|---| | client | Discord.Client | — | Client discord.js connecté (sinon token). | | token | string | env.DISCORD_BOT_TOKEN | Token du bot (requis si pas de client). | | appId | string | (déduit) | ID d'application ; déduit du client ou du token. | | timeoutMs | number | 20000 | Timeout des requêtes API / CDN. |

Dossiers

| Option | Type | Défaut | Description | |---|---|---|---| | emojiDir | string | ./emojis | Dossier des images sources locales. | | downloadDir | string | ./emojis/downloads | Dossier par défaut de downloadEmojis. | | createDirIfMissing | boolean | true | Crée les dossiers manquants. |

Cache

| Option | Type | Défaut | Description | |---|---|---|---| | cacheTtlMs | number | 30000 | Durée de validité du cache des emojis distants (ms). | | refreshOnMiss | boolean | true | Rafraîchit le cache si un nom demandé est absent. |

Synchronisation au démarrage

| Option | Type | Défaut | Description | |---|---|---|---| | syncOnInit | boolean | false | Resynchronise les emojis locaux à l'init(). | | syncOnInitMode | string | missing-only | missing-only ou update-all. | | syncConcurrency | number | 8 | Traitements en parallèle. | | updateStrategy | string | missing-only | missing-only ou strict-remote-hash. | | syncDefault | string | — | Valeur de repli pendant le sync. |

Normalisation des images (avant upload)

| Option | Type | Défaut | Description | |---|---|---|---| | normalizeUploads | boolean | false | Normalise les images avant l'envoi à Discord. | | normalizeSize | number | 128 | Taille cible (px). | | normalizeFormat | string | png | png, webp ou jpeg. | | normalizeCacheDir | string | ./emojis/.discord-cache | Cache disque des images converties. |

Logs

| Option | Type | Défaut | Description | |---|---|---|---| | log | boolean | false | Active les logs du module. | | logLevels | string[] | tous | Filtre par niveau : debug, info, warn, error. | | logEvents | string[] | tous | Filtre par event : create, update, delete, download, … | | logger | object | console | Logger personnalisé (compatible console). |

Cas d'usage

Sauvegarder tous les emojis du bot

const emoji = await createEmojiModule({ client }).init();
await emoji.downloadEmojis({ dir: './backup', overwrite: false });

Réparer des emojis renommés / inversés

Si les noms existent encore sur le bot mais pointent vers le mauvais visuel :

const emoji = await createEmojiModule({
  client,
  emojiDir: './emojis',
  syncOnInit: true,
  syncOnInitMode: 'update-all',
  updateStrategy: 'strict-remote-hash',
  syncConcurrency: 8,
}).init();

Ce mode compare visuellement le local et le distant, puis recrée l'emoji si le contenu ne correspond pas.

Quand normalizeUploads est activé, un cache disque des images converties est créé dans .discord-cache pour éviter les reconversions et réduire la latence.

Structure du projet

Le code est découpé dans src/fonction/, une responsabilité par fichier :

| Fichier | Rôle | |---|---| | resolveContext.js | Construit le contexte (token, appId, dossiers, options). | | moduleState.js | Cache, comparaison visuelle, préparation des images. | | remoteApi.js | Appels API Discord (liste / création / suppression). | | getemoji.js | Récupération / création / mise à jour / suppression d'un emoji. | | getallemoji.js | Liste filtrable des emojis. | | getemojinumber.js | Nombre total d'emojis. | | downloadEmoji.js | Téléchargement des emojis au format Discord. | | emojiDir.js | Résolution des dossiers et fichiers locaux. | | logger.js | Logs colorés et empilables. | | sanitizeName.js | Nettoyage des noms d'emoji. |

Script tout-en-un : télécharger tous les emojis d'un bot

Copier-coller, renseigner le token et le dossier, lancer avec node backup.js. Télécharge tous les emojis du bot dans le dossier indiqué, au format Discord (.webp / .gif), en parallèle.

// backup.js
const { createEmojiModule } = require('@beret.27/discord-app-emojis');

// ⬇️ À MODIFIER
const TOKEN = 'TON_TOKEN_BOT_ICI';
const DOSSIER = './backup-emojis'; // dossier de destination (créé si absent)

(async () => {
  const emoji = await createEmojiModule({
    token: TOKEN,
    log: true, // affiche la progression
  }).init();

  const results = await emoji.downloadEmojis({
    dir: DOSSIER,
    concurrency: 16, // téléchargements en parallèle = rapide
  });

  const ok = results.filter((r) => !r.error).length;
  const ko = results.length - ok;
  console.log(`\n✅ ${ok} emoji(s) téléchargé(s) dans ${DOSSIER}` + (ko ? ` — ❌ ${ko} échec(s)` : ''));
})();

Astuce : pour ne récupérer que certains emojis, ajoute names: ['yes', 'no', 'wave'] dans downloadEmojis({ ... }).

Licence

MIT © beret.27