Skip to content

Commit 785ac29

Browse files
nicktrnnicktrn
committed
Add docs
1 parent f4aaae3 commit 785ac29

9 files changed

Lines changed: 255 additions & 2 deletions

File tree

‎docs/_snippets/send-events-params.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
<ParamField body="events" type="array" required>
2+
<Expandable title="event properties" defaultOpen>
3+
<ParamField body="name" type="string" required>
4+
The `name` property must exactly match any subscriptions you want to
5+
trigger.
6+
</ParamField>
7+
<ParamField body="payload" type="any">
8+
The `payload` property will be sent to any matching Jobs and will appear
9+
as the `payload` param of the `run()` function. You can leave this
10+
parameter out if you just want to trigger a Job without any input data.
11+
</ParamField>
12+
<ParamField body="context" type="any">
13+
The optional `context` property will be sent to any matching Jobs and will
14+
be passed through as the `context.event.context` param of the `run()`
15+
function. This is optional but can be useful if you want to pass through
16+
some additional context to the Job.
17+
</ParamField>
18+
<ParamField body="id" type="string">
19+
The `id` property uniquely identify this particular event. If unset it
20+
will be set automatically using `ulid`.
21+
</ParamField>
22+
<ParamField body="timestamp" type="Date">
23+
This is optional, it defaults to the current timestamp. Usually you would
24+
only set this if you have a timestamp that you wish to pass through, e.g.
25+
you receive a timestamp from a service and you want the same timestamp to
26+
be used in your Job.
27+
</ParamField>
28+
<ParamField body="source" type="string">
29+
This is optional, it defaults to "trigger.dev". It can be useful to set
30+
this as you can filter events using this in the `eventTrigger()`.
31+
</ParamField>
32+
</Expandable>
33+
</ParamField>
34+
35+
<ParamField body="options" type="object">
36+
<Expandable title="properties" defaultOpen>
37+
<ParamField body="deliverAt" type="Date">
38+
An optional Date when you want the event to Trigger Jobs. The event will
39+
be sent to the platform immediately but won't be acted upon until the
40+
specified time.
41+
</ParamField>
42+
<ParamField body="deliverAfter" type="number">
43+
An optional number of seconds you want to wait for the event to Trigger
44+
any relevant Jobs. The event will be sent to the platform immediately but
45+
won't be acted upon until the specified time.
46+
</ParamField>
47+
<ParamField body="accountId" type="string">
48+
This optional param will be used by the Trigger.dev Connect feature, which
49+
is coming soon.
50+
</ParamField>
51+
</Expandable>
52+
</ParamField>

‎docs/_snippets/send-events-return.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<ResponseField name="events" type="array">
2+
<Expandable title="properties" defaultOpen>
3+
<ResponseField name="id" type="string" required>
4+
The `id` of the event that was sent.
5+
</ResponseField>
6+
<ResponseField name="name" type="string" required>
7+
The `name` of the event that was sent.
8+
</ResponseField>
9+
<ResponseField name="payload" type="any" required>
10+
The `payload` of the event that was sent
11+
</ResponseField>
12+
<ResponseField name="timestamp" type="Date" required>
13+
The `timestamp` of the event that was sent
14+
</ResponseField>
15+
<ResponseField name="context" type="any">
16+
The `context` of the event that was sent. Is `undefined` if no context was
17+
set when sending the event.
18+
</ResponseField>
19+
<ResponseField name="deliverAt" type="Date">
20+
The timestamp when the event will be delivered to any matching Jobs. Is
21+
`undefined` if `deliverAt` or `deliverAfter` wasn't set when sending the
22+
event.
23+
</ResponseField>
24+
<ResponseField name="deliveredAt" type="Date">
25+
The timestamp when the event was delivered. Is `undefined` if `deliverAt`
26+
or `deliverAfter` were set when sending the event.
27+
</ResponseField>
28+
</Expandable>
29+
</ResponseField>

