### Install canvas-forge

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Install the canvas-forge library using npm, yarn, or pnpm.

```bash
# npm
npm install canvas-forge

# yarn
yarn add canvas-forge

# pnpm
pnpm add canvas-forge
```

--------------------------------

### Full Custom Canvas Example

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/custom-canvas.md

A comprehensive example showing how to build a custom card with various drawing elements, including background, gradients, text, polygons, progress bars, and borders. Saves the output to a PNG file.

```typescript
import { CanvasBuilder } from 'canvas-forge';
import fs from 'fs';

const buffer = new CanvasBuilder(800, 400)
  .setBackground('#1a1a2e')
  .drawShadow('rgba(0,0,0,0.3)', 8, 3, 3)
  .drawGradientRect(20, 20, 760, 360, {
    colors: ['#16213e', '#0f3460'],
    direction: 'diagonal',
  }, 15)
  .clearShadow()
  .drawLine(40, 70, 760, 70, 'rgba(255,255,255,0.1)', 1)
  .setFont(36, 'sans-serif', 'bold')
  .drawText('My Custom Card', 400, 55, '#e94560', 'center')
  .drawPolygon(
    [[400, 100], [480, 180], [400, 260], [320, 180]],
    '#5865F2',
  )
  .setFont(16, 'sans-serif', 'normal')
  .drawText('Built with canvas-forge', 400, 300, '#a0a0b0', 'center')
  .drawProgressBar(50, 330, 700, 20, 0.85, '#e94560', '#2a2a3e', 10)
  .drawBorderedRect(40, 80, 720, 260, 'rgba(255,255,255,0.05)', 1, 10)
  .toBuffer();

fs.writeFileSync('custom.png', buffer);
```

--------------------------------

### Fully Customize a Welcome Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/welcome-card.md

This example demonstrates extensive customization options for the welcome card, including text, colors, theme, background, and dimensions. Adjust parameters to match your server's aesthetic.

```typescript
const card = await new WelcomeCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setDiscriminator(member.user.discriminator)
  .setGuildName(member.guild.name)
  .setMemberCount(member.guild.memberCount)
  .setTitleText('Welcome to the server!')
  .setSubtitleText('You are member #{memberCount}')
  .setTheme('dark')
  .setBackground('#1a1a2e')
  .setAvatarBorder('#e94560')
  .setAvatarBorderWidth(5)
  .setAvatarSize(150)
  .setTitleColor('#e94560')
  .setSubtitleColor('#a0a0b0')
  .setUsernameColor('#ffffff')
  .setOverlay('#000000', 0.3)
  .setOutputFormat('png')
  .setSize(1024, 450)
  .build();
```

--------------------------------

### Create a Basic Welcome Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/welcome-card.md

Use this snippet to generate a simple welcome card with essential member and server information. Ensure 'canvas-forge' is installed and imported.

```typescript
import { WelcomeCardBuilder } from 'canvas-forge';

const card = await new WelcomeCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setGuildName(member.guild.name)
  .setMemberCount(member.guild.memberCount)
  .build();
```

--------------------------------

### Install canvas-forge

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/getting-started.md

Install the canvas-forge package using npm, yarn, or pnpm. Requires Node.js 18 or higher.

```bash
npm install canvas-forge
```

```bash
yarn add canvas-forge
```

```bash
pnpm add canvas-forge
```

--------------------------------

### Build a Server Stats Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/server-stats-card.md

Demonstrates the basic usage of ServerStatsCardBuilder to create a statistics card. Ensure 'canvas-forge' is installed and imported.

```typescript
import { ServerStatsCardBuilder } from 'canvas-forge';

const card = await new ServerStatsCardBuilder()
  .setGuildName('Pixel Developers')
  .setGuildIcon(guild.iconURL({ extension: 'png' }))
  .setTotalMembers(guild.memberCount)
  .setOnlineMembers(onlineCount)
  .setBoosts(guild.premiumSubscriptionCount)
  .setBoostLevel(guild.premiumTier)
  .build();
```

--------------------------------

### Basic Boost Card Creation

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/boost-card.md

Demonstrates the fundamental usage of BoostCardBuilder to create a notification card with essential user and server details. Ensure 'canvas-forge' is installed and imported.

```typescript
import { BoostCardBuilder } from 'canvas-forge';

const card = await new BoostCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setGuildName(member.guild.name)
  .setBoostCount(15)
  .build();
```

--------------------------------

### Fully Customized Leave Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/leave-card.md

Shows how to apply extensive customization options to a leave card, including text, theme, and border colors. This example builds upon the basic setup.

```typescript
const card = await new LeaveCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setGuildName(member.guild.name)
  .setTitleText('Goodbye!')
  .setSubtitleText('We will miss you...')
  .setTheme('dark')
  .setAvatarBorder('#747f8d')
  .setTitleColor('#747f8d')
  .build();
```

--------------------------------

### Build Fully Customized Profile Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/profile-card.md

Demonstrates extensive customization options for a profile card, including discriminator, display name alignment, badges, join date, accent colors, and background. This example showcases a wide range of available settings.

