synapse

package module
v0.0.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2026 License: MIT Imports: 11 Imported by: 0

README

Synapse Go SDK

Client oficial em Go para a API Synapse.

Instalação

go get github.com/WonitTecnologia/synapse

Início rápido

import "github.com/WonitTecnologia/synapse"

client, err := synapse.NewClient("seu-token", nil)
if err != nil {
    log.Fatal(err)
}

Configuração

NewClient aceita um token obrigatório e um *Options opcional.

client, err := synapse.NewClient("seu-token", &synapse.Options{
    BaseURL: "https://staging.synapse.example.com", // padrão: https://synapse.wonit.net.br
    Timeout: 15 * time.Second,                      // padrão: 30s
})
Campo Tipo Descrição
BaseURL string Sobrescreve a URL base da API (staging, self-hosted…)
Timeout time.Duration Timeout por requisição HTTP. Padrão: 30s

Domínios

Campo Interface Endpoints cobertos
client.Auth AuthCase Login, logout, OTP, reset de senha, API tokens
client.User UserCase CRUD de usuários
client.Tenant TenantCase CRUD de tenants
client.Provider ProviderCase Listagem de providers do catálogo
client.Service ServiceCase Listagem de services do catálogo
client.Google GoogleCase Integração Google Vision AI (OCR)
client.OpenAI OpenAICase Chat, análise de imagem, transcrição de áudio
client.Chatvolt ChatvoltCase Query a agentes Chatvolt

Auth

Login
resp, err := client.Auth.Login(ctx, synapse.LoginRequest{
    Email:    "usuario@empresa.com",
    Password: "senha123",
})

fmt.Println(resp.Token)
fmt.Println(resp.User.Name)
Healthcheck (validar token)
resp, err := client.Auth.Healthcheck(ctx)
fmt.Println(resp.User.Email)
Logout
err := client.Auth.Logout(ctx, "token-a-revogar")
Solicitar OTP
err := client.Auth.RequestOTP(ctx, synapse.OTPRequest{
    Email: "usuario@empresa.com",
})
Resetar senha com OTP
err := client.Auth.ResetPassword(ctx, synapse.OTPResetPasswordRequest{
    Email:    "usuario@empresa.com",
    OTP:      "123456",
    Password: "novaSenha@123",
})
API Tokens
// Criar
token, err := client.Auth.CreateAPIToken(ctx, synapse.ApiTokenCreateRequest{
    Name:        "Integração CI",
    Description: "Token para pipeline de deploy",
    ExpireAt:    "2026-12-31T00:00:00Z", // opcional
})
fmt.Println(token.Token)

// Listar
list, err := client.Auth.ListAPITokens(ctx, 1, 20)
for _, t := range list.APITokens {
    fmt.Println(t.Name, t.ExpireAt)
}

User

// Buscar por UUID ou email
user, err := client.User.Get(ctx, "uuid-ou-email")

// Listar
users, err := client.User.List(ctx, synapse.ListUsersParams{
    Page:             1,
    Size:             20,
    TenantIdentifier: "uuid-do-tenant", // apenas SystemAdmin
})

// Criar  (identifier = UUID ou documento do tenant)
user, err := client.User.Create(ctx, "uuid-do-tenant", synapse.CreateUserRequestDto{
    Name:     "João Silva",
    Email:    "joao@empresa.com",
    Password: "senha@123",
    Role:     synapse.UserRoleTenantUser,
})

// Atualizar
user, err := client.User.Update(ctx, "uuid-do-usuario", synapse.UpdateUserRequestDto{
    Name: "João Silva Jr.",
})

// Deletar
err := client.User.Delete(ctx, "uuid-ou-email")
Roles disponíveis
Constante Valor
synapse.UserRoleSystemAdmin SYSTEM_ADMIN
synapse.UserRoleTenantAdmin TENANT_ADMIN
synapse.UserRoleTenantUser TENANT_USER

Tenant

// Buscar por UUID ou documento (CNPJ/CPF)
tenant, err := client.Tenant.Get(ctx, "uuid", "")
tenant, err := client.Tenant.Get(ctx, "", "12345678000199")

// Listar
tenants, err := client.Tenant.List(ctx, 1, 10)

// Criar
tenant, err := client.Tenant.Create(ctx, synapse.CreateTenantRequestDto{
    Name:     "Empresa XPTO",
    Document: "12345678000199",
})

// Atualizar
live := true
tenant, err := client.Tenant.Update(ctx, "uuid-do-tenant", synapse.UpdateTenantRequestDto{
    Name: "Empresa XPTO Ltda.",
    Live: &live,
})

// Deletar
err := client.Tenant.Delete(ctx, "uuid-do-tenant", "")

// Providers
provider, err := client.Provider.Get(ctx, "uuid-do-provider")
providers, err := client.Provider.List(ctx, 1, 20)

// Services
service, err := client.Service.Get(ctx, "uuid-do-service")
services, err := client.Service.List(ctx, 1, 20)

Google Vision AI

Configurar integração
err := client.Google.Configure(ctx, synapse.ConfigureGoogleRequest{
    Credentials: synapse.VisionAICredentialsDTO{Token: "sua-api-key-google"},
    IsActive:    true,
})
OCR (extração de texto)
imageBytes, _ := os.ReadFile("nota_fiscal.jpg")

result, err := client.Google.VisionOCR(ctx, "nota_fiscal.jpg", imageBytes)
fmt.Println(result.Response)

Formatos aceitos: png, jpg, jpeg, webp.

OpenAI

Configurar integração
err := client.OpenAI.Configure(ctx, synapse.ConfigureOpenAIRequest{
    Credentials: synapse.OpenAICredentialsDTO{Token: "sk-..."},
    Settings: synapse.OpenAISettingsDTO{
        Model:       synapse.OpenAIModelGPT4o,
        Temperature: 0.7,
    },
    IsActive: true,
})
Modelos disponíveis
Constante Modelo
synapse.OpenAIModelGPT4oMini gpt-4o-mini
synapse.OpenAIModelGPT4o gpt-4o
synapse.OpenAIModelGPT4_1 gpt-4.1
synapse.OpenAIModelGPT4_1Mini gpt-4.1-mini
synapse.OpenAIModelO4Mini o4-mini
Chat Completion
reply, err := client.OpenAI.Chat(ctx, synapse.ChatCompletionRequest{
    Prompt: "Resuma este contrato em 3 pontos.",
})
fmt.Println(reply.Response)
Análise de imagem
imageBytes, _ := os.ReadFile("diagrama.png")

result, err := client.OpenAI.AnalyzeImage(ctx, "diagrama.png", imageBytes, "Descreva o que está nesta imagem.")
fmt.Println(result.Response)
Transcrição de áudio
audioBytes, _ := os.ReadFile("reuniao.mp3")

result, err := client.OpenAI.TranscribeAudio(ctx, synapse.TranscribeAudioRequest{
    FileName: "reuniao.mp3",
    Content:  audioBytes,
    Model:    "whisper-1",    // whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe
    Language: "pt",           // opcional
    Prompt:   "",             // opcional: contexto para melhorar a transcrição
})
fmt.Println(result.Response)

Chatvolt

Configurar integração
err := client.Chatvolt.Configure(ctx, synapse.ConfigureChatvoltRequest{
    Credentials: synapse.ChatvoltCredentialsDTO{Token: "seu-token-chatvolt"},
    IsActive:    true,
})
Query a agente
// Nova conversa
resp, err := client.Chatvolt.Query(ctx, synapse.ChatvoltAgentQueryRequest{
    AgentID: "id-do-agente",
    Query:   "Qual o status do meu pedido #1234?",
})
fmt.Println(resp.Answer)
fmt.Println(resp.ConversationID) // guarde para continuar o contexto

// Continuar conversa existente
resp, err = client.Chatvolt.Query(ctx, synapse.ChatvoltAgentQueryRequest{
    AgentID:        "id-do-agente",
    ConversationID: resp.ConversationID,
    Query:          "E qual a previsão de entrega?",
})
Enviar dados de contato
resp, err := client.Chatvolt.Query(ctx, synapse.ChatvoltAgentQueryRequest{
    AgentID: "id-do-agente",
    Query:   "Preciso de suporte.",
    Contact: &synapse.ChatvoltContact{
        Email:     "cliente@email.com",
        FirstName: "Maria",
        LastName:  "Souza",
    },
})

Tratamento de erros

Verificar tipo de erro com sentinels

Use errors.Is para identificar a categoria do erro sem precisar inspecionar o payload:

