@checkstack/sdk 0.94.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# @checkstack/sdk
+
+## 0.93.1
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/auth-common@0.8.0
+  - @checkstack/healthcheck-common@1.5.0
+  - @checkstack/notification-common@1.3.0
+  - @checkstack/anomaly-common@1.3.0
+  - @checkstack/automation-common@0.4.0
+  - @checkstack/catalog-common@2.3.0
+  - @checkstack/common@0.13.0
+  - @checkstack/script-packages-common@0.3.0
+  - @checkstack/slo-common@0.5.0
+  - @checkstack/satellite-common@0.8.0
+  - @checkstack/announcement-common@0.5.0
+  - @checkstack/cache-common@0.5.0
+  - @checkstack/command-common@0.3.0
+  - @checkstack/dependency-common@1.2.0
+  - @checkstack/gitops-common@0.6.0
+  - @checkstack/incident-common@1.4.0
+  - @checkstack/integration-common@0.7.0
+  - @checkstack/maintenance-common@1.4.0
+  - @checkstack/queue-common@0.6.0
+  - @checkstack/secrets-common@0.2.0
+  - @checkstack/theme-common@0.2.0
+  - @checkstack/tips-common@0.3.0
+  - @checkstack/pluginmanager-common@0.2.5

package/generated/editor-bundle-module.d.ts

@@ -0,0 +1,7 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** The combined ambient `.d.ts` the in-app editor mounts into Monaco. */
+export declare const SDK_EDITOR_BUNDLE_DTS: string;
+export { SDK_RELEASE_VERSION } from "./version.d.ts";

package/generated/editor-bundle.d.ts

@@ -0,0 +1,122 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+// Combined ambient declarations served ONLY by the version-keyed editor
+// route and mounted into Monaco. NOT the `exports`-resolved declarations
+// (those are the per-subpath generated/*.d.ts). Declares the subpath module
+// names only - bare names are intentionally absent so an old import errors.
+//
+// Every declaration is module-scoped (no top-level globals): the editor
+// mounts this bundle alongside scriptContext.ts, which owns the global
+// `defineHealthCheck` / `defineIntegration` + schema-narrowed context types
+// (plan §6.2). Top-level globals here would duplicate those and error.
+
+declare module "@checkstack/sdk/healthcheck" {
+  /** Result emitted by an inline health-check script. */
+  interface HealthCheckScriptResult {
+    /** Whether the health check passed. */
+    success: boolean;
+    /** Optional status message — surfaces in the run detail. */
+    message?: string;
+    /** Optional numeric value — feeds the value chart + anomaly detection. */
+    value?: number;
+  }
+
+  /**
+   * Runtime context exposed to inline health-check scripts. `config` is
+   * typed from the collector's own JSON Schema, so the fields you've
+   * declared on the configuration are autocompletable inside the script.
+   */
+  interface HealthCheckScriptContext {
+    /** Strongly-typed collector configuration. */
+    readonly config: Record<string, unknown>;
+    /** Metadata about the health check this run is for. */
+    readonly check: {
+      /** The health check configuration id. */
+      readonly id: string;
+      /** The health check's display name (falls back to the id). */
+      readonly name: string;
+      /** The configured run interval, in seconds. */
+      readonly intervalSeconds: number;
+    };
+    /** Metadata about the system this check runs for. */
+    readonly system: {
+      /** The system id. */
+      readonly id: string;
+      /** The system's display name (falls back to the id). */
+      readonly name: string;
+    };
+  }
+
+  export function defineHealthCheck<
+    T extends
+      | HealthCheckScriptResult
+      | ((ctx: HealthCheckScriptContext) =>
+          | HealthCheckScriptResult
+          | Promise<HealthCheckScriptResult>),
+  >(value: T): T;
+  export type { HealthCheckScriptResult, HealthCheckScriptContext };
+}
+
+declare module "@checkstack/sdk/integration" {
+  /** Result emitted by an inline integration script. */
+  interface IntegrationScriptResult {
+    /** External ID for tracking (e.g. ticket number, message ID). */
+    id?: string;
+    /** Same as `id` — accepted for backwards compatibility. */
+    externalId?: string;
+  }
+
+  /**
+   * Runtime context exposed to inline integration scripts. `event.payload`
+   * is typed from the event's payload schema so the fields it advertises
+   * are autocompletable inside the script.
+   */
+  interface IntegrationScriptContext {
+    /** The event being delivered. */
+    readonly event: {
+      /** Fully-qualified event ID, e.g. "incident.created". */
+      readonly eventId: string;
+      /** Strongly-typed event payload. */
+      readonly payload: Record<string, unknown>;
+      /** ISO-8601 timestamp of when the event was emitted. */
+      readonly timestamp: string;
+      /** Unique ID for this delivery attempt. */
+      readonly deliveryId: string;
+    };
+    /** Subscription that triggered this delivery. */
+    readonly subscription: {
+      readonly id: string;
+      readonly name: string;
+    };
+  }
+
+  export function defineIntegration<
+    T extends
+      | IntegrationScriptResult
+      | void
+      | ((ctx: IntegrationScriptContext) =>
+          | IntegrationScriptResult
+          | void
+          | Promise<IntegrationScriptResult | void>),
+  >(value: T): T;
+  export type { IntegrationScriptResult, IntegrationScriptContext };
+}
+
+declare module "@checkstack/sdk" {
+  export { defineHealthCheck } from "@checkstack/sdk/healthcheck";
+  export type { HealthCheckScriptResult, HealthCheckScriptContext } from "@checkstack/sdk/healthcheck";
+  export { defineIntegration } from "@checkstack/sdk/integration";
+  export type { IntegrationScriptResult, IntegrationScriptContext } from "@checkstack/sdk/integration";
+  export interface CreateCheckstackClientOptions {
+    baseUrl: string;
+    headers?: Record<string, string>;
+  }
+  /** The fully-typed Checkstack API client (one entry per plugin id). */
+  export type CheckstackClient = Record<string, unknown>;
+  /** Build a typed Checkstack client over the REST/OpenAPI surface. */
+  export function createCheckstackClient(
+    options: CreateCheckstackClientOptions,
+  ): CheckstackClient;
+}