```typescript
const card = await new ProfileCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setDiscriminator(user.discriminator)
  .setDisplayName('Cool Nickname')
  .setBio('Full-stack developer. Discord bot enthusiast.')
  .setBioAlign('left')
  .setBadges([
    { icon: './badges/verified.png', label: 'Verified' },
    { icon: './badges/booster.png', label: 'Server Booster' },
  ])
  .setLevel(25)
  .setCurrentXP(7500)
  .setRequiredXP(10000)
  .setRank(5)
  .setReputation(420)
  .setJoinedAt(new Date('2023-06-15'))
  .setStatus('online')
  .setAccentColor('#e94560')
  .setProgressBarColor('#e94560')
  .setProgressBarTrackColor('#2a2a3e')
  .setBackground('#1a1a2e')
  .build();
```

--------------------------------

### Full Customization of Rank Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/rank-card.md

This example demonstrates how to fully customize the appearance of the rank card, including colors, dimensions, and specific elements like the progress bar and avatar border. All customization options are chained after setting the basic user information.

```typescript
const card = await new RankCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setLevel(15)
  .setCurrentXP(2500)
  .setRequiredXP(5000)
  .setRank(3)
  .setStatus('online')
  .setProgressBarColor('#e94560')
  .setProgressBarTrackColor('#2a2a3e')
  .setProgressBarHeight(30)
  .setAvatarBorder('#e94560')
  .setLevelColor('#e94560')
  .setRankColor('#ffffff')
  .setXPColor('#a0a0b0')
  .setUsernameColor('#ffffff')
  .setBackground('#1a1a2e')
  .build();
```

--------------------------------

### CanvasBuilder Constructor

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Initialize a new CanvasBuilder instance with specified width and height. This is the starting point for creating custom canvas designs.

```typescript
new CanvasBuilder(width: number, height: number)
```

--------------------------------

### Leave Card Integration with Discord.js

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/leave-card.md

Provides an example of how to generate a leave card and send it to a Discord channel when a member leaves the server using Discord.js event listeners. Ensure 'CHANNEL_ID' is replaced with a valid channel ID.

```typescript
client.on(Events.GuildMemberRemove, async (member) => {
  const card = await new LeaveCardBuilder()
    .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
    .setUsername(member.user.username)
    .setGuildName(member.guild.name)
    .build();

  const attachment = new AttachmentBuilder(card, { name: 'goodbye.png' });
  const channel = member.guild.channels.cache.get('CHANNEL_ID');
  if (channel?.isTextBased()) {
    await channel.send({ content: `${member.user.username} has left.`, files: [attachment] });
  }
});
```

--------------------------------

### Send Server Stats Card in Discord.js

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/server-stats-card.md

An example of how to generate and send a server stats card within a Discord.js application. This snippet calculates online members and replies with the generated card as an attachment.

```typescript
import { AttachmentBuilder } from 'discord.js';
import { ServerStatsCardBuilder } from 'canvas-forge';

async function sendStats(interaction) {
  const guild = interaction.guild;
  const onlineCount = guild.members.cache.filter(m => m.presence?.status !== 'offline').size;

  const card = await new ServerStatsCardBuilder()
    .setGuildName(guild.name)
    .setGuildIcon(guild.iconURL({ extension: 'png' }))
    .setTotalMembers(guild.memberCount)
    .setOnlineMembers(onlineCount)
    .setBoosts(guild.premiumSubscriptionCount || 0)
    .setBoostLevel(guild.premiumTier)
    .build();

  const attachment = new AttachmentBuilder(card, { name: 'stats.png' });
  await interaction.reply({ files: [attachment] });
}
```

--------------------------------

### Logging Moderation Actions with Discord.js

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/moderation-card.md

An example of how to use the ModerationCardBuilder within a Discord.js application to log moderation actions. This function generates a card and sends it to a specified log channel.

```typescript
import { AttachmentBuilder } from 'discord.js';
import { ModerationCardBuilder } from 'canvas-forge';

async function logBan(guild, user, moderator, reason, caseNum) {
  const card = await new ModerationCardBuilder()
    .setAction('ban')
    .setAvatar(user.displayAvatarURL({ extension: 'png' }))
    .setUsername(user.username)
    .setModerator(moderator.username)
    .setReason(reason)
    .setCaseNumber(`#${caseNum}`)
    .build();

  const attachment = new AttachmentBuilder(card, { name: 'ban-log.png' });
  const logChannel = guild.channels.cache.get('LOGS_CHANNEL_ID');
  await logChannel.send({ files: [attachment] });
}
```

--------------------------------

### Discord.js Guild Member Update Event Handling

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/boost-card.md

An example of integrating BoostCardBuilder within a Discord.js bot to send a boost notification card when a member's boost status changes. This snippet requires a Discord.js client instance and a channel to send the message.

```typescript
client.on('guildMemberUpdate', async (oldMember, newMember) => {
  if (oldMember.premiumSince === null && newMember.premiumSince !== null) {
    const card = await new BoostCardBuilder()
      .setAvatar(newMember.user.displayAvatarURL({ extension: 'png', size: 512 }))
      .setUsername(newMember.user.username)
      .setGuildName(newMember.guild.name)
      .setBoostCount(newMember.guild.premiumSubscriptionCount ?? 1)
      .build();

    const attachment = new AttachmentBuilder(card, { name: 'boost.png' });
    boostChannel.send({ files: [attachment] });
  }
});
```

--------------------------------

### Create a Welcome Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/getting-started.md

Generate a basic welcome card with username, server name, member count, and a title. The output is saved as a PNG file.

```typescript
import { WelcomeCardBuilder } from 'canvas-forge';
import fs from 'fs';

const card = await new WelcomeCardBuilder()
  .setUsername('Jersuxs')
  .setGuildName('My Server')
  .setMemberCount(1500)
  .setTitleText('Welcome!')
  .setBackground('#1a1a2e')
  .build();

// Save to file
fs.writeFileSync('welcome.png', card);
```

--------------------------------

### Build Basic Info Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/info-card.md

Demonstrates how to create a basic info card with a title, description, fields, footer, and accent color. Requires importing InfoCardBuilder.

```typescript
import { InfoCardBuilder } from 'canvas-forge';

const card = await new InfoCardBuilder()
  .setTitle('Server Rules')
  .setDescription('Please follow these rules.')
  .addField({ name: 'Rule 1', value: 'Be respectful' })
  .addField({ name: 'Rule 2', value: 'No spam' })
  .setFooter('Last updated: May 2026')
  .setAccentColor('#5865F2')
  .build();
```

--------------------------------

### Build a Basic Spotify Now Playing Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/spotify-card.md

Demonstrates how to create a basic Spotify 'Now Playing' card using the SpotifyCardBuilder. Requires importing the builder and setting essential song details, album art, and playback progress.

```typescript
import { SpotifyCardBuilder } from 'canvas-forge';

const card = await new SpotifyCardBuilder()
  .setSongTitle('Blinding Lights')
  .setArtist('The Weeknd')
  .setAlbum('After Hours')
  .setAlbumArt('https://example.com/album-cover.jpg')
  .setElapsed(90000)   // 1:30 (in milliseconds)
  .setDuration(200000) // 3:20 (in milliseconds)
  .setIsPlaying(true)
  .build();
```

--------------------------------

### Initialize CanvasBuilder

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/custom-canvas.md

Sets up a new canvas instance with specified dimensions. This is the first step before any drawing operations.

```typescript
import { CanvasBuilder } from 'canvas-forge';

const canvas = new CanvasBuilder(800, 400);
```

--------------------------------

### Create Welcome Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Generates a welcome card for new guild members. Requires discord.js AttachmentBuilder.

```typescript
import { WelcomeCardBuilder } from 'canvas-forge';
import { AttachmentBuilder } from 'discord.js';

// Inside your guildMemberAdd event handler:
const card = await new WelcomeCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setGuildName(member.guild.name)
  .setMemberCount(member.guild.memberCount)
  .setTitleText('Welcome!')
  .setSubtitleText('You are member #{memberCount}')
  .setBackground('#1a1a2e')
  .setAvatarBorder('#e94560')
  .build();

const attachment = new AttachmentBuilder(card, { name: 'welcome.png' });
channel.send({ files: [attachment] });
```

--------------------------------

### Integrate with Discord.js for Welcome Messages

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/getting-started.md

Automatically send a generated welcome card to a Discord channel when a new member joins the server. Requires discord.js and GatewayIntentBits.GuildMembers.

```typescript
import { WelcomeCardBuilder } from 'canvas-forge';
import { AttachmentBuilder, Client, GatewayIntentBits } from 'discord.js';

const client = new Client({ intents: [GatewayIntentBits.GuildMembers] });

client.on('guildMemberAdd', async (member) => {
  const card = await new WelcomeCardBuilder()
    .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
    .setUsername(member.user.username)
    .setGuildName(member.guild.name)
    .setMemberCount(member.guild.memberCount)
    .build();

  const attachment = new AttachmentBuilder(card, { name: 'welcome.png' });
  const channel = member.guild.systemChannel;
  if (channel) channel.send({ files: [attachment] });
});
```

--------------------------------

### Basic Leave Card Creation

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/leave-card.md

Demonstrates the essential steps to create a leave card with user and server information. Requires importing LeaveCardBuilder.

```typescript
import { LeaveCardBuilder } from 'canvas-forge';

const card = await new LeaveCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setGuildName(member.guild.name)
  .build();
```

--------------------------------

### Build Basic Profile Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/profile-card.md

Creates a profile card with essential user information like avatar, username, bio, level, and status. Requires importing ProfileCardBuilder.

```typescript
import { ProfileCardBuilder } from 'canvas-forge';

const card = await new ProfileCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setDisplayName(member.nickname ?? user.globalName ?? user.username)
  .setBio('Hello! I love coding bots.')
  .setLevel(25)
  .setCurrentXP(7500)
  .setRequiredXP(10000)
  .setRank(5)
  .setReputation(420)
  .setStatus('online')
  .build();
```

--------------------------------

### CanvasBuilder Constructor

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Initializes a new CanvasBuilder instance with specified width and height.

```APIDOC
## CanvasBuilder Constructor

### Description
Creates a new freeform canvas builder instance.

### Constructor
```typescript
new CanvasBuilder(width: number, height: number)
```

### Parameters
- **width** (number) - The width of the canvas.
- **height** (number) - The height of the canvas.
```

--------------------------------

### Build a Server Stats Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Use ServerStatsCardBuilder to display server statistics. Include guild name, icon, total and online members, and boost information.

```typescript
import { ServerStatsCardBuilder } from 'canvas-forge';

const card = await new ServerStatsCardBuilder()
  .setGuildName('Pixel Developers')
  .setGuildIcon(guild.iconURL({ extension: 'png' }))
  .setTotalMembers(2540)
  .setOnlineMembers(890)
  .setBoosts(22)
  .setBoostLevel(3)
  .build();
```

--------------------------------

### Build a Basic Leaderboard Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/leaderboard-card.md

Use LeaderboardCardBuilder to create a ranked leaderboard. Add entries with rank, username, and score, and set a score label. Requires importing LeaderboardCardBuilder.

```typescript
import { LeaderboardCardBuilder } from 'canvas-forge';

const card = await new LeaderboardCardBuilder()
  .setTitle('🏆 XP Leaderboard')
  .addEntry({ rank: 1, username: 'Jersuxs', score: 25400 })
  .addEntry({ rank: 2, username: 'Alice', score: 19200 })
  .addEntry({ rank: 3, username: 'Bob', score: 15800 })
  .setScoreLabel('XP')
  .build();
```

--------------------------------

### Canvas Output Formats

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/custom-canvas.md

Demonstrates how to set the output format (PNG, JPEG, WebP) and quality for the canvas buffer.

```typescript
// Default: PNG
const buffer = canvas.toBuffer();

// JPEG
canvas.setOutputFormat('jpeg');
canvas.setOutputQuality(90);
const jpegBuffer = canvas.toBuffer();

// WebP
canvas.setOutputFormat('webp');
canvas.setOutputQuality(85);
const webpBuffer = canvas.toBuffer();
```

--------------------------------

### Integrate Welcome Card with Discord.js

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/welcome-card.md

This snippet shows how to use the WelcomeCardBuilder within a Discord.js bot to automatically send a welcome card when a new member joins. Ensure you have a Discord bot client set up and replace 'CHANNEL_ID' with the target channel's ID.

```typescript
import { WelcomeCardBuilder } from 'canvas-forge';
import { AttachmentBuilder, Events } from 'discord.js';

client.on(Events.GuildMemberAdd, async (member) => {
  const card = await new WelcomeCardBuilder()
    .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
    .setUsername(member.user.username)
    .setGuildName(member.guild.name)
    .setMemberCount(member.guild.memberCount)
    .build();

  const attachment = new AttachmentBuilder(card, { name: 'welcome.png' });
  const channel = member.guild.channels.cache.get('CHANNEL_ID');
  if (channel?.isTextBased()) {
    await channel.send({ content: `Welcome ${member}!`, files: [attachment] });
  }
});
```

--------------------------------

### Set Background Options

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Configure the background of a card using solid colors, gradients, or images. An overlay can be applied on top of background images.

```typescript
// Solid color
builder.setBackground('#1a1a2e');

// Gradient
builder.setBackgroundGradient({
  colors: ['#e94560', '#0f3460'],
  direction: 'horizontal', // 'horizontal' | 'vertical' | 'diagonal' | 'radial'
});

// Image (URL, file path, or Buffer)
builder.setBackgroundImage('https://example.com/background.png');

// Add an overlay on top (useful for darkening background images)
builder.setOverlay('#000000', 0.5);
```

--------------------------------

### Import Text Utilities

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Import functions for text formatting and measurement. These are useful for rendering text on the canvas, including wrapping, truncating, and measuring.

```typescript
import { formatNumber, formatRank, buildFontString, wrapText, truncateText, measureText } from 'canvas-forge';
```

--------------------------------

### Create Profile Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Generates a profile card displaying user information, level, XP, and reputation.

```typescript
import { ProfileCardBuilder } from 'canvas-forge';

const card = await new ProfileCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setDisplayName(member.nickname ?? user.globalName ?? user.username)
  .setBio('Hello! I love coding bots.')
  .setLevel(25)
  .setCurrentXP(7500)
  .setRequiredXP(10000)
  .setRank(5)
  .setReputation(420)
  .setStatus('online')
  .setAccentColor('#e94560')
  .build();
```

--------------------------------

### Create Boost Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Generates a server boost notification card.

```typescript
import { BoostCardBuilder } from 'canvas-forge';

const card = await new BoostCardBuilder()
  .setAvatar(member.user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(member.user.username)
  .setGuildName(member.guild.name)
  .setBoostCount(15)
  .setAccentColor('#f47fff')
  .build();
```

--------------------------------

### Create Spotify Card from Discord.js Activity

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/spotify-card.md

Shows how to generate a Spotify card using data from a user's Discord activity, specifically when they are listening to Spotify. It extracts song title, artist, album art, elapsed time, and duration from the activity object.

```typescript
const activities = member.presence?.activities;
const spotify = activities?.find(a => a.name === 'Spotify');

if (spotify) {
  const card = await new SpotifyCardBuilder()
    .setSongTitle(spotify.details ?? 'Unknown')
    .setArtist(spotify.state ?? 'Unknown')
    .setAlbumArt(spotify.assets?.largeImageURL() ?? '')
    .setElapsed(Date.now() - (spotify.timestamps?.start?.getTime() ?? 0))
    .setDuration((spotify.timestamps?.end?.getTime() ?? 0) - (spotify.timestamps?.start?.getTime() ?? 0))
    .build();

  const attachment = new AttachmentBuilder(card, { name: 'spotify.png' });
  channel.send({ files: [attachment] });
}
```

--------------------------------

### Build a Spotify Now Playing Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Utilize SpotifyCardBuilder to generate a card showing current song details. Configure song title, artist, album, album art, playback progress, and colors.

```typescript
import { SpotifyCardBuilder } from 'canvas-forge';

const card = await new SpotifyCardBuilder()
  .setSongTitle('Blinding Lights')
  .setArtist('The Weeknd')
  .setAlbum('After Hours')
  .setAlbumArt('https://example.com/cover.jpg')
  .setElapsed(90000)
  .setDuration(200000)
  .setIsPlaying(true)
  .setProgressBarColor('#1DB954')
  .build();
```

--------------------------------

### Import Utility Functions

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Import various utility functions for color manipulation, text formatting, shape drawing, and image loading from the canvas-forge library.

```typescript
import {
  // Color utilities
  resolveColor, hexToRgba, rgbaToHex, darken, lighten, withOpacity, isHexColor,

  // Text utilities
  formatNumber, formatRank, buildFontString,

  // Shape utilities (for use with CanvasBuilder.getContext())
  drawRoundedRect, drawCircle, drawProgressBar, drawCircularProgress,

  // Constants
  DiscordColors, StatusColors, DefaultDimensions,

  // Image loading
  loadImage, tryLoadImage, clearImageCache,
} from 'canvas-forge';
```

--------------------------------

### Apply Built-in Themes

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Card builders support predefined themes like 'dark', 'light', or a customizable 'custom' theme. Apply themes using the setTheme method.

```typescript
// Dark theme (default)
builder.setTheme('dark');

// Light theme
builder.setTheme('light');

// Custom (configure your own colors)
builder.setTheme('custom');
```

--------------------------------

### Create Info Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Generates an informational card, suitable for displaying server rules or details.

```typescript
import { InfoCardBuilder } from 'canvas-forge';

const card = await new InfoCardBuilder()
  .setTitle('Server Rules')
  .setDescription('Please follow these rules to keep the server friendly.')
  .addField({ name: 'Rule 1', value: 'Be respectful' })
  .addField({ name: 'Rule 2', value: 'No spam' })
  .addField({ name: 'Members', value: '1,500', inline: true })
  .addField({ name: 'Online', value: '320', inline: true })
  .setFooter('Last updated: May 2026')
  .setAccentColor('#5865F2')
  .build();
```

--------------------------------

### Basic Level Up Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/level-up-card.md

Creates a basic level up card with essential user information. Requires importing LevelUpCardBuilder.

```typescript
import { LevelUpCardBuilder } from 'canvas-forge';

const card = await new LevelUpCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 256 }))
  .setUsername(user.username)
  .setLevel(10)
  .build();
```

--------------------------------

### Import Color Utilities

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Import necessary functions for color manipulation from the canvas-forge library. These utilities help in resolving, converting, and adjusting colors.

```typescript
import { resolveColor, hexToRgba, rgbaToHex, darken, lighten, withOpacity, isHexColor } from 'canvas-forge';
```

--------------------------------

### Set Output Formats

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Choose the output format for the generated image, such as PNG, JPEG, or WebP. Quality can be adjusted for JPEG and WebP formats.

```typescript
// PNG (default, best quality)
builder.setOutputFormat('png');

// JPEG (smaller file size)
builder.setOutputFormat('jpeg');
builder.setQuality(90); // 1-100

// WebP (modern, small & high quality)
builder.setOutputFormat('webp');
builder.setQuality(85);
```

--------------------------------

### Build a Leaderboard Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Use the LeaderboardCardBuilder to create a card displaying ranked entries with scores. Set a title and score label.

```typescript
import { LeaderboardCardBuilder } from 'canvas-forge';

const card = await new LeaderboardCardBuilder()
  .setTitle('🏆 XP Leaderboard')
  .addEntry({ rank: 1, username: 'Jersuxs', score: 25400 })
  .addEntry({ rank: 2, username: 'Alice', score: 19200 })
  .addEntry({ rank: 3, username: 'Bob', score: 15800 })
  .setScoreLabel('XP')
  .build();
```

--------------------------------

### CanvasBuilder Background Methods

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Methods for setting the background of the CanvasBuilder.

```APIDOC
## CanvasBuilder Background Methods

### Description
Methods to configure the background of the canvas.

### Methods
- `setBackground(color)`: Fill canvas with solid color.
- `setBackgroundGradient(gradient)`: Fill canvas with gradient.
- `setBackgroundImage(source)`: Draw background image (async).
```

--------------------------------

### Import Constants

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Import predefined constants for colors and dimensions. These can be used for consistent styling and layout.

```typescript
import { DiscordColors, StatusColors, DefaultDimensions } from 'canvas-forge';
```

--------------------------------

### Basic Moderation Card Creation

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/moderation-card.md

Demonstrates the basic usage of ModerationCardBuilder to create a moderation action card. Ensure the 'canvas-forge' library is imported.

```typescript
import { ModerationCardBuilder } from 'canvas-forge';

