@theholocron/checkly-client 1.50.0 → 1.52.0

package/README.md

@@ -75,8 +75,40 @@ account id (visible at `https://app.checklyhq.com/settings/account/general`)
 The token is passed directly or read from `CHECKLY_API_KEY`; the account id
 from `CHECKLY_ACCOUNT_ID`. Neither has a default — both are required.
 
-> **Note:** This client only covers API checks (`checks.*`, the
-> `/v1/checks/api` and `/v1/checks` endpoints) — the subset this org
-> currently provisions programmatically. Checkly's full surface (browser
-> checks, check groups, alert channels, dashboards) is out of scope until a
-> real consumer needs it.
+## Alert channels
+
+```ts
+import { DISCORD_TEMPLATE } from "@theholocron/checkly-client";
+
+// A Discord channel is a WEBHOOK marked WEBHOOK_DISCORD. The template is not filled in for you when you create one
+// through the API, so pass DISCORD_TEMPLATE (Checkly's own Discord message body).
+const channel = await checkly.alertChannels.create({
+  type: "WEBHOOK",
+  config: {
+    name: "Discord #uptime",
+    url: "https://discord.com/api/webhooks/…", // a secret: anyone holding it can post
+    method: "POST",
+    headers: [],
+    queryParameters: [],
+    template: DISCORD_TEMPLATE,
+    webhookType: "WEBHOOK_DISCORD",
+  },
+  sendFailure: true,
+  sendRecovery: true,
+  sendDegraded: true,
+  // Checks made through the API are never auto-subscribed: list each one.
+  subscriptions: [{ checkId: check.id, activated: true }],
+});
+
+const all = await checkly.alertChannels.list(); // every page
+const one = await checkly.alertChannels.get(channel.id);
+await checkly.alertChannels.update(channel.id, {/* the complete channel */});
+await checkly.alertChannels.delete(channel.id);
+```
+
+`update` replaces the whole channel (settings and subscriptions), so send everything you want to keep. Checkly offers
+no version check, so do not update one channel from two places at once.
+
+> **Note:** This client covers API checks (`checks.*`) and alert channels (`alertChannels.*`) — the subset this org
+> currently provisions programmatically. Checkly's full surface (browser checks, check groups, dashboards) is out of
+> scope until a real consumer needs it.

package/dist/index.d.mts

@@ -16,6 +16,90 @@ interface ChecklyClientOptions {
   errors?: ErrorSink;
 }
 //#endregion
