CultivaCRM — API de Campañas Estable

// Branded types — el compilador rechaza mezclas de IDs
export type CampaignId = string & { readonly __brand: 'CampaignId' };
export type AdId       = string & { readonly __brand: 'AdId' };
export type ClientId  = string & { readonly __brand: 'ClientId' };

// Helpers de casting seguro
export const toCampaignId = (s: string): CampaignId => s as CampaignId;
export const toAdId       = (s: string): AdId       => s as AdId;

// Error de compilación si mezclas — previene bugs en producción
// getCampaign(adId)  ← TypeScript error ✓

// Discriminated union — cada estado lleva sus propios campos
export type CampaignStatus =
  | { type: 'draft' }
  | { type: 'scheduled';  scheduledAt: Date }
  | { type: 'active';     startedAt: Date;  budget: number }
  | { type: 'paused';    pausedAt: Date;   reason: string }
  | { type: 'completed'; endedAt: Date;    totalSpend: number }
  | { type: 'cancelled'; cancelledAt: Date; by: UserId };

// Input (lo que el cliente envía)
export interface CreateCampaignInput {
  name:        string;
  clientId:    ClientId;
  platform:    'META' | 'GOOGLE' | 'TIKTOK' | 'LINKEDIN';
  budget:      number;                   // EUR, centavos
  objective:   'AWARENESS' | 'LEADS' | 'CONVERSIONS';
  scheduledAt?: Date;                    // opcional — puede ser inmediata
  labels?:     string[];               // añadido en v1.1, sigue opcional
}

// Output (lo que el servidor devuelve — incluye campos generados)
export interface Campaign {
  id:          CampaignId;
  name:        string;
  clientId:    ClientId;
  platform:    'META' | 'GOOGLE' | 'TIKTOK' | 'LINKEDIN';
  budget:      number;
  objective:   'AWARENESS' | 'LEADS' | 'CONVERSIONS';
  status:      CampaignStatus;
  labels:      string[];
  createdAt:   Date;
  updatedAt:   Date;
  createdBy:   UserId;
}

// Este archivo define el contrato. El servidor lo implementa.
// El cliente (React / SDK / Zapier) lo consume. Nunca al revés.
export interface CampaignAPI {
  /** Crea campaña y devuelve el objeto completo con ID generado */
  createCampaign(input: CreateCampaignInput): Promise<Campaign>;

  /** Lista campañas con cursor-based pagination */
  listCampaigns(params: ListCampaignsParams): Promise<CursorPage<Campaign>>;

  /** Devuelve campaña o lanza NotFoundError */
  getCampaign(id: CampaignId): Promise<Campaign>;

  /** Actualización parcial — solo cambian los campos proporcionados */
  updateCampaign(id: CampaignId, input: UpdateCampaignInput): Promise<Campaign>;

  /** Delete idempotente — éxito aunque ya esté eliminada */
  deleteCampaign(id: CampaignId): Promise<void>;

  /** Sub-recurso: anuncios de una campaña */
  listAds(campaignId: CampaignId, params: ListAdsParams): Promise<CursorPage<Ad>>;
  createAd(campaignId: CampaignId, input: CreateAdInput): Promise<Ad>;

  /** Métricas agregadas — solo lectura */
  getMetrics(campaignId: CampaignId, params: MetricsParams): Promise<CampaignMetrics>;
}