package/generated/healthcheck.d.ts

@@ -0,0 +1,49 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** Result emitted by an inline health-check script. */
+interface HealthCheckScriptResult {
+  /** Whether the health check passed. */
+  success: boolean;
+  /** Optional status message — surfaces in the run detail. */
+  message?: string;
+  /** Optional numeric value — feeds the value chart + anomaly detection. */
+  value?: number;
+}
+
+/**
+ * Runtime context exposed to inline health-check scripts. `config` is
+ * typed from the collector's own JSON Schema, so the fields you've
+ * declared on the configuration are autocompletable inside the script.
+ */
+interface HealthCheckScriptContext {
+  /** Strongly-typed collector configuration. */
+  readonly config: Record<string, unknown>;
+  /** Metadata about the health check this run is for. */
+  readonly check: {
+    /** The health check configuration id. */
+    readonly id: string;
+    /** The health check's display name (falls back to the id). */
+    readonly name: string;
+    /** The configured run interval, in seconds. */
+    readonly intervalSeconds: number;
+  };
+  /** Metadata about the system this check runs for. */
+  readonly system: {
+    /** The system id. */
+    readonly id: string;
+    /** The system's display name (falls back to the id). */
+    readonly name: string;
+  };
+}
+
+export declare function defineHealthCheck<
+  T extends
+    | HealthCheckScriptResult
+    | ((ctx: HealthCheckScriptContext) =>
+        | HealthCheckScriptResult
+        | Promise<HealthCheckScriptResult>),
+>(value: T): T;
+
+export type { HealthCheckScriptResult, HealthCheckScriptContext };

package/generated/index.d.ts

