codemeet-go

README

🚀 CodeMeet Go SDK

یک SDK قدرتمند، مدرن و Production-Ready برای توسعه ربات‌های CodeMeet با زبان Go

High Performance • Type-Safe • Concurrent • Modular • Production Ready

---

📖 فهرست مطالب

• 📌 معرفی کتابخانه
• ✨ ویژگی‌های کلیدی
• 📦 نصب و راه‌اندازی
• 🚀 شروع سریع
• 🌐 Bot API
• 🧩 معماری کتابخانه
• 🛡 پکیج‌های Contrib
• 📊 مانیتورینگ و Dashboard
• ⚡ Performance و Concurrency
• 📚 مستندات کامل
• 🤝 مشارکت
• 👨‍💻 توسعه‌دهنده

---

📌 معرفی کتابخانه

CodeMeet Go SDK یک کتابخانه مدرن و ماژولار برای توسعه ربات‌های پلتفرم CodeMeet با زبان Go است.

هدف اصلی این پروژه فراهم کردن یک لایه‌ی قدرتمند، type-safe و قابل استفاده در پروژه‌های واقعی روی Bot API کدمیت است؛ به‌طوری که توسعه‌دهنده بتواند بدون درگیر شدن مستقیم با جزئیات HTTP و JSON، ربات‌های سریع، پایدار و قابل توسعه ایجاد کند.

کتابخانه علاوه بر API اصلی، مجموعه‌ای از ابزارهای زیرساختی و پکیج‌های کمکی را نیز ارائه می‌کند:

• HTTP Client
• Bot API Methods
• Typed Models
• Dispatcher
• Middleware
• Long Polling
• Webhook
• Retry
• Rate Limiting
• Concurrency Limiting
• In-Memory Cache
• Sharded Cache
• Circuit Breaker
• Structured Logging
• Error Handling
• Statistics
• Health Check
• Dashboard
• ابزارهای امنیتی و مدیریتی در contrib

---

✨ ویژگی‌های کلیدی

دسته‌بندی	قابلیت‌ها	توضیح
🌐 ارتباط با API	HTTP Client، Request، Multipart، Form	لایه‌ی ارتباطی مرکزی با Bot API
🛡 پایداری شبکه	Retry، Circuit Breaker	مدیریت خطاها و درخواست‌های ناموفق
⚡ کنترل ترافیک	Rate Limiter، Concurrency Limiter	کنترل نرخ و تعداد درخواست‌های همزمان
🚀 پردازش آپدیت	Dispatcher، Worker	مدیریت و پردازش Updateها
🔌 دریافت Update	Long Polling، Webhook	دو روش اصلی دریافت رویدادها
💾 Cache	Cache، Sharded Cache، TTL	ذخیره سریع داده‌های موقت در حافظه
🧩 Middleware	Recovery، Logging، Metrics، Timeout	کنترل رفتار پردازش Update
📨 پیام	Text، HTML، Markdown، Edit، Delete	مدیریت پیام‌ها
🎞 Media	Photo، Video، Document، Audio، Voice و...	ارسال و دریافت انواع Media
🎛 Keyboard	Inline Keyboard، Reply Keyboard	ساخت رابط تعاملی برای ربات
👥 مدیریت Chat	Member، Admin، Ban، Restrict، Invite	مدیریت گروه‌ها و کانال‌ها
🤖 Bot Management	Profile، Commands	مدیریت اطلاعات و دستورات Bot
📊 Observability	Statistics، Logs، Metrics، Health Check	مشاهده وضعیت و عملکرد سیستم
🛡 امنیت	AntiSpam، AntiLink، Gatekeeper و...	ابزارهای امنیتی آماده
🧰 ابزارهای مدیریتی	ForceJoin، WarnSystem، Maintenance Mode	امکانات مدیریتی برای ربات‌ها
🔍 تحلیل فایل	VPN Detector	بررسی فایل‌ها و کانفیگ‌های مشکوک

---

📦 نصب و راه‌اندازی

برای نصب کتابخانه:

