@c1m-public/dash-site-kit 0.4.1 → 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.
@@ -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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@c1m-public/dash-site-kit",
3
- "version": "0.4.1",
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": {