diff --git a/packages/internal/src/schemas/api.ts b/packages/internal/src/schemas/api.ts index 2e987214a..179d0c5a9 100644 --- a/packages/internal/src/schemas/api.ts +++ b/packages/internal/src/schemas/api.ts @@ -184,32 +184,73 @@ export const IndexEndpointResponseSchema = z.object({ export type IndexEndpointResponse = z.infer; export const RawEventSchema = z.object({ - id: z.string().default(() => ulid()), + /** The `name` property must exactly match any subscriptions you want to + trigger. */ name: z.string(), - source: z.string().optional(), + /** The `payload` property will be sent to any matching Jobs and will appear + as the `payload` param of the `run()` function. You can leave this + parameter out if you just want to trigger a Job without any input data. */ payload: z.any(), + /** The optional `context` property will be sent to any matching Jobs and will + be passed through as the `context.event.context` param of the `run()` + function. This is optional but can be useful if you want to pass through + some additional context to the Job. */ context: z.any().optional(), + /** The `id` property uniquely identify this particular event. If unset it + will be set automatically using `ulid`. */ + id: z.string().default(() => ulid()), + /** This is optional, it defaults to the current timestamp. Usually you would + only set this if you have a timestamp that you wish to pass through, e.g. + you receive a timestamp from a service and you want the same timestamp to + be used in your Job. */ timestamp: z.string().datetime().optional(), + /** This is optional, it defaults to "trigger.dev". It can be useful to set + this as you can filter events using this in the `eventTrigger()`. */ + source: z.string().optional(), }); export type RawEvent = z.infer; + +/** The event you wish to send to Trigger a Job */ export type SendEvent = z.input; +/** The event that was sent */ export const ApiEventLogSchema = z.object({ + /** The `id` of the event that was sent. + */ id: z.string(), + /** The `name` of the event that was sent. */ name: z.string(), + /** The `payload` of the event that was sent */ payload: DeserializedJsonSchema, + /** The `context` of the event that was sent. Is `undefined` if no context was + set when sending the event. */ context: DeserializedJsonSchema.optional().nullable(), + /** The `timestamp` of the event that was sent */ timestamp: z.coerce.date(), + /** The timestamp when the event will be delivered to any matching Jobs. Is + `undefined` if `deliverAt` or `deliverAfter` wasn't set when sending the + event. */ deliverAt: z.coerce.date().optional().nullable(), + /** The timestamp when the event was delivered. Is `undefined` if `deliverAt` + or `deliverAfter` were set when sending the event. */ deliveredAt: z.coerce.date().optional().nullable(), }); export type ApiEventLog = z.infer; +/** Options to control the delivery of the event */ export const SendEventOptionsSchema = z.object({ + /** An optional Date when you want the event to Trigger Jobs. The event will + be sent to the platform immediately but won't be acted upon until the + specified time. */ deliverAt: z.string().datetime().optional(), + /** An optional number of seconds you want to wait for the event to Trigger + any relevant Jobs. The event will be sent to the platform immediately but + won't be acted upon until the specified time. */ deliverAfter: z.number().int().optional(), + /** This optional param will be used by the Trigger.dev Connect feature, which + is coming soon. */ accountId: z.string().optional(), }); @@ -502,7 +543,7 @@ export const InitializeTriggerBodySchema = z.object({ id: z.string(), params: z.any(), accountId: z.string().optional(), - metadata: z.any().optional() + metadata: z.any().optional(), }); export type InitializeTriggerBody = z.infer; diff --git a/packages/trigger-sdk/src/triggerClient.ts b/packages/trigger-sdk/src/triggerClient.ts index c1f390e72..a7749f35d 100644 --- a/packages/trigger-sdk/src/triggerClient.ts +++ b/packages/trigger-sdk/src/triggerClient.ts @@ -9,6 +9,7 @@ import { NormalizedResponse, PreprocessRunBody, PreprocessRunBodySchema, + Prettify, REGISTER_SOURCE_EVENT, RegisterSourceEvent, RegisterSourceEventSchema, @@ -45,12 +46,20 @@ const registerSourceEvent: EventSpecification = { }; export type TriggerClientOptions = { + /** The `id` property is used to uniquely identify the client. + */ id: string; + /** The `apiKey` property is the API Key for your Trigger.dev environment. We + recommend using an environment variable to store your API Key. */ apiKey?: string; + /** The `apiUrl` property is an optional property that specifies the API URL. You + only need to specify this if you are not using Trigger.dev Cloud and are + running your own Trigger.dev instance. */ apiUrl?: string; logLevel?: LogLevel; }; +/** A [TriggerClient](https://trigger.dev/docs/documentation/concepts/client-adaptors) is used to connect to a specific [Project](https://trigger.dev/docs/documentation/concepts/projects) by using an [API Key](https://trigger.dev/docs/documentation/concepts/environments-apikeys). */ export class TriggerClient { #options: TriggerClientOptions; #registeredJobs: Record>, any>> = @@ -81,7 +90,7 @@ export class TriggerClient { #logger: Logger; id: string; - constructor(options: TriggerClientOptions) { + constructor(options: Prettify) { this.id = options.id; this.#options = options; this.#client = new ApiClient(this.#options); @@ -528,6 +537,8 @@ export class TriggerClient { return this.#client.getAuth(this.id, id); } + /** 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()` from inside a `run()` function. + */ async sendEvent(event: SendEvent, options?: SendEventOptions) { return this.#client.sendEvent(event, options); }