resp, err := client.Auth.Login(ctx, req)
if err != nil {
    switch {
    case errors.Is(err, synapse.ErrUnauthorized):
        // 401 — credenciais inválidas ou token expirado
    case errors.Is(err, synapse.ErrForbidden):
        // 403 — sem permissão para este recurso
    case errors.Is(err, synapse.ErrNotFound):
        // 404 — recurso não encontrado
    case errors.Is(err, synapse.ErrConflict):
        // 409 — duplicidade (ex: email já em uso)
    case errors.Is(err, synapse.ErrBadRequest):
        // 400 — parâmetros inválidos
    case errors.Is(err, synapse.ErrBadGateway):
        // 502 — erro no provedor externo (OpenAI, Google…)
    case errors.Is(err, synapse.ErrInternalServer):
        // 500 — erro interno da API
    default:
        // erro de rede, timeout, etc.
    }
}
Inspecionar payload completo da API

Use synapse.AsAPIError quando precisar dos detalhes (trace_id, causes):

if apiErr, ok := synapse.AsAPIError(err); ok {
    fmt.Println("HTTP status:", apiErr.StatusCode)
    fmt.Println("Trace ID:",    apiErr.TraceID)
    fmt.Println("Mensagem:",    apiErr.Message)

    for _, cause := range apiErr.Causes {
        fmt.Printf("  campo %q: %s\n", cause.Field, cause.Message)
    }
}
Sentinels disponíveis
Sentinel HTTP Quando ocorre
synapse.ErrInvalidToken — Token vazio ao criar o client
synapse.ErrUnauthorized 401 Token inválido ou expirado
synapse.ErrForbidden 403 Sem permissão para o recurso
synapse.ErrNotFound 404 Recurso não encontrado
synapse.ErrConflict 409 Duplicidade (email, documento, token…)
synapse.ErrBadRequest 400 Parâmetros inválidos
synapse.ErrInternalServer 500 Erro interno da API
synapse.ErrBadGateway 502 Falha no provedor externo
synapse.ErrIntegrationNotConfigured 409 Integração não configurada para o tenant

Exemplo completo

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "os"
    "time"

    "github.com/WonitTecnologia/synapse"
)

func main() {
    client, err := synapse.NewClient(os.Getenv("SYNAPSE_TOKEN"), &synapse.Options{
        Timeout: 20 * time.Second,
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Validar token
    me, err := client.Auth.Healthcheck(ctx)
    if err != nil {
        if errors.Is(err, synapse.ErrUnauthorized) {
            log.Fatal("token inválido ou expirado")
        }
        log.Fatal(err)
    }
    fmt.Printf("Logado como: %s (%s)\n", me.User.Name, me.User.Role)

    // Transcrever um áudio
    audio, _ := os.ReadFile("reuniao.mp3")
    transcription, err := client.OpenAI.TranscribeAudio(ctx, synapse.TranscribeAudioRequest{
        FileName: "reuniao.mp3",
        Content:  audio,
        Model:    "whisper-1",
        Language: "pt",
    })
    if err != nil {
        if apiErr, ok := synapse.AsAPIError(err); ok {
            log.Fatalf("erro da API [trace=%s]: %s", apiErr.TraceID, apiErr.Message)
        }
        log.Fatal(err)
    }
    fmt.Println("Transcrição:", transcription.Response)
}

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidToken             = errors.New("synapse: token cannot be empty")
	ErrUnauthorized             = errors.New("synapse: unauthorized — invalid or missing token")
	ErrForbidden                = errors.New("synapse: forbidden — insufficient permissions")
	ErrNotFound                 = errors.New("synapse: resource not found")
	ErrConflict                 = errors.New("synapse: conflict — resource already exists or duplicate")
	ErrBadRequest               = errors.New("synapse: bad request — invalid parameters")
	ErrInternalServer           = errors.New("synapse: internal server error")
	ErrBadGateway               = errors.New("synapse: bad gateway — upstream provider error")
	ErrIntegrationNotConfigured = errors.New("synapse: integration not configured for this tenant")
)

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	// StatusCode is the HTTP status returned by the API.
	StatusCode int `json:"-"`

	// Code mirrors the numeric code in the response body.
	Code int `json:"code"`

	// Err is the short error label from the response body.
	Err string `json:"error"`

	// Message is the human-readable description from the response body.
	Message string `json:"message"`

	// TraceID is the trace identifier returned by the API for debugging.
	TraceID string `json:"trace_id"`

	// Causes holds field-level validation errors when applicable.
	Causes []RestErrCause `json:"causes"`
}

APIError represents an error response from the Synapse API. It carries the full response payload and wraps a typed sentinel error so callers can use errors.Is for control flow.

Example: 

_, err := client.Auth.Login(ctx, req)
if errors.Is(err, synapse.ErrUnauthorized) { ... }

if apiErr, ok := synapse.AsAPIError(err); ok {
    fmt.Println(apiErr.TraceID, apiErr.Causes)
}

func AsAPIError 

func AsAPIError(err error) (*APIError, bool)

AsAPIError unwraps err into *APIError and reports whether it succeeded. Use this to inspect the full API error payload (causes, trace_id, etc.).

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) Unwrap 

func (e *APIError) Unwrap() error

Unwrap maps the HTTP status code to the appropriate sentinel error, enabling errors.Is checks against the package-level sentinels.

type AgentCase added in v0.0.6 

type AgentCase interface {
	// Create registers a new AI agent.
	// SYSTEM_ADMIN must set req.TenantUUID; other roles use the tenant from the token.
	Create(ctx context.Context, req CreateAgentRequest) (*AgentResponse, error)

	// Get returns an agent by its UUID.
	// SYSTEM_ADMIN can fetch agents from any tenant.
	Get(ctx context.Context, agentUUID string) (*AgentResponse, error)

	// List returns a paginated list of agents.
	// SYSTEM_ADMIN lists agents from all tenants; other roles are scoped to their own tenant.
	// Use page=0 and size=0 to rely on server defaults.
	List(ctx context.Context, page, size int) (*ListAgentsResponse, error)

	// Update replaces all mutable fields of an agent (PUT semantics).
	// SYSTEM_ADMIN can update agents from any tenant.
	Update(ctx context.Context, agentUUID string, req UpdateAgentRequest) (*AgentResponse, error)

	// Patch updates a single field of an agent (PATCH semantics).
	// Set exactly one field in req; the server rejects requests with 0 or more than 1 field.
	// SYSTEM_ADMIN can patch agents from any tenant.
	Patch(ctx context.Context, agentUUID string, req UpdateAgentRequest) (*AgentResponse, error)

	// Delete permanently removes an agent and all its conversations.
	// SYSTEM_ADMIN can delete agents from any tenant.
	Delete(ctx context.Context, agentUUID string) error

	// Chat sends a message to an agent and returns the response.
	// Omit req.ConversationUUID to start a new conversation; the returned
	// ChatResponse.ConversationUUID can be passed in subsequent calls to maintain context.
	// req.ConversationUUID also accepts any client-defined identifier instead of a UUID
	// (e.g. "2024123ABCabc"): the backend generates and links a UUID to it on the first
	// call, scoped by tenant + agent, and reuses the same conversation on later calls with
	// the same identifier — see ChatRequest.ConversationUUID for details.
	// SYSTEM_ADMIN can chat with agents from any tenant.
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)

	// ListConversations returns a paginated list of conversation summaries.
	// SYSTEM_ADMIN lists conversations from all tenants; other roles are scoped to their own tenant.
	// Use params.AgentUUID to filter by a specific agent.
	ListConversations(ctx context.Context, params ListConversationsParams) (*ListConversationsResponse, error)

	// ListPrompts returns a paginated list of versioned prompts saved for an agent.
	// The IsActive field in each response indicates which prompt is currently active.
	ListPrompts(ctx context.Context, agentUUID string, page, size int) (*ListAgentPromptsResponse, error)

	// GetPrompt returns a single versioned prompt by its UUID.
	GetPrompt(ctx context.Context, agentUUID, promptUUID string) (*AgentPromptResponse, error)

	// CreatePrompt saves a new versioned prompt for an agent.
	// Multiple prompts with the same name are allowed; each is versioned by creation date.
	CreatePrompt(ctx context.Context, agentUUID string, req CreateAgentPromptRequest) (*AgentPromptResponse, error)

	// UpdatePrompt updates the name and/or content of a saved prompt.
	// If the prompt is currently active, the agent's prompt content is synced automatically.
	UpdatePrompt(ctx context.Context, agentUUID, promptUUID string, req UpdateAgentPromptRequest) (*AgentPromptResponse, error)

	// DeletePrompt permanently removes a saved prompt.
	// If the deleted prompt was the active one, the agent will have no active prompt (active_prompt_uuid = null).
	DeletePrompt(ctx context.Context, agentUUID, promptUUID string) error

	// ActivatePrompt sets a saved prompt as the active prompt for the agent.
	// The agent's prompt content is updated immediately to reflect the selected version.
	ActivatePrompt(ctx context.Context, agentUUID, promptUUID string) error

	// DeactivatePrompt removes the active prompt link from the agent (active_prompt_uuid = null).
	DeactivatePrompt(ctx context.Context, agentUUID string) error

	// ListLogs returns execution logs for an agent, filterable by conversation UUID or external ID.
	ListLogs(ctx context.Context, agentUUID string, params ListAgentLogsParams) (*ListAgentLogsResponse, error)
}

