Types

type Event interface {
    // Type returns the event type
    Type() EventType

    // Timestamp returns the event timestamp (Unix milliseconds)
    Timestamp() *int64

    // SetTimestamp sets the event timestamp
    SetTimestamp(timestamp int64)

    // ThreadID returns the thread ID associated with this event
    ThreadID() string

    // RunID returns the run ID associated with this event
    RunID() string

    // Validate validates the event structure and content
    Validate() error

    // ToJSON serializes the event to JSON for cross-SDK compatibility
    ToJSON() ([]byte, error)

    // GetBaseEvent returns the underlying base event
    GetBaseEvent() *BaseEvent
}

// Working with events through the interface
func handleEvent(event events.Event) error {
    // Validate the event
    if err := event.Validate(); err != nil {
        return fmt.Errorf("invalid event: %w", err)
    }

    // Check event type
    switch event.Type() {
    case events.EventTypeTextMessageStart:
        fmt.Printf("Message started at %d\n", *event.Timestamp())
    case events.EventTypeToolCallStart:
        fmt.Printf("Tool call in thread %s\n", event.ThreadID())
    }

    // Serialize to JSON
    jsonData, err := event.ToJSON()
    if err != nil {
        return err
    }

    return nil
}

type BaseEvent struct {
    EventType   EventType `json:"type"`
    TimestampMs *int64    `json:"timestamp,omitempty"`
    RawEvent    any       `json:"rawEvent,omitempty"`
}

// Creating a base event
baseEvent := events.NewBaseEvent(events.EventTypeTextMessageStart)

// All specific events embed BaseEvent
type TextMessageStartEvent struct {
    *BaseEvent
    MessageID string  `json:"messageId"`
    Role      *string `json:"role,omitempty"`
}

// The BaseEvent provides common functionality
event := &TextMessageStartEvent{
    BaseEvent: baseEvent,
    MessageID: "msg-123",
}

type TextMessageStartEvent struct {
    *BaseEvent
    MessageID string  `json:"messageId"`
    Role      *string `json:"role,omitempty"`
}

type TextMessageContentEvent struct {
    *BaseEvent
    MessageID string `json:"messageId"`
    Delta     string `json:"delta"`
}

type TextMessageEndEvent struct {
    *BaseEvent
    MessageID string `json:"messageId"`
}

// Creating and streaming a text message
messageID := events.GenerateMessageID()

// Start the message
startEvent := events.NewTextMessageStartEvent(messageID, events.WithRole("assistant"))

// Stream content
contentEvent1 := events.NewTextMessageContentEvent(messageID, "Hello, ")
contentEvent2 := events.NewTextMessageContentEvent(messageID, "how can I help you?")

// End the message
endEvent := events.NewTextMessageEndEvent(messageID)

// Validate and send events
for _, event := range []events.Event{startEvent, contentEvent1, contentEvent2, endEvent} {
    if err := event.Validate(); err != nil {
        log.Printf("Invalid event: %v", err)
        continue
    }
    // Send event to stream...
}

type ToolCallStartEvent struct {
    *BaseEvent
    ToolCallID string `json:"toolCallId"`
    ToolName   string `json:"toolName"`
}

type ToolCallArgsEvent struct {
    *BaseEvent
    ToolCallID string `json:"toolCallId"`
    Args       string `json:"args"`
}

type ToolCallEndEvent struct {
    *BaseEvent
    ToolCallID string `json:"toolCallId"`
}

type ToolCallResultEvent struct {
    *BaseEvent
    ToolCallID string  `json:"toolCallId"`
    Result     any     `json:"result"`
    Error      *string `json:"error,omitempty"`
}

type StateSnapshotEvent struct {
    *BaseEvent
    State any `json:"state"`
}

type StateDeltaEvent struct {
    *BaseEvent
    Delta     any     `json:"delta"`
    Operation *string `json:"operation,omitempty"`
}

// Creating state events
type AgentState struct {
    Counter int    `json:"counter"`
    Status  string `json:"status"`
}

// Snapshot event with complete state
state := &AgentState{Counter: 5, Status: "processing"}
snapshotEvent := events.NewStateSnapshotEvent(state)

// Delta event with incremental update
delta := map[string]interface{}{
    "counter": 6,
}
deltaEvent := events.NewStateDeltaEvent(delta, events.WithOperation("merge"))

// Generate a unique thread ID (format: "thread-{uuid}")
threadID := events.GenerateThreadID()

// Generate a unique run ID (format: "run-{uuid}")
runID := events.GenerateRunID()

// Generate a unique message ID (format: "msg-{uuid}")
messageID := events.GenerateMessageID()

// Generate a unique tool call ID (format: "tool-{uuid}")
toolCallID := events.GenerateToolCallID()

// Generate a unique step ID (format: "step-{uuid}")
stepID := events.GenerateStepID()

// Use timestamp-based IDs
generator := events.NewTimestampIDGenerator("myapp")
events.SetDefaultIDGenerator(generator)

// Now all ID generation will use timestamp format
// Format: "myapp-{type}-{timestamp}-{shortUUID}"
messageID := events.GenerateMessageID() // "myapp-msg-1709123456789-a1b2c3d4"

// Or implement your own IDGenerator interface
type CustomIDGenerator struct{}

func (g *CustomIDGenerator) GenerateMessageID() string {
    return fmt.Sprintf("custom-msg-%d", time.Now().Unix())
}
// ... implement other methods

events.SetDefaultIDGenerator(&CustomIDGenerator{})

// Example showing how events compose
type TextMessageStartEvent struct {
    *BaseEvent                    // Embeds base event fields and methods
    MessageID string  `json:"messageId"`
    Role      *string `json:"role,omitempty"`
}

// The event automatically inherits all BaseEvent methods
event := &TextMessageStartEvent{
    BaseEvent: events.NewBaseEvent(events.EventTypeTextMessageStart),
    MessageID: "msg-123",
}

// Can call both BaseEvent and specific methods
event.SetTimestamp(time.Now().UnixMilli()) // From BaseEvent
err := event.Validate()                     // TextMessageStartEvent override