@theholocron/holocron-plugin-checkly 0.0.0-stage → 5.0.0-alpha.140

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.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +89 -2
  3. package/dist/index.d.mts +64 -0
  4. package/dist/index.mjs +145 -0
  5. package/package.json +63 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Newton Koumantzelis
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,90 @@
1
- # Temporary Holding Version
1
+ <!-- editorconfig-checker-disable-file -->
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ # `@theholocron/holocron-plugin-checkly`
4
+
5
+ Checkly plugin for [Holocron](../cli). Implements the
6
+ `monitoring` capability against [Checkly's REST API](https://api.checklyhq.com/v1)
7
+ (API checks only — browser checks, heartbeats, and dashboards are out of
8
+ scope until a real consumer needs them), plus exports `verifyToken` +
9
+ `AUTH_HINT` for use by `holocron auth`.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pnpm add -D @theholocron/holocron-plugin-checkly@alpha
15
+ ```
16
+
17
+ ## Auth
18
+
19
+ Token resolution order (standard 4-step precedence, same pattern as
20
+ every other plugin):
21
+
22
+ 1. `--token <TOKEN>` flag on the holocron invocation
23
+ 2. `HOLOCRON_CHECKLY_TOKEN` env var (preferred — explicit intent)
24
+ 3. `CHECKLY_API_KEY` env var (Checkly-native)
25
+ 4. **Keyring** — `com.theholocron.cli` service, account `checkly`
26
+ 5. `AuthError` naming all four options + the bootstrap hint
27
+
28
+ Use a regular **User API key** (Account settings → API keys). Checkly's
29
+ account-scoped **Service API keys** survive personnel changes and carry
30
+ granular roles, but require the Starter tier or above — not available
31
+ on the free Hobby tier. Revisit if/when the account upgrades.
32
+
33
+ ```bash
34
+ holocron auth set checkly <TOKEN>
35
+ holocron auth check checkly # verify — hits GET /v1/accounts
36
+ ```
37
+
38
+ ## Config
39
+
40
+ `accountId` is required on every request (Checkly's `x-checkly-account`
41
+ header) — it is not a secret, the same status as Vercel's `teamId`.
42
+ `checks` is the list of API checks `holocron repo setup` ensures exist,
43
+ each matched and upserted by exact `name`. **`locations` is required** —
44
+ Checkly rejects a check with neither `locations` nor `privateLocations`
45
+ set (`400 "You have to set at least one location or privateLocation"`)
46
+ on any account with no account-level default configured, which includes
47
+ every free Hobby/trial account. **`shouldFail` is required whenever the
48
+ check's healthy response is itself an HTTP error status** — Checkly
49
+ classifies any response >= 400 as a platform-level failure before
50
+ assertions are evaluated at all; a custom assertion that matches the
51
+ "expected" error status does not override that on its own:
52
+
53
+ ```ts
54
+ monitoring: [
55
+ "checkly",
56
+ {
57
+ accountId: "<your Checkly account id>",
58
+ checks: [
59
+ {
60
+ name: "Sentinel webhook uptime",
61
+ url: "https://sentinel.theholocron.dev/api/webhook",
62
+ method: "GET",
63
+ locations: ["us-east-1"],
64
+ shouldFail: true, // 405 is the EXPECTED healthy response here
65
+ assertions: [{ source: "status_code", comparison: "equals", target: "405" }],
66
+ },
67
+ ],
68
+ },
69
+ ];
70
+ ```
71
+
72
+ ## What's implemented
73
+
74
+ - `monitoring.ensureCheck(input)` — find-by-exact-name (Checkly's own
75
+ `search` query param is a case-insensitive partial match, so results
76
+ are filtered client-side for an exact match), then create or update
77
+ the API check accordingly.
78
+ - `monitoring.whoami()` — lightweight auth probe (`GET /checks?limit=1`).
79
+ - `monitoring.checks` — the configured check list, read by
80
+ `holocron repo setup` to loop over `ensureCheck`.
81
+ - `verifyToken` — `GET /v1/accounts` (the one Checkly endpoint that does
82
+ **not** require `x-checkly-account`), used by `holocron auth set` /
83
+ `holocron auth check` before any `accountId` is in scope.
84
+
85
+ ## Status
86
+
87
+ **`v2.0.0-alpha.1`** — `src/rest.ts` re-exports `@theholocron/checkly-client`
88
+ directly (two-phase plugin pattern, see `.claude/skills/holocron-skill-plugin/`
89
+ — shipped with an inline wrapper first, migrated once the typed client
90
+ published).
package/dist/index.d.mts ADDED
@@ -0,0 +1,64 @@
1
+ import { AuthError, Monitoring, MonitoringCheck, MonitoringCheckInput, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
2
+ import { ApiCheck, ApiCheckInput, ApiCheckRequest, Assertion, AssertionComparison, AssertionSource, ChecklyClient, ChecklyClientOptions, HttpMethod, ListChecksParams, createChecklyClient } from "@theholocron/checkly-client";
3
+ //#region src/auth.d.ts
4
+ declare const resolveToken: (input?: ResolveTokenInput) => string;
5
+ //#endregion
6
+ //#region src/capabilities/monitoring.d.ts
7
+ interface ChecklyMonitoringOptions {
8
+ checks?: MonitoringCheckInput[];
9
+ }
10
+ declare class ChecklyMonitoring implements Monitoring {
11
+ private readonly client;
12
+ readonly key: "monitoring";
13
+ readonly providerName = "checkly";
14
+ readonly checks: readonly MonitoringCheckInput[];
15
+ constructor(client: () => ChecklyClient, opts?: ChecklyMonitoringOptions);
16
+ whoami(): Promise<{
17
+ ok: boolean;
18
+ }>;
19
+ ensureCheck(input: MonitoringCheckInput): Promise<{
20
+ check: MonitoringCheck;
21
+ alreadyExists: boolean;
22
+ }>;
23
+ /** Checkly's `search` param is a case-insensitive partial match — narrow to the exact name ourselves. */
24
+ private findByExactName;
25
+ }
26
+ //#endregion
27
+ //#region src/verify-token.d.ts
28
+ interface VerifyTokenOptions {
29
+ baseUrl?: string;
30
+ fetch?: typeof fetch;
31
+ }
32
+ declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
33
+ //#endregion
34
+ //#region src/index.d.ts
35
+ interface ChecklyPluginOptions extends ResolveTokenInput {
36
+ /** Checkly account id — required on every request, not a secret (same status as Vercel's teamId). */
37
+ accountId: string;
38
+ /** Checks `holocron repo setup` should ensure exist. */
39
+ checks?: MonitoringCheckInput[];
40
+ /** Override base URL for tests. */
41
+ baseUrl?: string;
42
+ /** Override `fetch` for tests. */
43
+ fetch?: typeof fetch;
44
+ }
45
+ interface PluginContext {
46
+ options: ChecklyPluginOptions;
47
+ /** Memoized client — the token is resolved on first use, not at plugin load. */
48
+ client: () => ChecklyClient;
49
+ }
50
+ declare function createContext(options: ChecklyPluginOptions): PluginContext;
51
+ declare function monitoring(ctx: PluginContext): Monitoring;
52
+ declare function createPlugin(options: ChecklyPluginOptions): {
53
+ name: string;
54
+ capabilities: {
55
+ monitoring: () => Monitoring;
56
+ };
57
+ };
58
+ /**
59
+ * One-line hint printed by `holocron auth set checkly` when no token
60
+ * is supplied or the supplied token is rejected.
61
+ */
62
+ declare const AUTH_HINT: string;
63
+ //#endregion
64
+ export { AUTH_HINT, type ApiCheck, type ApiCheckInput, type ApiCheckRequest, type Assertion, type AssertionComparison, type AssertionSource, AuthError, type ChecklyClient, type ChecklyClientOptions, ChecklyMonitoring, ChecklyPluginOptions, type HttpMethod, type ListChecksParams, PluginContext, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createChecklyClient, createContext, createPlugin, monitoring, resolveToken, verifyToken };
package/dist/index.mjs ADDED
@@ -0,0 +1,145 @@
1
+ import { AuthError, createResolveToken, createRestClient } from "@theholocron/cli";
2
+ import { createChecklyClient } from "@theholocron/checkly-client";
3
+ import { errorMessage } from "@theholocron/misc-utils";
4
+ //#region src/auth.ts
5
+ const resolveToken = createResolveToken({
6
+ envName: "HOLOCRON_CHECKLY_TOKEN",
7
+ vendorEnvName: "CHECKLY_API_KEY",
8
+ keyringService: "checkly",
9
+ errorMessage: "no Checkly token found. Pass --token <TOKEN>, set HOLOCRON_CHECKLY_TOKEN / CHECKLY_API_KEY, or run: holocron auth set checkly <TOKEN>"
10
+ });
11
+ //#endregion
12
+ //#region src/capabilities/monitoring.ts
13
+ const SOURCE_MAP = {
14
+ status_code: "STATUS_CODE",
15
+ response_time: "RESPONSE_TIME",
16
+ body: "TEXT_BODY",
17
+ header: "HEADERS"
18
+ };
19
+ const COMPARISON_MAP = {
20
+ equals: "EQUALS",
21
+ not_equals: "NOT_EQUALS",
22
+ contains: "CONTAINS",
23
+ not_contains: "NOT_CONTAINS",
24
+ greater_than: "GREATER_THAN",
25
+ less_than: "LESS_THAN"
26
+ };
27
+ function toChecklyPayload(input) {
28
+ return {
29
+ name: input.name,
30
+ ...input.frequency !== void 0 ? { frequency: input.frequency } : {},
31
+ ...input.activated !== void 0 ? { activated: input.activated } : {},
32
+ ...input.locations !== void 0 ? { locations: input.locations } : {},
33
+ ...input.shouldFail !== void 0 ? { shouldFail: input.shouldFail } : {},
34
+ request: {
35
+ url: input.url,
36
+ method: input.method ?? "GET",
37
+ assertions: (input.assertions ?? []).map((a) => ({
38
+ source: SOURCE_MAP[a.source],
39
+ comparison: COMPARISON_MAP[a.comparison],
40
+ ...a.property !== void 0 ? { property: a.property } : {},
41
+ ...a.target !== void 0 ? { target: a.target } : {}
42
+ }))
43
+ }
44
+ };
45
+ }
46
+ var ChecklyMonitoring = class {
47
+ client;
48
+ key = "monitoring";
49
+ providerName = "checkly";
50
+ checks;
51
+ constructor(client, opts = {}) {
52
+ this.client = client;
53
+ this.checks = opts.checks ?? [];
54
+ }
55
+ async whoami() {
56
+ try {
57
+ await this.client().checks.list({ limit: 1 });
58
+ return { ok: true };
59
+ } catch {
60
+ return { ok: false };
61
+ }
62
+ }
63
+ async ensureCheck(input) {
64
+ const existing = await this.findByExactName(input.name);
65
+ const payload = toChecklyPayload(input);
66
+ if (existing) {
67
+ const updated = await this.client().checks.update(existing.id, payload);
68
+ return {
69
+ check: {
70
+ id: updated.id,
71
+ name: updated.name
72
+ },
73
+ alreadyExists: true
74
+ };
75
+ }
76
+ const created = await this.client().checks.create(payload);
77
+ return {
78
+ check: {
79
+ id: created.id,
80
+ name: created.name
81
+ },
82
+ alreadyExists: false
83
+ };
84
+ }
85
+ /** Checkly's `search` param is a case-insensitive partial match — narrow to the exact name ourselves. */
86
+ async findByExactName(name) {
87
+ return (await this.client().checks.list({ search: name })).find((c) => c.name === name);
88
+ }
89
+ };
90
+ //#endregion
91
+ //#region src/verify-token.ts
92
+ async function verifyToken(token, opts = {}) {
93
+ const rest = createRestClient({
94
+ baseUrl: opts.baseUrl ?? "https://api.checklyhq.com/v1",
95
+ token,
96
+ vendor: "Checkly",
97
+ ...opts.fetch !== void 0 ? { fetch: opts.fetch } : {}
98
+ });
99
+ try {
100
+ return {
101
+ ok: true,
102
+ subject: (await rest.request("/accounts")).map((a) => `${a.name} (${a.id})`).join(", ") || "no accounts visible"
103
+ };
104
+ } catch (err) {
105
+ return {
106
+ ok: false,
107
+ message: errorMessage(err)
108
+ };
109
+ }
110
+ }
111
+ //#endregion
112
+ //#region src/index.ts
113
+ function createContext(options) {
114
+ let client;
115
+ return {
116
+ options,
117
+ client: () => {
118
+ if (client) return client;
119
+ const clientOpts = {
120
+ token: resolveToken(options),
121
+ accountId: options.accountId
122
+ };
123
+ if (options.baseUrl !== void 0) clientOpts.baseUrl = options.baseUrl;
124
+ if (options.fetch !== void 0) clientOpts.fetch = options.fetch;
125
+ return client = createChecklyClient(clientOpts);
126
+ }
127
+ };
128
+ }
129
+ function monitoring(ctx) {
130
+ return new ChecklyMonitoring(ctx.client, { checks: ctx.options.checks });
131
+ }
132
+ function createPlugin(options) {
133
+ const ctx = createContext(options);
134
+ return {
135
+ name: "@theholocron/holocron-plugin-checkly",
136
+ capabilities: { monitoring: () => monitoring(ctx) }
137
+ };
138
+ }
139
+ /**
140
+ * One-line hint printed by `holocron auth set checkly` when no token
141
+ * is supplied or the supplied token is rejected.
142
+ */
143
+ const AUTH_HINT = "generate a Checkly API key at https://app.checklyhq.com/settings/user/api-keys, then run: holocron auth set checkly <KEY>";
144
+ //#endregion
145
+ export { AUTH_HINT, AuthError, ChecklyMonitoring, createChecklyClient, createContext, createPlugin, monitoring, resolveToken, verifyToken };
package/package.json CHANGED
@@ -1,6 +1,66 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-checkly",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "5.0.0-alpha.140",
4
+ "description": "Holocron plugin for Checkly. Implements the monitoring capability against Checkly's REST API, plus exports verifyToken + AUTH_HINT for `holocron auth`.",
5
+ "keywords": [
6
+ "checkly",
7
+ "holocron",
8
+ "monitoring",
9
+ "plugin"
10
+ ],
11
+ "homepage": "https://github.com/theholocron/holocron/tree/main/plugins/holocron-plugin-checkly#readme",
12
+ "bugs": "https://github.com/theholocron/holocron/issues",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/theholocron/holocron.git",
16
+ "directory": "plugins/holocron-plugin-checkly"
17
+ },
18
+ "license": "MIT",
19
+ "author": "Newton Koumantzelis",
20
+ "sideEffects": false,
21
+ "type": "module",
22
+ "exports": {
23
+ ".": {
24
+ "types": "./dist/index.d.mts",
25
+ "import": "./dist/index.mjs",
26
+ "default": "./dist/index.mjs"
27
+ }
28
+ },
29
+ "files": [
30
+ "dist"
31
+ ],
32
+ "devDependencies": {
33
+ "@theholocron/checkly-client": "^1.41.0",
34
+ "@theholocron/http-client": "^1.41.0",
35
+ "@theholocron/misc-utils": "^1.9.2",
36
+ "@theholocron/tsconfig": "^8.7.1",
37
+ "@types/node": "^26",
38
+ "@vitest/coverage-v8": "^4.1.11",
39
+ "eslint": "^10.8.1",
40
+ "globals": "^17.11.0",
41
+ "tsdown": "^0.22.14",
42
+ "tsx": "4.23.12",
43
+ "typescript": "^5.9.3",
44
+ "vitest": "^4.1.11",
45
+ "@theholocron/cli": "5.0.0-alpha.140"
46
+ },
47
+ "peerDependencies": {
48
+ "@theholocron/checkly-client": "^1.41.0",
49
+ "@theholocron/misc-utils": "^1.9.2",
50
+ "@theholocron/cli": "5.0.0-alpha.140"
51
+ },
52
+ "engines": {
53
+ "node": ">=22"
54
+ },
55
+ "publishConfig": {
56
+ "access": "public"
57
+ },
58
+ "scripts": {
59
+ "delivery.build": "tsdown",
60
+ "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
61
+ "test:watch": "vitest",
62
+ "validate": "tsx scripts/validate.mjs",
63
+ "verification.typeSafety": "holocron run verification.typeSafety --",
64
+ "verification.unitTests": "holocron run verification.unitTests --"
65
+ }
6
66
  }