AgentCase provides CRUD, chat and conversation operations for AI agents.

type AgentLogItem added in v0.0.17 

type AgentLogItem struct {
	UUID                   string  `json:"uuid"`
	TenantUUID             string  `json:"tenant_uuid"`
	AgentUUID              string  `json:"agent_uuid"`
	AgentName              string  `json:"agent_name"`
	ConversationUUID       *string `json:"conversation_uuid,omitempty"`
	ConversationExternalID *string `json:"conversation_external_id,omitempty"`
	Level                  string  `json:"level"`
	Category               string  `json:"category"`
	Summary                string  `json:"summary"`
	Detail                 any     `json:"detail,omitempty"`
	ToolName               *string `json:"tool_name,omitempty"`
	ToolParams             any     `json:"tool_params,omitempty"`
	ToolSuccess            *bool   `json:"tool_success,omitempty"`
	ToolSummary            *string `json:"tool_summary,omitempty"`
	DurationMs             *int    `json:"duration_ms,omitempty"`
	Model                  *string `json:"model,omitempty"`
	TokensUsed             int     `json:"tokens_used"`
	CreatedAt              string  `json:"created_at"`
}

AgentLogItem represents a single agent execution log entry.

type AgentPromptResponse added in v0.0.11 

type AgentPromptResponse struct {
	UUID       string `json:"uuid"`
	AgentUUID  string `json:"agent_uuid"`
	TenantUUID string `json:"tenant_uuid"`
	Name       string `json:"name"`
	Prompt     string `json:"prompt"`
	// IsActive reports whether this prompt is currently set as the agent's active prompt.
	IsActive  bool   `json:"is_active"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

AgentPromptResponse describes a versioned prompt saved for an agent.

type AgentResponse added in v0.0.6 

type AgentResponse struct {
	UUID                string   `json:"uuid"`
	TenantUUID          string   `json:"tenant_uuid"`
	Name                string   `json:"name"`
	Description         string   `json:"description"`
	Model               string   `json:"model"`
	Prompt              string   `json:"prompt"`
	CollectionUUIDs     []string `json:"collection_uuids"`
	QueryEmbedModel     string   `json:"query_embed_model,omitempty"`
	MaxContext          int      `json:"max_context"`
	Temperature         float64  `json:"temperature"`
	Active              bool     `json:"active"`
	McpEnabled          bool     `json:"mcp_enabled"`
	McpIntegrationUUIDs []string `json:"mcp_integration_uuids"`
	McpDisabledTools    []string `json:"mcp_disabled_tools"`
	ActivePromptUUID    string   `json:"active_prompt_uuid,omitempty"`
	CreatedAt           string   `json:"created_at"`
	UpdatedAt           string   `json:"updated_at"`
}

AgentResponse describes an AI agent.

type AnalyzeImageFromURLRequest added in v0.0.5 

type AnalyzeImageFromURLRequest struct {
	FileURL string `json:"file_url"`
	Prompt  string `json:"prompt"`
}

AnalyzeImageFromURLRequest is the body for analysing an image that the server fetches from a download URL (OpenAI image analysis).

type AnalyzeImageResponse 

type AnalyzeImageResponse struct {
	Response string `json:"response"`
}

AnalyzeImageResponse is returned by both OpenAI and Google Vision image endpoints.

type ApiTokenCreateRequest 

type ApiTokenCreateRequest struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// ExpireAt is optional; if omitted the server sets a default expiry.
	ExpireAt string `json:"expire_at,omitempty"`
}

ApiTokenCreateRequest is the body for creating an API token.

type ApiTokenCreateResponse 

type ApiTokenCreateResponse struct {
	UUID        string `json:"uuid"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Token       string `json:"token"`
	TenantUUID  string `json:"tenant_uuid"`
	UserUUID    string `json:"user_uuid"`
	ExpireAt    string `json:"expire_at"`
	CreatedAt   string `json:"create_at"`
}

ApiTokenCreateResponse describes a created or listed API token.

type AuthCase 

type AuthCase interface {
	// Login authenticates a user with email and password and returns an access token.
	Login(ctx context.Context, req LoginRequest) (*LoginResponse, error)

	// Logout revokes the given access token.
	Logout(ctx context.Context, token string) error

	// Healthcheck validates the current token and returns the logged-in user's data.
	Healthcheck(ctx context.Context) (*LoginResponse, error)

	// RequestOTP sends a one-time password to the given email address.
	RequestOTP(ctx context.Context, req OTPRequest) error

	// ResetPassword validates the OTP and replaces the user's password.
	ResetPassword(ctx context.Context, req OTPResetPasswordRequest) error

	// ListAPITokens returns all API tokens linked to the authenticated user.
	// Use page=0 and pageSize=0 to rely on server defaults.
	ListAPITokens(ctx context.Context, page, pageSize int) (*ListApiTokensResponse, error)

	// CreateAPIToken creates a new API token for the authenticated user.
	CreateAPIToken(ctx context.Context, req ApiTokenCreateRequest) (*ApiTokenCreateResponse, error)
}

AuthCase provides all authentication-related operations against the Synapse API.

type ChatCompletionRequest 

type ChatCompletionRequest struct {
	Prompt string `json:"prompt"`
}

ChatCompletionRequest is the body for a chat completion call.

type ChatCompletionResponse 

type ChatCompletionResponse struct {
	Response string `json:"response"`
}

ChatCompletionResponse is the response from a chat completion call.

type ChatRagInfo added in v0.0.6 

type ChatRagInfo struct {
	Enabled     bool   `json:"enabled"`
	ChunksFound int    `json:"chunks_found"`
	Error       string `json:"error,omitempty"`
}

ChatRagInfo reports what happened during the semantic search step.

type ChatReference added in v0.0.6 

type ChatReference struct {
	Filename   string  `json:"filename"`
	ChunkIndex int     `json:"chunk_index"`
	Score      float32 `json:"score"`
	ScorePct   float32 `json:"score_pct"`
	Text       string  `json:"text"`
}

ChatReference is a document chunk retrieved from Qdrant and used in the RAG context.

type ChatRequest added in v0.0.6 

type ChatRequest struct {
	AgentUUID string `json:"agent_uuid"`
	Message   string `json:"message"`
	// ConversationUUID continues an existing conversation; omit to start a new one.
	// It accepts two formats:
	//   - a conversation UUID returned by a previous Chat call: continues that conversation;
	//   - any client-defined identifier (e.g. "2024123ABCabc"): the backend generates a UUID
	//     on the first call and links that identifier to it (scoped by tenant + agent).
	//     Subsequent calls with the same identifier reuse the same conversation, and the
	//     same identifier from a different tenant resolves to a different conversation.
	ConversationUUID *string `json:"conversation_uuid,omitempty"`
	// Context carries free-text metadata from the calling system (e.g. PABX). Format is
	// implementation-defined — e.g. "tenant_uuid:x,protocol_uuid:y". When present, the agent
	// runtime injects this into MCP tool parameters.
	Context *string `json:"context,omitempty"`
}

ChatRequest is the body for sending a message to an AI agent.

type ChatResponse added in v0.0.6 

type ChatResponse struct {
	ConversationUUID string          `json:"conversation_uuid"`
	Message          string          `json:"message"`
	References       []ChatReference `json:"references"`
	Rag              ChatRagInfo     `json:"rag"`
}

ChatResponse is the reply from the AI agent.

type ChatvoltAgentItem added in v0.0.4 