@@ -0,0 +1,178 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+import type { InferClient } from "@checkstack/common";
+import type { AnnouncementApi } from "@checkstack/announcement-common";
+import type { AnomalyApi } from "@checkstack/anomaly-common";
+import type { AuthApi } from "@checkstack/auth-common";
+import type { AutomationApi } from "@checkstack/automation-common";
+import type { CacheApi } from "@checkstack/cache-common";
+import type { CatalogApi } from "@checkstack/catalog-common";
+import type { CommandApi } from "@checkstack/command-common";
+import type { DependencyApi } from "@checkstack/dependency-common";
+import type { GitOpsApi } from "@checkstack/gitops-common";
+import type { HealthCheckApi } from "@checkstack/healthcheck-common";
+import type { IncidentApi } from "@checkstack/incident-common";
+import type { IntegrationApi } from "@checkstack/integration-common";
+import type { MaintenanceApi } from "@checkstack/maintenance-common";
+import type { NotificationApi } from "@checkstack/notification-common";
+import type { PluginManagerApi } from "@checkstack/pluginmanager-common";
+import type { QueueApi } from "@checkstack/queue-common";
+import type { SatelliteApi } from "@checkstack/satellite-common";
+import type { ScriptPackagesApi } from "@checkstack/script-packages-common";
+import type { SecretsApi } from "@checkstack/secrets-common";
+import type { SloApi } from "@checkstack/slo-common";
+import type { ThemeApi } from "@checkstack/theme-common";
+import type { TipsApi } from "@checkstack/tips-common";
+
+export interface CheckstackClient {
+  announcement: InferClient<typeof AnnouncementApi>;
+  anomaly: InferClient<typeof AnomalyApi>;
+  auth: InferClient<typeof AuthApi>;
+  automation: InferClient<typeof AutomationApi>;
+  cache: InferClient<typeof CacheApi>;
+  catalog: InferClient<typeof CatalogApi>;
+  command: InferClient<typeof CommandApi>;
+  dependency: InferClient<typeof DependencyApi>;
+  gitops: InferClient<typeof GitOpsApi>;
+  healthcheck: InferClient<typeof HealthCheckApi>;
+  incident: InferClient<typeof IncidentApi>;
+  integration: InferClient<typeof IntegrationApi>;
+  maintenance: InferClient<typeof MaintenanceApi>;
+  notification: InferClient<typeof NotificationApi>;
+  pluginmanager: InferClient<typeof PluginManagerApi>;
+  queue: InferClient<typeof QueueApi>;
+  satellite: InferClient<typeof SatelliteApi>;
+  "script-packages": InferClient<typeof ScriptPackagesApi>;
+  secrets: InferClient<typeof SecretsApi>;
+  slo: InferClient<typeof SloApi>;
+  theme: InferClient<typeof ThemeApi>;
+  tips: InferClient<typeof TipsApi>;
+}
+
+export interface CreateCheckstackClientOptions {
+  baseUrl: string;
+  headers?: Record<string, string>;
+}
+
+export declare function createCheckstackClient(
+  options: CreateCheckstackClientOptions,
+): CheckstackClient;
+
+export { AnnouncementApi } from "@checkstack/announcement-common";
+export { AnomalyApi } from "@checkstack/anomaly-common";
+export { AuthApi } from "@checkstack/auth-common";
+export { AutomationApi } from "@checkstack/automation-common";
+export { CacheApi } from "@checkstack/cache-common";
+export { CatalogApi } from "@checkstack/catalog-common";
+export { CommandApi } from "@checkstack/command-common";
+export { DependencyApi } from "@checkstack/dependency-common";
+export { GitOpsApi } from "@checkstack/gitops-common";
+export { HealthCheckApi } from "@checkstack/healthcheck-common";
+export { IncidentApi } from "@checkstack/incident-common";
+export { IntegrationApi } from "@checkstack/integration-common";
+export { MaintenanceApi } from "@checkstack/maintenance-common";
+export { NotificationApi } from "@checkstack/notification-common";
+export { PluginManagerApi } from "@checkstack/pluginmanager-common";
+export { QueueApi } from "@checkstack/queue-common";
+export { SatelliteApi } from "@checkstack/satellite-common";
+export { ScriptPackagesApi } from "@checkstack/script-packages-common";
+export { SecretsApi } from "@checkstack/secrets-common";
+export { SloApi } from "@checkstack/slo-common";
+export { ThemeApi } from "@checkstack/theme-common";
+export { TipsApi } from "@checkstack/tips-common";
+
+// Script-authoring helpers (also available under the per-subpath exports).
+/** Result emitted by an inline health-check script. */
+interface HealthCheckScriptResult {
+  /** Whether the health check passed. */
+  success: boolean;
+  /** Optional status message — surfaces in the run detail. */
+  message?: string;
+  /** Optional numeric value — feeds the value chart + anomaly detection. */
+  value?: number;
+}
+
+/**
+ * Runtime context exposed to inline health-check scripts. `config` is
+ * typed from the collector's own JSON Schema, so the fields you've
+ * declared on the configuration are autocompletable inside the script.
+ */
+interface HealthCheckScriptContext {
+  /** Strongly-typed collector configuration. */
+  readonly config: Record<string, unknown>;
+  /** Metadata about the health check this run is for. */
+  readonly check: {
+    /** The health check configuration id. */
+    readonly id: string;
+    /** The health check's display name (falls back to the id). */
+    readonly name: string;
+    /** The configured run interval, in seconds. */
+    readonly intervalSeconds: number;
+  };
+  /** Metadata about the system this check runs for. */
+  readonly system: {
+    /** The system id. */
+    readonly id: string;
+    /** The system's display name (falls back to the id). */
+    readonly name: string;
+  };
+}
+
+/** Result emitted by an inline integration script. */
+interface IntegrationScriptResult {
+  /** External ID for tracking (e.g. ticket number, message ID). */
+  id?: string;
+  /** Same as `id` — accepted for backwards compatibility. */
+  externalId?: string;
+}
+
+/**
+ * Runtime context exposed to inline integration scripts. `event.payload`
+ * is typed from the event's payload schema so the fields it advertises
+ * are autocompletable inside the script.
+ */
+interface IntegrationScriptContext {
+  /** The event being delivered. */
+  readonly event: {
+    /** Fully-qualified event ID, e.g. "incident.created". */
+    readonly eventId: string;
+    /** Strongly-typed event payload. */
+    readonly payload: Record<string, unknown>;
+    /** ISO-8601 timestamp of when the event was emitted. */
+    readonly timestamp: string;
+    /** Unique ID for this delivery attempt. */
+    readonly deliveryId: string;
+  };
+  /** Subscription that triggered this delivery. */
+  readonly subscription: {
+    readonly id: string;
+    readonly name: string;
+  };
+}
+
+export declare function defineHealthCheck<
+  T extends
+    | HealthCheckScriptResult
+    | ((ctx: HealthCheckScriptContext) =>
+        | HealthCheckScriptResult
+        | Promise<HealthCheckScriptResult>),
+>(value: T): T;
+export declare function defineIntegration<
+  T extends
+    | IntegrationScriptResult
+    | void
+    | ((ctx: IntegrationScriptContext) =>
+        | IntegrationScriptResult
+        | void
+        | Promise<IntegrationScriptResult | void>),
+>(value: T): T;
+export type {
+  HealthCheckScriptResult,
+  HealthCheckScriptContext,
+  IntegrationScriptResult,
+  IntegrationScriptContext,
+};
+
+export type { InferClient, ClientDefinition } from "@checkstack/common";

package/generated/integration.d.ts

@@ -0,0 +1,47 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** Result emitted by an inline integration script. */
+interface IntegrationScriptResult {
+  /** External ID for tracking (e.g. ticket number, message ID). */
+  id?: string;
+  /** Same as `id` — accepted for backwards compatibility. */
+  externalId?: string;
+}
+
+/**
+ * Runtime context exposed to inline integration scripts. `event.payload`
+ * is typed from the event's payload schema so the fields it advertises
+ * are autocompletable inside the script.
+ */
+interface IntegrationScriptContext {
+  /** The event being delivered. */
+  readonly event: {
+    /** Fully-qualified event ID, e.g. "incident.created". */
+    readonly eventId: string;
+    /** Strongly-typed event payload. */
+    readonly payload: Record<string, unknown>;
+    /** ISO-8601 timestamp of when the event was emitted. */
+    readonly timestamp: string;
+    /** Unique ID for this delivery attempt. */
+    readonly deliveryId: string;
+  };
+  /** Subscription that triggered this delivery. */
+  readonly subscription: {
+    readonly id: string;
+    readonly name: string;
+  };
+}
+
+export declare function defineIntegration<
+  T extends
+    | IntegrationScriptResult
+    | void
+    | ((ctx: IntegrationScriptContext) =>
+        | IntegrationScriptResult
+        | void
+        | Promise<IntegrationScriptResult | void>),
+>(value: T): T;
+
+export type { IntegrationScriptResult, IntegrationScriptContext };

