@devramps/sdk-typescript 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DevRamps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,461 @@
+# @devramps/step-sdk
+
+SDK for building custom deployment steps for DevRamps. Create simple one-shot steps or polling steps for long-running operations, with optional approval workflows.
+
+## Installation
+
+```bash
+npm install @devramps/step-sdk
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0
+
+## Quick Start
+
+### Simple Step
+
+A simple step runs once and returns a result.
+
+```typescript
+import { SimpleStep, Step, StepOutputs, StepRegistry } from "@devramps/step-sdk";
+import { z } from "zod";
+
+// Define your input schema
+const DeploySchema = z.object({
+  target: z.string(),
+  version: z.string(),
+});
+
+type DeployParams = z.infer<typeof DeploySchema>;
+
+// Create your step
+@Step({ name: "Deploy", type: "deploy", schema: DeploySchema })
+class DeployStep extends SimpleStep<DeployParams> {
+  async run(params: DeployParams) {
+    this.logger.info("Starting deployment", { target: params.target });
+
+    // Your deployment logic here
+    const deploymentId = `deploy-${params.target}-${params.version}`;
+
+    this.logger.info("Deployment complete", { deploymentId });
+    return StepOutputs.success({ deploymentId });
+  }
+}
+
+// Register and run
+StepRegistry.run([DeployStep]);
+```
+
+### Polling Step
+
+A polling step is used for long-running operations that need status checks.
+
+```typescript
+import { PollingStep, Step, StepOutputs, StepRegistry } from "@devramps/step-sdk";
+import { z } from "zod";
+
+const BuildSchema = z.object({
+  project: z.string(),
+  branch: z.string(),
+});
+
+type BuildParams = z.infer<typeof BuildSchema>;
+
+type BuildPollingState = {
+  buildId: string;
+  startedAt: number;
+};
+
+@Step({ name: "Build", type: "build", schema: BuildSchema })
+class BuildStep extends PollingStep<BuildParams, BuildPollingState> {
+  async trigger(params: BuildParams) {
+    this.logger.info("Starting build", { project: params.project });
+
+    // Start the build and return initial polling state
+    const buildId = await startBuild(params.project, params.branch);
+
+    return StepOutputs.triggered({
+      buildId,
+      startedAt: Date.now(),
+    });
+  }
+
+  async poll(params: BuildParams, state: BuildPollingState) {
+    const status = await checkBuildStatus(state.buildId);
+
+    if (status === "running") {
+      // Still running - poll again in 5 seconds
+      return StepOutputs.pollAgain(state, 5000);
+    }
+
+    if (status === "failed") {
+      return StepOutputs.failed("Build failed", "BUILD_FAILED");
+    }
+
+    return StepOutputs.success({ buildId: state.buildId, status: "complete" });
+  }
+}
+
+StepRegistry.run([BuildStep]);
+```
+
+## Approval Workflows
+
+Steps can require approval before execution by overriding the `prepare` method.
+
+### Simple Step with Approval
+
+```typescript
+import { SimpleStep, Step, StepOutputs, ApprovalContext } from "@devramps/step-sdk";
+import { z } from "zod";
+
+const DeleteUserSchema = z.object({
+  userId: z.string(),
+  reason: z.string(),
+});
+
+type DeleteUserParams = z.infer<typeof DeleteUserSchema>;
+
+@Step({ name: "Delete User", type: "delete-user", schema: DeleteUserSchema })
+class DeleteUserStep extends SimpleStep<DeleteUserParams> {
+  // Override prepare to require approval
+  async prepare(params: DeleteUserParams) {
+    return StepOutputs.approvalRequired({
+      message: `Delete user ${params.userId}? Reason: ${params.reason}`,
+      approvers: ["admin@example.com"],
+      metadata: { userId: params.userId },
+    });
+  }
+
+  async run(params: DeleteUserParams, approval?: ApprovalContext) {
+    this.logger.info("Deleting user", {
+      userId: params.userId,
+      approvedBy: approval?.approverId,
+    });
+
+    await deleteUser(params.userId);
+
+    return StepOutputs.success({ deleted: true });
+  }
+}
+```
+
+### Polling Step with Approval
+
+```typescript
+import { PollingStep, Step, StepOutputs, ApprovalContext } from "@devramps/step-sdk";
+import { z } from "zod";
+
+const ProductionDeploySchema = z.object({
+  service: z.string(),
+  version: z.string(),
+});
+
+type ProductionDeployParams = z.infer<typeof ProductionDeploySchema>;
+
+type DeployState = {
+  deploymentId: string;
+};
+
+@Step({ name: "Production Deploy", type: "production-deploy", schema: ProductionDeploySchema })
+class ProductionDeployStep extends PollingStep<ProductionDeployParams, DeployState> {
+  async prepare(params: ProductionDeployParams) {
+    return StepOutputs.approvalRequired({
+      message: `Deploy ${params.service} v${params.version} to production?`,
+      approvers: ["release-manager@example.com", "oncall@example.com"],
+    });
+  }
+
+  async trigger(params: ProductionDeployParams, approval?: ApprovalContext) {
+    this.logger.info("Starting production deployment", {
+      service: params.service,
+      approvedBy: approval?.approverId,
+    });
+
+    const deploymentId = await startProductionDeploy(params);
+    return StepOutputs.triggered({ deploymentId });
+  }
+
+  async poll(_params: ProductionDeployParams, state: DeployState) {
+    const status = await getDeploymentStatus(state.deploymentId);
+
+    if (status === "in_progress") {
+      return StepOutputs.pollAgain(state, 10000);
+    }
+
+    if (status === "failed") {
+      return StepOutputs.failed("Deployment failed", "DEPLOY_FAILED");
+    }
+
+    return StepOutputs.success({ deploymentId: state.deploymentId });
+  }
+}
+```
+
+## API Reference
+
+### Step Outputs
+
+The SDK provides helper functions for creating step outputs:
+
+```typescript
+import { StepOutputs } from "@devramps/step-sdk";
+
+// Success with optional data
+StepOutputs.success();
+StepOutputs.success({ key: "value" });
+
+// Failure with error message and optional error code
+StepOutputs.failed("Something went wrong");
+StepOutputs.failed("Not found", "NOT_FOUND");
+
+// Approval required (used in prepare method)
+StepOutputs.approvalRequired({
+  message: "Please approve this action",
+  approvers: ["admin@example.com"],  // optional
+  metadata: { key: "value" },         // optional
+});
+
+// Triggered with polling state (used in PollingStep.trigger)
+StepOutputs.triggered({ jobId: "123", startedAt: Date.now() });
+
+// Poll again with updated state and optional delay (used in PollingStep.poll)
+StepOutputs.pollAgain({ jobId: "123", attempt: 2 }, 5000);
+```
+
+### @Step Decorator
+
+The `@Step` decorator adds metadata to your step class:
+
+```typescript
+@Step({
+  name: "Human-readable name",
+  type: "unique-step-type",
+  schema: zodSchema,
+})
+```
+
+- `name`: Display name for the step
+- `type`: Unique identifier used when executing the step
+- `schema`: Zod schema for validating input parameters
+
+### StepRegistry
+
+The registry handles CLI argument parsing and step execution:
+
+```typescript
+import { StepRegistry } from "@devramps/step-sdk";
+
+// Register all your steps
+StepRegistry.run([
+  DeployStep,
+  BuildStep,
+  DeleteUserStep,
+]);
+```
+
+#### CLI Arguments
+
+When running your step entrypoint:
+
+```bash
+node entrypoint.js --input '{"job":"EXECUTE","type":"deploy","params":{"target":"staging","version":"1.0.0"}}'
+```
+
+| Argument | Description | Default |
+|----------|-------------|---------|
+| `--input` | JSON input with job type and parameters | Required |
+| `--output` | Path to write output JSON | `/tmp/step-output.json` |
+| `--log-dir` | Directory for log files | `/tmp/step-logs` |
+| `--execution-id` | Unique ID for this execution | Auto-generated |
+
+#### Input Format
+
+**Synthesize Metadata** - Get metadata for all registered steps:
+```json
+{
+  "job": "SYNTHESIZE-METADATA"
+}
+```
+
+**Execute Step** - Run a specific step:
+```json
+{
+  "job": "EXECUTE",
+  "type": "deploy",
+  "params": { "target": "staging", "version": "1.0.0" }
+}
+```
+
+**Execute with Approval Context**:
+```json
+{
+  "job": "EXECUTE",
+  "type": "delete-user",
+  "params": { "userId": "123", "reason": "requested" },
+  "approvalContext": {
+    "approved": true,
+    "approverId": "admin@example.com"
+  }
+}
+```
+
+**Execute Poll Phase**:
+```json
+{
+  "job": "EXECUTE",
+  "type": "build",
+  "params": { "project": "my-app", "branch": "main" },
+  "pollingState": {
+    "buildId": "build-123",
+    "startedAt": 1704067200000
+  }
+}
+```
+
+### Logging
+
+Steps have access to a structured logger:
+
+```typescript
+class MyStep extends SimpleStep<MyParams> {
+  async run(params: MyParams) {
+    // Log info with optional data
+    this.logger.info("Processing started", { itemCount: 10 });
+
+    // Log errors
+    this.logger.error("Failed to connect", { host: "example.com" });
+
+    return StepOutputs.success();
+  }
+}
+```
+
+Logs are written as JSON lines to `{log-dir}/{execution-id}.jsonl`:
+
+```json
+{"timestamp":"2024-01-01T12:00:00.000Z","level":"info","message":"Processing started","data":{"itemCount":10},"stepType":"my-step","executionId":"exec-123"}
+```
+
+## Output Types
+
+### RunOutput (SimpleStep.run)
+- `SUCCESS` with optional data
+- `FAILED` with error message
+
+### TriggerOutput (PollingStep.trigger)
+- `TRIGGERED` with polling state
+- `FAILED` with error message
+
+### PollOutput (PollingStep.poll)
+- `SUCCESS` with optional data
+- `POLL_AGAIN` with updated polling state and optional retry delay
+- `FAILED` with error message
+
+### PrepareOutput (approval flow)
+- `APPROVAL_REQUIRED` with approval request details
+- `FAILED` with error message
+
+## Complete Example
+
+Here's a complete example with multiple step types:
+
+```typescript
+// steps.ts
+import {
+  SimpleStep,
+  PollingStep,
+  Step,
+  StepOutputs,
+  StepRegistry,
+  ApprovalContext,
+} from "@devramps/step-sdk";
+import { z } from "zod";
+
+// Schema definitions
+const NotifySchema = z.object({
+  channel: z.string(),
+  message: z.string(),
+});
+
+const MigrationSchema = z.object({
+  database: z.string(),
+  version: z.string(),
+});
+
+// Simple notification step
+@Step({ name: "Send Notification", type: "notify", schema: NotifySchema })
+class NotifyStep extends SimpleStep<z.infer<typeof NotifySchema>> {
+  async run(params: z.infer<typeof NotifySchema>) {
+    this.logger.info("Sending notification", { channel: params.channel });
+    // Send notification logic...
+    return StepOutputs.success({ sent: true });
+  }
+}
+
+// Database migration with approval and polling
+type MigrationState = {
+  migrationId: string;
+  startedAt: number;
+};
+
+@Step({ name: "Database Migration", type: "db-migration", schema: MigrationSchema })
+class MigrationStep extends PollingStep<z.infer<typeof MigrationSchema>, MigrationState> {
+  async prepare(params: z.infer<typeof MigrationSchema>) {
+    return StepOutputs.approvalRequired({
+      message: `Run migration ${params.version} on ${params.database}?`,
+      approvers: ["dba@example.com"],
+    });
+  }
+
+  async trigger(params: z.infer<typeof MigrationSchema>, approval?: ApprovalContext) {
+    this.logger.info("Starting migration", {
+      database: params.database,
+      approvedBy: approval?.approverId,
+    });
+
+    const migrationId = `migration-${Date.now()}`;
+    return StepOutputs.triggered({
+      migrationId,
+      startedAt: Date.now(),
+    });
+  }
+
+  async poll(_params: z.infer<typeof MigrationSchema>, state: MigrationState) {
+    // Check migration status...
+    const elapsed = Date.now() - state.startedAt;
+
+    if (elapsed < 30000) {
+      return StepOutputs.pollAgain(state, 5000);
+    }
+
+    return StepOutputs.success({
+      migrationId: state.migrationId,
+      duration: elapsed,
+    });
+  }
+}
+
+// Run the registry
+StepRegistry.run([NotifyStep, MigrationStep]);
+```
+
+## TypeScript Configuration
+
+Ensure your `tsconfig.json` includes decorator support:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## License
+
+MIT

package/dist/base/base-step.d.ts

@@ -0,0 +1,41 @@
+import type { ZodType, z } from "zod";
+import type { StepLogger } from "../logging/step-logger";
+import type { PrepareOutput } from "../output/step-output";
+export type StepKind = "simple" | "polling";
+export interface StepMetadata<S extends ZodType = ZodType> {
+    name: string;
+    type: string;
+    schema: S;
+    stepKind: StepKind;
+    requiresApproval: boolean;
+}
+/**
+ * Base class for all steps.
+ * Provides logging and common functionality.
+ */
+export declare abstract class BaseStep<TParams = unknown> {
+    protected logger: StepLogger;
+    /**
+     * Called by the registry to inject the logger before execution.
+     * @internal
+     */
+    _setLogger(logger: StepLogger): void;
+    /**
+     * Returns metadata about this step.
+     * Implemented by the @Step decorator.
+     */
+    getMetadata(): StepMetadata;
+    /**
+     * Optional prepare method for approval flow.
+     * Override this to require approval before execution.
+     * If not overridden, the step will not require approval.
+     */
+    prepare(_params: TParams): Promise<PrepareOutput>;
+}
+/**
+ * Type representing a class constructor that produces a BaseStep instance
+ * with the getMetadata method available.
+ */
+export type StepClass<S extends ZodType = ZodType> = new (...args: any[]) => BaseStep<z.infer<S>> & {
+    getMetadata(): StepMetadata<S>;
+};

package/dist/base/base-step.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseStep = void 0;
+const step_logger_1 = require("../logging/step-logger");
+const step_output_1 = require("../output/step-output");
+/**
+ * Base class for all steps.
+ * Provides logging and common functionality.
+ */
+class BaseStep {
+    logger = new step_logger_1.NoOpLogger();
+    /**
+     * Called by the registry to inject the logger before execution.
+     * @internal
+     */
+    _setLogger(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Returns metadata about this step.
+     * Implemented by the @Step decorator.
+     */
+    getMetadata() {
+        throw new Error("getMetadata not implemented. Did you forget to add the @Step decorator?");
+    }
+    /**
+     * Optional prepare method for approval flow.
+     * Override this to require approval before execution.
+     * If not overridden, the step will not require approval.
+     */
+    async prepare(_params) {
+        // Default: no approval required - this should never be called
+        // The registry checks if prepare is overridden before calling it
+        return step_output_1.StepOutputs.failed("prepare() called but not implemented", "PREPARE_NOT_IMPLEMENTED");
+    }
+}
+exports.BaseStep = BaseStep;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmFzZS1zdGVwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2Jhc2UvYmFzZS1zdGVwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUVBLHdEQUFvRDtBQUVwRCx1REFBb0Q7QUFZcEQ7OztHQUdHO0FBQ0gsTUFBc0IsUUFBUTtJQUNsQixNQUFNLEdBQWUsSUFBSSx3QkFBVSxFQUFFLENBQUM7SUFFaEQ7OztPQUdHO0lBQ0gsVUFBVSxDQUFDLE1BQWtCO1FBQzNCLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFDO0lBQ3ZCLENBQUM7SUFFRDs7O09BR0c7SUFDSCxXQUFXO1FBQ1QsTUFBTSxJQUFJLEtBQUssQ0FDYix5RUFBeUUsQ0FDMUUsQ0FBQztJQUNKLENBQUM7SUFFRDs7OztPQUlHO0lBQ0gsS0FBSyxDQUFDLE9BQU8sQ0FBQyxPQUFnQjtRQUM1Qiw4REFBOEQ7UUFDOUQsaUVBQWlFO1FBQ2pFLE9BQU8seUJBQVcsQ0FBQyxNQUFNLENBQ3ZCLHNDQUFzQyxFQUN0Qyx5QkFBeUIsQ0FDMUIsQ0FBQztJQUNKLENBQUM7Q0FDRjtBQWxDRCw0QkFrQ0MiLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgdHlwZSB7IFpvZFR5cGUsIHogfSBmcm9tIFwiem9kXCI7XG5pbXBvcnQgdHlwZSB7IFN0ZXBMb2dnZXJ9IGZyb20gXCIuLi9sb2dnaW5nL3N0ZXAtbG9nZ2VyXCI7XG5pbXBvcnQgeyBOb09wTG9nZ2VyIH0gZnJvbSBcIi4uL2xvZ2dpbmcvc3RlcC1sb2dnZXJcIjtcbmltcG9ydCB0eXBlIHsgUHJlcGFyZU91dHB1dH0gZnJvbSBcIi4uL291dHB1dC9zdGVwLW91dHB1dFwiO1xuaW1wb3J0IHsgU3RlcE91dHB1dHMgfSBmcm9tIFwiLi4vb3V0cHV0L3N0ZXAtb3V0cHV0XCI7XG5cbmV4cG9ydCB0eXBlIFN0ZXBLaW5kID0gXCJzaW1wbGVcIiB8IFwicG9sbGluZ1wiO1xuXG5leHBvcnQgaW50ZXJmYWNlIFN0ZXBNZXRhZGF0YTxTIGV4dGVuZHMgWm9kVHlwZSA9IFpvZFR5cGU+IHtcbiAgbmFtZTogc3RyaW5nO1xuICB0eXBlOiBzdHJpbmc7XG4gIHNjaGVtYTogUztcbiAgc3RlcEtpbmQ6IFN0ZXBLaW5kO1xuICByZXF1aXJlc0FwcHJvdmFsOiBib29sZWFuO1xufVxuXG4vKipcbiAqIEJhc2UgY2xhc3MgZm9yIGFsbCBzdGVwcy5cbiAqIFByb3ZpZGVzIGxvZ2dpbmcgYW5kIGNvbW1vbiBmdW5jdGlvbmFsaXR5LlxuICovXG5leHBvcnQgYWJzdHJhY3QgY2xhc3MgQmFzZVN0ZXA8VFBhcmFtcyA9IHVua25vd24+IHtcbiAgcHJvdGVjdGVkIGxvZ2dlcjogU3RlcExvZ2dlciA9IG5ldyBOb09wTG9nZ2VyKCk7XG5cbiAgLyoqXG4gICAqIENhbGxlZCBieSB0aGUgcmVnaXN0cnkgdG8gaW5qZWN0IHRoZSBsb2dnZXIgYmVmb3JlIGV4ZWN1dGlvbi5cbiAgICogQGludGVybmFsXG4gICAqL1xuICBfc2V0TG9nZ2VyKGxvZ2dlcjogU3RlcExvZ2dlcik6IHZvaWQge1xuICAgIHRoaXMubG9nZ2VyID0gbG9nZ2VyO1xuICB9XG5cbiAgLyoqXG4gICAqIFJldHVybnMgbWV0YWRhdGEgYWJvdXQgdGhpcyBzdGVwLlxuICAgKiBJbXBsZW1lbnRlZCBieSB0aGUgQFN0ZXAgZGVjb3JhdG9yLlxuICAgKi9cbiAgZ2V0TWV0YWRhdGEoKTogU3RlcE1ldGFkYXRhIHtcbiAgICB0aHJvdyBuZXcgRXJyb3IoXG4gICAgICBcImdldE1ldGFkYXRhIG5vdCBpbXBsZW1lbnRlZC4gRGlkIHlvdSBmb3JnZXQgdG8gYWRkIHRoZSBAU3RlcCBkZWNvcmF0b3I/XCJcbiAgICApO1xuICB9XG5cbiAgLyoqXG4gICAqIE9wdGlvbmFsIHByZXBhcmUgbWV0aG9kIGZvciBhcHByb3ZhbCBmbG93LlxuICAgKiBPdmVycmlkZSB0aGlzIHRvIHJlcXVpcmUgYXBwcm92YWwgYmVmb3JlIGV4ZWN1dGlvbi5cbiAgICogSWYgbm90IG92ZXJyaWRkZW4sIHRoZSBzdGVwIHdpbGwgbm90IHJlcXVpcmUgYXBwcm92YWwuXG4gICAqL1xuICBhc3luYyBwcmVwYXJlKF9wYXJhbXM6IFRQYXJhbXMpOiBQcm9taXNlPFByZXBhcmVPdXRwdXQ+IHtcbiAgICAvLyBEZWZhdWx0OiBubyBhcHByb3ZhbCByZXF1aXJlZCAtIHRoaXMgc2hvdWxkIG5ldmVyIGJlIGNhbGxlZFxuICAgIC8vIFRoZSByZWdpc3RyeSBjaGVja3MgaWYgcHJlcGFyZSBpcyBvdmVycmlkZGVuIGJlZm9yZSBjYWxsaW5nIGl0XG4gICAgcmV0dXJuIFN0ZXBPdXRwdXRzLmZhaWxlZChcbiAgICAgIFwicHJlcGFyZSgpIGNhbGxlZCBidXQgbm90IGltcGxlbWVudGVkXCIsXG4gICAgICBcIlBSRVBBUkVfTk9UX0lNUExFTUVOVEVEXCJcbiAgICApO1xuICB9XG59XG5cbi8qKlxuICogVHlwZSByZXByZXNlbnRpbmcgYSBjbGFzcyBjb25zdHJ1Y3RvciB0aGF0IHByb2R1Y2VzIGEgQmFzZVN0ZXAgaW5zdGFuY2VcbiAqIHdpdGggdGhlIGdldE1ldGFkYXRhIG1ldGhvZCBhdmFpbGFibGUuXG4gKi9cbmV4cG9ydCB0eXBlIFN0ZXBDbGFzczxTIGV4dGVuZHMgWm9kVHlwZSA9IFpvZFR5cGU+ID0gbmV3IChcbiAgLi4uYXJnczogYW55W11cbikgPT4gQmFzZVN0ZXA8ei5pbmZlcjxTPj4gJiB7XG4gIGdldE1ldGFkYXRhKCk6IFN0ZXBNZXRhZGF0YTxTPjtcbn07XG4iXX0=

package/dist/base/polling-step.d.ts

@@ -0,0 +1,85 @@
+import type { StepMetadata } from "./base-step";
+import { BaseStep } from "./base-step";
+import type { ApprovalContext, PollOutput, StepOutput, TriggerOutput } from "../output/step-output";
+/**
+ * A polling step for long-running operations that need status checks.
+ *
+ * Users extend this class and implement:
+ * - `trigger(params)` - Start the operation, return initial polling state
+ * - `poll(params, pollingState)` - Check status, return POLL_AGAIN, SUCCESS, or FAILED
+ *
+ * Optionally override `prepare` to require approval before triggering.
+ *
+ * @typeParam TParams - The input parameters type (validated by schema)
+ * @typeParam TPollingState - The polling state type passed between poll calls
+ *
+ * @example
+ * ```typescript
+ * type JobParams = { target: string };
+ * type JobPollingState = { jobId: string; startedAt: number };
+ *
+ * @Step({ name: "Long Job", type: "long-job", schema: jobSchema })
+ * class LongJobStep extends PollingStep<JobParams, JobPollingState> {
+ *   async trigger(params: JobParams): Promise<TriggerOutput<JobPollingState>> {
+ *     const jobId = await startJob(params);
+ *     return StepOutputs.triggered({ jobId, startedAt: Date.now() });
+ *   }
+ *
+ *   async poll(params: JobParams, state: JobPollingState): Promise<PollOutput<JobPollingState>> {
+ *     const status = await checkJob(state.jobId);
+ *     if (status === "running") {
+ *       return StepOutputs.pollAgain(state, 5000);
+ *     }
+ *     return StepOutputs.success({ result: status });
+ *   }
+ * }
+ * ```
+ *
+ * @example With approval
+ * ```typescript
+ * @Step({ name: "Dangerous Job", type: "dangerous-job", schema: dangerousSchema })
+ * class DangerousJobStep extends PollingStep<DangerousParams, DangerousPollingState> {
+ *   async prepare(params: DangerousParams): Promise<PrepareOutput> {
+ *     return StepOutputs.approvalRequired({
+ *       message: `Run dangerous job on ${params.target}?`,
+ *     });
+ *   }
+ *
+ *   async trigger(params: DangerousParams, approval: ApprovalContext): Promise<TriggerOutput<DangerousPollingState>> {
+ *     const jobId = await startDangerousJob(params);
+ *     return StepOutputs.triggered({ jobId });
+ *   }
+ *
+ *   async poll(params: DangerousParams, state: DangerousPollingState): Promise<PollOutput<DangerousPollingState>> {
+ *     // ... check status
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class PollingStep<TParams, TPollingState extends Record<string, unknown> = Record<string, unknown>> extends BaseStep<TParams> {
+    /**
+     * Start the long-running operation.
+     * @param params - The validated input parameters
+     * @param approval - Approval context if this step requires approval (has prepare method)
+     * @returns TRIGGERED with initial polling state, or FAILED
+     */
+    abstract trigger(params: TParams, approval?: ApprovalContext): Promise<TriggerOutput<TPollingState>>;
+    /**
+     * Check the status of the operation.
+     * @param params - The original input parameters
+     * @param pollingState - State from previous trigger() or poll() call
+     * @returns POLL_AGAIN with updated state, SUCCESS, or FAILED
+     */
+    abstract poll(params: TParams, pollingState: TPollingState): Promise<PollOutput<TPollingState>>;
+    /**
+     * Called by the registry to execute the trigger phase.
+     * @internal
+     */
+    executeTrigger(params: TParams, approval?: ApprovalContext): Promise<StepOutput>;
+    /**
+     * Called by the registry to execute the poll phase.
+     * @internal
+     */
+    executePoll(params: TParams, pollingState: TPollingState): Promise<StepOutput>;
+    getMetadata(): StepMetadata;
+}