type ChatvoltAgentItem struct {
	ID          string                  `json:"id"`
	Name        string                  `json:"name"`
	IconUrl     *string                 `json:"iconUrl,omitempty"`
	Description string                  `json:"description"`
	ModelName   string                  `json:"modelName"`
	Visibility  ChatvoltAgentVisibility `json:"visibility"`
}

ChatvoltAgentItem describes a single Chatvolt agent returned by the catalog.

type ChatvoltAgentQueryRequest 

type ChatvoltAgentQueryRequest struct {
	AgentID string `json:"agentId"`
	Query   string `json:"query"`
	// ConversationID keeps context across turns; omit to start a new conversation.
	ConversationID string `json:"conversationId,omitempty"`
	// Streaming should generally be false for synchronous responses.
	Streaming bool             `json:"streaming"`
	Contact   *ChatvoltContact `json:"contact,omitempty"`
}

ChatvoltAgentQueryRequest is the body for querying a Chatvolt agent.

type ChatvoltAgentQueryResponse 

type ChatvoltAgentQueryResponse struct {
	Answer         string      `json:"answer"`
	ConversationID string      `json:"conversationId"`
	MessageID      string      `json:"messageId"`
	VisitorID      string      `json:"visitorId"`
	Sources        interface{} `json:"sources"`
	Metadata       interface{} `json:"metadata"`
}

ChatvoltAgentQueryResponse is the response from a Chatvolt agent query.

type ChatvoltAgentVisibility added in v0.0.4 

type ChatvoltAgentVisibility string

ChatvoltAgentVisibility indicates whether a Chatvolt agent is publicly accessible. 

const (
	ChatvoltAgentVisibilityPublic  ChatvoltAgentVisibility = "public"
	ChatvoltAgentVisibilityPrivate ChatvoltAgentVisibility = "private"
)

type ChatvoltCase 

type ChatvoltCase interface {
	// Configure creates or updates the Chatvolt integration credentials
	// for the authenticated tenant.
	Configure(ctx context.Context, req ConfigureChatvoltRequest) error

	// Query sends a message to a Chatvolt agent and returns its response.
	// Set req.ConversationID to continue an existing conversation thread.
	Query(ctx context.Context, req ChatvoltAgentQueryRequest) (*ChatvoltAgentQueryResponse, error)

	// ListAgents returns all Chatvolt agents available for the authenticated tenant.
	ListAgents(ctx context.Context) (*ListChatvoltAgentsResponse, error)
}

ChatvoltCase provides operations for the Chatvolt agent integration.

type ChatvoltContact 

type ChatvoltContact struct {
	UserID      string `json:"userId,omitempty"`
	Email       string `json:"email,omitempty"`
	FirstName   string `json:"firstName,omitempty"`
	LastName    string `json:"lastName,omitempty"`
	PhoneNumber string `json:"phoneNumber,omitempty"`
}

ChatvoltContact carries optional contact metadata attached to a Chatvolt query.

type ChatvoltCredentialsDTO 

type ChatvoltCredentialsDTO struct {
	Token string `json:"token"`
}

ChatvoltCredentialsDTO holds the API key for the Chatvolt integration.

type Client 

type Client struct {
	// Auth covers login, logout, OTP, password reset, and API token management.
	Auth AuthCase

	// User covers user CRUD operations.
	User UserCase

	// Tenant covers tenant CRUD operations.
	Tenant TenantCase

	// Provider covers read operations for catalog integration providers.
	Provider ProviderCase

	// Service covers read operations for catalog integration services.
	Service ServiceCase

	// Google covers the Google Vision AI integration (configure + OCR).
	Google GoogleCase

	// OpenAI covers the OpenAI integration (configure, chat, image analysis, transcription).
	OpenAI OpenAICase

	// Chatvolt covers the Chatvolt agent integration (configure, query, list agents).
	Chatvolt ChatvoltCase

	// OpenRouter covers the OpenRouter integration (workspace sync/desync, model listing).
	OpenRouter OpenRouterCase

	// Collection covers Qdrant vector collection CRUD for the knowledge base.
	Collection CollectionCase

	// Document covers document upload and vectorization for the knowledge base.
	Document DocumentCase

	// Agent covers AI agent CRUD operations and chat (including RAG).
	Agent AgentCase

	// Mcp covers MCP (Model Context Protocol) server integration management.
	Mcp McpCase
}

Client is the top-level Synapse SDK entry point. Each field exposes a domain-specific interface covering a group of API endpoints.

Usage: 

client, err := synapse.NewClient("your-token", nil)

// Auth
resp, err := client.Auth.Login(ctx, synapse.LoginRequest{...})

// Tenant
tenant, err := client.Tenant.Get(ctx, "uuid", "")

// Google Vision
err = client.Google.Configure(ctx, synapse.ConfigureGoogleRequest{...})
ocr, err := client.Google.VisionOCR(ctx, "photo.jpg", imageBytes)

// OpenAI
reply, err := client.OpenAI.Chat(ctx, synapse.ChatCompletionRequest{Prompt: "Hello!"})

// Chatvolt
answer, err := client.Chatvolt.Query(ctx, synapse.ChatvoltAgentQueryRequest{...})

// OpenRouter
sync, err := client.OpenRouter.Sync(ctx, synapse.OpenRouterSyncRequest{})
models, err := client.OpenRouter.ListModels(ctx, false)

// Knowledge
col, err := client.Collection.Create(ctx, synapse.CreateCollectionRequest{Name: "docs", VectorSize: 1536})
doc, err := client.Document.Upload(ctx, synapse.UploadDocumentRequest{...})

// Agent
agent, err := client.Agent.Create(ctx, synapse.CreateAgentRequest{...})
resp, err := client.Agent.Chat(ctx, synapse.ChatRequest{AgentUUID: "...", Message: "Olá!"})

func NewClient 

func NewClient(token string, opts *Options) (*Client, error)

NewClient creates and returns a fully initialised Synapse Client.

token is required and is sent as a Bearer token on every request. Pass an *Options to override the base URL or request timeout; pass nil for defaults. 

client, err := synapse.NewClient("sk-...", &synapse.Options{
    BaseURL: "https://staging.synapse.example.com",
    Timeout: 15 * time.Second,
})

type CollectionCase added in v0.0.6 

type CollectionCase interface {
	// Create registers a new vector collection for the authenticated tenant.
	Create(ctx context.Context, req CreateCollectionRequest) (*CollectionResponse, error)

	// Get returns a collection by its UUID.
	Get(ctx context.Context, collectionUUID string) (*CollectionResponse, error)

	// List returns a paginated list of collections for the authenticated tenant.
	// Use page=0 and size=0 to rely on server defaults.
	List(ctx context.Context, page, size int) (*CollectionsResponse, error)

	// Delete permanently removes a collection and its Qdrant data by UUID.
	Delete(ctx context.Context, collectionUUID string) error
}

CollectionCase provides CRUD operations for Qdrant vector collections.

type CollectionResponse added in v0.0.6 

type CollectionResponse struct {
	UUID                 string `json:"uuid"`
	TenantUUID           string `json:"tenant_uuid"`
	Name                 string `json:"name"`
	QdrantCollectionName string `json:"qdrant_collection_name"`
	VectorSize           uint64 `json:"vector_size"`
	Distance             string `json:"distance"`
	CreatedAt            string `json:"createAt"`
	UpdatedAt            string `json:"updateAt"`
}

CollectionResponse describes a single Qdrant collection registered for a tenant.

type CollectionsResponse added in v0.0.6 

type CollectionsResponse struct {
	Collections []CollectionResponse `json:"collections"`
	Page        int                  `json:"page"`
	Size        int                  `json:"size"`
}

CollectionsResponse is the paginated list of collections for a tenant.

type ConfigureChatvoltRequest 

type ConfigureChatvoltRequest struct {
	Credentials ChatvoltCredentialsDTO `json:"credentials"`
	IsActive    bool                   `json:"is_active,omitempty"`
}

ConfigureChatvoltRequest is the body for creating/updating the Chatvolt integration.

type ConfigureGoogleRequest 

type ConfigureGoogleRequest struct {
	Credentials VisionAICredentialsDTO `json:"credentials"`
	IsActive    bool                   `json:"is_active,omitempty"`
}

ConfigureGoogleRequest is the body for creating/updating the Google Vision integration.

type ConfigureOpenAIRequest 

type ConfigureOpenAIRequest struct {
	Credentials OpenAICredentialsDTO `json:"credentials"`
	Settings    OpenAISettingsDTO    `json:"settings"`
	IsActive    bool                 `json:"is_active,omitempty"`
}

