@project-ajax/create 0.0.31 → 0.0.32

package/README.md

@@ -25,6 +25,4 @@ npm init @project-ajax -- --directory my-worker --project my-worker
 
 ### Scheduling
 
-Generated sync workers default to `continuous`, meaning the sync runs continuously/as fast as possible. To slow cadence, set `schedule` in `src/index.ts` to an interval like `30m`, `1h`, or `1d` (min `1m`, max `7d`), which runs the sync once per interval.
-
-This can be useful for minding rate limits.
+Sync workers default to running every 30 minutes. To change the cadence, set `schedule` in `src/index.ts` to an interval like `15m`, `1h`, or `1d` (min `1m`, max `7d`), or `continuous` to run as fast as possible.

package/package.json

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

package/template/AGENTS.md

@@ -49,12 +49,13 @@ worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
 ### 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`.
+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`. By default, syncs run every 30 minutes. Set `schedule` to an interval like `"15m"`, `"1h"`, `"1d"` (min `"1m"`, max `"7d"`), or `"continuous"` to run as fast as possible.
 
 - 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)
+- Use `Pacer.wait` to respect upstream rate limits during `execute` calls; pick a stable key per API or endpoint.
 
 **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.

package/template/CLAUDE.md

@@ -49,12 +49,13 @@ worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
 ### 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`.
+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`. By default, syncs run every 30 minutes. Set `schedule` to an interval like `"15m"`, `"1h"`, `"1d"` (min `"1m"`, max `"7d"`), or `"continuous"` to run as fast as possible.
 
 - 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)
+- Use `Pacer.wait` to respect upstream rate limits during `execute` calls; pick a stable key per API or endpoint.
 
 **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.

package/template/README.md

@@ -13,7 +13,7 @@ single `Worker` instance.
 ## Quickstart
 
 ```shell
-npm init @project-ajax
+npm init @project-ajax@latest
 # choose a folder, then:
 cd my-worker
 npm install
@@ -37,7 +37,7 @@ npx workers exec tasksSync
 
 - Worker: The Node/TypeScript program you deploy, defined in `src/index.ts`.
 - Capability: A named sync, tool, automation, or OAuth definition registered on a worker.
-- Secret: A key/value stored with `npx workers secrets`, exposed as environment variables (for example, `process.env.SECRET_NAME`).
+- Secret: A key/value stored with `npx workers secrets`, exposed as environment variables (for example, `process.env.SECRET_NAME`). Use `KEY=VALUE` pairs when setting secrets.
 
 ## Build a Worker
 
@@ -171,6 +171,33 @@ changes: [
 ]
 ```
 
+#### Respect rate limits
+
+
+If the source API has a rate limit, call `Pacer.wait` inside `execute` to pace requests (for example, 10 requests per minute):
+
+```ts
+import { Pacer } from "@project-ajax/sdk/pacer";
+
+worker.sync("tasksSync", {
+  primaryKeyProperty: "ID",
+  schema: { defaultName: "Tasks", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async () => {
+    const oneMinute = 60 * 1000;
+    await Pacer.wait("tasks-api", { requests: 10, intervalMs: oneMinute });
+    const items = await fetchTasks();
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore: false,
+    };
+  },
+});
+```
+
 ### Tool
 
 Tools are callable by Notion custom agents.
@@ -299,6 +326,12 @@ Store secrets for runtime access:
 npx workers secrets set API_KEY=my-secret
 ```
 
+You can pass multiple secrets and quote values that contain spaces or `=`:
+
+```shell
+npx workers secrets set FOO=bar BAZ="qux" ASDF="x=y" GREETING="hello world"
+```
+
 ### `npx workers secrets list`
 List secret keys: