@wearedev-mgrr/sdk-visual

v1.0.9

Published

a month ago

Visual SDK (Web Components Lit 3) for MGRR — tenant-embeddable UI

0High
0Medium
0Low

weare-edisson

mgrr weare sdk web-components lit reports

`@wearedev-mgrr/sdk-visual`

Status: alpha (v0.0.x). Public API may change between minor releases until v0.1.0. Do not rely on this package in production.

npm install @wearedev-mgrr/sdk-visual @wearedev-mgrr/sdk lit @lit/context

Qué es

Web Components (Lit 3 + Shadow DOM + container queries) que renderizan las vistas de MGRR — catálogo de reportes, ejecución, admin — dentro de cualquier portal cliente. Cada componente es autónomo: estilos aislados, zero conflictos con CSS del host.

Instalación

npm install @wearedev-mgrr/sdk-visual @wearedev-mgrr/sdk lit @lit/context

Peer dependency: @wearedev-mgrr/sdk (cliente HTTP) tiene que instalarse explícitamente; no se distribuye con el visual para permitir que el host escoja versión.

Quickstart (3 pasos)

1. Exponer un endpoint `/api/mgrr-token` en tu backend

Nunca pongas la API key de MGRR en el navegador. El SDK visual llama a un endpoint server-side de tu aplicación, que a su vez intercambia la API key por un JWT de corta vida contra MGRR.

Ejemplo mínimo (Express/Node):

// server/routes/mgrr-token.ts
import type { Request, Response } from 'express';

export async function mgrrTokenHandler(_req: Request, res: Response) {
  const response = await fetch(`${process.env.MGRR_API_BASE_URL}/auth/token/from-apikey`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.MGRR_API_KEY!, // server-side only
    },
  });

  if (!response.ok) {
    return res.status(response.status).json({ error: 'auth_failed' });
  }

  // Same shape the SDK expects: { access_token, expires_in, token_type, tenant_id, role }
  res.json(await response.json());
}

Warning de seguridad:

MGRR_API_KEY vive solo en el server (env var, secret manager). Nunca en VITE_*, NEXT_PUBLIC_*, bundle del cliente, ni HTML.
tokenEndpoint es siempre un path relativo a tu dominio (/api/mgrr-token), no a MGRR.
Puedes añadir autorización propia en este handler (sesión, RBAC, scoping por userId) antes de intercambiar la key.

2. Importar el SDK en tu app

Importar el bundle registra <mgrr-shell> como custom element:

// src/main.ts
import '@wearedev-mgrr/sdk-visual';

3. Renderizar `<mgrr-shell>`

Ejemplo vanilla copy-pasteable (funciona tal cual en un index.html servido por Vite):

<!DOCTYPE html>
<html lang="es-CO">
  <head>
    <meta charset="UTF-8" />
    <title>Mi Portal</title>
    <script type="module">
      import '@wearedev-mgrr/sdk-visual';
    </script>
  </head>
  <body>
    <mgrr-shell
      token-endpoint="/api/mgrr-token"
      api-base-url="https://mgrr.api.weare.co"
      app="reports-user"
      theme="auto"
      locale="es-CO"
    >
      <nav slot="navbar">Mi Portal — Reportes</nav>
      <ul slot="sidebar">
        <li>Reportes</li>
      </ul>
    </mgrr-shell>
  </body>
</html>

Atributos del <mgrr-shell>:

| Atributo | Requerido | Valores | Default | |---|---|---|---| | token-endpoint | sí | path o URL al proxy server-side | — | | api-base-url | sí (prod) | URL base del MGRR API | http://localhost:8080 | | app | sí | reports-user | reports-admin | tenant-admin | — | | theme | no | light | dark | auto | auto | | locale | no | es-CO | es-CO | | sidebar-open | no | boolean attribute | false |

Apps disponibles

| App | Estado | Descripción | |---|---|---| | reports-user | roadmap (E4) | Catálogo y ejecución de reportes para usuarios finales | | reports-admin | roadmap (E5) | Wizard de configuración de reportes para administradores | | tenant-admin | roadmap | Gestión de usuarios, API keys y secretos por tenant |

En v0.0.x solo el shell (<mgrr-shell>) y el core (auth, api-bridge, i18n, router, design tokens) están implementados. Los bundles de apps cargan en E4/E5.

Theming

Todos los estilos del SDK se exponen como CSS custom properties con prefijo --mgrr-*. Ver docs/TOKENS.md para la referencia completa.

Override mínimo para ajustar color de marca:

