checkly 0.0.0-canary.7b9cf29

package/dist/constructs/check-group-v2.d.ts

@@ -0,0 +1,120 @@
+import { PrivateLocation, PrivateLocationRef } from './private-location.js';
+import type { Region } from '../index.js';
+import { AlertEscalation } from './alert-escalation-policy.js';
+import { Diagnostics } from './diagnostics.js';
+import { CheckGroupV1, CheckGroupV1Props, GroupRetryStrategy } from './check-group-v1.js';
+export interface CheckGroupV2Props extends Omit<CheckGroupV1Props, 'alertEscalationPolicy'> {
+    /**
+     * This property is no longer supported; use {@link retryStrategy} instead.
+     *
+     * To match the behavior of `doubleCheck: true`, use:
+     *
+     *     retryStrategy: RetryStrategyBuilder.fixedStrategy({
+     *       maxRetries: 1,
+     *       baseBackoffSeconds: 0,
+     *       maxDurationSeconds: 600,
+     *       sameRegion: false,
+     *     })
+     *
+     * To match the behavior of `doubleCheck: false`, use:
+     *
+     *     retryStrategy: RetryStrategyBuilder.noRetries()
+     *
+     * @deprecated Use {@link CheckGroupV2Props.retryStrategy} instead.
+     */
+    doubleCheck?: boolean;
+    /**
+     * An array of one or more data center locations where to run the checks.
+     *
+     * If either {@link CheckGroupV2Props.locations} or
+     * {@link CheckGroupV2Props.privateLocations} is set to a non-empty value, all
+     * checks in the group will use those values instead of their own.
+     */
+    locations?: (keyof Region)[];
+    /**
+     * An array of one or more private locations where to run the checks.
+     *
+     * If either {@link CheckGroupV2Props.locations} or
+     * {@link CheckGroupV2Props.privateLocations} is set to a non-empty value, all
+     * checks in the group will use those values instead of their own.
+     */
+    privateLocations?: (string | PrivateLocation | PrivateLocationRef)[];
+    /**
+     * When {@link AlertEscalation}, all checks in the group will use the
+     * group's alert escalation policy. Use {@link AlertEscalationBuilder} to
+     * build a suitable policy.
+     *
+     * When `"global"`, all checks in the group will use the global alert
+     * escalation policy.
+     *
+     * If not set, individual check settings are used.
+     */
+    alertEscalationPolicy?: AlertEscalation | 'global';
+    /**
+     * Sets a retry policy for the group. Use {@link RetryStrategyBuilder} to
+     * create a retry policy.
+     *
+     * If set, all checks in the group use the group's retry strategy.
+     *
+     * If not set, individual check settings are used.
+     */
+    retryStrategy?: GroupRetryStrategy;
+    /**
+     * Determines whether the checks in the group should run on all selected
+     * locations in parallel or round-robin.
+     *
+     * When `true`, all checks in the group run in parallel regardless of their
+     * individual setting.
+     *
+     * When `false`, all checks in the group run in round-robin regardless of
+     * their individual setting.
+     *
+     * If not set, individual check settings are used.
+     *
+     * See https://www.checklyhq.com/docs/concepts/locations/ to learn
+     * more about scheduling strategies.
+     */
+    runParallel?: boolean;
+}
+/**
+ * Creates a Check Group (v2).
+ *
+ * The following properties have changed since CheckGroupV1:
+ *
+ *   - {@link CheckGroupV2Props.alertEscalationPolicy}
+ *     - The implicit default for this property has been removed, allowing
+ *       individual check settings to take effect.
+ *     - Can be set to `"global"` to match the earlier default behavior.
+ *   - {@link CheckGroupV2Props.retryStrategy}
+ *     - The implicit default for this property has been removed, allowing
+ *       individual check settings to take effect.
+ *   - {@link CheckGroupV2Props.runParallel}
+ *     - The implicit default for this property has been removed, allowing
+ *       individual check settings to take effect.
+ */
+export declare class CheckGroupV2 extends CheckGroupV1 {
+    constructor(logicalId: string, props: CheckGroupV2Props);
+    describe(): string;
+    onBeforeValidate(diagnostics: Diagnostics): Promise<void>;
+    protected validateDoubleCheck(diagnostics: Diagnostics): Promise<void>;
+    synthesize(): {
+        doubleCheck: undefined;
+        v: number;
+        name: string;
+        activated: boolean | undefined;
+        muted: boolean | undefined;
+        tags: string[] | undefined;
+        locations: (keyof Region)[];
+        runtimeId: string | undefined;
+        privateLocations: undefined;
+        concurrency: number | undefined;
+        localSetupScript: string | undefined;
+        localTearDownScript: string | undefined;
+        apiCheckDefaults: import("./api-check.js").ApiCheckDefaultConfig;
+        environmentVariables: import("./key-value-pair.js").default[] | undefined;
+        retryStrategy: import("./retry-strategy.js").LinearRetryStrategy | import("./retry-strategy.js").ExponentialRetryStrategy | import("./retry-strategy.js").FixedRetryStrategy | import("./retry-strategy.js").SingleRetryRetryStrategy | null | undefined;
+        runParallel: boolean | undefined;
+        alertSettings: AlertEscalation | undefined;
+        useGlobalAlertSettings: boolean | undefined;
+    };
+}