ConfigureOpenAIRequest is the body for creating/updating the OpenAI integration.

type ConversationResponse added in v0.0.7 

type ConversationResponse struct {
	UUID       string `json:"uuid"`
	TenantUUID string `json:"tenant_uuid"`
	AgentUUID  string `json:"agent_uuid"`
	// ExternalID is the client-defined identifier linked to this conversation, when the
	// conversation was started by passing an arbitrary identifier in ConversationUUID
	// instead of a UUID. Nil for conversations created/continued by UUID.
	ExternalID *string `json:"external_id,omitempty"`
	// MessageCount is the total number of messages (user + assistant turns).
	MessageCount int    `json:"message_count"`
	CreatedAt    string `json:"created_at"`
	UpdatedAt    string `json:"updated_at"`
}

ConversationResponse is a summary of a stored conversation (without full message content).

type CreateAgentPromptRequest added in v0.0.11 

type CreateAgentPromptRequest struct {
	Name   string `json:"name"`
	Prompt string `json:"prompt"`
}

CreateAgentPromptRequest is the body for saving a new versioned prompt for an agent.

type CreateAgentRequest added in v0.0.6 

type CreateAgentRequest struct {
	// TenantUUID is required when the caller is SYSTEM_ADMIN; ignored for other roles.
	TenantUUID  *string `json:"tenant_uuid,omitempty"`
	Name        string  `json:"name"`
	Description string  `json:"description,omitempty"`
	Model       string  `json:"model"`
	Prompt      string  `json:"prompt"`
	// CollectionUUIDs enables RAG with one or more indexed collections.
	// The embedding model is resolved automatically from the first collection's documents.
	// All collections must use the same embedding model.
	CollectionUUIDs []string `json:"collection_uuids,omitempty"`
	// MaxContext accepted values: 10000, 15000, 20000 (default: 10000).
	MaxContext int `json:"max_context,omitempty"`
	// Temperature controls randomness: 0.0 (deterministic) – 0.7 (max without hallucination).
	Temperature *float64 `json:"temperature,omitempty"`
	McpEnabled  *bool    `json:"mcp_enabled,omitempty"`
	// McpIntegrationUUIDs links the agent to specific MCP server integrations.
	McpIntegrationUUIDs []string `json:"mcp_integration_uuids,omitempty"`
	// McpDisabledTools lists tool names (from the linked integrations) that this agent must not call.
	McpDisabledTools []string `json:"mcp_disabled_tools,omitempty"`
}

CreateAgentRequest is the body for creating an AI agent.

type CreateCollectionRequest added in v0.0.6 

type CreateCollectionRequest struct {
	// TenantUUID is required when the caller is SYSTEM_ADMIN; ignored for other roles.
	TenantUUID *string `json:"tenant_uuid,omitempty"`
	Name       string  `json:"name"`
	// VectorSize is the dimension of the embedding vectors (e.g. 1536 for text-embedding-ada-002).
	// When zero the server uses its default (1536).
	VectorSize uint64 `json:"vector_size,omitempty"`
	// Distance is the similarity metric: "Cosine" (default), "Euclid", or "Dot".
	Distance string `json:"distance,omitempty"`
}

CreateCollectionRequest is the body for creating a Qdrant vector collection.

type CreateMcpIntegrationRequest added in v0.0.13 

type CreateMcpIntegrationRequest struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// BaseURL is the root URL of the MCP server (e.g. "https://pabx.wonit.cloud").
	BaseURL string `json:"base_url"`
	// Token is the Bearer token sent in every request to the MCP server.
	Token string `json:"token"`
}

CreateMcpIntegrationRequest is the body for registering a new MCP server integration.

type CreateTenantRequestDto 

type CreateTenantRequestDto struct {
	ID       string `json:"uuid"`
	Name     string `json:"name"`
	Document string `json:"document"`
}

CreateTenantRequestDto is the body for creating a tenant.

type CreateUserRequestDto 

type CreateUserRequestDto struct {
	Name     string   `json:"name"`
	Email    string   `json:"email"`
	Password string   `json:"password"`
	Role     UserRole `json:"role"`
}

CreateUserRequestDto is the body for creating a user.

type DocumentCase added in v0.0.6 

type DocumentCase interface {
	// Upload sends a document file to the server, which parses it, generates embeddings
	// via OpenRouter, and stores the vectors in Qdrant. Processing happens in the background;
	// the returned DocumentResponse will have Status="processing" immediately.
	Upload(ctx context.Context, req UploadDocumentRequest) (*DocumentResponse, error)

	// Get returns the metadata of a document by its UUID.
	Get(ctx context.Context, documentUUID string) (*DocumentResponse, error)

	// List returns a paginated list of documents belonging to the given collection.
	List(ctx context.Context, params ListDocumentsParams) (*ListDocumentsResponse, error)

	// Delete removes a document and all its associated Qdrant vectors.
	Delete(ctx context.Context, documentUUID string) error

	// ListChunks returns a paginated list of the vectorized text chunks stored in
	// Qdrant for the given document, ordered by chunk_index (reading order).
	// Use params.Size to control how many chunks per page (max 100, default 20).
	ListChunks(ctx context.Context, documentUUID string, params ListChunksParams) (*ListChunksResponse, error)
}

DocumentCase provides operations for uploading and managing vectorized documents.

type DocumentChunkResponse added in v0.0.10 

type DocumentChunkResponse struct {
	ID           string `json:"id"`
	ChunkIndex   int    `json:"chunk_index"`
	Text         string `json:"text"`
	DocumentUUID string `json:"document_uuid"`
	Filename     string `json:"filename"`
	FileType     string `json:"file_type"`
}

DocumentChunkResponse is a single vectorized text chunk stored in Qdrant.

type DocumentResponse added in v0.0.6 

type DocumentResponse struct {
	UUID           string `json:"uuid"`
	TenantUUID     string `json:"tenant_uuid"`
	CollectionUUID string `json:"collection_uuid"`
	Filename       string `json:"filename"`
	FileType       string `json:"file_type"`
	EmbedModel     string `json:"embed_model"`
	ChunkCount     int    `json:"chunk_count"`
	VectorSize     int    `json:"vector_size"`
	TokensUsed     int64  `json:"tokens_used"`
	// Status is "processing", "ready", or "error".
	Status       string `json:"status"`
	ErrorMessage string `json:"error_message,omitempty"`
	CreatedAt    string `json:"created_at"`
	UpdatedAt    string `json:"updated_at"`
}

DocumentResponse describes a document that has been uploaded and vectorized.

type GoogleCase 

type GoogleCase interface {
	// Configure creates or updates the Google Vision AI integration credentials
	// for the authenticated tenant.
	Configure(ctx context.Context, req ConfigureGoogleRequest) error

	// VisionOCR extracts text from an image using Google Vision TEXT_DETECTION.
	// fileName is used as the multipart filename (e.g. "photo.jpg").
	// fileContent is the raw image bytes (png, jpg, jpeg, webp).
	VisionOCR(ctx context.Context, fileName string, fileContent []byte) (*AnalyzeImageResponse, error)

	// VisionOCRFromURL extracts text from an image that the Synapse server
	// downloads from the URL in req.FileURL.
	VisionOCRFromURL(ctx context.Context, req VisionOCRFromURLRequest) (*AnalyzeImageResponse, error)
}

GoogleCase provides operations for the Google Vision AI integration.

type ListAgentLogsParams added in v0.0.17 

type ListAgentLogsParams struct {
	ConversationUUID string
	ExternalID       string
	Page             int
	Size             int
}

ListAgentLogsParams holds optional filters when listing agent logs.

type ListAgentLogsResponse added in v0.0.17 

type ListAgentLogsResponse struct {
	Logs  []AgentLogItem `json:"logs"`
	Page  int            `json:"page"`
	Size  int            `json:"size"`
	Total int64          `json:"total"`
}

ListAgentLogsResponse is the paginated response for listing agent logs.

type ListAgentPromptsResponse added in v0.0.11 

type ListAgentPromptsResponse struct {
	Prompts []AgentPromptResponse `json:"prompts"`
	Page    int                   `json:"page"`
	Size    int                   `json:"size"`
}

ListAgentPromptsResponse is the paginated list of saved prompts for an agent.

type ListAgentsResponse added in v0.0.6 

type ListAgentsResponse struct {
	Agents []AgentResponse `json:"agents"`
	Page   int             `json:"page"`
	Size   int             `json:"size"`
}

ListAgentsResponse is the paginated list of agents for a tenant.

