Saltar al contenido principal

Prueba la API para desarrolladores de extensiones

Utilice esta guía si desea crear una extensión Chastify, alojar una página de extensión iframe o llamar a la API para desarrolladores desde su propio backend.

Esta página es el punto de partida: qué modo elegir, qué llamar primero y adónde ir después.

Para obtener información sobre el comportamiento concreto de las extensiones, como los bloqueadores de desbloqueo, las acciones requeridas habituales, las recompensas y los castigos, consulte Funciones de la API de extensiones.

tip

¿Solo quieres controlar tu propia cerradura?

Si no necesitas crear una extensión pública, la página API y programas externos es la forma más sencilla de empezar. Solo tienes que crear un token DEV y llamar a puntos finales REST simples; no se requiere configuración de extensión, ni iframe, ni gestión de sesiones. Admite añadir/eliminar tiempo, congelar, tareas, comandos de dispositivo y mucho más.

¿Para qué sirve esta API?​

La API para desarrolladores de extensiones le permite crear experiencias de extensiones de terceros que se ejecutan dentro de las sesiones de bloqueo Chastify.

Con él, puedes:

  • Leer el contexto de la sesión y del bloqueo (session.get para extensiones, /api/apps/v1/session para su propia automatización de bloqueo)
  • Lee los datos propiedad de la extensión por sesión de bloqueo (state.get) y escríbelos desde tu backend (PUT/PATCH /state).
  • Almacene archivos de imagen propiedad de la extensión con el almacenamiento R2 administrado por Chastify (files.*).
  • Agregar acciones de interfaz de usuario de extensión en tarjetas de bloqueo (metadata.homeActions)
  • Desbloqueo de puerta con bloqueadores de desbloqueo propiedad de la extensión (metadata.unlockBlockers)
  • Activar acciones de bloqueo desde un servidor de confianza (añadir/eliminar tiempo, congelar/descongelar, parchear la configuración).
  • Tarea de activación y acciones de higiene (task.assign, task.start_timer, task.complete, hygienic_unlock.start)
  • Enviar acciones regulares con contadores/soporte de cadencia
  • Enviar comandos de dispositivos compatibles cuando estén disponibles
  • Escriba entradas de registro de extensión personalizadas para bloquear el historial.

Lo que puedes construir​

El conjunto de características adecuado depende de dónde reside la confianza.

Las extensiones de iframe solo para el frontend pueden crear experiencias centradas en la interfaz de usuario que no necesitan mutación de bloqueo de confianza:

  • Configurar páginas que recopilan la configuración de la extensión
  • Paneles que leen el contexto de la sesión
  • Interfaces de usuario para rompecabezas, listas de verificación o juegos que leen el estado de la sesión y envían el progreso verificado a través de un servidor.
  • Flujos basados ​​en medios que leen archivos de extensión ya almacenados por Chastify
  • Puntos de entrada de acciones de inicio que abren su iframe con una intención

Las extensiones respaldadas por el servidor pueden crear funciones que afectan al bloqueo porque su backend verifica los resultados antes de llamar a las API privilegiadas:

  • Sistemas de tareas o hábitos con requisitos de desbloqueo
  • Requisitos diarios o semanales con sanciones programadas por incumplimiento.
  • Juegos que recompensan el éxito o penalizan el fracaso con cambios en el tiempo de bloqueo
  • Flujos de verificación que eliminan los bloqueadores de desbloqueo después de la validación del lado del servidor.
  • Flujos complementarios de control de dispositivos mediante comandos de dispositivo compatibles.
  • Flujos de trabajo de webhook/base de datos que mantienen el estado de la extensión fuera del iframe.

Los programas externos sirven para la automatización privada de su propia cerradura activa:

  • scripts locales
  • Paneles de control personales
  • Herramientas de automatización que utilizan una clave DEV para todo el usuario.

Elige tu modo​

Elige uno de estos modos:

  1. Hosted iframe extension: aloja una interfaz de usuario de iframe estático en Cloudflare Pages o un servicio similar. Usa el puente para la configuración, el contexto de la sesión y las lecturas seguras. No uses este modo solo para escrituras de estado, recompensas, castigos, finalización de desbloqueo o progreso de requisitos de confianza.
  2. Server-backed extension: aloja la interfaz de usuario del iframe y ejecuta tu propio backend. El iframe envía su código de inicio mainToken a tu backend, y este llama a la API de extensión Chastify con una clave de API de desarrollador con ámbito de aplicación más x-chastify-main-token. Usa este modo para acciones privilegiadas, desbloquear bloqueadores, progreso confiable, recompensas, castigos, webhooks y bases de datos externas.
  3. External API & Programs: utilice una clave DEV para todo el usuario en scripts, programas locales o automatizaciones que controlen su propio bloqueo activo. Este no es el modo para usuarios externos que instalen su extensión.

