document

type BatchDocumentResult struct {
	Index    int
	Document *entity.DocumentWithRecipients
	Error    error
}

type CreateDocumentCommand struct {
	WorkspaceID               string
	TemplateVersionID         string
	Title                     string
	ClientExternalReferenceID *string
	InjectedValues            map[string]any
	Recipients                []DocumentRecipientCommand
	OperationType             entity.OperationType // CREATE, RENEW, or AMEND (defaults to CREATE)
	RelatedDocumentID         *string              // Required for RENEW/AMEND operations
}

type DocumentAccessUseCase interface {
	// GetPublicDocumentInfo returns minimal public info about a document (title, status).
	GetPublicDocumentInfo(ctx context.Context, documentID string) (*PublicDocumentInfoResponse, error)

	// RequestAccess validates email against document recipients and sends an access link.
	// Always returns nil to prevent email enumeration.
	RequestAccess(ctx context.Context, documentID, email string) error

	// RequestAccessByToken requests access using an existing (possibly expired)
	// token as the entrypoint. Always returns nil to prevent token/email enumeration.
	RequestAccessByToken(ctx context.Context, token, email string) error

	// RequestDirectAccess generates a tokenized signing URL directly for an
	// already-authenticated recipient (custom middleware path).
	// Returns empty URL when direct access cannot be granted.
	RequestDirectAccess(ctx context.Context, documentID, email string) (string, error)
}

type DocumentCreationResult struct {
	Document   *entity.Document
	Recipients []*entity.DocumentRecipient
	PDF        []byte
}

type DocumentRecipientCommand struct {
	RoleID string
	Name   string
	Email  string
}

type DocumentStatistics struct {
	Total      int            `json:"total"`
	ByStatus   map[string]int `json:"byStatus"`
	Pending    int            `json:"pending"`
	InProgress int            `json:"inProgress"`
	Completed  int            `json:"completed"`
	Declined   int            `json:"declined"`
}

type DocumentUseCase interface {
	// CreateAndSendDocument creates a document, generates the PDF, and sends it for signing.
	CreateAndSendDocument(ctx context.Context, cmd CreateDocumentCommand) (*entity.DocumentWithRecipients, error)

	// GetDocument retrieves a document by ID.
	GetDocument(ctx context.Context, id string) (*entity.Document, error)

	// GetDocumentWithRecipients retrieves a document with all its recipients.
	GetDocumentWithRecipients(ctx context.Context, id string) (*entity.DocumentWithRecipients, error)

	// ListDocuments lists documents in a workspace with optional filters.
	ListDocuments(ctx context.Context, workspaceID string, filters port.DocumentFilters) ([]*entity.DocumentListItem, error)

	// GetSigningURL retrieves the signing URL for a specific recipient.
	GetSigningURL(ctx context.Context, documentID, recipientID string) (string, error)

	// RefreshDocumentStatus polls the signing provider for the latest status.
	RefreshDocumentStatus(ctx context.Context, documentID string) (*entity.DocumentWithRecipients, error)

	// CancelDocument cancels/voids a document that is pending signatures.
	CancelDocument(ctx context.Context, documentID string) error

	// HandleWebhookEvent processes an incoming webhook event from the signing provider.
	HandleWebhookEvent(ctx context.Context, event *port.WebhookEvent) error

	// GetDocumentsByExternalRef finds documents by the client's external reference ID.
	GetDocumentsByExternalRef(ctx context.Context, workspaceID, externalRef string) ([]*entity.Document, error)

	// GetDocumentRecipients retrieves all recipients for a document with their role information.
	GetDocumentRecipients(ctx context.Context, documentID string) ([]*entity.DocumentRecipientWithRole, error)

	// GetDocumentStatistics returns document statistics for a workspace.
	GetDocumentStatistics(ctx context.Context, workspaceID string) (*DocumentStatistics, error)

	// GetDocumentPDF returns the signed PDF for a completed document.
	// Returns the PDF bytes, suggested filename, and any error.
	GetDocumentPDF(ctx context.Context, documentID string) ([]byte, string, error)

	// ExpireDocuments finds and expires documents that have passed their expiration time.
	ExpireDocuments(ctx context.Context, limit int) error

	// CreateDocumentsBatch creates multiple documents in a single batch.
	// Per-document errors are captured in results rather than failing the entire batch.
	CreateDocumentsBatch(ctx context.Context, cmds []CreateDocumentCommand) ([]BatchDocumentResult, error)

	// SendReminder sends reminder notifications to pending recipients of a document.
	SendReminder(ctx context.Context, documentID string) error
}

