@orakl/shared 0.1.0

package/dist/analytics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Analytics posture (map #840, decision #12): one self-hosted Umami script,
+ * served only when the visitor has not turned analytics off and their browser
+ * sends no privacy signal. The server decides — an opted-out page carries no
+ * measurement script at all.
+ */
+/** First-party opt-out cookie; value `off` means no script. */
+export declare const ANALYTICS_COOKIE = "orakl-analytics";
+export declare const ANALYTICS_OFF = "off";
+/** Placeholder in `app.html` that the HTML hook replaces. */
+export declare const ANALYTICS_MARKER = "<meta name=\"orakl-analytics-slot\" />";
+export declare const UMAMI_SCRIPT_TAG = "<script async defer src=\"https://visitors.nhg.app/vues\" data-website-id=\"3d102361-df16-457f-b384-3e22a7dc56fb\"></script>";
+export interface AnalyticsState {
+    /** True when the script is served. */
+    enabled: boolean;
+    /** True when the browser sent Global Privacy Control or Do Not Track. */
+    browserSignal: boolean;
+}
+export declare function analyticsState(request: Request, cookie: string | undefined): AnalyticsState;
+/** Replace the marker with the script tag, or with nothing. */
+export declare function renderAnalytics(html: string, state: AnalyticsState): string;

package/dist/analytics.js

@@ -0,0 +1,21 @@
+/**
+ * Analytics posture (map #840, decision #12): one self-hosted Umami script,
+ * served only when the visitor has not turned analytics off and their browser
+ * sends no privacy signal. The server decides — an opted-out page carries no
+ * measurement script at all.
+ */
+/** First-party opt-out cookie; value `off` means no script. */
+export const ANALYTICS_COOKIE = "orakl-analytics";
+export const ANALYTICS_OFF = "off";
+/** Placeholder in `app.html` that the HTML hook replaces. */
+export const ANALYTICS_MARKER = '<meta name="orakl-analytics-slot" />';
+export const UMAMI_SCRIPT_TAG = '<script async defer src="https://visitors.nhg.app/vues" data-website-id="3d102361-df16-457f-b384-3e22a7dc56fb"></script>';
+export function analyticsState(request, cookie) {
+    const browserSignal = request.headers.get("Sec-GPC") === "1" ||
+        request.headers.get("DNT") === "1";
+    return { enabled: !browserSignal && cookie !== ANALYTICS_OFF, browserSignal };
+}
+/** Replace the marker with the script tag, or with nothing. */
+export function renderAnalytics(html, state) {
+    return html.replace(ANALYTICS_MARKER, state.enabled ? UMAMI_SCRIPT_TAG : "");
+}

package/dist/avatar-helpers.d.ts

@@ -0,0 +1,46 @@
+export interface DbAvatar {
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    src: string;
+}
+export interface AvatarGroup {
+    category: string;
+    items: {
+        id: string;
+        title: string;
+        description: string;
+        src: string;
+    }[];
+}
+/** Build categorised avatar groups from DB avatar list. */
+export declare function buildAvatarGroups(dbAvatars: DbAvatar[]): AvatarGroup[];
+/** Resolve avatar src from DB list, falling back to static bundled avatars. */
+export declare function getAvatarSrc(avatarId: string, dbAvatars: DbAvatar[]): string;
+/** Default avatar description when none is provided. */
+export declare const DEFAULT_AVATAR_DESC = "There's no description for this avatar yet.";
+export interface PoolAvatar {
+    id: string;
+    title: string;
+    description: string;
+    src: string;
+}
+/** Merge DB avatars over the static bundled list, DB rows winning by id. */
+export declare function avatarPool(dbAvatars: DbAvatar[], staticAvatarList?: {
+    id: string;
+    name: string;
+    src: string;
+}[]): PoolAvatar[];
+/** Pick a uniformly random avatar from a pool. */
+export declare function randomAvatar<T>(pool: T[], rng?: () => number): T;
+/** Resolve a shown description, falling back to the default when empty. */
+export declare function avatarDescription(desc: string | undefined): string;
+/** Candidates for rallying: grouped (rendered) avatars when loaded, else the full pool. */
+export declare function rallyCandidates(groups: AvatarGroup[], dbAvatars: DbAvatar[], staticAvatarList?: {
+    id: string;
+    name: string;
+    src: string;
+}[]): PoolAvatar[];
+/** Whether setup should auto-pick an avatar: no selection yet, but a pool exists. */
+export declare function shouldAutoRally(selectedId: string, poolLength: number): boolean;

package/dist/avatar-helpers.js

@@ -0,0 +1,69 @@
+/**
+ * Avatar selection helpers for the join-quiz flow.
+ * Pure functions — no Alpine state dependencies.
+ */
+import { avatars as staticAvatars } from "./avatars.js";
+/** Build categorised avatar groups from DB avatar list. */
+export function buildAvatarGroups(dbAvatars) {
+    const grouped = new Map();
+    for (const av of dbAvatars) {
+        const cat = av.category || "";
+        if (!grouped.has(cat))
+            grouped.set(cat, []);
+        grouped.get(cat)?.push(av);
+    }
+    const cats = [...grouped.keys()].filter(Boolean).sort();
+    return [
+        ...cats.map((c) => ({ category: c, items: grouped.get(c) ?? [] })),
+        ...(grouped.has("")
+            ? [{ category: "", items: grouped.get("") ?? [] }]
+            : []),
+    ];
+}
+/** Resolve avatar src from DB list, falling back to static bundled avatars. */
+export function getAvatarSrc(avatarId, dbAvatars) {
+    const dbMatch = dbAvatars.find((a) => a.id === avatarId);
+    if (dbMatch)
+        return dbMatch.src;
+    return staticAvatars.find((a) => a.id === avatarId)?.src ?? "";
+}
+/** Default avatar description when none is provided. */
+export const DEFAULT_AVATAR_DESC = "There's no description for this avatar yet.";
+/** Merge DB avatars over the static bundled list, DB rows winning by id. */
+export function avatarPool(dbAvatars, staticAvatarList = staticAvatars) {
+    const dbIds = new Set(dbAvatars.map((a) => a.id));
+    const fromStatic = staticAvatarList
+        .filter((a) => !dbIds.has(a.id))
+        .map((a) => ({ id: a.id, title: a.name, description: "", src: a.src }));
+    const fromDb = dbAvatars.map((a) => ({
+        id: a.id,
+        title: a.title,
+        description: a.description,
+        src: a.src,
+    }));
+    return [...fromDb, ...fromStatic];
+}
+/** Pick a uniformly random avatar from a pool. */
+export function randomAvatar(pool, rng = Math.random) {
+    return pool[Math.floor(rng() * pool.length)];
+}
+/** Resolve a shown description, falling back to the default when empty. */
+export function avatarDescription(desc) {
+    return desc || DEFAULT_AVATAR_DESC;
+}
+/** Candidates for rallying: grouped (rendered) avatars when loaded, else the full pool. */
+export function rallyCandidates(groups, dbAvatars, staticAvatarList = staticAvatars) {
+    const flattened = groups.flatMap((g) => g.items.map((av) => ({
+        id: av.id,
+        title: av.title,
+        description: av.description,
+        src: av.src,
+    })));
+    return flattened.length > 0
+        ? flattened
+        : avatarPool(dbAvatars, staticAvatarList);
+}
+/** Whether setup should auto-pick an avatar: no selection yet, but a pool exists. */
+export function shouldAutoRally(selectedId, poolLength) {
+    return !selectedId && poolLength > 0;
+}

package/dist/avatars.d.ts

@@ -0,0 +1,6 @@
+export interface Avatar {
+    id: string;
+    name: string;
+    src: string;
+}
+export declare const avatars: Avatar[];