diff --git a/internal/ports/ports.go b/internal/ports/ports.go new file mode 100644 index 0000000..77f148c --- /dev/null +++ b/internal/ports/ports.go @@ -0,0 +1,42 @@ +// Package ports defines the interfaces (hexagonal "ports") that the use-case +// engine depends on. Concrete adapters live in internal/adapters. The engine +// imports this package; it never imports a concrete provider, store, or model. +// See docs/architecture/architecture.md. +package ports + +import ( + "context" + + "gitea.d-ma.be/mathias/tapir/internal/domain" +) + +// VideoSource is a video platform Tapir watches (YouTube, Vimeo). +type VideoSource interface { + // ListSubscriptions returns the channels the user subscribes to. + ListSubscriptions(ctx context.Context, userID string) ([]domain.Subscription, error) + // NewVideos returns videos newly seen for the given subscription. + NewVideos(ctx context.Context, sub domain.Subscription) ([]domain.Video, error) + // FetchTranscript resolves a transcript, captions-first. Returns a + // Transcript with Source == SourceNone when none is available (not an error). + FetchTranscript(ctx context.Context, v domain.Video) (domain.Transcript, error) +} + +// Summarizer turns a transcript into a summary. Backed by the AI router +// (local Primary -> BYO Fallback). See docs/use-cases/ai_routing.feature. +type Summarizer interface { + Summarize(ctx context.Context, v domain.Video, t domain.Transcript) (domain.Summary, error) +} + +// Sink delivers a summary to a destination (user store, brain, ...). +// Implementations fail independently of one another. +type Sink interface { + // Name identifies the sink for delivery records ("store", "brain"). + Name() string + Deliver(ctx context.Context, s domain.Summary) error +} + +// SecretStore resolves opaque references to secret material (OAuth tokens, +// BYO keys). Backed by ESO/1Password. Tables store only the reference. +type SecretStore interface { + Get(ctx context.Context, ref string) (string, error) +}