go get github.com/AbolfazlZarei-dev/codemeet-go

سپس می‌توانید آن را در پروژه‌ی Go خود import کنید.

---

🚀 شروع سریع

یک ربات ساده با Long Polling:

package main

import (
	"context"
	"fmt"
	"log"
	"os/signal"
	"syscall"

	codemeet "github.com/AbolfazlZarei-dev/codemeet-go/codemeet"
	"github.com/AbolfazlZarei-dev/codemeet-go/models"
	"github.com/AbolfazlZarei-dev/codemeet-go/polling"
)

func main() {
	token := "YOUR_BOT_TOKEN"

	ctx, cancel := signal.NotifyContext(
		context.Background(),
		syscall.SIGINT,
		syscall.SIGTERM,
	)
	defer cancel()

	bot, err := codemeet.New(token)
	if err != nil {
		log.Fatal(err)
	}
	defer bot.Close()

	bot.OnMessage(func(
		ctx context.Context,
		msg *models.Message,
	) {
		fmt.Printf(
			"📥 پیام از %s: %s\n",
			msg.From.FullName(),
			msg.Text,
		)

		_, err := bot.Reply(
			ctx,
			msg,
			"👋 سلام! پیام شما دریافت شد.",
		)

		if err != nil {
			log.Println(err)
		}
	})

	bot.OnCommand(
		"start",
		func(
			ctx context.Context,
			msg *models.Message,
		) {
			_, err := bot.SendHTML(
				ctx,
				msg.Chat.ID,
				"<b>🤖 ربات با موفقیت فعال شد!</b>",
			)

			if err != nil {
				log.Println(err)
			}
		},
	)

	fmt.Println("🚀 ربات در حال اجراست...")

	cfg := polling.DefaultConfig()
	cfg.Timeout = 20

	if err := bot.StartPolling(ctx, cfg); err != nil {
		log.Fatal(err)
	}
}

---

🌐 Bot API

CodeMeet Go روی Bot API پلتفرم CodeMeet ساخته شده است.

Endpoint اصلی API:

https://botapi.codemeet.chat/bot{TOKEN}/{METHOD}

کتابخانه جزئیات HTTP Request، Response، Encoding، Multipart، Error Handling و Retry را در لایه‌ی api و methods مدیریت می‌کند.

بنابراین توسعه‌دهنده معمولاً به جای ساخت دستی HTTP Request می‌تواند از API سطح بالای کتابخانه استفاده کند.

مثال:

msg, err := bot.API().
	Messages().
	SendText(
		ctx,
		chatID,
		"سلام 👋",
	)

---

🧩 معماری کتابخانه

ساختار پروژه به شکل ماژولار طراحی شده است:

codemeet-go/
│
├── api/
│   └── HTTP Client و لایه ارتباط با Bot API
│
├── methods/
│   ├── Messages
│   ├── Media
│   ├── Bot
│   ├── Chat
│   ├── Updates
│   └── Webhook
│
├── models/
│   ├── User
│   ├── Chat
│   ├── Message
│   ├── Update
│   ├── Keyboard
│   └── Media
│
├── dispatcher/
│   └── مدیریت و Dispatch کردن Updateها
│
├── middleware/
│   └── Middlewareهای آماده
│
├── polling/
│   └── Long Polling
│
├── webhook/
│   └── Webhook Server
│
├── cache/
│   └── In-Memory و Sharded Cache
│
├── ratelimit/
│   └── Rate و Concurrency Limiting
│
├── retry/
│   └── Retry Policy
│
├── logger/
│   └── Logging و JSON Logging
│
├── errors/
│   └── Error Handling
│
└── contrib/
    ├── antilink
    ├── antispam
    ├── forcejoin
    ├── gatekeeper
    ├── maintenancemode
    ├── profanityfilter
    ├── vpndetector
    └── warnsystem

---

🛡 پکیج‌های Contrib

پکیج‌های contrib قابلیت‌های اختیاری و سطح بالاتری هستند که می‌توانند در کنار هسته‌ی کتابخانه استفاده شوند.

