/**
 * SignatureAPI Types
 *
 * Type definitions for SignatureAPI eSignature operations.
 * SignatureAPI uses raw fetch (no official SDK).
 */

/**
 * SignatureAPI credentials format
 * Stored in credentials table, encrypted
 */
export interface SignatureApiCredentials {
  apiKey: string // key_live_xxx or key_test_xxx
  apiUrl?: string // Optional override, defaults to https://api.signatureapi.com/v1
}

/**
 * Signature field configuration
 *
 * Note: The 'date' type is supported here for convenience but gets mapped
 * to 'recipient_completed_date' when sent to the SignatureAPI.
 */
export interface SignatureField {
  type: 'signature' | 'date' | 'text' | 'initials' // 'date' maps to 'recipient_completed_date'
  page: number // 1-indexed, or -1 for last page
  x: number // X position in points
  y: number // Y position in points
  width?: number // Field width
  height?: number // Field height
}

/**
 * Valid SignatureAPI field types
 *
 * Note: SignatureAPI does NOT support 'date' - use 'recipient_completed_date' instead.
 * Our workflow utility maps 'date' -> 'recipient_completed_date' for convenience.
 */
export type SignatureApiFieldType =
  | 'signature'
  | 'initials'
  | 'recipient_completed_date'
  | 'envelope_completed_date'
  | 'recipient_name'
  | 'recipient_email'
  | 'text'
  | 'text_input'
  | 'boxed_text_input'
  | 'multi_line_text_input'
  | 'checkbox'
  | 'dropdown'

/**
 * Signing place configuration
 */
export interface SigningPlace {
  recipientKey: string // Links to recipient
  type: SignatureApiFieldType
  page: number
  x: number
  y: number
  width?: number
  height?: number
  fontColor?: string // Hex color (e.g., '#FFFFFF' for white)
}

/**
 * Document for signing
 *
 * Note: SignatureAPI requires documents to be provided via URL (not base64).
 * Use a publicly accessible URL (e.g., Supabase signed URL).
 */
export interface EnvelopeDocument {
  name: string // Display name (e.g., 'proposal.pdf')
  url: string // Publicly accessible URL to PDF (NOT base64)
  places?: SigningPlace[] // Where to place signature fields
}

/**
 * Recipient/signer configuration
 */
export interface Recipient {
  key: string // Unique identifier (e.g., 'signer1')
  type: 'signer' | 'viewer' | 'approver'
  name: string
  email: string
  language?: string // 'en', 'es', 'fr', etc.
}

/**
 * Create envelope parameters
 */
export interface CreateEnvelopeParams {
  title: string // Envelope name
  message?: string // Custom message in emails
  documents: EnvelopeDocument[] // Documents to sign
  recipients: Recipient[] // Signers
  metadata?: Record<string, string> // Custom metadata
  webhookUrl?: string // Override default webhook
  routing?: 'parallel' | 'sequential' // Default: parallel
}

/**
 * Create envelope result
 */
export interface CreateEnvelopeResult {
  id: string // env_xxx
  status: string // 'processing', 'pending', etc.
  signingUrl?: string // URL for first signer
}

/**
 * Void envelope parameters
 */
export interface VoidEnvelopeParams {
  envelopeId: string
  reason?: string
}

/**
 * Void envelope result
 */
export interface VoidEnvelopeResult {
  id: string
  status: 'voided'
}

/**
 * Download document parameters
 */
export interface DownloadDocumentParams {
  envelopeId: string
  documentType?: 'combined' | 'original' | 'audit' // Default: combined
}

/**
 * Download document result
 */
export interface DownloadDocumentResult {
  content: Buffer // PDF content
  contentType: string // 'application/pdf'
  filename: string // Suggested filename
}

/**
 * Get envelope parameters
 */
export interface GetEnvelopeParams {
  envelopeId: string
}

/**
 * Get envelope result
 */
export interface GetEnvelopeResult {
  id: string
  title: string
  status: 'processing' | 'pending' | 'completed' | 'declined' | 'voided'
  createdAt: string
  completedAt?: string
  metadata: Record<string, string>
  recipients: Array<{
    key: string
    name: string
    email: string
    status: 'pending' | 'signed' | 'declined'
    signedAt?: string
  }>
}

/**
 * SignatureAPI error response
 */
export interface SignatureApiErrorResponse {
  error: {
    code: string
    message: string
    details?: unknown
  }
}

// ============================================================================
// Deliverable Types (for downloading signed documents)
// ============================================================================

/**
 * Deliverable type - what's included in the PDF
 */
export type DeliverableType = 'standard' | 'simple'

/**
 * Deliverable status - processing lifecycle
 */
export type DeliverableStatus = 'pending' | 'processing' | 'generated' | 'failed'

/**
 * Deliverable object returned by SignatureAPI
 */
export interface Deliverable {
  id: string // del_xxx
  envelope_id: string
  type: DeliverableType
  status: DeliverableStatus
  url: string | null // Pre-signed download URL (null until generated)
  password?: string
  created_at: string
  generated_at: string | null
  language?: string
  timezone?: string
  timestamp_format?: string
}

/**
 * List deliverables response
 */
export interface ListDeliverablesResponse {
  data: Deliverable[]
  links: {
    next?: string
    previous?: string
  }
}

/**
 * Create deliverable parameters
 */
export interface CreateDeliverableParams {
  envelopeId: string
  type?: DeliverableType // Default: standard
}

/**
 * Create deliverable result
 */
export type CreateDeliverableResult = Deliverable

/**
 * Get deliverable parameters
 */
export interface GetDeliverableParams {
  deliverableId: string
}

/**
 * Get deliverable result
 */
export type GetDeliverableResult = Deliverable
