@c1m-public/dash-site-kit 0.2.1 → 0.4.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
@@ -111,6 +111,74 @@ preferred; `C1M_*` is accepted for older sites:
111
111
  The token is **server-only**. A `NEXT_PUBLIC_*` form of either variable is
112
112
  rejected at startup rather than ignored.
113
113
 
114
+ ## Error reporting
115
+
116
+ The kit owns the shared channel-site Sentry options and validation, but the
117
+ site owns the SDK import. Keep the static import in the special Next.js file so
118
+ Turbopack can include `@sentry/nextjs` in both server and edge outputs:
119
+
120
+ ```ts
121
+ // instrumentation.ts, or src/instrumentation.ts when the app uses src/app
122
+ import * as Sentry from "@sentry/nextjs";
123
+ import {
124
+ createChannelSiteRequestErrorHandler,
125
+ initializeChannelSiteSentry,
126
+ } from "@c1m-public/dash-site-kit/next";
127
+
128
+ export function register() {
129
+ initializeChannelSiteSentry(Sentry.init);
130
+ }
131
+
132
+ export const onRequestError = createChannelSiteRequestErrorHandler(
133
+ Sentry.captureRequestError,
134
+ );
135
+ ```
136
+
137
+ The consuming site must install `@sentry/nextjs`. The kit deliberately does not
138
+ list or dynamically discover it: an indirect runtime import can be omitted from
139
+ a Vercel function bundle and turn a packaging error into silent telemetry loss.
140
+
141
+ | Variable | Required | Meaning |
142
+ | --- | --- | --- |
143
+ | `CHANNEL_SITE_SENTRY_DSN` | no | Shared channel-sites Sentry DSN; absence disables reporting |
144
+ | `CHANNEL_SITE_NAME` | no | Backwards-compatible site-tag override; otherwise the Vercel production hostname is used |
145
+ | `CHANNEL_SITE_CHANNEL_ID` | no | Immutable channel identifier added as the `channel_id` tag |
146
+ | `SENTRY_ENVIRONMENT` | no | Explicit Sentry environment; otherwise `VERCEL_ENV` is used |
147
+
148
+ Browser capture uses the framework-neutral builder from the package root. The
149
+ consumer passes literal `NEXT_PUBLIC_*` values so Next.js can inline them:
150
+
151
+ ```ts
152
+ // instrumentation-client.ts
153
+ import * as Sentry from "@sentry/nextjs";
154
+ import { resolveChannelSiteSentryOptions } from "@c1m-public/dash-site-kit";
155
+
156
+ const options = resolveChannelSiteSentryOptions({
157
+ dsn: process.env.CHANNEL_SITE_BROWSER_SENTRY_DSN,
158
+ environment: process.env.NEXT_PUBLIC_VERCEL_ENV,
159
+ release: process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
160
+ site: globalThis.location.hostname,
161
+ });
162
+ if (options) Sentry.init(options);
163
+
164
+ export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;
165
+ ```
166
+
167
+ The browser DSN is public by design. Source-map upload credentials remain
168
+ build-only and must never use `NEXT_PUBLIC_*`.
169
+
170
+ A configured but malformed DSN or missing site identity fails fast. On the
171
+ server the kit uses `CHANNEL_SITE_NAME` when present, then derives `site` from
172
+ `VERCEL_PROJECT_PRODUCTION_URL`. Browser composition roots use
173
+ `location.hostname`. Every event also receives `site_kind=dash-site`, so one
174
+ shared Sentry project and one Grafana dashboard can separate future site
175
+ families without another per-deployment variable. This prevents a deployment
176
+ from claiming error reporting while sending no attributable events.
177
+ Use `CHANNEL_SITE_CHANNEL_ID` only when one deployment always represents one
178
+ channel. If a process can serve multiple channels, attach `channel_id` inside a
179
+ request-local Sentry scope after resolving the request instead of setting a
180
+ global initialization tag.
181
+
114
182
  ## Cache policy
115
183
 
116
184
  Two clients, deliberately:
package/dist/index.d.ts CHANGED
@@ -28,3 +28,5 @@ export * from "./url-policy.js";
28
28
  export * from "./image-policy.js";
