@indesad/feedback-widget 0.0.0-stage → 1.1.1

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @indesad/feedback-widget
+
+Botón de **opiniones de producto** para cualquier aplicación web: la persona reporta un problema, sugiere una mejora, hace una pregunta o felicita, y la opinión llega a la bandeja **Opiniones** de IndeFlow con folio, seguimiento y respuesta por correo en su idioma.
+
+- Sin dependencias. Vive en un Shadow DOM: no hereda ni rompe los estilos de la app.
+- Claro y oscuro: en los productos Indesad toma los tokens `--if-*` de la app (y su modo oscuro `html.dark`); en otras apps usa su paleta y sigue `data-theme`, la clase `dark` o `prefers-color-scheme`.
+- Español, inglés y portugués (`locale: 'auto'` usa el del navegador).
+- Si IndeFlow no responde, el botón no aparece y la app sigue igual.
+- Una opinión **no es un caso de soporte**: si la app tiene soporte, `supportUrl` agrega el enlace «Necesito ayuda».
+
+## 1. Activar opiniones en IndeFlow
+
+Proyecto → Observabilidad → fuente de la app → pestaña **Opiniones**: activar, agregar los orígenes desde los que se usará (por ejemplo `https://app.cliente.cl`) y copiar el código. La clave es el mismo token de la fuente (`if_obs_...`); al activar opiniones recibe el permiso `ingest:feedback`. Es pública por naturaleza (va en el navegador): solo sirve para enviar opiniones desde los orígenes permitidos.
+
+## 2a. Script listo para pegar (cualquier web)
+
+```html
+<script src="https://admin.indeflow.app/downloads/sdk/indeflow-feedback-1.1.1.js"
+        data-api="https://api.indeflow.app/api"
+        data-token="if_obs_prod_..."
+        data-locale="auto"></script>
+```
+
+Con la persona que ya inició sesión en tu app (recomendado):
+
+```html
+<script src="https://admin.indeflow.app/downloads/sdk/indeflow-feedback-1.1.1.js"></script>
+<script>
+  const feedback = IndeFlowFeedback.init({
+    apiUrl: 'https://api.indeflow.app/api',
+    sourceToken: 'if_obs_prod_...',
+    user: { name: 'Ana Pérez', email: 'ana@cliente.cl', company: 'Cliente S.A.', externalUserId: '42' },
+    locale: 'auto', theme: 'auto', supportUrl: '/soporte'
+  });
+  // Al cerrar sesión: feedback.setUser(null)
+</script>
+```
+
+## 2b. Angular (o React, Vue…)
+
+```bash
+npm install @indesad/feedback-widget@1.1.1
+```
+
+```ts
+import { createIndeFlowFeedback, IndeFlowFeedbackController } from '@indesad/feedback-widget';
+
+@Injectable({ providedIn: 'root' })
+export class FeedbackWidgetService {
+  private widget?: IndeFlowFeedbackController;
+  start(user: { name: string; email: string; company?: string; id: string }) {
+    this.widget ??= createIndeFlowFeedback({
+      apiUrl: environment.indeflowApi, sourceToken: environment.indeflowFeedbackToken,
+      user: { name: user.name, email: user.email, company: user.company, externalUserId: user.id },
+      locale: 'auto', theme: 'auto', brandLabel: 'InDeLedger'
+    });
+  }
+  stop() { this.widget?.destroy(); this.widget = undefined; }
+}
+```
+
+## Configuración
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `apiUrl`, `sourceToken` | — | Obligatorias. |
+| `user` | — | `{ name, email, company, externalUserId }` de la sesión. Sin `user`, el formulario pide nombre y correo (si la fuente admite anónimos). La identidad la declara la app; IndeFlow no la verifica. |
+| `locale` | `'auto'` | `es-419`, `en`, `pt-BR` o `auto`. También define el idioma de los correos al reportante. |
+| `theme`, `themeSelector` | `'auto'` | `light`, `dark` o `auto`. `themeSelector` (por ejemplo `'[data-mode="night"]'`) indica cuándo la app está en oscuro. |
+| `colors` | tokens `--if-*` | `accent`, `accentContrast`, `background`, `surface`, `text`, `muted`, `border`, `danger`, `success`, `radius`, `font`. |
+| `brandLabel`, `title` | los de la fuente | Nombre de la app arriba del panel y título. |
+| `position`, `offset` | `bottom-right`, 20 px | Lugar del botón; `offset` para no tapar otros botones flotantes. |
+| `launcher` | `'bubble'` | `'none'` oculta el botón: abre el panel con `open()` desde tu menú. |
+| `launcherLabel`, `launcherIcon`, `launcherIconType` | «Opiniones» | Texto e icono (`emoji`, `image`, `svg`). |
+| `kinds` | los de la fuente | Subconjunto de `bug`, `improvement`, `question`, `praise`. |
+| `supportUrl`, `supportLabel` | — | Enlace «Necesito ayuda» hacia tu soporte. |
+| `screenshot` | `true` | Permite adjuntar hasta 5 imágenes PNG, JPG o WebP de hasta 5 MB cada una (también pegadas con Ctrl+V). |
+| `context`, `appVersion`, `collectRoute` | — / — / `true` | Datos fijos del envío (máx. 20 claves, sin secretos), versión y ruta actual (sin parámetros). |
+| `zIndex`, `showPoweredBy` | `2147483000`, `true` | Capa y pie «Con tecnología de IndeFlow». |
+| `onSubmitted`, `onError` | — | Callbacks con `{ folio, trackingUrl }` o `{ code, message }`. |
+
+Controlador: `open(kind?)`, `close()`, `toggle()`, `setUser(user)`, `setContext(ctx)`, `update(config)`, `destroy()` y `ready` (promesa: `false` si quedó desactivado).
+
+## Qué se envía
+
+Tipo, mensaje, idioma, la identidad declarada, la URL **sin parámetros ni fragmento**, la ruta, versión, navegador, tamaño de pantalla, tema y el `context` que pongas. El servidor descarta claves de `context` que parezcan secretos (`token`, `password`, `apiKey`…), guarda la IP solo como huella y exige un desafío anti-robots por envío. Nunca se leen cookies, almacenamiento ni el contenido de la página.
+
+## Desarrollo
+
+```bash
+cd packages/web/feedback-widget && npm test          # jsdom + fetch simulado
+node scripts/build-feedback-widget.mjs               # genera las descargas en frontend/IndeFlow.Admin/public/downloads/sdk
+```