🚪 Gatekeeper

مسئول مدیریت ورود کاربران و اجرای Challenge/Captcha.

قابلیت‌ها:

• Math Captcha
• Number Captcha
• Inline Button Challenge
• مدیریت کاربران در انتظار
• مدیریت Challengeها
• Statistics
• Cleanup خودکار

مسیر:

contrib/gatekeeper

---

🔍 VPN Detector

سیستم تحلیل فایل و متن برای شناسایی نشانه‌های مربوط به VPN، Proxy و برخی فرمت‌های کانفیگ.

قابلیت‌های موجود در package شامل:

• بررسی متن
• بررسی نام APK
• بررسی نام فایل کانفیگ
• بررسی فایل‌های متنی
• بررسی APK
• بررسی ZIP
• تشخیص Base64 Candidate
• بررسی JSON
• بررسی YAML
• تشخیص الگوهای Host/Port
• تشخیص Proxy Indicator
• تحلیل Binary Signature
• Statistics

مسیر:

contrib/vpndetector

---

⚠️ Warn System

سیستم مدیریت اخطار کاربران.

قابلیت‌ها:

• افزودن Warning
• دریافت تعداد Warning
• Reset کردن Warning
• نگهداری وضعیت کاربران
• Cleanup
• Statistics
• پشتیبانی از Sharding

مسیر:

contrib/warnsystem

---

🔐 AntiLink

Middleware برای شناسایی و مدیریت لینک‌ها.

قابلیت‌ها:

• بررسی URL
• بررسی Host
• Normalization دامنه
• تشخیص دامنه‌های مجاز
• مدیریت لینک‌های مجاز
• Block کردن پیام‌های دارای لینک غیرمجاز

مسیر:

contrib/antilink

---

🛡 AntiSpam

سیستم کنترل Spam و Flood.

قابلیت‌ها:

• Rate Limit کاربران
• تشخیص Spam
• Keyword Detection
• Warning
• Ban / Unban
• User State
• Cleanup
• Statistics

مسیر:

contrib/antispam

---

👥 ForceJoin

سیستم بررسی عضویت اجباری.

قابلیت‌ها:

• Middleware
• بررسی وضعیت کاربر
• Cache کاربران
• پاک‌سازی Cache
• Statistics

مسیر:

contrib/forcejoin

---

🔧 Maintenance Mode

امکان قرار دادن ربات در حالت تعمیرات.

قابلیت‌ها:

• فعال / غیرفعال کردن Maintenance Mode
• بررسی وضعیت
• تشخیص Admin
• Middleware
• مدیریت Notification
• Cleanup
• Stop

مسیر:

contrib/maintenancemode

---

🔤 Profanity Filter

Middleware برای بررسی و فیلتر کلمات ممنوعه.

قابلیت‌ها:

• Normalization متن
• Normalization کلمات ممنوعه
• Scan متن
• Middleware

مسیر:

contrib/profanityfilter

---

📊 مانیتورینگ و Dashboard

کتابخانه دارای سیستم Statistics و Dashboard است.

در سطح Bot می‌توان از قابلیت‌هایی مانند:

bot.HealthCheck()

و:

bot.Stats()

و:

bot.Uptime()

استفاده کرد.

همچنین Dashboard از طریق:

bot.StartDashboard(ctx, ":9090")

قابل اجرا است.

نمونه:

go func() {
	err := bot.StartDashboard(
		context.Background(),
		":9090",
	)

	if err != nil {
		log.Println(err)
	}
}()

پس از اجرا:

http://localhost:9090

قابل دسترسی خواهد بود.

---

⚡ Performance و Concurrency

یکی از اهداف اصلی CodeMeet Go SDK، ارائه‌ی زیرساخت مناسب برای Botهای پرترافیک است.

بخش‌های مختلف کتابخانه برای کار با محیط‌های Concurrent طراحی شده‌اند.

موارد مهم:

