@inwink-mcp/backoffice-extension-helpers 1.0.0 → 1.0.2

package/templates/vite-extension/src/components/EventPicker.tsx

@@ -0,0 +1,25 @@
+import ContextCombobox from './ContextCombobox';
+import { useContextOptions } from '../hooks/useContextOptions';
+import { useInwinkContext } from '../hooks/useInwinkContext';
+
+/**
+ * Sélecteur d'événement courant. Pré-rempli depuis le contexte (URL) et modifiable.
+ * Composant autonome, montable où l'on veut (header, page…). Non monté par défaut.
+ */
+export default function EventPicker() {
+  const { eventId, setEvent, loadEvents } = useInwinkContext();
+  const { options, isLoading, error, search } = useContextOptions(loadEvents, eventId);
+
+  return (
+    <ContextCombobox
+      label="Événement"
+      placeholder="Choisir un événement"
+      value={eventId}
+      options={options}
+      isLoading={isLoading}
+      error={error}
+      onChange={setEvent}
+      onSearch={search}
+    />
+  );
+}

package/templates/vite-extension/src/components/Header.css

@@ -0,0 +1,25 @@
+.app-header {
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 1.5rem;
+  background: var(--color-bg);
+  border-bottom: 1px solid var(--color-border);
+  box-shadow: var(--shadow-sm);
+}
+
+.app-header__brand {
+  font-family: var(--font-title);
+  font-weight: 600;
+  font-size: 1.1rem;
+}
+
+.app-header__actions {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}

package/templates/vite-extension/src/components/Header.tsx

@@ -0,0 +1,37 @@
+import './Header.css';
+import { FiLogIn, FiLogOut } from 'react-icons/fi';
+import { useAuth } from '../hooks/useAuth';
+
+interface HeaderProps {
+  title: string;
+}
+
+/**
+ * En-tête de l'application : marque à gauche, bouton de connexion/déconnexion à droite.
+ *
+ * Composant volontairement isolé dans son propre fichier pour être facilement
+ * surchargé/personnalisé (ex. y monter un EventPicker / CommunityPicker selon
+ * l'usage de l'extension). Les pickers ne sont PAS montés ici par défaut.
+ */
+export default function Header({ title }: HeaderProps) {
+  const { isAuthenticated, isLoading, login, logout } = useAuth();
+
+  return (
+    <header className="app-header">
+      <div className="app-header__brand">{title}</div>
+      <div className="app-header__actions">
+        {isAuthenticated ? (
+          <button onClick={() => void logout()}>
+            <FiLogOut aria-hidden />
+            Se déconnecter
+          </button>
+        ) : (
+          <button className="btn-primary" disabled={isLoading} onClick={() => void login()}>
+            <FiLogIn aria-hidden />
+            {isLoading ? 'Initialisation…' : 'Se connecter'}
+          </button>
+        )}
+      </div>
+    </header>
+  );
+}

package/templates/vite-extension/src/components/Layout.css

