Saltar al contenido principal

Suscripciones de creador — Referencia técnica

← Volver a Suscripciones de creador

Dónde vive esto​

Backend

Frontend

Checklist de implementación técnica​

  • createTier / updateTier / activateTier / deactivateTier / deleteTier — resolvers conectados en subscription-tier.resolver.js; la gestión de niveles del frontend ahora vive en Configuración → Suscripciones (SubscriptionsSettingsPage.tsx)
  • activeCreatorTiers / subscribe — resolvers conectados en subscription-tier.resolver.js/user-subscription.resolver.js; el frontend ahora renderiza un selector de niveles y el llamado a la acción "Suscribirse" en PublicProfilePage.tsx, además de la opción de visibilidad de publicación Subscribers en CreatePostModal.tsx
  • mySubscriptions / cancelSubscription / renewSubscription / isSubscribedTo / subscriberCount — resolvers conectados en user-subscription.resolver.js; el frontend está conectado a través de SubscriptionsSettingsPage.tsx (listar/cancelar/renovar) y PublicProfilePage.tsx (isSubscribedTo)
  • mySubscribers — resolver conectado en user-subscription.resolver.js; no se encontró ninguna pantalla en el frontend para la lista de suscriptores del lado del creador
  • subscriberRetention — resolver conectado en user-subscription.resolver.js, calculado por userSubscriptionManager.getSubscriberRetention (conteos de nuevos/perdidos/activos agrupados por mes); gráfico en el frontend en InsightsAndToolsPage.tsx
  • subscribeToConversation / hasConversationAccess / cancelConversationSubscription — resolvers conectados en conversation-subscription.resolver.js; el frontend está conectado a través de useConversationSubscriptionAccess.ts → ChatView.tsx/SubscriptionPaywall.tsx y la lista de grupos de pago en PublicProfilePage.tsx
  • enableConversationSubscription / disableConversationSubscription — resolvers conectados; botones en el frontend en ConversationDetailsPanel.tsx (handleEnableSubscription/handleDisableSubscription) permiten al creador de un chat grupal activar/desactivar el acceso de pago
  • conversationSubscriptionStats / mySubscriptionEarnings / conversationSubscribers / grantFreeConversationAccess — resolvers conectados en conversation-subscription.resolver.js; no se encontró uso en el frontend de ninguno de estos campos
  • Restricción de publicaciones con visibility: subscribers — el valor del enum se puede seleccionar en CreatePostModal.tsx, y post.manager.js (apps/backend/managers/post-managers/post.manager.js, líneas ~572-577) verifica visibility === 'subscribers' mediante userSubscriptionManager.isSubscribed(...), lanzando un error si el espectador no está suscrito — aplicado del lado del servidor
  • Ofertas de suscripción (SubscriptionOffer) — enlaces de prueba gratuita y descuento para un nivel de perfil o un grupo de pago. El CRUD del creador (createSubscriptionOffer/updateSubscriptionOffer/deactivateSubscriptionOffer/deleteSubscriptionOffer) está conectado en SubscriptionOffersPage.tsx (Configuración → Ofertas de suscripción); el canje público (offerByToken/redeemSubscriptionTrial) está conectado en OfferRedemptionPage.tsx en /offer/[token]; applicableDiscount está conectado a través de useApplicableDiscount.ts/DiscountedPrice.tsx para mostrar precios con descuento en los llamados a la acción de suscripción

Niveles de suscripción (SubscriptionTier)​

CampoDescripción
nameNombre del nivel (p. ej. "Fan", "VIP")
descriptionDescripción de los beneficios
coinPricePrecio en monedas por período
benefitsLista de cadenas de beneficios
isActiveIndica si el nivel está abierto a nuevos suscriptores
subscriberCountSuscriptores activos actuales

activeCreatorTiers devuelve los niveles que un creador ha publicado y puesto a disposición. Úsalo para renderizar la página de "Suscribirse" en el perfil de un creador. myTiers devuelve los propios niveles del creador autenticado — usado en la pantalla de configuración del creador.

createTier agrega un nuevo nivel. El nivel empieza inactivo; llama a activateTier para abrirlo a suscriptores. updateTier edita el nombre, la descripción, el precio o los beneficios de un nivel. deactivateTier deja de aceptar nuevas suscripciones pero no cancela las existentes. deleteTier elimina permanentemente el nivel — solo es posible si no tiene suscriptores activos.

query CreatorTiers($creatorId: ID!) {
  activeCreatorTiers(creatorId: $creatorId) {
    id name description coinPrice benefits subscriberCount
  }
}

query MyTiers { myTiers { id name subscriberCount } }

mutation CreateTier($input: SubscriptionTierCreateInput!) { createTier(input: $input) { id name coinPrice } }
mutation UpdateTier($tierId: ID!, $input: SubscriptionTierUpdateInput!) { updateTier(tierId: $tierId, input: $input) { id } }
mutation ActivateTier($tierId: ID!)   { activateTier(tierId: $tierId) { isActive } }
mutation DeactivateTier($tierId: ID!) { deactivateTier(tierId: $tierId) { isActive } }
mutation DeleteTier($tierId: ID!)     { deleteTier(tierId: $tierId) }