• Worker-based Dispatcher
• Bounded Dispatch Queue
• Sharded Cache
• TTL Cache
• Rate Limiting
• Concurrency Limiting
• Retry Policy
• Circuit Breaker
• Async Logger
• Multipart Streaming
• Statistics
• Graceful Shutdown

این معماری اجازه می‌دهد بخش‌های مختلف سیستم بدون وابستگی شدید به یکدیگر توسعه داده شوند.

---

📨 Messages و Media

کتابخانه API سطح بالایی برای ارسال و مدیریت پیام ارائه می‌کند.

پیام متنی

msg, err := bot.API().
	Messages().
	SendText(
		ctx,
		chatID,
		"سلام",
	)

HTML

msg, err := bot.API().
	Messages().
	SendHTML(
		ctx,
		chatID,
		"<b>سلام</b>",
	)

Markdown

msg, err := bot.API().
	Messages().
	SendMarkdown(
		ctx,
		chatID,
		"*سلام*",
	)

Keyboard

markup := models.NewInlineKeyboard(
	models.InlineRow(
		models.Btn("تأیید", "confirm"),
		models.Btn("لغو", "cancel"),
	),
)

_, err := bot.API().
	Messages().
	SendWithKeyboard(
		ctx,
		chatID,
		"انتخاب کنید:",
		markup,
	)

کتابخانه همچنین API مربوط به:

• Forward
• Copy
• Edit
• Delete
• Chat Action
• Callback
• Photo
• Video
• Document
• Voice
• Audio
• Animation
• Sticker
• Video Note
• Media Group
• Location
• Venue
• Contact
• Poll
• Dice
• File
• Reaction

را در لایه‌ی Methods/Media پوشش می‌دهد.

---

🎛 Keyboard و Buttons

مدل‌های Keyboard در package models قرار دارند.

Inline Keyboard

markup := models.NewInlineKeyboard(
	models.InlineRow(
		models.Btn("تأیید", "confirm"),
		models.Btn("لغو", "cancel"),
	),
)

همچنین Builderهای مربوط به:

• URL Button
• WebApp Button
• Switch Inline Button
• Reply Keyboard
• Contact Button
• Location Button

وجود دارند.

---

🧱 Middleware

کتابخانه Middlewareهای مختلفی را ارائه می‌کند:

Recovery
Logging
RateLimit
Metrics
Timeout
BotOnly
UserOnly
AdminOnly
Blacklist
Whitelist

نمونه:

bot.Use(
	middleware.Logging(),
	middleware.Recovery(),
)

Middlewareها را می‌توان برای کنترل جریان پردازش Updateها و اضافه کردن رفتارهای مشترک استفاده کرد.

---

🔄 Polling و Webhook

CodeMeet Go از دو روش اصلی دریافت Update پشتیبانی می‌کند.

Long Polling

cfg := polling.DefaultConfig()

if err := bot.StartPolling(
	ctx,
	cfg,
); err != nil {
	log.Fatal(err)
}

Webhook

if err := bot.StartWebhook(
	ctx,
	config,
); err != nil {
	log.Fatal(err)
}

همچنین API مربوط به Set/Get/Delete Webhook در package methods وجود دارد.

---

🔁 Retry و Rate Limit

برای محیط‌های Production، مدیریت خطاهای موقتی اهمیت زیادی دارد.

Package retry سیاست‌های مختلفی ارائه می‌کند:

DefaultPolicy
AggressivePolicy
ConservativePolicy

و package ratelimit شامل:

Limiter
ConcurrencyLimiter
Token Bucket
Burst
Wait
TryWait
WaitTimeout

است.

---

💾 Cache

Package cache شامل Cache درون‌حافظه‌ای و Sharded Cache است.

قابلیت‌ها:

Get
Set
SetWithTTL
SetForever
Delete
Len
Keys
Clear
GetOrSet
GetOrSetWithTTL
Close

برای پروژه‌هایی که به دسترسی سریع به داده‌های موقت نیاز دارند، Cache می‌تواند فشار روی API و سایر منابع را کاهش دهد.

---

📝 Logging

Package logger چند حالت مختلف Logging ارائه می‌کند.

از جمله:

