nextgen-permsy-adapter

Official Nextgen adapter for the Permsy permission management engine.

🇹🇷 Türkçe Kullanım Kılavuzu için aşağıya bakın: Turkish Documentation

🚀 Quick Start

Installation

npm install nextgen-permsy-adapter permsy

Basic Setup (Recommended)

import { App, Intents } from 'discordjs-nextgen';
import { Permsy } from 'permsy';
import { NextgenAdapter, setupPermsyForPrefix } from 'nextgen-permsy-adapter';

const app = new App({ intents: Intents.ALL });

// Initialize Permsy
const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// Global auto-check for ALL prefix commands - ONE LINE!
setupPermsyForPrefix(app, permsy);

// Load commands
app.prefix({ prefix: '!', folder: './commands/prefix' });
app.slash({ folder: './commands/slash' });

app.run(process.env.TOKEN);

Create Permission Config

Create ./config/permsy.config.js:

import { definePermissionConfig } from 'permsy';

export default definePermissionConfig({
  defaultDenyMessage: "❌ You don't have permission!",
  
  commands: {
    prefixes: {
      ban: {
        rolesOnly: ["ADMIN_ROLE_ID"],
        denyMessage: "❌ You need Admin role to use this command!"
      },
      kick: {
        permissionsOnly: ["KICK_MEMBERS"]
      }
    },
    
    slashes: {
      // Slash command permissions coming soon
    }
  }
});

Write Your Commands (No Permission Checks Needed!)

// commands/prefix/ban.js
export default {
  name: 'ban',
  description: 'Ban a user',
  run: async (ctx) => {
    // No permission check needed - it's automatic!
    // If user doesn't have permission, they never reach here
    
    await ctx.reply('User banned!');
  }
};

That's it! ✨ Permissions are checked automatically. Users without permission will see the deny message from config.

📚 Usage Modes

Mode 1: Global Auto-Check (Recommended) ⭐

Use setupPermsyForPrefix() for automatic permission checking on ALL commands.

import { setupPermsyForPrefix } from 'nextgen-permsy-adapter';

setupPermsyForPrefix(app, permsy);

// Load commands - they're automatically protected
app.prefix({ prefix: '!', folder: './commands/prefix' });

Advantages:

✅ One-line setup
✅ No code in commands
✅ All config in permsy.config.js
✅ Clean and maintainable

Your commands:

export default {
  name: 'admin',
  run: async (ctx) => {
    // No permission check - automatic!
    await ctx.reply('Admin panel opened');
  }
};

Mode 2: Per-Command Manual Check

Use withPermsy() when you want to protect SPECIFIC commands only.

import { withPermsy } from 'nextgen-permsy-adapter';

export default {
  name: 'sensitive',
  description: 'Sensitive command with manual check',
  run: withPermsy('sensitive', async (ctx) => {
    // Check permission manually
    if (!await ctx.permsy.isAllowed(ctx)) return;
    
    // Custom logic after permission check
    await ctx.reply('Access granted!');
  })
};

When to use:

Need custom logic after permission check
Only specific commands need protection
Want to add additional validation

Setup:

import { NextgenAdapter, attachPermsy } from 'nextgen-permsy-adapter';

const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// Manual mode - attach permsy to context
app.use(attachPermsy(permsy));

Mode 3: Plugin Mode (Alternative Global)

Use PermsyPlugin for middleware-based automatic checking.

Note: This mode may have limitations with Nextgen's command system. Use setupPermsyForPrefix instead for better compatibility.

import { PermsyPlugin } from 'nextgen-permsy-adapter';

app.use(new PermsyPlugin(permsy));

🎯 API Reference

`NextgenAdapter`

The core adapter that bridges Nextgen Context with Permsy.

import { NextgenAdapter } from 'nextgen-permsy-adapter';

const adapter = new NextgenAdapter();

const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: adapter
});

Features:

Extracts user roles from message.member.roles
Converts Discord permissions from bitfield
Handles both slash and prefix commands
Sends ephemeral deny messages

