@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 +68 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/next/env.d.ts +2 -4
- package/dist/next/env.js +2 -6
- package/dist/next/sentry.d.ts +31 -0
- package/dist/next/sentry.js +54 -0
- package/dist/next.d.ts +2 -0
- package/dist/next.js +1 -0
- package/dist/sentry.d.ts +27 -0
- package/dist/sentry.js +52 -0
- package/package.json +10 -2
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";
|
package/dist/next/env.d.ts
CHANGED
|
@@ -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
|
-
|
|
3
|
-
|
|
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";
|
package/dist/sentry.d.ts
ADDED
|
@@ -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.
|
|
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.
|
|
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})\"",
|