New
NewJSON
NewAsync
Debug
Info
Warn
Error
Fatal
SetLevel
SetFormat
SetOutput
WithFields

همچنین قابلیت Async Logging و JSON Logging در API این package وجود دارد.

---

❌ Error Handling

Package errors برای مدیریت خطاهای کتابخانه طراحی شده است.

انواع اصلی:

APIError
ValidationError
NetworkError
MultiError

همچنین قابلیت‌هایی مانند:

IsRetryable
ParseError
AsAPIError
AsNetworkError
AsValidationError

در اختیار توسعه‌دهنده قرار دارد.

---

📚 مستندات کامل

مستندات پروژه به صورت بخش‌بندی‌شده داخل پوشه‌ی README/ قرار گرفته‌اند.

برای مشاهده مستندات کامل:

📖 Documentation

بخش‌های اصلی

• 01 — Getting Started
• 02 — Bot API and Architecture
• 03 — Messages and Media
• 04 — Updates, Polling and Webhook
• 05 — Chat Management
• 06 — Bot Profile and Commands
• 07 — Keyboards and Buttons
• 08 — Models

Package Reference

• 09 — Package: codemeet
• 10 — Package: api
• 11 — Package: methods
• 12 — Package: dispatcher
• 13 — Package: middleware
• 14 — Package: cache
• 15 — Package: ratelimit
• 16 — Package: retry
• 17 — Package: logger
• 18 — Package: errors
• 19 — Package: polling
• 20 — Package: webhook

Methods

• 21 — Bot Methods
• 22 — Chat Methods
• 23 — Message Methods
• 24 — Media Methods
• 25 — Updates and Webhook Methods

قابلیت‌های پیشرفته

• 26 — Reliability, Performance and Observability
• 27 — AntiLink
• 28 — AntiSpam
• 29 — ForceJoin
• 30 — Gatekeeper
• 31 — Maintenance Mode
• 32 — Profanity Filter
• 33 — VPN Detector
• 34 — Warn System

توسعه و استفاده واقعی

• 35 — Examples and Production Patterns
• 36 — Errors and Troubleshooting
• 37 — Package Map and API Index

---

⚠️ وضعیت API و سازگاری نسخه‌ها

این مستندات بر اساس API و ساختار نسخه‌ی 1.0.0 کتابخانه تهیه شده‌اند.

برخی قابلیت‌ها و Methodهایی که در لایه‌ی مستندات Bot API تعریف یا برای توسعه‌های آینده در نظر گرفته شده‌اند، ممکن است در نسخه‌ی فعلی کتابخانه هنوز به صورت کامل در Bot API یا Implementation نهایی CodeMeet در دسترس نباشند.

بنابراین:

وجود نام یک Method در Documentation به معنی تضمین در دسترس بودن همان Method در تمامی نسخه‌های Bot API نیست.

در صورت اضافه شدن یا تغییر API سمت CodeMeet، کتابخانه نیز می‌تواند در نسخه‌های بعدی به‌روزرسانی شود تا سازگاری کامل برقرار شود.

این موضوع به صورت عمدی در طراحی Documentation در نظر گرفته شده تا ساختار API آینده نیز قابل توسعه و نگهداری باشد.

---

📦 نسخه

CodeMeet Go SDK
Version: 1.0.0

Repository:

github.com/AbolfazlZarei-dev/codemeet-go

---

🤝 مشارکت

اگر در کتابخانه با Bug، مشکل Performance یا ناسازگاری با Bot API مواجه شدید، می‌توانید Issue ایجاد کنید یا Pull Request ارسال کنید.

پیشنهادهای مربوط به:

• Performance
• API Design
• Security
• Concurrency
• Documentation
• Developer Experience

نیز مورد استقبال هستند.

---

👨‍💻 توسعه‌دهنده

Abolfazl Zarei

Developer & Creator of CodeMeet Go SDK

CodeMeet Go SDK

Built with ❤️ and Go

© 2026 CodeMeet Go SDK

---

🚀 Build Fast. Scale Further. Code with Go.