const card = await new ModerationCardBuilder()
  .setAction('ban')
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setModerator(interaction.user.username)
  .setReason('Phishing links spam')
  .setCaseNumber('#1204')
  .build();
```

--------------------------------

### Create Rank Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Generates a rank card displaying user level, XP, and rank.

```typescript
import { RankCardBuilder } from 'canvas-forge';

const card = await new RankCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setLevel(15)
  .setCurrentXP(2500)
  .setRequiredXP(5000)
  .setRank(3)
  .setStatus('online')
  .setProgressBarColor('#e94560')
  .build();
```

--------------------------------

### Basic Rank Card Creation

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/rank-card.md

Use this snippet to create a basic rank card with essential user information and level progression. Ensure the 'canvas-forge' library is imported.

```typescript
import { RankCardBuilder } from 'canvas-forge';

const card = await new RankCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 512 }))
  .setUsername(user.username)
  .setLevel(15)
  .setCurrentXP(2500)
  .setRequiredXP(5000)
  .setRank(3)
  .setStatus('online')
  .build();
```

--------------------------------

### Import Shape Utilities

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Import functions for drawing common shapes on the canvas. These include rounded rectangles, circles, and progress indicators.

```typescript
import { drawRoundedRect, drawCircle, drawProgressBar, drawCircularProgress } from 'canvas-forge';
```

--------------------------------

### CanvasBuilder Background Methods

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Methods to set the background of the canvas. Supports solid colors, gradients, and images. Image loading is asynchronous.

```typescript
setBackground(color)
```

```typescript
setBackgroundGradient(gradient)
```

```typescript
setBackgroundImage(source)
```

--------------------------------

### Text Utilities

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Utility functions for text formatting, wrapping, and measurement.

```APIDOC
## Text Utilities

### `formatNumber(num)`

Format a number into a more readable string with suffixes (e.g., 1500 becomes '1.5K').

**Parameters:**
- `num` (number): The number to format.

### `formatRank(num, prefix?)`

Format a number as a rank string, typically with a '#' prefix.

**Parameters:**
- `num` (number): The rank number.
- `prefix` (string, optional): The prefix to use (defaults to '#').

### `buildFontString(size, family?, weight?)`

Construct a CSS-style font string.

**Parameters:**
- `size` (number): The font size.
- `family` (string, optional): The font family.
- `weight` (string | number, optional): The font weight.

### `wrapText(ctx, text, maxWidth)`

Wrap a given text string into multiple lines to fit within a specified maximum width.

**Parameters:**
- `ctx` (CanvasRenderingContext2D): The 2D rendering context.
- `text` (string): The text to wrap.
- `maxWidth` (number): The maximum width the text can occupy.

### `truncateText(ctx, text, maxWidth, suffix?)`

Truncate a text string to fit within a maximum width, appending an ellipsis if necessary.

**Parameters:**
- `ctx` (CanvasRenderingContext2D): The 2D rendering context.
- `text` (string): The text to truncate.
- `maxWidth` (number): The maximum width the text can occupy.
- `suffix` (string, optional): The suffix to append if truncation occurs (defaults to '...').

### `measureText(ctx, text)`

Measure the dimensions (width and height) of a given text string.

**Parameters:**
- `ctx` (CanvasRenderingContext2D): The 2D rendering context.
- `text` (string): The text to measure.

**Returns:**
- `{ width: number, height: number }`: An object containing the width and height of the text.
```

--------------------------------

### Fully Customized Level Up Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/level-up-card.md

Creates a level up card with extensive customization options for text, colors, borders, and theme. Requires importing LevelUpCardBuilder.

```typescript
const card = await new LevelUpCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 256 }))
  .setUsername(user.username)
  .setLevel(10)
  .setTitleText('Level Up!')
  .setTitleColor('#e94560')
  .setUsernameColor('#ffffff')
  .setLevelColor('#e94560')
  .setAvatarBorder('#e94560')
  .setTheme('dark')
  .build();
```

--------------------------------

### Card Builders Common Methods

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Common methods available to all card builders for setting canvas properties and output format. Use `build()` to generate the final card buffer.

```typescript
setSize(width, height)
```

```typescript
setBackground(color)
```

```typescript
setBackgroundGradient(gradient)
```

```typescript
setBackgroundImage(image)
```

```typescript
setOverlay(color, opacity)
```

```typescript
setOutputFormat(format)
```

```typescript
setQuality(quality)
```

```typescript
registerFont(path, name)
```

```typescript
build()
```

--------------------------------

### Card Builders Common Methods

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

All card builders extend BaseCanvas and share these common methods for setting canvas dimensions, background, output format, and quality.

```APIDOC
## Card Builders Common Methods

### Description
These methods are available on all card builder instances for configuring the canvas.

