@graphql-markdown/telemetry 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +118 -2
- package/dist/ci.d.ts +7 -0
- package/dist/ci.d.ts.map +1 -0
- package/dist/ci.js +43 -0
- package/dist/config-dir.d.ts +9 -0
- package/dist/config-dir.d.ts.map +1 -0
- package/dist/config-dir.js +29 -0
- package/dist/constants.d.ts +15 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +17 -0
- package/dist/disclaimer.d.ts +17 -0
- package/dist/disclaimer.d.ts.map +1 -0
- package/dist/disclaimer.js +49 -0
- package/dist/enabled.d.ts +23 -0
- package/dist/enabled.d.ts.map +1 -0
- package/dist/enabled.js +48 -0
- package/dist/error-type.d.ts +13 -0
- package/dist/error-type.d.ts.map +1 -0
- package/dist/error-type.js +47 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +39 -0
- package/dist/loader.d.ts +6 -0
- package/dist/loader.d.ts.map +1 -0
- package/dist/loader.js +79 -0
- package/dist/payload.d.ts +25 -0
- package/dist/payload.d.ts.map +1 -0
- package/dist/payload.js +133 -0
- package/dist/sanitize.d.ts +229 -0
- package/dist/sanitize.d.ts.map +1 -0
- package/dist/sanitize.js +260 -0
- package/dist/schema.d.ts +36 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +122 -0
- package/dist/state.d.ts +22 -0
- package/dist/state.d.ts.map +1 -0
- package/dist/state.js +77 -0
- package/dist/track.d.ts +19 -0
- package/dist/track.d.ts.map +1 -0
- package/dist/track.js +83 -0
- package/package.json +87 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2020 Grégory Heitz
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,119 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @graphql-markdown/telemetry
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Anonymous, opt-out usage telemetry for GraphQL-Markdown. Internal package: it is used by the CLI, the Docusaurus plugin and the Nuxt theme, not meant to be called directly.
|
|
4
|
+
|
|
5
|
+
- No runtime dependencies.
|
|
6
|
+
- Sends one event per distinct configuration; values are masked (URLs, paths and custom strings never leave the machine) and schema content is never read.
|
|
7
|
+
- No identifier of any kind is stored or sent.
|
|
8
|
+
- Opt out with `DO_NOT_TRACK=1`, `GRAPHQL_MARKDOWN_TELEMETRY_DISABLED=1`, `telemetry: false` or `--no-telemetry`.
|
|
9
|
+
- Disabled automatically in test runners (`VITEST`, `JEST_WORKER_ID`, `NODE_TEST_CONTEXT`, `NODE_ENV=test`).
|
|
10
|
+
- Events are sent to the Cloudflare Worker ingest (`gqlmd-telemetry.graphql-markdown.workers.dev`, see github.com/graphql-markdown/telemetry); set `GRAPHQL_MARKDOWN_TELEMETRY_ENDPOINT` to override it.
|
|
11
|
+
- `GRAPHQL_MARKDOWN_TELEMETRY_DEBUG=1` prints the exact payload to stderr instead of sending it.
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { track } from "@graphql-markdown/telemetry";
|
|
17
|
+
|
|
18
|
+
// never throws, never blocks on failure
|
|
19
|
+
void track({
|
|
20
|
+
trigger: "cli",
|
|
21
|
+
pkg: "@graphql-markdown/cli",
|
|
22
|
+
pkgVersion,
|
|
23
|
+
graphqlMajor,
|
|
24
|
+
config,
|
|
25
|
+
cli,
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
State (consent notice version and fingerprints of already-sent configs) is kept in `telemetry.json` in the OS config directory.
|
|
30
|
+
|
|
31
|
+
The `@graphql-markdown/telemetry/schema` subpath exports the payload allowlist (enums and mask tokens) as plain data.
|
|
32
|
+
|
|
33
|
+
## Payload example
|
|
34
|
+
|
|
35
|
+
Your configuration is never sent as-is. Each value is replaced by a mask token. The example below was generated from the real payload builder with the configuration shown.
|
|
36
|
+
|
|
37
|
+
Your config:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"schema": "https://api.acme.internal/graphql",
|
|
42
|
+
"rootPath": "./docs",
|
|
43
|
+
"baseURL": "/api",
|
|
44
|
+
"linkRoot": "/docs",
|
|
45
|
+
"homepage": "./intro.md",
|
|
46
|
+
"formatter": "@graphql-markdown/docusaurus",
|
|
47
|
+
"skipDocDirective": ["@internal"],
|
|
48
|
+
"groupByDirective": { "directive": "doc", "field": "category", "fallback": "Common" },
|
|
49
|
+
"printTypeOptions": { "deprecated": "group", "typeBadges": true },
|
|
50
|
+
"metatags": [{ "name": "robots", "content": "noindex" }],
|
|
51
|
+
"loaders": { "UrlLoader": "@graphql-tools/url-loader" }
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
What is sent (CLI options `{ "force": true }`, trigger `cli`, GraphQL 16):
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"v": 1,
|
|
60
|
+
"event": "config",
|
|
61
|
+
"pkg": "@graphql-markdown/cli",
|
|
62
|
+
"pkgVersion": "0.1.0",
|
|
63
|
+
"nodeMajor": 24,
|
|
64
|
+
"graphqlMajor": 16,
|
|
65
|
+
"os": "darwin",
|
|
66
|
+
"ci": false,
|
|
67
|
+
"pm": "unknown",
|
|
68
|
+
"firstRun": false,
|
|
69
|
+
"trigger": "cli",
|
|
70
|
+
"container": false,
|
|
71
|
+
"wsl": false,
|
|
72
|
+
"config": {
|
|
73
|
+
"schema": "<url>",
|
|
74
|
+
"rootPath": "<path>",
|
|
75
|
+
"baseURL": "<url>",
|
|
76
|
+
"linkRoot": "<path>",
|
|
77
|
+
"homepage": "<path>",
|
|
78
|
+
"formatter": "@graphql-markdown/docusaurus",
|
|
79
|
+
"skipDocDirective": [
|
|
80
|
+
"<string>"
|
|
81
|
+
],
|
|
82
|
+
"groupByDirective": {
|
|
83
|
+
"directive": "<string>",
|
|
84
|
+
"field": "<string>",
|
|
85
|
+
"fallback": "<string>"
|
|
86
|
+
},
|
|
87
|
+
"printTypeOptions": {
|
|
88
|
+
"deprecated": "group",
|
|
89
|
+
"typeBadges": true
|
|
90
|
+
},
|
|
91
|
+
"metatags": [
|
|
92
|
+
{
|
|
93
|
+
"<key:0>": "<string>",
|
|
94
|
+
"<key:1>": "<string>"
|
|
95
|
+
}
|
|
96
|
+
],
|
|
97
|
+
"loaders": {
|
|
98
|
+
"UrlLoader": "@graphql-tools/url-loader"
|
|
99
|
+
}
|
|
100
|
+
},
|
|
101
|
+
"loader": "url",
|
|
102
|
+
"cli": {
|
|
103
|
+
"force": true
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Masking rules:
|
|
109
|
+
|
|
110
|
+
- `<url>`, `<git>`, `<github>`: the kind of a schema pointer, or a URL value (for example `baseURL`). The host, path and any headers are never sent.
|
|
111
|
+
- `<file:sdl>`, `<file:json>`, `<file:code>`, `<glob>`, `<inline-sdl>`, `<unknown>`: the kind of a schema pointer (for example `schema`). The pointer itself is never sent.
|
|
112
|
+
- `<custom-formatter>`: a third-party or local `formatter` or `mdxParser`. Only presets and `@graphql-markdown/*` packages are kept as-is.
|
|
113
|
+
- `<path>`: a filesystem path (for example `rootPath`, `linkRoot`, `homepage`).
|
|
114
|
+
- `<string>`: a custom string (for example directive names, field names, fallback labels, metatag values).
|
|
115
|
+
- `<key:n>`: a custom object key, replaced by its position (for example metatag names). Only present when a custom key is used.
|
|
116
|
+
|
|
117
|
+
No identifier, IP address, schema content or path is ever included. Names from the allowlist (such as the formatter and loader names, or boolean and enum options) are kept as-is.
|
|
118
|
+
|
|
119
|
+
To print your own payload instead of sending it, set `GRAPHQL_MARKDOWN_TELEMETRY_DEBUG=1`. The exact payload is written to stderr.
|
package/dist/ci.d.ts
ADDED
package/dist/ci.d.ts.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ci.d.ts","sourceRoot":"","sources":["../src/ci.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAwB1D,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,eAAO,MAAM,QAAQ,SAAS,MAAM,CAAC,UAAU,KAAiB,MAqB/D,CAAC"}
|
package/dist/ci.js
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.detectCi = void 0;
|
|
4
|
+
/** Vendor table modelled on `ci-info`: env var presence only, never values. */
|
|
5
|
+
const VENDORS = [
|
|
6
|
+
["github-actions", ["GITHUB_ACTIONS"]],
|
|
7
|
+
["gitlab", ["GITLAB_CI"]],
|
|
8
|
+
["circleci", ["CIRCLECI"]],
|
|
9
|
+
["azure-pipelines", ["TF_BUILD"]],
|
|
10
|
+
// BUILD_ID alone is too generic (set by unrelated tooling); ci-info also
|
|
11
|
+
// requires JENKINS_URL, which Jenkins always sets.
|
|
12
|
+
["jenkins", ["JENKINS_URL"]],
|
|
13
|
+
["bitbucket", ["BITBUCKET_COMMIT"]],
|
|
14
|
+
["buildkite", ["BUILDKITE"]],
|
|
15
|
+
["travis", ["TRAVIS"]],
|
|
16
|
+
["vercel", ["NOW_BUILDER", "VERCEL"]],
|
|
17
|
+
["netlify", ["NETLIFY"]],
|
|
18
|
+
["cloudflare-pages", ["CF_PAGES"]],
|
|
19
|
+
["aws-codebuild", ["CODEBUILD_BUILD_ARN"]],
|
|
20
|
+
["teamcity", ["TEAMCITY_VERSION"]],
|
|
21
|
+
["appveyor", ["APPVEYOR"]],
|
|
22
|
+
["drone", ["DRONE"]],
|
|
23
|
+
["render", ["RENDER"]],
|
|
24
|
+
];
|
|
25
|
+
const detectCi = (env = process.env) => {
|
|
26
|
+
if (env.CI === "false" || env.CI === "0") {
|
|
27
|
+
return { ci: false };
|
|
28
|
+
}
|
|
29
|
+
for (const [provider, vars] of VENDORS) {
|
|
30
|
+
if (vars.some((name) => {
|
|
31
|
+
return env[name] !== undefined;
|
|
32
|
+
})) {
|
|
33
|
+
return { ci: true, ciProvider: provider };
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
if (env.CI !== undefined ||
|
|
37
|
+
env.CONTINUOUS_INTEGRATION !== undefined ||
|
|
38
|
+
env.BUILD_NUMBER !== undefined) {
|
|
39
|
+
return { ci: true, ciProvider: "other" };
|
|
40
|
+
}
|
|
41
|
+
return { ci: false };
|
|
42
|
+
};
|
|
43
|
+
exports.detectCi = detectCi;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolves the OS config directory, like `env-paths` without the dependency.
|
|
3
|
+
*
|
|
4
|
+
* @param platform - Node platform, defaults to `process.platform`.
|
|
5
|
+
* @param env - Environment variables, defaults to `process.env`.
|
|
6
|
+
* @param home - Home directory, defaults to `os.homedir()`.
|
|
7
|
+
*/
|
|
8
|
+
export declare const resolveConfigDir: (platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string) => string;
|
|
9
|
+
//# sourceMappingURL=config-dir.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config-dir.d.ts","sourceRoot":"","sources":["../src/config-dir.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,cACjB,MAAM,CAAC,QAAQ,QACpB,MAAM,CAAC,UAAU,SAChB,MAAM,KACX,MAUF,CAAC"}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.resolveConfigDir = void 0;
|
|
4
|
+
const node_os_1 = require("node:os");
|
|
5
|
+
const node_path_1 = require("node:path");
|
|
6
|
+
const nonEmpty = (value) => {
|
|
7
|
+
return value === undefined || value === "" ? undefined : value;
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* Resolves the OS config directory, like `env-paths` without the dependency.
|
|
11
|
+
*
|
|
12
|
+
* @param platform - Node platform, defaults to `process.platform`.
|
|
13
|
+
* @param env - Environment variables, defaults to `process.env`.
|
|
14
|
+
* @param home - Home directory, defaults to `os.homedir()`.
|
|
15
|
+
*/
|
|
16
|
+
const resolveConfigDir = (platform = process.platform, env = process.env, home = (0, node_os_1.homedir)()) => {
|
|
17
|
+
let base;
|
|
18
|
+
if (platform === "win32") {
|
|
19
|
+
base = nonEmpty(env.APPDATA) ?? (0, node_path_1.join)(home, "AppData", "Roaming");
|
|
20
|
+
}
|
|
21
|
+
else if (platform === "darwin") {
|
|
22
|
+
base = (0, node_path_1.join)(home, "Library", "Preferences");
|
|
23
|
+
}
|
|
24
|
+
else {
|
|
25
|
+
base = nonEmpty(env.XDG_CONFIG_HOME) ?? (0, node_path_1.join)(home, ".config");
|
|
26
|
+
}
|
|
27
|
+
return (0, node_path_1.join)(base, "graphql-markdown");
|
|
28
|
+
};
|
|
29
|
+
exports.resolveConfigDir = resolveConfigDir;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/** Current consent notice version; bump when a new category of data is added. */
|
|
2
|
+
export declare const NOTICE_VERSION = 1;
|
|
3
|
+
/**
|
|
4
|
+
* Telemetry endpoint: the Cloudflare Worker ingest (workers.dev, see
|
|
5
|
+
* github.com/graphql-markdown/telemetry). Overridable with
|
|
6
|
+
* `GRAPHQL_MARKDOWN_TELEMETRY_ENDPOINT`.
|
|
7
|
+
*/
|
|
8
|
+
export declare const DEFAULT_ENDPOINT = "https://gqlmd-telemetry.graphql-markdown.workers.dev/v1/event";
|
|
9
|
+
/** Number of config fingerprints kept in `telemetry.json`. */
|
|
10
|
+
export declare const MAX_SENT_CONFIGS = 20;
|
|
11
|
+
/** Body size (bytes) above which the request is gzipped. */
|
|
12
|
+
export declare const GZIP_THRESHOLD = 1024;
|
|
13
|
+
/** Request timeout in milliseconds. */
|
|
14
|
+
export declare const TIMEOUT_MS = 1000;
|
|
15
|
+
//# sourceMappingURL=constants.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,kEACoC,CAAC;AAElE,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,4DAA4D;AAC5D,eAAO,MAAM,cAAc,OAAO,CAAC;AAEnC,uCAAuC;AACvC,eAAO,MAAM,UAAU,OAAO,CAAC"}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.TIMEOUT_MS = exports.GZIP_THRESHOLD = exports.MAX_SENT_CONFIGS = exports.DEFAULT_ENDPOINT = exports.NOTICE_VERSION = void 0;
|
|
4
|
+
/** Current consent notice version; bump when a new category of data is added. */
|
|
5
|
+
exports.NOTICE_VERSION = 1;
|
|
6
|
+
/**
|
|
7
|
+
* Telemetry endpoint: the Cloudflare Worker ingest (workers.dev, see
|
|
8
|
+
* github.com/graphql-markdown/telemetry). Overridable with
|
|
9
|
+
* `GRAPHQL_MARKDOWN_TELEMETRY_ENDPOINT`.
|
|
10
|
+
*/
|
|
11
|
+
exports.DEFAULT_ENDPOINT = "https://gqlmd-telemetry.graphql-markdown.workers.dev/v1/event";
|
|
12
|
+
/** Number of config fingerprints kept in `telemetry.json`. */
|
|
13
|
+
exports.MAX_SENT_CONFIGS = 20;
|
|
14
|
+
/** Body size (bytes) above which the request is gzipped. */
|
|
15
|
+
exports.GZIP_THRESHOLD = 1024;
|
|
16
|
+
/** Request timeout in milliseconds. */
|
|
17
|
+
exports.TIMEOUT_MS = 1000;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { CiInfo } from "./ci";
|
|
2
|
+
import type { TelemetryState } from "./state";
|
|
3
|
+
export declare const FULL_NOTICE = "\u2139 GraphQL-Markdown collects anonymous usage data to help improve the tool.\n Sent: package/Node versions, OS, schema loader type, the settings you use,\n and the page count, duration and error type of each run.\n Custom strings, URLs and paths are masked; schema content is never sent.\n Details: https://graphql-markdown.dev/docs/telemetry\n Opt out: `gqlmd telemetry disable` or DO_NOT_TRACK=1\n";
|
|
4
|
+
/** Whether the full notice is due (never in CI, where it is not recorded). */
|
|
5
|
+
export declare const isNoticeDue: (state: TelemetryState | null | undefined, ci?: CiInfo) => boolean;
|
|
6
|
+
/** Resets the once-per-process guard. @internal */
|
|
7
|
+
export declare const resetDisclaimer: () => void;
|
|
8
|
+
/**
|
|
9
|
+
* Writes the notice straight to stderr, bypassing the logger, at most once per process.
|
|
10
|
+
*
|
|
11
|
+
* When `onFullNotice` is given, the full notice is passed to it instead.
|
|
12
|
+
*
|
|
13
|
+
* @returns `true` when the full notice is due, shown now or earlier in this
|
|
14
|
+
* process (it must then be recorded before anything is sent).
|
|
15
|
+
*/
|
|
16
|
+
export declare const printDisclaimer: (state: TelemetryState | null | undefined, ci: CiInfo, onFullNotice?: (notice: string) => void) => boolean;
|
|
17
|
+
//# sourceMappingURL=disclaimer.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"disclaimer.d.ts","sourceRoot":"","sources":["../src/disclaimer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,WAAW,4ZAMvB,CAAC;AAKF,8EAA8E;AAC9E,eAAO,MAAM,WAAW,UACf,cAAc,GAAG,IAAI,GAAG,SAAS,OACpC,MAAM,KACT,OAEF,CAAC;AAIF,mDAAmD;AACnD,eAAO,MAAM,eAAe,QAAO,IAElC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,UACnB,cAAc,GAAG,IAAI,GAAG,SAAS,MACpC,MAAM,iBACK,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,KACtC,OAeF,CAAC"}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.printDisclaimer = exports.resetDisclaimer = exports.isNoticeDue = exports.FULL_NOTICE = void 0;
|
|
4
|
+
const constants_1 = require("./constants");
|
|
5
|
+
exports.FULL_NOTICE = `ℹ GraphQL-Markdown collects anonymous usage data to help improve the tool.
|
|
6
|
+
Sent: package/Node versions, OS, schema loader type, the settings you use,
|
|
7
|
+
and the page count, duration and error type of each run.
|
|
8
|
+
Custom strings, URLs and paths are masked; schema content is never sent.
|
|
9
|
+
Details: https://graphql-markdown.dev/docs/telemetry
|
|
10
|
+
Opt out: \`gqlmd telemetry disable\` or DO_NOT_TRACK=1
|
|
11
|
+
`;
|
|
12
|
+
const SHORT_NOTICE = "ℹ Anonymous telemetry enabled. Opt out: gqlmd telemetry disable\n";
|
|
13
|
+
/** Whether the full notice is due (never in CI, where it is not recorded). */
|
|
14
|
+
const isNoticeDue = (state, ci = { ci: false }) => {
|
|
15
|
+
return !ci.ci && (!state || state.noticeVersion < constants_1.NOTICE_VERSION);
|
|
16
|
+
};
|
|
17
|
+
exports.isNoticeDue = isNoticeDue;
|
|
18
|
+
let printed = false;
|
|
19
|
+
/** Resets the once-per-process guard. @internal */
|
|
20
|
+
const resetDisclaimer = () => {
|
|
21
|
+
printed = false;
|
|
22
|
+
};
|
|
23
|
+
exports.resetDisclaimer = resetDisclaimer;
|
|
24
|
+
/**
|
|
25
|
+
* Writes the notice straight to stderr, bypassing the logger, at most once per process.
|
|
26
|
+
*
|
|
27
|
+
* When `onFullNotice` is given, the full notice is passed to it instead.
|
|
28
|
+
*
|
|
29
|
+
* @returns `true` when the full notice is due, shown now or earlier in this
|
|
30
|
+
* process (it must then be recorded before anything is sent).
|
|
31
|
+
*/
|
|
32
|
+
const printDisclaimer = (state, ci, onFullNotice) => {
|
|
33
|
+
// In CI the full notice is never recorded: print the reminder every run.
|
|
34
|
+
const full = (0, exports.isNoticeDue)(state, ci);
|
|
35
|
+
if (printed) {
|
|
36
|
+
// still due when an earlier event could not record it
|
|
37
|
+
return full;
|
|
38
|
+
}
|
|
39
|
+
if (onFullNotice && full) {
|
|
40
|
+
onFullNotice(exports.FULL_NOTICE);
|
|
41
|
+
}
|
|
42
|
+
else {
|
|
43
|
+
process.stderr.write(full ? exports.FULL_NOTICE : SHORT_NOTICE);
|
|
44
|
+
}
|
|
45
|
+
// Only once shown: a failed output must not let a later event skip it.
|
|
46
|
+
printed = true;
|
|
47
|
+
return full;
|
|
48
|
+
};
|
|
49
|
+
exports.printDisclaimer = printDisclaimer;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { TelemetryTrigger } from "@graphql-markdown/types";
|
|
2
|
+
import type { TelemetryState } from "./state";
|
|
3
|
+
export interface EnabledContext {
|
|
4
|
+
/** Entry point; without it only `telemetry: true` enables (programmatic). */
|
|
5
|
+
trigger?: TelemetryTrigger;
|
|
6
|
+
/** Value of the `telemetry` option (config, programmatic or CLI). */
|
|
7
|
+
option?: boolean;
|
|
8
|
+
/** State file content; `null` means corrupt, `undefined` means absent. */
|
|
9
|
+
state?: TelemetryState | null;
|
|
10
|
+
env?: NodeJS.ProcessEnv;
|
|
11
|
+
}
|
|
12
|
+
export declare const getEndpoint: (env?: NodeJS.ProcessEnv) => string;
|
|
13
|
+
/**
|
|
14
|
+
* Resolves whether telemetry is enabled and with which trigger.
|
|
15
|
+
* User-level and environment signals always beat project config.
|
|
16
|
+
*/
|
|
17
|
+
export declare const isEnabled: (ctx?: EnabledContext) => {
|
|
18
|
+
enabled: false;
|
|
19
|
+
} | {
|
|
20
|
+
enabled: true;
|
|
21
|
+
trigger: TelemetryTrigger;
|
|
22
|
+
};
|
|
23
|
+
//# sourceMappingURL=enabled.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"enabled.d.ts","sourceRoot":"","sources":["../src/enabled.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,qEAAqE;IACrE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,eAAO,MAAM,WAAW,SAAS,MAAM,CAAC,UAAU,KAAiB,MAElE,CAAC;AAQF;;;GAGG;AACH,eAAO,MAAM,SAAS,SACf,cAAc,KAClB;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAmCjE,CAAC"}
|
package/dist/enabled.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.isEnabled = exports.getEndpoint = void 0;
|
|
4
|
+
const constants_1 = require("./constants");
|
|
5
|
+
const getEndpoint = (env = process.env) => {
|
|
6
|
+
return env.GRAPHQL_MARKDOWN_TELEMETRY_ENDPOINT ?? constants_1.DEFAULT_ENDPOINT;
|
|
7
|
+
};
|
|
8
|
+
exports.getEndpoint = getEndpoint;
|
|
9
|
+
const isSet = (value) => {
|
|
10
|
+
return (value !== undefined && value !== "" && value !== "0" && value !== "false");
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Resolves whether telemetry is enabled and with which trigger.
|
|
14
|
+
* User-level and environment signals always beat project config.
|
|
15
|
+
*/
|
|
16
|
+
const isEnabled = (ctx = {}) => {
|
|
17
|
+
const env = ctx.env ?? process.env;
|
|
18
|
+
if (isSet(env.DO_NOT_TRACK) ||
|
|
19
|
+
isSet(env.GRAPHQL_MARKDOWN_TELEMETRY_DISABLED)) {
|
|
20
|
+
return { enabled: false };
|
|
21
|
+
}
|
|
22
|
+
if (ctx.state === null) {
|
|
23
|
+
return { enabled: false };
|
|
24
|
+
}
|
|
25
|
+
if (ctx.state && (!ctx.state.enabled || ctx.state.reason === "sunset")) {
|
|
26
|
+
return { enabled: false };
|
|
27
|
+
}
|
|
28
|
+
if (env.VITEST !== undefined ||
|
|
29
|
+
env.JEST_WORKER_ID !== undefined ||
|
|
30
|
+
env.NODE_TEST_CONTEXT !== undefined ||
|
|
31
|
+
env.NODE_ENV === "test") {
|
|
32
|
+
return { enabled: false };
|
|
33
|
+
}
|
|
34
|
+
if (ctx.option === false) {
|
|
35
|
+
return { enabled: false };
|
|
36
|
+
}
|
|
37
|
+
if (!(0, exports.getEndpoint)(env) && !isSet(env.GRAPHQL_MARKDOWN_TELEMETRY_DEBUG)) {
|
|
38
|
+
return { enabled: false };
|
|
39
|
+
}
|
|
40
|
+
if (ctx.trigger) {
|
|
41
|
+
return { enabled: true, trigger: ctx.trigger };
|
|
42
|
+
}
|
|
43
|
+
if (ctx.option === true) {
|
|
44
|
+
return { enabled: true, trigger: "programmatic" };
|
|
45
|
+
}
|
|
46
|
+
return { enabled: false };
|
|
47
|
+
};
|
|
48
|
+
exports.isEnabled = isEnabled;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** Error class names that may be reported as-is. */
|
|
2
|
+
export declare const ERROR_TYPES: readonly ["Error", "TypeError", "RangeError", "SyntaxError", "ReferenceError", "GraphQLError", "AggregateError", "AbortError", "SystemError"];
|
|
3
|
+
/** Reported when no schema could be loaded. */
|
|
4
|
+
export declare const NO_SCHEMA_ERROR = "<no-schema>";
|
|
5
|
+
/** Prefix for failures happening after generation (post-generation hooks). */
|
|
6
|
+
export declare const POST_ERROR_PREFIX = "post:";
|
|
7
|
+
/**
|
|
8
|
+
* Maps any thrown value to an anonymous error type: an allowlisted class
|
|
9
|
+
* name (optionally suffixed with a system code), or `<custom-error>`.
|
|
10
|
+
* Never throws.
|
|
11
|
+
*/
|
|
12
|
+
export declare const errorTypeOf: (error: unknown) => string;
|
|
13
|
+
//# sourceMappingURL=error-type.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"error-type.d.ts","sourceRoot":"","sources":["../src/error-type.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,eAAO,MAAM,WAAW,YACtB,OAAO,EACP,WAAW,EACX,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,CACL,CAAC;AAEX,+CAA+C;AAC/C,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAMzC;;;;GAIG;AACH,eAAO,MAAM,WAAW,UAAW,OAAO,KAAG,MAkB5C,CAAC"}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.errorTypeOf = exports.POST_ERROR_PREFIX = exports.NO_SCHEMA_ERROR = exports.ERROR_TYPES = void 0;
|
|
4
|
+
/** Error class names that may be reported as-is. */
|
|
5
|
+
exports.ERROR_TYPES = [
|
|
6
|
+
"Error",
|
|
7
|
+
"TypeError",
|
|
8
|
+
"RangeError",
|
|
9
|
+
"SyntaxError",
|
|
10
|
+
"ReferenceError",
|
|
11
|
+
"GraphQLError",
|
|
12
|
+
"AggregateError",
|
|
13
|
+
"AbortError",
|
|
14
|
+
"SystemError",
|
|
15
|
+
];
|
|
16
|
+
/** Reported when no schema could be loaded. */
|
|
17
|
+
exports.NO_SCHEMA_ERROR = "<no-schema>";
|
|
18
|
+
/** Prefix for failures happening after generation (post-generation hooks). */
|
|
19
|
+
exports.POST_ERROR_PREFIX = "post:";
|
|
20
|
+
const CUSTOM_ERROR = "<custom-error>";
|
|
21
|
+
const ERROR_CODE = /^E[A-Z]+$/;
|
|
22
|
+
/**
|
|
23
|
+
* Maps any thrown value to an anonymous error type: an allowlisted class
|
|
24
|
+
* name (optionally suffixed with a system code), or `<custom-error>`.
|
|
25
|
+
* Never throws.
|
|
26
|
+
*/
|
|
27
|
+
const errorTypeOf = (error) => {
|
|
28
|
+
try {
|
|
29
|
+
if (typeof error !== "object" || error === null) {
|
|
30
|
+
return CUSTOM_ERROR;
|
|
31
|
+
}
|
|
32
|
+
const name = error.constructor
|
|
33
|
+
?.name;
|
|
34
|
+
const base = exports.ERROR_TYPES.includes(name)
|
|
35
|
+
? name
|
|
36
|
+
: CUSTOM_ERROR;
|
|
37
|
+
const code = error.code;
|
|
38
|
+
if (typeof code === "string" && ERROR_CODE.test(code)) {
|
|
39
|
+
return `${base}:${code}`;
|
|
40
|
+
}
|
|
41
|
+
return base;
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
return CUSTOM_ERROR;
|
|
45
|
+
}
|
|
46
|
+
};
|
|
47
|
+
exports.errorTypeOf = errorTypeOf;
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export { NOTICE_VERSION, DEFAULT_ENDPOINT } from "./constants";
|
|
2
|
+
export { resolveConfigDir } from "./config-dir";
|
|
3
|
+
export { readState, writeState, getStatePath } from "./state";
|
|
4
|
+
export type { TelemetryState } from "./state";
|
|
5
|
+
export { detectCi } from "./ci";
|
|
6
|
+
export type { CiInfo } from "./ci";
|
|
7
|
+
export { isEnabled, getEndpoint } from "./enabled";
|
|
8
|
+
export type { EnabledContext } from "./enabled";
|
|
9
|
+
export { classifyPointer } from "./loader";
|
|
10
|
+
export type { LoaderKind } from "./loader";
|
|
11
|
+
export { sanitizeConfig, CONFIG_RULES, CLI_RULES } from "./sanitize";
|
|
12
|
+
export type { Rule, SanitizeResult } from "./sanitize";
|
|
13
|
+
export { buildPayload, fingerprint } from "./payload";
|
|
14
|
+
export type { PayloadInput } from "./payload";
|
|
15
|
+
export { errorTypeOf, ERROR_TYPES, NO_SCHEMA_ERROR, POST_ERROR_PREFIX, } from "./error-type";
|
|
16
|
+
export { printDisclaimer, isNoticeDue, resetDisclaimer, FULL_NOTICE, } from "./disclaimer";
|
|
17
|
+
export { track, encodeBody } from "./track";
|
|
18
|
+
export type { TrackInput } from "./track";
|
|
19
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAChC,YAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACrE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACtD,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,WAAW,EACX,eAAe,EACf,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,WAAW,EACX,eAAe,EACf,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.encodeBody = exports.track = exports.FULL_NOTICE = exports.resetDisclaimer = exports.isNoticeDue = exports.printDisclaimer = exports.POST_ERROR_PREFIX = exports.NO_SCHEMA_ERROR = exports.ERROR_TYPES = exports.errorTypeOf = exports.fingerprint = exports.buildPayload = exports.CLI_RULES = exports.CONFIG_RULES = exports.sanitizeConfig = exports.classifyPointer = exports.getEndpoint = exports.isEnabled = exports.detectCi = exports.getStatePath = exports.writeState = exports.readState = exports.resolveConfigDir = exports.DEFAULT_ENDPOINT = exports.NOTICE_VERSION = void 0;
|
|
4
|
+
var constants_1 = require("./constants");
|
|
5
|
+
Object.defineProperty(exports, "NOTICE_VERSION", { enumerable: true, get: function () { return constants_1.NOTICE_VERSION; } });
|
|
6
|
+
Object.defineProperty(exports, "DEFAULT_ENDPOINT", { enumerable: true, get: function () { return constants_1.DEFAULT_ENDPOINT; } });
|
|
7
|
+
var config_dir_1 = require("./config-dir");
|
|
8
|
+
Object.defineProperty(exports, "resolveConfigDir", { enumerable: true, get: function () { return config_dir_1.resolveConfigDir; } });
|
|
9
|
+
var state_1 = require("./state");
|
|
10
|
+
Object.defineProperty(exports, "readState", { enumerable: true, get: function () { return state_1.readState; } });
|
|
11
|
+
Object.defineProperty(exports, "writeState", { enumerable: true, get: function () { return state_1.writeState; } });
|
|
12
|
+
Object.defineProperty(exports, "getStatePath", { enumerable: true, get: function () { return state_1.getStatePath; } });
|
|
13
|
+
var ci_1 = require("./ci");
|
|
14
|
+
Object.defineProperty(exports, "detectCi", { enumerable: true, get: function () { return ci_1.detectCi; } });
|
|
15
|
+
var enabled_1 = require("./enabled");
|
|
16
|
+
Object.defineProperty(exports, "isEnabled", { enumerable: true, get: function () { return enabled_1.isEnabled; } });
|
|
17
|
+
Object.defineProperty(exports, "getEndpoint", { enumerable: true, get: function () { return enabled_1.getEndpoint; } });
|
|
18
|
+
var loader_1 = require("./loader");
|
|
19
|
+
Object.defineProperty(exports, "classifyPointer", { enumerable: true, get: function () { return loader_1.classifyPointer; } });
|
|
20
|
+
var sanitize_1 = require("./sanitize");
|
|
21
|
+
Object.defineProperty(exports, "sanitizeConfig", { enumerable: true, get: function () { return sanitize_1.sanitizeConfig; } });
|
|
22
|
+
Object.defineProperty(exports, "CONFIG_RULES", { enumerable: true, get: function () { return sanitize_1.CONFIG_RULES; } });
|
|
23
|
+
Object.defineProperty(exports, "CLI_RULES", { enumerable: true, get: function () { return sanitize_1.CLI_RULES; } });
|
|
24
|
+
var payload_1 = require("./payload");
|
|
25
|
+
Object.defineProperty(exports, "buildPayload", { enumerable: true, get: function () { return payload_1.buildPayload; } });
|
|
26
|
+
Object.defineProperty(exports, "fingerprint", { enumerable: true, get: function () { return payload_1.fingerprint; } });
|
|
27
|
+
var error_type_1 = require("./error-type");
|
|
28
|
+
Object.defineProperty(exports, "errorTypeOf", { enumerable: true, get: function () { return error_type_1.errorTypeOf; } });
|
|
29
|
+
Object.defineProperty(exports, "ERROR_TYPES", { enumerable: true, get: function () { return error_type_1.ERROR_TYPES; } });
|
|
30
|
+
Object.defineProperty(exports, "NO_SCHEMA_ERROR", { enumerable: true, get: function () { return error_type_1.NO_SCHEMA_ERROR; } });
|
|
31
|
+
Object.defineProperty(exports, "POST_ERROR_PREFIX", { enumerable: true, get: function () { return error_type_1.POST_ERROR_PREFIX; } });
|
|
32
|
+
var disclaimer_1 = require("./disclaimer");
|
|
33
|
+
Object.defineProperty(exports, "printDisclaimer", { enumerable: true, get: function () { return disclaimer_1.printDisclaimer; } });
|
|
34
|
+
Object.defineProperty(exports, "isNoticeDue", { enumerable: true, get: function () { return disclaimer_1.isNoticeDue; } });
|
|
35
|
+
Object.defineProperty(exports, "resetDisclaimer", { enumerable: true, get: function () { return disclaimer_1.resetDisclaimer; } });
|
|
36
|
+
Object.defineProperty(exports, "FULL_NOTICE", { enumerable: true, get: function () { return disclaimer_1.FULL_NOTICE; } });
|
|
37
|
+
var track_1 = require("./track");
|
|
38
|
+
Object.defineProperty(exports, "track", { enumerable: true, get: function () { return track_1.track; } });
|
|
39
|
+
Object.defineProperty(exports, "encodeBody", { enumerable: true, get: function () { return track_1.encodeBody; } });
|
package/dist/loader.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export type LoaderKind = "code-file" | "file-json" | "file-sdl" | "git" | "github" | "glob" | "inline-sdl" | "unknown" | "url";
|
|
2
|
+
/** Classifies a schema pointer; the pointer itself is never returned. */
|
|
3
|
+
export declare const classifyPointer: (pointer: unknown) => LoaderKind | LoaderKind[];
|
|
4
|
+
/** Classifies a schema pointer into mask token(s) for the config slot. */
|
|
5
|
+
export declare const maskPointer: (pointer: unknown) => string[] | string;
|
|
6
|
+
//# sourceMappingURL=loader.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,WAAW,GACX,UAAU,GACV,KAAK,GACL,QAAQ,GACR,MAAM,GACN,YAAY,GACZ,SAAS,GACT,KAAK,CAAC;AA2DV,yEAAyE;AACzE,eAAO,MAAM,eAAe,YACjB,OAAO,KACf,UAAU,GAAG,UAAU,EAMzB,CAAC;AAcF,0EAA0E;AAC1E,eAAO,MAAM,WAAW,YAAa,OAAO,KAAG,MAAM,EAAE,GAAG,MAOzD,CAAC"}
|