@closerclick/closer-click-notifications 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,10 @@ app reimplementaba por separado (messenger, eco, chess, pronóstico, gymbro):
    temable por CSS vars (`--ccn-*`). **Sin JS de terceros ni cookies.**
 3. **`createVaultPushProvider(...)`** — Web Push (app cerrada) ligado al transporte
    del ecosistema (`closer-click-proxy-client`) y firmado por el vault de identidad.
+4. **`createShareReceipts(...)`** — **acuses de apertura** de contenido compartido:
+   el autor recibe una notificación (con el mismo enlace) cuando un tercero abre lo
+   que compartió. Mismo transporte (proxy) e identidad (vault); contenido por la
+   cola cifrada, no por el push.
 
 El ecosistema es mixto Vue/vanilla → la UI va como **custom element** (mismo patrón
 que `closer-click-support` / `closer-click-profile` / `closer-click-nav`).
@@ -115,6 +119,54 @@ El "timbre" **no transporta contenido**: el Service Worker despierta y la app
 reconecta e `identify()` drena la cola cifrada del proxy. La subscription se liga
 a la **misma pubkey del vault** usada en `identify`, con un sobre firmado por el vault.
 
+## Acuses de apertura (`createShareReceipts`)
+
+Avisa al **autor** cuando un tercero **abre** un contenido que compartió, con el
+**mismo enlace** de vuelta (para re-ver el contenido desde la notificación). Solo
+funciona si el enlace permite recuperar la **pubkey del autor** (p. ej. el blob
+firmado del pronosticador): así el que abre puede enrutar el acuse por
+`sendByPubkey` (cola offline 24h del proxy).
+
+```js
+import { createNotifications, createShareReceipts } from '@closerclick/closer-click-notifications'
+import { getWebSocketProxyClient } from '@closerclick/closer-click-proxy-client'
+import { Identity } from '@closerclick/closer-click-identity'
+
+const notifications = createNotifications({
+  storageKey: 'mundial',
+  categories: [
+    { key: 'shareOpened', label: { es: 'Aperturas de lo que compartí', en: 'Opens of what I shared' } },
+  ],
+})
+
+const receipts = createShareReceipts({
+  proxyClient: () => getWebSocketProxyClient(),
+  identity: () => Identity.connect(),
+  notifications,                  // dispara notify('shareOpened', …) con data.url
+  // render(env) → { title, body, ... } | null  (opcional: personaliza el contenido)
+})
+
+// Lado AUTOR (escuchar acuses entrantes mientras la app está abierta):
+receipts.start()
+
+// Lado del que ABRE (al importar contenido AJENO firmado):
+await receipts.report({ toPubkey: parsed.publickey, url: sharedUrl, name: parsed.name })
+```
+
+- **Identidad del que abre**: el sobre incluye **siempre** `from { pubkey, nick }`.
+- **Anti-spam**: `report` aplica throttle por `(toPubkey|url)` (default 24h).
+- **Propio**: `report` es no-op si el contenido es tuyo (`toPubkey === tu pubkey`).
+- **Contenido por defecto** (mismo en toda app, es/en): *"Abrieron tu contenido"* +
+  *«name» · nick*. Pásalo a medida con `render(env)`.
+- **Offline**: el contenido viaja por la **cola del proxy** (no por el push). El
+  push solo "timbra"; al reabrir la app, `identify()` drena la cola y aparece la
+  notificación con el enlace. El click usa `data.url` — tu SW
+  (`closer-click-push-sw.js`) ya navega a `event.notification.data.url`.
+
+> Apps de **partida en vivo** (chess/cuarenta comparten `#table=<token>` sin pubkey
+> del autor) no usan este acuse: el anfitrión ya ve el "join" por el canal. Pueden
+> enrutar ese evento por el mismo `createNotifications` para una UX uniforme.
+
 ## Tema (CSS custom properties)
 
 ```css

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@closerclick/closer-click-notifications",
-  "version": "0.1.0",
-  "description": "Notificaciones compartidas del ecosistema Closer Click: controlador data-agnostic (permiso del navegador + preferencias por categoría con scope por app + disparo) y el Web Component <closer-click-notifications> (panel de ajustes). Incluye helper de Web Push ligado al vault + proxy. Autohosteado, Shadow DOM, sin JS de terceros ni cookies.",
+  "version": "0.2.0",
+  "description": "Notificaciones compartidas del ecosistema Closer Click: controlador data-agnostic (permiso del navegador + preferencias por categoría con scope por app + disparo), el Web Component <closer-click-notifications> (panel de ajustes), helper de Web Push ligado al vault + proxy y acuses de apertura de contenido compartido (createShareReceipts). Autohosteado, Shadow DOM, sin JS de terceros ni cookies.",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/index.d.ts

@@ -76,8 +76,69 @@ export interface VaultPushProviderConfig {
   storageKey?: string
 }
 
+/** Provider de Web Push concreto (todos los miembros son funciones llamables). */
+export interface VaultPushProvider {
+  supported(): boolean
+  isEnabled(): boolean
+  busy(): boolean
+  error(): string
+  enable(): Promise<boolean>
+  disable(): Promise<boolean>
+  ensureSubscribed(): Promise<void>
+}
+
 /** Provider de Web Push ligado al vault + proxy del ecosistema. */
-export function createVaultPushProvider(cfg: VaultPushProviderConfig): Required<Pick<PushProvider, 'supported' | 'isEnabled' | 'busy' | 'error' | 'enable' | 'disable' | 'ensureSubscribed'>>
+export function createVaultPushProvider(cfg: VaultPushProviderConfig): VaultPushProvider
+
+/** Sobre estándar de un acuse de apertura (lo que viaja por el proxy). */
+export interface ShareReceiptEnvelope {
+  /** marca + versión del sobre (= 1). */
+  __ccn: number
+  /** tipo de acuse ('opened' por defecto, extensible). */
+  kind: string
+  /** enlace compartido (vuelve al autor para re-ver el contenido). */
+  url: string
+  /** nombre/título del contenido, si la app lo pasó. */
+  name?: string | null
+  /** identidad del que abrió (siempre identificado por decisión del ecosistema). */
+  from: { pubkey: string | null; nick: string | null }
+  /** instante del acuse (ms epoch). */
+  ts: number
+}
+
+export interface ShareReceiptsConfig {
+  /** Cliente proxy del ecosistema (o getter): on('message',…) + sendByPubkey. */
+  proxyClient: any | (() => any)
+  /** Instancia Identity del vault (o getter, puede ser async). */
+  identity: any | (() => any | Promise<any>)
+  /** Controlador de createNotifications(...) (para notify/prefs). */
+  notifications: NotificationsController
+  /** Categoría de prefs a respetar/disparar (default 'shareOpened'). */
+  category?: string
+  /** Override del contenido: recibe el sobre, devuelve NotifyOptions o null. */
+  render?: (env: ShareReceiptEnvelope) => (NotifyOptions | null)
+  /** Idioma del render por defecto ('es'|'en'|'auto', default 'auto'). */
+  lang?: string
+  /** Ventana anti-spam por contenido en ms (default 24h). */
+  throttleMs?: number
+  /** Override del click (default: navegar a url). */
+  onOpen?: (url: string, env: ShareReceiptEnvelope) => void
+}
+
+export interface ShareReceipts {
+  /** Lado del que ABRE: avisa al autor que abriste su contenido. */
+  report(opts: { toPubkey: string; url: string; kind?: string; name?: string }): Promise<boolean>
+  /** Lado AUTOR: empieza a escuchar acuses entrantes (idempotente). */
+  start(): void
+  /** Deja de escuchar. */
+  stop(): void
+  readonly category: string
+  readonly RECEIPT_TAG: string
+  readonly RECEIPT_VERSION: number
+}
+
+/** Motor común de acuses de apertura de contenido compartido. */
+export function createShareReceipts(cfg: ShareReceiptsConfig): ShareReceipts
 
 export class CloserClickNotifications extends HTMLElement {
   controller: NotificationsController | null

package/src/index.js

@@ -244,7 +244,191 @@ export function createVaultPushProvider ({ proxyClient, identity, storageKey = '
 }
 
 /* ============================================================================
- * 3) Web Component  ──  <closer-click-notifications>  (panel de ajustes)
+ * 3) Acuses de apertura  ──  createShareReceipts(...)
+ *
+ * Mecanismo COMÚN para que el autor de un contenido compartido reciba un aviso
+ * cuando un tercero abre el enlace, con el MISMO enlace de vuelta (para re-ver
+ * el contenido desde la notificación). Reutilizable por cualquier app del
+ * ecosistema.
+ *
+ *   - Lado del que ABRE:   report({ toPubkey, url, kind, name })  → manda un
+ *       sobre firmable por la cola offline del proxy (sendByPubkey, 24h). No
+ *       avisa si el contenido es propio (toPubkey === mi pubkey) y aplica
+ *       throttle por (toPubkey|url) para no spamear al reabrir.
+ *   - Lado AUTOR:          start()  → escucha mensajes del proxy, filtra los
+ *       sobres de acuse (__ccn) y dispara una notificación local con el enlace
+ *       (data.url). El CONTENIDO por defecto es el mismo en toda app; la app
+ *       puede inyectar render(env) para personalizarlo.
+ *
+ * El transporte y la identidad NO se reimplementan: se inyectan los mismos
+ * `proxyClient` (closer-click-proxy-client) e `identity` (vault) que usa el
+ * resto del ecosistema. El contenido viaja por la cola CIFRADA del proxy, no
+ * por el push (el push solo "timbra" sin contenido — política del ecosistema).
+ * ==========================================================================*/
+
+const RECEIPT_TAG = '__ccn'        // marca del sobre (envelope) de acuse
+const RECEIPT_VERSION = 1
+const LS_THROTTLE = 'cc-receipt:'  // namespace del anti-spam por contenido
+
+const RECEIPT_I18N = {
+  es: {
+    openedTitle: 'Abrieron tu contenido',
+    openedBodyNamed: (name, nick) => nick ? `Abrieron «${name}» · ${nick}` : `Abrieron «${name}»`,
+    openedBodyAnon: (nick) => nick ? `${nick} abrió lo que compartiste` : 'Alguien abrió lo que compartiste',
+  },
+  en: {
+    openedTitle: 'Your content was opened',
+    openedBodyNamed: (name, nick) => nick ? `“${name}” opened · ${nick}` : `“${name}” opened`,
+    openedBodyAnon: (nick) => nick ? `${nick} opened what you shared` : 'Someone opened what you shared',
+  },
+}
+
+function _receiptLang (lang) {
+  const a = (lang || 'auto').toLowerCase()
+  if (a === 'es' || a === 'en') return a
+  const nav = (isBrowser && navigator.language || 'es').slice(0, 2)
+  return nav === 'en' ? 'en' : 'es'
+}
+
+/**
+ * Crea el motor de acuses de apertura (data-agnostic, sin framework).
+ *
+ * @param {object} cfg
+ * @param {object|function} cfg.proxyClient  cliente proxy del ecosistema (o getter).
+ *        Debe exponer `on('message', (from, payload) => …)` y `sendByPubkey(pk, payload)`.
+ * @param {object|function} cfg.identity     instancia Identity del vault (o getter async).
+ * @param {object} cfg.notifications         controlador de createNotifications(...) (para notify/prefs).
+ * @param {string} [cfg.category='shareOpened']  categoría de prefs a respetar/disparar.
+ * @param {(env:object)=>(object|null)} [cfg.render]  override del contenido: recibe el sobre
+ *        y devuelve { title, body, ...NotifyOptions } o null para ignorar. Si no se pasa,
+ *        usa el render por defecto (mismo contenido en toda app), bilingüe es/en.
+ * @param {string} [cfg.lang='auto']         idioma del render por defecto.
+ * @param {number} [cfg.throttleMs=86400000] ventana anti-spam por contenido (default 24h).
+ * @param {(url:string,env:object)=>void} [cfg.onOpen]  override del click (default: navegar a url).
+ */
+export function createShareReceipts (cfg = {}) {
+  const getProxy = typeof cfg.proxyClient === 'function' ? cfg.proxyClient : () => cfg.proxyClient
+  const getId = typeof cfg.identity === 'function' ? cfg.identity : () => cfg.identity
+  const notifications = cfg.notifications || null
+  const category = cfg.category || 'shareOpened'
+  const render = typeof cfg.render === 'function' ? cfg.render : null
+  const lang = cfg.lang || 'auto'
+  const throttleMs = cfg.throttleMs != null ? cfg.throttleMs : 24 * 60 * 60 * 1000
+  const onOpen = typeof cfg.onOpen === 'function'
+    ? cfg.onOpen
+    : (url) => { try { if (isBrowser && url) location.assign(url) } catch (_) {} }
+
+  let _off = null
+  const _seen = new Set()   // dedup de acuses entrantes (from|url|ts)
+
+  async function _myPubkey () {
+    try {
+      const id = await getId()
+      return (id && id.me && id.me.publickey) || null
+    } catch (_) { return null }
+  }
+
+  // ---- anti-spam: 1 acuse por (toPubkey|url) por ventana (localStorage) ----
+  function _throttled (toPubkey, url) {
+    if (!isBrowser || throttleMs <= 0) return false
+    try {
+      const k = LS_THROTTLE + _hash(toPubkey + '|' + url)
+      const last = Number(localStorage.getItem(k) || 0)
+      const now = Date.now()
+      if (now - last < throttleMs) return true
+      localStorage.setItem(k, String(now))
+      return false
+    } catch (_) { return false }
+  }
+
+  // Hash corto y estable (djb2) para no guardar la URL completa en la clave.
+  function _hash (s) {
+    let h = 5381
+    for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0
+    return (h >>> 0).toString(36)
+  }
+
+  /**
+   * Lado del que ABRE: avisa al autor (toPubkey) que abriste su contenido.
+   * No-op si es contenido propio o si el throttle lo bloquea. Devuelve true si
+   * se encoló el acuse.
+   * @returns {Promise<boolean>}
+   */
+  async function report ({ toPubkey, url, kind = 'opened', name } = {}) {
+    if (!toPubkey || !url) return false
+    const mine = await _myPubkey()
+    if (mine && mine === toPubkey) return false           // no avisarme a mí mismo
+    if (_throttled(toPubkey, url)) return false
+    // Decisión del ecosistema: identificar SIEMPRE al que abre.
+    let from = { pubkey: mine || null, nick: null }
+    try {
+      const id = await getId()
+      from = { pubkey: (id && id.me && id.me.publickey) || mine || null, nick: (id && id.me && id.me.nickname) || null }
+    } catch (_) {}
+    const env = { [RECEIPT_TAG]: RECEIPT_VERSION, kind, url, name: name || null, from, ts: Date.now() }
+    try {
+      const proxy = getProxy()
+      if (typeof proxy.ensureConnected === 'function') { try { await proxy.ensureConnected() } catch (_) {} }
+      proxy.sendByPubkey(toPubkey, env)
+      return true
+    } catch (e) {
+      console.warn('[cc-notif] report (acuse) falló:', (e && e.message) || e)
+      return false
+    }
+  }
+
+  // Construye {title, body, ...} por defecto a partir del sobre (mismo contenido
+  // en toda app). La app puede sobreescribirlo con cfg.render.
+  function _defaultRender (env) {
+    const t = RECEIPT_I18N[_receiptLang(lang)]
+    const nick = env.from && env.from.nick
+    const title = t.openedTitle
+    const body = env.name ? t.openedBodyNamed(env.name, nick) : t.openedBodyAnon(nick)
+    return { title, body }
+  }
+
+  function _handle (env) {
+    if (!env || env[RECEIPT_TAG] !== RECEIPT_VERSION || !env.url) return
+    const key = `${(env.from && env.from.pubkey) || ''}|${env.url}|${env.ts || ''}`
+    if (_seen.has(key)) return
+    _seen.add(key)
+    const rendered = render ? render(env) : _defaultRender(env)
+    if (!rendered) return
+    const { title, body, ...rest } = rendered
+    if (!notifications || typeof notifications.notify !== 'function') return
+    notifications.notify(category, {
+      title: title || '',
+      body: body || '',
+      tag: rest.tag || ('cc-receipt:' + _hash(env.url)),
+      data: { url: env.url, ...(rest.data || {}) },
+      onClick: () => onOpen(env.url, env),
+      ...rest,
+    })
+  }
+
+  /** Lado AUTOR: empieza a escuchar acuses entrantes (idempotente). */
+  function start () {
+    if (_off) return
+    const proxy = getProxy()
+    if (!proxy || typeof proxy.on !== 'function') return
+    _off = proxy.on('message', (_from, payload) => {
+      const env = (typeof payload === 'object' && payload) ? payload : _tryParse(payload)
+      _handle(env)
+    })
+  }
+
+  function _tryParse (s) {
+    if (typeof s !== 'string') return null
+    try { return JSON.parse(s) } catch (_) { return null }
+  }
+
+  function stop () { if (_off) { try { _off() } catch (_) {} _off = null } }
+
+  return { report, start, stop, category, RECEIPT_TAG, RECEIPT_VERSION }
+}
+
+/* ============================================================================
+ * 4) Web Component  ──  <closer-click-notifications>  (panel de ajustes)
  * ==========================================================================*/
 
 const I18N = {