From b7aa6545ae936a6ba4d18c421f54a61531a7794f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 21 Aug 2026 10:13:01 +0000 Subject: [PATCH 1/7] Add streak pauses documentation Document streak pauses from the 1.21.0 OpenAPI specs: create and archive admin endpoints, plus pauses and usedPause on the user streak response. Co-authored-by: jasontlouro --- .../endpoints/streaks/archive-pauses.mdx | 10 + admin-api/endpoints/streaks/create-pauses.mdx | 10 + docs.json | 4 + .../endpoints/streaks/archive-pauses.mdx | 10 + .../endpoints/streaks/create-pauses.mdx | 10 + es/features/streaks.mdx | 66 ++- es/guides/how-to-build-a-streaks-feature.mdx | 8 +- features/streaks.mdx | 66 ++- guides/how-to-build-a-streaks-feature.mdx | 8 +- lingo/glossary.csv | 2 + openapi/admin.json | 435 +++++++++++++++++- openapi/application.json | 75 ++- snippets/streak-response-block.mdx | 28 +- 13 files changed, 691 insertions(+), 41 deletions(-) create mode 100644 admin-api/endpoints/streaks/archive-pauses.mdx create mode 100644 admin-api/endpoints/streaks/create-pauses.mdx create mode 100644 es/admin-api/endpoints/streaks/archive-pauses.mdx create mode 100644 es/admin-api/endpoints/streaks/create-pauses.mdx diff --git a/admin-api/endpoints/streaks/archive-pauses.mdx b/admin-api/endpoints/streaks/archive-pauses.mdx new file mode 100644 index 00000000..9d633696 --- /dev/null +++ b/admin-api/endpoints/streaks/archive-pauses.mdx @@ -0,0 +1,10 @@ +--- +title: Archive streak pauses +openapi: "/openapi/admin.json DELETE /streaks/pauses" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + diff --git a/admin-api/endpoints/streaks/create-pauses.mdx b/admin-api/endpoints/streaks/create-pauses.mdx new file mode 100644 index 00000000..b04d06d7 --- /dev/null +++ b/admin-api/endpoints/streaks/create-pauses.mdx @@ -0,0 +1,10 @@ +--- +title: Create streak pauses for multiple users +openapi: "/openapi/admin.json POST /streaks/pauses" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Rate Limits** + + diff --git a/docs.json b/docs.json index 1674147a..5b83cdfc 100644 --- a/docs.json +++ b/docs.json @@ -260,6 +260,8 @@ "group": "Streaks", "pages": [ "admin-api/endpoints/streaks/grant-freezes", + "admin-api/endpoints/streaks/create-pauses", + "admin-api/endpoints/streaks/archive-pauses", "admin-api/endpoints/streaks/restore-streaks" ] }, @@ -646,6 +648,8 @@ "group": "Rachas", "pages": [ "es/admin-api/endpoints/streaks/grant-freezes", + "es/admin-api/endpoints/streaks/create-pauses", + "es/admin-api/endpoints/streaks/archive-pauses", "es/admin-api/endpoints/streaks/restore-streaks" ] }, diff --git a/es/admin-api/endpoints/streaks/archive-pauses.mdx b/es/admin-api/endpoints/streaks/archive-pauses.mdx new file mode 100644 index 00000000..bd85710f --- /dev/null +++ b/es/admin-api/endpoints/streaks/archive-pauses.mdx @@ -0,0 +1,10 @@ +--- +title: Archivar pausas de racha +openapi: "/openapi/admin.json DELETE /streaks/pauses" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Límites de velocidad** + + diff --git a/es/admin-api/endpoints/streaks/create-pauses.mdx b/es/admin-api/endpoints/streaks/create-pauses.mdx new file mode 100644 index 00000000..7e0c2d18 --- /dev/null +++ b/es/admin-api/endpoints/streaks/create-pauses.mdx @@ -0,0 +1,10 @@ +--- +title: Crear pausas de racha para múltiples usuarios +openapi: "/openapi/admin.json POST /streaks/pauses" +--- + +import { RateLimitBadge } from "../../../components/rate-limit-badge.jsx"; + +**Límites de velocidad** + + diff --git a/es/features/streaks.mdx b/es/features/streaks.mdx index 05c40166..0f8d62d9 100644 --- a/es/features/streaks.mdx +++ b/es/features/streaks.mdx @@ -76,6 +76,38 @@ Si has [configurado zonas horarias](/es/features/users#param-tz) para tus usuari En Trophy también configuras el número máximo de congelaciones que cada usuario puede tener, hasta un límite de 100. La [acumulación de congelaciones](#freeze-accumulation) solo otorgará congelaciones hasta este límite. +## Pausas de Racha {#streak-pauses} + +Las pausas de racha protegen la racha de un usuario durante un rango de fechas conocido, como unas vacaciones u otra pausa planificada. Mientras una pausa cubre un período, Trophy mantiene la duración de la racha del usuario en lugar de terminarla si no cumple sus [condiciones de racha](#streak-conditions). + +A diferencia de las [congelaciones de rachas](#streak-freezes), las pausas no se consumen un período a la vez. Cada pausa tiene una fecha de inicio y una fecha de fin, y se aplica durante todo ese rango. + + +Usa congelaciones para períodos ocasionales que se pierden. Usa pausas cuando ya sabes que un usuario estará ausente durante un período de tiempo específico. + + +### Crear Pausas {#creating-pauses} + +Crea pausas con la [API de administración para crear pausas de racha](/es/admin-api/endpoints/streaks/create-pauses). Puedes crear pausas para hasta 100 usuarios en una sola solicitud. + +Cada pausa requiere: + +- `userId`: el usuario para el que crear una pausa +- `start`: la primera fecha que cubre la pausa, en formato `YYYY-MM-DD`. No debe ser anterior a hoy en la zona horaria del usuario. +- `end`: la última fecha que cubre la pausa, en formato `YYYY-MM-DD`. Debe ser igual o posterior a `start`. + +Las fechas de inicio en el pasado se rechazan. Si has [configurado zonas horarias](/es/features/users#param-tz) para tus usuarios, Trophy evalúa `start` contra el día de hoy en la zona horaria local de cada usuario. + +### Archivar Pausas {#archiving-pauses} + +Para dejar de aplicar una pausa, archívala con la [API de administración para archivar pausas de racha](/es/admin-api/endpoints/streaks/archive-pauses). Los registros de pausas no se eliminan. Archivar establece su estado en `archived` para que ya no afecten la lógica de rachas. + +### Leer Pausas {#reading-pauses} + +La [API de rachas de usuario](/es/api-reference/endpoints/users/get-a-users-streak) devuelve las pausas próximas y actualmente activas en el campo `pauses`. Se omiten las pausas pasadas y archivadas. + +Cada período en `streakHistory` incluye `usedPause`, que es `true` cuando la racha del usuario estuvo en pausa durante ese período. + ## Seguimiento de Rachas {#tracking-streaks} Trophy calcula automáticamente las rachas para todos los usuarios en función de los [eventos de métrica](/es/features/events#tracking-metric-events) que reportes a Trophy. @@ -116,6 +148,10 @@ Para obtener más información sobre cómo establecer preferencias de usuario pa Esta sección describe algunas de las operaciones que puedes realizar para administrar las rachas de los usuarios en tu aplicación. +### Pausar la Racha de un Usuario {#pausing-a-users-streak} + +Para pausar la racha de un usuario durante un rango de fechas específico, usa la [API de administración para crear pausas de racha](/es/admin-api/endpoints/streaks/create-pauses). Consulta [pausas de racha](#streak-pauses) para saber cómo funcionan las pausas, incluyendo cómo archivarlas. + ### Restaurar la Racha de un Usuario {#restoring-a-users-streak} Para restaurar la racha de un usuario, dirígete a la página de detalles del usuario y usa la acción 'Restaurar Racha'. Restaurar la racha de un usuario la establece en la duración que tenía cuando la perdió por última vez. @@ -156,7 +192,7 @@ Esto puede usarse para activar transaccionalmente elementos de UI/UX incluyendo: ### API de Rachas de Usuario {#user-streaks-api} -La [API de rachas de usuario](/es/api-reference/endpoints/users/get-a-users-streak) devuelve la racha actual de un usuario individual, junto con su historial reciente de rachas. Usa el parámetro de consulta `historyPeriods` para controlar cuántos períodos devolver. +La [API de rachas de usuario](/es/api-reference/endpoints/users/get-a-users-streak) devuelve la racha actual de un usuario individual, junto con su historial reciente de rachas y cualquier [pausa de racha](#streak-pauses) próxima o activa. Usa el parámetro de consulta `historyPeriods` para controlar cuántos períodos devolver. {/* vale off */} @@ -169,41 +205,55 @@ La [API de rachas de usuario](/es/api-reference/endpoints/users/get-a-users-stre "periodEnd": "2025-04-05", "expires": "2025-04-12", "rank": 5, + "pauses": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "start": "2026-08-20", + "end": "2026-08-27" + } + ], "streakHistory": [ { "periodStart": "2025-03-02", "periodEnd": "2025-03-08", - "length": 9 + "length": 9, + "usedPause": false }, { "periodStart": "2025-03-09", "periodEnd": "2025-03-15", - "length": 0 + "length": 0, + "usedPause": false }, { "periodStart": "2025-03-16", "periodEnd": "2025-03-22", - "length": 0 + "length": 0, + "usedPause": false }, { "periodStart": "2025-03-23", "periodEnd": "2025-03-29", - "length": 1 + "length": 1, + "usedPause": false }, { "periodStart": "2025-03-30", "periodEnd": "2025-04-05", - "length": 2 + "length": 2, + "usedPause": false }, { "periodStart": "2025-04-06", "periodEnd": "2025-04-12", - "length": 3 + "length": 3, + "usedPause": false }, { "periodStart": "2025-04-13", "periodEnd": "2025-04-19", - "length": 4 + "length": 4, + "usedPause": false } ] } diff --git a/es/guides/how-to-build-a-streaks-feature.mdx b/es/guides/how-to-build-a-streaks-feature.mdx index f30e44f4..5fee6a1b 100644 --- a/es/guides/how-to-build-a-streaks-feature.mdx +++ b/es/guides/how-to-build-a-streaks-feature.mdx @@ -160,7 +160,7 @@ Para obtener datos sobre la racha de un usuario, usa la [API de racha de usuario -Esta API no solo devuelve datos sobre la racha actual del usuario como `length` y `expires`, sino que también puede devolver datos históricos de rachas que se pueden usar para mostrar cualquier tipo de interfaz de racha que desees a través del parámetro `historyPeriods`. +Esta API no solo devuelve datos sobre la racha actual del usuario como `length` y `expires`, sino que también puede devolver datos históricos de rachas que se pueden usar para mostrar cualquier tipo de interfaz de racha que desees a través del parámetro `historyPeriods`. La respuesta también incluye [pausas de racha](/es/features/streaks#streak-pauses) próximas y activas en `pauses`, y cada período del historial incluye `usedPause`. @@ -198,6 +198,12 @@ Trophy también admite congelación de rachas, lo que puede ayudar a evitar que Obtén más información sobre la congelación de rachas en la [documentación dedicada de congelación de rachas](/es/features/streaks#streak-freezes). +## Pausas de Racha {#streak-pauses} + +Trophy también admite pausas de racha, que protegen la racha de un usuario durante un rango de fechas conocido en lugar de terminarla. + +Obtén más información sobre las pausas de racha en la [documentación dedicada de pausas de racha](/es/features/streaks#streak-pauses). + ## Obtener Soporte {#get-support} ¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudar! diff --git a/features/streaks.mdx b/features/streaks.mdx index 04405887..da5a18f3 100644 --- a/features/streaks.mdx +++ b/features/streaks.mdx @@ -76,6 +76,38 @@ If you've [configured time zones](/features/users#param-tz) for your users, Trop In Trophy you also configure the maximum number of freezes that each user can have, up to a limit of 100. [Freeze accumulation](#freeze-accumulation) will only ever grant freezes up to this limit. +## Streak Pauses {#streak-pauses} + +Streak pauses protect a user's streak over a known date range, such as a vacation or other planned break. While a pause covers a period, Trophy maintains the user's streak length instead of ending the streak if they miss their [streak conditions](#streak-conditions). + +Unlike [streak freezes](#streak-freezes), pauses are not consumed one period at a time. Each pause has a start date and an end date, and it applies for that entire range. + + +Use freezes for occasional missed periods. Use pauses when you already know a user will be away for a specific stretch of time. + + +### Creating Pauses {#creating-pauses} + +Create pauses with the [create streak pauses admin API](/admin-api/endpoints/streaks/create-pauses). You can create pauses for up to 100 users in a single request. + +Each pause requires: + +- `userId`: the user to create a pause for +- `start`: the first date the pause covers, in `YYYY-MM-DD` format. Must not be before today in the user's timezone. +- `end`: the last date the pause covers, in `YYYY-MM-DD` format. Must be on or after `start`. + +Start dates in the past are rejected. If you've [configured time zones](/features/users#param-tz) for your users, Trophy evaluates `start` against today in each user's local timezone. + +### Archiving Pauses {#archiving-pauses} + +To stop a pause from applying, archive it with the [archive streak pauses admin API](/admin-api/endpoints/streaks/archive-pauses). Pause records are not deleted. Archiving sets their status to `archived` so they no longer affect streak logic. + +### Reading Pauses {#reading-pauses} + +The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns upcoming and currently active pauses in the `pauses` field. Past and archived pauses are omitted. + +Each period in `streakHistory` includes `usedPause`, which is `true` when the user's streak was paused during that period. + ## Tracking Streaks {#tracking-streaks} Trophy automatically calculates streaks for all users based on the [metric events](/features/events#tracking-metric-events) you report to Trophy. @@ -116,6 +148,10 @@ To learn more about how to set user preferences for a specific user, read the de This section outlines some of the operations you can perform to manage user's streaks in your application. +### Pausing A Users Streak {#pausing-a-users-streak} + +To pause a user's streak for a specific date range, use the [create streak pauses admin API](/admin-api/endpoints/streaks/create-pauses). See [streak pauses](#streak-pauses) for how pauses work, including how to archive them. + ### Restoring A Users Streak {#restoring-a-users-streak} To restore a user's streak, head to the user details page and use the 'Restore Streak' action. Restoring a user's streak sets it to the length it was when they last lost it. @@ -158,7 +194,7 @@ This can be used to transactionally trigger UI/UX elements including: ### User Streaks API {#user-streaks-api} -The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns the current streak for a single user, along with their recent streak history. Use the `historyPeriods` query parameter to control how many periods to return. +The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns the current streak for a single user, along with their recent streak history and any upcoming or active [streak pauses](#streak-pauses). Use the `historyPeriods` query parameter to control how many periods to return. {/* vale off */} @@ -171,41 +207,55 @@ The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) return "periodEnd": "2025-04-05", "expires": "2025-04-12", "rank": 5, + "pauses": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "start": "2026-08-20", + "end": "2026-08-27" + } + ], "streakHistory": [ { "periodStart": "2025-03-02", "periodEnd": "2025-03-08", - "length": 9 + "length": 9, + "usedPause": false }, { "periodStart": "2025-03-09", "periodEnd": "2025-03-15", - "length": 0 + "length": 0, + "usedPause": false }, { "periodStart": "2025-03-16", "periodEnd": "2025-03-22", - "length": 0 + "length": 0, + "usedPause": false }, { "periodStart": "2025-03-23", "periodEnd": "2025-03-29", - "length": 1 + "length": 1, + "usedPause": false }, { "periodStart": "2025-03-30", "periodEnd": "2025-04-05", - "length": 2 + "length": 2, + "usedPause": false }, { "periodStart": "2025-04-06", "periodEnd": "2025-04-12", - "length": 3 + "length": 3, + "usedPause": false }, { "periodStart": "2025-04-13", "periodEnd": "2025-04-19", - "length": 4 + "length": 4, + "usedPause": false } ] } diff --git a/guides/how-to-build-a-streaks-feature.mdx b/guides/how-to-build-a-streaks-feature.mdx index e603803b..7f52712a 100644 --- a/guides/how-to-build-a-streaks-feature.mdx +++ b/guides/how-to-build-a-streaks-feature.mdx @@ -164,7 +164,7 @@ To fetch data on a user's streak use the [user streak API](/api-reference/endpoi -This API not only returns data on the user's current streak like `length` and `expires`, but it can also return historical streak data which can be used to display any kind of streak UI you like through the `historyPeriods` parameter. +This API not only returns data on the user's current streak like `length` and `expires`, but it can also return historical streak data which can be used to display any kind of streak UI you like through the `historyPeriods` parameter. The response also includes upcoming and active [streak pauses](/features/streaks#streak-pauses) in `pauses`, and each history period includes `usedPause`. @@ -204,6 +204,12 @@ Trophy also supports streak freezes which can help prevent users from losing the Learn more about streak freezes in the dedicated [streak freezes docs](/features/streaks#streak-freezes). +## Streak Pauses {#streak-pauses} + +Trophy also supports streak pauses, which protect a user's streak over a known date range instead of ending it. + +Learn more about streak pauses in the dedicated [streak pauses docs](/features/streaks#streak-pauses). + ## Get Support {#get-support} Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help! diff --git a/lingo/glossary.csv b/lingo/glossary.csv index b82334b3..7521c78b 100644 --- a/lingo/glossary.csv +++ b/lingo/glossary.csv @@ -30,6 +30,8 @@ en,es,Leaderboard,Clasificación,custom_translation,Gamification feature noun en,es,Leaderboards,Clasificaciones,custom_translation,Gamification feature noun plural en,es,Streak,Racha,custom_translation,Gamification feature noun en,es,Streaks,Rachas,custom_translation,Gamification feature noun plural +en,es,Streak Pause,Pausa de racha,custom_translation,Gamification feature noun +en,es,Streak Pauses,Pausas de racha,custom_translation,Gamification feature noun plural en,es,Achievement,Logro,custom_translation,Gamification feature noun en,es,Achievements,Logros,custom_translation,Gamification feature noun plural en,es,Points,Puntos,custom_translation,Gamification feature noun plural diff --git a/openapi/admin.json b/openapi/admin.json index d2883ca8..a6632ac6 100644 --- a/openapi/admin.json +++ b/openapi/admin.json @@ -2,13 +2,13 @@ "openapi": "3.1.0", "info": { "title": "Trophy", - "version": "1.20.1" + "version": "1.21.0" }, "x-fern-global-headers": [ { "header": "X-SDK-VERSION", "name": "sdkVersion", - "x-fern-default": "1.20.1" + "x-fern-default": "1.21.0" } ], "paths": { @@ -4862,6 +4862,300 @@ ] } }, + "/streaks/pauses": { + "servers": [ + { + "url": "https://admin.trophy.so/v1", + "description": "Admin API" + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/TenantId" + } + ], + "post": { + "description": "Create streak pauses for multiple users. A pause covers a specific date range and maintains the user's streak length during that range instead of ending the streak. Start dates in the past are rejected.", + "operationId": "admin_streaks_pauses_create", + "x-fern-server-name": "admin", + "x-fern-sdk-group-name": [ + "admin", + "streaks", + "pauses" + ], + "x-fern-sdk-method-name": "create", + "tags": [ + "Admin" + ], + "x-codeSamples": [ + { + "lang": "javascript", + "source": "import { TrophyApiClient } from '@trophyso/node';\n\nconst trophy = new TrophyApiClient({\n apiKey: 'YOUR_API_KEY'\n});\n\nconst response = await trophy.admin.streaks.pauses.create({\n pauses: [\n { userId: 'user-123', start: '2026-08-20', end: '2026-08-27' },\n { userId: 'user-456', start: '2026-09-01', end: '2026-09-07' },\n ]\n});\n" + }, + { + "lang": "python", + "source": "from trophy import TrophyApi\n\nclient = TrophyApi(api_key='YOUR_API_KEY')\n\nresponse = client.admin.streaks.pauses.create({\n \"pauses\": [\n {\"userId\": \"user-123\", \"start\": \"2026-08-20\", \"end\": \"2026-08-27\"},\n {\"userId\": \"user-456\", \"start\": \"2026-09-01\", \"end\": \"2026-09-07\"}\n ]\n})\n" + }, + { + "lang": "go", + "source": "import (\n \"context\"\n\n api \"github.com/trophyso/trophy-go\"\n trophyclient \"github.com/trophyso/trophy-go/client\"\n \"github.com/trophyso/trophy-go/option\"\n)\n\nclient := trophyclient.NewClient(\n option.WithApiKey(\"YOUR_API_KEY\"),\n)\n\nresponse, err := client.Admin.Streaks.Pauses.Create(context.TODO(), nil)\n" + } + ], + "requestBody": { + "description": "Array of pauses to create", + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStreakPausesRequest" + }, + "examples": { + "Create pauses for multiple users": { + "value": { + "pauses": [ + { + "userId": "user-123", + "start": "2026-08-20", + "end": "2026-08-27" + }, + { + "userId": "user-456", + "start": "2026-09-01", + "end": "2026-09-07" + } + ] + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Successful operation (no pauses created)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStreakPausesResponse" + }, + "examples": { + "Mixed success and errors": { + "value": { + "created": [], + "issues": [ + { + "userId": "non-existent-user", + "severity": "error", + "message": "User does not exist" + } + ] + } + } + } + } + } + }, + "201": { + "description": "Created (at least one pause created)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateStreakPausesResponse" + }, + "examples": { + "Success with no issues": { + "value": { + "created": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "userId": "user-123", + "start": "2026-08-20", + "end": "2026-08-27", + "status": "active" + } + ], + "issues": [] + } + }, + "Mixed success and errors": { + "value": { + "created": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "userId": "user-123", + "start": "2026-08-20", + "end": "2026-08-27", + "status": "active" + } + ], + "issues": [ + { + "userId": "non-existent-user", + "severity": "error", + "message": "User does not exist" + } + ] + } + } + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminErrorBody" + } + } + } + }, + "422": { + "description": "Unprocessible Entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminErrorBody" + } + } + } + } + }, + "summary": "Create streak pauses for multiple users", + "security": [ + { + "ApiKeyAuth": [] + } + ] + }, + "delete": { + "description": "Archive streak pauses by ID. Pause records are not deleted; their status is set to archived so they no longer apply to streak logic.", + "operationId": "admin_streaks_pauses_delete", + "x-fern-server-name": "admin", + "x-fern-sdk-group-name": [ + "admin", + "streaks", + "pauses" + ], + "x-fern-sdk-method-name": "delete", + "tags": [ + "Admin" + ], + "x-codeSamples": [ + { + "lang": "javascript", + "source": "import { TrophyApiClient } from '@trophyso/node';\n\nconst trophy = new TrophyApiClient({\n apiKey: 'YOUR_API_KEY'\n});\n\nconst response = await trophy.admin.streaks.pauses.delete({\n ids: [\n '550e8400-e29b-41d4-a716-446655440000',\n '550e8400-e29b-41d4-a716-446655440001'\n ]\n});\n" + }, + { + "lang": "python", + "source": "from trophy import TrophyApi\n\nclient = TrophyApi(api_key='YOUR_API_KEY')\n\nresponse = client.admin.streaks.pauses.delete(\n ids=[\n '550e8400-e29b-41d4-a716-446655440000',\n '550e8400-e29b-41d4-a716-446655440001'\n ]\n)\n" + }, + { + "lang": "go", + "source": "import (\n \"context\"\n\n api \"github.com/trophyso/trophy-go\"\n trophyclient \"github.com/trophyso/trophy-go/client\"\n \"github.com/trophyso/trophy-go/option\"\n)\n\nclient := trophyclient.NewClient(\n option.WithApiKey(\"YOUR_API_KEY\"),\n)\n\nresponse, err := client.Admin.Streaks.Pauses.Delete(context.TODO(), nil)\n" + } + ], + "parameters": [ + { + "name": "ids", + "in": "query", + "description": "Streak pause IDs to archive. Repeat the query param or provide a comma-separated list.", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "minItems": 1, + "maxItems": 100 + }, + "style": "form", + "explode": true, + "examples": { + "Multiple query params": { + "value": [ + "550e8400-e29b-41d4-a716-446655440000", + "550e8400-e29b-41d4-a716-446655440001" + ] + } + } + } + ], + "responses": { + "200": { + "description": "Successful operation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteStreakPausesResponse" + }, + "examples": { + "Success with no issues": { + "value": { + "deleted": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000" + } + ], + "issues": [] + } + }, + "Mixed success and errors": { + "value": { + "deleted": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000" + } + ], + "issues": [ + { + "id": "not-a-uuid", + "severity": "error", + "message": "id must be a valid UUID" + }, + { + "id": "550e8400-e29b-41d4-a716-446655440999", + "severity": "error", + "message": "Streak pause not found by ID" + } + ] + } + } + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminErrorBody" + } + } + } + }, + "422": { + "description": "Unprocessible Entity", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AdminErrorBody" + } + } + } + } + }, + "summary": "Archive streak pauses", + "security": [ + { + "ApiKeyAuth": [] + } + ] + } + }, "/streaks/restore": { "servers": [ { @@ -6058,6 +6352,143 @@ "issues" ] }, + "CreateStreakPausesRequest": { + "title": "CreateStreakPausesRequest", + "type": "object", + "description": "Request body for creating streak pauses.", + "properties": { + "pauses": { + "type": "array", + "items": { + "type": "object", + "properties": { + "userId": { + "type": "string", + "description": "The ID of the user to create a pause for.", + "example": "user-123" + }, + "start": { + "type": "string", + "format": "date", + "description": "The first date the pause covers, in YYYY-MM-DD format. Must not be before today in the user's timezone.", + "example": "2026-08-20" + }, + "end": { + "type": "string", + "format": "date", + "description": "The last date the pause covers, in YYYY-MM-DD format. Must be on or after start.", + "example": "2026-08-27" + } + }, + "required": [ + "userId", + "start", + "end" + ] + }, + "description": "Array of pauses to create. Maximum 100 pauses per request.", + "maxItems": 100, + "minItems": 1 + } + }, + "required": [ + "pauses" + ] + }, + "AdminStreakPause": { + "title": "AdminStreakPause", + "type": "object", + "description": "A streak pause returned from the admin pauses endpoints.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "The unique ID of the streak pause." + }, + "userId": { + "type": "string", + "description": "The ID of the user the pause belongs to.", + "example": "user-123" + }, + "start": { + "type": "string", + "format": "date", + "description": "The first date the pause covers.", + "example": "2026-08-20" + }, + "end": { + "type": "string", + "format": "date", + "description": "The last date the pause covers.", + "example": "2026-08-27" + }, + "status": { + "type": "string", + "enum": [ + "active", + "archived" + ], + "description": "The status of the pause." + } + }, + "required": [ + "id", + "userId", + "start", + "end", + "status" + ] + }, + "CreateStreakPausesResponse": { + "title": "CreateStreakPausesResponse", + "type": "object", + "description": "Response containing created streak pauses and any issues encountered.", + "properties": { + "created": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminStreakPause" + }, + "description": "Array of streak pauses that were created." + }, + "issues": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminIssue" + }, + "description": "Array of issues encountered during pause creation." + } + }, + "required": [ + "created", + "issues" + ] + }, + "DeleteStreakPausesResponse": { + "title": "DeleteStreakPausesResponse", + "type": "object", + "description": "Response containing archived streak pauses and any issues encountered.", + "properties": { + "deleted": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeletedResource" + }, + "description": "Array of archived streak pause IDs." + }, + "issues": { + "type": "array", + "items": { + "$ref": "#/components/schemas/AdminIssue" + }, + "description": "Array of issues encountered during pause archival." + } + }, + "required": [ + "deleted", + "issues" + ] + }, "CreateAttributesRequest": { "title": "CreateAttributesRequest", "type": "array", diff --git a/openapi/application.json b/openapi/application.json index 1fd9cd75..44f77fb5 100644 --- a/openapi/application.json +++ b/openapi/application.json @@ -2,13 +2,13 @@ "openapi": "3.1.0", "info": { "title": "Trophy", - "version": "1.20.1" + "version": "1.21.0" }, "x-fern-global-headers": [ { "header": "X-SDK-VERSION", "name": "sdkVersion", - "x-fern-default": "1.20.1" + "x-fern-default": "1.21.0" } ], "paths": { @@ -2010,41 +2010,49 @@ "periodEnd": "2025-04-05", "expires": "2025-04-12", "extended": "2025-04-03T14:30:00Z", + "pauses": [], "streakHistory": [ { "periodStart": "2025-03-30", "periodEnd": "2025-04-05", - "length": 1 + "length": 1, + "usedPause": false }, { "periodStart": "2025-04-06", "periodEnd": "2025-04-12", - "length": 2 + "length": 2, + "usedPause": false }, { "periodStart": "2025-04-13", "periodEnd": "2025-04-19", - "length": 3 + "length": 3, + "usedPause": false }, { "periodStart": "2025-04-20", "periodEnd": "2025-04-26", - "length": 0 + "length": 0, + "usedPause": false }, { "periodStart": "2025-04-27", "periodEnd": "2025-05-03", - "length": 1 + "length": 1, + "usedPause": false }, { "periodStart": "2025-05-04", "periodEnd": "2025-05-10", - "length": 2 + "length": 2, + "usedPause": false }, { "periodStart": "2025-05-11", "periodEnd": "2025-05-17", - "length": 3 + "length": 3, + "usedPause": false } ] } @@ -4620,7 +4628,7 @@ "post": { "summary": "Points changed", "operationId": "webhooks_points_changed", - "description": "Triggered when a user is awarded or loses points. This event is fired a maximum of once per user per points system per minute.", + "description": "Triggered when a user is awarded or loses points. This event is fired a maximum of once per user per points system every fifteen minutes.", "requestBody": { "description": "The webhook event.", "content": { @@ -5035,7 +5043,7 @@ "post": { "summary": "Leaderboard changed", "operationId": "webhooks_leaderboard_changed", - "description": "Triggered when leaderboard rankings change.", + "description": "Triggered when leaderboard rankings change. This event is fired a maximum of once per leaderboard every fifteen minutes.", "requestBody": { "description": "The webhook event.", "content": { @@ -5427,7 +5435,7 @@ "post": { "summary": "Leaderboard rank changed", "operationId": "webhooks_leaderboard_rank_changed", - "description": "Triggered when a user's leaderboard rank changes.", + "description": "Triggered when a user's leaderboard rank changes. This event is fired a maximum of once per user per leaderboard every fifteen minutes.", "requestBody": { "description": "The webhook event.", "content": { @@ -5695,19 +5703,58 @@ "type": "boolean", "description": "Whether the user used a streak freeze during this period. Only present if the organization has enabled streak freezes.", "example": false + }, + "usedPause": { + "type": "boolean", + "description": "Whether the user's streak was paused during this period.", + "example": false } }, "required": [ "periodStart", "periodEnd", - "length" + "length", + "usedPause" + ] + } + }, + "pauses": { + "type": "array", + "description": "Upcoming and currently active streak pauses for the user. Past and archived pauses are omitted.", + "items": { + "type": "object", + "description": "An object representing a streak pause.", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "The unique ID of the streak pause." + }, + "start": { + "type": "string", + "format": "date", + "description": "The first date the pause covers.", + "example": "2026-08-20" + }, + "end": { + "type": "string", + "format": "date", + "description": "The last date the pause covers.", + "example": "2026-08-27" + } + }, + "required": [ + "id", + "start", + "end" ] } } }, "required": [ "extended", - "streakHistory" + "streakHistory", + "pauses" ] } ] diff --git a/snippets/streak-response-block.mdx b/snippets/streak-response-block.mdx index 320798ae..eb978c85 100644 --- a/snippets/streak-response-block.mdx +++ b/snippets/streak-response-block.mdx @@ -8,41 +8,55 @@ "periodStart": "2025-03-31", "periodEnd": "2025-04-05", "expires": "2025-04-12", + "pauses": [ + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "start": "2026-08-20", + "end": "2026-08-27" + } + ], "streakHistory": [ { "periodStart": "2025-03-30", "periodEnd": "2025-04-05", - "length": 1 + "length": 1, + "usedPause": false }, { "periodStart": "2025-04-06", "periodEnd": "2025-04-12", - "length": 2 + "length": 2, + "usedPause": false }, { "periodStart": "2025-04-13", "periodEnd": "2025-04-19", - "length": 3 + "length": 3, + "usedPause": false }, { "periodStart": "2025-04-20", "periodEnd": "2025-04-26", - "length": 0 + "length": 0, + "usedPause": false }, { "periodStart": "2025-04-27", "periodEnd": "2025-05-03", - "length": 1 + "length": 1, + "usedPause": false }, { "periodStart": "2025-05-04", "periodEnd": "2025-05-10", - "length": 2 + "length": 2, + "usedPause": false }, { "periodStart": "2025-05-11", "periodEnd": "2025-05-17", - "length": 3 + "length": 3, + "usedPause": false } ] } From bcc09d03a826f1c5410a7bd5f1ed6035a97631d9 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 21 Aug 2026 10:17:47 +0000 Subject: [PATCH 2/7] Update i18n.lock for streak pauses docs Refresh Lingo checksums so the frozen translation gate matches the new pause pages and updated streak source files. Co-authored-by: jasontlouro --- i18n.lock | 109 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 70 insertions(+), 39 deletions(-) diff --git a/i18n.lock b/i18n.lock index 6731c8d9..fa7b3461 100644 --- a/i18n.lock +++ b/i18n.lock @@ -962,7 +962,7 @@ checksums: content/41: 1191b96ec64242a19f43447ef7af155a content/42: 90d0e4bc15ea442181d8dc462d5f7c33 content/43: f95ceb19818666fbf6b851cb0a5e733a - content/44: d87a7aa16b897cd52bc2df13e9a93af2 + content/44: 6e79ae23c1719455e429b92bcc839b12 content/45: e66130735f1fe298cc80b97a666d5bea content/46: 7cf10ff79dfa04584ec7f2885430bd1e content/47: 624f0e41c8ea15ce77cd3270a1db4180 @@ -973,8 +973,11 @@ checksums: content/52: 889ae336e820bf64bf9a9e718e398b69 content/53: a64f63364045ef5cee1f72d5d5310c8a content/54: 5a2429a79da0c233105c776147a1aa84 - content/55: 10e8e9a59847ddd720c6d06b12c7b120 - content/56: 9799b973234bf2d10d5c971b267f55a5 + content/55: f54eca2e48f83b23715d4e024a2f4718 + content/56: 853ad7a01d8b9fc073508f8df84d974a + content/57: 3df147fc937d53be81b9eda333476936 + content/58: 10e8e9a59847ddd720c6d06b12c7b120 + content/59: 9799b973234bf2d10d5c971b267f55a5 f22316048205b16e3a434589e803e82b: meta/title: 16a229352e4e4bb5b14f38574c8f2723 meta/description: ffe37cf89d34043b5629a64d0263f83a @@ -3057,42 +3060,58 @@ checksums: content/22: 3a5b1b80506797525441e85460ee2a51 content/23: d300b0f0f9a24dac347eeddaef7c82a3 content/24: f1afe4d72b108602b3a93450760788f5 - content/25: 2b47756439adf8f9b38b04085a709a03 - content/26: b6f909922cc9e10746ea84ce96827b16 - content/27: 0b45597750a093259a241cf3c4da862e - content/28: d6facb51881f25f097fe04dbf2e5103f - content/29: 43ad0b6ea6fbeef69ece943e165a168e - content/30: fdefaf43995cd4efa70dfcaf981fd697 - content/31: 524454ff831052b4331a56d6f674ccaa - content/32: 2214e876e97977bf5cebec45dcdcd1c8 - content/33: fbdc0fc1e117f4e5cfeae94fc771c993 - content/34: 20bdf64fd91ed2bc4687a1657bbfae8a - content/35: 2dacfcc9d13a93d2965ca6051ee62fde - content/36: 4caecadc2bf024da1773cf2b612aa8cb - content/37: 3cfd18a2975ad68bef9d67e350e8c463 - content/38: 9e4d09a957ca66f58d4248300fbe2662 - content/39: 758ecef4a7a0b5d55fb97febe4184ec2 - content/40: 9aec72901fcecb0cdf45f729387b9742 - content/41: 71d6882b2ae9220e3bb0c6abc98fc236 - content/42: bfa82570db14cd44d636f90e20080898 - content/43: 59f82b2e0dbec73340a007cb020ab2ce - content/44: 54e6b1cb90e203d05d06a5d188238cd4 - content/45: 4f72e470a0dbe75e396f57952f29901a - content/46: 380be3ed5af370f2d36a66f4c55f7f0b - content/47: 5a5f6f25f2b2cf4ebbb5f018bb0d5824 - content/48: ed7cd0fb6f61c823f39fe089a7f62e1f - content/49: b3bc9605c19967a6162e1c72333251a9 - content/50: 6a5bc8b31ffa32876914a59c0882a336 - content/51: 40a3888d076524edcb9716f64683c5b3 - content/52: ca8396af4c4ecc5a806c42187204d877 - content/53: 98200505f691d3dcb12fa6833d0e88ad - content/54: df90d3b6267199a3dd86d820374aa785 - content/55: 286a2716711641435b4b996d8b22e881 - content/56: 29e769123cc029c8c9657dcd8d384b83 - content/57: 08345a94bd6f9b9539d128e5db15184a - content/58: 47770b5654a1f47d56eba81273ff08d9 - content/59: 10e8e9a59847ddd720c6d06b12c7b120 - content/60: 9799b973234bf2d10d5c971b267f55a5 + content/25: f54eca2e48f83b23715d4e024a2f4718 + content/26: 436aa442c7d61808162bfd9b5fd28a8b + content/27: 008f8dae4e748cc4b258dadbbd340887 + content/28: f42fb7dc2e3247184cea083fee89e3a8 + content/29: b75955d955dac9b43a659941bff4e9d2 + content/30: 0a308129fbd6cbc11825b5535d16121f + content/31: 75fc66d4cd183160c472887b94158023 + content/32: bcf9c5ec5fda6fb6a91bc3c745e2b372 + content/33: 6c2e152e0502c6e1ba03425956c939c1 + content/34: d8fd1e66d92a4a5a78c638308c2ada54 + content/35: 56bced711d71cdcfc3faaedf7768c4e6 + content/36: f34dda0acf61e6e574b8809e7753ae0f + content/37: f03f282ee16391d88de0cdf27d4ba812 + content/38: 000f69acf39db68262e439f9ca2dcfa2 + content/39: 2b47756439adf8f9b38b04085a709a03 + content/40: b6f909922cc9e10746ea84ce96827b16 + content/41: 0b45597750a093259a241cf3c4da862e + content/42: d6facb51881f25f097fe04dbf2e5103f + content/43: 43ad0b6ea6fbeef69ece943e165a168e + content/44: fdefaf43995cd4efa70dfcaf981fd697 + content/45: 524454ff831052b4331a56d6f674ccaa + content/46: 2214e876e97977bf5cebec45dcdcd1c8 + content/47: fbdc0fc1e117f4e5cfeae94fc771c993 + content/48: 20bdf64fd91ed2bc4687a1657bbfae8a + content/49: 2dacfcc9d13a93d2965ca6051ee62fde + content/50: 4caecadc2bf024da1773cf2b612aa8cb + content/51: 91ab34d44f402d50cb706d51ef0288b4 + content/52: 5ace91d5d169a3beb8f7f47bafe60836 + content/53: 3cfd18a2975ad68bef9d67e350e8c463 + content/54: 9e4d09a957ca66f58d4248300fbe2662 + content/55: 758ecef4a7a0b5d55fb97febe4184ec2 + content/56: 9aec72901fcecb0cdf45f729387b9742 + content/57: 71d6882b2ae9220e3bb0c6abc98fc236 + content/58: bfa82570db14cd44d636f90e20080898 + content/59: 59f82b2e0dbec73340a007cb020ab2ce + content/60: 54e6b1cb90e203d05d06a5d188238cd4 + content/61: 4f72e470a0dbe75e396f57952f29901a + content/62: 380be3ed5af370f2d36a66f4c55f7f0b + content/63: 5a5f6f25f2b2cf4ebbb5f018bb0d5824 + content/64: ed7cd0fb6f61c823f39fe089a7f62e1f + content/65: b3bc9605c19967a6162e1c72333251a9 + content/66: ac3267698b45c30fea7622d6f38767b5 + content/67: 40a3888d076524edcb9716f64683c5b3 + content/68: f8bc90b1b7d0108fdfad2e3bd7641dbf + content/69: 98200505f691d3dcb12fa6833d0e88ad + content/70: df90d3b6267199a3dd86d820374aa785 + content/71: 286a2716711641435b4b996d8b22e881 + content/72: 29e769123cc029c8c9657dcd8d384b83 + content/73: 08345a94bd6f9b9539d128e5db15184a + content/74: 47770b5654a1f47d56eba81273ff08d9 + content/75: 10e8e9a59847ddd720c6d06b12c7b120 + content/76: 9799b973234bf2d10d5c971b267f55a5 9f5464896b543cfd1d607b30a9997155: meta/title: e771f23130f9aab4f3e2e99acacf5d5a meta/description: 8539ebe90ff733bef6498db1933f3a57 @@ -7023,3 +7042,15 @@ checksums: content/26: e815c435234e61991573554f3b017fe1 content/27: 10e8e9a59847ddd720c6d06b12c7b120 content/28: 9799b973234bf2d10d5c971b267f55a5 + b15fa1c26da90316f7e8951e1ce18470: + meta/title: 1a0643dc8057fe771da3366044fdee76 + meta/openapi: 63b1e6a9c74af0e1c92c182d3cee355d + content/0: c3d96e3528a55b20b8fbcae10af25b02 + content/1: 264d832bc605beaf5168c080bfed567c + content/2: 580af53aa9812f2ec29a632e145669a5 + b0fce8448e0e09224983fe6dc137a18c: + meta/title: 81ff989f5182157d37a38620eb9c9b84 + meta/openapi: 77443e4bbca3e94947607a45397e6bb4 + content/0: c3d96e3528a55b20b8fbcae10af25b02 + content/1: 264d832bc605beaf5168c080bfed567c + content/2: 580af53aa9812f2ec29a632e145669a5 From 1312a3e8b74555476d28430145d25111376148b2 Mon Sep 17 00:00:00 2001 From: Jason Louro Date: Fri, 21 Aug 2026 12:33:25 +0200 Subject: [PATCH 3/7] fixes --- .../{archive-pauses.mdx => delete-pauses.mdx} | 2 +- features/streaks.mdx | 22 +++++++------------ guides/how-to-build-a-streaks-feature.mdx | 2 +- 3 files changed, 10 insertions(+), 16 deletions(-) rename admin-api/endpoints/streaks/{archive-pauses.mdx => delete-pauses.mdx} (86%) diff --git a/admin-api/endpoints/streaks/archive-pauses.mdx b/admin-api/endpoints/streaks/delete-pauses.mdx similarity index 86% rename from admin-api/endpoints/streaks/archive-pauses.mdx rename to admin-api/endpoints/streaks/delete-pauses.mdx index 9d633696..5947ae51 100644 --- a/admin-api/endpoints/streaks/archive-pauses.mdx +++ b/admin-api/endpoints/streaks/delete-pauses.mdx @@ -1,5 +1,5 @@ --- -title: Archive streak pauses +title: Delete streak pauses openapi: "/openapi/admin.json DELETE /streaks/pauses" --- diff --git a/features/streaks.mdx b/features/streaks.mdx index da5a18f3..503949ac 100644 --- a/features/streaks.mdx +++ b/features/streaks.mdx @@ -80,12 +80,6 @@ In Trophy you also configure the maximum number of freezes that each user can ha Streak pauses protect a user's streak over a known date range, such as a vacation or other planned break. While a pause covers a period, Trophy maintains the user's streak length instead of ending the streak if they miss their [streak conditions](#streak-conditions). -Unlike [streak freezes](#streak-freezes), pauses are not consumed one period at a time. Each pause has a start date and an end date, and it applies for that entire range. - - -Use freezes for occasional missed periods. Use pauses when you already know a user will be away for a specific stretch of time. - - ### Creating Pauses {#creating-pauses} Create pauses with the [create streak pauses admin API](/admin-api/endpoints/streaks/create-pauses). You can create pauses for up to 100 users in a single request. @@ -93,18 +87,18 @@ Create pauses with the [create streak pauses admin API](/admin-api/endpoints/str Each pause requires: - `userId`: the user to create a pause for -- `start`: the first date the pause covers, in `YYYY-MM-DD` format. Must not be before today in the user's timezone. -- `end`: the last date the pause covers, in `YYYY-MM-DD` format. Must be on or after `start`. +- `start`: the first date the pause covers +- `end`: the last date the pause covers Start dates in the past are rejected. If you've [configured time zones](/features/users#param-tz) for your users, Trophy evaluates `start` against today in each user's local timezone. -### Archiving Pauses {#archiving-pauses} +### Deleting Pauses {#deleting-pauses} -To stop a pause from applying, archive it with the [archive streak pauses admin API](/admin-api/endpoints/streaks/archive-pauses). Pause records are not deleted. Archiving sets their status to `archived` so they no longer affect streak logic. +To stop a pause from applying, delete it with the [delete streak pauses admin API](/admin-api/endpoints/streaks/delete-pauses). ### Reading Pauses {#reading-pauses} -The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns upcoming and currently active pauses in the `pauses` field. Past and archived pauses are omitted. +The [user streaks API](/api-reference/endpoints/users/get-a-users-streak) returns upcoming and currently active pauses in the `pauses` field. Past and deleted pauses are omitted. Each period in `streakHistory` includes `usedPause`, which is `true` when the user's streak was paused during that period. @@ -148,11 +142,11 @@ To learn more about how to set user preferences for a specific user, read the de This section outlines some of the operations you can perform to manage user's streaks in your application. -### Pausing A Users Streak {#pausing-a-users-streak} +### Pausing A User's Streak {#pausing-a-users-streak} -To pause a user's streak for a specific date range, use the [create streak pauses admin API](/admin-api/endpoints/streaks/create-pauses). See [streak pauses](#streak-pauses) for how pauses work, including how to archive them. +To pause a user's streak for a specific date range, use the [create streak pauses admin API](/admin-api/endpoints/streaks/create-pauses). See [streak pauses](#streak-pauses) for how pauses work, including how to delete them. -### Restoring A Users Streak {#restoring-a-users-streak} +### Restoring A User's Streak {#restoring-a-users-streak} To restore a user's streak, head to the user details page and use the 'Restore Streak' action. Restoring a user's streak sets it to the length it was when they last lost it. diff --git a/guides/how-to-build-a-streaks-feature.mdx b/guides/how-to-build-a-streaks-feature.mdx index 7f52712a..70a987f7 100644 --- a/guides/how-to-build-a-streaks-feature.mdx +++ b/guides/how-to-build-a-streaks-feature.mdx @@ -164,7 +164,7 @@ To fetch data on a user's streak use the [user streak API](/api-reference/endpoi -This API not only returns data on the user's current streak like `length` and `expires`, but it can also return historical streak data which can be used to display any kind of streak UI you like through the `historyPeriods` parameter. The response also includes upcoming and active [streak pauses](/features/streaks#streak-pauses) in `pauses`, and each history period includes `usedPause`. +This API not only returns data on the user's current streak like `length` and `expires`, but it can also return historical streak data which can be used to display any kind of streak UI you like through the `historyPeriods` parameter. From 685f2ea7012ca8041598bfd8e33c7f390c2b24ec Mon Sep 17 00:00:00 2001 From: Jason Louro Date: Fri, 21 Aug 2026 12:35:04 +0200 Subject: [PATCH 4/7] fix es --- .../endpoints/streaks/{archive-pauses.mdx => delete-pauses.mdx} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename es/admin-api/endpoints/streaks/{archive-pauses.mdx => delete-pauses.mdx} (85%) diff --git a/es/admin-api/endpoints/streaks/archive-pauses.mdx b/es/admin-api/endpoints/streaks/delete-pauses.mdx similarity index 85% rename from es/admin-api/endpoints/streaks/archive-pauses.mdx rename to es/admin-api/endpoints/streaks/delete-pauses.mdx index bd85710f..50cc1916 100644 --- a/es/admin-api/endpoints/streaks/archive-pauses.mdx +++ b/es/admin-api/endpoints/streaks/delete-pauses.mdx @@ -1,5 +1,5 @@ --- -title: Archivar pausas de racha +title: Eliminar pausas de racha openapi: "/openapi/admin.json DELETE /streaks/pauses" --- From 59f9c5076863787bd2550d926f3d7bb40e6cced6 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 21 Aug 2026 10:37:20 +0000 Subject: [PATCH 5/7] Align pause docs with delete naming Update nav, Spanish pages, and i18n.lock after renaming the admin endpoint page to delete-pauses. Keep the OpenAPI operation title. Co-authored-by: jasontlouro --- admin-api/endpoints/streaks/delete-pauses.mdx | 2 +- docs.json | 4 +- es/features/streaks.mdx | 18 +-- es/guides/how-to-build-a-streaks-feature.mdx | 2 +- i18n.lock | 106 +++++++++--------- 5 files changed, 65 insertions(+), 67 deletions(-) diff --git a/admin-api/endpoints/streaks/delete-pauses.mdx b/admin-api/endpoints/streaks/delete-pauses.mdx index 5947ae51..9d633696 100644 --- a/admin-api/endpoints/streaks/delete-pauses.mdx +++ b/admin-api/endpoints/streaks/delete-pauses.mdx @@ -1,5 +1,5 @@ --- -title: Delete streak pauses +title: Archive streak pauses openapi: "/openapi/admin.json DELETE /streaks/pauses" --- diff --git a/docs.json b/docs.json index 5b83cdfc..07ef75ce 100644 --- a/docs.json +++ b/docs.json @@ -261,7 +261,7 @@ "pages": [ "admin-api/endpoints/streaks/grant-freezes", "admin-api/endpoints/streaks/create-pauses", - "admin-api/endpoints/streaks/archive-pauses", + "admin-api/endpoints/streaks/delete-pauses", "admin-api/endpoints/streaks/restore-streaks" ] }, @@ -649,7 +649,7 @@ "pages": [ "es/admin-api/endpoints/streaks/grant-freezes", "es/admin-api/endpoints/streaks/create-pauses", - "es/admin-api/endpoints/streaks/archive-pauses", + "es/admin-api/endpoints/streaks/delete-pauses", "es/admin-api/endpoints/streaks/restore-streaks" ] }, diff --git a/es/features/streaks.mdx b/es/features/streaks.mdx index 0f8d62d9..6afd94f2 100644 --- a/es/features/streaks.mdx +++ b/es/features/streaks.mdx @@ -80,12 +80,6 @@ En Trophy también configuras el número máximo de congelaciones que cada usuar Las pausas de racha protegen la racha de un usuario durante un rango de fechas conocido, como unas vacaciones u otra pausa planificada. Mientras una pausa cubre un período, Trophy mantiene la duración de la racha del usuario en lugar de terminarla si no cumple sus [condiciones de racha](#streak-conditions). -A diferencia de las [congelaciones de rachas](#streak-freezes), las pausas no se consumen un período a la vez. Cada pausa tiene una fecha de inicio y una fecha de fin, y se aplica durante todo ese rango. - - -Usa congelaciones para períodos ocasionales que se pierden. Usa pausas cuando ya sabes que un usuario estará ausente durante un período de tiempo específico. - - ### Crear Pausas {#creating-pauses} Crea pausas con la [API de administración para crear pausas de racha](/es/admin-api/endpoints/streaks/create-pauses). Puedes crear pausas para hasta 100 usuarios en una sola solicitud. @@ -93,18 +87,18 @@ Crea pausas con la [API de administración para crear pausas de racha](/es/admin Cada pausa requiere: - `userId`: el usuario para el que crear una pausa -- `start`: la primera fecha que cubre la pausa, en formato `YYYY-MM-DD`. No debe ser anterior a hoy en la zona horaria del usuario. -- `end`: la última fecha que cubre la pausa, en formato `YYYY-MM-DD`. Debe ser igual o posterior a `start`. +- `start`: la primera fecha que cubre la pausa +- `end`: la última fecha que cubre la pausa Las fechas de inicio en el pasado se rechazan. Si has [configurado zonas horarias](/es/features/users#param-tz) para tus usuarios, Trophy evalúa `start` contra el día de hoy en la zona horaria local de cada usuario. -### Archivar Pausas {#archiving-pauses} +### Eliminar Pausas {#deleting-pauses} -Para dejar de aplicar una pausa, archívala con la [API de administración para archivar pausas de racha](/es/admin-api/endpoints/streaks/archive-pauses). Los registros de pausas no se eliminan. Archivar establece su estado en `archived` para que ya no afecten la lógica de rachas. +Para dejar de aplicar una pausa, elimínala con la [API de administración para eliminar pausas de racha](/es/admin-api/endpoints/streaks/delete-pauses). ### Leer Pausas {#reading-pauses} -La [API de rachas de usuario](/es/api-reference/endpoints/users/get-a-users-streak) devuelve las pausas próximas y actualmente activas en el campo `pauses`. Se omiten las pausas pasadas y archivadas. +La [API de rachas de usuario](/es/api-reference/endpoints/users/get-a-users-streak) devuelve las pausas próximas y actualmente activas en el campo `pauses`. Se omiten las pausas pasadas y eliminadas. Cada período en `streakHistory` incluye `usedPause`, que es `true` cuando la racha del usuario estuvo en pausa durante ese período. @@ -150,7 +144,7 @@ Esta sección describe algunas de las operaciones que puedes realizar para admin ### Pausar la Racha de un Usuario {#pausing-a-users-streak} -Para pausar la racha de un usuario durante un rango de fechas específico, usa la [API de administración para crear pausas de racha](/es/admin-api/endpoints/streaks/create-pauses). Consulta [pausas de racha](#streak-pauses) para saber cómo funcionan las pausas, incluyendo cómo archivarlas. +Para pausar la racha de un usuario durante un rango de fechas específico, usa la [API de administración para crear pausas de racha](/es/admin-api/endpoints/streaks/create-pauses). Consulta [pausas de racha](#streak-pauses) para saber cómo funcionan las pausas, incluyendo cómo eliminarlas. ### Restaurar la Racha de un Usuario {#restoring-a-users-streak} diff --git a/es/guides/how-to-build-a-streaks-feature.mdx b/es/guides/how-to-build-a-streaks-feature.mdx index 5fee6a1b..37101679 100644 --- a/es/guides/how-to-build-a-streaks-feature.mdx +++ b/es/guides/how-to-build-a-streaks-feature.mdx @@ -160,7 +160,7 @@ Para obtener datos sobre la racha de un usuario, usa la [API de racha de usuario -Esta API no solo devuelve datos sobre la racha actual del usuario como `length` y `expires`, sino que también puede devolver datos históricos de rachas que se pueden usar para mostrar cualquier tipo de interfaz de racha que desees a través del parámetro `historyPeriods`. La respuesta también incluye [pausas de racha](/es/features/streaks#streak-pauses) próximas y activas en `pauses`, y cada período del historial incluye `usedPause`. +Esta API no solo devuelve datos sobre la racha actual del usuario como `length` y `expires`, sino que también puede devolver datos históricos de rachas que se pueden usar para mostrar cualquier tipo de interfaz de racha que desees a través del parámetro `historyPeriods`. diff --git a/i18n.lock b/i18n.lock index fa7b3461..5e090e99 100644 --- a/i18n.lock +++ b/i18n.lock @@ -962,7 +962,7 @@ checksums: content/41: 1191b96ec64242a19f43447ef7af155a content/42: 90d0e4bc15ea442181d8dc462d5f7c33 content/43: f95ceb19818666fbf6b851cb0a5e733a - content/44: 6e79ae23c1719455e429b92bcc839b12 + content/44: d87a7aa16b897cd52bc2df13e9a93af2 content/45: e66130735f1fe298cc80b97a666d5bea content/46: 7cf10ff79dfa04584ec7f2885430bd1e content/47: 624f0e41c8ea15ce77cd3270a1db4180 @@ -3062,56 +3062,54 @@ checksums: content/24: f1afe4d72b108602b3a93450760788f5 content/25: f54eca2e48f83b23715d4e024a2f4718 content/26: 436aa442c7d61808162bfd9b5fd28a8b - content/27: 008f8dae4e748cc4b258dadbbd340887 - content/28: f42fb7dc2e3247184cea083fee89e3a8 - content/29: b75955d955dac9b43a659941bff4e9d2 - content/30: 0a308129fbd6cbc11825b5535d16121f - content/31: 75fc66d4cd183160c472887b94158023 - content/32: bcf9c5ec5fda6fb6a91bc3c745e2b372 - content/33: 6c2e152e0502c6e1ba03425956c939c1 - content/34: d8fd1e66d92a4a5a78c638308c2ada54 - content/35: 56bced711d71cdcfc3faaedf7768c4e6 - content/36: f34dda0acf61e6e574b8809e7753ae0f - content/37: f03f282ee16391d88de0cdf27d4ba812 - content/38: 000f69acf39db68262e439f9ca2dcfa2 - content/39: 2b47756439adf8f9b38b04085a709a03 - content/40: b6f909922cc9e10746ea84ce96827b16 - content/41: 0b45597750a093259a241cf3c4da862e - content/42: d6facb51881f25f097fe04dbf2e5103f - content/43: 43ad0b6ea6fbeef69ece943e165a168e - content/44: fdefaf43995cd4efa70dfcaf981fd697 - content/45: 524454ff831052b4331a56d6f674ccaa - content/46: 2214e876e97977bf5cebec45dcdcd1c8 - content/47: fbdc0fc1e117f4e5cfeae94fc771c993 - content/48: 20bdf64fd91ed2bc4687a1657bbfae8a - content/49: 2dacfcc9d13a93d2965ca6051ee62fde - content/50: 4caecadc2bf024da1773cf2b612aa8cb - content/51: 91ab34d44f402d50cb706d51ef0288b4 - content/52: 5ace91d5d169a3beb8f7f47bafe60836 - content/53: 3cfd18a2975ad68bef9d67e350e8c463 - content/54: 9e4d09a957ca66f58d4248300fbe2662 - content/55: 758ecef4a7a0b5d55fb97febe4184ec2 - content/56: 9aec72901fcecb0cdf45f729387b9742 - content/57: 71d6882b2ae9220e3bb0c6abc98fc236 - content/58: bfa82570db14cd44d636f90e20080898 - content/59: 59f82b2e0dbec73340a007cb020ab2ce - content/60: 54e6b1cb90e203d05d06a5d188238cd4 - content/61: 4f72e470a0dbe75e396f57952f29901a - content/62: 380be3ed5af370f2d36a66f4c55f7f0b - content/63: 5a5f6f25f2b2cf4ebbb5f018bb0d5824 - content/64: ed7cd0fb6f61c823f39fe089a7f62e1f - content/65: b3bc9605c19967a6162e1c72333251a9 - content/66: ac3267698b45c30fea7622d6f38767b5 - content/67: 40a3888d076524edcb9716f64683c5b3 - content/68: f8bc90b1b7d0108fdfad2e3bd7641dbf - content/69: 98200505f691d3dcb12fa6833d0e88ad - content/70: df90d3b6267199a3dd86d820374aa785 - content/71: 286a2716711641435b4b996d8b22e881 - content/72: 29e769123cc029c8c9657dcd8d384b83 - content/73: 08345a94bd6f9b9539d128e5db15184a - content/74: 47770b5654a1f47d56eba81273ff08d9 - content/75: 10e8e9a59847ddd720c6d06b12c7b120 - content/76: 9799b973234bf2d10d5c971b267f55a5 + content/27: b75955d955dac9b43a659941bff4e9d2 + content/28: 0a308129fbd6cbc11825b5535d16121f + content/29: 75fc66d4cd183160c472887b94158023 + content/30: c7564d1e160d174268defdbc3f3e5ecd + content/31: 6c2e152e0502c6e1ba03425956c939c1 + content/32: 2a2ec04319e0d097d6bfd0a59f866447 + content/33: 7f514b74b42a9c9b39dfbfa6323bb450 + content/34: f34dda0acf61e6e574b8809e7753ae0f + content/35: 7b6f98aeeee6661aef43d14eb0f19071 + content/36: 000f69acf39db68262e439f9ca2dcfa2 + content/37: 2b47756439adf8f9b38b04085a709a03 + content/38: b6f909922cc9e10746ea84ce96827b16 + content/39: 0b45597750a093259a241cf3c4da862e + content/40: d6facb51881f25f097fe04dbf2e5103f + content/41: 43ad0b6ea6fbeef69ece943e165a168e + content/42: fdefaf43995cd4efa70dfcaf981fd697 + content/43: 524454ff831052b4331a56d6f674ccaa + content/44: 2214e876e97977bf5cebec45dcdcd1c8 + content/45: fbdc0fc1e117f4e5cfeae94fc771c993 + content/46: 20bdf64fd91ed2bc4687a1657bbfae8a + content/47: 2dacfcc9d13a93d2965ca6051ee62fde + content/48: 4caecadc2bf024da1773cf2b612aa8cb + content/49: b1704d9be89cf0327f93e58b1b278c06 + content/50: b2781293b2faf65a1eee51baca384490 + content/51: 91ffb03304d0dc66f9fc2357aa39346f + content/52: 9e4d09a957ca66f58d4248300fbe2662 + content/53: 758ecef4a7a0b5d55fb97febe4184ec2 + content/54: 9aec72901fcecb0cdf45f729387b9742 + content/55: 71d6882b2ae9220e3bb0c6abc98fc236 + content/56: bfa82570db14cd44d636f90e20080898 + content/57: 59f82b2e0dbec73340a007cb020ab2ce + content/58: 54e6b1cb90e203d05d06a5d188238cd4 + content/59: 4f72e470a0dbe75e396f57952f29901a + content/60: 380be3ed5af370f2d36a66f4c55f7f0b + content/61: 5a5f6f25f2b2cf4ebbb5f018bb0d5824 + content/62: ed7cd0fb6f61c823f39fe089a7f62e1f + content/63: b3bc9605c19967a6162e1c72333251a9 + content/64: ac3267698b45c30fea7622d6f38767b5 + content/65: 40a3888d076524edcb9716f64683c5b3 + content/66: f8bc90b1b7d0108fdfad2e3bd7641dbf + content/67: 98200505f691d3dcb12fa6833d0e88ad + content/68: df90d3b6267199a3dd86d820374aa785 + content/69: 286a2716711641435b4b996d8b22e881 + content/70: 29e769123cc029c8c9657dcd8d384b83 + content/71: 08345a94bd6f9b9539d128e5db15184a + content/72: 47770b5654a1f47d56eba81273ff08d9 + content/73: 10e8e9a59847ddd720c6d06b12c7b120 + content/74: 9799b973234bf2d10d5c971b267f55a5 9f5464896b543cfd1d607b30a9997155: meta/title: e771f23130f9aab4f3e2e99acacf5d5a meta/description: 8539ebe90ff733bef6498db1933f3a57 @@ -7054,3 +7052,9 @@ checksums: content/0: c3d96e3528a55b20b8fbcae10af25b02 content/1: 264d832bc605beaf5168c080bfed567c content/2: 580af53aa9812f2ec29a632e145669a5 + 445b7d324d865a5796fd42e5a37e584e: + meta/title: 81ff989f5182157d37a38620eb9c9b84 + meta/openapi: 77443e4bbca3e94947607a45397e6bb4 + content/0: c3d96e3528a55b20b8fbcae10af25b02 + content/1: 264d832bc605beaf5168c080bfed567c + content/2: 580af53aa9812f2ec29a632e145669a5 From 845f1a44cffedb639753ecf63acf34d669244f1f Mon Sep 17 00:00:00 2001 From: Jason Louro Date: Fri, 21 Aug 2026 13:42:13 +0200 Subject: [PATCH 6/7] update openapi specs and rename archive -> delete --- admin-api/endpoints/streaks/delete-pauses.mdx | 2 +- openapi/admin.json | 20 +++++++++---------- openapi/application.json | 6 +++--- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/admin-api/endpoints/streaks/delete-pauses.mdx b/admin-api/endpoints/streaks/delete-pauses.mdx index 9d633696..5947ae51 100644 --- a/admin-api/endpoints/streaks/delete-pauses.mdx +++ b/admin-api/endpoints/streaks/delete-pauses.mdx @@ -1,5 +1,5 @@ --- -title: Archive streak pauses +title: Delete streak pauses openapi: "/openapi/admin.json DELETE /streaks/pauses" --- diff --git a/openapi/admin.json b/openapi/admin.json index a6632ac6..293e28c5 100644 --- a/openapi/admin.json +++ b/openapi/admin.json @@ -2,13 +2,13 @@ "openapi": "3.1.0", "info": { "title": "Trophy", - "version": "1.21.0" + "version": "1.21.1" }, "x-fern-global-headers": [ { "header": "X-SDK-VERSION", "name": "sdkVersion", - "x-fern-default": "1.21.0" + "x-fern-default": "1.21.1" } ], "paths": { @@ -1826,7 +1826,7 @@ ] }, "delete": { - "description": "Delete (archive) points systems by ID.", + "description": "Delete points systems by ID.", "operationId": "admin_points_systems_delete", "x-fern-server-name": "admin", "x-fern-sdk-group-name": [ @@ -3862,7 +3862,7 @@ ] }, "delete": { - "description": "Delete (archive) points triggers by ID. Maximum 100 trigger IDs per request.", + "description": "Delete points triggers by ID. Maximum 100 trigger IDs per request.", "operationId": "admin_points_triggers_delete", "x-fern-server-name": "admin", "x-fern-sdk-group-name": [ @@ -5030,7 +5030,7 @@ ] }, "delete": { - "description": "Archive streak pauses by ID. Pause records are not deleted; their status is set to archived so they no longer apply to streak logic.", + "description": "Delete streak pauses by ID.", "operationId": "admin_streaks_pauses_delete", "x-fern-server-name": "admin", "x-fern-sdk-group-name": [ @@ -5060,7 +5060,7 @@ { "name": "ids", "in": "query", - "description": "Streak pause IDs to archive. Repeat the query param or provide a comma-separated list.", + "description": "Streak pause IDs to delete. Repeat the query param or provide a comma-separated list.", "required": true, "schema": { "type": "array", @@ -5148,7 +5148,7 @@ } } }, - "summary": "Archive streak pauses", + "summary": "Delete streak pauses", "security": [ { "ApiKeyAuth": [] @@ -6467,21 +6467,21 @@ "DeleteStreakPausesResponse": { "title": "DeleteStreakPausesResponse", "type": "object", - "description": "Response containing archived streak pauses and any issues encountered.", + "description": "Response containing deleted streak pauses and any issues encountered.", "properties": { "deleted": { "type": "array", "items": { "$ref": "#/components/schemas/DeletedResource" }, - "description": "Array of archived streak pause IDs." + "description": "Array of deleted streak pause IDs." }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/AdminIssue" }, - "description": "Array of issues encountered during pause archival." + "description": "Array of issues encountered during pause deletion." } }, "required": [ diff --git a/openapi/application.json b/openapi/application.json index 44f77fb5..6fe3bdaa 100644 --- a/openapi/application.json +++ b/openapi/application.json @@ -2,13 +2,13 @@ "openapi": "3.1.0", "info": { "title": "Trophy", - "version": "1.21.0" + "version": "1.21.1" }, "x-fern-global-headers": [ { "header": "X-SDK-VERSION", "name": "sdkVersion", - "x-fern-default": "1.21.0" + "x-fern-default": "1.21.1" } ], "paths": { @@ -5720,7 +5720,7 @@ }, "pauses": { "type": "array", - "description": "Upcoming and currently active streak pauses for the user. Past and archived pauses are omitted.", + "description": "Upcoming and currently active streak pauses for the user.", "items": { "type": "object", "description": "An object representing a streak pause.", From b5ec6342eb97666018d4a0965314ec944d4c9c39 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 21 Aug 2026 11:45:02 +0000 Subject: [PATCH 7/7] Update i18n.lock after delete pauses title change Refresh the Lingo checksum for the Admin delete-pauses page now that the OpenAPI summary is Delete streak pauses. Co-authored-by: jasontlouro --- i18n.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n.lock b/i18n.lock index 5e090e99..5c23640a 100644 --- a/i18n.lock +++ b/i18n.lock @@ -7053,7 +7053,7 @@ checksums: content/1: 264d832bc605beaf5168c080bfed567c content/2: 580af53aa9812f2ec29a632e145669a5 445b7d324d865a5796fd42e5a37e584e: - meta/title: 81ff989f5182157d37a38620eb9c9b84 + meta/title: 61ff643dc79ca2d6f8e5f138f8892bf8 meta/openapi: 77443e4bbca3e94947607a45397e6bb4 content/0: c3d96e3528a55b20b8fbcae10af25b02 content/1: 264d832bc605beaf5168c080bfed567c