@theholocron/holocron-plugin-checkly 0.0.0-stage → 2.0.0-alpha.1

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 +79 -2
  3. package/dist/index.d.mts +64 -0
  4. package/dist/index.mjs +143 -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,80 @@
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`:
44
+
45
+ ```ts
46
+ monitoring: [
47
+ "checkly",
48
+ {
49
+ accountId: "<your Checkly account id>",
50
+ checks: [
51
+ {
52
+ name: "Sentinel webhook uptime",
53
+ url: "https://sentinel.theholocron.dev/api/webhook",
54
+ method: "GET",
55
+ assertions: [{ source: "status_code", comparison: "equals", target: "405" }],
56
+ },
57
+ ],
58
+ },
59
+ ];
60
+ ```
61
+
62
+ ## What's implemented
63
+
64
+ - `monitoring.ensureCheck(input)` — find-by-exact-name (Checkly's own
65
+ `search` query param is a case-insensitive partial match, so results
66
+ are filtered client-side for an exact match), then create or update
67
+ the API check accordingly.
68
+ - `monitoring.whoami()` — lightweight auth probe (`GET /checks?limit=1`).
69
+ - `monitoring.checks` — the configured check list, read by
70
+ `holocron repo setup` to loop over `ensureCheck`.
71
+ - `verifyToken` — `GET /v1/accounts` (the one Checkly endpoint that does
72
+ **not** require `x-checkly-account`), used by `holocron auth set` /
73
+ `holocron auth check` before any `accountId` is in scope.
74
+
75
+ ## Status
76
+
77
+ **`v2.0.0-alpha.1`** — `src/rest.ts` re-exports `@theholocron/checkly-client`
78
+ directly (two-phase plugin pattern, see `.claude/skills/holocron-skill-plugin/`
79
+ — shipped with an inline wrapper first, migrated once the typed client
80
+ 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,143 @@
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
+ request: {
33
+ url: input.url,
34
+ method: input.method ?? "GET",
35
+ assertions: (input.assertions ?? []).map((a) => ({
36
+ source: SOURCE_MAP[a.source],
37
+ comparison: COMPARISON_MAP[a.comparison],
38
+ ...a.property !== void 0 ? { property: a.property } : {},
39
+ ...a.target !== void 0 ? { target: a.target } : {}
40
+ }))
41
+ }
42
+ };
43
+ }
44
+ var ChecklyMonitoring = class {
45
+ client;
46
+ key = "monitoring";
47
+ providerName = "checkly";
48
+ checks;
49
+ constructor(client, opts = {}) {
50
+ this.client = client;
51
+ this.checks = opts.checks ?? [];
52
+ }
53
+ async whoami() {
54
+ try {
55
+ await this.client().checks.list({ limit: 1 });
56
+ return { ok: true };
57
+ } catch {
58
+ return { ok: false };
59
+ }
60
+ }
61
+ async ensureCheck(input) {
62
+ const existing = await this.findByExactName(input.name);
63
+ const payload = toChecklyPayload(input);
64
+ if (existing) {
65
+ const updated = await this.client().checks.update(existing.id, payload);
66
+ return {
67
+ check: {
68
+ id: updated.id,
69
+ name: updated.name
70
+ },
71
+ alreadyExists: true
72
+ };
73
+ }
74
+ const created = await this.client().checks.create(payload);
75
+ return {
76
+ check: {
77
+ id: created.id,
78
+ name: created.name
79
+ },
80
+ alreadyExists: false
81
+ };
82
+ }
83
+ /** Checkly's `search` param is a case-insensitive partial match — narrow to the exact name ourselves. */
84
+ async findByExactName(name) {
85
+ return (await this.client().checks.list({ search: name })).find((c) => c.name === name);
86
+ }
87
+ };
88
+ //#endregion
89
+ //#region src/verify-token.ts
90
+ async function verifyToken(token, opts = {}) {
91
+ const rest = createRestClient({
92
+ baseUrl: opts.baseUrl ?? "https://api.checklyhq.com/v1",
93
+ token,
94
+ vendor: "Checkly",
95
+ ...opts.fetch !== void 0 ? { fetch: opts.fetch } : {}
96
+ });
97
+ try {
98
+ return {
99
+ ok: true,
100
+ subject: (await rest.request("/accounts")).map((a) => `${a.name} (${a.id})`).join(", ") || "no accounts visible"
101
+ };
102
+ } catch (err) {
103
+ return {
104
+ ok: false,
105
+ message: errorMessage(err)
106
+ };
107
+ }
108
+ }
109
+ //#endregion
110
+ //#region src/index.ts
111
+ function createContext(options) {
112
+ let client;
113
+ return {
114
+ options,
115
+ client: () => {
116
+ if (client) return client;
117
+ const clientOpts = {
118
+ token: resolveToken(options),
119
+ accountId: options.accountId
120
+ };
121
+ if (options.baseUrl !== void 0) clientOpts.baseUrl = options.baseUrl;
122
+ if (options.fetch !== void 0) clientOpts.fetch = options.fetch;
123
+ return client = createChecklyClient(clientOpts);
124
+ }
125
+ };
126
+ }
127
+ function monitoring(ctx) {
128
+ return new ChecklyMonitoring(ctx.client, { checks: ctx.options.checks });
129
+ }
130
+ function createPlugin(options) {
131
+ const ctx = createContext(options);
132
+ return {
133
+ name: "@theholocron/holocron-plugin-checkly",
134
+ capabilities: { monitoring: () => monitoring(ctx) }
135
+ };
136
+ }
137
+ /**
138
+ * One-line hint printed by `holocron auth set checkly` when no token
139
+ * is supplied or the supplied token is rejected.
140
+ */
141
+ const AUTH_HINT = "generate a Checkly API key at https://app.checklyhq.com/settings/user/api-keys, then run: holocron auth set checkly <KEY>";
142
+ //#endregion
143
+ 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": "2.0.0-alpha.1",
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.40.0",
34
+ "@theholocron/http-client": "^1.40.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.134"
46
+ },
47
+ "peerDependencies": {
48
+ "@theholocron/checkly-client": "^1.40.0",
49
+ "@theholocron/misc-utils": "^1.9.2",
50
+ "@theholocron/cli": "5.0.0-alpha.134"
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
  }