chore(examples): add bots, background-jobs, and workflows examples (#1395)

Author: NathanFlurry

examples/ai-agent/src/backend/my-utils.ts renamed to examples/ai-agent/src/backend/my-tools.ts

@@ -2,13 +2,8 @@ import { openai } from "@ai-sdk/openai";
 import { generateText, tool } from "ai";
 import { actor, setup } from "rivetkit";
 import { z } from "zod";
-import { getWeather } from "./my-utils";
-
-export type Message = {
-	role: "user" | "assistant";
-	content: string;
-	timestamp: number;
-};
+import { getWeather } from "./my-tools";
+import type { Message } from "./types";
 
 export const aiAgent = actor({
 	// Persistent state that survives restarts: https://rivet.dev/docs/actors/state

examples/ai-agent/src/backend/registry.ts

@@ -0,0 +1,5 @@
+export type Message = {
+	role: "user" | "assistant";
+	content: string;
+	timestamp: number;
+};

examples/ai-agent/src/backend/types.ts

@@ -1,6 +1,7 @@
 import { createRivetKit } from "@rivetkit/react";
 import { useEffect, useState } from "react";
-import type { Message, registry } from "../backend/registry";
+import { registry } from "../backend/registry";
+import type { Message } from "../backend/types";
 
 const { useActor } = createRivetKit<typeof registry>("http://localhost:8080");
 

examples/ai-agent/src/frontend/App.tsx

@@ -14,7 +14,7 @@ vi.mock("ai", () => ({
 	tool: vi.fn().mockImplementation(({ execute }) => ({ execute })),
 }));
 
-vi.mock("../src/backend/my-utils", () => ({
+vi.mock("../src/backend/my-tools", () => ({
 	getWeather: vi.fn().mockResolvedValue({
 		location: "San Francisco",
 		temperature: 72,

examples/ai-agent/tests/ai-agent.test.ts

@@ -0,0 +1,2 @@
+.actorcore
+node_modules

examples/background-jobs/.gitignore

@@ -0,0 +1,37 @@
+# Daily Email Campaign for RivetKit
+
+Example project demonstrating scheduled background emails with [RivetKit](https://rivetkit.org).
+
+[Learn More →](https://github.com/rivet-dev/rivetkit)
+
+[Discord](https://rivet.dev/discord) — [Documentation](https://rivetkit.org) — [Issues](https://github.com/rivet-dev/rivetkit/issues)
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- [Resend](https://resend.com) API key and verified sender domain
+
+### Installation
+
+```sh
+git clone https://github.com/rivet-dev/rivetkit
+cd rivetkit/examples/background-jobs
+npm install
+```
+
+### Development
+
+```sh
+RESEND_API_KEY=your-api-key \
+RESEND_FROM_EMAIL="Example <[email protected]>" \
+[email protected] \
+npm run dev
+```
+
+The example creates a single `emailCampaignUser` actor, stores the recipient email, and schedules a daily task that sends mail through the live Resend API. The server logs the next scheduled send time, and the actor reschedules itself after each successful delivery. Set `CAMPAIGN_USER_ID` to control the actor key when you need to track multiple users.
+
+## License
+
+Apache 2.0

examples/background-jobs/README.md

@@ -0,0 +1,22 @@
+{
+  "name": "example-background-jobs",
+  "version": "2.0.14",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/server.ts",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "rivetkit": "workspace:*",
+    "@types/node": "^22.13.9",
+    "tsx": "^3.12.7",
+    "typescript": "^5.7.3",
+    "vitest": "^3.1.1"
+  },
+  "dependencies": {
+    "resend": "^4.0.1"
+  },
+  "stableVersion": "0.8.0"
+}

examples/background-jobs/package.json

@@ -0,0 +1,52 @@
+import { Resend } from "resend";
+import { actor, setup } from "rivetkit";
+import type { CampaignInput, CampaignState } from "./types";
+
+const DAY_IN_MS = 86_400_000;
+
+const EMAIL_SUBJECT = "Daily campaign update";
+const EMAIL_BODY = [
+	"<p>Hi there,</p>",
+	"<p>This is your automated daily campaign email from RivetKit.</p>",
+	"<p>Have a great day!</p>",
+].join("");
+
+const emailCampaignUser = actor({
+	createState: (_c, input: CampaignInput): CampaignState => ({
+		email: input.email,
+	}),
+
+	onCreate: async (c) => {
+		const nextSendAt = Date.now() + DAY_IN_MS;
+		c.state.nextSendAt = nextSendAt;
+		await c.schedule.at(nextSendAt, "sendDailyEmail");
+	},
+
+	actions: {
+		sendDailyEmail: async (c) => {
+			const resend = new Resend(process.env.RESEND_API_KEY ?? "");
+
+			const { data, error } = await resend.emails.send({
+				from: process.env.RESEND_FROM_EMAIL ?? "",
+				to: c.state.email,
+				subject: EMAIL_SUBJECT,
+				html: EMAIL_BODY,
+			});
+
+			c.state.lastSentAt = Date.now();
+			c.state.lastMessageId = data?.id ?? String(error ?? "");
+
+			const nextSendAt = Date.now() + DAY_IN_MS;
+			c.state.nextSendAt = nextSendAt;
+			await c.schedule.at(nextSendAt, "sendDailyEmail");
+		},
+
+		getStatus: (c) => c.state,
+	},
+});
+
+export const registry = setup({
+	use: { emailCampaignUser },
+});
+
+export type Registry = typeof registry;

examples/background-jobs/src/registry.ts

@@ -0,0 +1,28 @@
+import { registry } from "./registry";
+
+const { client } = registry.start();
+
+async function main() {
+	const userEmail = process.env.CAMPAIGN_USER_EMAIL;
+	const userId = process.env.CAMPAIGN_USER_ID ?? "demo-user";
+
+	if (!userEmail) {
+		console.warn(
+			"Set CAMPAIGN_USER_EMAIL to schedule the daily email campaign (e.g. [email protected]).",
+		);
+		return;
+	}
+
+	const campaign = client.emailCampaignUser.getOrCreate(userId, {
+		createWithInput: { email: userEmail },
+	});
+	const status = await campaign.getStatus();
+
+	const nextSend = status.nextSendAt
+		? new Date(status.nextSendAt).toISOString()
+		: "not scheduled";
+
+	console.log(`Next daily email for ${status.email} scheduled at ${nextSend}`);
+}
+
+void main();