`setupPermsyForPrefix(app, permsy)`

RECOMMENDED: Sets up global automatic permission checking for ALL prefix commands.

Parameters:

app - Nextgen App instance
permsy - Permsy instance

Example:

import { setupPermsyForPrefix } from 'nextgen-permsy-adapter';

const app = new App({ intents: Intents.ALL });
const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// Must be called BEFORE loading commands
setupPermsyForPrefix(app, permsy);

// Now load commands
app.prefix({ prefix: '!', folder: './commands/prefix' });

Important: Call setupPermsyForPrefix BEFORE app.prefix() to ensure all commands are wrapped.

`withPermsy(commandName, handler)`

Wraps a single command handler to inject command name for Permsy checks.

Parameters:

commandName - The command name (string)
handler - The command handler function

Example:

import { withPermsy } from 'nextgen-permsy-adapter';

export default {
  name: 'ban',
  run: withPermsy('ban', async (ctx) => {
    // Manual permission check
    if (!await ctx.permsy.isAllowed(ctx)) return;
    
    // Command logic
    await ctx.reply('User banned!');
  })
};

Use case: When you need manual control over specific commands while using global setup.

`PermsyPlugin`

Middleware plugin for automatic permission checking.

Example:

import { PermsyPlugin } from 'nextgen-permsy-adapter';

app.use(new PermsyPlugin(permsy));

Note: Due to Nextgen's architecture, setupPermsyForPrefix is recommended instead for better command name resolution.

🔧 Configuration Examples

Simple Role-Based Access

export default definePermissionConfig({
  defaultDenyMessage: "❌ Access denied!",
  
  commands: {
    prefixes: {
      admin: {
        rolesOnly: ["ADMIN_ROLE_ID"],
        denyMessage: "❌ Admin role required!"
      }
    }
  }
});

Permission-Based Access

export default definePermissionConfig({
  commands: {
    prefixes: {
      ban: {
        permissionsOnly: ["BAN_MEMBERS"]
      },
      kick: {
        permissionsOnly: ["KICK_MEMBERS"]
      }
    }
  }
});

Multiple Requirements (OR Logic)

export default definePermissionConfig({
  commands: {
    prefixes: {
      moderate: {
        rolesOnly: ["MODERATOR_ROLE_ID"],
        usersOnly: ["OWNER_USER_ID"],
        permissionsOnly: ["MODERATE_MEMBERS"]
        // User needs ANY ONE of these
      }
    }
  }
});

Channel Restrictions

export default definePermissionConfig({
  commands: {
    prefixes: {
      modlog: {
        channelsOnly: ["MOD_CHANNEL_ID"],
        rolesOnly: ["MODERATOR_ROLE_ID"]
      }
    }
  }
});

📝 Complete Example

bot/index.js:

import { App, Intents } from 'discordjs-nextgen';
import { Permsy } from 'permsy';
import { NextgenAdapter, setupPermsyForPrefix } from 'nextgen-permsy-adapter';
import 'dotenv/config';

const app = new App({ intents: Intents.ALL });

const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// Global auto-check - one line!
setupPermsyForPrefix(app, permsy);

// Load commands
app.prefix({ prefix: '!', folder: './commands/prefix' });
app.slash({ folder: './commands/slash' });

app.run(process.env.TOKEN);

config/permsy.config.js:

import { definePermissionConfig } from 'permsy';

export default definePermissionConfig({
  defaultDenyMessage: "❌ You don't have permission!",
  
  commands: {
    prefixes: {
      ban: {
        rolesOnly: ["ADMIN_ROLE_ID"],
        denyMessage: "⛔ Admin role required!"
      },
      kick: {
        permissionsOnly: ["KICK_MEMBERS"]
      },
      help: {
        // Not listed = everyone can use
      }
    }
  }
});

commands/prefix/ban.js:

export default {
  name: 'ban',
  description: 'Ban a user',
  run: async (ctx) => {
    // No permission check - automatic!
    await ctx.reply('User banned!');
  }
};

commands/prefix/help.js:

