@project-ajax/create 0.0.26 → 0.0.28

package/package.json

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

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

@@ -29,8 +29,8 @@ const myCustomAuth = worker.oauth("myCustomAuth", {
 	authorizationEndpoint: "https://provider.example.com/oauth/authorize",
 	tokenEndpoint: "https://provider.example.com/oauth/token",
 	scope: "read write",
-	clientId: requireEnv("MY_CUSTOM_OAUTH_CLIENT_ID"),
-	clientSecret: requireEnv("MY_CUSTOM_OAUTH_CLIENT_SECRET"),
+	clientId: "1234567890",
+	clientSecret: process.env.MY_CUSTOM_OAUTH_CLIENT_SECRET ?? "",
 	authorizationParams: {
 		access_type: "offline",
 		prompt: "consent",
@@ -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 };
 	},
 });
 
@@ -73,12 +73,3 @@ worker.tool("customApiTool", {
 		return { success: true };
 	},
 });
-
-function requireEnv(key: string): string {
-	const value = process.env[key];
-	if (value) {
-		return value;
-	}
-
-	throw new Error(`Missing environment variable "${key}"`);
-}

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

@@ -21,9 +21,10 @@ worker.sync("mySync", {
 	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"),
@@ -31,7 +32,7 @@ worker.sync("mySync", {
 					},
 				},
 			],
-			done: true,
+			hasMore: false,
 		};
 	},
 });

package/template/AGENTS.md

@@ -21,8 +21,8 @@ worker.sync("tasksSync", {
   primaryKeyProperty: "ID",
   schema: { defaultName: "Tasks", properties: { Name: Schema.title(), ID: Schema.richText() } },
   execute: async () => ({
-    objects: [{ key: "1", properties: { Name: Builder.title("Write docs"), ID: Builder.richText("1") } }],
-    done: true,
+    changes: [{ type: "upsert", key: "1", properties: { Name: Builder.title("Write docs"), ID: Builder.richText("1") } }],
+    hasMore: false,
   }),
 });
 
@@ -44,6 +44,93 @@ 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 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`.
+
+**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 only changes since the last run. Deletions must be explicit via `{ type: "delete", key: "..." }`. Records not mentioned are left unchanged.
+
+**When to use each:**
+- `replace`: small datasets or cheap full scans. Each cycle returns the full dataset for simplicity.
+- `incremental`: large datasets (e.g., Stripe, Salesforce, Zendesk) where full scans are expensive. First backfill, then return only incremental changes.
+
+Implement pagination to avoid exceeding output size limits. Returning too many changes in one execution can cause the output JSON to exceed size limits and fail.
+
+**How pagination works:**
+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 `hasMore: false`
+
+```ts
+worker.sync("paginatedSync", {
+  primaryKeyProperty: "ID",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { page: number }) => {
+    const page = context?.page ?? 1;
+    const pageSize = 100;
+    const { items, hasMore } = await fetchPage(page, pageSize);
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore,
+      nextContext: hasMore ? { page: page + 1 } : undefined,
+    };
+  },
+});
+```
+
+**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.
+
+**Replace example (full dataset each cycle, each execute call paginated):**
+```ts
+worker.sync("fullSync", {
+  primaryKeyProperty: "ID",
+  mode: "replace",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { cursor?: string }) => {
+    const { items, nextCursor } = await fetchPage(context?.cursor);
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore: Boolean(nextCursor),
+      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+    };
+  },
+});
+```
+
+**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,
+    };
+  },
+});
+```
+
 ## 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

@@ -73,8 +73,9 @@ worker.sync("tasksSync", {
     },
   },
   execute: async () => ({
-    objects: [
+    changes: [
       {
+        type: "upsert",
         key: "1",
         properties: {
           Name: Builder.title("Write docs"),
@@ -82,11 +83,70 @@ worker.sync("tasksSync", {
         },
       },
     ],
-    done: true,
+    hasMore: false,
   }),
 });
 ```
 
+#### Sync strategy and pagination
+
+A sync runs in a "sync cycle": a back-to-back chain of `execute` calls that ends when an execution returns `hasMore: false`.
+
+Choose a strategy with `mode`:
+- `replace` (default): each cycle returns the full dataset. After the final `hasMore: false`, any records not seen in that cycle are deleted.
+- `incremental`: each cycle returns only changes since the last run. Deletions must be explicit via `{ type: "delete", key: "..." }`. Records not mentioned are left unchanged.
+
+**When to use each:**
+- `replace`: small datasets or cheap full scans. Each cycle returns the full dataset for simplicity.
+- `incremental`: large datasets (Stripe, Salesforce, Zendesk) where full scans are expensive. First backfill, then return only changes.
+
+Paginate large datasets by returning `hasMore: true` with a `nextContext` cursor, and continue until `hasMore: false`.
+
+**Replace example (full dataset each cycle, each execute call paginated):**
+```ts
+worker.sync("fullSync", {
+  primaryKeyProperty: "ID",
+  mode: "replace",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { cursor?: string }) => {
+    const { items, nextCursor } = await fetchPage(context?.cursor);
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore: Boolean(nextCursor),
+      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+    };
+  },
+});
+```
+
+**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,
+    };
+  },
+});
+```
+
 ### Tool
 
 Tools are callable by Notion custom agents.

package/template/src/index.ts

@@ -35,9 +35,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 returns the complete dataset. After hasMore:false,
+	//              pages not seen in this sync run are deleted.
+	// - "incremental": Sync returns changes only. Use delete markers
+	//                  (e.g., { type: "delete", key: "task-1" }) to remove pages.
+	// Defaults to "replace".
+	// mode: "replace",
 
 	schema: {
 		defaultName: "Sample Tasks",
@@ -68,7 +72,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: {
@@ -81,8 +86,8 @@ worker.sync("tasksSync", {
 		}));
 
 		return {
-			objects,
-			done: true,
+			changes,
+			hasMore: false,
 		};
 	},
 });