@checkstack/integration-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# @checkstack/integration-common
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/common@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 4dd644d: Enable external application (API key) access to management endpoints
+
+  Changed `userType: "user"` to `userType: "authenticated"` for 52 endpoints across 5 packages, allowing external applications (service accounts with API keys) to call these endpoints programmatically while maintaining RBAC permission checks:
+
+  - **incident-common**: createIncident, updateIncident, addUpdate, resolveIncident, deleteIncident
+  - **maintenance-common**: createMaintenance, updateMaintenance, addUpdate, closeMaintenance, deleteMaintenance
+  - **catalog-common**: System CRUD, Group CRUD, addSystemToGroup, removeSystemFromGroup
+  - **healthcheck-common**: Configuration management, system associations, retention config, detailed history
+  - **integration-common**: Subscription management, connection management, event discovery, delivery logs
+
+  This enables automation use cases such as:
+
+  - Creating incidents from external monitoring systems (Prometheus, Grafana)
+  - Scheduling maintenances from CI/CD pipelines
+  - Managing catalog systems from infrastructure-as-code tools
+  - Configuring health checks from deployment scripts
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [b55fae6]
+  - @checkstack/common@0.1.0
+  - @checkstack/signal-common@0.1.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@checkstack/integration-common",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@checkstack/signal-common": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.7.2",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+// Schemas - Zod validators for API contracts
+export {
+  // Delivery status
+  DeliveryStatusSchema,
+  type DeliveryStatus,
+  // Webhook subscriptions
+  WebhookSubscriptionSchema,
+  type WebhookSubscription,
+  CreateSubscriptionInputSchema,
+  type CreateSubscriptionInput,
+  UpdateSubscriptionInputSchema,
+  type UpdateSubscriptionInput,
+  // Delivery logs
+  DeliveryLogSchema,
+  type DeliveryLog,
+  DeliveryLogQueryInputSchema,
+  type DeliveryLogQueryInput,
+  // Provider info
+  IntegrationProviderInfoSchema,
+  type IntegrationProviderInfo,
+  // Event info
+  IntegrationEventInfoSchema,
+  type IntegrationEventInfo,
+  // Result schemas (for API validation)
+  IntegrationDeliveryResultSchema,
+  TestConnectionResultSchema,
+  // Connection management
+  ProviderConnectionSchema,
+  type ProviderConnection,
+  ProviderConnectionRedactedSchema,
+  type ProviderConnectionRedacted,
+  CreateConnectionInputSchema,
+  type CreateConnectionInput,
+  UpdateConnectionInputSchema,
+  type UpdateConnectionInput,
+  GetConnectionOptionsInputSchema,
+  type GetConnectionOptionsInput,
+  ConnectionOptionSchema,
+  type ConnectionOptionOutput,
+  // Payload property hints
+  PayloadPropertySchema,
+  type PayloadProperty,
+  EventPayloadSchemaOutputSchema,
+  type EventPayloadSchemaOutput,
+} from "./schemas";
+
+// NOTE: All backend-only types (IntegrationProvider, IntegrationDeliveryContext, etc.)
+// are defined in @checkstack/integration-backend/provider-types.
+// Frontend code should only use the Zod schemas above for API contracts.
+
+// Permissions
+export * from "./permissions";
+
+// RPC Contract
+export * from "./rpc-contract";
+
+// Signals
+export * from "./signals";
+
+// Plugin Metadata
+export * from "./plugin-metadata";
+
+// Routes
+export { integrationRoutes } from "./routes";

package/src/permissions.ts

@@ -0,0 +1,12 @@
+import { createPermission } from "@checkstack/common";
+
+export const permissions = {
+  /** Manage webhook integrations and view delivery logs */
+  integrationManage: createPermission(
+    "integration",
+    "manage",
+    "Manage webhook integrations and view delivery logs"
+  ),
+};
+
+export const permissionList = Object.values(permissions);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the integration plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "integration",
+});

package/src/routes.ts