export default {
  name: 'help',
  description: 'Help command',
  run: async (ctx) => {
    // Not in config = everyone can use
    await ctx.reply('Help menu...');
  }
};

❓ FAQ

Do I need to check permissions in every command?

No! When using setupPermsyForPrefix(), permissions are checked automatically. You only write command logic.

What if a command is not in the config?

Commands not listed in permsy.config.js are allowed by default. Only add commands that need restrictions.

Can I mix protected and public commands?

Yes! Only add restricted commands to config. Other commands work normally.

How do I protect all commands by default?

You would need to list all commands in config. Permsy uses an "allow by default" approach for commands not in config.

Can I add custom logic after permission check?

Yes! Use withPermsy() for manual checks with custom logic:

run: withPermsy('admin', async (ctx) => {
  if (!await ctx.permsy.isAllowed(ctx)) {
    // Custom denied logic
    console.log('Access denied');
    return;
  }
  
  // Custom allowed logic
  console.log('Access granted');
  await ctx.reply('Welcome!');
})

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Ümit ULUSOY

🔗 Links

🇹🇷 Turkish Documentation / Türkçe Dokümantasyon

Nextgen framework'ü için resmi Permsy izin yönetim motoru adaptörü.

🚀 Hızlı Başlangıç

Kurulum

npm install nextgen-permsy-adapter permsy

Temel Kurulum (Önerilen)

import { App, Intents } from 'discordjs-nextgen';
import { Permsy } from 'permsy';
import { NextgenAdapter, setupPermsyForPrefix } from 'nextgen-permsy-adapter';

const app = new App({ intents: Intents.ALL });

// Permsy'yi başlat
const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// TÜM prefix komutları için global otomatik kontrol - TEK SATIR!
setupPermsyForPrefix(app, permsy);

// Komutları yükle
app.prefix({ prefix: '!', folder: './commands/prefix' });
app.slash({ folder: './commands/slash' });

app.run(process.env.TOKEN);

İzin Konfigürasyonu Oluştur

./config/permsy.config.js dosyası oluşturun:

import { definePermissionConfig } from 'permsy';

export default definePermissionConfig({
  defaultDenyMessage: "❌ Bu komutu kullanma yetkin yok!",
  
  commands: {
    prefixes: {
      ban: {
        rolesOnly: ["ADMIN_ROL_ID"],
        denyMessage: "❌ Bu komutu kullanmak için Admin rolü gerekli!"
      },
      kick: {
        permissionsOnly: ["KICK_MEMBERS"]
      }
    },
    
    slashes: {
      // Slash komut izinleri yakında
    }
  }
});

Komutlarınızı Yazın (İzin Kontrolü Gereksiz!)

// commands/prefix/ban.js
export default {
  name: 'ban',
  description: 'Kullanıcıyı yasakla',
  run: async (ctx) => {
    // İzin kontrolü gerekmez - otomatik!
    // Kullanıcının izni yoksa buraya asla ulaşmaz
    
    await ctx.reply('Kullanıcı yasaklandı!');
  }
};

Bu kadar! ✨ İzinler otomatik kontrol edilir. İzni olmayan kullanıcılar config'teki reddetme mesajını görür.

📚 Kullanım Modları

Mod 1: Global Otomatik Kontrol (Önerilen) ⭐

TÜM komutlarda otomatik izin kontrolü için setupPermsyForPrefix() kullanın.

import { setupPermsyForPrefix } from 'nextgen-permsy-adapter';

setupPermsyForPrefix(app, permsy);

// Komutları yükle - otomatik korunuyorlar
app.prefix({ prefix: '!', folder: './commands/prefix' });

Avantajlar:

✅ Tek satır kurulum
✅ Komutlarda kod yok
✅ Tüm config permsy.config.js'te
✅ Temiz ve bakımı kolay

Komutlarınız:

export default {
  name: 'admin',
  run: async (ctx) => {
    // İzin kontrolü yok - otomatik!
    await ctx.reply('Admin paneli açıldı');
  }
};

Mod 2: Komut Bazında Manuel Kontrol

