create-ncblock 0.0.39 → 0.0.41

package/templates/worker/.examples/automation-example.ts

@@ -0,0 +1,60 @@
+/**
+ * Automations are only available in a private alpha.
+ */
+
+import { Worker } from "@notionhq/workers"
+
+const worker = new Worker()
+export default worker
+
+type RichTextProperty = {
+	type: "rich_text"
+	rich_text: Array<{ plain_text: string }>
+}
+
+/**
+ * Example automation that sends an email based on a database page property.
+ *
+ * This automation:
+ * 1. Reads an email address from a page property
+ * 2. Sends an email to that address
+ * 3. Updates the page to indicate the email has been sent
+ */
+worker.automation("sendEmailAutomation", {
+	title: "Send Email Automation",
+	description: "Reads an email address from a database page and sends an email",
+	execute: async (event, { notion }) => {
+		const { pageId, pageData } = event
+		// Extract email from the page data
+		const emailProperty = pageData?.properties?.Email as
+			| RichTextProperty
+			| undefined
+
+		// Extract text content from the property
+		let emailValue = ""
+		if (emailProperty?.type === "rich_text") {
+			emailValue = emailProperty.rich_text.map(rt => rt.plain_text).join("")
+		}
+
+		// Handle empty email or pageId
+		if (!emailValue || !pageId) {
+			return
+		}
+
+		await sendEmail(emailValue)
+
+		// Update the page to indicate the email has been sent
+		await notion.pages.update({
+			page_id: pageId,
+			properties: {
+				EmailSent: {
+					checkbox: true,
+				},
+			},
+		})
+	},
+})
+
+async function sendEmail(email: string): Promise<void> {
+	console.log(`Sending email to ${email}`)
+}

package/templates/worker/.examples/oauth-example.ts

@@ -0,0 +1,79 @@
+import { Worker } from "@notionhq/workers"
+import * as Schema from "@notionhq/workers/schema"
+import { j } from "@notionhq/workers/schema-builder"
+
+const worker = new Worker()
+export default worker
+
+/**
+ * OAuth capabilities let your worker access third-party APIs.
+ *
+ * After deploying your worker, start OAuth from the CLI:
+ *
+ *   ntn workers oauth start <capabilityKey>
+ *
+ * Where `capabilityKey` is the OAuth capability's key (see `ntn workers capabilities list`).
+ * Once OAuth completes, the worker runtime exposes the access token via an
+ * environment variable and `accessToken()` reads it for you.
+ */
+
+// Option 1: Notion-managed provider (recommended when available).
+// Notion owns the OAuth app credentials and the backend has pre-configured provider settings.
+// Notion-managed providers are only available in a private alpha.
+const googleAuth = worker.oauth("googleAuth", {
+	name: "google-calendar",
+	provider: "google",
+})
+
+// Option 2: User-managed provider (you own the OAuth app credentials).
+// Keep client credentials in worker secrets and read them from `process.env`.
+// Generally available.
+const myCustomAuth = worker.oauth("myCustomAuth", {
+	name: "my-custom-provider",
+	authorizationEndpoint: "https://provider.example.com/oauth/authorize",
+	tokenEndpoint: "https://provider.example.com/oauth/token",
+	scope: "read write",
+	clientId: "1234567890",
+	clientSecret: process.env.MY_CUSTOM_OAUTH_CLIENT_SECRET ?? "",
+	authorizationParams: {
+		access_type: "offline",
+		prompt: "consent",
+	},
+})
+
+// Use the OAuth handles in your capabilities
+const calendarEvents = worker.database("calendarEvents", {
+	type: "managed",
+	initialTitle: "Calendar Events",
+	primaryKeyProperty: "Event ID",
+	schema: {
+		properties: {
+			Title: Schema.title(),
+			"Event ID": Schema.richText(),
+		},
+	},
+})
+
+worker.sync("googleCalendarSync", {
+	database: calendarEvents,
+	execute: async () => {
+		// Get the OAuth access token
+		const token = await googleAuth.accessToken()
+
+		// Use token to fetch from Google Calendar API
+		console.log("Using Google token:", `${token.slice(0, 10)}...`)
+
+		return { changes: [], hasMore: false }
+	},
+})
+
+worker.tool("customApiTool", {
+	title: "Custom API Tool",
+	description: "Calls a custom API using OAuth",
+	schema: j.object({}),
+	execute: async () => {
+		const token = await myCustomAuth.accessToken()
+		console.log("Using custom provider token:", `${token.slice(0, 10)}...`)
+		return { success: true }
+	},
+})