Si realiza pruebas rápidamente, comience con el modo iframe para la interfaz de usuario y lecturas seguras. Agregue un backend antes de implementar escrituras de estado, recompensas confiables, cambios de tiempo, progreso de requisitos programados o finalización de bloqueo de desbloqueo.

precaución

El código del iframe no constituye un límite de confianza. Todo lo que sea visible para el iframe, incluyendo las cargas útiles de hash y los tokens de lanzamiento, puede ser inspeccionado y reproducido por el usuario.

Primeros 10 minutos (modo iframe)​

  1. Lee la carga útil location.hash desde el iframe Chastify abierto.
  2. Cree una solicitud de puente para session.get.
  3. Confirme la respuesta con type: "chastify:ext:resp" y ok: true.
  4. Prueba de lectura de estado con state.get.
  5. Agregar redimensionamiento automático y compatibilidad con temas para que el iframe se comporte correctamente en la interfaz de usuario.

La compatibilidad con temas forma parte de un iframe listo para producción. Chastify pasa los valores de ui en el hash de lanzamiento y envía actualizaciones de tema en tiempo real mientras el iframe está abierto. Consulta Temas de iframe para ver ejemplos de temas claros y oscuros, así como patrones Tailwind compatibles con contraste.

Valores de carga útil requeridos:

  • bridge.nonce
  • bridge.parentOrigin
  • sessionId
  • lockId

Ejemplo de solicitud de puente:

{
  "type": "chastify:ext:req",
  "v": 1,
  "id": "request-id", // unique id per request
  "nonce": "nonce-from-hash",
  "action": "session.get",
  "payload": {}
}

Ejemplo de respuesta del puente:

{
  "type": "chastify:ext:resp",
  "v": 1,
  "id": "request-id",
  "ok": true,
  "data": {}
}

Acciones básicas que debes aprender primero​

  • session.get
  • state.get
    Lee el almacenamiento JSON propiedad de la extensión para la sesión de bloqueo. Escribe el estado desde tu backend con las credenciales de la API de desarrollador.
  • files.capabilities, files.list, files.get Utilice lecturas de almacenamiento de archivos para medios binarios, como imágenes de rompecabezas o vistas previas generadas. Almacene los identificadores de archivo en el estado escrito en el servidor y, a continuación, actualice las URL firmadas con files.get.
  • metadata.get Lea los bloqueadores de desbloqueo de sesión bloqueada y las acciones/intenciones de la página principal de la tarjeta de extensión.
  • regularActions.get

Las modificaciones de sesión, como la escritura de estado, el envío de acciones regulares, la carga/eliminación de archivos en tiempo de ejecución, los cambios de hora, las actualizaciones de bloqueo de desbloqueo, la finalización de tareas, el inicio de procesos de higiene y los comandos del dispositivo, deben invocarse desde el backend con una clave de API de desarrollador. El código iframe del navegador no es de confianza para estas acciones.

URLs completas de la API (compatibles)​

Dominio base: https://chastify.net

