imap/client/docs.go

// Copyright (c) 2025 H0llyW00dzZ All rights reserved.
//
// By accessing or using this software, you agree to be bound by the terms
// of the License Agreement, which you can find at LICENSE files.

// Package client provides a simple interface to manage IMAP connections
// for single or multiple users. It allows you to connect to an IMAP server,
// list messages, export messages, manage multiple user accounts, and list available mailboxes.
//
// # Features
//   - Connect and disconnect from an IMAP server
//   - List messages in a specified mailbox
//   - Export messages to various formats
//   - Manage multiple users with separate IMAP clients
//   - List all available mailboxes
//
// # Usage
//
// Single User Example:
//
//	package main
//
//	import (
//	    "fmt"
//	    "log"
//
//	    "git.b0zal.io/H0llyW00dzZ/imap/client"
//	)
//
//	func main() {
//	    config := &client.Config{
//	        Username:           "user@example.com",
//	        Password:           "password",
//	        Server:             "imap.example.com:993",
//	        InsecureSkipVerify: true,
//	    }
//
//	    imapClient := client.NewIMAP(config)
//
//	    err := imapClient.Connect()
//	    if err != nil {
//	        log.Fatalf("Failed to connect: %v", err)
//	    }
//	    defer imapClient.Disconnect()
//
//	    messageConfig := client.MessageConfig{
//	        GrabID:      true,
//	        GrabFrom:    true,
//	        GrabSubject: true,
//	        GrabBody:    true,
//	    }
//
//	    messages, err := imapClient.ListMessages("INBOX", 10, messageConfig)
//	    if err != nil {
//	        log.Fatalf("Failed to list messages: %v", err)
//	    }
//
//	    for _, msg := range messages {
//	        fmt.Printf("ID: %s, From: %v, Subject: %s, Body: %s\n", msg[client.KeyID], msg[client.KeyFrom], msg[client.KeySubject], msg[client.KeyBody])
//	    }
//	}
//
// List All Available Mailboxes Example:
//
//	package main
//
//	import (
//	    "fmt"
//	    "log"
//
//	    "git.b0zal.io/H0llyW00dzZ/imap/client"
//	)
//
//	func main() {
//	    config := &client.Config{
//	        Username:           "user@example.com",
//	        Password:           "password",
//	        Server:             "imap.example.com:993",
//	        InsecureSkipVerify: true,
//	    }
//
//	    imapClient := client.NewIMAP(config)
//
//	    err := imapClient.Connect()
//	    if err != nil {
//	        log.Fatalf("Failed to connect: %v", err)
//	    }
//	    defer imapClient.Disconnect()
//
//	    mailboxes, err := imapClient.ListMailboxes()
//	    if err != nil {
//	        log.Fatalf("Failed to list mailboxes: %v", err)
//	    }
//	    fmt.Println("Mailboxes:", mailboxes)
//	}
//
// Multiple Users Example:
//
//	package main
//
//	import (
//	    "fmt"
//	    "log"
//
//	    "git.b0zal.io/H0llyW00dzZ/imap/client"
//	)
//
//	func main() {
//	    multiUserIMAP := client.NewMultiUserIMAP()
//
//	    multiUserIMAP.AddUser("user1@example.com", "password1", "imap.example.com:993", true)
//	    multiUserIMAP.AddUser("user2@example.com", "password2", "imap.example.com:993", true)
//
//	    err := multiUserIMAP.ConnectUser("user1@example.com")
//	    if err != nil {
//	        log.Fatalf("Failed to connect user1: %v", err)
//	    }
//	    defer multiUserIMAP.DisconnectUser("user1@example.com")
//
//	    messageConfig := client.MessageConfig{
//	        GrabID:      true,
//	        GrabFrom:    true,
//	        GrabSubject: true,
//	        GrabBody:    true,
//	    }
//
//	    messages, err := multiUserIMAP.ListUserMessages("user1@example.com", "INBOX", 10, messageConfig)
//	    if err != nil {
//	        log.Fatalf("Failed to list messages for user1: %v", err)
//	    }
//
//	    for _, msg := range messages {
//	        fmt.Printf("ID: %s, From: %v, Subject: %s, Body: %s\n", msg[client.KeyID], msg[client.KeyFrom], msg[client.KeySubject], msg[client.KeyBody])
//	    }
//	}
//
// Export Messages Example:
//
//	package main
//
//	import (
//	    "log"
//	    "os"
//
//	    "git.b0zal.io/H0llyW00dzZ/imap/client"
//	    "git.b0zal.io/H0llyW00dzZ/imap/export"
//	)
//
//	func main() {
//	    config := &client.Config{
//	        Username:           "user@example.com",
//	        Password:           "password",
//	        Server:             "imap.example.com:993",
//	        InsecureSkipVerify: true,
//	    }
//
//	    imapClient := client.NewIMAP(config)
//
//	    err := imapClient.Connect()
//	    if err != nil {
//	        log.Fatalf("Failed to connect: %v", err)
//	    }
//	    defer imapClient.Disconnect()
//
//	    messageConfig := client.MessageConfig{
//	        GrabID:      true,
//	        GrabFrom:    true,
//	        GrabSubject: true,
//	        GrabBody:    true,
//	    }
//
//	    file, err := os.Create("messages.json")
//	    if err != nil {
//	        log.Fatalf("Failed to create file: %v", err)
//	    }
//	    defer file.Close()
//
//	    exporter := &export.JSONExporter{Encoder: export.DefaultJSONEncoder}
//	    err = imapClient.ExportMessagesTo(file, exporter, "INBOX", 10, messageConfig)
//	    if err != nil {
//	        log.Fatalf("Failed to export messages: %v", err)
//	    }
//	}
package client