package/templates/worker/.examples/sync-example.ts

@@ -0,0 +1,184 @@
+/**
+ * Example: syncing projects and tasks from an external API to Notion.
+ *
+ * Demonstrates:
+ * - Database declarations (hoisted from sync config)
+ * - Pacers for rate limiting upstream API requests
+ * - Relations between databases
+ * - Backfill + delta sync pattern
+ */
+
+import { Worker } from "@notionhq/workers"
+import * as Builder from "@notionhq/workers/builder"
+import * as Schema from "@notionhq/workers/schema"
+
+const worker = new Worker()
+export default worker
+
+// -- Pacer: rate-limit requests to the upstream API --
+// Research the API's rate limits and declare them here.
+// If multiple syncs share a pacer, the budget is apportioned evenly.
+const exampleApi = worker.pacer("exampleApi", {
+	allowedRequests: 10, // 10 requests
+	intervalMs: 1000, // per second
+})
+
+// -- Databases --
+
+const projects = worker.database("projects", {
+	type: "managed",
+	initialTitle: "Projects",
+	primaryKeyProperty: "Project ID",
+	schema: {
+		properties: {
+			"Project Name": Schema.title(),
+			"Project ID": Schema.richText(),
+		},
+	},
+})
+
+const tasks = worker.database("tasks", {
+	type: "managed",
+	initialTitle: "Tasks",
+	primaryKeyProperty: "Task ID",
+	schema: {
+		properties: {
+			"Task Name": Schema.title(),
+			"Task ID": Schema.richText(),
+			Status: Schema.select([
+				{ name: "Open", color: "blue" },
+				{ name: "In Progress", color: "yellow" },
+				{ name: "Done", color: "green" },
+			]),
+			Project: Schema.relation("projectsSync", {
+				twoWay: true,
+				relatedPropertyName: "Tasks",
+			}),
+		},
+	},
+})
+
+// -- Simple replace sync for projects (small dataset) --
+
+worker.sync("projectsSync", {
+	database: projects,
+	mode: "replace",
+	schedule: "1h",
+	execute: async state => {
+		const page = state?.page ?? 1
+		await exampleApi.wait()
+		const { items, hasMore } = await fetchProjects(page)
+
+		return {
+			changes: items.map(item => ({
+				type: "upsert" as const,
+				key: item.id,
+				properties: {
+					"Project Name": Builder.title(item.name),
+					"Project ID": Builder.richText(item.id),
+				},
+			})),
+			hasMore,
+			nextState: hasMore ? { page: page + 1 } : undefined,
+		}
+	},
+})
+
+// -- Backfill + delta sync pair for tasks --
+
+// Backfill: paginates the full upstream dataset.
+// Schedule: manual. To run:
+//   ntn workers sync state reset tasksBackfill
+//   ntn workers sync trigger tasksBackfill
+// Replace mode: mark-and-sweep deletes records no longer upstream.
+worker.sync("tasksBackfill", {
+	database: tasks,
+	mode: "replace",
+	schedule: "manual",
+	execute: async state => {
+		const page = state?.page ?? 1
+		await exampleApi.wait()
+		const { items, hasMore } = await fetchAllTasks(page)
+
+		return {
+			changes: items.map(item => ({
+				type: "upsert" as const,
+				key: item.id,
+				properties: {
+					"Task Name": Builder.title(item.name),
+					"Task ID": Builder.richText(item.id),
+					Status: Builder.select(item.status),
+					Project: [Builder.relation(item.projectId)],
+				},
+			})),
+			hasMore,
+			nextState: hasMore ? { page: page + 1 } : undefined,
+		}
+	},
+})
+
+// Delta: fetches only recent changes.
+// Schedule: runs every 5 minutes to keep Notion up to date.
+// Incremental mode: only returns changes since the last cursor.
+worker.sync("tasksDelta", {
+	database: tasks,
+	mode: "incremental",
+	schedule: "5m",
+	execute: async state => {
+		const cursor = state?.cursor
+		await exampleApi.wait()
+		const { items, nextCursor } = await fetchTaskChanges(cursor)
+
+		return {
+			changes: items.map(item => ({
+				type: "upsert" as const,
+				key: item.id,
+				properties: {
+					"Task Name": Builder.title(item.name),
+					"Task ID": Builder.richText(item.id),
+					Status: Builder.select(item.status),
+					Project: [Builder.relation(item.projectId)],
+				},
+			})),
+			hasMore: Boolean(nextCursor),
+			nextState: nextCursor ? { cursor: nextCursor } : undefined,
+		}
+	},
+})
+
+// -- Placeholder functions (replace with real API calls) --
+
+async function fetchProjects(_page: number) {
+	return {
+		items: [{ id: "proj-1", name: "Example Project" }],
+		hasMore: false,
+	}
+}
+
+async function fetchAllTasks(_page: number) {
+	return {
+		items: [
+			{
+				id: "task-1",
+				name: "Write docs",
+				status: "Open",
+				projectId: "proj-1",
+			},
+		],
+		hasMore: false,
+	}
+}
+
+async function fetchTaskChanges(_cursor: string | undefined) {
+	return {
+		items: [
+			{
+				id: "task-1",
+				name: "Write docs",
+				status: "Done",
+				projectId: "proj-1",
+			},
+		],
+		nextCursor: null as string | null,
+	}
+}

