@c1m-public/dash-site-kit 0.4.0 → 0.5.0

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
@@ -173,7 +173,10 @@ server the kit uses `CHANNEL_SITE_NAME` when present, then derives `site` from
173
173
  `location.hostname`. Every event also receives `site_kind=dash-site`, so one
174
174
  shared Sentry project and one Grafana dashboard can separate future site
175
175
  families without another per-deployment variable. This prevents a deployment
176
- from claiming error reporting while sending no attributable events.
176
+ from claiming error reporting while sending no attributable events. The
177
+ `observability.grafana_dashboard` event context links directly back to the same
178
+ site selection in the shared Grafana dashboard; it is derived from `site` and
179
+ does not need configuration.
177
180
  Use `CHANNEL_SITE_CHANNEL_ID` only when one deployment always represents one
178
181
  channel. If a process can serve multiple channels, attach `channel_id` inside a
179
182
  request-local Sentry scope after resolving the request instead of setting a
@@ -1,7 +1,6 @@
1
1
  /**
2
- * Re-exported from the kit rather than redefined. The dash surface has no
3
- * webhook route in v1, so nothing revalidates this tag automatically — content
4
- * refreshes on the client's `revalidate` window. Keeping the kit's canonical
5
- * tag means a future on-demand revalidation hook needs no data migration.
2
+ * The one cache tag every cached dash read carries. `createDashWebhookRoute`
3
+ * revalidates it on `menu.updated` and `page.*`; sites that do not mount the
4
+ * receiver refresh at the client's `revalidate` window instead.
6
5
  */
7
6
  export { CHANNEL_SITE_CACHE_TAG } from "@c1m-public/channel-client/next";
@@ -1,7 +1,6 @@
1
1
  /**
2
- * Re-exported from the kit rather than redefined. The dash surface has no
3
- * webhook route in v1, so nothing revalidates this tag automatically — content
4
- * refreshes on the client's `revalidate` window. Keeping the kit's canonical
5
- * tag means a future on-demand revalidation hook needs no data migration.
2
+ * The one cache tag every cached dash read carries. `createDashWebhookRoute`
3
+ * revalidates it on `menu.updated` and `page.*`; sites that do not mount the
4
+ * receiver refresh at the client's `revalidate` window instead.
6
5
  */
7
6
  export { CHANNEL_SITE_CACHE_TAG } from "@c1m-public/channel-client/next";
@@ -1,6 +1,6 @@
1
1
  import "server-only";
2
- import { createNextChannelClient } from "@c1m-public/channel-client/next";
3
- type ChannelClient = ReturnType<typeof createNextChannelClient>;
2
+ import { type DashChannelClient } from "@c1m-public/channel-client/dash/next";
3
+ type ChannelClient = DashChannelClient;
4
4
  export declare class ChannelScopeMismatchError extends Error {
5
5
  constructor(actualScope: string);
6
6
  }
@@ -1,5 +1,5 @@
1
1
  import "server-only";
2
- import { createNextChannelClient } from "@c1m-public/channel-client/next";
2
+ import { createNextDashChannelClient } from "@c1m-public/channel-client/dash/next";
3
3
  import { cache } from "react";
4
4
  import { headers } from "next/headers";
5
5
  import { observeChannelRequest } from "./observability.js";