29
29
  export { canonicalUrl, createSiteConfig, safeLocale, } from "./site-config.js";
30
30
  export type { SiteConfig, SiteConfigOptions, SiteDefaults, SiteMeta, SiteMetaBootstrap, } from "./site-config.js";
31
+ export { ChannelSiteSentryConfigurationError, resolveChannelSiteSentryOptions, } from "./sentry.js";
32
+ export type { ChannelSiteSentryConfiguration, ChannelSiteSentryOptions, } from "./sentry.js";
package/dist/index.js CHANGED
@@ -4,3 +4,4 @@ export { formatMoney } from "./format.js";
4
4
  export * from "./url-policy.js";
5
5
  export * from "./image-policy.js";
6
6
  export { canonicalUrl, createSiteConfig, safeLocale, } from "./site-config.js";
7
+ export { ChannelSiteSentryConfigurationError, resolveChannelSiteSentryOptions, } from "./sentry.js";
@@ -1,12 +1,10 @@
1
1
  import "server-only";
2
+ import { ChannelConfigurationError } from "@c1m-public/channel-client";
3
+ export { ChannelConfigurationError };
2
4
  export interface ChannelEnvironment {
3
5
  token: string;
4
6
  /** Set only for local development or a self-hosted SaaSDash API. */
5
7
  apiUrl?: string;
6
8
  }
7
- export declare class ChannelConfigurationError extends Error {
8
- constructor(message: string);
9
- }
10
9
  type ChannelProcessEnvironment = Readonly<Record<string, string | undefined>>;
11
10
  export declare function resolveChannelEnvironment(environment?: ChannelProcessEnvironment): ChannelEnvironment;
12
- export {};
package/dist/next/env.js CHANGED
@@ -1,10 +1,6 @@
1
1
  import "server-only";
