securelink

type Config struct {
	SigningKey    string            // Secret key for JWT signing (length validated based on algorithm)
	Expiration    time.Duration     // Token lifetime (e.g., 1*time.Hour, 30*time.Minute)
	BaseURL       string            // Base URL for generated links (e.g., "https://api.example.com")
	QueryKey      string            // Query parameter name when AsQuery=true (e.g., "token", "auth")
	Routes        map[string]string // Map of route names to URL paths (e.g., {"reset": "/auth/reset"})
	AsQuery       bool              // false=path URLs (/path/{token}), true=query URLs (/path?key={token})
	SigningMethod jwt.SigningMethod // JWT algorithm (HS256, HS384, HS512). Defaults to HS256 if nil
}

type Configurator interface {
	GetSigningKey() string        // The secret key used for JWT signing (min 32 bytes for HS256)
	GetExpiration() time.Duration // How long tokens remain valid
	GetBaseURL() string           // Base URL for generated links
	GetQueryKey() string          // Query parameter name when GetAsQuery() is true
	GetRoutes() map[string]string // Map of route names to URL paths
	GetAsQuery() bool             // Whether to embed token as query param (true) or path segment (false)
}

type Manager interface {
	// Generate creates a secure link for the specified route with optional payload data.
	// Multiple payloads can be provided and will be merged (later payloads override earlier ones).
	//
	// Parameters:
	//   route: Must match a key in the Routes configuration map
	//   payloads: Zero or more Payload maps to embed in the token
	//
	// Returns:
	//   string: Complete URL with embedded token
	//   error: Configuration errors, unknown routes, or token generation failures
	//
	// Example:
	//   payload := securelink.Payload{"user_id": "123"}
	//   link, err := manager.Generate("activate", payload)
	//   // Returns: "https://example.com/activate/eyJhbGciOi..."
	Generate(route string, payloads ...Payload) (string, error)

	// Validate verifies a JWT token and returns the embedded payload data.
	// Validates signature, expiration, and token structure.
	//
	// Parameters:
	//   token: JWT token string to validate
	//
	// Returns:
	//   map[string]any: Payload data that was embedded in the token
	//   error: Invalid signature, expired token, or malformed token
	//
	// Example:
	//   payload, err := manager.Validate("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
	//   if err == nil {
	//       userID := payload["user_id"].(string)
	//   }
	Validate(token string) (map[string]any, error)

	// GetAndValidate extracts a token using the provided function and validates it.
	// This is a convenience method for web handlers that need to extract tokens
	// from HTTP requests.
	//
	// Parameters:
	//   fn: Function that extracts the token (e.g., from query params, headers, etc.)
	//
	// Returns:
	//   Payload: Validated payload data from the token
	//   error: Token extraction, validation, or parsing errors
	//
	// Example:
	//   payload, err := manager.GetAndValidate(func(key string) string {
	//       return r.URL.Query().Get(key) // Extract from HTTP query params
	//   })
	GetAndValidate(fn func(string) string) (Payload, error)

	// GetExpiration returns the token lifetime configured for this manager.
	// This can be useful for displaying expiration information to users.
	//
	// Returns:
	//   time.Duration: How long tokens remain valid
	GetExpiration() time.Duration
}

type Payload map[string]any