‎docs/mint.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,7 @@
302302
"group": "Instance methods",
303303
"pages": [
304304
"sdk/triggerclient/instancemethods/sendevent",
305+
"sdk/triggerclient/instancemethods/sendevents",
305306
"sdk/triggerclient/instancemethods/getevent",
306307
"sdk/triggerclient/instancemethods/cancel-event",
307308
"sdk/triggerclient/instancemethods/cancel-runs-for-event",
@@ -325,6 +326,7 @@
325326
"sdk/io/wait",
326327
"sdk/io/logger",
327328
"sdk/io/sendevent",
329+
"sdk/io/sendevents",
328330
"sdk/io/backgroundfetch",
329331
"sdk/io/random",
330332
"sdk/io/try",

‎docs/sdk/io/overview.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,16 @@ Waits for a certain amount of time before continuing the Job. Delays works even
3232

3333
### [sendEvent()](/sdk/io/sendevent)
3434

35-
`io.sendEvent()` allows you to send an event from inside a Job run. The sent even will trigger any Jobs that are listening for that event (based on the name).
35+
`io.sendEvent()` allows you to send an event from inside a Job run. The sent event will trigger any Jobs that are listening for that event (based on the name).
3636

3737
If you want to send an event from outside a run (e.g. just from your backend) you can use [client.sendEvent()](/sdk/triggerclient/instancemethods/sendevent).
3838

39+
### [sendEvents()](/sdk/io/sendevents)
40+
41+
`io.sendEvents()` allows you to send multiple events from inside a Job run. The sent events will trigger any Jobs that are listening for those events (based on the name).
42+
43+
If you want to send multiple events from outside a run (e.g. just from your backend) you can use [client.sendEvents()](/sdk/triggerclient/instancemethods/sendevents).
44+
3945
### [backgroundFetch()](/sdk/io/backgroundfetch)
4046

4147
`io.backgroundFetch()` allows you to fetch data from a URL that can take longer that the serverless timeout. The actual `fetch` request is performed on the Trigger.dev platform, and the response is sent back to you. An example use case is fetching data from a slow API, like some AI endpoints.

‎docs/sdk/io/sendevent.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
---
22
title: "io.sendEvent()"
33
sidebarTitle: "sendEvent()"
4-
description: "`io.sendEvent()` allows you to send an event from inside a Job run. The sent even will trigger any Jobs that are listening for that event (based on the name)."
4+
description: "`io.sendEvent()` allows you to send an event from inside a Job run. The sent event will trigger any Jobs that are listening for that event (based on the name)."
55
---
66

77
If you want to send an event from outside a run (e.g. just from your backend) you should use [client.sendEvent()](/sdk/triggerclient/instancemethods/sendevent) instead.
88

99
Use [eventTrigger()](/sdk/eventtrigger) on a Job to listen for events.
1010

11+
For multiple events, use [io.sendEvents()](/sdk/io/sendevents) instead.
12+
1113
## Parameters
1214

1315
<Snippet file="stable-key-param.mdx" />

‎docs/sdk/io/sendevents.mdx‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: "io.sendEvents()"
3+
sidebarTitle: "sendEvents()"
4+
description: "`io.sendEvents()` allows you to send multiple events from inside a Job run. The sent events will trigger any Jobs that are listening for those events (based on the name)."
5+
---
6+
7+
If you want to send multiple events from outside a run (e.g. just from your backend) you should use [client.sendEvents()](/sdk/triggerclient/instancemethods/sendevents) instead.
8+
9+
Use [eventTrigger()](/sdk/eventtrigger) on a Job to listen for events.
10+
11+
For single events, use [io.sendEvent()](/sdk/io/sendevent) instead.
12+
13+
## Parameters
14+
15+
<Snippet file="stable-key-param.mdx" />
16+
17+
<Snippet file="send-events-params.mdx" />
18+
19+
## Returns
20+
21+
<Snippet file="send-events-return.mdx" />
22+
23+
<RequestExample>
24+
25+
```ts Send multiple events
26+
//this Job sends multiple events that triggers the second job
27+
client.defineJob({
28+
id: "job-1",
29+
name: "First job",
30+
version: "0.0.1",
31+
trigger: cronTrigger({
32+
cron: "0 9 * * *", // 9am every day (UTC)
33+
}),
34+
run: async (payload, io, ctx) => {
35+
//sends "new.user" events with a userId in the payload
36+
await io.sendEvents("send-events", [
37+
{
38+
name: "new.user",
39+
payload: {
40+
userId: "u_12345",
41+
},
42+
},
43+
{
44+
name: "new.user",
45+
payload: {
46+
userId: "u_67890",
47+
},
48+
},
49+
]);
50+
},
51+
});
52+
53+
client.defineJob({
54+
id: "job-2",
55+
name: "Second job",
56+
version: "0.0.1",
57+
//subscribes to the "new.user" event
58+
trigger: eventTrigger({
59+
name: "new.user",
60+
schema: z.object({
61+
userId: z.string(),
62+
}),
63+
}),
64+
run: async (payload, io, ctx) => {
65+
await io.logger.log("New user created", { userId: payload.userId });
66+
//do stuff with the new user
67+
},
68+
});
69+
```
70+
71+
</RequestExample>

‎docs/sdk/triggerclient/instancemethods/sendevent.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ You can call this function from anywhere in your backend to send an event. The o
88

99
Use [eventTrigger()](/sdk/eventtrigger) on a Job to listen for events.
1010

11+
For multiple events, use [client.sendEvents()](/sdk/triggerclient/instancemethods/sendevents) instead.
12+
1113
## Parameters
1214

1315
<Snippet file="send-event-params.mdx" />

‎docs/sdk/triggerclient/instancemethods/sendevents.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: "TriggerClient: sendEvents() instance method"
3+
sidebarTitle: "sendEvents()"
4+
description: "The `sendEvents()` instance method send multiple events that triggers any Jobs that are listening for those events (based on the name)."
5+
---
6+
7+
You can call this function from anywhere in your backend to send multiple events. The other way to send multiple events is by using [io.sendEvents()](/sdk/io/sendevents) from inside a `run()` function.
8+
9+
Use [eventTrigger()](/sdk/eventtrigger) on a Job to listen for events.
10+
11+
For single events, use [client.sendEvent()](/sdk/triggerclient/instancemethods/sendevent) instead.
12+
13+
## Parameters
14+
15+
<Snippet file="send-events-params.mdx" />
16+
17+
## Returns
18+
19+
<Snippet file="send-events-return.mdx" />
20+
21+
<RequestExample>
22+
23+
```ts Simple example with payloads
24+
const event = client.sendEvents([
25+
{
26+
name: "new.user",
27+
payload: {
28+
userId: "u_12345",
29+
},
30+
},
31+
{
32+
name: "new.user",
33+
payload: {
34+
userId: "u_67890",
35+
},
36+
},
37+
]);
38+
```
39+
40+
```ts Send multiple events with an ID
41+
const event = client.sendEvents([
42+
{
43+
id: "e_12345", // You can use this to deduplicate events
44+
name: "new.user",
45+
payload: {
46+
userId: "u_12345",
47+
},
48+
},
49+
{
50+
id: "e_67890", // You can use this to deduplicate events
51+
name: "new.user",
52+
payload: {
53+
userId: "u_67890",
54+
},
55+
},
56+
]);
57+
```
58+
59+
```ts Send multiple events to be delivered later
60+
const event = client.sendEvents(
61+
[
62+
{
63+
id: "e_12345", // You can use this to deduplicate events
64+
name: "new.user",
65+
payload: {
66+
userId: "u_12345",
67+
},
68+
},
69+
{
70+
id: "e_67890", // You can use this to deduplicate events
71+
name: "new.user",
72+
payload: {
73+
userId: "u_67890",
74+
},
75+
},
76+
],
77+
{
78+
deliverAt: new Date("2023-12-01T00:00:00.000Z"),
79+
}
80+
);
81+
```
82+
83+
</RequestExample>

‎docs/sdk/triggerclient/overview.mdx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,12 @@ Sending an event triggers any Jobs that are listening for that event (based on t
3838

3939
You can call this function from anywhere in your code to send an event. The other way to send an event is by using [io.sendEvent()](/sdk/io) from inside a `run()` function.
4040

41+
#### [sendEvents()](/sdk/triggerclient/instancemethods/sendevents)
42+
43+
Sending multiple events triggers any Jobs that are listening for those events (based on the name). Use [eventTrigger()](/sdk/eventtrigger) on a Job to listen for events.
44+
45+
You can call this function from anywhere in your code to send multiple events. The other way to send multiple events is by using [io.sendEvents()](/sdk/io) from inside a `run()` function.
46+
4147
#### [getEvent()](/sdk/triggerclient/instancemethods/getevent)
4248

4349
The `getEvent()` method gets the event details for a given eventId.

0 commit comments

Comments
 (0)