package/dist/i18n.d.ts

@@ -0,0 +1,44 @@
+import type { FeedbackKind, FeedbackLocale } from './types';
+type Copy = {
+    launcher: string;
+    title: string;
+    subtitle: string;
+    close: string;
+    back: string;
+    kinds: Record<FeedbackKind, {
+        label: string;
+        hint: string;
+        placeholder: string;
+    }>;
+    needHelp: string;
+    message: string;
+    name: string;
+    email: string;
+    emailOptional: string;
+    sendingAs: string;
+    attach: string;
+    attachMore: string;
+    attachHint: string;
+    remove: string;
+    send: string;
+    sending: string;
+    privacy: string;
+    successTitle: string;
+    successBody: string;
+    successEmail: string;
+    viewStatus: string;
+    another: string;
+    errorGeneric: string;
+    errorMessage: string;
+    errorName: string;
+    errorEmail: string;
+    errorAttachmentType: string;
+    errorAttachmentSize: string;
+    errorAttachmentCount: string;
+    poweredBy: string;
+    counter: string;
+};
+export declare const COPY: Record<FeedbackLocale, Copy>;
+export declare function resolveLocale(requested?: string | null, fallback?: string | null): FeedbackLocale;
+export declare function format(text: string, values: Record<string, string | number>): string;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createIndeFlowFeedback, IndeFlowFeedbackWidget, VERSION } from './widget';
+export { sha256Hex, solveChallenge } from './sha256';
+export { COPY, resolveLocale } from './i18n';
+export type { FeedbackKind, FeedbackLocale, FeedbackTheme, FeedbackUser, IndeFlowFeedbackConfig, IndeFlowFeedbackController, RemoteConfig } from './types';