@project-ajax/create 0.0.26 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/create",
-	"version": "0.0.26",
+	"version": "0.0.27",
 	"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",
@@ -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/AGENTS.md

@@ -20,10 +20,18 @@ export default worker;
 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,
-  }),
+  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,
+    };
+  },
 });
 
 worker.tool("sayHello", {
@@ -44,6 +52,37 @@ 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
+
+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.
+
+**How pagination works:**
+1. Return a batch of objects with `done: false` and a `nextContext` value
+2. The runtime calls `execute` again with that context
+3. Continue until you return `done: true`
+
+```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 {
+      objects: items.map((item) => ({
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      done: !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.
+
 ## 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.