@@ -0,0 +1,13 @@
+.app-layout {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.app-content {
+  flex: 1;
+  width: 100%;
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 2rem 1.5rem;
+}

package/templates/vite-extension/src/components/Layout.tsx

@@ -0,0 +1,19 @@
+import './Layout.css';
+import { Outlet } from 'react-router-dom';
+import Header from './Header';
+
+interface LayoutProps {
+  title: string;
+}
+
+/** Gabarit applicatif : Header + zone de contenu (routes enfants via Outlet). */
+export default function Layout({ title }: LayoutProps) {
+  return (
+    <div className="app-layout">
+      <Header title={title} />
+      <main className="app-content">
+        <Outlet />
+      </main>
+    </div>
+  );
+}

package/templates/vite-extension/src/context/InwinkContextProvider.tsx

@@ -0,0 +1,170 @@
+// Contexte inwink : expose l'objet courant (event / community / tenant) déduit
+// de l'URL ou choisi par l'utilisateur, et les loaders de listes pour les pickers.
+import { createContext, useMemo, useState, type PropsWithChildren } from 'react';
+import { useInwinkCustomerApi } from '../hooks/useInwinkCustomerApi';
+import {
+  deriveScope,
+  loadPersistedContext,
+  persistContext,
+  readInwinkContextFromUrl,
+  type InwinkContextParams,
+  type InwinkScope,
+} from '../lib/inwinkContextParams';
+
+/** Option affichable dans un picker (événement, communauté ou tenant). */
+export interface InwinkContextOption {
+  id: string;
+  label: string;
+}
+
+export interface IInwinkContextQuery {
+  search?: string;
+  id?: string;
+}
+
+interface InwinkContextValue {
+  scope: InwinkScope;
+  eventId?: string;
+  communityId?: string;
+  tenantId?: string;
+  /** Sélectionne un événement (réinitialise la communauté). */
+  setEvent: (id: string) => void;
+  /** Sélectionne une communauté (réinitialise l'événement). */
+  setCommunity: (id: string) => void;
+  /** Sélectionne un tenant / audience (réinitialise event + community). */
+  setTenant: (id: string) => void;
+  /**
+   * Liste les événements de l'utilisateur (API Customer `me/events/query`),
+   * triés par date décroissante. `query` filtre côté serveur par nom ou id.
+   */
+  loadEvents: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>;
+  /**
+   * Liste les communautés de l'utilisateur (API Customer `me/communities/query`).
+   * `query` filtre côté serveur par nom ou id.
+   */
+  loadCommunities: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>;
+  /**
+   * Liste les tenants / audiences de l'utilisateur (API Customer `me/tenants/query`).
+   * `query` filtre côté serveur par nom ou id.
+   */
+  loadTenants: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>;
+}
+
+export const InwinkContext = createContext<InwinkContextValue | null>(null);
+
+// Pagination des requêtes `*/query`. Les listes sont paginées côté serveur :
+// la recherche (`query`) sert à retrouver un objet au-delà de la 1re page.
+const PAGE = { index: 0, size: 200 };
+
+// Construit le corps d'une requête de liste (`me/<entité>/query`) :
+// - `query` → filtre serveur par id (égalité) OU libellé (`$contains`) ;
+// - `labelField` → champ texte de l'entité (`title` pour les events, `name` sinon) ;
+// - `orders` → tri serveur (ex. date décroissante pour les events).
+// Ajuste `selects` / `filters` selon les entités après discovery MCP (cf. AGENTS.md).
+function buildQueryBody(opts: {
+  query?: IInwinkContextQuery;
+  labelField: string;
+  orders?: unknown[];
+}): Record<string, unknown> {
+  const body: Record<string, any> = { page: PAGE };
+  if (opts.orders) body.orders = opts.orders;
+  if (opts.query?.id) {
+    body.filters ??= {};
+    body.filters.id = opts.query.id;    
+  } else if (opts.query?.search) {
+    body.filters ??= {};
+    const q = opts.query?.search?.trim();
+    if (q) {
+      body.filters.$and ??= [];
+      //detect if q is a guid
+      const guidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+      if (guidRegex.test(q)) {
+        body.filters.$and.push({ id: q });
+      } else {
+        body.filters.$and.push({ [opts.labelField]: { $contains: q } });
+      }
+      
+    }
+  }
+  return body;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+}
+
+// Normalise une réponse `*/query` en options { id, label }, quel que soit le wrapping.
+function normalizeOptions(raw: unknown): InwinkContextOption[] {
+  const root = asRecord(raw);
+  const list: unknown[] = Array.isArray(raw)
+    ? raw
+    : Array.isArray(root.data)
+      ? (root.data as unknown[])
+      : Array.isArray(root.items)
+        ? (root.items as unknown[])
+        : [];
+
+  const options: InwinkContextOption[] = [];
+  for (const entry of list) {
+    const item = asRecord(entry);
+    const id = item.id ?? item.eventId ?? item.communityId ?? item.tenantId;
+    if (id == null) continue;
+    const label = item.title ?? item.name ?? item.displayName ?? id;
+    options.push({ id: String(id), label: String(label) });
+  }
+  return options;
+}
+
+/** Init : l'URL fait foi ; sinon on retombe sur le contexte persisté en session. */
+function initialParams(): InwinkContextParams {
+  const fromUrl = readInwinkContextFromUrl();
+  if (fromUrl.eventId || fromUrl.communityId || fromUrl.tenantId) {
+    persistContext(fromUrl);
+    return fromUrl;
+  }
+  return loadPersistedContext();
+}
+
+export function InwinkContextProvider({ children }: PropsWithChildren) {
+  const customerApi = useInwinkCustomerApi();
+  const [params, setParams] = useState<InwinkContextParams>(initialParams);
+
+  const value = useMemo<InwinkContextValue>(() => {
+    const apply = (next: InwinkContextParams) => {
+      setParams(next);
+      persistContext(next);
+    };
+    return {
+      scope: deriveScope(params),
+      eventId: params.eventId,
+      communityId: params.communityId,
+      tenantId: params.tenantId,
+      setEvent: (id) => apply({ ...params, eventId: id, communityId: undefined }),
+      setCommunity: (id) => apply({ ...params, communityId: id, eventId: undefined }),
+      setTenant: (id) => apply({ tenantId: id }),
+      loadEvents: async (query?: IInwinkContextQuery) =>
+        normalizeOptions(
+          await customerApi.post(
+            '/00000000-0000-0000-0000-000000000000/my/events/query',
+            buildQueryBody({ query, labelField: 'title', orders: [{ desc: true, value: { startDate: {} } }] }),
+          ),
+        ),
+      loadCommunities: async (query?: IInwinkContextQuery) =>
+        normalizeOptions(
+          await customerApi.post(
+            '/00000000-0000-0000-0000-000000000000/my/communities/query',
+            buildQueryBody({ query, labelField: 'name' }),
+          ),
+        ),
+      loadTenants: async (query?: IInwinkContextQuery) =>
+        normalizeOptions(
+          await customerApi.post(
+            '/00000000-0000-0000-0000-000000000000/my/tenants/query',
+            buildQueryBody({ query, labelField: 'name' }),
+          ),
+        ),
+    };
+  }, [params, customerApi]);
+
+  return <InwinkContext.Provider value={value}>{children}</InwinkContext.Provider>;
+}

package/templates/vite-extension/src/hooks/useContextOptions.ts

@@ -0,0 +1,106 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { IInwinkContextQuery, InwinkContextOption } from '../context/InwinkContextProvider';
+
+interface ContextOptionsState {
+  options: InwinkContextOption[];
+  isLoading: boolean;
+  error: string | null;
+  /** Relance le loader avec un terme de recherche texte (debouncé). */
+  search: (query: string) => void;
+}
+
+const DEBOUNCE_MS = 250;
+
+/**
+ * Charge une liste d'options de contexte via le loader fourni
+ * (`loadEvents` / `loadCommunities` / `loadTenants` de useInwinkContext).
+ * Mutualise la gestion chargement / erreur des pickers et expose `search()`
+ * pour relancer le loader côté serveur (par nom ou id) en debounçant la saisie.
+ *
+ * `selectedId` (id courant, typiquement issu de l'URL) est fetché par id et
+ * fusionné dans les options : la liste `me/<entité>/query` étant paginée (1ʳᵉ page
+ * seulement), l'objet sélectionné peut ne pas y figurer alors qu'il existe — sans ce
+ * fetch le picker afficherait l'id brut au lieu de son libellé.
+ *
+ * Les réponses obsolètes (saisie rapide, démontage) sont ignorées.
+ */
+export function useContextOptions(
+  load: (query?: IInwinkContextQuery) => Promise<InwinkContextOption[]>,
+  selectedId?: string,
+): ContextOptionsState {
+  const [options, setOptions] = useState<InwinkContextOption[]>([]);
+  const [selectedOption, setSelectedOption] = useState<InwinkContextOption | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // `load` provient du contexte et change d'identité à chaque rendu : on le garde
+  // dans une ref pour ne pas relancer le chargement initial à chaque rendu.
+  const loadRef = useRef(load);
+  loadRef.current = load;
+
+  // Identifiant monotone de requête : seule la dernière en vol met à jour l'état.
+  const reqId = useRef(0);
+  const debounce = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const run = useCallback((query?: IInwinkContextQuery) => {
+    const id = ++reqId.current;
+    setIsLoading(true);
+    setError(null);
+    loadRef.current(query)
+      .then((opts) => {
+        if (id === reqId.current) setOptions(opts);
+      })
+      .catch((err: unknown) => {
+        if (id === reqId.current) setError(err instanceof Error ? err.message : String(err));
+      })
+      .finally(() => {
+        if (id === reqId.current) setIsLoading(false);
+      });
+  }, []);
+
+  // Chargement initial (sans filtre) au montage ; invalide les requêtes en vol au démontage.
+  useEffect(() => {
+    run();
+    return () => {
+      reqId.current++;
+      clearTimeout(debounce.current);
+    };
+  }, [run]);
+
+  // Fetch du détail de l'objet sélectionné par id (cf. doc ci-dessus).
+  useEffect(() => {
+    if (!selectedId) {
+      setSelectedOption(null);
+      return;
+    }
+    let active = true;
+    loadRef.current({ id: selectedId })
+      .then((opts) => {
+        if (active) setSelectedOption(opts.find((o) => o.id === selectedId) ?? opts[0] ?? null);
+      })
+      .catch(() => {
+        // En cas d'échec, on laisse le picker afficher l'id brut : non bloquant.
+      });
+    return () => {
+      active = false;
+    };
+  }, [selectedId]);
+
+  const search = useCallback(
+    (query: string) => {
+      clearTimeout(debounce.current);
+      const q = query.trim();
+      debounce.current = setTimeout(() => run(q ? { search: q } : undefined), DEBOUNCE_MS);
+    },
+    [run],
+  );
+
+  // Garantit que l'option sélectionnée est toujours présente (et en tête) même si
+  // elle est absente de la page courante ou d'un résultat de recherche filtré.
+  const mergedOptions = useMemo(() => {
+    if (!selectedOption || options.some((o) => o.id === selectedOption.id)) return options;
+    return [selectedOption, ...options];
+  }, [options, selectedOption]);
+
+  return { options: mergedOptions, isLoading, error, search };
+}

package/templates/vite-extension/src/hooks/useInwinkApi.ts

@@ -1,3 +1,4 @@
+import { useMemo } from 'react';
 import { useAuth } from './useAuth';
 
 /** Erreur levée lorsqu'une réponse API n'est pas OK (hors 401 géré par renouvellement). */
@@ -38,64 +39,66 @@ async function safeBody(response: Response): Promise<unknown> {
 export function useInwinkApi(baseUrl: string): InwinkApi {
   const { getAccessToken, renewToken, login } = useAuth();
 
-  async function doFetch(path: string, token: string, init?: RequestInit): Promise<Response> {
-    return fetch(`${baseUrl}${path}`, {
-      ...init,
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json',
-        ...(init?.headers as Record<string, string> | undefined),
-      },
-    });
-  }
-
-  async function request<T = unknown>(path: string, init?: RequestInit): Promise<T> {
-    let token = getAccessToken();
-    if (!token) {
-      await login();
-      throw new InwinkApiError(401, 'Non authentifié.');
+  return useMemo(() => {
+    async function doFetch(path: string, token: string, init?: RequestInit): Promise<Response> {
+      return fetch(`${baseUrl}${path}`, {
+        ...init,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+          ...(init?.headers as Record<string, string> | undefined),
+        },
+      });
     }
 
-    let response = await doFetch(path, token, init);
-
-    if (response.status === 401) {
-      const renewed = await renewToken();
-      if (renewed) {
-        token = renewed;
-        response = await doFetch(path, token, init);
+    async function request<T = unknown>(path: string, init?: RequestInit): Promise<T> {
+      let token = getAccessToken();
+      if (!token) {
+        await login();
+        throw new InwinkApiError(401, 'Non authentifié.');
       }
+
+      let response = await doFetch(path, token, init);
+
       if (response.status === 401) {
-        await login();
-        throw new InwinkApiError(401, 'Session expirée, reconnexion requise.');
+        const renewed = await renewToken();
+        if (renewed) {
+          token = renewed;
+          response = await doFetch(path, token, init);
+        }
+        if (response.status === 401) {
+          await login();
+          throw new InwinkApiError(401, 'Session expirée, reconnexion requise.');
+        }
       }
-    }
 
-    if (!response.ok) {
-      throw new InwinkApiError(response.status, await safeBody(response));
-    }
+      if (!response.ok) {
+        throw new InwinkApiError(response.status, await safeBody(response));
+      }
 
-    if (response.status === 204) {
-      return undefined as T;
+      if (response.status === 204) {
+        return undefined as T;
+      }
+      return (await response.json()) as T;
     }
-    return (await response.json()) as T;
-  }
 
-  const withBody =
-    (method: string) =>
-    <T = unknown>(path: string, body?: unknown, init?: RequestInit): Promise<T> =>
-      request<T>(path, {
-        ...init,
-        method,
-        body: body === undefined ? init?.body : JSON.stringify(body),
-      });
+    const withBody =
+      (method: string) =>
+      <T = unknown>(path: string, body?: unknown, init?: RequestInit): Promise<T> =>
+        request<T>(path, {
+          ...init,
+          method,
+          body: body === undefined ? init?.body : JSON.stringify(body),
+        });
 
-  return {
-    request,
-    get: <T = unknown>(path: string, init?: RequestInit) =>
-      request<T>(path, { ...init, method: 'GET' }),
-    post: withBody('POST'),
-    put: withBody('PUT'),
-    del: <T = unknown>(path: string, init?: RequestInit) =>
-      request<T>(path, { ...init, method: 'DELETE' }),
-  };
+    return {
+      request,
+      get: <T = unknown>(path: string, init?: RequestInit) =>
+        request<T>(path, { ...init, method: 'GET' }),
+      post: withBody('POST'),
+      put: withBody('PUT'),
+      del: <T = unknown>(path: string, init?: RequestInit) =>
+        request<T>(path, { ...init, method: 'DELETE' }),
+    };
+  }, [baseUrl, getAccessToken, renewToken, login]);
 }

package/templates/vite-extension/src/hooks/useInwinkContext.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+import { InwinkContext } from '../context/InwinkContextProvider';
+
+/** Accès au contexte inwink courant (event / community / tenant + loaders de listes). */
+export function useInwinkContext() {
+  const context = useContext(InwinkContext);
+
+  if (!context) {
+    throw new Error('useInwinkContext must be used within InwinkContextProvider.');
+  }
+
+  return context;
+}

package/templates/vite-extension/src/lib/inwinkContextParams.ts

@@ -0,0 +1,80 @@
+// Lecture / persistance du contexte inwink (event / community / tenant) passé
+// par le back-office dans l'URL à l'ouverture de l'extension.
+//
+// Pourquoi persister ? Le callback OIDC nettoie la query string
+// (`window.history.replaceState({}, '', pathname)`) et le `redirect_uri` ne
+// réémet pas la query : sans persistance, le contexte serait perdu après login.
+// On capture donc les paramètres dès le chargement dans sessionStorage.
+
+export type InwinkScope = 'event' | 'community' | 'tenant' | null;
+
+export interface InwinkContextParams {
+  eventId?: string;
+  communityId?: string;
+  tenantId?: string;
+}
+
+const STORAGE_KEY = 'inwink.context';
+
+/** Recherche une clé insensible à la casse dans un jeu de paramètres. */
+function pick(params: URLSearchParams, key: string): string | undefined {
+  for (const [k, v] of params.entries()) {
+    if (k.toLowerCase() === key && v) {
+      return v;
+    }
+  }
+  return undefined;
+}
+
+function paramsFromHashQuery(): URLSearchParams {
+  const hash = window.location.hash;
+  const queryIndex = hash.indexOf('?');
+  return queryIndex >= 0
+    ? new URLSearchParams(hash.slice(queryIndex + 1))
+    : new URLSearchParams();
+}
+
+/**
+ * Lit `eventid` / `communityid` / `tenantid` depuis l'URL.
+ * Couvre la query classique (`?eventid=`) ET la query dans le hash (`#/...?eventid=`),
+ * car le routage utilise HashRouter.
+ */
+export function readInwinkContextFromUrl(): InwinkContextParams {
+  const search = new URLSearchParams(window.location.search);
+  const hash = paramsFromHashQuery();
+  const get = (key: string) => pick(search, key) ?? pick(hash, key);
+
+  const params: InwinkContextParams = {};
+  const eventId = get('eventid');
+  const communityId = get('communityid');
+  const tenantId = get('tenantid');
+  if (eventId) params.eventId = eventId;
+  if (communityId) params.communityId = communityId;
+  if (tenantId) params.tenantId = tenantId;
+  return params;
+}
+
+export function persistContext(params: InwinkContextParams): void {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(params));
+  } catch {
+    // sessionStorage indisponible (mode privé strict) : on ignore silencieusement.
+  }
+}
+
+export function loadPersistedContext(): InwinkContextParams {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    return raw ? (JSON.parse(raw) as InwinkContextParams) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Détermine le scope courant. Priorité : event > community > tenant. */
+export function deriveScope(params: InwinkContextParams): InwinkScope {
+  if (params.eventId) return 'event';
+  if (params.communityId) return 'community';
+  if (params.tenantId) return 'tenant';
+  return null;
+}

package/templates/vite-extension/src/main.tsx

@@ -3,13 +3,16 @@ import ReactDOM from 'react-dom/client';
 import { HashRouter } from 'react-router-dom';
 import App from './App';
 import { AuthProvider } from './auth/AuthProvider';
+import { InwinkContextProvider } from './context/InwinkContextProvider';
 import './styles.css';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <HashRouter>
       <AuthProvider>
-        <App />
+        <InwinkContextProvider>
+          <App />
+        </InwinkContextProvider>
       </AuthProvider>
     </HashRouter>
   </React.StrictMode>,