package/generated/version.d.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** The platform release version this SDK was stamped to. */
+export declare const SDK_RELEASE_VERSION: string;

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@checkstack/sdk",
+  "version": "0.94.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "description": "Auto-generated, version-pinned typed client and script-authoring helpers for Checkstack.",
+  "exports": {
+    ".": {
+      "types": "./generated/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./healthcheck": {
+      "types": "./generated/healthcheck.d.ts",
+      "default": "./src/healthcheck.ts"
+    },
+    "./integration": {
+      "types": "./generated/integration.d.ts",
+      "default": "./src/integration.ts"
+    },
+    "./editor-bundle": {
+      "types": "./generated/editor-bundle-module.d.ts",
+      "default": "./src/editor-bundle.ts"
+    },
+    "./version": {
+      "types": "./generated/version.d.ts",
+      "default": "./src/version.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/announcement-common": "0.4.2",
+    "@checkstack/anomaly-common": "1.2.3",
+    "@checkstack/auth-common": "0.7.2",
+    "@checkstack/automation-common": "0.3.0",
+    "@checkstack/cache-common": "0.4.2",
+    "@checkstack/catalog-common": "2.2.3",
+    "@checkstack/command-common": "0.2.14",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/dependency-common": "1.1.3",
+    "@checkstack/gitops-common": "0.5.0",
+    "@checkstack/healthcheck-common": "1.4.0",
+    "@checkstack/incident-common": "1.3.1",
+    "@checkstack/integration-common": "0.6.0",
+    "@checkstack/maintenance-common": "1.3.0",
+    "@checkstack/notification-common": "1.2.1",
+    "@checkstack/pluginmanager-common": "0.2.4",
+    "@checkstack/queue-common": "0.5.2",
+    "@checkstack/satellite-common": "0.7.0",
+    "@checkstack/script-packages-common": "0.2.0",
+    "@checkstack/secrets-common": "0.1.0",
+    "@checkstack/slo-common": "0.4.2",
+    "@checkstack/theme-common": "0.1.14",
+    "@checkstack/tips-common": "0.2.3",
+    "@orpc/client": "^1.14.4",
+    "@orpc/openapi-client": "^1.14.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.4"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/client.ts

@@ -0,0 +1,120 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+import { createORPCClient } from "@orpc/client";
+import { OpenAPILink } from "@orpc/openapi-client/fetch";
+import type { InferClient } from "@checkstack/common";
+import { AnnouncementApi } from "@checkstack/announcement-common";
+import { AnomalyApi } from "@checkstack/anomaly-common";
+import { AuthApi } from "@checkstack/auth-common";
+import { AutomationApi } from "@checkstack/automation-common";
+import { CacheApi } from "@checkstack/cache-common";
+import { CatalogApi } from "@checkstack/catalog-common";
+import { CommandApi } from "@checkstack/command-common";
+import { DependencyApi } from "@checkstack/dependency-common";
+import { GitOpsApi } from "@checkstack/gitops-common";
+import { HealthCheckApi } from "@checkstack/healthcheck-common";
+import { IncidentApi } from "@checkstack/incident-common";
+import { IntegrationApi } from "@checkstack/integration-common";
+import { MaintenanceApi } from "@checkstack/maintenance-common";
+import { NotificationApi } from "@checkstack/notification-common";
+import { PluginManagerApi } from "@checkstack/pluginmanager-common";
+import { QueueApi } from "@checkstack/queue-common";
+import { SatelliteApi } from "@checkstack/satellite-common";
+import { ScriptPackagesApi } from "@checkstack/script-packages-common";
+import { SecretsApi } from "@checkstack/secrets-common";
+import { SloApi } from "@checkstack/slo-common";
+import { ThemeApi } from "@checkstack/theme-common";
+import { TipsApi } from "@checkstack/tips-common";
+
+/**
+ * The fully-typed Checkstack API client. One entry per plugin id, mirroring
+ * the backend's root oRPC router nesting (`rootRpcRouter[pluginId]`). Each
+ * value is the contract's inferred client (`InferClient`).
+ */
+export interface CheckstackClient {
+  announcement: InferClient<typeof AnnouncementApi>;
+  anomaly: InferClient<typeof AnomalyApi>;
+  auth: InferClient<typeof AuthApi>;
+  automation: InferClient<typeof AutomationApi>;
+  cache: InferClient<typeof CacheApi>;
+  catalog: InferClient<typeof CatalogApi>;
+  command: InferClient<typeof CommandApi>;
+  dependency: InferClient<typeof DependencyApi>;
+  gitops: InferClient<typeof GitOpsApi>;
+  healthcheck: InferClient<typeof HealthCheckApi>;
+  incident: InferClient<typeof IncidentApi>;
+  integration: InferClient<typeof IntegrationApi>;
+  maintenance: InferClient<typeof MaintenanceApi>;
+  notification: InferClient<typeof NotificationApi>;
+  pluginmanager: InferClient<typeof PluginManagerApi>;
+  queue: InferClient<typeof QueueApi>;
+  satellite: InferClient<typeof SatelliteApi>;
+  "script-packages": InferClient<typeof ScriptPackagesApi>;
+  secrets: InferClient<typeof SecretsApi>;
+  slo: InferClient<typeof SloApi>;
+  theme: InferClient<typeof ThemeApi>;
+  tips: InferClient<typeof TipsApi>;
+}
+
+/** Options for {@link createCheckstackClient}. */
+export interface CreateCheckstackClientOptions {
+  /** Base URL of the Checkstack REST surface, e.g. `https://host/rest`. */
+  baseUrl: string;
+  /** Extra request headers, e.g. API-key / bearer auth. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * The nested contract router mirroring the backend's `/rest/:pluginId/*`
+ * surface. Passed to {@link OpenAPILink} so calls map to REST routes.
+ */
+const checkstackContract = {
+  announcement: AnnouncementApi.contract,
+  anomaly: AnomalyApi.contract,
+  auth: AuthApi.contract,
+  automation: AutomationApi.contract,
+  cache: CacheApi.contract,
+  catalog: CatalogApi.contract,
+  command: CommandApi.contract,
+  dependency: DependencyApi.contract,
+  gitops: GitOpsApi.contract,
+  healthcheck: HealthCheckApi.contract,
+  incident: IncidentApi.contract,
+  integration: IntegrationApi.contract,
+  maintenance: MaintenanceApi.contract,
+  notification: NotificationApi.contract,
+  pluginmanager: PluginManagerApi.contract,
+  queue: QueueApi.contract,
+  satellite: SatelliteApi.contract,
+  "script-packages": ScriptPackagesApi.contract,
+  secrets: SecretsApi.contract,
+  slo: SloApi.contract,
+  theme: ThemeApi.contract,
+  tips: TipsApi.contract,
+};
+
+/**
+ * Build a typed Checkstack client over the REST/OpenAPI surface
+ * (`/rest/:pluginId/*`). Each plugin is reachable under its plugin id.
+ */
+export function createCheckstackClient({
+  baseUrl,
+  headers,
+}: CreateCheckstackClientOptions): CheckstackClient {
+  // Strip trailing slashes without a backtracking-prone regex
+  // (`/\/+$/` is O(n^2) on inputs like "////...x" - CodeQL js/polynomial-redos).
+  let normalizedBase = baseUrl;
+  while (normalizedBase.endsWith("/")) normalizedBase = normalizedBase.slice(0, -1);
+  const link = new OpenAPILink(checkstackContract, {
+    url: normalizedBase,
+    headers: () => headers ?? {},
+  });
+  // oRPC's `createORPCClient` constrains its type param to an index-signature
+  // `NestedClient`, which a fixed-key interface like `CheckstackClient` cannot
+  // satisfy structurally. The runtime client IS the CheckstackClient shape
+  // (one entry per plugin contract), so cast through the oRPC-inferred client.
+  // Mirrors core/frontend/src/apis/rpc-api.ts.
+  return createORPCClient(link) as unknown as CheckstackClient;
+}

package/src/contracts.ts

@@ -0,0 +1,31 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/**
+ * Re-export of every per-plugin oRPC contract `ClientDefinition`. Each is
+ * the source-of-truth API surface the running backend serves at
+ * `/rest/:pluginId/*`.
+ */
+export { AnnouncementApi } from "@checkstack/announcement-common";
+export { AnomalyApi } from "@checkstack/anomaly-common";
+export { AuthApi } from "@checkstack/auth-common";
+export { AutomationApi } from "@checkstack/automation-common";
+export { CacheApi } from "@checkstack/cache-common";
+export { CatalogApi } from "@checkstack/catalog-common";
+export { CommandApi } from "@checkstack/command-common";
+export { DependencyApi } from "@checkstack/dependency-common";
+export { GitOpsApi } from "@checkstack/gitops-common";
+export { HealthCheckApi } from "@checkstack/healthcheck-common";
+export { IncidentApi } from "@checkstack/incident-common";
+export { IntegrationApi } from "@checkstack/integration-common";
+export { MaintenanceApi } from "@checkstack/maintenance-common";
+export { NotificationApi } from "@checkstack/notification-common";
+export { PluginManagerApi } from "@checkstack/pluginmanager-common";
+export { QueueApi } from "@checkstack/queue-common";
+export { SatelliteApi } from "@checkstack/satellite-common";
+export { ScriptPackagesApi } from "@checkstack/script-packages-common";
+export { SecretsApi } from "@checkstack/secrets-common";
+export { SloApi } from "@checkstack/slo-common";
+export { ThemeApi } from "@checkstack/theme-common";
+export { TipsApi } from "@checkstack/tips-common";

package/src/editor-bundle.ts

@@ -0,0 +1,13 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+// Runtime-importable copy of the editor bundle, served by the
+// @checkstack/sdk editor-types backend route (plan §6.1). Imported by
+// the BACKEND only - it embeds the full bundle text, which the frontend
+// must NOT bundle (it fetches the bundle live; see ./version.ts).
+
+/** The combined ambient `.d.ts` the in-app editor mounts into Monaco. */
+export const SDK_EDITOR_BUNDLE_DTS = "// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.\n// Run `bun run generate:sdk` after changing a *-common contract or the\n// script-context helper builders.\n\n// Combined ambient declarations served ONLY by the version-keyed editor\n// route and mounted into Monaco. NOT the `exports`-resolved declarations\n// (those are the per-subpath generated/*.d.ts). Declares the subpath module\n// names only - bare names are intentionally absent so an old import errors.\n//\n// Every declaration is module-scoped (no top-level globals): the editor\n// mounts this bundle alongside scriptContext.ts, which owns the global\n// `defineHealthCheck` / `defineIntegration` + schema-narrowed context types\n// (plan §6.2). Top-level globals here would duplicate those and error.\n\ndeclare module \"@checkstack/sdk/healthcheck\" {\n  /** Result emitted by an inline health-check script. */\n  interface HealthCheckScriptResult {\n    /** Whether the health check passed. */\n    success: boolean;\n    /** Optional status message — surfaces in the run detail. */\n    message?: string;\n    /** Optional numeric value — feeds the value chart + anomaly detection. */\n    value?: number;\n  }\n\n  /**\n   * Runtime context exposed to inline health-check scripts. `config` is\n   * typed from the collector's own JSON Schema, so the fields you've\n   * declared on the configuration are autocompletable inside the script.\n   */\n  interface HealthCheckScriptContext {\n    /** Strongly-typed collector configuration. */\n    readonly config: Record<string, unknown>;\n    /** Metadata about the health check this run is for. */\n    readonly check: {\n      /** The health check configuration id. */\n      readonly id: string;\n      /** The health check's display name (falls back to the id). */\n      readonly name: string;\n      /** The configured run interval, in seconds. */\n      readonly intervalSeconds: number;\n    };\n    /** Metadata about the system this check runs for. */\n    readonly system: {\n      /** The system id. */\n      readonly id: string;\n      /** The system's display name (falls back to the id). */\n      readonly name: string;\n    };\n  }\n\n  export function defineHealthCheck<\n    T extends\n      | HealthCheckScriptResult\n      | ((ctx: HealthCheckScriptContext) =>\n          | HealthCheckScriptResult\n          | Promise<HealthCheckScriptResult>),\n  >(value: T): T;\n  export type { HealthCheckScriptResult, HealthCheckScriptContext };\n}\n\ndeclare module \"@checkstack/sdk/integration\" {\n  /** Result emitted by an inline integration script. */\n  interface IntegrationScriptResult {\n    /** External ID for tracking (e.g. ticket number, message ID). */\n    id?: string;\n    /** Same as `id` — accepted for backwards compatibility. */\n    externalId?: string;\n  }\n\n  /**\n   * Runtime context exposed to inline integration scripts. `event.payload`\n   * is typed from the event's payload schema so the fields it advertises\n   * are autocompletable inside the script.\n   */\n  interface IntegrationScriptContext {\n    /** The event being delivered. */\n    readonly event: {\n      /** Fully-qualified event ID, e.g. \"incident.created\". */\n      readonly eventId: string;\n      /** Strongly-typed event payload. */\n      readonly payload: Record<string, unknown>;\n      /** ISO-8601 timestamp of when the event was emitted. */\n      readonly timestamp: string;\n      /** Unique ID for this delivery attempt. */\n      readonly deliveryId: string;\n    };\n    /** Subscription that triggered this delivery. */\n    readonly subscription: {\n      readonly id: string;\n      readonly name: string;\n    };\n  }\n\n  export function defineIntegration<\n    T extends\n      | IntegrationScriptResult\n      | void\n      | ((ctx: IntegrationScriptContext) =>\n          | IntegrationScriptResult\n          | void\n          | Promise<IntegrationScriptResult | void>),\n  >(value: T): T;\n  export type { IntegrationScriptResult, IntegrationScriptContext };\n}\n\ndeclare module \"@checkstack/sdk\" {\n  export { defineHealthCheck } from \"@checkstack/sdk/healthcheck\";\n  export type { HealthCheckScriptResult, HealthCheckScriptContext } from \"@checkstack/sdk/healthcheck\";\n  export { defineIntegration } from \"@checkstack/sdk/integration\";\n  export type { IntegrationScriptResult, IntegrationScriptContext } from \"@checkstack/sdk/integration\";\n  export interface CreateCheckstackClientOptions {\n    baseUrl: string;\n    headers?: Record<string, string>;\n  }\n  /** The fully-typed Checkstack API client (one entry per plugin id). */\n  export type CheckstackClient = Record<string, unknown>;\n  /** Build a typed Checkstack client over the REST/OpenAPI surface. */\n  export function createCheckstackClient(\n    options: CreateCheckstackClientOptions,\n  ): CheckstackClient;\n}\n";
+
+export { SDK_RELEASE_VERSION } from "./version.ts";

package/src/healthcheck.ts

@@ -0,0 +1,57 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** Result emitted by an inline health-check script. */
+interface HealthCheckScriptResult {
+  /** Whether the health check passed. */
+  success: boolean;
+  /** Optional status message — surfaces in the run detail. */
+  message?: string;
+  /** Optional numeric value — feeds the value chart + anomaly detection. */
+  value?: number;
+}
+
+/**
+ * Runtime context exposed to inline health-check scripts. `config` is
+ * typed from the collector's own JSON Schema, so the fields you've
+ * declared on the configuration are autocompletable inside the script.
+ */
+interface HealthCheckScriptContext {
+  /** Strongly-typed collector configuration. */
+  readonly config: Record<string, unknown>;
+  /** Metadata about the health check this run is for. */
+  readonly check: {
+    /** The health check configuration id. */
+    readonly id: string;
+    /** The health check's display name (falls back to the id). */
+    readonly name: string;
+    /** The configured run interval, in seconds. */
+    readonly intervalSeconds: number;
+  };
+  /** Metadata about the system this check runs for. */
+  readonly system: {
+    /** The system id. */
+    readonly id: string;
+    /** The system's display name (falls back to the id). */
+    readonly name: string;
+  };
+}
+
+export type { HealthCheckScriptResult, HealthCheckScriptContext };
+
+/**
+ * Identity helper for defineHealthCheck scripts. The value is returned unchanged at
+ * runtime - the function only narrows what `export default` may be so
+ * mistakes are caught before the script runs. Matches the in-app runner's
+ * injected helper body exactly (esm-script-runner identity rewrite).
+ */
+export function defineHealthCheck<
+  T extends
+    | HealthCheckScriptResult
+    | ((ctx: HealthCheckScriptContext) =>
+        | HealthCheckScriptResult
+        | Promise<HealthCheckScriptResult>),
+>(value: T): T {
+  return value;
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+export * from "./contracts.ts";
+export * from "./client.ts";
+export * from "./healthcheck.ts";
+export * from "./integration.ts";
+export type { InferClient, ClientDefinition } from "@checkstack/common";

package/src/integration.ts

@@ -0,0 +1,55 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** Result emitted by an inline integration script. */
+interface IntegrationScriptResult {
+  /** External ID for tracking (e.g. ticket number, message ID). */
+  id?: string;
+  /** Same as `id` — accepted for backwards compatibility. */
+  externalId?: string;
+}
+
+/**
+ * Runtime context exposed to inline integration scripts. `event.payload`
+ * is typed from the event's payload schema so the fields it advertises
+ * are autocompletable inside the script.
+ */
+interface IntegrationScriptContext {
+  /** The event being delivered. */
+  readonly event: {
+    /** Fully-qualified event ID, e.g. "incident.created". */
+    readonly eventId: string;
+    /** Strongly-typed event payload. */
+    readonly payload: Record<string, unknown>;
+    /** ISO-8601 timestamp of when the event was emitted. */
+    readonly timestamp: string;
+    /** Unique ID for this delivery attempt. */
+    readonly deliveryId: string;
+  };
+  /** Subscription that triggered this delivery. */
+  readonly subscription: {
+    readonly id: string;
+    readonly name: string;
+  };
+}
+
+export type { IntegrationScriptResult, IntegrationScriptContext };
+
+/**
+ * Identity helper for defineIntegration scripts. The value is returned unchanged at
+ * runtime - the function only narrows what `export default` may be so
+ * mistakes are caught before the script runs. Matches the in-app runner's
+ * injected helper body exactly (esm-script-runner identity rewrite).
+ */
+export function defineIntegration<
+  T extends
+    | IntegrationScriptResult
+    | void
+    | ((ctx: IntegrationScriptContext) =>
+        | IntegrationScriptResult
+        | void
+        | Promise<IntegrationScriptResult | void>),
+>(value: T): T {
+  return value;
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/generate-sdk.ts - DO NOT EDIT BY HAND.
+// Run `bun run generate:sdk` after changing a *-common contract or the
+// script-context helper builders.
+
+/** The platform release version this SDK was stamped to. */
+export const SDK_RELEASE_VERSION = "0.94.0";

package/test/client.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { createCheckstackClient } from "../src/client.ts";
+import { defineHealthCheck } from "../src/healthcheck.ts";
+import { defineIntegration } from "../src/integration.ts";
+
+describe("createCheckstackClient", () => {
+  test("builds a client with one entry per plugin id", () => {
+    const client = createCheckstackClient({ baseUrl: "https://host/rest" });
+
+    // A representative spread across the plugin surface, including the
+    // hyphenated id which must be a quoted key.
+    expect(client.healthcheck).toBeDefined();
+    expect(client.integration).toBeDefined();
+    expect(client.automation).toBeDefined();
+    expect(client["script-packages"]).toBeDefined();
+    expect(client.auth).toBeDefined();
+  });
+
+  test("accepts custom headers without throwing", () => {
+    const client = createCheckstackClient({
+      baseUrl: "https://host/rest/",
+      headers: { authorization: "Bearer token" },
+    });
+    expect(client.tips).toBeDefined();
+  });
+});
+
+describe("script helpers (identity runtime)", () => {
+  test("defineHealthCheck returns its argument unchanged", () => {
+    const result = { success: true, value: 42 };
+    expect(defineHealthCheck(result)).toBe(result);
+
+    const fn = () => ({ success: false, message: "down" });
+    expect(defineHealthCheck(fn)).toBe(fn);
+  });
+
+  test("defineIntegration returns its argument unchanged", () => {
+    const result = { id: "ticket-1" };
+    expect(defineIntegration(result)).toBe(result);
+
+    const fn = async () => ({ externalId: "x" });
+    expect(defineIntegration(fn)).toBe(fn);
+  });
+});

package/test/fixtures/consumer-cross-subpath.ts

@@ -0,0 +1,8 @@
+// Fixture (NEGATIVE): proves per-subpath isolation. `defineIntegration` is
+// NOT part of the `@checkstack/sdk/healthcheck` surface, so importing it from
+// that subpath MUST be a resolution/type error (TS2305). If this ever
+// compiles, the subpaths are sharing a declaration file and the per-subpath
+// `.d.ts` guarantee is broken.
+import { defineIntegration } from "@checkstack/sdk/healthcheck";
+
+export const x = defineIntegration;

package/test/fixtures/consumer-good.ts

@@ -0,0 +1,28 @@
+// Fixture: an external consumer importing the self-contained helper subpaths.
+// Under `nodenext`/`node16` module resolution, each subpath MUST resolve
+// through the package's `exports` map to its OWN per-subpath `.d.ts`
+// (generated/healthcheck.d.ts, generated/integration.d.ts) — not a shared
+// ambient file. This file MUST typecheck cleanly.
+import {
+  defineHealthCheck,
+  type HealthCheckScriptContext,
+  type HealthCheckScriptResult,
+} from "@checkstack/sdk/healthcheck";
+import {
+  defineIntegration,
+  type IntegrationScriptContext,
+  type IntegrationScriptResult,
+} from "@checkstack/sdk/integration";
+
+const hcResult: HealthCheckScriptResult = { success: true, value: 1 };
+const intgResult: IntegrationScriptResult = { id: "x" };
+
+export const hc = defineHealthCheck((ctx: HealthCheckScriptContext) => ({
+  success: ctx.check.intervalSeconds > 0,
+  value: hcResult.value,
+}));
+
+export const intg = defineIntegration((ctx: IntegrationScriptContext) => ({
+  id: ctx.event.deliveryId,
+  externalId: intgResult.id,
+}));

package/test/subpath-resolution.test.ts

@@ -0,0 +1,121 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+/**
+ * LOAD-BEARING resolution test (plan §4.1, §9 Phase-1 row 4).
+ *
+ * Asserts that under `nodenext` module resolution an external consumer
+ * resolves `@checkstack/sdk/healthcheck` and `@checkstack/sdk/integration`
+ * through the package's `exports` map to EXACTLY their own per-subpath
+ * `.d.ts` — not a shared ambient file. The negative fixture proves the two
+ * subpaths do not bleed into each other.
+ *
+ * The package is symlinked into a temp `node_modules/@checkstack/sdk` so the
+ * REAL `exports` map drives resolution (a `paths` mapping would bypass it and
+ * defeat the test).
+ */
+
+const REPO_ROOT = path.resolve(import.meta.dirname, "..", "..", "..");
+const SDK_PKG_DIR = path.resolve(import.meta.dirname, "..");
+const FIXTURES_DIR = path.join(import.meta.dirname, "fixtures");
+const TSC = path.join(REPO_ROOT, "node_modules", ".bin", "tsc");
+
+const NODENEXT_COMPILER_OPTIONS = {
+  module: "nodenext",
+  moduleResolution: "nodenext",
+  target: "esnext",
+  strict: true,
+  noEmit: true,
+  skipLibCheck: true,
+  // No ambient libs — the subpath `.d.ts` must stand alone.
+  types: [] as string[],
+};
+
+let workDir: string;
+
+function runTsc({
+  consumer,
+  tsconfigName,
+}: {
+  consumer: string;
+  tsconfigName: string;
+}) {
+  const tsconfigPath = path.join(workDir, tsconfigName);
+  writeFileSync(
+    tsconfigPath,
+    JSON.stringify(
+      {
+        compilerOptions: NODENEXT_COMPILER_OPTIONS,
+        include: [consumer],
+      },
+      undefined,
+      2,
+    ),
+    "utf8",
+  );
+  return spawnSync(TSC, ["-p", tsconfigPath], {
+    cwd: workDir,
+    encoding: "utf8",
+  });
+}
+
+beforeAll(() => {
+  workDir = mkdtempSync(path.join(tmpdir(), "checkstack-sdk-resolution-"));
+  mkdirSync(path.join(workDir, "node_modules", "@checkstack"), {
+    recursive: true,
+  });
+  symlinkSync(
+    SDK_PKG_DIR,
+    path.join(workDir, "node_modules", "@checkstack", "sdk"),
+    "dir",
+  );
+});
+
+afterAll(() => {
+  if (workDir) rmSync(workDir, { recursive: true, force: true });
+});
+
+describe("@checkstack/sdk subpath exports (nodenext)", () => {
+  test("healthcheck + integration subpaths resolve to their own surface", async () => {
+    // Materialize fixture contents synchronously for tsc.
+    writeFileSync(
+      path.join(workDir, "consumer-good.ts"),
+      await Bun.file(path.join(FIXTURES_DIR, "consumer-good.ts")).text(),
+      "utf8",
+    );
+    const result = runTsc({
+      consumer: "consumer-good.ts",
+      tsconfigName: "tsconfig.good.json",
+    });
+    if (result.status !== 0) {
+      console.error(result.stdout, result.stderr);
+    }
+    expect(result.status).toBe(0);
+  });
+
+  test("importing a foreign helper from a subpath is a resolution error", async () => {
+    writeFileSync(
+      path.join(workDir, "consumer-cross-subpath.ts"),
+      await Bun.file(
+        path.join(FIXTURES_DIR, "consumer-cross-subpath.ts"),
+      ).text(),
+      "utf8",
+    );
+    const result = runTsc({
+      consumer: "consumer-cross-subpath.ts",
+      tsconfigName: "tsconfig.cross.json",
+    });
+    expect(result.status).not.toBe(0);
+    // TS2305: Module has no exported member 'defineIntegration'.
+    expect(result.stdout + result.stderr).toContain("defineIntegration");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,78 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src",
+    "generated"
+  ],
+  "references": [
+    {
+      "path": "../announcement-common"
+    },
+    {
+      "path": "../anomaly-common"
+    },
+    {
+      "path": "../auth-common"
+    },
+    {
+      "path": "../automation-common"
+    },
+    {
+      "path": "../cache-common"
+    },
+    {
+      "path": "../catalog-common"
+    },
+    {
+      "path": "../command-common"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../dependency-common"
+    },
+    {
+      "path": "../gitops-common"
+    },
+    {
+      "path": "../healthcheck-common"
+    },
+    {
+      "path": "../incident-common"
+    },
+    {
+      "path": "../integration-common"
+    },
+    {
+      "path": "../maintenance-common"
+    },
+    {
+      "path": "../notification-common"
+    },
+    {
+      "path": "../pluginmanager-common"
+    },
+    {
+      "path": "../queue-common"
+    },
+    {
+      "path": "../satellite-common"
+    },
+    {
+      "path": "../script-packages-common"
+    },
+    {
+      "path": "../secrets-common"
+    },
+    {
+      "path": "../slo-common"
+    },
+    {
+      "path": "../theme-common"
+    },
+    {
+      "path": "../tips-common"
+    }
+  ]
+}