Suscripciones de usuario (UserSubscription)​

mySubscriptions devuelve todas las suscripciones a creadores del usuario actual — tanto activas como canceladas. currentPeriodStart / currentPeriodEnd indican al cliente cuándo comenzó y termina el ciclo de facturación actual.

mySubscribers es la vista del lado del creador: quién está suscrito a ti y en qué nivel.

isSubscribedTo es una verificación booleana ligera — úsala para restringir contenido exclusivo sin obtener el objeto de suscripción completo. subscriberCount devuelve un único entero para la fila de estadísticas del perfil del creador.

subscribe crea una nueva suscripción pagando el coinPrice del nivel. Las monedas se deducen de inmediato. cancelSubscription marca la suscripción como cancelled — el acceso continúa hasta currentPeriodEnd. renewSubscription renueva manualmente una suscripción cancelada o expirada.

enum SubscriptionStatus { active  cancelled  expired  pending }

query MySubscriptions($status: SubscriptionStatus) {
  mySubscriptions(status: $status) {
    id status currentPeriodStart currentPeriodEnd
    creator { username profilePicture }
    tier { name coinPrice benefits }
  }
}

query MySubscribers($status: SubscriptionStatus) {
  mySubscribers(status: $status) {
    id status subscriber { username }
    tier { name }
  }
}

# Booleano ligero para restringir contenido exclusivo
query IsSubscribedTo($creatorId: ID!) { isSubscribedTo(creatorId: $creatorId) }
query SubscriberCount($creatorId: ID!) { subscriberCount(creatorId: $creatorId) }

# Iniciar una suscripción (deduce coinPrice de la billetera de inmediato)
mutation Subscribe($input: UserSubscriptionCreateInput!)  { subscribe(input: $input) { id status } }

# Cancelar — el acceso continúa hasta el final del período actual
mutation CancelSubscription($subscriptionId: ID!)         { cancelSubscription(subscriptionId: $subscriptionId) { status } }

# Renovar una suscripción cancelada o expirada
mutation RenewSubscription($subscriptionId: ID!)          { renewSubscription(subscriptionId: $subscriptionId) { status } }

subscriberRetention devuelve un SubscriberRetentionPoint por mes calendario (6 por defecto, máximo 24) con los conteos de suscriptores nuevos/perdidos/activos al final, y las tasas de pérdida/retención, para las suscripciones del perfil del creador autenticado:

query SubscriberRetention($months: Int) {
  subscriberRetention(months: $months) {
    month newSubscribers churned activeAtEnd churnRate retentionRate
  }
}

Ofertas de suscripción (SubscriptionOffer)​

Un creador puede generar un enlace compartible que otorga ya sea una prueba gratuita (kind: trial) o un descuento en el primer pago (kind: discount) para un nivel de perfil (scope: profile) o una conversación grupal de pago (scope: group). Las ofertas están limitadas por maxRedemptions, pueden expirar (expiresAt), y apuntan a una audience: new (nunca se ha suscrito), returning (se suscribió antes, ahora inactivo), o all. El canje se rastrea por usuario para que la misma oferta no pueda canjearse dos veces.

mutation CreateSubscriptionOffer($input: CreateOfferInput!) {
  createSubscriptionOffer(input: $input) { id token }
}

query MyOffers($scope: String, $kind: String) {
  myOffers(scope: $scope, kind: $kind) {
    id kind scope token name trialDays discountType discountValue
    audience maxRedemptions redemptionCount expiresAt isActive
  }
}

# Vista previa pública — no requiere autenticación — renderizada en /offer/<token>
query OfferByToken($token: String!) {
  offerByToken(token: $token) {
    kind scope name trialDays discountType discountValue
    coinPrice isActive expired capReached redemptionsLeft
  }
}

# Canjear un enlace de prueba gratuita (otorga acceso que expira al final de la prueba, sin cobro automático)
mutation RedeemSubscriptionTrial($token: String!) {
  redeemSubscriptionTrial(token: $token) { success scope trialEndsAt }
}

# El mejor descuento que el espectador actual obtendría en este momento, si existe alguno
query ApplicableDiscount($scope: String!, $subscriptionTierId: ID, $conversationId: ID) {
  applicableDiscount(scope: $scope, subscriptionTierId: $subscriptionTierId, conversationId: $conversationId) {
    discountType discountValue discountAmount originalPrice discountedPrice
  }
}

Conversaciones restringidas por suscripción​

Una conversación puede requerir un pago en monedas para unirse — independiente de la suscripción al perfil del creador. Consulta el documento de Mensajes para la API completa.

# Create a subscription-gated group conversation
input ConversationCreateInput {
  type: String!          # "subscription"
  participantIds: [ID!]!
  name: String
}

# The Conversation model exposes:
# isSubscriptionRequired: Boolean!
# subscriptionPriceCoins: Int
# subscriberCount: Int!
# totalEarnings: Int!

Contenido exclusivo​

Las publicaciones con visibility: subscribers solo son visibles para los suscriptores activos del creador. El backend verifica la suscripción activa antes de devolver el contenido. Los usuarios que no son suscriptores ven una vista previa borrosa/bloqueada y una invitación a suscribirse.