+//#region ../../../../../src/alert-channels/alert-channels.d.ts
+type AlertChannelType = "EMAIL" | "SLACK" | "SLACK_APP" | "WEBHOOK" | "SMS" | "PAGERDUTY" | "OPSGENIE" | "CALL";
+type WebhookMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
+/**
+ * Which service a webhook channel is formatted for. Checkly stores a Discord channel as a plain `WEBHOOK` with this
+ * marker and a body template; there is no separate Discord type.
+ */
+type WebhookType = "WEBHOOK_DISCORD" | "WEBHOOK_MSTEAMS" | "WEBHOOK_TELEGRAM" | "WEBHOOK_GITHUB" | "WEBHOOK_SPIKE";
+interface WebhookKeyValue {
+  key: string;
+  value: string;
+  locked?: boolean;
+}
+/** The `config` of a `WEBHOOK` channel, as Checkly returns it. */
+interface WebhookConfig {
+  name: string;
+  /** Where Checkly posts. For Discord this is a webhook URL and is a secret: anyone holding it can post to the channel. */
+  url: string;
+  method: WebhookMethod;
+  /** Handlebars body template with Checkly's `{{VARIABLES}}`. */
+  template?: string;
+  headers?: WebhookKeyValue[];
+  queryParameters?: WebhookKeyValue[];
+  webhookType?: WebhookType;
+  webhookSecret?: string;
+}
+/** A subscription targets exactly one check or one check group. */
+type AlertChannelSubscription = {
+  id?: number;
+  activated: boolean;
+} & ({
+  checkId: string;
+  groupId?: null;
+} | {
+  groupId: number;
+  checkId?: null;
+});
+interface AlertChannelSettings {
+  sendRecovery?: boolean;
+  sendFailure?: boolean;
+  sendDegraded?: boolean;
+  sslExpiry?: boolean;
+  sslExpiryThreshold?: number;
+  /** Subscribe checks created later in the UI. Checks made through the API or CLI are never auto-subscribed. */
+  autoSubscribe?: boolean;
+  /**
+   * The full list of subscribed checks. Checkly's update replaces the whole channel, so anything left out here (or
+   * in the settings above) is dropped: send the complete channel, not just what changed.
+   */
+  subscriptions?: AlertChannelSubscription[];
+}
+/** What a channel is made of. A webhook's `config` is checked; the other types are passed through as Checkly defines them. */
+type AlertChannelInput = AlertChannelSettings & ({
+  type: "WEBHOOK";
+  config: WebhookConfig;
+} | {
+  type: Exclude<AlertChannelType, "WEBHOOK">;
+  config: Record<string, unknown>;
+});
+interface AlertChannelRecord {
+  id: number;
+  sendRecovery: boolean;
+  sendFailure: boolean;
+  sendDegraded: boolean;
+  sslExpiry: boolean;
+  sslExpiryThreshold: number;
+  autoSubscribe: boolean;
+  subscriptions: AlertChannelSubscription[];
+  created_at: string;
+  updated_at: string | null;
+}
+type AlertChannel = AlertChannelRecord & ({
+  type: "WEBHOOK";
+  config: WebhookConfig;
+} | {
+  type: Exclude<AlertChannelType, "WEBHOOK">;
+  config: Record<string, unknown>;
+});
+/**
+ * The message body of Checkly's own Discord setup (its AI-analysis section left out, since not every account has it), so
+ * a channel made through the API reads like one made in the UI.
+ */
+declare const DISCORD_TEMPLATE = "{\n  \"content\": null,\n  \"username\": \"Checkly\",\n  \"avatar_url\": \"https://s3.eu-central-1.amazonaws.com/cdn.checklyhq.com/slack/checkly-slack-icon.png\",\n  {{! Embeds for the SSL expiry notifications}}\n  {{#eq ALERT_TYPE \"ALERT_SSL\" }}\n  \"embeds\": [\n    {\n      \"title\": \"{{ALERT_TITLE}}\",\n      \"url\": \"{{RESULT_LINK}}\",\n      \"color\": 16762924\n    }\n  ]\n  {{else}}\n  {{! Embeds for the standard failure, recovery and degraded notifications}}\n  \"embeds\": [\n    {\n      \"title\": \"{{ALERT_TITLE}}\",\n      \"url\": \"{{RESULT_LINK}}\",\n      \"fields\": [\n        {{#eq ALERT_TYPE \"API\" }}\n        {\n          \"name\": \"Status code\",\n          \"value\": \"{{API_CHECK_RESPONSE_STATUS_CODE}}\"\n        },\n        {{/eq}}\n        {{#if GROUP_NAME}}\n        {\n          \"name\": \"Group\",\n          \"value\": \"{{GROUP_NAME}}\"\n        },\n        {{/if}}\n        {\n          \"name\": \"Response Time\",\n          \"value\": \"{{RESPONSE_TIME}}ms\"\n        },\n        {\n          \"name\": \"Location\",\n          \"value\": \"{{RUN_LOCATION}}\"\n        },\n        {\n          \"name\": \"Tags\",\n          \"value\": \"[{{#each TAGS}} {{this}} {{#unless @last}},{{/unless}} {{/each}}]\"\n        }\n      ],\n      \"timestamp\": \"{{STARTED_AT}}\"\n    }\n  ]\n  {{/eq}}\n}\n";
+//#endregion
 //#region ../../../../../src/checks/checks.d.ts
 type AssertionSource = "STATUS_CODE" | "JSON_BODY" | "HEADERS" | "TEXT_BODY" | "RESPONSE_TIME";
 type AssertionComparison = "EQUALS" | "NOT_EQUALS" | "HAS_KEY" | "NOT_HAS_KEY" | "HAS_VALUE" | "NOT_HAS_VALUE" | "IS_EMPTY" | "NOT_EMPTY" | "GREATER_THAN" | "LESS_THAN" | "CONTAINS" | "NOT_CONTAINS" | "IS_NULL" | "NOT_NULL";