### Methods
- `setSize(width, height)`: Set canvas dimensions.
- `setBackground(color)`: Set solid background color.
- `setBackgroundGradient(gradient)`: Set gradient background.
- `setBackgroundImage(image)`: Set image background.
- `setOverlay(color, opacity)`: Apply overlay on top of background.
- `setOutputFormat(format)`: Output format: `'png'`, `'jpeg'`, `'webp'`.
- `setQuality(quality)`: JPEG/WebP quality (1-100).
- `registerFont(path, name)`: Register a custom font file.
- `build()`: Build and return the card as a Buffer.
```

--------------------------------

### CanvasBuilder Text Methods

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Methods for rendering text on the CanvasBuilder.

```APIDOC
## CanvasBuilder Text Methods

### Description
Methods for drawing and styling text on the canvas.

### Methods
- `setFont(size, family?, weight?)`: Set current font.
- `drawText(text, x, y, color, align?)`: Draw text.
- `drawWrappedText(text, x, y, color, maxWidth, lineHeight?)`: Draw wrapped text.
- `drawTextWithEmojis(text, x, y, color, align?, emojiSize?)`: Draw text with Discord custom emojis inline (async).
```

--------------------------------

### Color Utilities

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Utility functions for color manipulation and conversion.

```APIDOC
## Color Utilities

### `resolveColor(color)`

Convert a `ColorResolvable` value into a CSS-compatible color string.

**Parameters:**
- `color` (ColorResolvable): The color value to resolve.

### `hexToRgba(hex)`

Parse a hexadecimal color string and return an RGBA object.

**Parameters:**
- `hex` (string): The hexadecimal color string (e.g., '#RRGGBB' or '#RRGGBBAA').

### `rgbaToHex(r, g, b, a?)`

Convert RGBA color components into a hexadecimal color string.

**Parameters:**
- `r` (number): The red component (0-255).
- `g` (number): The green component (0-255).
- `b` (number): The blue component (0-255).
- `a` (number, optional): The alpha component (0.0-1.0).

### `darken(color, amount)`

Darken a given color by a specified percentage.

**Parameters:**
- `color` (ColorResolvable): The color to darken.
- `amount` (number): The percentage to darken (0-100).

### `lighten(color, amount)`

Lighten a given color by a specified percentage.

**Parameters:**
- `color` (ColorResolvable): The color to lighten.
- `amount` (number): The percentage to lighten (0-100).

### `withOpacity(color, opacity)`

Apply a specified opacity to a given color.

**Parameters:**
- `color` (ColorResolvable): The base color.
- `opacity` (number): The desired opacity level (0.0-1.0).

### `isHexColor(string)`

Check if a given string is a valid hexadecimal color representation.

**Parameters:**
- `string` (string): The string to validate.

**Returns:**
- `boolean`: True if the string is a valid hex color, false otherwise.
```

--------------------------------

### Create Leaderboard Card with Avatars

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/leaderboard-card.md

Add an optional avatar to a leaderboard entry by providing an image URL or resolvable image object. This enhances user recognition on the card.

```typescript
const card = await new LeaderboardCardBuilder()
  .setTitle('Top Players')
  .addEntry({
    rank: 1,
    username: 'Jersuxs',
    score: 25400,
    avatar: 'https://cdn.discordapp.com/avatars/...',
  })
  .build();
```

--------------------------------

### State & Filter Methods

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/api-reference.md

Methods for controlling the visual state and applying filters to the canvas.

```APIDOC
## State & Filter Methods

### `drawShadow(color?, blur?, offsetX?, offsetY?)`

Enable shadow effects on the canvas.

**Parameters:**
- `color` (string, optional): The color of the shadow.
- `blur` (number, optional): The blur radius of the shadow.
- `offsetX` (number, optional): The horizontal offset of the shadow.
- `offsetY` (number, optional): The vertical offset of the shadow.

### `clearShadow()`

Disable shadow effects on the canvas.

### `setGlobalAlpha(alpha)`

Set the global transparency level for all subsequent drawing operations.

**Parameters:**
- `alpha` (number): The transparency value, ranging from 0.0 (fully transparent) to 1.0 (fully opaque).

### `resetGlobalAlpha()`

Reset the global transparency to its default value of 1.0.

### `setFilter(filterString)`

Apply a CSS filter string to the canvas.

**Parameters:**
- `filterString` (string): A valid CSS filter string (e.g., 'blur(5px) contrast(150%)').

### `clearFilter()`

Remove all applied CSS filters from the canvas.

### `applyBlur(pixels)`

Apply a CSS blur filter to the canvas.

**Parameters:**
- `pixels` (number): The blur radius in pixels.

### `applyGrayscale(percent)`

Apply a CSS grayscale filter to the canvas.

**Parameters:**
- `percent` (number): The grayscale amount, from 0 to 100.

### `applySepia(percent)`

Apply a CSS sepia filter to the canvas.

**Parameters:**
- `percent` (number): The sepia amount, from 0 to 100.

### `applyInvert(percent)`

Apply a CSS invert filter to the canvas.

**Parameters:**
- `percent` (number): The invert amount, from 0 to 100.

### `save()`

Save the current canvas state, including transformations, styles, and shadow settings.

### `restore()`

Restore the canvas state to the most recently saved state.

```

```APIDOC
## Output Methods

### `setOutputFormat(format)`

Set the output format for canvas rendering.

**Parameters:**
- `format` (string): The desired output format ('png', 'jpeg', or 'webp').

### `setOutputQuality(quality)`