package/dist/constructs/check-group-v2.js

@@ -0,0 +1,68 @@
+import { CheckGroupV1 } from './check-group-v1.js';
+import { validateRemovedDoubleCheck } from './internal/common-diagnostics.js';
+/**
+ * Creates a Check Group (v2).
+ *
+ * The following properties have changed since CheckGroupV1:
+ *
+ *   - {@link CheckGroupV2Props.alertEscalationPolicy}
+ *     - The implicit default for this property has been removed, allowing
+ *       individual check settings to take effect.
+ *     - Can be set to `"global"` to match the earlier default behavior.
+ *   - {@link CheckGroupV2Props.retryStrategy}
+ *     - The implicit default for this property has been removed, allowing
+ *       individual check settings to take effect.
+ *   - {@link CheckGroupV2Props.runParallel}
+ *     - The implicit default for this property has been removed, allowing
+ *       individual check settings to take effect.
+ */
+export class CheckGroupV2 extends CheckGroupV1 {
+    constructor(logicalId, props) {
+        const { alertEscalationPolicy, useGlobalAlertSettings } = (() => {
+            const { alertEscalationPolicy } = props;
+            // Do we want to always use the global policy?
+            if (alertEscalationPolicy === 'global') {
+                return {
+                    alertEscalationPolicy: undefined,
+                    useGlobalAlertSettings: true,
+                };
+            }
+            // Do we want to let checks keep their own policies?
+            if (alertEscalationPolicy === undefined) {
+                return {
+                    alertEscalationPolicy,
+                    useGlobalAlertSettings: undefined,
+                };
+            }
+            // The group policy will always apply.
+            return {
+                alertEscalationPolicy,
+                useGlobalAlertSettings: false,
+            };
+        })();
+        super(logicalId, {
+            ...props,
+            alertEscalationPolicy,
+        });
+        // Must override; the V1 constructor will not give us the desired behavior.
+        this.useGlobalAlertSettings = useGlobalAlertSettings;
+    }
+    describe() {
+        return `CheckGroupV2:${this.logicalId}`;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async onBeforeValidate(diagnostics) {
+        // No-op
+    }
+    async validateDoubleCheck(diagnostics) {
+        await validateRemovedDoubleCheck(diagnostics, this);
+    }
+    synthesize() {
+        return {
+            ...super.synthesize(),
+            doubleCheck: undefined,
+            v: 2,
+        };
+    }
+}
+//# sourceMappingURL=check-group-v2.js.map

package/dist/constructs/check-group-v2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-group-v2.js","sourceRoot":"","sources":["../../src/constructs/check-group-v2.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,YAAY,EAAyC,MAAM,qBAAqB,CAAA;AACzF,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAA;AAiF7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,YAAa,SAAQ,YAAY;IAC5C,YAAa,SAAiB,EAAE,KAAwB;QACtD,MAAM,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,GAAG,CAAC,GAAG,EAAE;YAC9D,MAAM,EAAE,qBAAqB,EAAE,GAAG,KAAK,CAAA;YAEvC,8CAA8C;YAC9C,IAAI,qBAAqB,KAAK,QAAQ,EAAE,CAAC;gBACvC,OAAO;oBACL,qBAAqB,EAAE,SAAS;oBAChC,sBAAsB,EAAE,IAAI;iBAC7B,CAAA;YACH,CAAC;YAED,oDAAoD;YACpD,IAAI,qBAAqB,KAAK,SAAS,EAAE,CAAC;gBACxC,OAAO;oBACL,qBAAqB;oBACrB,sBAAsB,EAAE,SAAS;iBAClC,CAAA;YACH,CAAC;YAED,sCAAsC;YACtC,OAAO;gBACL,qBAAqB;gBACrB,sBAAsB,EAAE,KAAK;aAC9B,CAAA;QACH,CAAC,CAAC,EAAE,CAAA;QAEJ,KAAK,CAAC,SAAS,EAAE;YACf,GAAG,KAAK;YACR,qBAAqB;SACtB,CAAC,CAAA;QAEF,2EAA2E;QAC3E,IAAI,CAAC,sBAAsB,GAAG,sBAAsB,CAAA;IACtD,CAAC;IAED,QAAQ;QACN,OAAO,gBAAgB,IAAI,CAAC,SAAS,EAAE,CAAA;IACzC,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,gBAAgB,CAAE,WAAwB;QAC9C,QAAQ;IACV,CAAC;IAES,KAAK,CAAC,mBAAmB,CAAE,WAAwB;QAC3D,MAAM,0BAA0B,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;IACrD,CAAC;IAED,UAAU;QACR,OAAO;YACL,GAAG,KAAK,CAAC,UAAU,EAAE;YACrB,WAAW,EAAE,SAAS;YACtB,CAAC,EAAE,CAAC;SACL,CAAA;IACH,CAAC;CACF"}

package/dist/constructs/check-group.d.ts

@@ -0,0 +1,4 @@
+export * from './check-group-v1.js';
+export * from './check-group-v2.js';
+export * from './check-group-ref.js';
+export { CheckGroupV1 as CheckGroup, CheckGroupV1Props as CheckGroupProps, } from './check-group-v1.js';

package/dist/constructs/check-group.js

@@ -0,0 +1,5 @@
+export * from './check-group-v1.js';
+export * from './check-group-v2.js';
+export * from './check-group-ref.js';
+export { CheckGroupV1 as CheckGroup, } from './check-group-v1.js';
+//# sourceMappingURL=check-group.js.map

package/dist/constructs/check-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-group.js","sourceRoot":"","sources":["../../src/constructs/check-group.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AAEpC,OAAO,EACL,YAAY,IAAI,UAAU,GAE3B,MAAM,qBAAqB,CAAA"}

package/dist/constructs/check.d.ts

@@ -0,0 +1,336 @@
+import { Ref } from './ref.js';
+import { Frequency } from './frequency.js';
+import { Construct } from './construct.js';
+import { AlertChannel, AlertChannelRef } from './alert-channel.js';
+import { EnvironmentVariable } from './environment-variable.js';
+import type { Region } from '../index.js';
+import type { CheckGroupV1, CheckGroupV2, CheckGroupRef } from './check-group.js';
+import { PrivateLocation, PrivateLocationRef } from './private-location.js';
+import { ExponentialRetryStrategy, FixedRetryStrategy, LinearRetryStrategy, NoRetriesRetryStrategy, SingleRetryRetryStrategy } from './retry-strategy.js';
+import { AlertEscalation } from './alert-escalation-policy.js';
+import { IncidentTrigger } from './incident.js';
+import { ConfigDefaultsGetter } from './check-config.js';
+import { Diagnostics } from './diagnostics.js';
+import { CheckConfigDefaults } from '../services/checkly-config-loader.js';
+/**
+ * Retry strategies supported by checks.
+ */
+export type CheckRetryStrategy = LinearRetryStrategy | ExponentialRetryStrategy | FixedRetryStrategy | SingleRetryRetryStrategy | NoRetriesRetryStrategy;
+/**
+ * Base configuration properties for all check types.
+ * These properties are inherited by ApiCheck, BrowserCheck, and other check types.
+ */
+export interface CheckProps {
+    /**
+     * The display name of the check. This will be shown in the Checkly dashboard.
+     *
+     * @example "User API Health Check"
+     */
+    name: string;
+    /**
+     * A description of the check. Supports markdown.
+     * Maximum 500 characters.
+     *
+     * @example "Validates the /users endpoint returns correct data and responds within SLA limits."
+     */
+    description?: string | null;
+    /**
+     * Determines whether the check will run periodically after being deployed.
+     * Set to `false` to pause a check without deleting it.
+     *
+     * @defaultValue true
+     */
+    activated?: boolean;
+    /**
+     * Determines if any notifications will be sent out when a check fails and/or recovers.
+     * Useful for temporarily silencing alerts during maintenance.
+     *
+     * @defaultValue false
+     */
+    muted?: boolean;
+    /**
+     * Setting this to "true" will trigger a retry when a check fails from the failing region and another,
+     * randomly selected region before marking the check as failed.
+     * @deprecated Use {@link retryStrategy} instead.
+     */
+    doubleCheck?: boolean;
+    /**
+     * Allows to invert the behaviour of when a check is considered to fail.
+     * Useful for validating error status codes like 404 or 500.
+     * This only applies to API Checks. When set to true, the check passes when
+     * it would normally fail, and fails when it would normally pass.
+     *
+     * @defaultValue false
+     * @example
+     * ```typescript
+     * // Check that expects a 404 status - must set shouldFail: true
+     * shouldFail: true,
+     * request: {
+     *   method: 'GET',
+     *   url: 'https://api.example.com/nonexistent',
+     *   assertions: [AssertionBuilder.statusCode().equals(404)]
+     * }
+     * ```
+     */
+    shouldFail?: boolean;
+    /**
+     * An array of one or more data center locations where to run this check.
+     *
+     * @example ['us-east-1', 'eu-west-1', 'ap-southeast-1']
+     * @see {@link https://www.checklyhq.com/docs/concepts/locations/ | Global Locations}
+     */
+    locations?: Array<keyof Region>;
+    /**
+     * An array of one or more private locations where to run the check.
+     * PrivateLocation instances or slug name strings are allowed.
+     *
+     * `string` slug names are **only** allowed for private locations that **not** belong to the project. Use
+     * PrivateLocation instances references for private locations created within the project.
+     *
+     * @example
+     * ```typescript
+     * // Using private location instances
+     * privateLocations: [myPrivateLocation, anotherPrivateLocation]
+     *
+     * // Using existing private location slugs
+     * privateLocations: ['my-datacenter-1', 'office-location']
+     * ```
+     */
+    privateLocations?: Array<string | PrivateLocation | PrivateLocationRef>;
+    /**
+     * Tags for organizing and filtering checks in the dashboard.
+     *
+     * @example ['production', 'api', 'critical']
+     */
+    tags?: Array<string>;
+    /**
+     * How often the check should run. Can be specified in minutes or using Frequency constants.
+     *
+     * @example
+     * ```typescript
+     * frequency: Frequency.EVERY_5M // Every 5 minutes
+     * ```
+     */
+    frequency?: number | Frequency;
+    /**
+     * The id of the check group this check is part of. Set this by calling `someGroup.ref()`
+     * @deprecated Use {@link group} instead.
+     */
+    groupId?: Ref;
+    /**
+     * The CheckGroup that this check is part of.
+     * Groups allow you to organize related checks and apply common settings.
+     *
+     * @example
+     * ```typescript
+     * // Create a new check group
+     * const apiGroup = new CheckGroupV2('api-group', {
+     *   name: 'API Checks'
+     * })
+     *
+     * // Reference an existing check group by ID
+     * const existingGroup = CheckGroupV2.fromId(123)
+     *
+     * // Use in check configuration
+     * group: apiGroup  // or existingGroup
+     * ```
+     */
+    group?: CheckGroupV1 | CheckGroupV2 | CheckGroupRef;
+    /**
+     * List of alert channels to notify when the check fails or recovers.
+     * If you don't set at least one, we won't be able to alert you in case something goes wrong with your check.
+     *
+     * @example
+     * ```typescript
+     * // Create alert channels once at the project level
+     * const emailChannel = new EmailAlertChannel('team-email', {
+     *   address: 'team@example.com'
+     * })
+     * const slackChannel = new SlackAppAlertChannel('team-slack', {
+     *   slackChannels: ['#alerts']
+     * })
+     *
+     * // Reference the channels in your check
+     * alertChannels: [emailChannel, slackChannel]
+     * ```
+     * @see {@link https://www.checklyhq.com/docs/communicate/alerts/channels/ | Alert Channels}
+     */
+    alertChannels?: Array<AlertChannel | AlertChannelRef>;
+    /**
+     * Determines the alert escalation policy for that particular check.
+     * Controls when and how alerts are escalated based on failure patterns.
+     *
+     * @example
+     * ```typescript
+     * alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(3, {
+     *   amount: 2,
+     *   interval: 10
+     * })
+     * ```
+     */
+    alertEscalationPolicy?: AlertEscalation;
+    /**
+     * Determines if the check is available only when 'test' runs (not included when 'deploy' is executed).
+     * Useful for development and testing scenarios.
+     *
+     * @defaultValue false
+     */
+    testOnly?: boolean;
+    /**
+     * Sets a retry policy for the check. Use RetryStrategyBuilder to create a retry policy.
+     *
+     * @example
+     * ```typescript
+     * retryStrategy: RetryStrategyBuilder.fixedStrategy({
+     *   maxRetries: 3,
+     *   baseBackoffSeconds: 30,
+     *   sameRegion: false
+     * })
+     * ```
+     */
+    retryStrategy?: CheckRetryStrategy;
+    /**
+     * Determines whether the check should run on all selected locations in parallel or round-robin.
+     *
+     * @defaultValue false (round-robin)
+     * @see {@link https://www.checklyhq.com/docs/concepts/scheduling/ | Scheduling Strategies}
+     */
+    runParallel?: boolean;
+    /**
+     * Determines whether the check should create and resolve an incident based on its alert configuration.
+     * Useful for status page automation.
+     *
+     * @see {@link https://www.checklyhq.com/docs/communicate/status-pages/incidents/#incident-automation | Incident Automation}
+     */
+    triggerIncident?: IncidentTrigger;
+}
+export declare abstract class Check extends Construct {
+    name: string;
+    description?: string | null;
+    activated?: boolean;
+    muted?: boolean;
+    doubleCheck?: boolean;
+    shouldFail?: boolean;
+    locations?: Array<keyof Region>;
+    privateLocations?: Array<string | PrivateLocation | PrivateLocationRef>;
+    tags?: Array<string>;
+    frequency?: number;
+    frequencyOffset?: number;
+    groupId?: Ref;
+    alertChannels?: Array<AlertChannel | AlertChannelRef>;
+    testOnly?: boolean;
+    retryStrategy?: CheckRetryStrategy;
+    alertSettings?: AlertEscalation;
+    useGlobalAlertSettings?: boolean;
+    runParallel?: boolean;
+    triggerIncident?: IncidentTrigger;
+    __checkFilePath?: string;
+    static readonly __checklyType = "check";
+    protected constructor(logicalId: string, props: CheckProps);
+    protected validateDoubleCheck(diagnostics: Diagnostics): Promise<void>;
+    protected validateRetryStrategyOnlyOn(diagnostics: Diagnostics): Promise<void>;
+    protected supportsOnlyOnNetworkErrorRetryStrategy(): boolean;
+    validate(diagnostics: Diagnostics): Promise<void>;
+    protected configDefaultsGetter(props: CheckProps): ConfigDefaultsGetter<CheckConfigDefaults>;
+    protected applyConfigDefaults<T extends CheckProps>(props: T): T;
+    /**
+     * Creates alert channel subscriptions for this check.
+     * Links the check to its configured alert channels to send notifications.
+     * Only creates subscriptions if alert channels are configured and check is not test-only.
+     */
+    addSubscriptions(): void;
+    /**
+     * Creates private location assignments for this check.
+     * Links the check to its configured private locations so it can run on them.
+     * Only processes PrivateLocation instances, not string slugs.
+     */
+    addPrivateLocationCheckAssignments(): void;
+    /**
+     * Gets the source file path where this check was defined.
+     * Used for filtering and debugging purposes.
+     *
+     * @returns The absolute path to the check file, or undefined if not set
+     */
+    getSourceFile(): string | undefined;
+    synthesize(): {
+        activated: boolean | undefined;
+        muted: boolean | undefined;
+        shouldFail: boolean | undefined;
+        locations: (keyof Region)[] | undefined;
+        privateLocations: undefined;
+        tags: string[] | undefined;
+        frequency: number | undefined;
+        frequencyOffset: number | undefined;
+        groupId: Ref | null;
+        retryStrategy: LinearRetryStrategy | ExponentialRetryStrategy | FixedRetryStrategy | SingleRetryRetryStrategy | null | undefined;
+        doubleCheck: boolean | undefined;
+        alertSettings: AlertEscalation | undefined;
+        useGlobalAlertSettings: boolean | undefined;
+        runParallel: boolean | undefined;
+        triggerIncident: {
+            serviceId: Ref;
+            severity: "MINOR" | "MEDIUM" | "MAJOR" | "CRITICAL";
+            name: string;
+            description: string;
+            notifySubscribers: boolean;
+        } | undefined;
+        description?: string | undefined;
+        name: string;
+    };
+}
+export interface RuntimeCheckProps extends CheckProps {
+    /**
+     * The runtime version, i.e. fixed set of runtime dependencies, used to execute this check.
+     *
+     * @example "2024.09"
+     * @see {@link https://www.checklyhq.com/docs/runtimes/ | Runtime Documentation}
+     */
+    runtimeId?: string;
+    /**
+     * Environment variables available to the check script.
+     * Maximum of 50 environment variables per check.
+     *
+     * @maxItems 50
+     * @example
+     * ```typescript
+     * environmentVariables: [
+     *   { key: 'API_TOKEN', value: '{{API_TOKEN}}', secret: true },
+     *   { key: 'BASE_URL', value: 'https://api.example.com' }
+     * ]
+     * ```
+     */
+    environmentVariables?: EnvironmentVariable[];
+}
+export declare abstract class RuntimeCheck extends Check {
+    runtimeId?: string;
+    environmentVariables?: EnvironmentVariable[];
+    protected constructor(logicalId: string, props: RuntimeCheckProps);
+    protected applyConfigDefaults<T extends RuntimeCheckProps>(props: T): T;
+    synthesize(): {
+        runtimeId: string | undefined;
+        environmentVariables: import("./key-value-pair.js").default[] | undefined;
+        activated: boolean | undefined;
+        muted: boolean | undefined;
+        shouldFail: boolean | undefined;
+        locations: (keyof Region)[] | undefined;
+        privateLocations: undefined;
+        tags: string[] | undefined;
+        frequency: number | undefined;
+        frequencyOffset: number | undefined;
+        groupId: Ref | null;
+        retryStrategy: LinearRetryStrategy | ExponentialRetryStrategy | FixedRetryStrategy | SingleRetryRetryStrategy | null | undefined;
+        doubleCheck: boolean | undefined;
+        alertSettings: AlertEscalation | undefined;
+        useGlobalAlertSettings: boolean | undefined;
+        runParallel: boolean | undefined;
+        triggerIncident: {
+            serviceId: Ref;
+            severity: "MINOR" | "MEDIUM" | "MAJOR" | "CRITICAL";
+            name: string;
+            description: string;
+            notifySubscribers: boolean;
+        } | undefined;
+        description?: string | undefined;
+        name: string;
+    };
+}