hooks

type CallMeta struct {
	CallID        string
	CorrelationID string // inbound Call-ID for outbound transfer legs
	Direction     Direction
	Scenario      string // e.g. outbound.ScenarioTransferAgent — opaque string avoids import cycles
	TenantID      uint
	RemoteAddr    string
	LocalIP       string
	Codec         string
	StartedAt     time.Time
}

type Direction string

type HangupInitiator string

type HangupMeta struct {
	Initiator HangupInitiator
	SIPCode   int    // final SIP status when known (0 if N/A)
	Reason    string // SIP phrase or internal reason
	Duration  time.Duration
	EndedAt   time.Time
}

type LifecycleSink interface {
	// OnRinging is an optional early hook (180/183). No-op default: use NopLifecycle.
	OnRinging(meta CallMeta)

	// OnEstablished fires after ACK (inbound UAS) or outbound 200+ACK.
	OnEstablished(meta CallMeta)

	// OnTransferStarted fires when a B2BUA transfer dial begins (REFER or AI transfer).
	OnTransferStarted(inbound CallMeta, targetURI string)

	// OnBridgeStarted fires when two-leg media bridge is active.
	OnBridgeStarted(inboundCallID, outboundCallID string)

	// OnBye fires when a dialog ends cleanly (BYE completed or local teardown).
	OnBye(meta CallMeta, hangup HangupMeta, recording RecordingArtifact)

	// OnFailed fires when setup or transfer fails before a stable bridge.
	OnFailed(meta CallMeta, hangup HangupMeta)
}

type NopLifecycle struct{}

type NopRecording struct{}

type RecordingArtifact struct {
	CallID     string
	Format     RecordingFormat
	Payload    []byte // SN3 blob or app-defined PCM container
	Codec      string
	SampleRate int
	Channels   int // 1 mono taps, 2 when stereo PCM sink merged
}

type RecordingChannel int

type RecordingFormat string

type RecordingResult struct {
	URL       string
	ObjectKey string
	Bytes     int64
}

type RecordingSink interface {
	// BeginRecording returns false to disable taps for this call (SN3 capture may still run in session).
	BeginRecording(meta CallMeta, sampleRate int, codec string) bool

	// AppendPCM delivers mono PCM16 LE frames during the call (transfer bridge / voice pipeline).
	// Implementations must copy pcm if retained beyond the call.
	AppendPCM(callID string, ch RecordingChannel, pcm []byte)

	// FinishRecording is invoked once at hangup with the SN3 artifact (may be nil/empty).
	// Return a durable reference (URL, object key) for LifecycleSink.OnBye if needed.
	FinishRecording(ctx context.Context, artifact RecordingArtifact) (RecordingResult, error)
}

type Registry struct {
	Lifecycle LifecycleSink
	Recording RecordingSink
}