@@ -0,0 +1,15 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the integration plugin.
+ */
+export const integrationRoutes = createRoutes("integration", {
+  /** Main integrations management page */
+  list: "/",
+  /** Delivery logs page (all logs) */
+  logs: "/logs",
+  /** Delivery logs filtered by subscription */
+  deliveryLogs: "/logs/:subscriptionId",
+  /** Provider connections management */
+  connections: "/connections/:providerId",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,311 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { permissions } from "./permissions";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkstack/common";
+import {
+  WebhookSubscriptionSchema,
+  CreateSubscriptionInputSchema,
+  UpdateSubscriptionInputSchema,
+  DeliveryLogSchema,
+  DeliveryLogQueryInputSchema,
+  IntegrationProviderInfoSchema,
+  IntegrationEventInfoSchema,
+  TestConnectionResultSchema,
+  ProviderConnectionRedactedSchema,
+  CreateConnectionInputSchema,
+  UpdateConnectionInputSchema,
+  GetConnectionOptionsInputSchema,
+  ConnectionOptionSchema,
+  EventPayloadSchemaOutputSchema,
+} from "./schemas";
+
+// Base builder with full metadata support (userType + permissions)
+const _base = oc.$meta<ProcedureMetadata>({});
+
+// Integration RPC Contract
+export const integrationContract = {
+  // ==========================================================================
+  // SUBSCRIPTION MANAGEMENT (Admin only)
+  // ==========================================================================
+
+  /** List all webhook subscriptions */
+  listSubscriptions: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(
+      z.object({
+        page: z.number().min(1).default(1),
+        pageSize: z.number().min(1).max(100).default(20),
+        providerId: z.string().optional(),
+        eventType: z.string().optional(),
+        enabled: z.boolean().optional(),
+      })
+    )
+    .output(
+      z.object({
+        subscriptions: z.array(WebhookSubscriptionSchema),
+        total: z.number(),
+      })
+    ),
+
+  /** Get a single subscription by ID */
+  getSubscription: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(WebhookSubscriptionSchema),
+
+  /** Create a new webhook subscription */
+  createSubscription: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(CreateSubscriptionInputSchema)
+    .output(WebhookSubscriptionSchema),
+
+  /** Update an existing subscription */
+  updateSubscription: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(UpdateSubscriptionInputSchema)
+    .output(WebhookSubscriptionSchema),
+
+  /** Delete a subscription */
+  deleteSubscription: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /** Toggle subscription enabled state */
+  toggleSubscription: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ id: z.string(), enabled: z.boolean() }))
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // PROVIDER DISCOVERY (Admin only)
+  // ==========================================================================
+
+  /** List all registered integration providers */
+  listProviders: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .output(z.array(IntegrationProviderInfoSchema)),
+
+  /** Test a provider connection with given config */
+  testProviderConnection: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(
+      z.object({
+        providerId: z.string(),
+        config: z.record(z.string(), z.unknown()),
+      })
+    )
+    .output(TestConnectionResultSchema),
+
+  // ==========================================================================
+  // CONNECTION MANAGEMENT (Admin only)
+  // Generic CRUD for site-wide provider connections
+  // ==========================================================================
+
+  /** List all connections for a provider */
+  listConnections: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ providerId: z.string() }))
+    .output(z.array(ProviderConnectionRedactedSchema)),
+
+  /** Get a single connection (redacted) */
+  getConnection: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ connectionId: z.string() }))
+    .output(ProviderConnectionRedactedSchema),
+
+  /** Create a new provider connection */
+  createConnection: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(CreateConnectionInputSchema)
+    .output(ProviderConnectionRedactedSchema),
+
+  /** Update a provider connection */
+  updateConnection: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(UpdateConnectionInputSchema)
+    .output(ProviderConnectionRedactedSchema),
+
+  /** Delete a provider connection */
+  deleteConnection: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ connectionId: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /** Test a saved connection */
+  testConnection: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ connectionId: z.string() }))
+    .output(TestConnectionResultSchema),
+
+  /** Get dynamic options for cascading dropdowns */
+  getConnectionOptions: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(GetConnectionOptionsInputSchema)
+    .output(z.array(ConnectionOptionSchema)),
+
+  // ==========================================================================
+  // EVENT DISCOVERY (Admin only)
+  // ==========================================================================
+
+  /** List all registered integration events */
+  listEventTypes: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .output(z.array(IntegrationEventInfoSchema)),
+
+  /** Get events grouped by category */
+  getEventsByCategory: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .output(
+      z.array(
+        z.object({
+          category: z.string(),
+          events: z.array(IntegrationEventInfoSchema),
+        })
+      )
+    ),
+
+  /** Get payload schema for a specific event with flattened property list for template hints */
+  getEventPayloadSchema: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ eventId: z.string() }))
+    .output(EventPayloadSchemaOutputSchema),
+
+  // ==========================================================================
+  // DELIVERY LOGS (Admin only)
+  // ==========================================================================
+
+  /** Get delivery logs with filtering */
+  getDeliveryLogs: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(DeliveryLogQueryInputSchema)
+    .output(
+      z.object({
+        logs: z.array(DeliveryLogSchema),
+        total: z.number(),
+      })
+    ),
+
+  /** Get a single delivery log entry */
+  getDeliveryLog: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(DeliveryLogSchema),
+
+  /** Retry a failed delivery */
+  retryDelivery: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(z.object({ logId: z.string() }))
+    .output(z.object({ success: z.boolean(), message: z.string().optional() })),
+
+  /** Get delivery statistics for dashboard */
+  getDeliveryStats: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.integrationManage.id],
+    })
+    .input(
+      z.object({
+        /** Time range in hours (default: 24) */
+        hours: z.number().min(1).max(720).default(24),
+      })
+    )
+    .output(
+      z.object({
+        total: z.number(),
+        successful: z.number(),
+        failed: z.number(),
+        retrying: z.number(),
+        pending: z.number(),
+        byEvent: z.array(
+          z.object({
+            eventType: z.string(),
+            count: z.number(),
+          })
+        ),
+        byProvider: z.array(
+          z.object({
+            providerId: z.string(),
+            count: z.number(),
+          })
+        ),
+      })
+    ),
+};
+
+// Export contract type
+export type IntegrationContract = typeof integrationContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(IntegrationApi);
+export const IntegrationApi = createClientDefinition(
+  integrationContract,
+  pluginMetadata
+);

