docs: add migration guide from paultyng/go-unifi

docs/migrating_from_upstream.md

@@ -0,0 +1,96 @@
+# Migrating from `paultyng/go-unifi`
+
+This guide will help you migrate from `paultyng/go-unifi` to `filipowm/go-unifi`. The main differences are in how the client is initialized, while all client methods remain the same, with additional methods covering of the UniFi Controller API.
+
+## Client Initialization Changes
+
+### paultyng/go-unifi Style
+
+In the upstream library, client initialization typically looks like this:
+
+```go
+client := unifi.Client{}
+client.SetBaseURL("https://unifi.localdomain")
+
+// Optional: Configure TLS
+if skipTLSVerify {
+    httpClient := &http.Client{
+        Transport: &http.Transport{
+            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
+        },
+    }
+    jar, _ := cookiejar.New(nil)
+    httpClient.Jar = jar
+    client.SetHTTPClient(httpClient)
+}
+
+// Login is required
+err := client.Login(ctx, username, password)
+if err != nil {
+    return nil, err
+}
+```
+
+### filipowm/go-unifi Style
+
+The new library provides a more structured and configurable approach:
+
+```go
+// Using API Key (recommended, requires UniFi Controller 9.0.108+)
+client, err := unifi.NewClient(&unifi.ClientConfig{
+    BaseURL: "https://unifi.localdomain",
+    APIKey:  "your-api-key",
+})
+
+// OR using username/password
+client, err := unifi.NewClient(&unifi.ClientConfig{
+    BaseURL:  "https://unifi.localdomain",
+    Username: "your-username",
+    Password: "your-password",
+})
+
+if err != nil {
+    log.Fatalf("Failed to create client: %v", err)
+}
+```
+
+## Key Differences
+
+1. **Client Creation**:
+   - Old: Manual client creation and configuration using setters. Client used is a struct.
+   - New: Builder pattern with `NewClient` function and `ClientConfig` struct. Client used is an [interface](../unifi/client.generated.go).
+
+2. **Authentication**:
+   - Old: Only username/password authentication with explicit `Login()` call
+   - New: Supports both API Key (recommended) and username/password authentication
+   - New: Login is handled automatically during client creation
+
+3. **HTTP Client Configuration**:
+   - Old: Manual HTTP client configuration with `SetHTTPClient` and manual creation of `http.Client` and `cookiejar.Jar`
+   - New: Built-in configuration options through `ClientConfig`:
+     - `HttpTransportCustomizer` for transport-level customization
+     - `HttpRoundTripperProvider` for complete HTTP client control
+
+5. **Additional Features in filipowm/go-unifi**:
+   - Validation modes (Soft, Hard, Disabled)
+   - Request/Response interceptors
+   - Custom error handling
+   - Comprehensive configuration options
+
+## Migration Steps
+
+1. Replace the import from `github.com/paultyng/go-unifi` to `github.com/filipowm/go-unifi`
+2. Replace manual client creation with `NewClient` and appropriate `ClientConfig`
+3. If using TLS skip verification, use the `VerifySSL` option in `ClientConfig`:
+   ```go
+   client, err := unifi.NewClient(&unifi.ClientConfig{
+       BaseURL: "https://unifi.localdomain",
+       APIKey:  "your-api-key",
+       VerifySSL: false,
+   })
+   ```
+4. Remove explicit `Login()` calls as they are now handled automatically, unless you use [bare client initialization](./getting_started.md#BareClientInitialization)
+
+The rest of your code using the client methods should continue to work as before, as the API methods remain the same.
+
+For details on configuring client, check [client configuration](./configuration.md).

docs/readme.md

@@ -6,10 +6,11 @@ leveraging auto-generated models and manual enhancements for undocumented endpoi
 
 ## Table of Contents
 
-- [Overview](readme)
+- [Overview](readme.md)
 - [Getting Started](getting_started.md)
 - [Client Configuration](configuration.md)
 - [Usage Examples](usage_examples.md)
+- [Migrating from paultyng/go-unifi](migrating_from_upstream.md)
 - [Advanced Topics](advanced_topics.md)
 
 Each section is designed to help you understand and effectively utilize the UniFi client in your Go projects.