Sadece BELİRLİ komutları korumak istediğinizde withPermsy() kullanın.

import { withPermsy } from 'nextgen-permsy-adapter';

export default {
  name: 'hassas',
  description: 'Manuel kontrollü hassas komut',
  run: withPermsy('hassas', async (ctx) => {
    // İzni manuel kontrol et
    if (!await ctx.permsy.isAllowed(ctx)) return;
    
    // İzin kontrolünden sonra özel mantık
    await ctx.reply('Erişim verildi!');
  })
};

Ne zaman kullanılır:

İzin kontrolünden sonra özel mantık gerekli
Sadece belirli komutların korunması gerekli
Ek doğrulama eklemek istiyorsunuz

Mod 3: Plugin Modu (Alternatif Global)

Middleware tabanlı otomatik kontrol için PermsyPlugin kullanın.

Not: Bu modun Nextgen'in komut sistemiyle sınırlamaları olabilir. Daha iyi uyumluluk için setupPermsyForPrefix kullanın.

import { PermsyPlugin } from 'nextgen-permsy-adapter';

app.use(new PermsyPlugin(permsy));

🎯 API Referansı

`NextgenAdapter`

Nextgen Context'i Permsy ile birleştiren ana adaptör.

import { NextgenAdapter } from 'nextgen-permsy-adapter';

const adapter = new NextgenAdapter();

const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: adapter
});

Özellikler:

message.member.roles'den kullanıcı rollerini çıkarır
Discord yetkilerini bitfield'den dönüştürür
Hem slash hem prefix komutları destekler
Ephemeral reddetme mesajları gönderir

`setupPermsyForPrefix(app, permsy)`

ÖNERİLEN: TÜM prefix komutları için global otomatik izin kontrolü kurar.

Parametreler:

app - Nextgen App instance
permsy - Permsy instance

Örnek:

import { setupPermsyForPrefix } from 'nextgen-permsy-adapter';

const app = new App({ intents: Intents.ALL });
const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// Komutları yüklemeden ÖNCE çağrılmalı
setupPermsyForPrefix(app, permsy);

// Şimdi komutları yükle
app.prefix({ prefix: '!', folder: './commands/prefix' });

Önemli: setupPermsyForPrefix'i app.prefix()'den ÖNCE çağırın ki tüm komutlar wrap edilsin.

`withPermsy(commandName, handler)`

Tek bir komut handler'ını wrap ederek Permsy kontrolleri için komut adını inject eder.

Parametreler:

commandName - Komut adı (string)
handler - Komut handler fonksiyonu

Örnek:

import { withPermsy } from 'nextgen-permsy-adapter';

export default {
  name: 'ban',
  run: withPermsy('ban', async (ctx) => {
    // Manuel izin kontrolü
    if (!await ctx.permsy.isAllowed(ctx)) return;
    
    // Komut mantığı
    await ctx.reply('Kullanıcı yasaklandı!');
  })
};

`PermsyPlugin`

Otomatik izin kontrolü için middleware plugin.

Örnek:

import { PermsyPlugin } from 'nextgen-permsy-adapter';

app.use(new PermsyPlugin(permsy));

Not: Nextgen'in mimarisi nedeniyle, daha iyi komut adı çözümlemesi için setupPermsyForPrefix önerilir.

📝 Tam Örnek

bot/index.js:

import { App, Intents } from 'discordjs-nextgen';
import { Permsy } from 'permsy';
import { NextgenAdapter, setupPermsyForPrefix } from 'nextgen-permsy-adapter';
import 'dotenv/config';

const app = new App({ intents: Intents.ALL });

const permsy = new Permsy({
  configDir: './config',
  fileName: 'permsy.config.js',
  adapter: new NextgenAdapter()
});

// Global otomatik kontrol - tek satır!
setupPermsyForPrefix(app, permsy);

// Komutları yükle
app.prefix({ prefix: '!', folder: './commands/prefix' });
app.slash({ folder: './commands/slash' });

app.run(process.env.TOKEN);