@@ -84,6 +168,13 @@ interface ListChecksParams {
 //#endregion
 //#region ../../../../../src/index.d.ts
 declare function createChecklyClient(opts: ChecklyClientOptions): {
+  alertChannels: {
+    list: () => Promise<AlertChannel[]>;
+    get: (id: number) => Promise<AlertChannel>;
+    create: (input: AlertChannelInput) => Promise<AlertChannel>;
+    update: (id: number, input: AlertChannelInput) => Promise<AlertChannel>;
+    delete: (id: number) => Promise<void>;
+  };
   checks: {
     list: (params?: ListChecksParams) => Promise<ApiCheck[]>;
     get: (id: string) => Promise<ApiCheck>;
@@ -94,4 +185,4 @@ declare function createChecklyClient(opts: ChecklyClientOptions): {
 };
 type ChecklyClient = ReturnType<typeof createChecklyClient>;
 //#endregion
-export { type ApiCheck, type ApiCheckInput, type ApiCheckRequest, type Assertion, type AssertionComparison, type AssertionSource, ChecklyClient, type ChecklyClientOptions, type HttpMethod, type ListChecksParams, createChecklyClient };
+export { type AlertChannel, type AlertChannelInput, type AlertChannelSubscription, type AlertChannelType, type ApiCheck, type ApiCheckInput, type ApiCheckRequest, type Assertion, type AssertionComparison, type AssertionSource, ChecklyClient, type ChecklyClientOptions, DISCORD_TEMPLATE, type HttpMethod, type ListChecksParams, type WebhookConfig, type WebhookKeyValue, type WebhookMethod, type WebhookType, createChecklyClient };

package/dist/index.mjs

@@ -1,4 +1,99 @@
 import { createRestClient } from "@theholocron/http-client";
+//#region ../../../../../src/alert-channels/alert-channels.ts
+/**
+* The message body of Checkly's own Discord setup (its AI-analysis section left out, since not every account has it), so
+* a channel made through the API reads like one made in the UI.
+*/
+const DISCORD_TEMPLATE = `{
+  "content": null,
+  "username": "Checkly",
+  "avatar_url": "https://s3.eu-central-1.amazonaws.com/cdn.checklyhq.com/slack/checkly-slack-icon.png",
+  {{! Embeds for the SSL expiry notifications}}
+  {{#eq ALERT_TYPE "ALERT_SSL" }}
+  "embeds": [
+    {
+      "title": "{{ALERT_TITLE}}",
+      "url": "{{RESULT_LINK}}",
+      "color": 16762924
+    }
+  ]
+  {{else}}
+  {{! Embeds for the standard failure, recovery and degraded notifications}}
+  "embeds": [
+    {
+      "title": "{{ALERT_TITLE}}",
+      "url": "{{RESULT_LINK}}",
+      "fields": [
+        {{#eq ALERT_TYPE "API" }}
+        {
+          "name": "Status code",
+          "value": "{{API_CHECK_RESPONSE_STATUS_CODE}}"
+        },
+        {{/eq}}
+        {{#if GROUP_NAME}}
+        {
+          "name": "Group",
+          "value": "{{GROUP_NAME}}"
+        },
+        {{/if}}
+        {
+          "name": "Response Time",
+          "value": "{{RESPONSE_TIME}}ms"
+        },
+        {
+          "name": "Location",
+          "value": "{{RUN_LOCATION}}"
+        },
+        {
+          "name": "Tags",
+          "value": "[{{#each TAGS}} {{this}} {{#unless @last}},{{/unless}} {{/each}}]"
+        }
+      ],
+      "timestamp": "{{STARTED_AT}}"
+    }
+  ]
+  {{/eq}}
+}
+`;
+/** Checkly's page size ceiling for this listing. */
+const PAGE = 100;
+/** A guard so a runaway listing cannot loop forever. */
+const MAX_PAGES = 50;
+function alertChannels(rest) {
+	return {
+		/** Every alert channel on the account, read page by page. */
+		list: async () => {
+			const read = (page) => rest.request("/alert-channels", { query: {
+				limit: String(PAGE),
+				page: String(page)
+			} });
+			const all = [];
+			for (let page = 1; page <= MAX_PAGES; page++) {
+				const batch = await read(page);
+				all.push(...batch);
+				if (batch.length < PAGE) return all;
+			}
+			if ((await read(51)).length > 0) throw new Error(`more than 5000 alert channels; refusing to read them all`);
+			return all;
+		},
+		/** One alert channel. Throws ProviderApiError 404 if there is none. */
+		get: (id) => rest.request(`/alert-channels/${id}`),
+		create: (input) => rest.request("/alert-channels", {
+			method: "POST",
+			body: { ...input }
+		}),
+		/**
+		* Replace a channel. Checkly's update takes the whole channel, so send every setting and subscription you want
+		* to keep; there is no version check, so callers must not update the same channel concurrently.
+		*/
+		update: (id, input) => rest.request(`/alert-channels/${id}`, {
+			method: "PUT",
+			body: { ...input }
+		}),
+		delete: (id) => rest.request(`/alert-channels/${id}`, { method: "DELETE" })
+	};
+}
+//#endregion
 //#region ../../../../../src/checks/checks.ts
 /**
 * `ApiCheckInput.request.body` is holocron's simplified shape (just the raw
@@ -59,7 +154,11 @@ function createChecklyRestClient(opts) {
 //#endregion
 //#region ../../../../../src/index.ts
 function createChecklyClient(opts) {
-	return { checks: checks(createChecklyRestClient(opts)) };
+	const rest = createChecklyRestClient(opts);
+	return {
+		alertChannels: alertChannels(rest),
+		checks: checks(rest)
+	};
 }
 //#endregion
-export { createChecklyClient };
+export { DISCORD_TEMPLATE, createChecklyClient };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/checkly-client",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "description": "A TypeScript client for the Checkly monitoring API",
   "keywords": [
     "checkly",
@@ -34,7 +34,7 @@
   ],
   "dependencies": {
     "@theholocron/observability": "^0.3.0",
-    "@theholocron/http-client": "^1.50.0"
+    "@theholocron/http-client": "^1.52.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.79",