type ListApiTokensResponse 

type ListApiTokensResponse struct {
	UserUUID  string                   `json:"user_uuid"`
	Page      int                      `json:"page"`
	Size      int                      `json:"size"`
	APITokens []ApiTokenCreateResponse `json:"api_tokens"`
}

ListApiTokensResponse is the paginated response for the API token list.

type ListChatvoltAgentsResponse added in v0.0.4 

type ListChatvoltAgentsResponse struct {
	Agents []ChatvoltAgentItem `json:"agents"`
}

ListChatvoltAgentsResponse is the response for the Chatvolt agents list endpoint.

type ListChunksParams added in v0.0.10 

type ListChunksParams struct {
	Page int
	// Size is the number of chunks per page (max 100, default 20).
	Size int
}

ListChunksParams holds query parameters for the chunk list endpoint.

type ListChunksResponse added in v0.0.10 

type ListChunksResponse struct {
	Chunks     []DocumentChunkResponse `json:"chunks"`
	Total      int                     `json:"total"`
	Page       int                     `json:"page"`
	Size       int                     `json:"size"`
	TotalPages int                     `json:"total_pages"`
}

ListChunksResponse is the paginated list of chunks for a document.

type ListConversationsParams added in v0.0.7 

type ListConversationsParams struct {
	// AgentUUID filters conversations by a specific agent (optional).
	AgentUUID string
	Page      int
	Size      int
}

ListConversationsParams holds query parameters for the conversation list endpoint.

type ListConversationsResponse added in v0.0.7 

type ListConversationsResponse struct {
	Conversations []ConversationResponse `json:"conversations"`
	Page          int                    `json:"page"`
	Size          int                    `json:"size"`
}

ListConversationsResponse is the paginated list of conversation summaries.

type ListDocumentsParams added in v0.0.6 

type ListDocumentsParams struct {
	// CollectionUUID filters documents by collection.
	// Required for TENANT_ADMIN/TENANT_USER; optional for SYSTEM_ADMIN.
	CollectionUUID string
	Page           int
	Size           int
}

ListDocumentsParams holds query parameters for the document list endpoint.

type ListDocumentsResponse added in v0.0.6 

type ListDocumentsResponse struct {
	Documents []DocumentResponse `json:"documents"`
	Page      int                `json:"page"`
	Size      int                `json:"size"`
}

ListDocumentsResponse is the paginated list of documents in a collection.

type ListUsersParams 

type ListUsersParams struct {
	Page int
	Size int
	// TenantIdentifier filters by tenant UUID or document (SystemAdmin only).
	TenantIdentifier string
}

ListUsersParams holds query parameters for the user list endpoint.

type LoginRequest 

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
	// RememberMe extends the token expiry to 30 days when true.
	// Omit or set false for the default short-lived session.
	RememberMe bool `json:"remember_me,omitempty"`
}

LoginRequest holds the credentials for the login endpoint.

type LoginResponse 

type LoginResponse struct {
	Token         string          `json:"token"`
	Expire        string          `json:"expire"`
	SystemTimeUTC string          `json:"system_time_utc"`
	User          UserResponseDto `json:"user"`
}

LoginResponse is returned on successful login or healthcheck.

type McpCase added in v0.0.13 

type McpCase interface {
	Create(ctx context.Context, req CreateMcpIntegrationRequest) (*McpIntegrationResponse, error)
	Get(ctx context.Context, uuid string) (*McpIntegrationResponse, error)
	List(ctx context.Context) (*McpIntegrationListResponse, error)
	Update(ctx context.Context, uuid string, req UpdateMcpIntegrationRequest) (*McpIntegrationResponse, error)
	Toggle(ctx context.Context, uuid string, req ToggleMcpIntegrationRequest) (*McpIntegrationResponse, error)
	Delete(ctx context.Context, uuid string) error
	// GetTools lists the tools exposed by the remote MCP server behind this integration.
	GetTools(ctx context.Context, uuid string) (*McpToolsListResponse, error)
}

McpCase provides CRUD operations for MCP (Model Context Protocol) server integrations.

type McpIntegrationListResponse added in v0.0.13 

type McpIntegrationListResponse struct {
	Items []McpIntegrationResponse `json:"integrations"`
	Total int                      `json:"total"`
}

McpIntegrationListResponse is the list of MCP integrations for a tenant.

type McpIntegrationResponse added in v0.0.13 

type McpIntegrationResponse struct {
	UUID        string `json:"uuid"`
	TenantUUID  string `json:"tenant_uuid"`
	Name        string `json:"name"`
	Description string `json:"description"`
	BaseURL     string `json:"base_url"`
	IsActive    bool   `json:"is_active"`
	CreatedAt   string `json:"created_at"`
	UpdatedAt   string `json:"updated_at"`
}

McpIntegrationResponse describes a registered MCP server integration.

type McpToolDefinition added in v0.0.15 

type McpToolDefinition struct {
	Name        string             `json:"name"`
	DisplayName string             `json:"display_name"`
	Description string             `json:"description"`
	Parameters  []McpToolParameter `json:"parameters"`
}

McpToolDefinition describes a tool exposed by an MCP integration's remote server.

type McpToolParameter added in v0.0.15 

type McpToolParameter struct {
	Name        string   `json:"name"`
	Type        string   `json:"type"`
	Description string   `json:"description"`
	Required    bool     `json:"required"`
	Enum        []string `json:"enum,omitempty"`
}

McpToolParameter describes one parameter of a tool exposed by an MCP integration.

type McpToolsListResponse added in v0.0.15 

type McpToolsListResponse struct {
	Tools []McpToolDefinition `json:"tools"`
}

McpToolsListResponse is the response of listing the tools exposed by an MCP integration.

type OTPRequest 

type OTPRequest struct {
	Email string `json:"email"`
}

OTPRequest requests a one-time password to be sent to the given email.

type OTPResetPasswordRequest 

type OTPResetPasswordRequest struct {
	Email    string `json:"email"`
	OTP      string `json:"otp"`
	Password string `json:"password"`
}

OTPResetPasswordRequest resets a user password using an OTP code.

type OpenAICase 

type OpenAICase interface {
	// Configure creates or updates the OpenAI integration credentials and settings
	// for the authenticated tenant.
	Configure(ctx context.Context, req ConfigureOpenAIRequest) error

	// Chat executes a Chat Completion call using the tenant's configured OpenAI account.
	Chat(ctx context.Context, req ChatCompletionRequest) (*ChatCompletionResponse, error)

	// AnalyzeImage analyses an image using OpenAI vision.
	// fileName is the multipart filename (e.g. "image.png").
	// fileContent is the raw image bytes (png, jpg, jpeg, webp).
	// prompt describes what analysis to perform.
	AnalyzeImage(ctx context.Context, fileName string, fileContent []byte, prompt string) (*AnalyzeImageResponse, error)

	// AnalyzeImageFromURL analyses an image that the Synapse server downloads from
	// the provided URL (no local upload required).
	AnalyzeImageFromURL(ctx context.Context, req AnalyzeImageFromURLRequest) (*AnalyzeImageResponse, error)

	// TranscribeAudio converts an audio file to text using OpenAI Whisper or GPT-4o.
	// See TranscribeAudioRequest for the full set of options.
	TranscribeAudio(ctx context.Context, req TranscribeAudioRequest) (*TranscriptionResponse, error)

	// TranscribeAudioFromURL converts an audio file to text; the Synapse server
	// downloads the file from the URL in req.FileURL.
	TranscribeAudioFromURL(ctx context.Context, req TranscribeAudioFromURLRequest) (*TranscriptionResponse, error)
}

OpenAICase provides operations for the OpenAI integration.

type OpenAICredentialsDTO 

type OpenAICredentialsDTO struct {
	Token string `json:"token"`
}

OpenAICredentialsDTO holds the API key for the OpenAI integration.

type OpenAIModel 

type OpenAIModel string

OpenAIModel is the model identifier accepted by the OpenAI integration. 

const (
	OpenAIModelGPT4oMini  OpenAIModel = "gpt-4o-mini"
	OpenAIModelGPT4o      OpenAIModel = "gpt-4o"
	OpenAIModelGPT4_1     OpenAIModel = "gpt-4.1"
	OpenAIModelGPT4_1Mini OpenAIModel = "gpt-4.1-mini"
	OpenAIModelO4Mini     OpenAIModel = "o4-mini"
)

type OpenAISettingsDTO 

