@deveye/types 0.15.0

package/src/features/audience.ts

@@ -0,0 +1,275 @@
+import { z } from 'zod';
+import {
+    AUDIENCE_BREAKDOWN_MAX,
+    AUDIENCE_FUNNEL_MAX_STEPS,
+    AUDIENCE_FUNNEL_NAME_MAX_LENGTH,
+    AUDIENCE_MAX_ORIGINS,
+    AUDIENCE_ORIGIN_MAX_LENGTH,
+    AUDIENCE_RETENTION_MAX_DAYS,
+    AUDIENCE_RETENTION_MIN_DAYS,
+    AUDIENCE_SITE_DESCRIPTION_MAX_LENGTH,
+    AUDIENCE_SITE_NAME_MAX_LENGTH,
+    audienceActivitySchema,
+    audienceBreakdownItemSchema,
+    audienceDimensionSchema,
+    audienceFunnelSchema,
+    audienceFunnelStepDraftSchema,
+    audienceLiveSchema,
+    audienceOverviewSchema,
+    audiencePlatformSchema,
+    audienceRangeSchema,
+    audienceVisitorModeSchema,
+    audienceSiteSchema,
+    audienceUsageSchema
+} from '../domain/audience';
+
+/**
+ * Commandes de l'audience d'un espace.
+ *
+ * Préfixe unique `audience.`, comme `git.`, `database.` et `project.` — d'où le
+ * camelCase derrière le point.
+ *
+ * ⚠️ Conséquence à connaître : le filet de démarrage (`MUTATION_VERB` dans
+ * `src/features/_topics.ts`) cherche un verbe **juste après le point**. Il ne
+ * verra donc **aucune** de ces commandes, et un `mutates` oublié ne produira
+ * aucun avertissement. Il se relit à la main.
+ *
+ * ## Ce qui n'est pas ici
+ *
+ * L'**ingestion** n'est pas une commande. Elle entre par HTTP, sans session,
+ * depuis des machines qui ne connaissent pas DevEye — voir `POST /api/t/b`. Ces
+ * commandes-ci ne font que *lire* ce qu'elle a écrit, et *déclarer* les sites.
+ *
+ * L'espace visé n'apparaît dans aucune entrée : il voyage sur l'enveloppe WS et
+ * le dispatcheur le résout, appartenance vérifiée, avant le handler.
+ */
+
+const siteId = z.number().int().positive();
+
+/** Ce qu'on peut régler sur un site — identique à l'ajout et à la modification. */
+const siteBody = {
+    name: z.string().min(1).max(AUDIENCE_SITE_NAME_MAX_LENGTH),
+    description: z.string().max(AUDIENCE_SITE_DESCRIPTION_MAX_LENGTH),
+    platform: audiencePlatformSchema,
+    visitorMode: audienceVisitorModeSchema,
+    /**
+     * Les hôtes autorisés à écrire. Le client envoie des hôtes nus
+     * (`exemple.fr`) ou des origines complètes (`https://exemple.fr`) : le
+     * serveur normalise, parce que c'est lui qui compare.
+     */
+    origins: z.array(z.string().max(AUDIENCE_ORIGIN_MAX_LENGTH)).max(AUDIENCE_MAX_ORIGINS),
+    active: z.boolean(),
+    retentionDays: z
+        .number()
+        .int()
+        .min(AUDIENCE_RETENTION_MIN_DAYS)
+        .max(AUDIENCE_RETENTION_MAX_DAYS)
+};
+
+// ------------------------------------------------------------------ sites
+
+/** Le nombre de sites de l'espace, pour la tuile de l'accueil. */
+export const audienceCount = {
+    command: 'audience.count' as const,
+    input: z.object({}),
+    output: z.object({ count: z.number().int().nonnegative() })
+};
+
+/** Les sites de l'espace, dans l'ordre de l'utilisateur. */
+export const audienceList = {
+    command: 'audience.list' as const,
+    input: z.object({}),
+    output: z.object({ sites: z.array(audienceSiteSchema) })
+};
+
+/**
+ * Un site, avec les projets qui le suivent et l'adresse de sa balise.
+ *
+ * `ingestOrigin` vient du serveur (`AUDIENCE_ORIGIN`, à défaut `PUBLIC_ORIGIN`)
+ * et non de l'origine du navigateur : l'application est derrière le VPN, alors
+ * que l'ingestion doit être joignable sans lui — les deux adresses diffèrent
+ * donc par construction. La déduire côté client aurait donné une balise juste en
+ * développement et fausse en production, ce qui est le pire des deux mondes.
+ */
+export const audienceGet = {
+    command: 'audience.get' as const,
+    input: z.object({ siteId }),
+    output: z.object({
+        site: audienceSiteSchema,
+        usage: z.array(audienceUsageSchema),
+        ingestOrigin: z.string()
+    })
+};
+
+/**
+ * Déclare un site. La clé publique est **engendrée par le serveur** : la laisser
+ * choisir permettrait de viser celle d'un site existant d'un autre espace.
+ */
+export const audienceSiteAdd = {
+    command: 'audience.siteAdd' as const,
+    input: z.object(siteBody),
+    output: z.object({ site: audienceSiteSchema })
+};
+
+export const audienceSiteUpdate = {
+    command: 'audience.siteUpdate' as const,
+    input: z.object({ siteId, ...siteBody }),
+    output: z.object({ site: audienceSiteSchema })
+};
+
+/**
+ * Supprime un site **et tout son historique**.
+ *
+ * Contrairement aux projets, rien ne s'archive ici : un site retiré n'a pas de
+ * seconde vie, et garder des millions d'événements orphelins pour un objet que
+ * plus rien ne nomme ne rendrait service à personne. Les liaisons de projet
+ * tombent avec (`CASCADE`), les projets eux-mêmes ne bougent pas.
+ */
+export const audienceSiteRemove = {
+    command: 'audience.siteRemove' as const,
+    input: z.object({ siteId }),
+    output: z.object({ ok: z.literal(true) })
+};
+
+/**
+ * Renouvelle la clé publique.
+ *
+ * Le geste utile quand une clé s'est retrouvée là où elle n'aurait pas dû —
+ * dépôt public, capture d'écran. L'ancienne cesse d'entrer **immédiatement** ;
+ * l'historique déjà collecté, lui, reste : il a été mesuré, il est vrai.
+ */
+export const audienceSiteRotateKey = {
+    command: 'audience.siteRotateKey' as const,
+    input: z.object({ siteId }),
+    output: z.object({ site: audienceSiteSchema })
+};
+
+export const audienceReorder = {
+    command: 'audience.reorder' as const,
+    input: z.object({ siteIds: z.array(siteId).min(1) }),
+    output: z.object({ ok: z.literal(true) })
+};
+
+// ------------------------------------------------------------ statistiques
+
+/** Le bandeau, la comparaison à la période précédente, et la courbe. */
+export const audienceOverview = {
+    command: 'audience.overview' as const,
+    input: z.object({ siteId, range: audienceRangeSchema }),
+    output: audienceOverviewSchema
+};
+
+/**
+ * Un classement sur l'axe demandé.
+ *
+ * Une commande pour les neuf axes plutôt que neuf commandes : ils rendent tous
+ * la même forme, se lisent par la même requête, et l'écran en affiche plusieurs
+ * côte à côte. Neuf entrées auraient divergé au premier ajustement.
+ */
+export const audienceBreakdown = {
+    command: 'audience.breakdown' as const,
+    input: z.object({
+        siteId,
+        range: audienceRangeSchema,
+        dimension: audienceDimensionSchema,
+        limit: z.number().int().min(1).max(AUDIENCE_BREAKDOWN_MAX).optional()
+    }),
+    output: z.object({ items: z.array(audienceBreakdownItemSchema) })
+};
+
+/** La carte jour × heure, en heure **locale du visiteur**, et les fuseaux. */
+export const audienceActivity = {
+    command: 'audience.activity' as const,
+    input: z.object({ siteId, range: audienceRangeSchema }),
+    output: audienceActivitySchema
+};
+
+/**
+ * Qui est là en ce moment (cinq dernières minutes).
+ *
+ * Volontairement séparée de `overview` : elle est minuscule, elle se relit
+ * souvent, et la faire voyager avec le bandeau obligerait à recalculer tout
+ * l'agrégat pour rafraîchir un compteur.
+ */
+export const audienceLive = {
+    command: 'audience.live' as const,
+    input: z.object({ siteId }),
+    output: audienceLiveSchema
+};
+
+// ------------------------------------------------------------ entonnoirs
+
+const funnelId = z.number().int().positive();
+
+/** Les marches, dans l'ordre. Un entonnoir d'une seule marche n'en est pas un. */
+const steps = z.array(audienceFunnelStepDraftSchema).min(2).max(AUDIENCE_FUNNEL_MAX_STEPS);
+
+/**
+ * Les entonnoirs d'un site, **avec leurs chiffres** sur la fenêtre demandée.
+ *
+ * Définitions et mesures dans la même réponse : l'écran n'affiche jamais l'une
+ * sans l'autre, et les séparer aurait fait deux allers-retours pour dessiner un
+ * seul graphique. Les entonnoirs se comptent en unités, pas en milliers.
+ */
+export const audienceFunnelList = {
+    command: 'audience.funnelList' as const,
+    input: z.object({ siteId, range: audienceRangeSchema }),
+    output: z.object({ funnels: z.array(audienceFunnelSchema) })
+};
+
+/**
+ * Définit un entonnoir à partir de ce que le site a **déjà** émis.
+ *
+ * C'est tout le découpage : le site pose des signaux nommés, l'entonnoir se
+ * compose ici. Mesurer autre chose ne demande donc aucun redéploiement — ni
+ * même de prévenir qui que ce soit.
+ */
+export const audienceFunnelAdd = {
+    command: 'audience.funnelAdd' as const,
+    input: z.object({
+        siteId,
+        name: z.string().min(1).max(AUDIENCE_FUNNEL_NAME_MAX_LENGTH),
+        steps
+    }),
+    output: z.object({ funnelId })
+};
+
+export const audienceFunnelUpdate = {
+    command: 'audience.funnelUpdate' as const,
+    input: z.object({
+        funnelId,
+        name: z.string().min(1).max(AUDIENCE_FUNNEL_NAME_MAX_LENGTH),
+        steps
+    }),
+    output: z.object({ ok: z.literal(true) })
+};
+
+/**
+ * Supprime un entonnoir. **Aucune mesure n'est perdue** : un entonnoir n'est
+ * qu'une lecture des événements déjà là, jamais une collecte à part. Le
+ * recréer à l'identique rendrait exactement les mêmes chiffres.
+ */
+export const audienceFunnelRemove = {
+    command: 'audience.funnelRemove' as const,
+    input: z.object({ funnelId }),
+    output: z.object({ ok: z.literal(true) })
+};
+
+export const audienceCommands = [
+    audienceCount,
+    audienceList,
+    audienceGet,
+    audienceSiteAdd,
+    audienceSiteUpdate,
+    audienceSiteRemove,
+    audienceSiteRotateKey,
+    audienceReorder,
+    audienceOverview,
+    audienceBreakdown,
+    audienceActivity,
+    audienceLive,
+    audienceFunnelList,
+    audienceFunnelAdd,
+    audienceFunnelUpdate,
+    audienceFunnelRemove
+] as const;