@@ -25,7 +25,7 @@ export function getChannelClient() {
25
25
  if (channelClient)
26
26
  return channelClient;
27
27
  const environment = resolveChannelEnvironment();
28
- channelClient = createNextChannelClient({
28
+ channelClient = createNextDashChannelClient({
29
29
  token: environment.token,
30
30
  ...(environment.apiUrl ? { baseUrl: environment.apiUrl } : {}),
31
31
  cache: { revalidate: 60, tags: [CHANNEL_SITE_CACHE_TAG] },
@@ -44,17 +44,17 @@ let visitorChannelClient = null;
44
44
  /**
45
45
  * The `no-store` client for VISITOR-SCOPED calls. Anything whose answer
46
46
  * depends on who is asking — geo detection (which picks the pricing region
47
- * and therefore the displayed currency), lead capture — must never ride the
48
- * shared 60s revalidation window above: the npm client forces no-store only
49
- * for mutations and customer-session reads, so a signed-visitor GET on the
50
- * cached singleton would be answered from the first visitor's cache entry
51
- * for everyone that follows.
47
+ * and therefore the displayed currency), lead capture — is kept off the
48
+ * shared 60s revalidation window above. Since channel-client 0.23.0 the
49
+ * adapter itself forces no-store for any visitor-signed read (and for the
50
+ * attestation ping), so this client is belt-and-braces rather than the only
51
+ * guard; it stays because the intent is clearer at the call site.
52
52
  */
53
53
  function getVisitorScopedChannelClient() {
54
54
  if (visitorChannelClient)
55
55
  return visitorChannelClient;
56
56
  const environment = resolveChannelEnvironment();
57
- visitorChannelClient = createNextChannelClient({
57
+ visitorChannelClient = createNextDashChannelClient({
58
58
  token: environment.token,
59
59
  ...(environment.apiUrl ? { baseUrl: environment.apiUrl } : {}),
60
60
  cache: "no-store",
@@ -8,3 +8,11 @@ export interface ChannelEnvironment {
8
8
  }
9
9
  type ChannelProcessEnvironment = Readonly<Record<string, string | undefined>>;
10
10
  export declare function resolveChannelEnvironment(environment?: ChannelProcessEnvironment): ChannelEnvironment;
11
+ /**
12
+ * The signing secret for the site's channel webhook receiver. Preferred name
13
+ * `SAASDASH_CHANNEL_WEBHOOK_SECRET`; `C1M_CHANNEL_WEBHOOK_SECRET` is accepted
14
+ * as the legacy name during the same migration the token went through. The
15
+ * value is read per request by the route factory, so a build without the
16
+ * secret still succeeds and the first request reports the omission.
17
+ */
18
+ export declare function resolveChannelWebhookSecret(environment?: ChannelProcessEnvironment): string;
package/dist/next/env.js CHANGED
@@ -32,3 +32,28 @@ export function resolveChannelEnvironment(environment = process.env) {
32
32
  }
33
33
  return apiUrl ? { token, apiUrl } : { token };
34
34
  }
35
+ /**
36
+ * The signing secret for the site's channel webhook receiver. Preferred name
37
+ * `SAASDASH_CHANNEL_WEBHOOK_SECRET`; `C1M_CHANNEL_WEBHOOK_SECRET` is accepted
38
+ * as the legacy name during the same migration the token went through. The
39
+ * value is read per request by the route factory, so a build without the
40
+ * secret still succeeds and the first request reports the omission.
41
+ */
42
+ export function resolveChannelWebhookSecret(environment = process.env) {
43
+ if (environment.NEXT_PUBLIC_SAASDASH_CHANNEL_WEBHOOK_SECRET ||
44
+ environment.NEXT_PUBLIC_C1M_CHANNEL_WEBHOOK_SECRET) {
45
+ throw new ChannelConfigurationError("SAASDASH_CHANNEL_WEBHOOK_SECRET must not use a NEXT_PUBLIC_* variable");
46
+ }
47
+ const preferred = environment.SAASDASH_CHANNEL_WEBHOOK_SECRET?.trim();
48
+ const legacy = environment.C1M_CHANNEL_WEBHOOK_SECRET?.trim();
49
+ if (preferred && legacy && preferred !== legacy) {
50
+ throw new ChannelConfigurationError("SAASDASH_CHANNEL_WEBHOOK_SECRET and legacy C1M_CHANNEL_WEBHOOK_SECRET must match during migration");
51
+ }
52
+ const secret = preferred || legacy;
53
+ if (!secret)
54
+ throw new ChannelConfigurationError("SAASDASH_CHANNEL_WEBHOOK_SECRET is required");
55
+ if (!secret.startsWith("whsec_")) {
56
+ throw new ChannelConfigurationError("SAASDASH_CHANNEL_WEBHOOK_SECRET must start with whsec_");
57
+ }
58
+ return secret;
59
+ }
@@ -0,0 +1,26 @@
1
+ import "server-only";
2
+ export interface SiteEvent {
3
+ name: string;
4
+ providerSlug: string;
5
+ }
6
+ export interface CreateSiteEventsRouteOptions {
7
+ /** The one event name this receiver accepts, e.g. `brand.directory_profile_viewed`. */
8
+ eventName: string;
9
+ /** Where an accepted event goes — the site's own observer. */
10
+ observe: (event: SiteEvent) => void;
11
+ /**
12
+ * Largest body accepted, in bytes. The beacon is a name and a slug; anything
13
+ * bigger is not ours.
14
+ */
15
+ maxBodyBytes?: number;
16
+ }
17
+ /**
18
+ * The browser-beacon receiver a dash site mounts at `app/api/site-events`.
19
+ *
20
+ * It is anonymous by nature (it is called from the page), so it holds the line
21
+ * in other ways: same-origin only where the browser says so (`Sec-Fetch-Site`),
22
+ * a small body cap, exactly one accepted event name, and a directory-key
23
+ * validated slug. Two commissioned sites carried byte-identical copies of this
24
+ * handler with no such checks.
25
+ */
26
+ export declare function createSiteEventsRoute(options: CreateSiteEventsRouteOptions): (request: Request) => Promise<Response>;
@@ -0,0 +1,44 @@
1
+ import "server-only";
2
+ import { validateDirectoryKey } from "../validation/directory.js";
3
+ const DEFAULT_MAX_BODY_BYTES = 1024;
4
+ /**
5
+ * The browser-beacon receiver a dash site mounts at `app/api/site-events`.
6
+ *
7
+ * It is anonymous by nature (it is called from the page), so it holds the line
8
+ * in other ways: same-origin only where the browser says so (`Sec-Fetch-Site`),
9
+ * a small body cap, exactly one accepted event name, and a directory-key
10
+ * validated slug. Two commissioned sites carried byte-identical copies of this
11
+ * handler with no such checks.
12
+ */
13
+ export function createSiteEventsRoute(options) {
14
+ const { eventName, observe, maxBodyBytes = DEFAULT_MAX_BODY_BYTES } = options;
15
+ const reject = (status) => new Response(null, { status });
16
+ return async (request) => {
17
+ const fetchSite = request.headers.get("sec-fetch-site");
18
+ if (fetchSite && fetchSite !== "same-origin")
19
+ return reject(403);
20
+ const length = Number(request.headers.get("content-length") ?? "0");
21
+ if (Number.isFinite(length) && length > maxBodyBytes)
22
+ return reject(413);
23
+ let payload;
24
+ try {
25
+ const text = await request.text();
26
+ if (text.length > maxBodyBytes)
27
+ return reject(413);
28
+ payload = JSON.parse(text);
29
+ }
30
+ catch {
31
+ return reject(400);
32
+ }
33
+ if (!payload || typeof payload !== "object")
34
+ return reject(400);
35
+ const value = payload;
36
+ if (value.name !== eventName)
37
+ return reject(400);
38
+ const providerSlug = validateDirectoryKey(value.providerSlug);
39
+ if (!providerSlug)
40
+ return reject(400);
41
+ observe({ name: eventName, providerSlug });
42
+ return new Response(null, { status: 204, headers: { "Cache-Control": "no-store" } });
43
+ };
44
+ }
@@ -0,0 +1,26 @@
1
+ import "server-only";
2
+ import { type ChannelCacheInvalidator, type ChannelWebhookHandlers, type ChannelWebhookRouteLogger } from "@c1m-public/channel-client/next";
3
+ export interface CreateDashWebhookRouteOptions {
4
+ /**
5
+ * Next's cache invalidation, injected so this module never imports `next`.
6
+ * Pass `{ revalidatePath, revalidateTag: (tag) => revalidateTag(tag, { expire: 0 }) }`
7
+ * from `next/cache`.
8
+ */
9
+ invalidate: ChannelCacheInvalidator;
10
+ /** Defaults to the SAASDASH_CHANNEL_WEBHOOK_SECRET environment variable, read per request. */
11
+ secret?: string | (() => string);
12
+ /** Per-event overrides; a handler replaces the built-in behavior for its type. */
13
+ onEvent?: ChannelWebhookHandlers;
14
+ logger?: ChannelWebhookRouteLogger;
15
+ }
16
+ /**
17
+ * The dash site's channel webhook receiver: `export const POST =
18
+ * createDashWebhookRoute({ invalidate })` in `app/api/webhooks/c1m/route.ts`.
19
+ *
20
+ * Every cached dash read is tagged `CHANNEL_SITE_CACHE_TAG` by
21
+ * `getChannelClient()`, so the client's built-in behavior — `menu.updated`
22
+ * and `page.*` revalidate that tag — refreshes profile, directory and plans
23
+ * on the next request instead of at the 60 s window. Before this factory no
24
+ * dash site had a receiver at all, whatever topics the backend emitted.
25
+ */
26
+ export declare function createDashWebhookRoute(options: CreateDashWebhookRouteOptions): (request: Request) => Promise<Response>;
@@ -0,0 +1,22 @@
1
+ import "server-only";
2
+ import { createChannelWebhookRoute, } from "@c1m-public/channel-client/next";
3
+ import { resolveChannelWebhookSecret } from "./env.js";
4
+ /**
5
+ * The dash site's channel webhook receiver: `export const POST =
6
+ * createDashWebhookRoute({ invalidate })` in `app/api/webhooks/c1m/route.ts`.
7
+ *
8
+ * Every cached dash read is tagged `CHANNEL_SITE_CACHE_TAG` by
9
+ * `getChannelClient()`, so the client's built-in behavior — `menu.updated`
10
+ * and `page.*` revalidate that tag — refreshes profile, directory and plans
11
+ * on the next request instead of at the 60 s window. Before this factory no
12
+ * dash site had a receiver at all, whatever topics the backend emitted.
13
+ */
14
+ export function createDashWebhookRoute(options) {
15
+ const { invalidate, secret, onEvent, logger } = options;
16
+ return createChannelWebhookRoute({
17
+ secret: secret ?? (() => resolveChannelWebhookSecret()),
18
+ invalidate,
19
+ ...(onEvent ? { onEvent } : {}),
20
+ ...(logger ? { logger } : {}),
21
+ });
22
+ }
package/dist/next.d.ts CHANGED
@@ -9,10 +9,14 @@
9
9
  export { createDashDataLayer } from "./next/data-layer.js";
10
10
  export type { DashDataLayer, DashDataLayerOptions, DashPreview } from "./next/data-layer.js";
11
11
  export { ChannelScopeMismatchError, getChannelClient, getDashChannelClient, getVisitorDashChannelClient, requireDashScope, } from "./next/client.js";
12
- export { ChannelConfigurationError, resolveChannelEnvironment } from "./next/env.js";
12
+ export { ChannelConfigurationError, resolveChannelEnvironment, resolveChannelWebhookSecret } from "./next/env.js";
13
13
  export type { ChannelEnvironment } from "./next/env.js";
14
14
  export { CHANNEL_SITE_CACHE_TAG } from "./next/cache.js";
15
15
  export { getChannelAttestation } from "./next/delivery.js";
16
+ export { createDashWebhookRoute } from "./next/webhooks.js";
17
+ export type { CreateDashWebhookRouteOptions } from "./next/webhooks.js";
18
+ export { createSiteEventsRoute } from "./next/site-events.js";
19
+ export type { CreateSiteEventsRouteOptions, SiteEvent } from "./next/site-events.js";
16
20
  export { observeChannelRequest } from "./next/observability.js";
17
21
  export { ChannelSiteSentryConfigurationError, createChannelSiteRequestErrorHandler, initializeChannelSiteSentry, resolveChannelSiteSentryOptions, } from "./next/sentry.js";
18
22
  export type { ChannelSiteSentryEnvironment, ChannelSiteSentryOptions, } from "./next/sentry.js";
package/dist/next.js CHANGED
@@ -8,9 +8,11 @@
8
8
  */
9
9
  export { createDashDataLayer } from "./next/data-layer.js";
10
10
  export { ChannelScopeMismatchError, getChannelClient, getDashChannelClient, getVisitorDashChannelClient, requireDashScope, } from "./next/client.js";
11
- export { ChannelConfigurationError, resolveChannelEnvironment } from "./next/env.js";
11
+ export { ChannelConfigurationError, resolveChannelEnvironment, resolveChannelWebhookSecret } from "./next/env.js";
12
12
  export { CHANNEL_SITE_CACHE_TAG } from "./next/cache.js";
13
13
  export { getChannelAttestation } from "./next/delivery.js";
14
+ export { createDashWebhookRoute } from "./next/webhooks.js";
15
+ export { createSiteEventsRoute } from "./next/site-events.js";
14
16
  export { observeChannelRequest } from "./next/observability.js";
15
17
  export { ChannelSiteSentryConfigurationError, createChannelSiteRequestErrorHandler, initializeChannelSiteSentry, resolveChannelSiteSentryOptions, } from "./next/sentry.js";
16
18
  export { resolveC1MAsset } from "./next/assets.js";
package/dist/sentry.d.ts CHANGED
@@ -10,6 +10,11 @@ export interface ChannelSiteSentryOptions {
10
10
  enableLogs: false;
11
11
  environment?: string;
12
12
  initialScope: {
13
+ contexts: {
14
+ observability: {
15
+ grafana_dashboard: string;
16
+ };
17
+ };
13
18
  tags: {
14
19
  channel_id?: string;
15
20
  site: string;
package/dist/sentry.js CHANGED
@@ -39,6 +39,12 @@ export function resolveChannelSiteSentryOptions(configuration) {
39
39
  enableLogs: false,
40
40
  ...(environment ? { environment } : {}),
41
41
  initialScope: {
42
+ contexts: {
43
+ observability: {
44
+ grafana_dashboard: "https://cloud1medialtd.grafana.net/d/c1m-sites-errors-health/saasdash-sites-errors-health" +
45
+ `?var-site=${encodeURIComponent(site)}&var-site_kind=dash-site&from=now-24h&to=now`,
46
+ },
47
+ },
42
48
  tags: {
43
49
  site,
44
50
  site_kind: "dash-site",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@c1m-public/dash-site-kit",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "description": "Shared transport, domain and UI layer for MML dash-scoped public sites",
@@ -54,7 +54,7 @@
54
54
  "typescript": "5.9.3",
55
55
  "vitest": "^4.1.4",
56
56
  "@types/node": "^22",
57
- "@c1m-public/channel-client": "0.21.0"
57
+ "@c1m-public/channel-client": "0.23.0"
58
58
  },
59
59
  "peerDependenciesMeta": {
60
60
  "next": {