type OpenAISettingsDTO struct {
	Model OpenAIModel `json:"model"`
	// Temperature ranges 0–2; omitted when zero.
	Temperature float64 `json:"temperature,omitempty"`
}

OpenAISettingsDTO configures model and sampling behaviour.

type OpenRouterCase added in v0.0.6 

type OpenRouterCase interface {
	// Sync creates or returns an existing OpenRouter workspace for the authenticated tenant.
	// SystemAdmin callers may target a specific tenant by setting req.TenantUUID.
	Sync(ctx context.Context, req OpenRouterSyncRequest) (*OpenRouterSyncResponse, error)

	// Desync removes the OpenRouter workspace for the authenticated tenant.
	// SystemAdmin callers may target a specific tenant by setting req.TenantUUID.
	Desync(ctx context.Context, req OpenRouterSyncRequest) (*OpenRouterDesyncResponse, error)

	// ListModels returns all models available on OpenRouter.
	// Set freeOnly=true to filter for free-tier models only.
	ListModels(ctx context.Context, freeOnly bool) (*OpenRouterListModelsResponse, error)

	// ListEmbeddingModels fetches live embedding models from the OpenRouter API,
	// filtered by output modality. Each entry includes vector_size (0 = unknown) and
	// context_length so callers can configure Qdrant collections and chunk sizes correctly.
	// Set freeOnly=true to filter for free-tier models only.
	ListEmbeddingModels(ctx context.Context, freeOnly bool) (*OpenRouterListEmbeddingModelsResponse, error)
}

OpenRouterCase provides operations for the OpenRouter integration.

type OpenRouterDesyncResponse added in v0.0.6 

type OpenRouterDesyncResponse struct {
	TenantUUID string `json:"tenant_uuid"`
	Removed    bool   `json:"removed"`
}

OpenRouterDesyncResponse is returned after a successful workspace removal.

type OpenRouterEmbeddingModel added in v0.0.6 

type OpenRouterEmbeddingModel struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	Provider      string `json:"provider"`
	VectorSize    int    `json:"vector_size"`
	ContextLength int    `json:"context_length,omitempty"`
	Description   string `json:"description"`
	PricePer1M    string `json:"price_per_token_usd"`
	IsFree        bool   `json:"is_free"`
}

OpenRouterEmbeddingModel describes a single embedding model returned live from the OpenRouter API. VectorSize is 0 when the model is not in the known-dimensions catalogue. ContextLength is the maximum number of input tokens the model accepts per request. PricePer1M is the raw per-token USD price as returned by OpenRouter (use *1e6 to convert to per-1M).

type OpenRouterListEmbeddingModelsResponse added in v0.0.6 

type OpenRouterListEmbeddingModelsResponse struct {
	Models []OpenRouterEmbeddingModel `json:"models"`
	Total  int                        `json:"total"`
}

OpenRouterListEmbeddingModelsResponse is the paginated list of OpenRouter embedding models.

type OpenRouterListModelsResponse added in v0.0.6 

type OpenRouterListModelsResponse struct {
	Models []OpenRouterModelInfo `json:"models"`
	Total  int                   `json:"total"`
}

OpenRouterListModelsResponse is the paginated list of OpenRouter models.

type OpenRouterModelArchitecture added in v0.0.8 

type OpenRouterModelArchitecture struct {
	InputModalities  []string `json:"input_modalities,omitempty"`
	OutputModalities []string `json:"output_modalities,omitempty"`
	Modality         string   `json:"modality,omitempty"`
}

OpenRouterModelArchitecture holds the supported modalities for a model.

type OpenRouterModelInfo added in v0.0.6 

type OpenRouterModelInfo struct {
	ID                  string                      `json:"id"`
	Name                string                      `json:"name"`
	CanonicalSlug       string                      `json:"canonical_slug,omitempty"`
	Description         string                      `json:"description,omitempty"`
	ContextLength       int                         `json:"context_length,omitempty"`
	Created             int64                       `json:"created,omitempty"`
	KnowledgeCutoff     string                      `json:"knowledge_cutoff,omitempty"`
	Pricing             OpenRouterModelPricing      `json:"pricing"`
	Architecture        OpenRouterModelArchitecture `json:"architecture"`
	TopProvider         OpenRouterTopProvider       `json:"top_provider"`
	SupportedParameters []string                    `json:"supported_parameters,omitempty"`
	IsFree              bool                        `json:"is_free"`
}

OpenRouterModelInfo describes a single model available on OpenRouter.

type OpenRouterModelPricing added in v0.0.6 

type OpenRouterModelPricing struct {
	Prompt     string `json:"prompt"`
	Completion string `json:"completion"`
	Image      string `json:"image,omitempty"`
	Request    string `json:"request,omitempty"`
}

OpenRouterModelPricing holds per-token/request pricing for an OpenRouter model.

type OpenRouterSyncRequest added in v0.0.6 

type OpenRouterSyncRequest struct {
	TenantUUID string `json:"tenant_uuid,omitempty"`
}

OpenRouterSyncRequest is the body for syncing a workspace with OpenRouter. TenantUUID is optional and only honoured when the caller is a SystemAdmin.

type OpenRouterSyncResponse added in v0.0.6 

type OpenRouterSyncResponse struct {
	TenantUUID    string `json:"tenant_uuid"`
	WorkspaceID   string `json:"workspace_id"`
	KeyHash       string `json:"key_hash"`
	Active        bool   `json:"active"`
	AlreadySynced bool   `json:"already_synced"`
	SyncedAt      string `json:"synced_at"`
}

OpenRouterSyncResponse is returned after a successful workspace sync.

type OpenRouterTopProvider added in v0.0.8 

type OpenRouterTopProvider struct {
	MaxCompletionTokens *int `json:"max_completion_tokens,omitempty"`
	IsModerated         bool `json:"is_moderated"`
}

OpenRouterTopProvider holds information about the primary provider of a model.

type Options 

type Options struct {
	// BaseURL overrides the default API base URL (https://synapse.wonit.net.br).
	// Useful for staging environments or self-hosted deployments.
	BaseURL string

	// Timeout sets the maximum duration for each HTTP request.
	// Defaults to 30 seconds when zero.
	Timeout time.Duration
}

Options configures the Synapse client at creation time. All fields are optional; zero values fall back to library defaults.

type ProviderCase 

type ProviderCase interface {
	// Get fetches a single provider by its UUID.
	Get(ctx context.Context, id string) (*ProviderResponseDto, error)

	// List returns a paginated list of all available providers.
	List(ctx context.Context, page, pageSize int) (*ProvidersResponseDto, error)
}

ProviderCase provides read operations for catalog integration providers.

type ProviderResponseDto 