API de sesión de extensión (/api/extensions/*)​

Estas rutas tienen diferentes modos de acceso. No considere que toda la superficie /api/extensions/* sea segura para iframes.

Las rutas seguras del puente iframe se enrutan a través del padre Chastify después de las solicitudes de puente postMessage:

  • GET https://chastify.net/api/extensions/sessions/:sessionId
  • GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId

Las rutas de extensiones instaladas que solo se ejecutan en el backend requieren una clave API de desarrollador con ámbito de aplicación y el token de lanzamiento del iframe:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH
info

Este modelo de dos tokens vincula una solicitud de backend tanto al desarrollador de la extensión (Authorization) como a la sesión de extensión actualmente abierta (x-chastify-main-token).

  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • PUT https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/state
  • PATCH https://chastify.net/api/extensions/sessions/:sessionId/regular-actions/config
  • POST https://chastify.net/api/extensions/sessions/:sessionId/regular-actions
  • POST https://chastify.net/api/extensions/sessions/:sessionId/files
  • DELETE https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId
  • POST https://chastify.net/api/extensions/sessions/:sessionId/logs/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/notifications/custom
  • POST https://chastify.net/api/extensions/sessions/:sessionId/device-command
  • POST https://chastify.net/api/extensions/sessions/:sessionId/action
  • POST https://chastify.net/api/extensions/sessions/:sessionId/requirements/progress

API de tokens de backend (/api/apps/v1/*)​

Utilice Authorization: Bearer <user-wide DEV token>. Estos puntos finales gestionan las sesiones de bloqueo activas del propietario del token y están destinados a scripts/programas de API externas, no a sesiones de extensiones de terceros instaladas.

  • GET https://chastify.net/api/apps/v1/session
  • GET https://chastify.net/api/apps/v1/state
  • PUT https://chastify.net/api/apps/v1/state
  • PATCH https://chastify.net/api/apps/v1/state
  • GET https://chastify.net/api/apps/v1/metadata
  • PATCH https://chastify.net/api/apps/v1/metadata
  • POST https://chastify.net/api/apps/v1/action
  • POST https://chastify.net/api/apps/v1/lock/apply-time
  • POST https://chastify.net/api/apps/v1/lock/freeze
  • POST https://chastify.net/api/apps/v1/lock/unfreeze
  • POST https://chastify.net/api/apps/v1/logs/custom

Comandos de puente de iframe​

Las cargas útiles de comandos del puente se envían mediante un iframe (chastify:ext:req) y se enrutan a través del nodo padre Chastify. El puente está intencionalmente limitado a operaciones de interfaz de usuario seguras/de sesión.

  • session.get -> GET https://chastify.net/api/extensions/sessions/:sessionId
  • state.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/state
  • files.capabilities -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/capabilities
  • files.list -> GET https://chastify.net/api/extensions/sessions/:sessionId/files
  • files.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/files/:fileId con { "fileId": "file_record_id" }
  • metadata.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/metadata
  • regularActions.get -> GET https://chastify.net/api/extensions/sessions/:sessionId/regular-actions

Los puntos finales de mutación de sesión son llamadas directas a la API del backend, no comandos de puente iframe. Esto incluye escrituras de estado, envío de acciones regulares y carga/eliminación de archivos en tiempo de ejecución, ya que el código del iframe puede ser controlado por el usuario.

Ejemplos de API de sesión de backend​

Su backend debe enviar ambos encabezados para las llamadas privilegiadas de la extensión instalada:

Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY
x-chastify-main-token: MAIN_TOKEN_FROM_IFRAME_HASH

Ejemplos de acciones en el backend:

  • metadata.patch -> PATCH /api/extensions/sessions/:sessionId/metadata
  • regularActions.submit -> POST /api/extensions/sessions/:sessionId/regular-actions
  • files.upload -> POST /api/extensions/sessions/:sessionId/files
  • files.delete -> DELETE /api/extensions/sessions/:sessionId/files/:fileId
  • lock.applyTime -> POST /api/extensions/sessions/:sessionId/action con { "name": "add_time", "params": <deltaSeconds> }
  • lock.freeze -> POST /api/extensions/sessions/:sessionId/action con { "name": "freeze", "params": { "durationSeconds": 900 } }
  • lock.unfreeze -> POST /api/extensions/sessions/:sessionId/action con { "name": "unfreeze", "params": {} }
  • lock.settings.patch -> POST /api/extensions/sessions/:sessionId/action con { "name": "settings.patch", "params": { ... } }
  • task.assign -> POST /api/extensions/sessions/:sessionId/action
  • task.start_timer -> POST /api/extensions/sessions/:sessionId/action con { "name": "task.start_timer", "params": {} }
  • task.complete -> POST /api/extensions/sessions/:sessionId/action con { "name": "task.complete", "params": { "successful": true } }
  • hygienic_unlock.start -> POST /api/extensions/sessions/:sessionId/action con { "name": "hygienic_unlock.start", "params": { "durationSeconds": 900 } }
  • pillory.end -> POST /api/extensions/sessions/:sessionId/action con { "name": "pillory.end", "params": {} }
  • device.command -> POST /api/extensions/sessions/:sessionId/device-command
  • logs.custom -> POST /api/extensions/sessions/:sessionId/logs/custom
  • notifications.custom -> POST /api/extensions/sessions/:sessionId/notifications/custom
  • requirements.progress -> POST /api/extensions/sessions/:sessionId/requirements/progress

Comportamiento del token, el alcance, la revocación y la auditoría​

Utilice el token correcto para el límite de confianza correcto.

aviso

Las claves API para desarrolladores son confidenciales. Si alguna queda expuesta al código del navegador, revoque su acceso de inmediato y modifique la variable de entorno del backend.

token de lanzamiento de iframe (mainToken)​

  • Se entrega en el hash del iframe cuando un usuario abre una página de extensión instalada.
  • Está diseñado para ser visible en el navegador. Identifica la sesión de la extensión abierta, pero no es un secreto del servidor.
  • De corta duración. Los tokens de lanzamiento actuales caducan después de 10 horas; actualícelos volviendo a abrir la página de la extensión.
  • Se requiere como x-chastify-main-token cuando su backend llama a las rutas de sesión de la extensión instalada, para que Chastify pueda vincular la solicitud del backend al usuario/sesión que abrió la extensión.
  • No debe utilizarse por sí solo para autorizar cambios de hora, desbloquear la finalización de bloqueos, completar tareas, comandos de dispositivos, cargas/eliminaciones en tiempo de ejecución, registros personalizados o notificaciones personalizadas.

Clave API de desarrollador con ámbito de aplicación​

  • Creado desde la interfaz de usuario para desarrolladores de una aplicación de extensión.
  • Secreto exclusivo del backend. Nunca lo incluyas en el código JavaScript de un iframe, en paquetes de aplicaciones móviles, en la configuración de alojamiento estático ni en registros legibles por el navegador.
  • Se utiliza con Authorization: Bearer YOUR_APP_SCOPED_DEVELOPER_KEY y x-chastify-main-token.
  • Solo se pueden llamar a las API de sesión de extensiones instaladas para las sesiones que coincidan con la aplicación de extensión y el token de inicio.
  • No caduca automáticamente. Revoque inmediatamente si queda expuesta y actualice la variable de entorno de su servidor.

Clave API para desarrolladores a nivel de usuario​

  • Creado desde la interfaz de desarrollador sin seleccionar una aplicación de extensión.
  • Secreto exclusivo para el backend para /api/apps/v1/*.
  • Controla las sesiones de bloqueo activas actuales y futuras del propietario de la llave.
  • No se puede utilizar como credencial de backend de una extensión de terceros instalada.

Revocación​

  • Las claves de API de desarrollador revocadas dejan de autorizar nuevas solicitudes.
  • Las claves revocadas se pueden eliminar permanentemente desde la interfaz de usuario para desarrolladores.
  • Los nuevos lanzamientos de iframe reciben tokens de lanzamiento nuevos. No almacene mainToken como credencial a largo plazo.

Alcances y funciones​

  • Los ámbitos de la aplicación de extensión describen qué solicitudes tiene permitidas la aplicación.
  • Las llamadas seguras al puente iframe se limitan al arranque de la interfaz de usuario, las lecturas de sesión, el estado propiedad de la extensión, las lecturas de metadatos, las lecturas de acciones regulares y las lecturas de archivos.
  • Las mutaciones de sesión instalada con privilegios requieren credenciales de backend incluso cuando la extensión tiene un ámbito coincidente.
  • Las acciones que dependen del rol aún pueden ser rechazadas según si el lanzamiento pertenece a un usuario o a un titular de la llave.

Auditoría y límites​

  • Los metadatos del último uso de la clave API para desarrolladores se actualizan cuando se utilizan las claves.
  • Las rutas de acción privilegiadas tienen limitaciones de velocidad y devuelven errores explícitos como server_credentials_required o user_wide_dev_key_required cuando se utiliza un tipo de credencial incorrecto.
  • Los registros personalizados escriben entradas visibles en el historial de bloqueos.
  • Las notificaciones personalizadas crean notificaciones Chastify para el destino solicitado.
  • La cobertura de auditoría completa para cada mutación de extensión privilegiada se registra como un elemento de endurecimiento de la producción.

Valores de comando admitidos​

/api/extensions/sessions/:sessionId/action y /api/apps/v1/action​

name admite:

  • add_time
  • remove_time
  • freeze
  • pillory
  • unfreeze
  • toggle_freeze
  • settings.patch
  • task.assign
  • task.start_timer
  • task.complete
  • hygienic_unlock.start
  • pillory.end

Restricciones de acción:

  • Las acciones de tareas requieren que la extensión/módulo Tareas esté habilitado en el bloqueo.
  • hygienic_unlock.start requiere que la Apertura Higiénica esté habilitada y que no haya ninguna sesión de higiene activa.

Ayudantes de datos de bloqueo session.get​

session.get / GET /api/apps/v1/session también incluye lockData con booleanos, números y cadenas amigables para el tiempo de ejecución para motores de reglas.

Ejemplos:

  • booleanos: frozen, unlockable, trusted, taskAssigned (true cuando existe un TaskRun abierto)
  • números: timeLockedSeconds, timeRemainingSeconds, maxTimeRemainingSeconds, taskPoints
  • cadenas: lockTitle, campos de perfil del usuario/titular de la llave

Privacidad:

  • wearerLastSeenTimestamp y keyholderLastSeenTimestamp son null cuando ese usuario deshabilitó el estado en línea (showOnlineStatus === false).

Comandos del dispositivo​

Las sesiones de extensión pueden utilizar el punto final basado en sesión:

POST /api/extensions/sessions/:sessionId/device-command

Los programas externos con un token DEV pueden usar el punto final v1 más simple (no se necesita ID de sesión):

POST /api/apps/v1/device-command

Ambas aceptan el mismo cuerpo de solicitud y devuelven la misma respuesta. Consulte API y programas externos para obtener más detalles.

Página de configuración (opcional, recomendada)​

Si su extensión tiene una interfaz de usuario de configuración:

  1. El padre envía chastify:ext:setup:init (configuración guardada + contexto).
  2. Su iframe de configuración devuelve actualizaciones con chastify:ext:setup:config.
  3. Los padres pueden solicitar la configuración actual con chastify:ext:setup:get_config.

Flujo de tokens de backend (cuando se necesitan llamadas del lado del servidor)​

Para scripts sencillos y programas externos, utilice un token DEV válido para todo el usuario, disponible en la página de la API para desarrolladores. Consulte API y programas externos.

Flujo predeterminado en modo iframe de extensión:

  1. Chastify emite un token de inicio visible en el navegador de corta duración para la sesión de extensión activa.
  2. El token de lanzamiento está incrustado en la carga útil del hash del iframe como mainToken.
  3. Tu iframe reenvía mainToken a tu backend.
  4. Su backend llama a https://chastify.net/api/extensions/sessions/:sessionId/* con Authorization: Bearer <app-scoped Developer API key> y x-chastify-main-token: <mainToken>.

No envíe claves de API de desarrollador al código del iframe/navegador. mainToken identifica la sesión de extensión abierta; no es un secreto de backend y no puede usarse por sí solo para acciones privilegiadas.

Opción de reserva manual:

  • Si necesita obtener/rotar el token de lanzamiento del iframe explícitamente desde la interfaz de usuario de primera parte, llame a GET https://chastify.net/api/extensions/sessions/:sessionId/auth.

Utilice el modo backend si necesita tareas programadas, webhooks o automatización mientras la página Chastify no esté abierta. Las mutaciones de sesión de la extensión instalada actual aún requieren un token de lanzamiento de iframe válido de 10 horas, por lo que las tareas desatendidas deben almacenar la prueba pendiente y enviarla en el siguiente lanzamiento válido, a menos que esté utilizando un flujo de servidor propio/integrado diseñado para la ejecución en segundo plano.

info

Para un comportamiento de producción totalmente automatizado, se recomienda utilizar un flujo de servidor integrado o de terceros, o esperar a que se otorguen permisos explícitos para la extensión en segundo plano. Actualmente, las API de sesión con ámbito de aplicación están vinculadas al token de inicio.

Backend vs. Cloudflare Pages (sin servidor)​

Utilice Cloudflare Pages (sin servidor backend) cuando:​

  • Buscas la configuración más sencilla y económica (que además se puede alojar gratis).
  • Solo necesitas acciones controladas por la interfaz de usuario mientras el usuario esté activamente en la página de tu extensión.
  • No necesita escrituras de estado de extensión persistentes en el servidor.
  • Estás creando prototipos o desarrollando extensiones ligeras rápidamente.

Ejemplo de prueba local (PowerShell):

cloudflared tunnel --url http://localhost:5174

Utilice la URL pública generada como URL de su iframe durante las pruebas.

Utilice un servidor backend cuando:​

  • Necesitas tareas programadas (comportamiento similar a cron).
  • Necesitas webhooks o integraciones externas.
  • Necesitas automatización/procesamiento en segundo plano cuando no hay nadie en la página de la extensión.
  • Necesitas flujos de trabajo controlados por el servidor que deban ejecutarse de forma continua.

Limitación importante sin un backend:

  • Sin ejecución en segundo plano. Tu extensión solo puede realizar acciones mientras el usuario tenga abierto el iframe de la extensión y esté interactuando con él.

Problemas comunes​

  • 403 extension_not_enabled: la extensión no está habilitada para este bloqueo.
  • 409 lock_ended: el bloqueo ya no está activo.
  • 429: se ha alcanzado el límite de velocidad.
  • No hay respuestas en el iframe: compruebe nonce, targetOrigin (parentOrigin) y los orígenes permitidos.

Próximas guías​