package/src/features/backup.ts

@@ -0,0 +1,230 @@
+import { z } from 'zod';
+import {
+    BACKUP_ACCESS_KEY_MAX,
+    BACKUP_BUCKET_MAX,
+    BACKUP_DESTINATION_NAME_MAX,
+    BACKUP_ENDPOINT_MAX,
+    BACKUP_JOB_NAME_MAX,
+    BACKUP_PATH_MAX,
+    BACKUP_SECRET_MAX,
+    backupDestinationKindSchema,
+    backupDestinationProbeSchema,
+    backupDestinationSchema,
+    backupEncryptionSchema,
+    backupJobSchema,
+    backupRunSchema,
+    backupScheduleKindSchema,
+    backupSourceCandidateSchema,
+    backupSourceKindSchema
+} from '../domain/backup';
+
+/**
+ * Commandes des sauvegardes.
+ *
+ * Deux moitiés qui ne se recouvrent pas: les **destinations** (où) et les
+ * **travaux** (quoi, quand, combien de copies). Tout est à l'étage ouvert, donc
+ * aucune de ces commandes ne demande de session déverrouillée — c'est la
+ * condition pour qu'une sauvegarde parte à 3 h du matin.
+ *
+ * `backup.deveyeDump` n'existe pas comme commande: la base de DevEye se
+ * sauvegarde par un travail de source `deveye` comme les autres, et il n'y a
+ * aucune raison de lui inventer un chemin à part.
+ */
+
+const destinationId = z.number().int().positive();
+const jobId = z.number().int().positive();
+
+// ---------------------------------------------------------- destinations
+
+/** Les destinations de l'espace, dans l'ordre où elles ont été déclarées. */
+export const backupDestinationList = {
+    command: 'backup.destinationList' as const,
+    input: z.object({}),
+    output: z.object({ destinations: z.array(backupDestinationSchema) })
+};
+
+/**
+ * Déclare une destination.
+ *
+ * Un seul schéma pour les trois genres, avec les champs des deux autres à
+ * `null`: la forme alternative (trois commandes, ou une union discriminée)
+ * obligerait l'écran à trois formulaires là où il n'en a qu'un, dont les champs
+ * apparaissent selon le genre choisi.
+ */
+export const backupDestinationAdd = {
+    command: 'backup.destinationAdd' as const,
+    input: z.object({
+        kind: backupDestinationKindSchema,
+        name: z.string().min(1).max(BACKUP_DESTINATION_NAME_MAX),
+        deviceId: z.uuid().nullable(),
+        path: z.string().max(BACKUP_PATH_MAX),
+        endpoint: z.string().max(BACKUP_ENDPOINT_MAX).nullable(),
+        region: z.string().max(64).nullable(),
+        bucket: z.string().max(BACKUP_BUCKET_MAX).nullable(),
+        accessKeyId: z.string().max(BACKUP_ACCESS_KEY_MAX).nullable(),
+        secret: z.string().max(BACKUP_SECRET_MAX).nullable(),
+        pathStyle: z.boolean()
+    }),
+    output: z.object({ destination: backupDestinationSchema })
+};
+
+/** `secret` omis = inchangé: le serveur ne l'a jamais rendu, on ne le réécrit pas. */
+export const backupDestinationUpdate = {
+    command: 'backup.destinationUpdate' as const,
+    input: z.object({
+        destinationId,
+        name: z.string().min(1).max(BACKUP_DESTINATION_NAME_MAX),
+        deviceId: z.uuid().nullable(),
+        path: z.string().max(BACKUP_PATH_MAX),
+        endpoint: z.string().max(BACKUP_ENDPOINT_MAX).nullable(),
+        region: z.string().max(64).nullable(),
+        bucket: z.string().max(BACKUP_BUCKET_MAX).nullable(),
+        accessKeyId: z.string().max(BACKUP_ACCESS_KEY_MAX).nullable(),
+        secret: z.string().max(BACKUP_SECRET_MAX).optional(),
+        pathStyle: z.boolean()
+    }),
+    output: z.object({ destination: backupDestinationSchema })
+};
+
+/**
+ * Retire une destination. **Refusée** tant qu'un travail la vise.
+ *
+ * Contrairement aux jetons de déploiement, qui laissent la cible orpheline mais
+ * vivante: un travail sans destination n'a aucun comportement raisonnable — il
+ * ne peut ni s'exécuter ni le dire à l'avance. Mieux vaut obliger à trancher.
+ */
+export const backupDestinationRemove = {
+    command: 'backup.destinationRemove' as const,
+    input: z.object({ destinationId }),
+    output: z.object({ destinationId })
+};
+
+/**
+ * Contrôle qu'une destination est joignable et inscriptible, **maintenant**.
+ *
+ * Écrit puis relit puis efface un petit objet témoin: lister un bucket ne prouve
+ * pas qu'on peut y écrire, et découvrir le contraire à 3 h du matin est
+ * exactement ce que cette commande existe pour éviter.
+ */
+export const backupDestinationTest = {
+    command: 'backup.destinationTest' as const,
+    input: z.object({ destinationId }),
+    output: backupDestinationProbeSchema
+};
+
+// ---------------------------------------------------------------- travaux
+
+/** Les travaux de l'espace, avec l'état de leur dernier passage. */
+export const backupJobList = {
+    command: 'backup.jobList' as const,
+    input: z.object({}),
+    output: z.object({ jobs: z.array(backupJobSchema) })
+};
+
+/** Compte les travaux actifs. Métadonnée en clair pure, pour la tuile d'accueil. */
+export const backupCount = {
+    command: 'backup.count' as const,
+    input: z.object({}),
+    output: z.object({
+        count: z.number().int().nonnegative(),
+        /** Combien ont échoué à leur dernier passage — ce que la tuile signale. */
+        failing: z.number().int().nonnegative()
+    })
+};
+
+/** Un travail et son historique, du plus récent au plus ancien. */
+export const backupJobGet = {
+    command: 'backup.jobGet' as const,
+    input: z.object({ jobId, limit: z.number().int().positive().max(100).optional() }),
+    output: z.object({ job: backupJobSchema, runs: z.array(backupRunSchema) })
+};
+
+const jobBody = {
+    name: z.string().min(1).max(BACKUP_JOB_NAME_MAX),
+    destinationId,
+    encryption: backupEncryptionSchema,
+    source: backupSourceKindSchema,
+    sourceId: z.number().int().positive().nullable(),
+    enabled: z.boolean(),
+    schedule: backupScheduleKindSchema,
+    scheduleHour: z.number().int().min(0).max(23),
+    scheduleWeekday: z.number().int().min(0).max(6),
+    scheduleDay: z.number().int().min(1).max(28),
+    keepLast: z.number().int().min(1).max(365)
+};
+
+export const backupJobAdd = {
+    command: 'backup.jobAdd' as const,
+    input: z.object(jobBody),
+    output: z.object({ job: backupJobSchema })
+};
+
+export const backupJobUpdate = {
+    command: 'backup.jobUpdate' as const,
+    input: z.object({ jobId, ...jobBody }),
+    output: z.object({ job: backupJobSchema })
+};
+
+/**
+ * Supprime un travail et son historique.
+ *
+ * Les archives déjà écrites ne sont **pas** touchées: DevEye a produit des
+ * fichiers chez quelqu'un d'autre, et les effacer parce qu'on range sa
+ * configuration serait le contraire d'une sauvegarde. L'écran le dit.
+ */
+export const backupJobRemove = {
+    command: 'backup.jobRemove' as const,
+    input: z.object({ jobId }),
+    output: z.object({ jobId })
+};
+
+/**
+ * Lance un travail tout de suite.
+ *
+ * Ne rend pas l'archive: une sauvegarde dure des minutes, et attendre la réponse
+ * d'une commande WS pendant ce temps-là ne marcherait pas. Elle inscrit
+ * l'exécution en `running` et rend sa ligne; l'avancement se lit en
+ * re-sollicitant, comme partout ailleurs (le sujet `backup` est diffusé à
+ * chaque transition).
+ */
+export const backupJobRun = {
+    command: 'backup.jobRun' as const,
+    input: z.object({ jobId }),
+    output: z.object({ run: backupRunSchema })
+};
+
+/** Les sources sauvegardables de l'espace, pour remplir le sélecteur. */
+export const backupSources = {
+    command: 'backup.sources' as const,
+    input: z.object({}),
+    output: z.object({ candidates: z.array(backupSourceCandidateSchema) })
+};
+
+/**
+ * Les dernières exécutions de l'espace, tous travaux confondus.
+ *
+ * Ce que la vue d'ensemble montre: on veut savoir « est-ce que mes sauvegardes
+ * tournent », pas ouvrir sept fiches pour le découvrir.
+ */
+export const backupRuns = {
+    command: 'backup.runs' as const,
+    input: z.object({ limit: z.number().int().positive().max(200).optional() }),
+    output: z.object({ runs: z.array(backupRunSchema) })
+};
+
+export const backupCommands = [
+    backupDestinationList,
+    backupDestinationAdd,
+    backupDestinationUpdate,
+    backupDestinationRemove,
+    backupDestinationTest,
+    backupJobList,
+    backupCount,
+    backupJobGet,
+    backupJobAdd,
+    backupJobUpdate,
+    backupJobRemove,
+    backupJobRun,
+    backupSources,
+    backupRuns
+] as const;