0
# Interface Types
1

2
Strongly typed interfaces for component triggers including timer-based execution, HTTP endpoints, and app webhooks.
3

4
## Capabilities
5

6
### Timer Interface
7

8
Interface for timer-based component triggers with support for intervals and cron expressions.
9

10
```typescript { .api }
11
/**
12
 * Timer interface for scheduled component execution
13
 */
14
interface TimerInterface {
15
  /** Always "$.interface.timer" for timer interfaces */
16
  type: "$.interface.timer";
17
  /** Default timer configuration (optional) */
18
  default?: {
19
    /** Interval in seconds between executions (optional) */
20
    intervalSeconds?: number;
21
    /** Cron expression for advanced scheduling (optional) */
22
    cron?: string;
23
  };
24
}
25

26
/**
27
 * Event object passed to components triggered by timer interface
28
 */
29
interface TimerEvent {
30
  /** Timestamp when the timer was triggered */
31
  timestamp: number;
32
  /** Configured interval in seconds (if using interval) */
33
  interval_seconds?: number;
34
  /** Configured cron expression (if using cron) */
35
  cron?: string;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { PipedreamComponent, TimerInterface, TimerEvent } from "@pipedream/types";
43

44
// Simple interval timer (every 15 minutes)
45
const intervalComponent: PipedreamComponent = {
46
  name: "Interval Timer Component",
47
  version: "1.0.0",
48
  props: {
49
    timer: {
50
      type: "$.interface.timer",
51
      default: {
52
        intervalSeconds: 60 * 15 // 15 minutes
53
      }
54
    } as TimerInterface
55
  },
56
  async run(event: TimerEvent) {
57
    console.log("Timer triggered at:", new Date(event.timestamp));
58
    console.log("Interval:", event.interval_seconds, "seconds");
59
  }
60
};
61

62
// Cron-based timer (daily at 9 AM)
63
const cronComponent: PipedreamComponent = {
64
  name: "Cron Timer Component", 
65
  version: "1.0.0",
66
  props: {
67
    timer: {
68
      type: "$.interface.timer",
69
      default: {
70
        cron: "0 9 * * *" // Daily at 9:00 AM
71
      }
72
    } as TimerInterface
73
  },
74
  async run(event: TimerEvent) {
75
    console.log("Daily task triggered");
76
    console.log("Cron expression:", event.cron);
77
  }
78
};
79
```
80

81
### HTTP Interface
82

83
Interface for HTTP endpoint components that can receive and respond to HTTP requests.
84

85
```typescript { .api }
86
/**
87
 * HTTP interface for HTTP endpoint components
88
 */
89
interface HttpInterface {
90
  /** Always "$.interface.http" for HTTP interfaces */
91
  type: "$.interface.http";
92
  /** Enable custom HTTP responses (optional) */
93
  customResponse?: boolean;
94
  /** HTTP response method (available at runtime) */
95
  respond?: HttpRespondMethod;
96
}
97

98
/**
99
 * Event object passed to components triggered by HTTP requests
100
 */
101
interface HttpEvent {
102
  /** HTTP method (GET, POST, PUT, DELETE, etc.) */
103
  method: string;
104
  /** Request path */
105
  path: string;
106
  /** Query string parameters */
107
  query: Record<string, any>;
108
  /** Request headers */
109
  headers: Record<string, string>;
110
  /** Raw request body as string */
111
  bodyRaw: string;
112
  /** Parsed request body */
113
  body: any;
114
}
115

116
/**
117
 * Method for sending HTTP responses
118
 */
119
interface HttpRespondMethod {
120
  (response: {
121
    /** HTTP status code */
122
    status: number;
123
    /** Response headers (optional) */
124
    headers?: Record<string, string>;
125
    /** Response body (optional) */
126
    body?: string | object | Buffer;
127
  }): void;
128
}
129

130
/**
131
 * HTTP endpoint information available in component context
132
 */
133
interface HttpEndpoint {
134
  /** Generated endpoint URL */
135
  endpoint: string;
136
}
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
import { PipedreamComponent, HttpInterface, HttpEvent } from "@pipedream/types";
143

144
// Basic HTTP endpoint
145
const basicHttpComponent: PipedreamComponent = {
146
  name: "Basic HTTP Component",
147
  version: "1.0.0", 
148
  props: {
149
    http: {
150
      type: "$.interface.http"
151
    } as HttpInterface
152
  },
153
  async run(event: HttpEvent) {
154
    console.log(`Received ${event.method} request to ${event.path}`);
155
    console.log("Query params:", event.query);
156
    console.log("Body:", event.body);
157
    
158
    // Emit the event
159
    this.$emit(event, {
160
      summary: `${event.method} ${event.path}`
161
    });
162
  }
163
};
164

165
// HTTP endpoint with custom response
166
const customResponseComponent: PipedreamComponent = {
167
  name: "Custom Response Component",
168
  version: "1.0.0",
169
  props: {
170
    http: {
171
      type: "$.interface.http",
172
      customResponse: true
173
    } as HttpInterface
174
  },
175
  async run(event: HttpEvent) {
176
    // Process the request
177
    const result = await processData(event.body);
178
    
179
    // Send custom response
180
    this.http.respond({
181
      status: 200,
182
      headers: {
183
        "Content-Type": "application/json",
184
        "X-Custom-Header": "processed"
185
      },
186
      body: {
187
        success: true,
188
        data: result,
189
        timestamp: new Date().toISOString()
190
      }
191
    });
192
    
193
    // Also emit as event
194
    this.$emit(result);
195
  }
196
};
197

198
// Webhook endpoint with validation
199
const webhookComponent: PipedreamComponent = {
200
  name: "Webhook Component",
201
  version: "1.0.0",
202
  props: {
203
    http: {
204
      type: "$.interface.http",
205
      customResponse: true
206
    } as HttpInterface,
207
    webhookSecret: {
208
      type: "string",
209
      label: "Webhook Secret",
210
      description: "Secret for webhook validation",
211
      secret: true
212
    }
213
  },
214
  async run(event: HttpEvent) {
215
    // Validate webhook signature
216
    const isValid = validateWebhookSignature(
217
      event.bodyRaw,
218
      event.headers['x-webhook-signature'],
219
      this.webhookSecret
220
    );
221
    
222
    if (!isValid) {
223
      this.http.respond({
224
        status: 401,
225
        body: { error: "Invalid signature" }
226
      });
227
      return;
228
    }
229
    
230
    // Process valid webhook
231
    this.http.respond({
232
      status: 200,
233
      body: { received: true }
234
    });
235
    
236
    this.$emit(event.body, {
237
      id: event.body.id || Date.now(),
238
      summary: "Webhook received"
239
    });
240
  }
241
};
242
```
243

