@project-ajax/create 0.0.27 → 0.0.30

package/dist/index.js

@@ -94,14 +94,12 @@ function printNextSteps(directoryName) {
   if (directoryName === ".") {
     console.log(`
   ${chalk.bold("npm install")}
-  ${chalk.bold("npx workers auth login")}
   ${chalk.bold("npx workers deploy")}
     `);
   } else {
     console.log(`
   ${chalk.bold(`cd ${directoryName}`)}
   ${chalk.bold("npm install")}
-  ${chalk.bold("npx workers auth login")}
   ${chalk.bold("npx workers deploy")}
     `);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/create",
-	"version": "0.0.27",
+	"version": "0.0.30",
 	"description": "Initialize a new Notion Project Ajax extensions repo.",
 	"bin": {
 		"create-ajax": "dist/index.js"

package/template/.examples/oauth-example.ts

@@ -54,7 +54,7 @@ worker.sync("googleCalendarSync", {
 		// Use token to fetch from Google Calendar API
 		console.log("Using Google token:", `${token.slice(0, 10)}...`);
 
-		return { objects: [], done: true };
+		return { changes: [], hasMore: false };
 	},
 });
 

package/template/.examples/sync-example.ts

@@ -5,6 +5,41 @@ import * as Schema from "@project-ajax/sdk/schema";
 const worker = new Worker();
 export default worker;
 
+const projectId = "project-1";
+const projectName = "Example Project";
+
+worker.sync("projectsSync", {
+	// Which field to use in each object as the primary key. Must be unique.
+	primaryKeyProperty: "Project ID",
+	// The schema of the collection to create in Notion.
+	schema: {
+		// Name of the collection to create in Notion.
+		defaultName: "Projects",
+		properties: {
+			// See `Schema` for the full list of possible column types.
+			"Project Name": Schema.title(),
+			"Project ID": Schema.richText(),
+		},
+	},
+	execute: async () => {
+		// Fetch and return data
+		return {
+			changes: [
+				// Each change must match the shape of `properties` above.
+				{
+					type: "upsert" as const,
+					key: projectId,
+					properties: {
+						"Project Name": Builder.title(projectName),
+						"Project ID": Builder.richText(projectId),
+					},
+				},
+			],
+			hasMore: false,
+		};
+	},
+});
+
 worker.sync("mySync", {
 	// Which field to use in each object as the primary key. Must be unique.
 	primaryKeyProperty: "ID",
@@ -16,22 +51,25 @@ worker.sync("mySync", {
 			// See `Schema` for the full list of possible column types.
 			Title: Schema.title(),
 			ID: Schema.richText(),
+			Project: Schema.relation("projectsSync"),
 		},
 	},
 	execute: async () => {
 		// Fetch and return data
 		return {
-			objects: [
-				// Each object must match the shape of `properties` above.
+			changes: [
+				// Each change must match the shape of `properties` above.
 				{
+					type: "upsert" as const,
 					key: "1",
 					properties: {
 						Title: Builder.title("Item 1"),
 						ID: Builder.richText("1"),
+						Project: [Builder.relation(projectId)],
 					},
 				},
 			],
-			done: true,
+			hasMore: false,
 		};
 	},
 });

package/template/AGENTS.md

@@ -20,18 +20,10 @@ export default worker;
 worker.sync("tasksSync", {
   primaryKeyProperty: "ID",
   schema: { defaultName: "Tasks", properties: { Name: Schema.title(), ID: Schema.richText() } },
-  execute: async (context?: { cursor?: string }) => {
-    const pageSize = 100;
-    const { items, nextCursor } = await fetchItems({ cursor: context?.cursor, limit: pageSize });
-    return {
-      objects: items.map((item) => ({
-        key: item.id,
-        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
-      })),
-      done: !nextCursor,
-      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
-    };
-  },
+  execute: async () => ({
+    changes: [{ type: "upsert", key: "1", properties: { Name: Builder.title("Write docs"), ID: Builder.richText("1") } }],
+    hasMore: false,
+  }),
 });
 
 worker.tool("sayHello", {
@@ -52,17 +44,30 @@ worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
 
 - For user-managed OAuth, supply `name`, `authorizationEndpoint`, `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` (optional: `authorizationParams`, `callbackUrl`, `accessTokenExpireMs`).
 
-### Sync Pagination
+### Sync
+#### Strategy and Pagination
+
+Syncs run in a "sync cycle": a back-to-back chain of `execute` calls that starts at a scheduled trigger and ends when an execution returns `hasMore: false`.
 
-Implement pagination in syncs to avoid exceeding maximum output size limits. Returning too many objects in a single execution can cause the output JSON to exceed size limits and fail.
+- Always use pagination, when available. Returning too many changes in one execution will fail. Start with batch sizes of ~100 changes.
+- `mode=replace` is simpler, and fine for smaller syncs (<10k)
+- Use `mode=incremental` when the sync could return a lot of data (>10k), eg for SaaS tools like Salesforce or Stripe
+- When using `mode=incremental`, emit delete markers as needed if easy to do (below)
+
+**Sync strategy (`mode`):**
+- `replace`: each sync cycle must return the full dataset. After the final `hasMore: false`, any records not seen during that cycle are deleted.
+- `incremental`: each sync cycle returns a subset of the full dataset (usually the changes since the last run). Deletions must be explicit via `{ type: "delete", key: "..." }`. Records not mentioned are left unchanged.
 
 **How pagination works:**
-1. Return a batch of objects with `done: false` and a `nextContext` value
+1. Return a batch of changes with `hasMore: true` and a `nextContext` value
 2. The runtime calls `execute` again with that context
-3. Continue until you return `done: true`
+3. Continue until you return `hasMore: false`
+
+**Example replace sync:**
 
 ```ts
 worker.sync("paginatedSync", {
+  mode: "replace",
   primaryKeyProperty: "ID",
   schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
   execute: async (context?: { page: number }) => {
@@ -70,11 +75,12 @@ worker.sync("paginatedSync", {
     const pageSize = 100;
     const { items, hasMore } = await fetchPage(page, pageSize);
     return {
-      objects: items.map((item) => ({
+      changes: items.map((item) => ({
+        type: "upsert",
         key: item.id,
         properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
       })),
-      done: !hasMore,
+      hasMore,
       nextContext: hasMore ? { page: page + 1 } : undefined,
     };
   },
@@ -83,6 +89,72 @@ worker.sync("paginatedSync", {
 
 **Context types:** The `nextContext` can be any serializable value—a cursor string, page number, timestamp, or complex object. Type your execute function's context parameter to match.
 
+**Incremental example (changes only, with deletes):**
+```ts
+worker.sync("incrementalSync", {
+  primaryKeyProperty: "ID",
+  mode: "incremental",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { cursor?: string }) => {
+    const { upserts, deletes, nextCursor } = await fetchChanges(context?.cursor);
+    return {
+      changes: [
+        ...upserts.map((item) => ({
+          type: "upsert",
+          key: item.id,
+          properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+        })),
+        ...deletes.map((id) => ({ type: "delete", key: id })),
+      ],
+      hasMore: Boolean(nextCursor),
+      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+    };
+  },
+});
+```
+
+#### Relations
+
+Two syncs can relate to one another using `Schema.relation(relatedSyncKey)` and `Builder.relation(primaryKey)` entries inside an array.
+
+```ts
+worker.sync("projectsSync", {
+	primaryKeyProperty: "Project ID",
+  ...
+});
+
+// Example sync worker that syncs sample tasks to a database
+worker.sync("tasksSync", {
+	primaryKeyProperty: "Task ID",
+  ...
+	schema: {
+    ...
+		properties: {
+      ...
+			Project: Schema.relation("projectsSync"),
+		},
+	},
+
+	execute: async () => {
+		// Return sample tasks as database entries
+    const tasks = fetchTasks()
+		const changes = tasks.map((task) => ({
+			type: "upsert" as const,
+			key: task.id,
+			properties: {
+        ...
+				Project: [Builder.relation(task.projectId)],
+			},
+		}));
+
+		return {
+			changes,
+			hasMore: false,
+		};
+	},
+});
+```
+
 ## Build, Test, and Development Commands
 - Node >= 22 and npm >= 10.9.2 (see `package.json` engines).
 - `npm run dev`: run `src/index.ts` with live reload.

package/template/README.md

@@ -22,10 +22,9 @@ npm install
 Connect to a Notion workspace and deploy the sample worker:
 
 ```shell
-npx workers auth login
-# or target a specific environment:
-npx workers auth login --env=dev
 npx workers deploy
+# or target a specific environment:
+npx workers deploy --env=dev
 ```
 
 Run the sample sync to create a database:
@@ -56,6 +55,8 @@ export default worker;
 
 Syncs create or update a Notion database from your source data.
 
+The most basic sync returns all data that should be copied to the Notion database on each run:
+
 ```ts
 import * as Builder from "@project-ajax/sdk/builder";
 import * as Schema from "@project-ajax/sdk/schema";
@@ -73,8 +74,9 @@ worker.sync("tasksSync", {
     },
   },
   execute: async () => ({
-    objects: [
+    changes: [
       {
+        type: "upsert",
         key: "1",
         properties: {
           Name: Builder.title("Write docs"),
@@ -82,11 +84,92 @@ worker.sync("tasksSync", {
         },
       },
     ],
-    done: true,
+    hasMore: false,
   }),
 });
 ```
 
+Notion will delete stale rows after each run. A stale row is a row that was in the database but that your function did not return.
+
+#### Write a sync that paginates
+
+When your sync is pulling in many rows of data (>1k), you'll want to use pagination. Breaking down pages to ~100 is a good starting point.
+
+You can use **context** to persist things like pagination tokens between `execute` runs. Notion passes `context` as the first argument to `execute`. Return `nextContext` to set the `context` for the next run:
+
+```ts
+worker.sync("fullSync", {
+  primaryKeyProperty: "ID",
+  mode: "replace",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { page: number }) => {
+    const { items , nextCursor } = await fetchPage(context?.page);
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore: nextCursor ? true : false,
+      nextCursor
+    };
+  },
+});
+```
+
+Return `hasMore=false` for each run until you reach the end. On the last run, return `hasMore=true`. At the start of the next cycle, Notion will start anew and call `execute` with `context=null`.
+
+#### Write a sync that syncs incrementally
+
+When your sync is working with a lot of data (10k+), you'll want to use the `incremental` sync mode. With incremental syncs, you can for example backfill all the data from an API into Notion, and then sync only incremental updates from that point forward.
+
+Set the sync's `mode` to `incremental` and use pagination as above:
+
+```ts
+worker.sync("incrementalSync", {
+  primaryKeyProperty: "ID",
+  mode: "incremental",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { cursor?: string }) => {
+    const { upserts, deletes, nextCursor } = await fetchChanges(context?.cursor);
+    return {
+      changes: [
+        ...upserts.map((item) => ({
+          type: "upsert",
+          key: item.id,
+          properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+        })),
+        ...deletes.map((id) => ({ type: "delete", key: id })),
+      ],
+      hasMore: Boolean(nextCursor),
+      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+    };
+  },
+});
+```
+
+Unlike the `replace` sync mode, Notion will not drop "stale" rows and `context` will persist between sync cycles.
+
+**Deletes**
+
+With incremental syncs, you can delete rows by returning a delete marker, like so:
+
+```ts
+changes: [
+  // this is an upsert
+  {
+    type: "upsert",
+    key: item.id,
+    properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+  },
+  // this is a delete
+  {
+    type: "delete",
+    key: item.id
+  }
+]
+```
+
 ### Tool
 
 Tools are callable by Notion custom agents.
@@ -155,6 +238,9 @@ Log in to Notion (use `--env=dev` for dev):
 npx workers auth login --env=dev
 ```
 
+Login is automatically handled by `npx workers deploy`, so this command is
+typically not needed.
+
 ### `npx workers auth show`
 Show the active auth token:
 

package/template/src/index.ts

@@ -5,6 +5,9 @@ import * as Schema from "@project-ajax/sdk/schema";
 const worker = new Worker();
 export default worker;
 
+const projectId = "project-123";
+const projectName = "Project 1";
+
 // Sample data for demonstration
 const sampleTasks = [
 	{
@@ -12,21 +15,52 @@ const sampleTasks = [
 		title: "Welcome to Project Ajax",
 		status: "Completed",
 		description: "This is a simple hello world example",
+		projectId,
 	},
 	{
 		id: "task-2",
 		title: "Build your first worker",
 		status: "In Progress",
 		description: "Create a sync or tool worker",
+		projectId,
 	},
 	{
 		id: "task-3",
 		title: "Deploy to production",
 		status: "Todo",
 		description: "Share your worker with your team",
+		projectId,
 	},
 ];
 
+worker.sync("projectsSync", {
+	primaryKeyProperty: "Project ID",
+	schema: {
+		defaultName: "Projects",
+		databaseIcon: Builder.notionIcon("activity"),
+		properties: {
+			"Project Name": Schema.title(),
+			"Project ID": Schema.richText(),
+		},
+	},
+	execute: async () => {
+		return {
+			changes: [
+				{
+					type: "upsert" as const,
+					key: projectId,
+					icon: Builder.notionIcon("activity"),
+					properties: {
+						"Project Name": Builder.title(projectName),
+						"Project ID": Builder.richText(projectId),
+					},
+				},
+			],
+			hasMore: false,
+		};
+	},
+});
+
 // Example sync worker that syncs sample tasks to a database
 worker.sync("tasksSync", {
 	primaryKeyProperty: "Task ID",
@@ -35,9 +69,13 @@ worker.sync("tasksSync", {
 	// Use intervals like "30m", "1h", "1d" (min: 1m, max: 7d)
 	schedule: "continuous",
 
-	// Optional: Set to true to delete pages that are not returned from sync executions.
-	// By default (false), sync only creates and updates pages, never deletes them.
-	// deleteUnreturnedPages: true,
+	// Sync mode:
+	// - "replace": Each sync cycle returns the complete dataset. After hasMore:false,
+	//              pages not seen in this sync run are deleted.
+	// - "incremental": Each sync cycle returns a subset of the complete dataset. Use delete markers
+	//                  (e.g., { type: "delete", key: "task-1" }) to remove pages.
+	// Defaults to "replace".
+	// mode: "replace",
 
 	schema: {
 		defaultName: "Sample Tasks",
@@ -51,6 +89,7 @@ worker.sync("tasksSync", {
 				{ name: "In Progress", color: "blue" },
 				{ name: "Todo", color: "default" },
 			]),
+			Project: Schema.relation("projectsSync"),
 		},
 	},
 
@@ -68,7 +107,8 @@ worker.sync("tasksSync", {
 			}
 		};
 		// Return sample tasks as database entries
-		const objects = sampleTasks.map((task) => ({
+		const changes = sampleTasks.map((task) => ({
+			type: "upsert" as const,
 			key: task.id,
 			icon: emojiForStatus(task.status),
 			properties: {
@@ -76,13 +116,19 @@ worker.sync("tasksSync", {
 				"Task ID": Builder.richText(task.id),
 				Description: Builder.richText(task.description),
 				Status: Builder.select(task.status),
+				Project: [Builder.relation(projectId)],
 			},
 			pageContentMarkdown: `## ${task.title}\n\n${task.description}`,
 		}));
 
 		return {
-			objects,
-			done: true,
+			// List of changes to apply to the Notion database.
+			changes,
+			// Indicates whether there is more data to fetch this sync cycle. If true, the runtime will call `execute` again with the nextContext.
+			hasMore: false,
+			// Optional context data Notion will pass back in the next execution.
+			// This can be any type of data (cursor, page number, timestamp, etc.).
+			nextContext: undefined,
 		};
 	},
 });