Skip to content

docs: ledger de contrato al día con B2B 1.5.0 / admin 1.1.0 #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LucasLeguizamo wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: ledger de contrato al día con B2B 1.5.0 / admin 1.1.0 #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion CONTRACT-GAPS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ Estados: `identified` (detectado, sin issue) · `requested` (issue abierto) ·
| Post-venta comprador B2C (reenvío de ticket sin credenciales) | `POST /public/tickets/{code}/resend` (reenvía QR/email al mail del comprador, rate-limited, email enmascarado en la respuesta) | B2C (`/api/public`) | mcp ✓ | [#191](https://github.com/AppFreeticket/free-admin/issues/191) | shipped |

| Authorization server OAuth 2.1 para el MCP remoto — claude.ai exige OAuth para connectors con credenciales. Resuelto **embebiendo el AS en el propio mcp** (v0.10.0): tokens stateless que sellan API key + workspace + sesión admin; no requirió endpoint nuevo en free-admin. `FT_OAUTH_ISSUER` permite delegar a un AS de free-admin si algún día existe | `/.well-known/oauth-authorization-server` (RFC 8414), dynamic client registration (RFC 7591), `/authorize` + `/token` con PKCE y página de consentimiento — todo servido por el mcp | B2B | mcp ✓ | — | shipped |
| Update endpoints sin `requestBody` en el spec — el mcp no puede tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedan fuera de la Ola B | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — declarar `requestBody` (schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate`) | B2B | mcp | — | identified |
| Update endpoints sin `requestBody` en el spec — el mcp no podía tipar el cuerpo, así que `event_dates_create/update`, `ticket_types_update`, `plans_update` y `venues_update` quedaban fuera de la Ola B. **Resuelto en el contrato 1.5.0**: los cinco schemas existen y el mcp los expone (v0.12.0) | `POST /events/{id}/dates`, `PATCH /events/{id}/dates/{dateId}`, `PATCH /ticket-types/{id}`, `PATCH /membership-plans/{id}`, `PATCH /venues/{id}` — schemas `EventDateCreate/Update`, `TicketTypeUpdate`, `MembershipPlanUpdate`, `VenueUpdate` | B2B | mcp ✓ | — | shipped |

@qodo-code-review qodo-code-review Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

2. Roadmap quedó desactualizado 🐞 Bug ⚙ Maintainability

CONTRACT-GAPS.md marca como shipped el gap de updates sin requestBody, pero ROADMAP-AI-FIRST.md
todavía deja event_dates_create/update, ticket_types_update, plans_update y venues_update
como pendientes por ese mismo gap. Esto introduce drift de documentación y puede llevar a trabajo
duplicado o a creer que la Ola B sigue bloqueada.
Agent Prompt 
### Issue description
El roadmap sigue afirmando que varios tools están bloqueados por el gap “sin requestBody”, pero el ledger ya lo marcó `shipped`.

### Issue Context
El PR cambia el estado del gap a `shipped` en `CONTRACT-GAPS.md`, pero no actualiza el roadmap donde esos items figuran como pendientes.

### Fix Focus Areas
- ROADMAP-AI-FIRST.md[75-103]
- CONTRACT-GAPS.md[33-33]

### Suggested change
- Marcar como completados (`[x]`) los items `event_dates_create`, `event_dates_update`, `ticket_types_update`, `plans_update`, `venues_update`.
- Remover la nota “hueco de contrato (sin requestBody)” o reemplazarla por una nota histórica (opcional) que apunte al contrato 1.5.0.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

| API key de servicio self-service — un cron server-side (Vercel) no puede usar el device flow interactivo, y no había forma de acuñar una `ft_live_…` sin entrar al backend | `GET/POST/DELETE /api-keys` (scope `read`/`write`, `expiresAt`, el plano solo en la respuesta de creación) | B2B | cli ✓ (`ft api-keys`), mcp ✓ (solo list) | [freeticket-cli#29](https://github.com/AppFreeticket/freeticket-cli/issues/29) | shipped |
Comment on lines +33 to +34

@qodo-code-review qodo-code-review Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. contract-gaps.md not in english 📘 Rule violation ⚙ Maintainability

The PR adds/updates technical documentation content in Spanish, but repository documentation must be
written in English. This breaks the repo’s documentation language/locale convention and reduces
consistency for the intended audience.
Agent Prompt 
## Issue description
Technical documentation updates in `CONTRACT-GAPS.md` are written in Spanish, but repo documentation must be in English.

## Issue Context
Per the documentation language/locale convention, technical documentation should be English (end-user copy may be neutral Spanish).

## Fix Focus Areas
- CONTRACT-GAPS.md[33-39]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

@qodo-code-review qodo-code-review Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

4. Columna de issues ambigua 🐞 Bug ⚙ Maintainability

La tabla define la 5ª columna como “Issue free-admin”, pero se agregaron filas que enlazan issues de
freeticket-cli en esa columna. Esto rompe la semántica declarada del ledger y el workflow descrito
por endpoint-requester (gap ↔ issue en free-admin).
Agent Prompt 
### Issue description
La columna “Issue free-admin” ahora contiene links a issues de otros repos (p.ej. freeticket-cli), lo que vuelve el ledger ambiguo para el proceso de `endpoint-requester`.

### Issue Context
`endpoint-requester` documenta explícitamente la tabla con la columna “Issue free-admin” y el cruce de enlaces con issues en `AppFreeticket/free-admin`.

### Fix Focus Areas
- CONTRACT-GAPS.md[15-16]
- CONTRACT-GAPS.md[34-38]
- .claude/agents/endpoint-requester.md[76-84]

### Suggested change
- **Opción A (mínimo cambio):** mantener la columna como “Issue free-admin” y mover los links de CLI a la columna “Cliente” o al texto de “Funcionalidad”, dejando `—` en la columna de free-admin cuando no aplique.
- **Opción B (más claro):** renombrar la columna a “Issue/Tracking” (o agregar una columna adicional para “Issue cliente”) y actualizar la plantilla en `endpoint-requester.md` para reflejar la nueva estructura.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

| Service token de plataforma para `ft admin` headless — el superadmin solo tenía la cookie de sesión del browser | `GET/POST/DELETE /api/admin/tokens` | Admin | cli ✓ (`ft admin tokens`), mcp ✓ (solo list) | — | shipped |

@qodo-code-review qodo-code-review Bot Aug 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

3. Paths admin con prefijo mixto 🐞 Bug ⚙ Maintainability

En el ledger se documentan endpoints admin con prefijo /api/admin mientras el resto de docs usa
paths relativos al contrato (p.ej. /workspaces/{id}). Esta mezcla hace ambiguo si se está listando
el path del spec o la URL completa del backend.
Agent Prompt 
### Issue description
El ledger mezcla notación de paths: algunas filas admin usan `/api/admin/...` y otras docs (roadmap) usan `/...` relativo al spec.

### Issue Context
Para evitar confusiones (especialmente al pedir endpoints vía `endpoint-requester`), conviene tener una única convención: o siempre paths relativos al contrato, o siempre URLs con prefijo.

### Fix Focus Areas
- CONTRACT-GAPS.md[35-39]
- ROADMAP-AI-FIRST.md[137-141]

### Suggested change
- Elegir una convención y aplicarla consistentemente:
  - **Opción A (recomendada):** paths relativos al contrato (sin `/api/admin`), ej. `GET/POST/DELETE /tokens`, `PATCH /workspaces/{id}`, `POST /workspaces/{id}/plan`.
  - **Opción B:** mantener prefijo en todas las filas admin y documentar explícitamente la base (`/api/admin`) en el encabezado/nota del ledger.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

| Liquidaciones al organizador: monto consignado y estado por evento/función, y el desglose financiero (bruto, cargo de plataforma, facial, comisión de pasarela, 4x1000, neto) | `GET /settlements`, `GET /reports/financials` | B2B | cli ✓ (`ft settlements list`, `ft reports financials`), mcp ✓ | [freeticket-cli#32](https://github.com/AppFreeticket/freeticket-cli/issues/32) | shipped |
| **PDF de comprobante de liquidación** — el contrato expone `hasDocument` y los `fileName` de los comprobantes, pero no una URL de descarga; el archivo sigue siendo solo del panel. Bloquea archivar el comprobante junto al resto de la documentación financiera | `GET /settlements/{id}/document` (o URL firmada de corta vida en el `Settlement`) | B2B | cli, mcp | [#381](https://github.com/AppFreeticket/free-admin/issues/381) · origen [cli#32](https://github.com/AppFreeticket/freeticket-cli/issues/32) | requested |
| **Listado de staff cross-workspace** — `GET /staff` está scopeado a un workspace por `X-Workspace-Id`, así que un dashboard con N workspaces hace 1×`/me` + N×`/staff`. El fan-out del mcp (`workspace: "all"`) tapa el síntoma del lado cliente, pero sigue siendo N round trips; en cold start serverless es el tramo más caro | `GET /staff?workspaceIds=a,b,c` devolviendo staff agrupado por workspace | B2B | cli, mcp | [#382](https://github.com/AppFreeticket/free-admin/issues/382) · origen [cli#31](https://github.com/AppFreeticket/freeticket-cli/issues/31) | requested |
| **Onboarding enterprise white-label por API** — el admin API no expone `webTemplate` / `customDomain` en `PATCH /workspaces/{id}` ni la asignación manual de plan, así que `ft admin enterprise` no se puede construir sin inventar contrato | `PATCH /api/admin/workspaces/{id}` con `webTemplate`, `customDomain`, `customDomainVerifiedAt` + `POST /api/admin/workspaces/{id}/plan` | Admin | cli | [#383](https://github.com/AppFreeticket/free-admin/issues/383) · origen [cli#23](https://github.com/AppFreeticket/freeticket-cli/issues/23) | requested |

<!-- endpoint-requester: agregá filas nuevas arriba de esta línea, ordenadas por prioridad. -->
2 changes: 1 addition & 1 deletion cli
Open in desktop
Submodule cli updated from c0200d to 529111
2 changes: 1 addition & 1 deletion mcp
Open in desktop
Submodule mcp updated 26 files
+24 −0 CHANGELOG.md
+38 −9 README.md
+1,274 −262 admin-openapi.json
+1 −1 api/server.ts
+2,039 −228 openapi.json
+62 −62 package.json
+1,082 −1,137 public-openapi.json
+85 −0 src/admin-client/sdk.gen.ts
+145 −0 src/admin-client/types.gen.ts
+17 −1 src/api.ts
+3 −0 src/brand.ts
+258 −21 src/client/sdk.gen.ts
+619 −34 src/client/types.gen.ts
+16 −6 src/public-client/client.gen.ts
+3 −2 src/public-client/index.ts
+116 −54 src/public-client/sdk.gen.ts
+279 −273 src/public-client/types.gen.ts
+7 −2 src/server.ts
+15 −0 src/tools/admin.ts
+122 −3 src/tools/b2b-writes.ts
+23 −8 src/tools/b2b.test.ts
+175 −37 src/tools/b2b.ts
+75 −0 src/ui.test.ts
+277 −0 src/ui.ts
+98 −0 src/workspaces.test.ts
+183 −0 src/workspaces.ts
2 changes: 1 addition & 1 deletion skills
Open in desktop
Submodule skills updated 2 files
+33 −6 skills/freeticket-cli/SKILL.md
+33 −1 skills/freeticket-cli/references/commands.md