package/src/schemas.ts

@@ -0,0 +1,306 @@
+import { z } from "zod";
+
+// =============================================================================
+// Webhook Subscription Schemas
+// =============================================================================
+
+/** Status of a webhook delivery attempt */
+export const DeliveryStatusSchema = z.enum([
+  "pending",
+  "success",
+  "failed",
+  "retrying",
+]);
+export type DeliveryStatus = z.infer<typeof DeliveryStatusSchema>;
+
+/** Webhook subscription configuration */
+export const WebhookSubscriptionSchema = z.object({
+  id: z.string(),
+  name: z.string().min(1).max(100),
+  description: z.string().optional(),
+
+  /** Fully qualified provider ID: {pluginId}.{providerId} */
+  providerId: z.string(),
+
+  /** Provider-specific configuration (validated against provider schema) */
+  providerConfig: z.record(z.string(), z.unknown()),
+
+  /** Single event to subscribe to (fully qualified event ID) */
+  eventId: z.string(),
+
+  /** Optional: Filter by system IDs */
+  systemFilter: z.array(z.string()).optional(),
+
+  /** Subscription state */
+  enabled: z.boolean().default(true),
+
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+});
+export type WebhookSubscription = z.infer<typeof WebhookSubscriptionSchema>;
+
+/** Input for creating a webhook subscription */
+export const CreateSubscriptionInputSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().optional(),
+  providerId: z.string(),
+  providerConfig: z.record(z.string(), z.unknown()),
+  /** Single event to subscribe to */
+  eventId: z.string(),
+  systemFilter: z.array(z.string()).optional(),
+});
+export type CreateSubscriptionInput = z.infer<
+  typeof CreateSubscriptionInputSchema
+>;
+
+/** Input for updating a webhook subscription */
+export const UpdateSubscriptionInputSchema = z.object({
+  id: z.string(),
+  updates: z.object({
+    name: z.string().min(1).max(100).optional(),
+    description: z.string().optional(),
+    providerConfig: z.record(z.string(), z.unknown()).optional(),
+    eventId: z.string().optional(),
+    systemFilter: z.array(z.string()).optional(),
+    enabled: z.boolean().optional(),
+  }),
+});
+export type UpdateSubscriptionInput = z.infer<
+  typeof UpdateSubscriptionInputSchema
+>;
+
+// =============================================================================
+// Delivery Log Schemas
+// =============================================================================
+
+/** Delivery log entry */
+export const DeliveryLogSchema = z.object({
+  id: z.string(),
+  subscriptionId: z.string(),
+  subscriptionName: z.string().optional(),
+
+  eventType: z.string(),
+  eventPayload: z.record(z.string(), z.unknown()),
+
+  status: DeliveryStatusSchema,
+  attempts: z.number(),
+  lastAttemptAt: z.coerce.date().optional(),
+  nextRetryAt: z.coerce.date().optional(),
+
+  externalId: z.string().optional(),
+  errorMessage: z.string().optional(),
+
+  createdAt: z.coerce.date(),
+});
+export type DeliveryLog = z.infer<typeof DeliveryLogSchema>;
+
+/** Input for querying delivery logs */
+export const DeliveryLogQueryInputSchema = z.object({
+  subscriptionId: z.string().optional(),
+  eventType: z.string().optional(),
+  status: DeliveryStatusSchema.optional(),
+  page: z.number().min(1).default(1),
+  pageSize: z.number().min(1).max(100).default(20),
+});
+export type DeliveryLogQueryInput = z.infer<typeof DeliveryLogQueryInputSchema>;
+
+// =============================================================================
+// Integration Provider Schemas
+// =============================================================================
+
+/** Documentation schema for provider setup help */
+export const ProviderDocumentationSchema = z
+  .object({
+    /** Brief setup instructions (rendered as markdown) */
+    setupGuide: z.string().optional(),
+    /** Example request body (JSON string for syntax highlighting) */
+    examplePayload: z.string().optional(),
+    /** HTTP headers that will be sent with each request */
+    headers: z
+      .array(
+        z.object({
+          name: z.string(),
+          description: z.string(),
+        })
+      )
+      .optional(),
+    /** Link to external documentation */
+    externalDocsUrl: z.string().url().optional(),
+  })
+  .optional();
+
+/** Provider info for API responses */
+export const IntegrationProviderInfoSchema = z.object({
+  /** Qualified ID: {pluginId}.{providerId} */
+  qualifiedId: z.string(),
+  /** Display name */
+  displayName: z.string(),
+  /** Description */
+  description: z.string().optional(),
+  /** Lucide icon name */
+  icon: z.string().optional(),
+  /** Owner plugin ID */
+  ownerPluginId: z.string(),
+  /** Events this provider can handle (undefined = all) */
+  supportedEvents: z.array(z.string()).optional(),
+  /** JSON Schema for provider config (for DynamicForm) */
+  configSchema: z.record(z.string(), z.unknown()),
+  /** Whether this provider has a connectionSchema (requires connection management) */
+  hasConnectionSchema: z.boolean().default(false),
+  /** JSON Schema for connection config (for DynamicForm in connection management) */
+  connectionSchema: z.record(z.string(), z.unknown()).optional(),
+  /** Optional documentation to help users configure their endpoints */
+  documentation: ProviderDocumentationSchema,
+});
+export type IntegrationProviderInfo = z.infer<
+  typeof IntegrationProviderInfoSchema
+>;
+
+// =============================================================================
+// Provider Connection Schemas
+// =============================================================================
+
+/** Provider connection record (site-wide credentials) */
+export const ProviderConnectionSchema = z.object({
+  /** Unique connection ID */
+  id: z.string(),
+  /** Qualified provider ID this connection belongs to */
+  providerId: z.string(),
+  /** Display name for this connection */
+  name: z.string().min(1).max(100),
+  /** Connection configuration (provider-specific, secrets redacted for API) */
+  config: z.record(z.string(), z.unknown()),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+});
+export type ProviderConnection = z.infer<typeof ProviderConnectionSchema>;
+
+/** Redacted connection for API responses (no secrets) */
+export const ProviderConnectionRedactedSchema = z.object({
+  id: z.string(),
+  providerId: z.string(),
+  name: z.string(),
+  /** Redacted config (secret fields removed) */
+  configPreview: z.record(z.string(), z.unknown()),
+  createdAt: z.coerce.date(),
+  updatedAt: z.coerce.date(),
+});
+export type ProviderConnectionRedacted = z.infer<
+  typeof ProviderConnectionRedactedSchema
+>;
+
+/** Input for creating a provider connection */
+export const CreateConnectionInputSchema = z.object({
+  /** Qualified provider ID */
+  providerId: z.string(),
+  /** Display name */
+  name: z.string().min(1).max(100),
+  /** Provider-specific connection config (validated against connectionSchema) */
+  config: z.record(z.string(), z.unknown()),
+});
+export type CreateConnectionInput = z.infer<typeof CreateConnectionInputSchema>;
+
+/** Input for updating a provider connection */
+export const UpdateConnectionInputSchema = z.object({
+  connectionId: z.string(),
+  updates: z.object({
+    name: z.string().min(1).max(100).optional(),
+    /** Partial config update (only provided fields are updated) */
+    config: z.record(z.string(), z.unknown()).optional(),
+  }),
+});
+export type UpdateConnectionInput = z.infer<typeof UpdateConnectionInputSchema>;
+
+/** Input for getting connection options (cascading dropdowns) */
+export const GetConnectionOptionsInputSchema = z.object({
+  providerId: z.string(),
+  connectionId: z.string(),
+  resolverName: z.string(),
+  context: z.record(z.string(), z.unknown()).default({}),
+});
+export type GetConnectionOptionsInput = z.infer<
+  typeof GetConnectionOptionsInputSchema
+>;
+
+/** Option returned from getConnectionOptions */
+export const ConnectionOptionSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+});
+export type ConnectionOptionOutput = z.infer<typeof ConnectionOptionSchema>;
+
+// =============================================================================
+// Integration Event Schemas
+// =============================================================================
+
+/** Integration event info for API responses */
+export const IntegrationEventInfoSchema = z.object({
+  /** Fully qualified event ID: {pluginId}.{hookId} */
+  eventId: z.string(),
+  /** Display name for UI */
+  displayName: z.string(),
+  /** Description of when this event fires */
+  description: z.string().optional(),
+  /** Category for UI grouping */
+  category: z.string().optional(),
+  /** Owner plugin ID */
+  ownerPluginId: z.string(),
+  /** JSON Schema for payload preview */
+  payloadSchema: z.record(z.string(), z.unknown()),
+});
+export type IntegrationEventInfo = z.infer<typeof IntegrationEventInfoSchema>;
+
+// =============================================================================
+// Delivery Result Schema
+// =============================================================================
+
+/** Result of a provider delivery attempt */
+export const IntegrationDeliveryResultSchema = z.object({
+  success: z.boolean(),
+  externalId: z.string().optional(),
+  error: z.string().optional(),
+  retryAfterMs: z.number().optional(),
+});
+export type IntegrationDeliveryResult = z.infer<
+  typeof IntegrationDeliveryResultSchema
+>;
+
+// =============================================================================
+// Test Connection Schema
+// =============================================================================
+
+/** Result of testing a provider connection */
+export const TestConnectionResultSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional(),
+});
+export type TestConnectionResult = z.infer<typeof TestConnectionResultSchema>;
+
+// =============================================================================
+// Payload Property Schema (for template hints)
+// =============================================================================
+
+/** A single payload property available for templating */
+export const PayloadPropertySchema = z.object({
+  /** Full path to the property, e.g., "payload.incident.title" */
+  path: z.string(),
+  /** Type of the property, e.g., "string", "number", "boolean" */
+  type: z.string(),
+  /** Optional description of the property */
+  description: z.string().optional(),
+});
+export type PayloadProperty = z.infer<typeof PayloadPropertySchema>;
+
+/** Output schema for getEventPayloadSchema */
+export const EventPayloadSchemaOutputSchema = z.object({
+  /** Event ID */
+  eventId: z.string(),
+  /** Full JSON Schema for the payload */
+  payloadSchema: z.record(z.string(), z.unknown()),
+  /** Flattened list of available properties for template hints */
+  availableProperties: z.array(PayloadPropertySchema),
+});
+export type EventPayloadSchemaOutput = z.infer<
+  typeof EventPayloadSchemaOutputSchema
+>;

package/src/signals.ts

@@ -0,0 +1,31 @@
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+import { DeliveryStatusSchema } from "./schemas";
+
+/**
+ * Signal emitted when a delivery completes (success or failure).
+ * Used to update the delivery logs UI in real-time.
+ */
+export const INTEGRATION_DELIVERY_COMPLETED = createSignal(
+  "INTEGRATION_DELIVERY_COMPLETED",
+  z.object({
+    logId: z.string(),
+    subscriptionId: z.string(),
+    eventType: z.string(),
+    status: DeliveryStatusSchema,
+    externalId: z.string().optional(),
+    errorMessage: z.string().optional(),
+  })
+);
+
+/**
+ * Signal emitted when a subscription is created, updated, or deleted.
+ * Used to refresh the subscriptions list in real-time.
+ */
+export const INTEGRATION_SUBSCRIPTION_CHANGED = createSignal(
+  "INTEGRATION_SUBSCRIPTION_CHANGED",
+  z.object({
+    action: z.enum(["created", "updated", "deleted"]),
+    subscriptionId: z.string(),
+  })
+);

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}