type FieldResponseInput struct {
	FieldID  string          `json:"fieldId"`
	Response json.RawMessage `json:"response"` // {"selectedOptionIds":[...]} or {"text":"..."}
}

type InteractiveFieldDTO struct {
	ID          string                          `json:"id"`
	FieldType   string                          `json:"fieldType"`
	Label       string                          `json:"label"`
	Required    bool                            `json:"required"`
	Options     []portabledoc.InteractiveOption `json:"options,omitempty"`
	Placeholder string                          `json:"placeholder,omitempty"`
	MaxLength   int                             `json:"maxLength,omitempty"`
}

type InternalCreateCommand struct {
	TenantCode      string             // From header X-Tenant-Code
	WorkspaceCode   string             // From header X-Workspace-Code
	DocumentType    string             // From header X-Document-Type
	Process         string             // From header X-Process (default: "default")
	ProcessType     string             // From header X-Process-Type (default: "CANONICAL_NAME")
	ExternalID      string             // From header X-External-ID
	TransactionalID string             // From header X-Transactional-ID
	Environment     entity.Environment // From header X-Environment
	ForceCreate     bool               // Optional body field. Defaults to false.
	SupersedeReason *string            // Optional body field.
	Metadata        map[string]string  // Optional body field. Round-trip metadata returned in completion event.
	Headers         map[string]string  // All HTTP headers
	PayloadRaw      []byte             // Unparsed payload object (passed to Mapper)
}

type InternalCreateResult struct {
	Document                     *entity.DocumentWithRecipients
	IdempotentReplay             bool
	SupersededPreviousDocumentID *string
}

type InternalDocumentUseCase interface {
	// CreateDocument creates or replays a document using the extension system (Mapper, Init, Injectors).
	CreateDocument(ctx context.Context, cmd InternalCreateCommand) (*InternalCreateResult, error)
}

type PreSigningFormDTO struct {
	DocumentTitle  string                `json:"documentTitle"`
	DocumentStatus string                `json:"documentStatus"`
	RecipientName  string                `json:"recipientName"`
	RecipientEmail string                `json:"recipientEmail"`
	RoleID         string                `json:"roleId"`
	Content        json.RawMessage       `json:"content"` // full portabledoc ProseMirror content
	Fields         []InteractiveFieldDTO `json:"fields"`  // fields for this role
}

type PreSigningUseCase interface {
	// GetPublicSigningPage returns the current signing page state for a given access token.
	// The response step depends on the document status and token type.
	GetPublicSigningPage(ctx context.Context, token string) (*PublicSigningResponse, error)

	// SubmitPreSigningForm submits field responses and returns the updated preview state.
	// Provider submission happens only after ProceedToSigning creates/reuses an attempt and River processes it.
	SubmitPreSigningForm(ctx context.Context, token string, responses []FieldResponseInput) (*PublicSigningResponse, error)

	// ProceedToSigning creates or reuses the active signing attempt and enqueues River work.
	// Accepts both SIGNING (Path A) and PRE_SIGNING (Path B) tokens; callers usually receive processing until River prepares signing refs.
	ProceedToSigning(ctx context.Context, token string) (*PublicSigningResponse, error)

	// RenderPreviewPDF renders the document PDF on-demand for preview (no storage).
	RenderPreviewPDF(ctx context.Context, token string) ([]byte, error)

	// CompleteEmbeddedSigning marks the token as used after signing is completed.
	CompleteEmbeddedSigning(ctx context.Context, token string) error

	// RefreshEmbeddedURL refreshes an expired embedded signing URL.
	RefreshEmbeddedURL(ctx context.Context, token string) (*PublicSigningResponse, error)

	// DownloadCompletedPDF downloads the signed PDF for a completed document when
	// the token holder is authorized.
	DownloadCompletedPDF(ctx context.Context, token string) ([]byte, string, error)

	// InvalidateTokens invalidates all active tokens for a document.
	// Requires the document to be in AWAITING_INPUT status.
	InvalidateTokens(ctx context.Context, documentID string) error
}