type ProviderResponseDto struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	LogoURL   string `json:"logo_url"`
	Website   string `json:"website"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

ProviderResponseDto describes a catalog integration provider (e.g. Google, OpenAI).

type ProvidersResponseDto 

type ProvidersResponseDto struct {
	Page      int                   `json:"page"`
	Size      int                   `json:"size"`
	Providers []ProviderResponseDto `json:"providers"`
}

ProvidersResponseDto is the paginated response for the provider list.

type RestErrCause 

type RestErrCause struct {
	Field   string `json:"field"`
	Message string `json:"message"`
}

RestErrCause holds a field-level validation detail returned by the API.

type ServiceCase 

type ServiceCase interface {
	// Get fetches a single integration service by its UUID.
	Get(ctx context.Context, id string) (*ServiceResponseDto, error)

	// List returns a paginated list of all available integration services.
	List(ctx context.Context, page, pageSize int) (*ServicesResponseDto, error)
}

ServiceCase provides read operations for catalog integration services.

type ServiceResponseDto 

type ServiceResponseDto struct {
	ID               string `json:"id"`
	Name             string `json:"name"`
	Slug             string `json:"slug"`
	ProviderID       string `json:"provider_id"`
	BaseURL          string `json:"base_url"`
	AuthType         string `json:"auth_type"`
	DocumentationURL string `json:"documentation_url"`
}

ServiceResponseDto describes a catalog integration service.

type ServicesResponseDto 

type ServicesResponseDto struct {
	Page     int                  `json:"page"`
	Size     int                  `json:"size"`
	Services []ServiceResponseDto `json:"services"`
}

ServicesResponseDto is the paginated response for the service list.

type TenantCase 

type TenantCase interface {
	// Get fetches a tenant by UUID or document (CNPJ/CPF).
	// At least one of uuid or document must be non-empty.
	Get(ctx context.Context, uuid, document string) (*TenantResponseDto, error)

	// List returns a paginated list of all tenants.
	List(ctx context.Context, page, pageSize int) (*TenantsResponseDto, error)

	// Create registers a new tenant.
	Create(ctx context.Context, req CreateTenantRequestDto) (*TenantResponseDto, error)

	// Update partially updates the tenant identified by uuid.
	Update(ctx context.Context, uuid string, req UpdateTenantRequestDto) (*TenantResponseDto, error)

	// Delete permanently removes a tenant by UUID or document.
	// At least one of uuid or document must be non-empty.
	Delete(ctx context.Context, uuid, document string) error
}

TenantCase provides CRUD operations for tenants within the Synapse API.

type TenantResponseDto 

type TenantResponseDto struct {
	UUID      string `json:"uuid"`
	Name      string `json:"name"`
	Document  string `json:"document"`
	Live      bool   `json:"live"`
	CreatedAt string `json:"createAt"`
	UpdatedAt string `json:"updateAt"`
}

TenantResponseDto is the tenant shape returned by the API.

type TenantsResponseDto 

type TenantsResponseDto struct {
	Page    int                 `json:"page"`
	Size    int                 `json:"size"`
	Tenants []TenantResponseDto `json:"tenants"`
}

TenantsResponseDto is the paginated response for the tenant list.

type ToggleMcpIntegrationRequest added in v0.0.13 

type ToggleMcpIntegrationRequest struct {
	IsActive bool `json:"is_active"`
}

ToggleMcpIntegrationRequest is the body for activating or deactivating an MCP integration.

type TranscribeAudioFromURLRequest added in v0.0.5 

type TranscribeAudioFromURLRequest struct {
	// FileURL is the download link the server uses to fetch the audio file.
	FileURL string `json:"file_url"`
	// Model selects the transcription engine: whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe.
	Model string `json:"model,omitempty"`
	// Language hints the spoken language (e.g. "pt", "en", "es").
	Language string `json:"language,omitempty"`
	// Prompt is optional auxiliary text to improve transcription accuracy.
	Prompt string `json:"prompt,omitempty"`
}

TranscribeAudioFromURLRequest groups all parameters for the audio transcription endpoint when the audio file is fetched from a download URL by the server.

type TranscribeAudioRequest 

type TranscribeAudioRequest struct {
	// FileName is used as the multipart filename (e.g. "recording.mp3").
	FileName string
	// Content is the raw audio file bytes.
	Content []byte
	// Model selects the transcription engine: whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe.
	Model string
	// Language hints the spoken language (e.g. "pt", "en", "es").
	Language string
	// Prompt is optional auxiliary text to improve transcription accuracy.
	Prompt string
}

TranscribeAudioRequest groups all parameters for the audio transcription endpoint.

type TranscriptionResponse 

type TranscriptionResponse struct {
	Response string `json:"response"`
}

TranscriptionResponse is the response from the audio transcription endpoint.

type UpdateAgentPromptRequest added in v0.0.11 

type UpdateAgentPromptRequest struct {
	Name   *string `json:"name,omitempty"`
	Prompt *string `json:"prompt,omitempty"`
}

UpdateAgentPromptRequest is the body for updating name and/or content of a saved prompt.

type UpdateAgentRequest added in v0.0.6 

type UpdateAgentRequest struct {
	Name            *string   `json:"name,omitempty"`
	Description     *string   `json:"description,omitempty"`
	Model           *string   `json:"model,omitempty"`
	Prompt          *string   `json:"prompt,omitempty"`
	CollectionUUIDs *[]string `json:"collection_uuids,omitempty"`
	MaxContext      *int      `json:"max_context,omitempty"`
	Temperature     *float64  `json:"temperature,omitempty"`
	Active          *bool     `json:"active,omitempty"`
	McpEnabled      *bool     `json:"mcp_enabled,omitempty"`
	// McpIntegrationUUIDs: nil = no change, []string{} = remove all, ["uuid1"] = replace all.
	McpIntegrationUUIDs *[]string `json:"mcp_integration_uuids,omitempty"`
	// McpDisabledTools: nil = no change, []string{} = re-enable all tools, ["tool1"] = replace all.
	McpDisabledTools *[]string `json:"mcp_disabled_tools,omitempty"`
}

UpdateAgentRequest is used for both full (PUT) and partial (PATCH) agent updates. For PATCH, set exactly one field; for PUT you may set multiple. CollectionUUIDs: nil = no change, []string{} = remove all, ["uuid1","uuid2"] = replace all.

type UpdateMcpIntegrationRequest added in v0.0.13 

type UpdateMcpIntegrationRequest struct {
	Name        *string `json:"name,omitempty"`
	Description *string `json:"description,omitempty"`
	BaseURL     *string `json:"base_url,omitempty"`
	Token       *string `json:"token,omitempty"`
}

UpdateMcpIntegrationRequest is the body for partially updating an MCP integration.

type UpdateTenantRequestDto 

type UpdateTenantRequestDto struct {
	Name     string `json:"name,omitempty"`
	Document string `json:"document,omitempty"`
	// Live uses a pointer so false can be distinguished from omitted.
	Live *bool `json:"live,omitempty"`
}

UpdateTenantRequestDto is the body for partially updating a tenant.

type UpdateUserRequestDto 

type UpdateUserRequestDto struct {
	Name     string   `json:"name,omitempty"`
	Email    string   `json:"email,omitempty"`
	Password string   `json:"password,omitempty"`
	Role     UserRole `json:"role,omitempty"`
}

UpdateUserRequestDto is the body for partially updating a user.

type UploadDocumentRequest added in v0.0.6 

type UploadDocumentRequest struct {
	// TenantUUID is required when the caller is SYSTEM_ADMIN; ignored for other roles.
	TenantUUID *string
	// CollectionUUID is the UUID of the target Qdrant collection.
	CollectionUUID string
	// EmbedModel is the OpenRouter embedding model ID (e.g. "openai/text-embedding-ada-002").
	EmbedModel string
	// ChunkSize is the chunk size in characters (default: 1000 when zero).
	ChunkSize int
	// ChunkOverlap is the overlap between chunks in characters (default: 200 when zero).
	ChunkOverlap int
	// FileName is the multipart filename (e.g. "report.pdf").
	FileName string
	// Content is the raw file bytes (PDF, HTML, DOCX, XLSX, CSV).
	Content []byte
}

UploadDocumentRequest groups all parameters for the document upload endpoint.

type UserCase 

type UserCase interface {
	// Get returns a single user by UUID or email.
	// Pass the authenticated user's own identifier to fetch their profile.
	Get(ctx context.Context, identifier string) (*UserResponseDto, error)

	// List returns a paginated list of users.
	// SystemAdmin can filter by tenant using params.TenantIdentifier.
	List(ctx context.Context, params ListUsersParams) ([]UserResponseDto, error)

	// Create registers a new user under the given tenant identifier (UUID or document).
	Create(ctx context.Context, tenantIdentifier string, req CreateUserRequestDto) (*UserResponseDto, error)

	// Update partially updates a user identified by UUID or email.
	Update(ctx context.Context, identifier string, req UpdateUserRequestDto) (*UserResponseDto, error)

	// Delete permanently removes a user identified by UUID or email.
	Delete(ctx context.Context, identifier string) error
}

UserCase provides CRUD operations for users within the Synapse API.

type UserResponseDto 

type UserResponseDto struct {
	UUID       string   `json:"uuid"`
	Name       string   `json:"name"`
	Email      string   `json:"email"`
	Role       UserRole `json:"role"`
	TenantUUID string   `json:"tenant_uuid"`
	Live       bool     `json:"live"`
	CreatedAt  string   `json:"create_at"`
	UpdatedAt  string   `json:"update_at"`
}

UserResponseDto is the user shape returned by the API.

type UserRole 

type UserRole string

UserRole represents the access level of a user within the system. 

const (
	UserRoleSystemAdmin UserRole = "SYSTEM_ADMIN"
	UserRoleTenantAdmin UserRole = "TENANT_ADMIN"
	UserRoleTenantUser  UserRole = "TENANT_USER"
)

type VisionAICredentialsDTO 

type VisionAICredentialsDTO struct {
	Token string `json:"token"`
}

VisionAICredentialsDTO holds the API key for the Google Vision integration.

type VisionOCRFromURLRequest added in v0.0.5 

type VisionOCRFromURLRequest struct {
	FileURL string `json:"file_url"`
}

VisionOCRFromURLRequest is the body for the Google Vision OCR endpoint when the image is fetched by the server from a download URL.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.