docs: add migration guide from paultyng/go-unifi

README.md

@@ -8,6 +8,8 @@
 This SDK provides a Go client for the UniFi Network Controller API. It is used primarily in the [Terraform provider for UniFi](https://github.com/filipowm/terraform-provider-unifi),
 but can be used independently for any Go project requiring UniFi Network Controller API integration.
 
+Check out the detailed [documentation](docs/readme.md) for more information.
+
 ## Features
 
 - Great UniFi Network Controller API coverage through automated code generation and manually added code for undocumented endpoints
@@ -37,6 +39,11 @@ go generate unifi/codegen.go
 **Note:** While the current code generation approach works, we're exploring better ways to extract API specifications. There is no official API specifications available, and the UniFi Controller JAR is obfuscated, making it
 challenging to directly use Java classes. Contributions and suggestions for improvements are welcome!
 
+## Migrating from `paultyng/go-unifi`
+
+If you already use `paultyng/go-unifi`, you can easily migrate to this SDK, because it is a fork and the SDK is fully compatible with the original one. 
+Check out the [migration guide](docs/migrating_from_upstream.md) for information on how to migrate from the upstream `paultyng/go-unifi` SDK.
+
 ## Usage
 
 Unifi client support both username/password and API Key authentication. It is recommended to use API Key authentication for better security,

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.