A Go client library for interacting with the Mate API, providing comprehensive access to session management, team operations, and real-time WebSocket communication.
- REST API Client: Complete access to all Mate API endpoints, including User, Team, Agent, Session, and Browser services.
- WebSocket Support: Real-time session communication and control with detailed message handling for starting, stopping, sending input, pausing, resuming, and pinging sessions.
- Session Management: High-level session lifecycle management, including creation, retrieval, message fetching, and name updates.
- Authentication: Secure API key-based authentication for all API interactions.
- Configuration: Flexible configuration options with YAML file support for easy setup and management.
- Error Handling: Comprehensive error handling with custom
APIErrortypes and detailed error codes for robust application development. - Retry Logic: Built-in retry mechanism with exponential backoff for resilient API calls.
- Logging: Configurable request/response logging to aid in debugging and monitoring.
- Input Validation: Robust input validation for all API requests to ensure data integrity.
- Concurrency: Leverages Go's built-in concurrency features for efficient API performance.
The current version of the Mate SDK Go can be accessed through the mate.Version constant:
package main
import (
"fmt"
mate "github.com/matego/mate-sdk-go"
)
func main() {
fmt.Printf("Mate SDK Go Version: %s\n", mate.Version)
}go get github.com/matego/mate-sdk-gopackage main
import (
"context"
"fmt"
"log"
mate "github.com/matego/mate-sdk-go"
)
func main() {
// Create client with API key
client, err := mate.NewClient(&mate.ClientOptions{
APIKey: "your-api-key",
BaseURL: "https://api.mate.wyseos.com", // Replace with your Mate API base URL
})
if err != nil {
log.Fatal(err)
}
// Get list of teams
ctx := context.Background()
teams, err := client.Team.GetList(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Found %d teams\n", len(teams))
// Example: Get info for a specific team (replace with an actual team ID)
if len(teams) > 0 {
teamInfo, err := client.Team.GetInfo(ctx, teams[0].ID)
if err != nil {
log.Printf("Error getting team info: %v\n", err)
} else {
fmt.Printf("Team Info: Name: %s, ID: %s\n", teamInfo.Name, teamInfo.ID)
}
}
}package main
import (
"context"
"fmt"
"log"
"time"
mate "github.com/matego/mate-sdk-go"
)
func main() {
// Create client with API key
client, err := mate.NewClient(&mate.ClientOptions{
APIKey: "your-api-key",
BaseURL: "https://api.mate.wyseos.com", // Replace with your Mate API base URL
})
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
// Create a session
createSessionReq := &mate.CreateSessionRequest{
TeamID: "your-team-id", // Replace with an actual team ID
AgentID: "your-agent-id", // Replace with an actual agent ID
}
session, err := client.Session.Create(ctx, createSessionReq)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created session: %s\n", session.ID)
// Connect to WebSocket
ws, err := client.Session.ConnectWebSocket(ctx, session.ID)
if err != nil {
log.Fatal(err)
}
defer ws.Close()
fmt.Println("WebSocket connected.")
// Start the session in a goroutine
go func() {
err := ws.Start(ctx)
if err != nil {
log.Printf("WebSocket start error: %v\n", err)
}
}()
// Send input after a short delay to allow session to start
time.Sleep(2 * time.Second)
input := "Hello, how can you help me today?"
err = ws.SendInput(ctx, input)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Sent input: %s\n", input)
// Listen for messages in a separate goroutine
messageChan := ws.Messages()
done := make(chan struct{})
go func() {
for msg := range messageChan {
fmt.Printf("Received message (Type: %s, Source: %s): %s\n", msg.Type, msg.Source, msg.Content)
// Example of handling different message types
switch msg.Type {
case "text":
// Process text messages
case "plan":
// Handle AI generated plans
case "error":
fmt.Printf("Received error from WebSocket: %s\n", msg.Error)
}
}
close(done)
}()
// Keep the main goroutine alive to receive messages, or implement a stopping mechanism
// For demonstration, we'll wait for a few seconds and then stop
time.Sleep(10 * time.Second)
fmt.Println("Stopping WebSocket session.")
err = ws.Stop(ctx)
if err != nil {
log.Printf("Error stopping WebSocket: %v\n", err)
}
<-done // Wait for message listener to finish
fmt.Println("WebSocket session stopped gracefully.")
}Create a mate.yaml configuration file at the root of your project or in a standard configuration path:
api_key: "your-api-key" # Replace with your actual API key
base_url: "https://api.mate.wyseos.com" # Replace with your Mate API base URL
timeout: 30s
retry:
max_attempts: 3
initial_delay: 1s
logging:
enabled: true
level: "info" # Options: "debug", "info", "warn", "error"Then load it in your Go application:
package main
import (
"fmt"
"log"
mate "github.com/matego/mate-sdk-go"
)
func main() {
// Load client from config file
client, err := mate.NewClientFromConfig("mate.yaml")
if err != nil {
log.Fatal(err)
}
fmt.Println("Client loaded from config file successfully!")
// You can now use the client for API calls as shown in "Basic Usage"
}The SDK provides client services for various Mate API functionalities:
Client.User: Manages API keys and retrieves call records.CreateAPIKey,DeleteAPIKey,ListAPIKeysGetFilterValues,GetCallList
Client.Team: Provides operations for managing teams.GetList,GetInfo,CreateTeam,UpdateTeam
Client.Agent: Offers functionalities related to agents.GetList,GetInfo
Client.Session: Handles session creation, retrieval, and message management.Create,GetInfo,GetCurrent,GetMessages,GetBetweenMessages,ListSessions,UpdateSessionName
Client.Browser: Manages browser information and operations.GetInfo,ListBrowsers,ReleaseBrowser,ListBrowserPages
The SessionWebSocket object, obtained via Client.Session.ConnectWebSocket, provides real-time interaction capabilities:
ws.Start(ctx): Initiates the session.ws.Stop(ctx): Terminates the session.ws.SendInput(ctx, input): Sends user input (text, plan responses) to the session.ws.Pause(ctx): Pauses the current session execution.ws.Resume(ctx): Resumes a paused session.ws.Ping(ctx): Sends a ping message to keep the connection alive.ws.Messages(): Returns a channel to receive incoming messages from the WebSocket.ws.Close(): Closes the WebSocket connection and cleans up resources.
The SDK provides comprehensive error handling through the *mate.APIError type:
teams, err := client.Team.GetList(ctx)
if err != nil {
if apiErr, ok := err.(*mate.APIError); ok {
fmt.Printf("API Error: %s (Code: %d, Message: %s, Details: %v)\n", apiErr.Error(), apiErr.Code, apiErr.Message, apiErr.Details)
} else {
fmt.Printf("Network or unexpected error: %s\n", err)
}
}The APIError type includes Code, Message, and Details fields for precise error identification.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
For support and questions, please open an issue on GitHub.