mgrr-shell {
  --mgrr-color-primary: #0ea5e9;
  --mgrr-font-family-brand: "Inter", sans-serif;
}

Modo oscuro forzado:

<mgrr-shell data-mgrr-theme="dark" ...></mgrr-shell>

Auth flow

┌──────────┐   1. GET page        ┌──────────────────┐
│ Browser  │─────────────────────▶│ Tenant frontend  │
│ (host)   │                      │ (your portal)    │
└────┬─────┘                      └─────────┬────────┘
     │                                      │
     │ 2. <mgrr-shell> mounts               │
     │    AuthProvider.login()              │
     │                                      │
     │ 3. POST /api/mgrr-token              │
     │    (credentials: include)            │
     ├─────────────────────────────────────▶│
     │                                      │
     │                                      │ 4. POST /auth/token/from-apikey
     │                                      │    (X-API-Key: server secret)
     │                                      ├─────────────────────────┐
     │                                      │                         │
     │                                      │    ┌────────────────────▼──┐
     │                                      │    │ MGRR API (your server │
     │                                      │    │ or mgrr.api.weare.co) │
     │                                      │    └────────────────────┬──┘
     │                                      │                         │
     │                                      │ 5. { access_token, exp } │
     │                                      │◀────────────────────────┘
     │ 6. { access_token, exp }             │
     │◀─────────────────────────────────────┤
     │                                      │
     │ 7. ApiBridge installs Bearer,        │
     │    shell renders app                 │
     │                                      │
     │ 8. Auto-refresh 30s before expiry,   │
     │    or reactive on 401                │

Invariantes:

La API key de MGRR nunca sale del server del tenant.
El JWT vive solo en memoria del tab (no localStorage, no cookies). Se pierde al cerrar el tab.
Refresh proactivo 30s antes de expirar; reactivo ante 401.
Concurrent refresh requests se deduplican (single in-flight promise).

Navegadores soportados

(DEC-001) El SDK depende de Shadow DOM v1, container queries y @lit/context. Versiones mínimas:

| Navegador | Versión mínima | |---|---| | Chrome / Edge / Chromium | 114+ | | Firefox | 125+ | | Safari | 17+ |

No se soporta IE ni navegadores sin container queries. No hay polyfills oficiales — usar un host moderno.

Browser vs Node

@wearedev-mgrr/sdk-visual es solo navegador. Depende de HTMLElement, customElements, document y fetch en contexto window.

Para SSR (Next.js, Remix): el custom element renderiza un elemento vacío en el server; la hidratación ocurre en el cliente. Si necesitas contenido pre-renderizado, usa <mgrr-shell> dentro de un boundary 'use client' / client:only.
Para scripts Node, CLIs, workers o edge runtimes: usa @wearedev-mgrr/sdk directamente — no importes @wearedev-mgrr/sdk-visual.

Eventos del shell

Todos los eventos son CustomEvent con bubbles: true, composed: true — escuchables desde document:

| Evento | Detail | Cuándo dispara | |---|---|---| | mgrr-config-changed | { previous, current, changed: string[] } | Cambio en apiBaseUrl, tokenEndpoint, theme, locale | | auth:refreshed | AuthSession | Login exitoso o refresh completado | | auth:failed | Error | Intercambio rechazado (401/403) o fallo de red tras retries | | auth:logout | void | Logout explícito | | mgrr-toast | { level, message, ... } | Notificación UI (surface en apps E4+) |

document.addEventListener('auth:failed', (ev) => {
  const err = (ev as CustomEvent<Error>).detail;
  console.error('MGRR auth failed:', err.message);
  // redirigir a login propio del tenant, etc.
});

Roadmap v0.1

[x] E3 — Scaffolding: monorepo, build Vite, tokens, shell, core (auth, api-bridge, i18n, router), storybook, docs
[ ] E4 — App reports-user: catálogo, formulario de parámetros, ejecución, historial
[ ] E5 — App reports-admin: wizard 5 pasos (meta, source, fields, validations, post-process)
[ ] E6 — App tenant-admin: usuarios, API keys, secretos

Release

Publishing to npm is triggered automatically when a tag matching sdk-visual-v* is pushed.

# Example: publish 0.1.0-beta.0
git tag sdk-visual-v0.1.0-beta.0
git push origin sdk-visual-v0.1.0-beta.0

Prerequisites (one-time, manual): Add the NPM_TOKEN secret in GitHub repository Settings → Secrets and variables → Actions with an npm automation token that has publish access to @wearedev-mgrr/sdk-visual.