package/templates/worker/.examples/tool-example.ts

@@ -0,0 +1,37 @@
+/**
+ * Tools are generally available.
+ */
+
+import { Worker } from "@notionhq/workers"
+import { j } from "@notionhq/workers/schema-builder"
+
+const worker = new Worker()
+export default worker
+
+worker.tool("myTool", {
+	title: "My Tool",
+	// Description of what this tool does - shown to the AI agent
+	description: "Search for items by keyword or ID",
+	// Use the schema builder to define input — it auto-sets required and
+	// additionalProperties, and provides type inference.
+	schema: j.object({
+		query: j.string().describe("The search query").nullable(),
+		limit: j.number().describe("Maximum number of results").nullable(),
+	}),
+	// Optional: schema for the output the tool returns
+	outputSchema: j.object({
+		results: j.array(j.string()),
+	}),
+	// The function that executes when the tool is called
+	execute: async (input, { notion: _notion }) => {
+		// Destructure input with default values
+		const { query: _query, limit: _limit = 10 } = input
+
+		// Perform your logic here
+		// Example: search your data source using the query and limit
+		const results: string[] = []
+
+		// Return data matching your outputSchema (if provided)
+		return { results }
+	},
+})

package/templates/worker/.examples/webhook-example.ts

@@ -0,0 +1,66 @@
+/**
+ * This example shows how to verify GitHub webhook signatures using
+ * HMAC-SHA256. Set GITHUB_WEBHOOK_SECRET via `ntn workers env set`.
+ *
+ * After 5 consecutive WebhookVerificationError throws, the platform
+ * short-circuits and rejects all incoming requests without executing
+ * the handler. Redeploying the worker resets the counter.
+ */
+
+import { WebhookVerificationError, Worker } from "@notionhq/workers"
+import crypto from "crypto"
+
+const worker = new Worker()
+export default worker
+
+/**
+ * Verify a GitHub webhook signature.
+ * GitHub sends the HMAC-SHA256 signature in the X-Hub-Signature-256 header
+ * as "sha256={hex}". The raw body must be used for verification.
+ */
+function verifyGitHubSignature(
+	rawBody: string,
+	headers: Record<string, string>,
+): void {
+	const secret = process.env.GITHUB_WEBHOOK_SECRET
+	if (!secret) {
+		throw new WebhookVerificationError("GITHUB_WEBHOOK_SECRET not configured")
+	}
+
+	const signature = headers["x-hub-signature-256"]
+	if (!signature?.startsWith("sha256=")) {
+		throw new WebhookVerificationError("Invalid GitHub signature")
+	}
+
+	const expected = `sha256=${crypto
+		.createHmac("sha256", secret)
+		.update(rawBody)
+		.digest("hex")}`
+
+	if (signature.length !== expected.length) {
+		throw new WebhookVerificationError("Invalid GitHub signature")
+	}
+
+	// Use timing-safe comparison to prevent timing attacks
+	if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+		throw new WebhookVerificationError("Invalid GitHub signature")
+	}
+}
+
+worker.webhook("onGithubPush", {
+	title: "GitHub Push Webhook",
+	description: "Handles push events from GitHub repositories",
+	execute: async events => {
+		for (const event of events) {
+			verifyGitHubSignature(event.rawBody, event.headers)
+
+			// Signature verified — safe to process
+			const body = event.body
+			const ref = body.ref as string | undefined
+			const pusher = body.pusher as { name?: string } | undefined
+			console.log(
+				`Verified push to ${ref ?? "unknown"} by ${pusher?.name ?? "unknown"}`,
+			)
+		}
+	},
+})