@mgamadeus/ddd-site-insights 0.1.0-rc.2 → 0.1.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -3,8 +3,9 @@
3
3
  Frontend of the site insights module for backends built with [mgamadeus/ddd](https://github.com/ddd-framework/ddd)
4
4
  (Composer package [`mgamadeus/ddd-site-insights`](https://github.com/ddd-framework/ddd-site-insights), same version).
5
5
 
6
- Entry `.` holds the TypeScript types generated from the module's API and pure window logic. It loads no React and no
7
- stylesheet and can run on a server. The API factory and the screens follow in later versions.
6
+ Entry `.` holds the API factory, the TypeScript types generated from the module's API, and pure view logic (windows,
7
+ deltas, coverage wording). It loads no React runtime and no stylesheet; the pure functions run on a server. The screens
8
+ follow in a later version (`./screens`).
8
9
 
9
10
  ## Install
10
11
 
@@ -15,6 +16,36 @@ npm install @mgamadeus/ddd-site-insights
15
16
  ESM only. Peer dependencies: `@mgamadeus/ddd-web` `>=0.13.0 <1`, `@reduxjs/toolkit` `^2.6.0`, `react` `^19.0.0`,
16
17
  `react-redux` `^9.0.0`.
17
18
 
19
+ ## API factory
20
+
21
+ ```ts
22
+ import { createSiteInsightsApi } from '@mgamadeus/ddd-site-insights';
23
+ import { api } from './api'; // the application's createApi(...) with its DDD base query
24
+
25
+ export const siteInsightsApi = createSiteInsightsApi({ baseApi: api, apiPrefix: '/api/admin/siteInsights' });
26
+
27
+ const { data } = siteInsightsApi.useSearchQueriesQuery({ siteKey: 'example-site', compare: 'previousPeriod', limit: 100 });
28
+ ```
29
+
30
+ The factory injects the module's ten operations into the application's RTK Query api once (a second call with the
31
+ same api returns the first result) under the tag `SiteInsights`, rebasing the generated request builders onto
32
+ `apiPrefix`. Hooks: `useSitesQuery`, `useCheckAccessMutation` (a POST that counts a URL inspection: call it on demand),
33
+ `useSearchOverviewQuery`, `useSearchQueriesQuery`, `useSearchPagesQuery`, `useSearchCountriesQuery`,
34
+ `useSearchDevicesQuery`, `useSearchPageGroupsQuery`, `useSearchPageDetailQuery`, `useSearchQueryDetailQuery`. Keep the
35
+ module's tag out of the application's own generated SDK (`filterEndpoints`).
36
+
37
+ ## Deltas and coverage
38
+
39
+ ```ts
40
+ import { formatCoverageNotes, formatDelta } from '@mgamadeus/ddd-site-insights';
41
+
42
+ formatDelta(row.comparison, 'clicks'); // { text: '+12', direction: 'up', improvement: true, … }; notObserved is never 0
43
+ formatDelta(row.comparison, 'position'); // a lower position is an improvement
44
+ formatCoverageNotes(rows); // [{ code: 'sortedByModule', text: … }, { code: 'anonymizedQueriesOmitted', … }]
45
+ ```
46
+
47
+ Hosts translate the notes by `code` and the counterpart states through `stateTexts`.
48
+
18
49
  ## Window logic
19
50
 
20
51
  ```ts