Set the quality for JPEG or WebP output formats.

**Parameters:**
- `quality` (number): The quality level, typically between 0 and 1 (or 0 and 100 depending on implementation).

### `toBuffer()`

Encode the canvas content and return it as a Buffer.

### `getContext()`

Get the raw 2D rendering context of the canvas.

### `registerFont(path, name)`

Register a custom font for use on the canvas.

**Parameters:**
- `path` (string): The file path to the font file.
- `name` (string): The name to be used for the registered font.
```

--------------------------------

### Create a Custom Canvas Design

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/getting-started.md

Utilize CanvasBuilder for full creative control, drawing text, lines, progress bars, and gradients on a custom-sized canvas.

```typescript
import { CanvasBuilder } from 'canvas-forge';

const buffer = new CanvasBuilder(800, 400)
  .setBackground('#1a1a2e')
  .drawShadow()
  .drawGradientRect(20, 20, 760, 360, { colors: ['#e94560', '#0f3460'] }, 15)
  .clearShadow()
  .setFont(32, 'sans-serif', 'bold')
  .drawText('Custom Design', 400, 200, '#ffffff', 'center')
  .drawLine(40, 250, 760, 250, '#e94560', 2)
  .drawProgressBar(50, 300, 700, 30, 0.75, '#e94560', '#2a2a3e')
  .toBuffer();
```

--------------------------------

### Create Level Up Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Generates a level up card to notify users of their advancement.

```typescript
import { LevelUpCardBuilder } from 'canvas-forge';

const card = await new LevelUpCardBuilder()
  .setAvatar(user.displayAvatarURL({ extension: 'png', size: 256 }))
  .setUsername(user.username)
  .setLevel(10)
  .setTitleText('Level Up!')
  .build();
```

--------------------------------

### Register Custom Fonts

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

Load and register custom font files for use in text rendering on the canvas. Specify the file path and the font name.

```typescript
builder.registerFont('./fonts/Montserrat-Bold.ttf', 'Montserrat');
```

--------------------------------

### Build a Moderation Card

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

The ModerationCardBuilder creates a card for logging moderation actions. Specify the action type, user details, moderator, reason, and case number.

```typescript
import { ModerationCardBuilder } from 'canvas-forge';

const card = await new ModerationCardBuilder()
  .setAction('ban')
  .setAvatar(user.displayAvatarURL({ extension: 'png' }))
  .setUsername(user.username)
  .setModerator(interaction.user.username)
  .setReason('Spamming invites')
  .setCaseNumber('#1042')
  .build();
```

--------------------------------

### Set Canvas Background

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/custom-canvas.md

Configures the canvas background using a solid color, a gradient, or an image. Image background loading is asynchronous.

```typescript
// Solid color
canvas.setBackground('#1a1a2e');
```

```typescript
// Gradient
canvas.setBackgroundGradient({
  colors: ['#e94560', '#0f3460'],
  direction: 'horizontal',
});
```

```typescript
// Image (async)
await canvas.setBackgroundImage('https://example.com/bg.png');
```

--------------------------------

### Leaderboard Entry Format

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/cards/leaderboard-card.md

Defines the structure for each entry in the leaderboard. Includes rank, username, score, and an optional avatar. 'ImageResolvable' is a type for image sources.

```typescript
interface LeaderboardEntry {
  rank: number;           // Position (1, 2, 3, ...)
  username: string;       // Display name
  score: number;          // Score / XP / coins
  avatar?: ImageResolvable; // Optional avatar
}
```

--------------------------------

### Create a Custom Canvas

Source: https://github.com/jersuxsss/canvas-forge/blob/main/README.md

The CanvasBuilder allows for detailed customization of a canvas. Set background, draw shapes, text, and progress bars with specific colors and dimensions.

```typescript
import { CanvasBuilder } from 'canvas-forge';

const buffer = new CanvasBuilder(800, 400)
  .setBackground('#1a1a2e')
  .drawShadow()
  .drawGradientRect(20, 20, 760, 360, { colors: ['#e94560', '#0f3460'] }, 15)
  .clearShadow()
  .drawLine(40, 200, 760, 200, '#ffffff', 1)
  .setFont(32, 'sans-serif', 'bold')
  .drawText('My Custom Card', 400, 60, '#e94560', 'center')
  .drawPolygon([[400, 100], [500, 180], [400, 260], [300, 180]], '#5865F2')
  .drawProgressBar(50, 300, 700, 30, 0.75, '#e94560', '#2a2a3e')
  .toBuffer();
```

--------------------------------

### Draw Lines and Polygons

Source: https://github.com/jersuxsss/canvas-forge/blob/main/docs/custom-canvas.md

Draws straight lines and custom polygons. Polygons can be filled, stroked, or both.

```typescript
// Line
canvas.drawLine(0, 200, 800, 200, '#ffffff', 2);
```

```typescript
// Polygon (triangle, diamond, any shape)
canvas.drawPolygon(
  [[400, 50], [500, 200], [300, 200]],
  '#5865F2',
);
```

```typescript
// Polygon with stroke
canvas.drawPolygon(
  [[400, 50], [500, 200], [300, 200]],
  '#5865F2',
  '#ffffff', 2,
);
```