vortex

README

Vortex Go SDK

A Go SDK for Vortex invitation management and JWT generation.

Installation

go get github.com/TeamVortexSoftware/vortex-go-sdk

Usage

Basic Setup

package main

import (
    "fmt"
    "log"

    "https://github.com/TeamVortexSoftware/vortex-go-sdk"
)

func main() {
    // Initialize the client
    client := vortex.NewClient("your-api-key")
}

JWT Generation

// Simple usage
user := &vortex.User{
    ID:          "user-123",
    Email:       "user@example.com",
    AdminScopes: []string{"autojoin"},
}

jwt, err := client.GenerateJWT(user, nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("JWT: %s\n", jwt)

// With additional properties
extra := map[string]interface{}{
    "role":       "admin",
    "department": "Engineering",
}

jwt, err = client.GenerateJWT(user, extra)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("JWT with extra: %s\n", jwt)

Invitation Management

Get Invitations by Target

// Get invitations for a specific target
invitations, err := client.GetInvitationsByTarget("email", "user@example.com")
if err != nil {
    log.Fatal(err)
}

for _, invitation := range invitations {
    fmt.Printf("Invitation ID: %s, Status: %s\n", invitation.ID, invitation.Status)
}

Accept Invitations

// Accept multiple invitations
target := vortex.InvitationTarget{
    Type:  "email",
    Value: "user@example.com",
}

result, err := client.AcceptInvitations([]string{"inv1", "inv2"}, target)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Accepted invitation: %s\n", result.ID)

Get Specific Invitation

// Get a specific invitation by ID
invitation, err := client.GetInvitation("invitation-id")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Invitation: %s\n", invitation.ID)

Revoke Invitation

// Revoke an invitation
err := client.RevokeInvitation("invitation-id")
if err != nil {
    log.Fatal(err)
}

fmt.Println("Invitation revoked successfully")

Group Operations

Get Invitations by Group

// Get invitations for a specific group
invitations, err := client.GetInvitationsByGroup("organization", "org123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Found %d invitations\n", len(invitations))

Delete Invitations by Group

// Delete all invitations for a group
err := client.DeleteInvitationsByGroup("organization", "org123")
if err != nil {
    log.Fatal(err)
}

fmt.Println("Group invitations deleted successfully")

Reinvite

// Send a reinvitation
invitation, err := client.Reinvite("invitation-id")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Reinvited: %s\n", invitation.ID)

Error Handling

The SDK returns custom error types that provide detailed information about API failures:

invitations, err := client.GetInvitationsByTarget("email", "user@example.com")
if err != nil {
    if apiErr, ok := err.(*vortex.APIError); ok {
        fmt.Printf("API Error: %s (Status: %d)\n", apiErr.Message, apiErr.StatusCode)
        fmt.Printf("Details: %s\n", apiErr.Details)
    } else {
        fmt.Printf("Unexpected error: %s\n", err)
    }
    return
}

Environment Variables

• VORTEX_API_BASE_URL - Base URL for Vortex API (default: https://api.vortexsoftware.com)

API Compatibility

This Go SDK provides identical functionality to the Node.js SDK:

• Same JWT generation algorithm with HMAC-SHA256
• Same API endpoints and request/response formats
• Same error handling patterns
• Compatible with Express, Fastify, Next.js, and Python SDKs

Data Types

Core Types

// InvitationTarget represents the target of an invitation
type InvitationTarget struct {
    Type  string `json:"type"`  // "email", "sms", "username", "phoneNumber"
    Value string `json:"value"`
}

// InvitationGroup represents a group associated with an invitation
type InvitationGroup struct {
    ID        string `json:"id"`        // Vortex internal UUID
    AccountID string `json:"accountId"` // Vortex account ID
    GroupID   string `json:"groupId"`   // Customer's group ID (the ID they provided)
    Type      string `json:"type"`      // Group type (e.g., "workspace", "team")
    Name      string `json:"name"`      // Group name
    CreatedAt string `json:"createdAt"` // Timestamp when the group was created
}

// InvitationResult represents a complete invitation object
type InvitationResult struct {
    ID                    string                 `json:"id"`
    AccountID             string                 `json:"accountId"`
    ClickThroughs         int                    `json:"clickThroughs"`
    ConfigurationAttributes map[string]interface{} `json:"configurationAttributes"`
    Attributes            map[string]interface{} `json:"attributes"`
    CreatedAt             string                 `json:"createdAt"`
    Deactivated           bool                   `json:"deactivated"`
    DeliveryCount         int                    `json:"deliveryCount"`
    DeliveryTypes         []string               `json:"deliveryTypes"`
    ForeignCreatorID      string                 `json:"foreignCreatorId"`
    InvitationType        string                 `json:"invitationType"`
    ModifiedAt            *string                `json:"modifiedAt"`
    Status                string                 `json:"status"`
    Target                []InvitationTarget     `json:"target"`
    Views                 int                    `json:"views"`
    WidgetConfigurationID string                 `json:"widgetConfigurationId"`
    ProjectID             string                 `json:"projectId"`
    Groups                []InvitationGroup      `json:"groups"`
    Accepts               []InvitationAcceptance `json:"accepts"`
}

JWT Types

// User represents user data for JWT generation
type User struct {
    ID          string   `json:"id"`
    Email       string   `json:"email"`
    AdminScopes []string `json:"adminScopes,omitempty"`
}

The AdminScopes field is optional. If provided, the full array will be included in the JWT payload as adminScopes.

Development

Building

go build ./...

Running Tests

go test ./...

Module Dependencies

• Go 1.18+
• github.com/google/uuid v1.6.0

License

MIT

Documentation

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type AcceptInvitationRequest
• type Client
  • func NewClient(apiKey string) *Client
  • func NewClientWithOptions(apiKey, baseURL string, httpClient *http.Client) *Client
  • func (c *Client) AcceptInvitations(invitationIDs []string, target InvitationTarget) (*InvitationResult, error)
  • func (c *Client) DeleteInvitationsByGroup(groupType, groupID string) error
  • func (c *Client) GenerateJWT(user *User, extra map[string]interface{}) (string, error)
  • func (c *Client) GetInvitation(invitationID string) (*InvitationResult, error)
  • func (c *Client) GetInvitationsByGroup(groupType, groupID string) ([]InvitationResult, error)
  • func (c *Client) GetInvitationsByTarget(targetType, targetValue string) ([]InvitationResult, error)
  • func (c *Client) Reinvite(invitationID string) (*InvitationResult, error)
  • func (c *Client) RevokeInvitation(invitationID string) error
• type Group
• type Identifier
• type InvitationAcceptance
• type InvitationGroup
• type InvitationResult
• type InvitationTarget
• type InvitationsResponse
• type JWTClaims
• type JWTHeader
• type JWTPayload
• type JWTPayloadSimple
• type User

Constants

const Version = "v1.1.1"

Version is the current version of the Vortex Go SDK

Types

type APIError

type APIError struct {
	StatusCode int    `json:"statusCode"`
	Message    string `json:"message"`
	Details    string `json:"details,omitempty"`
}

APIError represents an error from the Vortex API

func (*APIError) Error

func (e *APIError) Error() string

type AcceptInvitationRequest

type AcceptInvitationRequest struct {
	InvitationIDs []string         `json:"invitationIds"`
	Target        InvitationTarget `json:"target"`
}

AcceptInvitationRequest represents the request body for accepting invitations

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents a Vortex API client

func NewClient

func NewClient(apiKey string) *Client

NewClient creates a new Vortex client

func NewClientWithOptions

func NewClientWithOptions(apiKey, baseURL string, httpClient *http.Client) *Client

NewClientWithOptions creates a new Vortex client with custom options

func (*Client) AcceptInvitations

func (c *Client) AcceptInvitations(invitationIDs []string, target InvitationTarget) (*InvitationResult, error)

AcceptInvitations accepts multiple invitations

func (*Client) DeleteInvitationsByGroup

func (c *Client) DeleteInvitationsByGroup(groupType, groupID string) error

DeleteInvitationsByGroup deletes all invitations for a specific group

func (*Client) GenerateJWT

func (c *Client) GenerateJWT(user *User, extra map[string]interface{}) (string, error)

GenerateJWT creates a JWT token with the given user data and optional extra properties

The user parameter should contain the user's ID, email, and optional admin scopes. If adminScopes is provided, the full array will be included in the JWT payload. The extra parameter can contain additional properties to include in the JWT payload.

Example:

user := &vortex.User{
    ID:          "user-123",
    Email:       "user@example.com",
    AdminScopes: []string{"autojoin"},
}
jwt, err := client.GenerateJWT(user, nil)

Example with extra properties:

extra := map[string]interface{}{
    "role":       "admin",
    "department": "Engineering",
}
jwt, err := client.GenerateJWT(user, extra)

func (*Client) GetInvitation

func (c *Client) GetInvitation(invitationID string) (*InvitationResult, error)

GetInvitation retrieves a specific invitation by ID

func (*Client) GetInvitationsByGroup

func (c *Client) GetInvitationsByGroup(groupType, groupID string) ([]InvitationResult, error)

GetInvitationsByGroup retrieves invitations for a specific group

func (*Client) GetInvitationsByTarget

func (c *Client) GetInvitationsByTarget(targetType, targetValue string) ([]InvitationResult, error)

GetInvitationsByTarget retrieves invitations by target type and value

func (*Client) Reinvite

func (c *Client) Reinvite(invitationID string) (*InvitationResult, error)

Reinvite sends a reinvitation for a specific invitation

func (*Client) RevokeInvitation

func (c *Client) RevokeInvitation(invitationID string) error

RevokeInvitation revokes an invitation

type Group

type Group struct {
	Type    string  `json:"type"`
	ID      *string `json:"id,omitempty"`      // Legacy field (deprecated, use GroupID)
	GroupID *string `json:"groupId,omitempty"` // Preferred: Customer's group ID
	Name    string  `json:"name"`
}

Group represents a user group for JWT generation (input) For backward compatibility, supports both 'id' and 'groupId' fields

type Identifier

type Identifier struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

Identifier represents a user identifier (email, sms, etc.)

type InvitationAcceptance

type InvitationAcceptance struct {
	ID         string           `json:"id"`
	AccountID  string           `json:"accountId"`
	ProjectID  string           `json:"projectId"`
	AcceptedAt string           `json:"acceptedAt"`
	Target     InvitationTarget `json:"target"`
}

InvitationAcceptance represents an accepted invitation

type InvitationGroup

type InvitationGroup struct {
	ID        string `json:"id"`        // Vortex internal UUID
	AccountID string `json:"accountId"` // Vortex account ID
	GroupID   string `json:"groupId"`   // Customer's group ID (the ID they provided)
	Type      string `json:"type"`      // Group type (e.g., "workspace", "team")
	Name      string `json:"name"`      // Group name
	CreatedAt string `json:"createdAt"` // Timestamp when the group was created
}

InvitationGroup represents a group associated with an invitation This matches the MemberGroups table structure from the API response

type InvitationResult

type InvitationResult struct {
	ID                      string                 `json:"id"`
	AccountID               string                 `json:"accountId"`
	ClickThroughs           int                    `json:"clickThroughs"`
	ConfigurationAttributes map[string]interface{} `json:"configurationAttributes"`
	Attributes              map[string]interface{} `json:"attributes"`
	CreatedAt               string                 `json:"createdAt"`
	Deactivated             bool                   `json:"deactivated"`
	DeliveryCount           int                    `json:"deliveryCount"`
	DeliveryTypes           []string               `json:"deliveryTypes"`
	ForeignCreatorID        string                 `json:"foreignCreatorId"`
	InvitationType          string                 `json:"invitationType"`
	ModifiedAt              *string                `json:"modifiedAt"`
	Status                  string                 `json:"status"`
	Target                  []InvitationTarget     `json:"target"`
	Views                   int                    `json:"views"`
	WidgetConfigurationID   string                 `json:"widgetConfigurationId"`
	DeploymentID            string                 `json:"deploymentId"`
	ProjectID               string                 `json:"projectId"`
	Groups                  []InvitationGroup      `json:"groups"`
	Accepts                 []InvitationAcceptance `json:"accepts"`
	Scope                   *string                `json:"scope,omitempty"`
	ScopeType               *string                `json:"scopeType,omitempty"`
	Expired                 bool                   `json:"expired"`
	Expires                 *string                `json:"expires,omitempty"`
	Metadata                map[string]interface{} `json:"metadata,omitempty"`
	PassThrough             *string                `json:"passThrough,omitempty"`
}

InvitationResult represents a complete invitation object

type InvitationTarget

type InvitationTarget struct {
	Type  string `json:"type"`
	Value string `json:"value"`
}

InvitationTarget represents the target of an invitation

type InvitationsResponse

type InvitationsResponse struct {
	Invitations []InvitationResult `json:"invitations"`
}

InvitationsResponse represents the API response containing multiple invitations

type JWTClaims

type JWTClaims struct {
	UserID              string       `json:"userId"`
	UserEmail           string       `json:"userEmail,omitempty"`
	UserIsAutojoinAdmin *bool        `json:"userIsAutojoinAdmin,omitempty"`
	Groups              []Group      `json:"groups,omitempty"`
	Role                *string      `json:"role,omitempty"`
	Expires             int64        `json:"expires"`
	Identifiers         []Identifier `json:"identifiers,omitempty"`
}

JWTClaims represents the JWT payload claims Supports both new simplified format and legacy format

type JWTHeader

type JWTHeader struct {
	IAT int64  `json:"iat"`
	Alg string `json:"alg"`
	Typ string `json:"typ"`
	Kid string `json:"kid"`
}

JWTHeader represents the JWT header

type JWTPayload

type JWTPayload struct {
	UserID      string       `json:"userId"`
	Identifiers []Identifier `json:"identifiers"`
	Groups      []Group      `json:"groups"`
	Role        *string      `json:"role,omitempty"`
}

JWTPayload represents the payload for JWT generation (legacy format) Deprecated: Use JWTPayloadSimple for new implementations

type JWTPayloadSimple

type JWTPayloadSimple struct {
	UserID              string `json:"userId"`
	UserEmail           string `json:"userEmail"`
	UserIsAutojoinAdmin *bool  `json:"userIsAutojoinAdmin,omitempty"`
}

JWTPayloadSimple represents the simplified JWT payload (recommended)

type User

type User struct {
	ID          string   `json:"id"`
	Email       string   `json:"email"`
	AdminScopes []string `json:"adminScopes,omitempty"`
}

User represents user data for JWT generation