callsystem

type Call interface {
	// ID returns the call identifier.
	ID() string

	// Direction returns inbound or outbound.
	Direction() CallDirection

	// Status returns the current call status.
	Status() CallStatus

	// From returns the caller ID.
	From() string

	// To returns the called number.
	To() string

	// StartTime returns when the call started.
	StartTime() time.Time

	// Duration returns the call duration.
	Duration() time.Duration

	// Answer answers an inbound call.
	Answer(ctx context.Context) error

	// Hangup ends the call.
	Hangup(ctx context.Context) error

	// Transport returns the underlying transport connection.
	Transport() transport.Connection

	// AttachAgent attaches a voice agent to handle the call.
	AttachAgent(ctx context.Context, session agent.Session) error

	// DetachAgent detaches the voice agent.
	DetachAgent(ctx context.Context) error
}

type CallDirection string

type CallHandler func(call Call) error

type CallOption func(*CallOptions)

type CallOptions struct {
	From           string
	Timeout        time.Duration
	MachineDetect  bool
	Record         bool
	Whisper        string
	AgentConfig    *agent.Config
	StatusCallback string
	Observer       observability.VoiceObserver
}

type CallStatus string

type CallSystem interface {
	// Name returns the call system name.
	Name() string

	// Configure configures the call system.
	Configure(config CallSystemConfig) error

	// OnIncomingCall sets the handler for incoming calls.
	OnIncomingCall(handler CallHandler)

	// MakeCall initiates an outbound call.
	MakeCall(ctx context.Context, to string, opts ...CallOption) (Call, error)

	// GetCall retrieves a call by ID.
	GetCall(ctx context.Context, callID string) (Call, error)

	// ListCalls lists active calls.
	ListCalls(ctx context.Context) ([]Call, error)

	// Close shuts down the call system.
	Close() error
}

type CallSystemConfig struct {
	// AccountSID is the account identifier (Twilio, etc).
	AccountSID string

	// AuthToken is the authentication token.
	AuthToken string //nolint:gosec // G117: field intentionally stores credential

	// APIKey is an API key (alternative to AuthToken).
	APIKey string //nolint:gosec // G117: field intentionally stores credential

	// APISecret is the API secret.
	APISecret string //nolint:gosec // G117: field intentionally stores credential

	// WebhookURL is the URL for incoming webhooks.
	WebhookURL string

	// PhoneNumber is the default outbound caller ID.
	PhoneNumber string

	// Region is the service region.
	Region string

	// Observer receives voice events for observability.
	// If nil, no events are emitted.
	Observer observability.VoiceObserver
}

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

type Meeting interface {
	// ID returns the meeting identifier.
	ID() string

	// Title returns the meeting title.
	Title() string

	// Participants returns current participants.
	Participants() []Participant

	// Transport returns the transport connection.
	Transport() transport.Connection

	// AttachAgent attaches a voice agent to the meeting.
	AttachAgent(ctx context.Context, session agent.Session) error

	// DetachAgent detaches the voice agent.
	DetachAgent(ctx context.Context) error

	// Leave leaves the meeting.
	Leave(ctx context.Context) error
}

type MeetingOption func(*meetingOptions)

type MeetingSystem interface {
	// Name returns the meeting system name.
	Name() string

	// JoinMeeting joins an existing meeting.
	JoinMeeting(ctx context.Context, meetingID string, opts ...MeetingOption) (Meeting, error)

	// LeaveMeeting leaves a meeting.
	LeaveMeeting(ctx context.Context, meetingID string) error

	// ListMeetings lists active meetings.
	ListMeetings(ctx context.Context) ([]Meeting, error)
}

type ObservableCallSystem interface {
	CallSystem
	observability.Observable
}

type Participant struct {
	// ID is the participant identifier.
	ID string

	// Name is the participant display name.
	Name string

	// IsMuted indicates if audio is muted.
	IsMuted bool

	// IsBot indicates if this is a bot participant.
	IsBot bool
}

type SMSMessage struct {
	// ID is the provider-specific message identifier.
	ID string

	// To is the recipient phone number (E.164 format).
	To string

	// From is the sender phone number (E.164 format).
	From string

	// Body is the message content.
	Body string

	// Status is the message delivery status.
	Status string
}

type SMSProvider interface {
	// SendSMS sends an SMS message.
	SendSMS(ctx context.Context, to, body string) (*SMSMessage, error)

	// SendSMSFrom sends an SMS message from a specific number.
	SendSMSFrom(ctx context.Context, to, from, body string) (*SMSMessage, error)
}