type PublicDocumentInfoResponse struct {
	DocumentID    string `json:"documentId"`
	DocumentTitle string `json:"documentTitle"`
	Status        string `json:"status"` // "active", "completed", "expired"
}

type PublicSigningResponse struct {
	// Step indicates the current signing flow step.
	// "preview" = show form (Path B) or PDF preview (Path A)
	// "processing" = River is preparing/retrying/reconciling the active attempt
	// "signing" = show embedded signing iframe
	// "waiting" = waiting for previous signers
	// "completed" = signing completed
	// "declined" = document was declined
	// "document_updated" = token points at a superseded/invalidated attempt
	// "unavailable" = active attempt failed or requires review
	Step string `json:"step"`

	// Form contains the pre-signing form data (step=preview, Path B).
	Form *PreSigningFormDTO `json:"form,omitempty"`

	// PdfURL is the URL to download the rendered PDF for preview (step=preview, Path A).
	PdfURL string `json:"pdfUrl,omitempty"`

	// EmbeddedSigningURL is the URL to load in an iframe (step=signing).
	EmbeddedSigningURL string `json:"embeddedSigningUrl,omitempty"`

	// DocumentTitle is the document title.
	DocumentTitle string `json:"documentTitle"`

	// RecipientName is the signer's display name.
	RecipientName string `json:"recipientName"`

	// WaitingForPrevious is true when waiting for earlier signers (step=waiting).
	WaitingForPrevious bool `json:"waitingForPrevious,omitempty"`

	// SigningPosition is the signer's position in signing order (step=waiting).
	SigningPosition int `json:"signingPosition,omitempty"`

	// TotalSigners is the total number of signers (step=waiting).
	TotalSigners int `json:"totalSigners,omitempty"`

	// FallbackURL is a direct signing URL when embedding is not supported.
	FallbackURL string `json:"fallbackUrl,omitempty"`

	// DocumentStatus is the canonical internal document status.
	DocumentStatus string `json:"documentStatus,omitempty"`

	// HasCurrentUserSigned indicates whether the token recipient has signed.
	HasCurrentUserSigned bool `json:"hasCurrentUserSigned"`

	// CanSign indicates whether this recipient can still proceed in signing flow.
	CanSign bool `json:"canSign"`

	// CanDownload indicates whether this recipient can download the completed PDF.
	CanDownload bool `json:"canDownload"`

	// DownloadURL is the endpoint for downloading the completed signed PDF.
	DownloadURL string `json:"downloadUrl,omitempty"`
}

type RenderDocumentRequest struct {
	TemplateVersionID string
	InjectedValues    map[string]any
	SignerRoleValues  map[string]port.SignerRoleValue
}

type RenderDocumentResult struct {
	PDF      []byte
	Filename string
}

type SigningSessionPrincipal struct {
	Email    string         `json:"email"`
	Subject  string         `json:"subject,omitempty"`
	Provider string         `json:"provider,omitempty"`
	Extra    map[string]any `json:"extra,omitempty"`
}

type SigningSessionResponse struct {
	SessionURL  string `json:"sessionUrl"`
	Step        string `json:"step"`
	CanSign     bool   `json:"canSign"`
	CanDownload bool   `json:"canDownload"`
	DownloadURL string `json:"downloadUrl,omitempty"`
}

type SigningSessionUseCase interface {
	// CreateOrGetSession returns a reusable tokenized session URL for a
	// recipient authenticated by JWT/custom auth middleware.
	CreateOrGetSession(ctx context.Context, documentID string, principal *SigningSessionPrincipal) (*SigningSessionResponse, error)
}

type UpdateDocumentStatusCommand struct {
	ProviderDocumentID  string
	ProviderRecipientID string
	DocumentStatus      *entity.DocumentStatus
	RecipientStatus     *entity.RecipientStatus
}

type WebhookEventData struct {
	EventType           string          `json:"eventType"`
	ProviderDocumentID  string          `json:"providerDocumentId"`
	ProviderRecipientID string          `json:"providerRecipientId,omitempty"`
	DocumentStatus      *string         `json:"documentStatus,omitempty"`
	RecipientStatus     *string         `json:"recipientStatus,omitempty"`
	Timestamp           string          `json:"timestamp"`
	RawPayload          json.RawMessage `json:"rawPayload,omitempty"`
}