Referensi Subistem & Konstanta
leaves-guardian memiliki arsitektur modular yang tersusun dari mesin keandalan terarah, utilitas developer, dan pengendali infrastruktur. Dokumen ini berfungsi sebagai peta referensi API sentral yang memetakan jalur akses subistem publik pada LeavesClient, konstruktor utilitas mandiri, fungsi pembantu (helpers), serta katalog lengkap tanpa pemotongan (...) dari seluruh konstanta publik, enum, status lifecycle, dan opsi konfigurasi default.
1. Peta Akses Subistem & Arsitektur
leaves-guardian mengorganisir komponen internal dan eksternal ke dalam tiga klasifikasi fungsional:
graph TD
subgraph ClientAttached [1. Client-Attached Subsystems]
C[LeavesClient]
C -->|client.terminal| T[LeavesTerminal]
C -->|client.store| S[SmartStore]
C -->|client.recovery| R[SessionRecovery]
C -->|client.health| H[HealthMonitor]
C -->|client.watchdog| W[Watchdog]
C -->|client.memoryGuard| M[MemoryGuard]
C -->|client.traffic| TC[TrafficController]
C -->|client.media| MP[MediaPipeline]
C -->|client.rateLimiter| RL[IngressRateLimiter]
C -->|client.deduplicator| DD[IngressDeduplicator]
C -->|client.autoDelete| AD[AutoDeleteManager]
end
subgraph OnDemand [2. On-Demand Utilities & Helpers]
MC[MessageCollector]
PR[Prompt]
PG[Paginator]
EM[EphemeralMessage]
HLP[Helpers: withAdReply, withChannelForward, resolveMedia, generateStatCard]
end
subgraph InternalInfra [3. Internal Runtime Infrastructure]
CM[ConnectionManager]
SM[SessionManager]
RM[ReconnectManager]
EMG[EventManager]
TM[TerminalManager]
PA[PresentationAdapter]
LA[LoggerAdapter]
endTabel Properti Akses Langsung pada LeavesClient
Tabel berikut merangkum seluruh pengakses subistem publik yang terpasang langsung pada instance LeavesClient:
Properti pada client | Instance Kelas | Fungsi Utama | Method Publik Utama |
|---|---|---|---|
client.terminal | LeavesTerminal | Logging terminal semantik & output konsol sadar privasi. | info(), success(), warn(), error(), debug(), mask() |
client.store | SmartStore | Penyimpanan state JSON & key-value in-memory atomik dengan TTL. | get(), set(), delete(), has(), keys(), clear(), sweep(), namespace() |
client.recovery | SessionRecovery | Verifikasi integritas sesi otomatis & pemulihan snapshot disk. | checkSessionHealth(), createSnapshot(), restoreLatestValidSnapshot(), quarantineCurrentSession(), cleanEligibleAuthFiles(), clearBackups() |
client.health | HealthMonitor | Diagnostik observabilitas, lag event loop, dan pemantauan memori. | start(), stop(), pause(), resume(), getStatus(), getMetrics(), getHistory(), registerProbe() |
client.watchdog | Watchdog | Verifikasi keaktifan socket & terminasi koneksi zombie. | start(), stop(), pause(), resume(), ping(), recordActivity(), getStatus() |
client.memoryGuard | MemoryGuard | Observasi memori proses & mitigasi heap bertahap. | start(), stop(), pause(), resume(), getStatus(), getMetrics(), getHistory(), registerMitigationHook() |
client.traffic | TrafficController | Antrean keluar prioritas, keadilan FIFO, backpressure & pacing. | enqueue(), cancelTask(), pause(), resume(), drain(), getStats(), getQueueStatus(), getHistory() |
client.media | MediaPipeline | Preparasi media, proteksi SSRF, validasi MIME & spill file sementara. | prepare(), abortJob(), abortAllJobs(), getStats(), cleanupTempDir() |
client.rateLimiter | IngressRateLimiter | Pembatasan laju pesan masuk dengan pelacak sliding window. | consume(), check(), resetKey(), resetAll(), getStats() |
client.deduplicator | IngressDeduplicator | Deteksi pesan masuk duplikat & penekanan duplikasi via cache. | isDuplicate(), register(), checkAndRegister(), clear(), getStats() |
client.autoDelete | AutoDeleteManager | Penghapusan pesan terjadwal dengan prinsip zero-rollback safety. | register(), cancel(), cancelAll(), getTask(), getStats() |
2. Utilitas On-Demand & Fungsi Pembantu (Helpers)
2.1 Kelas Utilitas Interaktif On-Demand
Kelas-kelas ini di-instantiate per alur interaksi dan beroperasi di atas objek pesan ternormalisasi (Message):
import {
MessageCollector,
Prompt,
Paginator,
EphemeralMessage
} from 'leaves-guardian';| Kelas | Signature Konstruktor | Deskripsi |
|---|---|---|
MessageCollector | new MessageCollector(client, options) | Mengumpulkan pesan masuk yang memenuhi kriteria filter tertentu dalam batas waktu/jumlah terkonfigurasi. |
Prompt | new Prompt(client, options) | Memandu pengguna melalui wizard interaktif tanya-jawab satu langkah maupun multi-langkah. |
Paginator | new Paginator(client, options) | Merender daftar multi-halaman, katalog, atau menu dengan kontrol navigasi interaktif. |
EphemeralMessage | new EphemeralMessage(client, options) | Mengonfigurasi dan mengirim pesan sementara yang hilang otomatis (disappearing messages). |
2.2 Fungsi Pembantu Standalone (Helpers)
import {
withAdReply,
withChannelForward,
resolveMedia,
generateStatCard
} from 'leaves-guardian';| Fungsi | Signature | Tipe Kembalian | Deskripsi |
|---|---|---|---|
withAdReply | (contextInfo: object, options: object) | object | Menyisipkan metadata pratinjau tautan interaktif / ad reply ke contextInfo Baileys. |
withChannelForward | (contextInfo: object, options: object) | object | Menyisipkan metadata header terusan saluran resmi / newsletter ke contextInfo. |
resolveMedia | async (client: object, source: any, type: string, opts?: object) | Promise<any> | Menyelesaikan buffer media, URL remote, atau path file lokal untuk pengiriman Baileys. |
generateStatCard | (stats: object, options?: object) | string | Memformat widget ringkasan dashboard ASCII untuk penyajian metrik/kesehatan bot. |
3. Infrastruktur Runtime Internal
Subistem berikut di-instantiate dan dikelola secara internal oleh LeavesClient. Komponen ini tidak dimaksudkan untuk di-instantiate manual oleh konsumen, namun perilakunya dapat dikonfigurasi melalui opsi konstruktor LeavesClient:
ConnectionManager: Mengelola pembuatan socket aktif Baileys, relai event, dan koordinasi kode QR/Pairing.SessionManager: Menangani persistensi state autentikasi multi-file, pembuatan folder sesi, dan validasi creds.ReconnectManager: Mengelola penjadwalan rekoneksi otomatis berbasis exponential backoff dengan jitter.EventManager: Mengoordinasikan langganan event emitter internal dan perutean event ternormalisasi.TerminalManager: Bus event sentral untuk logging diagnostik, multipleksing sink, dan sanitasi privasi.PresentationAdapter: Menjembatani event domainLeavesClientmenjadi log presentasi terminal yang semantik.LoggerAdapter: Mengadaptasi stream logger standar Pino ke dalamLeavesTerminal.
4. Kamus Sentral Konstanta & Enum Publik
Berikut adalah katalog lengkap dan pasti dari seluruh konstanta publik, enum, set state, kode error, dan objek opsi konfigurasi default yang diekspor oleh leaves-guardian.
4.1 Client & Koneksi
CLIENT_STATES
export const CLIENT_STATES = Object.freeze({
IDLE: 'IDLE',
INITIALIZING: 'INITIALIZING',
AUTHENTICATING: 'AUTHENTICATING',
CONNECTING: 'CONNECTING',
OPEN: 'OPEN',
READY: 'READY',
DISCONNECTED: 'DISCONNECTED',
RECONNECTING: 'RECONNECTING',
LOGGED_OUT: 'LOGGED_OUT',
SHUTDOWN: 'SHUTDOWN'
});RECONNECT_REASONS
export const RECONNECT_REASONS = Object.freeze({
NETWORK_ERROR: 'NETWORK_ERROR',
SERVER_UNAVAILABLE: 'SERVER_UNAVAILABLE',
CONNECTION_CLOSED: 'CONNECTION_CLOSED',
CONFLICT: 'CONFLICT',
UNKNOWN_TRANSIENT: 'UNKNOWN_TRANSIENT'
});4.2 Normalisasi & Abstraksi Pesan
MessageTypes
export const MessageTypes = Object.freeze({
TEXT: 'text',
IMAGE: 'image',
VIDEO: 'video',
AUDIO: 'audio',
DOCUMENT: 'document',
STICKER: 'sticker',
LOCATION: 'location',
CONTACT: 'contact',
REACTION: 'reaction',
POLL: 'poll',
BUTTON: 'button',
LIST: 'list',
UNKNOWN: 'unknown'
});4.3 SmartStore & Session Recovery
CURRENT_STORE_VERSION
export const CURRENT_STORE_VERSION = 1;SESSION_STATUS
export const SESSION_STATUS = Object.freeze({
FRESH_SESSION: 'FRESH_SESSION',
HEALTHY: 'HEALTHY',
CORRUPTED_ZERO_BYTE: 'CORRUPTED_ZERO_BYTE',
CORRUPTED_SYNTAX_ERROR: 'CORRUPTED_SYNTAX_ERROR',
CORRUPTED_SCHEMA_INVALID: 'CORRUPTED_SCHEMA_INVALID'
});SESSION_RECOVERY_CODES
export const SESSION_RECOVERY_CODES = Object.freeze({
SESSION_CORRUPTED: 'SESSION_CORRUPTED',
SNAPSHOT_CREATION_FAILED: 'SNAPSHOT_CREATION_FAILED',
SNAPSHOT_INCONSISTENT: 'SNAPSHOT_INCONSISTENT',
SNAPSHOT_CORRUPTED: 'SNAPSHOT_CORRUPTED',
SESSION_UNRECOVERABLE: 'SESSION_UNRECOVERABLE',
RESTORE_FAILED: 'RESTORE_FAILED',
RESTORE_ACTIVATION_FAILED: 'RESTORE_ACTIVATION_FAILED',
RECOVERY_BLOCKED_401: 'RECOVERY_BLOCKED_401',
RECOVERY_BUSY: 'RECOVERY_BUSY',
INVALID_PARAMETER: 'INVALID_PARAMETER'
});4.4 Health Monitor & Diagnostik
HEALTH_STATUS
export const HEALTH_STATUS = Object.freeze({
HEALTHY: 'HEALTHY',
DEGRADED: 'DEGRADED',
CRITICAL: 'CRITICAL'
});PROBE_STATUS
export const PROBE_STATUS = Object.freeze({
OK: 'OK',
ERROR: 'ERROR',
TIMEOUT: 'TIMEOUT'
});MONITOR_STATE
export const MONITOR_STATE = Object.freeze({
STOPPED: 'STOPPED',
RUNNING: 'RUNNING'
});HEALTH_ERROR_CODES
export const HEALTH_ERROR_CODES = Object.freeze({
HEALTH_INVALID_THRESHOLD: 'HEALTH_INVALID_THRESHOLD',
HEALTH_INVALID_OPTION: 'HEALTH_INVALID_OPTION',
HEALTH_PROBE_ERROR: 'HEALTH_PROBE_ERROR'
});DEFAULT_THRESHOLDS
export const DEFAULT_THRESHOLDS = Object.freeze({
eventLoopLagDegradedMs: 250,
eventLoopLagCriticalMs: 1000,
memoryHeapPercentDegraded: 80,
memoryHeapPercentCritical: 95,
disconnectedDurationDegradedMs: 15000,
disconnectedDurationCriticalMs: 60000
});4.5 Socket Watchdog & Memory Guard
WATCHDOG_STATE
export const WATCHDOG_STATE = Object.freeze({
STOPPED: 'STOPPED',
RUNNING: 'RUNNING',
PAUSED: 'PAUSED',
TERMINATING: 'TERMINATING'
});WATCHDOG_ERROR_CODES
export const WATCHDOG_ERROR_CODES = Object.freeze({
WATCHDOG_INVALID_OPTION: 'WATCHDOG_INVALID_OPTION',
WATCHDOG_SOCKET_ERROR: 'WATCHDOG_SOCKET_ERROR'
});DEFAULT_WATCHDOG_OPTIONS
export const DEFAULT_WATCHDOG_OPTIONS = Object.freeze({
enabled: true,
checkIntervalMs: 15000,
maxSilenceMs: 60000,
pingTimeoutMs: 10000,
maxMissedPings: 2
});MEMORY_GUARD_STATE
export const MEMORY_GUARD_STATE = Object.freeze({
STOPPED: 'STOPPED',
RUNNING: 'RUNNING',
PAUSED: 'PAUSED'
});MEMORY_GUARD_LEVEL
export const MEMORY_GUARD_LEVEL = Object.freeze({
NORMAL: 'NORMAL',
WARNING: 'WARNING',
CRITICAL: 'CRITICAL'
});MEMORY_ERROR_CODES
export const MEMORY_ERROR_CODES = Object.freeze({
MEMORY_INVALID_OPTION: 'MEMORY_INVALID_OPTION',
MEMORY_INVALID_THRESHOLD: 'MEMORY_INVALID_THRESHOLD',
MEMORY_HOOK_ERROR: 'MEMORY_HOOK_ERROR'
});DEFAULT_MEMORY_GUARD_OPTIONS
export const DEFAULT_MEMORY_GUARD_OPTIONS = Object.freeze({
enabled: true,
checkIntervalMs: 30000,
heapWarningBytes: 157286400, // 150 MB
heapCriticalBytes: 314572800, // 300 MB
rssWarningBytes: 262144000, // 250 MB
rssCriticalBytes: 524288000, // 500 MB
growthRateWarningPercent: 20,
minimumGrowthBytes: 20971520, // 20 MB
sampleWindowSize: 5,
autoMitigateOnCritical: true,
allowManualGc: false,
gcCooldownMs: 60000,
hookTimeoutMs: 5000
});DEFAULT_MEMORY_GUARD_STATUS
export const DEFAULT_MEMORY_GUARD_STATUS = Object.freeze({
state: 'STOPPED',
level: 'NORMAL',
timestamp: null,
heapUsed: null,
heapTotal: null,
heapRatio: null
});4.6 Traffic Controller & Ingress Controls
TRAFFIC_STATE
export const TRAFFIC_STATE = Object.freeze({
STOPPED: 'STOPPED',
RUNNING: 'RUNNING',
PAUSED: 'PAUSED'
});TRAFFIC_PRIORITY
export const TRAFFIC_PRIORITY = Object.freeze({
HIGH: 'HIGH',
NORMAL: 'NORMAL',
LOW: 'LOW'
});TRAFFIC_TASK_STATE
export const TRAFFIC_TASK_STATE = Object.freeze({
PENDING: 'PENDING',
DISPATCHING: 'DISPATCHING',
COMPLETED: 'COMPLETED',
FAILED: 'FAILED',
CANCELLED: 'CANCELLED'
});TRAFFIC_ERROR_CODES
export const TRAFFIC_ERROR_CODES = Object.freeze({
TRAFFIC_QUEUE_FULL: 'TRAFFIC_QUEUE_FULL',
TRAFFIC_TASK_CANCELLED: 'TRAFFIC_TASK_CANCELLED',
TRAFFIC_CONTROLLER_STOPPED: 'TRAFFIC_CONTROLLER_STOPPED',
TRAFFIC_INVALID_OPTION: 'TRAFFIC_INVALID_OPTION'
});DEFAULT_TRAFFIC_OPTIONS
export const DEFAULT_TRAFFIC_OPTIONS = Object.freeze({
maxQueueSize: 1000,
maxConcurrentDispatches: 1,
minDispatchIntervalMs: 250,
highWatermarkRatio: 0.8,
lowWatermarkRatio: 0.2,
maxConsecutiveHigh: 5,
historyLimit: 100
});LIMITER_STATE
export const LIMITER_STATE = Object.freeze({
RUNNING: 'RUNNING',
STOPPED: 'STOPPED',
DESTROYED: 'DESTROYED'
});RATE_LIMIT_ERROR_CODES
export const RATE_LIMIT_ERROR_CODES = Object.freeze({
INVALID_OPTION: 'RATE_LIMIT_INVALID_OPTION',
INTERNAL_ERROR: 'RATE_LIMIT_ERROR'
});DEFAULT_RATE_LIMITER_OPTIONS
export const DEFAULT_RATE_LIMITER_OPTIONS = Object.freeze({
windowMs: 60000, // 60 detik
maxRequests: 60, // 60 request per window
penaltyDurationMs: 0, // 0 = Nonaktif
maxTrackedKeys: 10000, // Maksimal 10.000 key terpantau
cleanupIntervalMs: 60000, // Interval pembersihan 60 detik
keyExtractor: defaultKeyExtractor,
clock: () => Date.now()
});DEDUP_STATE
export const DEDUP_STATE = Object.freeze({
RUNNING: 'RUNNING',
STOPPED: 'STOPPED',
DESTROYED: 'DESTROYED'
});DEDUP_ERROR_CODES
export const DEDUP_ERROR_CODES = Object.freeze({
INVALID_OPTION: 'DEDUP_INVALID_OPTION',
INVALID_KEY: 'DEDUP_INVALID_KEY',
INTERNAL_ERROR: 'DEDUP_ERROR'
});DEFAULT_DEDUPLICATOR_OPTIONS
export const DEFAULT_DEDUPLICATOR_OPTIONS = Object.freeze({
ttlMs: 300000, // 5 menit fixed TTL
maxTrackedMessages: 10000, // Maksimal 10.000 pesan terpantau
cleanupIntervalMs: 60000, // Interval pembersihan 60 detik
keyExtractor: defaultIdentityExtractor,
clock: () => Date.now()
});4.7 Media Pipeline
MEDIA_TYPE
export const MEDIA_TYPE = Object.freeze({
IMAGE: 'image',
VIDEO: 'video',
AUDIO: 'audio',
DOCUMENT: 'document',
STICKER: 'sticker'
});MEDIA_REPRESENTATION
export const MEDIA_REPRESENTATION = Object.freeze({
BUFFER: 'buffer',
STREAM: 'stream',
FILE: 'file'
});MEDIA_JOB_STATE
export const MEDIA_JOB_STATE = Object.freeze({
PENDING: 'PENDING',
RESOLVING: 'RESOLVING',
DETECTING: 'DETECTING',
VALIDATING: 'VALIDATING',
TRANSFORMING: 'TRANSFORMING',
FINALIZING: 'FINALIZING',
COMPLETED: 'COMPLETED',
FAILED: 'FAILED',
CANCELLED: 'CANCELLED'
});MEDIA_ERROR_CODES
export const MEDIA_ERROR_CODES = Object.freeze({
INVALID_SOURCE: 'MEDIA_INVALID_SOURCE',
SIZE_EXCEEDED: 'MEDIA_SIZE_EXCEEDED',
UNSUPPORTED_TYPE: 'MEDIA_UNSUPPORTED_TYPE',
FETCH_FAILED: 'MEDIA_FETCH_FAILED',
FETCH_TIMEOUT: 'MEDIA_FETCH_TIMEOUT',
SSRF_BLOCKED: 'MEDIA_SSRF_BLOCKED',
REDIRECT_LIMIT: 'MEDIA_REDIRECT_LIMIT',
TRANSFORM_FAILED: 'MEDIA_TRANSFORM_FAILED',
QUEUE_FULL: 'MEDIA_QUEUE_FULL',
PIPELINE_ABORTED: 'MEDIA_PIPELINE_ABORTED',
REPRESENTATION_UNAVAILABLE: 'MEDIA_REPRESENTATION_UNAVAILABLE',
RESOURCE_RELEASED: 'MEDIA_RESOURCE_RELEASED'
});DEFAULT_MEDIA_OPTIONS
export const DEFAULT_MEDIA_OPTIONS = Object.freeze({
maxInputBytes: 104857600, // 100 MB
maxOutputBytes: 104857600, // 100 MB
bufferThresholdBytes: 10485760, // 10 MB
fetchTimeoutMs: 30000, // 30 detik
maxRedirects: 5,
tempDir: path.join(os.tmpdir(), 'leaves-media'),
maxConcurrentJobs: 3,
maxWaitingJobs: 50,
allowPrivateIp: false
});4.8 Terminal Presentation
TERMINAL_LEVEL
export const TERMINAL_LEVEL = Object.freeze({
DEBUG: 'DEBUG',
INFO: 'INFO',
WARN: 'WARN',
ERROR: 'ERROR'
});LEVEL_WEIGHTS
export const LEVEL_WEIGHTS = Object.freeze({
DEBUG: 10,
INFO: 20,
WARN: 30,
ERROR: 40
});TERMINAL_DOMAIN
export const TERMINAL_DOMAIN = Object.freeze({
CLIENT: 'CLIENT',
MESSAGE: 'MESSAGE',
RELIABILITY: 'RELIABILITY',
TRAFFIC: 'TRAFFIC',
MEDIA: 'MEDIA',
APPLICATION: 'APPLICATION'
});TERMINAL_STATE
export const TERMINAL_STATE = Object.freeze({
RUNNING: 'RUNNING',
DESTROYED: 'DESTROYED'
});RENDERER_STATUS
export const RENDERER_STATUS = Object.freeze({
HEALTHY: 'HEALTHY',
DEGRADED: 'DEGRADED'
});TERMINAL_ERROR_CODES
export const TERMINAL_ERROR_CODES = Object.freeze({
INVALID_OPTION: 'TERMINAL_INVALID_OPTION',
INVALID_EVENT: 'TERMINAL_INVALID_EVENT',
RENDERER_ERROR: 'TERMINAL_RENDERER_ERROR',
INTERNAL_ERROR: 'TERMINAL_ERROR'
});DEFAULT_TERMINAL_OPTIONS
export const DEFAULT_TERMINAL_OPTIONS = Object.freeze({
enabled: true,
minLevel: 'INFO',
privacyMasking: true,
maxDispatchDepth: 3,
clock: () => Date.now()
});4.9 Utilitas Developer
COLLECTOR_END_REASONS
export const COLLECTOR_END_REASONS = Object.freeze({
LIMIT: 'limit',
TIME: 'time',
IDLE: 'idle',
USER: 'user',
CANCELED: 'canceled',
PROCESSED_LIMIT: 'processedLimit',
SHUTDOWN: 'clientShutdown'
});PROMPT_STATES
export const PROMPT_STATES = Object.freeze({
IDLE: 'IDLE',
RUNNING: 'RUNNING',
COMPLETED: 'COMPLETED',
CANCELLED: 'CANCELLED',
TIMEOUT: 'TIMEOUT',
MAX_RETRIES: 'MAX_RETRIES',
ERROR: 'ERROR',
SHUTDOWN: 'SHUTDOWN'
});PAGINATOR_STATES
export const PAGINATOR_STATES = Object.freeze({
IDLE: 'IDLE',
RUNNING: 'RUNNING',
STOPPED: 'STOPPED',
TIMEOUT: 'TIMEOUT',
SHUTDOWN: 'SHUTDOWN',
ERROR: 'ERROR'
});PAGINATOR_ACTIONS
export const PAGINATOR_ACTIONS = Object.freeze({
NEXT: 'NEXT',
PREV: 'PREV',
FIRST: 'FIRST',
LAST: 'LAST',
JUMP: 'JUMP',
STOP: 'STOP'
});EPHEMERAL_DURATIONS
export const EPHEMERAL_DURATIONS = Object.freeze({
ONE_DAY: 86400, // 24 Jam
ONE_WEEK: 604800, // 7 Hari
THREE_MONTHS: 7776000, // 90 Hari
DISABLED: 0 // Nonaktif
});DEFAULT_EPHEMERAL_DURATION
export const DEFAULT_EPHEMERAL_DURATION = 604800; // 7 HariAUTODELETE_STATES
export const AUTODELETE_STATES = Object.freeze({
PENDING: 'PENDING',
EXECUTING: 'EXECUTING',
COMPLETED: 'COMPLETED',
CANCELLED: 'CANCELLED',
FAILED: 'FAILED'
});