244
### App Hook Interface
245

246
Interface for app-specific webhook endpoints that listen to events from integrated apps.
247

248
```typescript { .api }
249
/**
250
 * App hook interface for app-specific webhooks
251
 */
252
interface AppHookInterface {
253
  /** Always "$.interface.apphook" for app hook interfaces */
254
  type: "$.interface.apphook";
255
  /** Reference to the app prop that provides webhook functionality */
256
  appProp: string;
257
  /** Array of event names to listen for from the app */
258
  eventNames: string[];
259
}
260
```
261

262
**Usage Example:**
263

264
```typescript
265
import { PipedreamComponent, AppHookInterface, PipedreamApp } from "@pipedream/types";
266

267
// GitHub app hook component
268
const githubHookComponent: PipedreamComponent = {
269
  name: "GitHub Webhook Component",
270
  version: "1.0.0",
271
  props: {
272
    github: {
273
      type: "app",
274
      app: "github"
275
    } as PipedreamApp,
276
    githubHook: {
277
      type: "$.interface.apphook",
278
      appProp: "github",
279
      eventNames: ["push", "pull_request", "issues"]
280
    } as AppHookInterface,
281
    repository: {
282
      type: "string",
283
      propDefinition: ["github", "repository"]
284
    }
285
  },
286
  async run(event) {
287
    console.log("GitHub event received:", event.type);
288
    console.log("Repository:", event.repository?.full_name);
289
    
290
    // Handle different event types
291
    switch (event.type) {
292
      case "push":
293
        this.$emit(event.payload, {
294
          summary: `Push to ${event.repository.full_name}`
295
        });
296
        break;
297
      case "pull_request":
298
        this.$emit(event.payload, {
299
          summary: `PR #${event.payload.number} ${event.payload.action}`
300
        });
301
        break;
302
      case "issues":
303
        this.$emit(event.payload, {
304
          summary: `Issue #${event.payload.issue.number} ${event.payload.action}`
305
        });
306
        break;
307
    }
308
  }
309
};
310
```
311

312
## Interface Combinations
313

314
### Multi-Interface Component
315

316
Components can use multiple interfaces, though this is less common:
317

318
```typescript
319
const multiInterfaceComponent: PipedreamComponent = {
320
  name: "Multi-Interface Component",
321
  version: "1.0.0",
322
  props: {
323
    // Timer for periodic tasks
324
    timer: {
325
      type: "$.interface.timer",
326
      default: { intervalSeconds: 3600 }
327
    } as TimerInterface,
328
    
329
    // HTTP for manual triggers
330
    http: {
331
      type: "$.interface.http"
332
    } as HttpInterface,
333
    
334
    // Database for state
335
    db: "$.service.db"
336
  },
337
  async run(event) {
338
    // Determine trigger type
339
    if ('timestamp' in event) {
340
      // Timer trigger
341
      console.log("Scheduled execution");
342
    } else if ('method' in event) {
343
      // HTTP trigger
344
      console.log("Manual trigger via HTTP");
345
    }
346
    
347
    // Common processing logic
348
    await this.processData(event);
349
  }
350
};
351
```
352

353
## Interface Runtime Context
354

355
When using interfaces, additional properties become available in the component context:
356

357
```typescript
358
// Timer interface adds timer property
359
interface TimerComponentThis extends ComponentThis {
360
  timer: {
361
    type: "$.interface.timer";
362
  };
363
}
364

365
// HTTP interface adds http property with endpoint and respond method
366
interface HttpComponentThis extends ComponentThis {
367
  http: HttpEndpoint & {
368
    respond: HttpRespondMethod;
369
  };
370
}
371

372
// App hook interface adds the hook property
373
interface AppHookComponentThis extends ComponentThis {
374
  [hookPropName: string]: {
375
    type: "$.interface.apphook";
376
    appProp: string;
377
    eventNames: string[];
378
  };
379
}
380
```