config/permsy.config.js:

import { definePermissionConfig } from 'permsy';

export default definePermissionConfig({
  defaultDenyMessage: "❌ Yetkin yok!",
  
  commands: {
    prefixes: {
      ban: {
        rolesOnly: ["ADMIN_ROL_ID"],
        denyMessage: "⛔ Admin rolü gerekli!"
      },
      kick: {
        permissionsOnly: ["KICK_MEMBERS"]
      },
      yardim: {
        // Listede değil = herkes kullanabilir
      }
    }
  }
});

commands/prefix/ban.js:

export default {
  name: 'ban',
  description: 'Kullanıcıyı yasakla',
  run: async (ctx) => {
    // İzin kontrolü yok - otomatik!
    await ctx.reply('Kullanıcı yasaklandı!');
  }
};

❓ Sık Sorulan Sorular

Her komutta izin kontrolü yazmam gerekir mi?

Hayır! setupPermsyForPrefix() kullandığınızda izinler otomatik kontrol edilir. Sadece komut mantığınızı yazarsınız.

Config'te olmayan komutlar ne olur?

permsy.config.js'te listelenmeyen komutlar varsayılan olarak izin verilir. Sadece kısıtlamak istediğiniz komutları ekleyin.

Korumalı ve genel komutları karıştırabilir miyim?

Evet! Sadece kısıtlı komutları config'e ekleyin. Diğer komutlar normal çalışır.

Tüm komutları varsayılan olarak nasıl korurım?

Tüm komutları config'te listelemeniz gerekir. Permsy, config'te olmayan komutlar için "varsayılan izin ver" yaklaşımı kullanır.

Name		Name	Last commit message	Last commit date
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
USAGE.md		USAGE.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Latest commit

History

Folders and files

Repository files navigation

nextgen-permsy-adapter

🚀 Quick Start

Installation

Basic Setup (Recommended)

Create Permission Config

Write Your Commands (No Permission Checks Needed!)

📚 Usage Modes

Mode 1: Global Auto-Check (Recommended) ⭐

Mode 2: Per-Command Manual Check

Mode 3: Plugin Mode (Alternative Global)

🎯 API Reference

NextgenAdapter

setupPermsyForPrefix(app, permsy)

withPermsy(commandName, handler)

PermsyPlugin

🔧 Configuration Examples

Simple Role-Based Access

Permission-Based Access

Multiple Requirements (OR Logic)

Channel Restrictions

📝 Complete Example

❓ FAQ

Do I need to check permissions in every command?

What if a command is not in the config?

Can I mix protected and public commands?

How do I protect all commands by default?

Can I add custom logic after permission check?

🤝 Contributing

📄 License

🔗 Links

🇹🇷 Turkish Documentation / Türkçe Dokümantasyon

🚀 Hızlı Başlangıç

Kurulum

Temel Kurulum (Önerilen)

İzin Konfigürasyonu Oluştur

Komutlarınızı Yazın (İzin Kontrolü Gereksiz!)

📚 Kullanım Modları

Mod 1: Global Otomatik Kontrol (Önerilen) ⭐

Mod 2: Komut Bazında Manuel Kontrol

Mod 3: Plugin Modu (Alternatif Global)

🎯 API Referansı

NextgenAdapter

setupPermsyForPrefix(app, permsy)

withPermsy(commandName, handler)

PermsyPlugin

📝 Tam Örnek

❓ Sık Sorulan Sorular

Her komutta izin kontrolü yazmam gerekir mi?

Config'te olmayan komutlar ne olur?

Korumalı ve genel komutları karıştırabilir miyim?

Tüm komutları varsayılan olarak nasıl korurım?

🤝 Katkıda Bulunma

📄 Lisans

🔗 Bağlantılar

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`NextgenAdapter`

`setupPermsyForPrefix(app, permsy)`

`withPermsy(commandName, handler)`

`PermsyPlugin`

`NextgenAdapter`

`setupPermsyForPrefix(app, permsy)`

`withPermsy(commandName, handler)`

`PermsyPlugin`