2
- export class ChannelConfigurationError extends Error {
3
- constructor(message) {
4
- super(message);
5
- this.name = "ChannelConfigurationError";
6
- }
7
- }
2
+ import { ChannelConfigurationError } from "@c1m-public/channel-client";
3
+ export { ChannelConfigurationError };
8
4
  export function resolveChannelEnvironment(environment = process.env) {
9
5
  if (environment.NEXT_PUBLIC_SAASDASH_CHANNEL_TOKEN || environment.NEXT_PUBLIC_C1M_CHANNEL_TOKEN) {
10
6
  throw new ChannelConfigurationError("SAASDASH_CHANNEL_TOKEN must not use a NEXT_PUBLIC_* variable");
@@ -0,0 +1,31 @@
1
+ import "server-only";
2
+ import { ChannelSiteSentryConfigurationError, type ChannelSiteSentryOptions } from "../sentry.js";
3
+ /** Environment keys shared by every dash-scoped channel site. */
4
+ export interface ChannelSiteSentryEnvironment {
5
+ CHANNEL_SITE_CHANNEL_ID?: string;
6
+ CHANNEL_SITE_NAME?: string;
7
+ CHANNEL_SITE_SENTRY_DSN?: string;
8
+ NEXT_RUNTIME?: string;
9
+ SENTRY_ENVIRONMENT?: string;
10
+ VERCEL_ENV?: string;
11
+ VERCEL_PROJECT_PRODUCTION_URL?: string;
12
+ }
13
+ /** The narrow Sentry configuration surface owned by dash-site-kit. */
14
+ export { ChannelSiteSentryConfigurationError };
15
+ export type { ChannelSiteSentryOptions };
16
+ /**
17
+ * Resolve the common Sentry options for a channel site.
18
+ *
19
+ * An absent DSN intentionally disables reporting. A present but malformed
20
+ * configuration fails fast so a deployment cannot claim error reporting while
21
+ * silently sending nothing.
22
+ */
23
+ export declare function resolveChannelSiteSentryOptions(environment?: ChannelSiteSentryEnvironment): ChannelSiteSentryOptions | null;
24
+ /**
25
+ * Initialise an app-owned Sentry SDK with shared, validated channel-site
26
+ * options. The consuming instrumentation file must statically import Sentry
27
+ * and inject `Sentry.init`; dash-site-kit never discovers SDKs dynamically.
28
+ */
29
+ export declare function initializeChannelSiteSentry(init: (options: ChannelSiteSentryOptions) => void, environment?: ChannelSiteSentryEnvironment): boolean;
30
+ /** Preserve the SDK handler's arguments and return type. */
31
+ export declare function createChannelSiteRequestErrorHandler<TArgs extends unknown[], TResult>(captureRequestError: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
@@ -0,0 +1,54 @@
1
+ import "server-only";
2
+ import { ChannelSiteSentryConfigurationError, resolveChannelSiteSentryOptions as resolveOptions, } from "../sentry.js";
3
+ /** The narrow Sentry configuration surface owned by dash-site-kit. */
4
+ export { ChannelSiteSentryConfigurationError };
5
+ function siteFromProductionUrl(value) {
6
+ const candidate = value?.trim();
7
+ if (!candidate)
8
+ return "";
9
+ try {
10
+ const url = new URL(candidate.includes("://") ? candidate : `https://${candidate}`);
11
+ return url.hostname.toLowerCase().replace(/\.$/, "");
12
+ }
13
+ catch {
14
+ return "";
15
+ }
16
+ }
17
+ /**
18
+ * Resolve the common Sentry options for a channel site.
19
+ *
20
+ * An absent DSN intentionally disables reporting. A present but malformed
21
+ * configuration fails fast so a deployment cannot claim error reporting while
22
+ * silently sending nothing.
23
+ */
24
+ export function resolveChannelSiteSentryOptions(environment = process.env) {
25
+ const rawDsn = environment.CHANNEL_SITE_SENTRY_DSN?.trim();
26
+ if (!rawDsn)
27
+ return null;
28
+ return resolveOptions({
29
+ channelId: environment.CHANNEL_SITE_CHANNEL_ID,
30
+ dsn: rawDsn,
31
+ environment: environment.SENTRY_ENVIRONMENT || environment.VERCEL_ENV,
32
+ site: environment.CHANNEL_SITE_NAME?.trim() ||
33
+ siteFromProductionUrl(environment.VERCEL_PROJECT_PRODUCTION_URL),
34
+ });
35
+ }
36
+ /**
37
+ * Initialise an app-owned Sentry SDK with shared, validated channel-site
38
+ * options. The consuming instrumentation file must statically import Sentry
39
+ * and inject `Sentry.init`; dash-site-kit never discovers SDKs dynamically.
40
+ */
41
+ export function initializeChannelSiteSentry(init, environment = process.env) {
42
+ if (environment.NEXT_RUNTIME !== "nodejs" && environment.NEXT_RUNTIME !== "edge") {
43
+ return false;
44
+ }
45
+ const options = resolveChannelSiteSentryOptions(environment);
46
+ if (!options)
47
+ return false;
48
+ init(options);
49
+ return true;
50
+ }
51
+ /** Preserve the SDK handler's arguments and return type. */
52
+ export function createChannelSiteRequestErrorHandler(captureRequestError) {
53
+ return (...args) => captureRequestError(...args);
54
+ }
package/dist/next.d.ts CHANGED
@@ -14,6 +14,8 @@ 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
16
  export { observeChannelRequest } from "./next/observability.js";
17
+ export { ChannelSiteSentryConfigurationError, createChannelSiteRequestErrorHandler, initializeChannelSiteSentry, resolveChannelSiteSentryOptions, } from "./next/sentry.js";
18
+ export type { ChannelSiteSentryEnvironment, ChannelSiteSentryOptions, } from "./next/sentry.js";
17
19
  export { resolveC1MAsset } from "./next/assets.js";
18
20
  export { createC1MBootstrapProvider } from "./next/providers/bootstrap.js";
19
21
  export { createC1MDirectoryProvider } from "./next/providers/directory.js";
package/dist/next.js CHANGED
@@ -12,6 +12,7 @@ export { ChannelConfigurationError, resolveChannelEnvironment } from "./next/env
12
12
  export { CHANNEL_SITE_CACHE_TAG } from "./next/cache.js";
13
13
  export { getChannelAttestation } from "./next/delivery.js";
14
14
  export { observeChannelRequest } from "./next/observability.js";
15
+ export { ChannelSiteSentryConfigurationError, createChannelSiteRequestErrorHandler, initializeChannelSiteSentry, resolveChannelSiteSentryOptions, } from "./next/sentry.js";
15
16
  export { resolveC1MAsset } from "./next/assets.js";
16
17
  export { createC1MBootstrapProvider } from "./next/providers/bootstrap.js";
17
18
  export { createC1MDirectoryProvider } from "./next/providers/directory.js";
@@ -0,0 +1,27 @@
1
+ export interface ChannelSiteSentryConfiguration {
2
+ channelId?: string;
3
+ dsn?: string;
4
+ environment?: string;
5
+ release?: string;
6
+ site: string;
7
+ }
8
+ export interface ChannelSiteSentryOptions {
9
+ dsn: string;
10
+ enableLogs: false;
11
+ environment?: string;
12
+ initialScope: {
13
+ tags: {
14
+ channel_id?: string;
15
+ site: string;
16
+ site_kind: "dash-site";
17
+ };
18
+ };
19
+ release?: string;
20
+ sendDefaultPii: false;
21
+ tracesSampleRate: 0;
22
+ }
23
+ export declare class ChannelSiteSentryConfigurationError extends Error {
24
+ readonly code: "invalid_dsn" | "missing_site";
25
+ constructor(code: ChannelSiteSentryConfigurationError["code"], message: string);
26
+ }
27
+ export declare function resolveChannelSiteSentryOptions(configuration: ChannelSiteSentryConfiguration): ChannelSiteSentryOptions | null;
package/dist/sentry.js ADDED
@@ -0,0 +1,52 @@
1
+ export class ChannelSiteSentryConfigurationError extends Error {
2
+ code;
3
+ constructor(code, message) {
4
+ super(message);
5
+ this.name = "ChannelSiteSentryConfigurationError";
6
+ this.code = code;
7
+ }
8
+ }
9
+ function validateDsn(value) {
10
+ let dsn;
11
+ try {
12
+ dsn = new URL(value);
13
+ }
14
+ catch {
15
+ throw new ChannelSiteSentryConfigurationError("invalid_dsn", "Channel-site Sentry DSN must be a valid URL");
16
+ }
17
+ const projectId = dsn.pathname.split("/").filter(Boolean).at(-1);
18
+ if ((dsn.protocol !== "https:" && dsn.protocol !== "http:") ||
19
+ !dsn.hostname ||
20
+ !dsn.username ||
21
+ !projectId) {
22
+ throw new ChannelSiteSentryConfigurationError("invalid_dsn", "Channel-site Sentry DSN must include a protocol, public key, host, and project ID");
23
+ }
24
+ return value;
25
+ }
26
+ export function resolveChannelSiteSentryOptions(configuration) {
27
+ const dsn = configuration.dsn?.trim();
28
+ if (!dsn)
29
+ return null;
30
+ const site = configuration.site.trim();
31
+ if (!site) {
32
+ throw new ChannelSiteSentryConfigurationError("missing_site", "A site identifier is required when channel-site Sentry is configured");
33
+ }
34
+ const channelId = configuration.channelId?.trim();
35
+ const environment = configuration.environment?.trim();
36
+ const release = configuration.release?.trim();
37
+ return {
38
+ dsn: validateDsn(dsn),
39
+ enableLogs: false,
40
+ ...(environment ? { environment } : {}),
41
+ initialScope: {
42
+ tags: {
43
+ site,
44
+ site_kind: "dash-site",
45
+ ...(channelId ? { channel_id: channelId } : {}),
46
+ },
47
+ },
48
+ ...(release ? { release } : {}),
49
+ sendDefaultPii: false,
50
+ tracesSampleRate: 0,
51
+ };
52
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@c1m-public/dash-site-kit",
3
- "version": "0.2.1",
3
+ "version": "0.4.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,15 @@
54
54
  "typescript": "5.9.3",
55
55
  "vitest": "^4.1.4",
56
56
  "@types/node": "^22",
57
- "@c1m-public/channel-client": "0.19.0"
57
+ "@c1m-public/channel-client": "0.21.0"
58
+ },
59
+ "peerDependenciesMeta": {
60
+ "next": {
61
+ "optional": true
62
+ },
63
+ "react": {
64
+ "optional": true
65
+ }
58
66
  },
59
67
  "scripts": {
60
68
  "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",