/**
 * Shared SignatureAPI param/result types (browser-safe)
 *
 * These types define the public interface for SignatureAPI eSignature operations --
 * used by both the server-side adapter and the SDK typed wrappers. They contain
 * zero Node.js dependencies and are safe to import in any environment.
 *
 * Uses Uint8Array instead of Buffer for browser safety.
 *
 * Server-internal types (API response shapes, credentials) remain in
 * server/adapters/signature-api/fetch/utils/types.ts
 */

// ============================================================================
// Helper Types
// ============================================================================

/**
 * Valid SignatureAPI field types
 */
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
  type: SignatureApiFieldType
  page: number
  x: number
  y: number
  width?: number
  height?: number
  fontColor?: string
}

/**
 * Document for signing
 */
export interface EnvelopeDocument {
  name: string
  url: string
  places?: SigningPlace[]
}

/**
 * Recipient/signer configuration
 */
export interface Recipient {
  key: string
  type: 'signer' | 'viewer' | 'approver'
  name: string
  email: string
  language?: string
}

// ============================================================================
// Create Envelope
// ============================================================================

/**
 * Create envelope parameters
 */
export interface CreateEnvelopeParams {
  title: string
  message?: string
  documents: EnvelopeDocument[]
  recipients: Recipient[]
  metadata?: Record<string, string>
  webhookUrl?: string
  routing?: 'parallel' | 'sequential'
}

/**
 * Create envelope result
 */
export interface CreateEnvelopeResult {
  id: string
  status: string
  signingUrl?: string
}

// ============================================================================
// Void Envelope
// ============================================================================

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

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

// ============================================================================
// Download Document
// ============================================================================

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

/**
 * Download document result (Uint8Array for browser safety)
 */
export interface DownloadDocumentResult {
  content: Uint8Array
  contentType: string
  filename: string
}

// ============================================================================
// Get Envelope
// ============================================================================

/**
 * 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
  }>
}
