create-ncblock 0.0.39 → 0.0.41

package/templates/worker/.agents/skills/auth-guide/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: auth-guide
+description: Guide to setting up third-party authentication for a Notion Worker. Covers external-service API keys / personal access tokens and OAuth. Use when the worker needs credentials for a non-Notion API, not for Notion API tokens or `ntn login`.
+user-invocable: false
+---
+
+## What this guide is for
+
+This guide is for authentication against the **third-party service** your worker integrates with — the place data is coming from or going to (GitHub, Stripe, Salesforce, Google, Slack, etc.).
+
+Use it when the worker needs credentials for a non-Notion API. Do not use it for Notion API tokens, `ntn login`, or general Notion workspace setup.
+
+Most workers will use one of two auth patterns from the upstream service:
+
+- personal API key / personal access token
+- OAuth
+
+## Decision framework
+
+Before recommending anything, check the provider's current developer docs. Confirm whether it offers:
+
+- personal API keys / personal access tokens
+- OAuth
+- neither
+
+Always research the provider's current auth docs on the web before advising the user. Do not rely on memory for auth availability, setup steps, or settings locations.
+
+Then choose mechanically:
+
+1. **Service offers personal API keys / PATs?** Recommend API key / PAT first. It is usually the simplest fit for an individual-scoped worker.
+2. **Service is OAuth-only?** Use OAuth.
+3. **Both exist, but the worker should not depend on one person's credential or should be easy to re-auth if that person leaves?** Recommend OAuth.
+4. **Service has neither?** See "When neither option is available" at the end of this guide.
+
+State the recommendation in one sentence with the reason. Example: "Linear offers personal API keys, so use an API key; it's the simplest fit here."
+
+## Setup: API key
+
+Pattern: store the credential in `.env` (or directly in the deployed worker's secrets), read it from `process.env` inside the capability's `execute`, push `.env` to the deployed worker before going live.
+
+1. Look up the provider's current docs for creating a token. Link the user to the exact settings page when possible.
+
+2. **Have the user add the token to `.env` themselves** (create the file if it doesn't exist), or tell them the equivalent `ntn workers env set` command. Tell them the variable name to use:
+
+   ```
+   GITHUB_API_TOKEN=<paste your token here>
+   ```
+
+   `.env` is automatically loaded for local execution (`--local`).
+
+3. Read the token inside `execute` (this is the part you write):
+
+   ```ts
+   const token = process.env.GITHUB_API_TOKEN ?? "";
+
+   const res = await fetch("https://api.github.com/user", {
+     headers: { Authorization: `Bearer ${token}` },
+   });
+   ```
+
+4. If auth seems broken, test the token outside the worker first against a simple authenticated endpoint from the provider docs. Example for GitHub:
+
+   ```shell
+   curl -H "Authorization: Bearer $GITHUB_API_TOKEN" https://api.github.com/user
+   ```
+
+5. Test locally with `ntn workers exec <capability> --local`. Confirm auth works before deploying.
+
+6. **Push the secret to the deployed worker.** Once the token is already in `.env`, run:
+
+   ```shell
+   ntn workers env push
+   ```
+
+   If the user prefers not to keep the token in `.env`, they can use the direct-set form instead:
+
+   ```shell
+   ntn workers env set GITHUB_API_TOKEN=<paste token>
+   ```
+
+7. Tell the user how to rotate: revoke the old token at the service, generate a new one, update `.env` (or `ntn workers env set` directly), and re-push if needed.
+
+## Setup: OAuth
+
+`worker.oauth()` declares an OAuth capability. The runtime handles the authorization redirect, token exchange, and refresh — you call `accessToken()` inside `execute` to get a fresh token.
+
+The user has to register an OAuth app with the provider, then plug the credentials in:
+
+```ts
+const myAuth = worker.oauth("myAuth", {
+  name: "my-provider",
+  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
+  tokenEndpoint: "https://provider.example.com/oauth/token",
+  scope: "read write",
+  clientId: process.env.MY_OAUTH_CLIENT_ID ?? "",
+  clientSecret: process.env.MY_OAUTH_CLIENT_SECRET ?? "",
+  // Optional: extra params the provider needs on the auth URL
+  authorizationParams: { ... },
+});
+```
+
+Setup steps:
+
+1. **Check the provider's current OAuth docs.** Confirm the authorization endpoint, token endpoint, scopes, any extra authorization params, and how the provider wants redirect URLs configured.
+
+2. **Register an OAuth app with the provider.** If the provider asks for a redirect URL up front and you do not have it yet, create the app shell first and come back to fill in the redirect URL after the first deploy.
+
+3. **Have the user add credentials to `.env` themselves**, or tell them the equivalent `ntn workers env set` commands. Tell them which variable names to use:
+
+   ```
+   MY_OAUTH_CLIENT_ID=<paste client id>
+   MY_OAUTH_CLIENT_SECRET=<paste client secret>
+   ```
+
+4. **Add the `worker.oauth()` declaration** to `src/index.ts`. Read `clientId`/`clientSecret` from `process.env`.
+
+5. **Create the worker (if not already created), push secrets, and deploy.** The deployed worker reads `clientSecret` from environment variables during capability registration, so the secret must be present remotely before `deploy`. Have the user run these themselves:
+
+   ```shell
+   ntn workers create --name <name>    # if not already created
+   ntn workers env push                  # push .env to remote
+   # or, to set values directly without putting them in .env:
+   # ntn workers env set MY_OAUTH_CLIENT_SECRET=<paste secret>
+   ntn workers deploy
+   ```
+
+   **Important:** any time the client ID or client secret changes, you must redeploy (`ntn workers deploy`) — the OAuth capability binds these values at registration time, so updating env vars alone won't take effect.
+
+6. **Get the redirect URL and have the user add it to the provider's app settings.** The redirect URL comes from the deployed worker. Get it with:
+
+   ```shell
+   ntn workers oauth show-redirect-url
+   ```
+
+   The user must paste this exact value into their OAuth app's "redirect URI" (or "authorized redirect URL", or "callback URL") setting before starting the OAuth flow. **Always remind the user of this step — OAuth will fail with a redirect mismatch error if it's missing or wrong.**
+
+7. **Start the OAuth flow:**
+
+   ```shell
+   ntn workers oauth start <oauthCapabilityKey>
+   ```
+
+   This opens the user's browser, walks them through the provider's consent screen, and stores the resulting tokens.
+
+8. **Use the token inside `execute`:**
+
+   ```ts
+   const token = await myAuth.accessToken();
+   const res = await fetch("https://provider.example.com/v1/things", {
+     headers: { Authorization: `Bearer ${token}` },
+   });
+   ```
+
+   `accessToken()` returns a valid, refreshed access token. The runtime handles refresh automatically — you don't need to track expiry yourself.
+
+### Local testing with OAuth
+
+OAuth capabilities can be tested locally, but only after a one-time bootstrap — the access token has to exist somewhere before `accessToken()` can read it. The flow:
+
+1. Deploy the worker, configure the redirect URL, and complete the OAuth flow once (steps 5–7 above).
+2. Pull the deployed worker's env vars (which now include the OAuth access token) into local `.env`:
+
+   ```shell
+   ntn workers env pull
+   ```
+
+3. Now `ntn workers exec <key> --local` works — `accessToken()` reads the token from local `.env`.
+
+Caveats:
+
+- Access tokens expire. The deployed runtime auto-refreshes; your local `.env` does not. When the local token goes stale, run `ntn workers env pull` again (or, if the refresh token has also expired, redo `ntn workers oauth start <key>` then `env pull`).
+- Until that first deploy + OAuth completes, you can't `--local`. Run `npm run check` for type validation, or mock `accessToken()` in a test file if you need to exercise the rest of the logic.
+
+## Common pitfalls
+
+1. **Hardcoded credentials in source.** Tokens and secrets must come from `process.env` — never inline them in `src/index.ts`. Even in personal repos, committed secrets get scraped.
+
+2. **Forgetting `ntn workers env push`.** Local works, deploy fails with auth errors. Always push secrets after changing `.env`. The deployed worker doesn't see local `.env`.
+
+3. **Debugging worker code before testing the raw token.** If API key auth is failing, hit a simple authenticated endpoint with `curl` first so you can separate bad credentials from worker bugs.
+
+4. **Pushing secrets after `ntn workers deploy` for OAuth.** OAuth `clientId` is read from `process.env` during capability registration — push secrets *before* `deploy`, or use the `create` → `env push` → `deploy` sequence.
+
+5. **Wrong redirect URL for OAuth.** `redirect_uri_mismatch` is the #1 OAuth failure mode. Always run `ntn workers oauth show-redirect-url` and verify the user has set the exact URL at the provider.
+
+6. **Asking for too many OAuth scopes.** Request the narrowest set that works. Scope creep makes the consent screen scary and slows OAuth review for production apps.
+
+7. **Not telling the user about manual rotation.** API keys don't refresh themselves. Tell the user up front that they'll need to rotate, and how.
+
+## CLI reference
+
+```shell
+# Push .env secrets to the deployed worker (run after any .env change)
+ntn workers env push
+
+# Pull remote env vars into local .env (useful for OAuth: brings access tokens
+# down so `ntn workers exec --local` can read them)
+ntn workers env pull
+
+# List remote env vars (without values)
+ntn workers env list
+
+# Set a single env var
+ntn workers env set KEY=value
+
+# OAuth: get the redirect URL to configure at the provider
+ntn workers oauth show-redirect-url
+
+# OAuth: start the authorization flow (opens browser)
+ntn workers oauth start <oauthCapabilityKey>
+
+# OAuth: inspect token state
+ntn workers oauth token <oauthCapabilityKey>
+```
+
+## When neither option is available
+
+If the service offers neither an API key nor an OAuth flow, the honest first answer is often that the integration isn't viable on that service.
+
+Before giving up, there are a few **indirect paths** worth considering.
+
+- **OAuth into a related service that already has the data.** Sometimes the data flows downstream into a place you *can* reach with proper auth — a calendar provider, file storage, a shared workspace. Following the data to a sanctioned interface is preferable to forcing a connection at the original source.
+- **Have the user export and upload.** If the service offers a manual data export (CSV/JSON), the user can drop files somewhere the worker can read (S3, Drive, etc.) and the worker syncs from there. Higher-friction but unambiguously sanctioned.
+- **Pull data out of the user's own email.** If the service sends the user emails containing the data (digests, notifications, exports, receipts), OAuth into the user's own email account (Gmail, etc.) and parse those messages. The user owns the inbox, the service is sending them the data on purpose, and the email provider has a real OAuth API. Indirect but stable.
+- **Use the service's own internal/frontend endpoints** (the JSON routes its web app calls). Sometimes the only thing the service exposes is the API its own UI talks to — you can authenticate as the logged-in user (session cookie, captured bearer token) and call those routes from the worker. Honest caveats: it's often flaky (the routes can change with any frontend release), it relies on credentials that probably weren't intended for programmatic use, and **the user needs to confirm this doesn't violate the service's terms of service** before doing it. Reasonable for a personal tool or hobby integration; not something to lean on for serious production use. Don't recommend it as a first choice — but if the user goes this way knowingly, help them do it carefully (sane pacers, descriptive `User-Agent`, manual credential rotation, no rate-limit evasion).
+
+   **Tip for discovery:** ask the user to export a `.har` file from their browser's devtools (Network tab → right-click → "Save all as HAR with content"). HAR files capture every request/response the page made — URLs, methods, headers, bodies — which lets you see the exact endpoint shape without the user having to describe it.

package/templates/worker/.agents/skills/sync/SKILL.md

@@ -0,0 +1,368 @@
+---
+name: sync
+description: Scaffold a new sync capability with guided setup — asks about data source, mode, pagination, and cursor design, then generates working code
+user-invocable: true
+disable-model-invocation: true
+allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep", "Agent"]
+---
+
+## Instructions
+
+You are helping the user create a new sync capability for their Notion Worker. Walk through each step, asking questions and making recommendations. Generate working code at the end.
+
+Before you begin, read these reference files to understand sync patterns:
+- `.agents/skills/sync-guide/SKILL.md` — concepts, modes, patterns, common mistakes
+- `.agents/skills/sync-guide/api-pagination-patterns.md` — real-world API strategies
+- `.agents/skills/sync-guide/examples/` — working code templates
+
+Also read the current `src/index.ts` to understand what already exists.
+
+### Step 1: Understand the Data Source
+
+Ask the user:
+- What data are you syncing? (e.g., "Jira issues", "Stripe customers", "ServiceNow tickets")
+
+If they name a well-known API, look up its pagination mechanism and change-tracking capabilities (does it have `updated_at`? an events endpoint? cursor-based pagination?).
+
+### Step 2: Determine the Right Architecture
+
+Based on what you know about the data source, recommend one of two architectures:
+
+#### Simple replace sync
+
+Use when: the source is small (<1k records) OR the API has no change tracking
+(no `updated_at`, no event feed).
+
+One sync, replace mode. Re-fetches everything each cycle. The runtime
+auto-deletes records that disappear from the source. Simplest option.
+
+#### Backfill + delta pair
+
+Use when: the API supports change tracking (`updated_at`, events, changelog) —
+this covers most enterprise APIs (Salesforce, Stripe, Linear, GitHub, HubSpot).
+
+Two separate syncs writing to the **same database**:
+
+- **Backfill sync** (replace mode, `schedule: "manual"`): Paginates the full
+  dataset. Triggered manually via CLI when a full re-import is needed. Replace
+  mode's mark-and-sweep automatically cleans up records deleted from the source.
+- **Delta sync** (incremental mode, `schedule: "5m"` or similar): Fetches only
+  recently changed records. Runs on a timer for low-latency updates.
+
+Advantages over a single bi-modal sync:
+- No phase discrimination in state — each sync has simple, focused state
+- No backfill-to-delta transition logic
+- Backfill and delta run independently — re-backfill anytime without disrupting delta
+- Easier to reason about and debug
+
+**Change tracking drives the decision, not dataset size.** A Linear workspace
+may only have a few thousand issues, but its API supports the queries needed
+for delta sync, so backfill+delta is the right choice. Conversely, a website
+listing local pickleball courts has no `updated_since` endpoint regardless of
+how many records it has.
+
+Recommend an architecture with a brief explanation. Let the user override if
+they disagree.
+
+### Step 3: Design the Schema
+
+Based on the API's response shape, propose a schema. Look up what fields the
+API returns and map the most useful ones to Schema types. Don't ask the user
+to enumerate fields — propose a sensible default and let them adjust.
+
+For example, if syncing Jira issues, propose:
+```ts
+const issuesDb = worker.database("issuesDb", {
+  type: "managed",
+  initialTitle: "Jira Issues",
+  primaryKeyProperty: "Issue Key",
+  schema: {
+    properties: {
+      "Issue Key": Schema.richText(),    // primaryKeyProperty — the unique ID
+      "Summary": Schema.title(),         // the main display field
+      "Status": Schema.select([...]),    // mapped from Jira statuses
+      "Assignee": Schema.richText(),     // or Schema.people() if email available
+      "Updated": Schema.date(),
+    },
+  },
+});
+```
+
+Guidelines:
+- Declare the database with `worker.database()` and reference the handle in `worker.sync()`
+- Every schema needs exactly one `Schema.title()` — pick the most descriptive field
+- Use `Schema.richText()` for the primary key property (the unique ID)
+- Use `Schema.url()`, `Schema.email()`, `Schema.date()`, `Schema.number()`,
+  `Schema.checkbox()`, `Schema.select()` where the data type fits
+- Use `Schema.relation("otherDatabaseKey")` for relations to another managed database
+- Start with 10-20 properties — be generous, include most useful fields from the API
+- See the full type list in `.agents/skills/sync-guide/SKILL.md` under "Schema Reference"
+
+Present the proposed schema to the user and ask if they want to add, remove,
+or change any fields before generating code.
+
+### Step 4: Design the State Machine
+
+Research the API to determine its pagination and change-tracking mechanisms.
+Do NOT ask the user about pagination details — figure it out from the API docs,
+your knowledge of the API, or by looking up the API. The user shouldn't need
+to know whether their API uses opaque cursors vs page numbers.
+
+You need to determine:
+1. **How the API paginates list results** (opaque cursor, page number, offset, keyset)
+2. **Whether the API has change tracking** (updated_at field, events endpoint, changelog)
+3. **Whether the API has deletion signals** (archived filter, audit log, delete events)
+
+Then design the state accordingly:
+
+**For simple replace syncs:** State is just within-cycle pagination.
+- Opaque cursor: `{ cursor: string | null }`
+- Page number: `{ page: number }`
+
+**For backfill + delta pairs:** Each sync has its own simple state — no
+bi-modal discriminated union needed.
+
+- **Backfill state:** Just pagination cursor for walking the full dataset.
+  Depends on how the API paginates its list endpoint:
+  - Opaque cursor: `{ cursor: string | null }`
+  - Page number: `{ page: number }`
+  - Keyset: `{ cursorTimestamp: string | null; cursorId: string | null }`
+
+- **Delta state:** Change-tracking cursor for fetching recent modifications.
+  Depends on how the API exposes changes:
+  - Opaque cursor (API sorted by updated_at): `{ cursor: string | null }`
+  - Timestamp keyset: `{ cursorTimestamp: string; cursorId: string }`
+  - Event ID: `{ eventCursor: string }`
+
+**Consistency buffer (delta syncs only):** In incremental mode the cursor
+never resets, so if you advance past a record that hasn't been indexed yet,
+it's lost permanently. Apply a consistency buffer: never advance the cursor
+closer than 10-15 seconds to "now". This is especially important for APIs
+with eventual consistency (Stripe, Salesforce, etc.).
+
+**Deletion handling:**
+There are three cases to consider:
+
+1. **API supports delta deletes** (e.g., Stripe events with `*.deleted` types,
+   APIs that return `deleted: true` in change feeds): Emit
+   `{ type: "delete", key }` in the delta sync. This is the cleanest approach.
+2. **Deletes are rare or irrelevant** for the use case: No action needed.
+   Stale records remain in Notion but don't cause problems.
+3. **Deletes matter but the API has no delete signal**: The backfill sync's
+   replace mode handles this automatically — its mark-and-sweep deletes any
+   records not seen during the full cycle. Trigger a backfill periodically
+   to clean up stale records.
+
+If the API has no change tracking at all, go back and recommend a simple
+replace sync instead.
+
+Present your state design to the user as a brief summary (e.g., "This API uses
+cursor-based pagination and has an `updated_at` field, so I'll use a
+backfill+delta pair with opaque cursor for backfill and timestamp keyset for
+delta"). Let them confirm or adjust before generating code.
+
+### Step 5: Set Up Authentication
+
+Before generating code, determine what auth the API needs and set it up so
+you can test locally.
+
+There are two patterns:
+
+**Pattern A: Static API token/key**
+For APIs where the user has a personal token or API key (e.g., Jira API token,
+GitHub PAT, simple API keys).
+
+Ask the user for their token and add it to `.env`:
+```
+JIRA_API_TOKEN=...
+JIRA_EMAIL=user@example.com
+```
+If `.env` doesn't exist, create it. The `.env` file is automatically loaded
+during local execution (`--local` flag).
+
+**Pattern B: OAuth**
+For APIs that require OAuth (e.g., Google, Salesforce, HubSpot). This has
+two parts:
+
+1. **Client credentials** — the OAuth app's client ID and secret. These go in `.env`:
+   ```
+   MY_OAUTH_CLIENT_ID=...
+   MY_OAUTH_CLIENT_SECRET=...
+   ```
+
+2. **User token** — obtained through the OAuth flow *after* deploying. This is
+   handled by the runtime automatically via `worker.oauth()` and `.accessToken()`.
+
+For OAuth syncs, you'll add a `worker.oauth()` call in the generated code.
+Always use `UserManagedOAuthConfiguration` (the shape with explicit endpoints and
+client credentials) rather than the `{ provider: "..." }` shorthand, as
+Notion-managed OAuth is in alpha and the user likely does not have access.
+
+```ts
+const myAuth = worker.oauth("myAuth", {
+  name: "my-provider",
+  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
+  tokenEndpoint: "https://provider.example.com/oauth/token",
+  scope: "read write",
+  clientId: process.env.MY_OAUTH_CLIENT_ID ?? "",
+  clientSecret: process.env.MY_OAUTH_CLIENT_SECRET ?? "",
+});
+```
+
+Then use `await myAuth.accessToken()` in the execute function instead of
+reading a static token from `process.env`.
+
+Note: OAuth syncs can't be fully tested locally since the OAuth flow requires
+a deployed worker. Local testing will fail at the `.accessToken()` call. This
+is fine — proceed to deploy and test via preview (Step 8).
+
+### Step 6: Generate the Code
+
+Write the sync into `src/index.ts`. Use the closest example from `.agents/skills/sync-guide/examples/` as a starting point:
+- `replace-simple.ts` — static data, no API
+- `replace-paginated.ts` — paginated replace mode (also used for backfill syncs)
+- `incremental-basic.ts` — delta sync with opaque cursor
+- `incremental-bimodal.ts` — full backfill + delta pair example
+- `incremental-events.ts` — delta sync with event feed
+
+Include in the generated code:
+- Proper imports (`Worker`, `Builder`, `Schema`)
+- Database declaration via `worker.database()` with schema and `primaryKeyProperty`
+- A pacer for the upstream API via `worker.pacer()` — and `await pacer.wait()` before every API request
+- The state type(s) — simple types, one per sync (no discriminated unions needed)
+- The `worker.sync()` call(s) referencing the database handle
+- For backfill+delta: two syncs targeting the same database, backfill with `schedule: "manual"`, delta with a timed schedule
+- A consistency buffer for delta syncs (if the API is eventually consistent)
+- Inline comments explaining *why* each design choice was made
+- API calls using `fetch` with auth from `process.env`
+
+**Code generation checklist:**
+- [ ] Database declared with `worker.database()` and referenced by handle
+- [ ] Pacer declared with `worker.pacer()` for the upstream API
+- [ ] `await pacer.wait()` called before every `fetch` to the upstream API
+- [ ] State types are simple (no bi-modal discriminated unions)
+- [ ] Backfill sync uses `mode: "replace"` and `schedule: "manual"` (if applicable)
+- [ ] Delta sync uses `mode: "incremental"` with a timed schedule (if applicable)
+- [ ] Consistency buffer applied to delta cursor advancement (if applicable)
+- [ ] Deletion handling matches one of the three cases from Step 4
+
+### Step 7: Test Locally
+
+Test the sync before deploying. This catches bugs early without a deploy cycle.
+
+**For syncs using static API tokens (Pattern A):**
+
+1. Run `npm run check` to verify TypeScript types compile. Fix any errors.
+
+2. Run `ntn workers exec <key> --local` to execute the sync locally.
+   This runs the execute function on your machine with `.env` loaded.
+   - Check: does it return data? Are properties populated correctly?
+   - Check: does `hasMore` look right? Does the cursor advance?
+
+3. If it returns `hasMore: true`, test the next page:
+   `ntn workers exec <key> --local -d '<nextState from previous output>'`
+
+4. If there are errors (auth failures, wrong field mappings, crashes):
+   fix the code and re-run — no deploy needed, iteration is fast.
+
+5. For backfill+delta pairs, test each sync independently:
+   - Test the backfill sync: `ntn workers exec <backfillKey> --local`
+   - Test the delta sync: `ntn workers exec <deltaKey> --local`
+   - Verify they both return well-formed data with the correct properties.
+
+6. Write a test file (`test.ts`) that exercises the sync. Import the worker
+   directly and call its `.run()` method.
+
+   If the user has API credentials in `.env`, write a test that hits the real
+   API — this is the most valuable test because it validates actual field
+   mappings, pagination behavior, and auth against the real service. If
+   credentials aren't available, stub the HTTP calls instead.
+
+   **Integration test (preferred when credentials are available):**
+   ```ts
+   import "dotenv/config"; // load .env
+   import worker from "./src/index.ts";
+   import assert from "node:assert";
+
+   async function test() {
+     // First page (backfill start, no prior state)
+     const page1 = await worker.run("mySync", undefined, { concreteOutput: true });
+     console.log(`Page 1: ${page1.changes.length} records, hasMore: ${page1.hasMore}`);
+     assert(page1.changes.length > 0, "Should return records");
+
+     // Verify fields are populated
+     const first = page1.changes[0];
+     assert(first.key, "Record should have a key");
+     console.log("Sample record:", JSON.stringify(first, null, 2));
+
+     // Test pagination
+     if (page1.hasMore) {
+       const page2 = await worker.run("mySync", page1.nextState, { concreteOutput: true });
+       console.log(`Page 2: ${page2.changes.length} records, hasMore: ${page2.hasMore}`);
+       assert(page2.changes.length > 0, "Second page should return records");
+     }
+
+     console.log("All tests passed!");
+   }
+
+   test().catch((err) => { console.error(err); process.exit(1); });
+   ```
+
+   Run with `npx tsx test.ts`. Adapt to the specific sync: use the actual
+   capability key, add assertions for specific field values, verify both
+   backfill and delta syncs for backfill+delta pairs, etc.
+
+**For syncs using OAuth (Pattern B):**
+Local execution won't work because `.accessToken()` requires a deployed worker
+with a completed OAuth flow. Skip to Step 8 (deploy + preview) instead.
+You can still run `npm run check` to verify types compile.
+
+### Step 8: Deploy and Validate with Preview
+
+Once local testing passes (or immediately for OAuth syncs), deploy and test remotely.
+
+If secrets need to be available at deploy time (e.g., OAuth `clientSecret` read
+from `process.env` during capability registration), create the worker and push
+secrets first:
+1. `ntn workers create --name <name>` — create the worker without deploying
+2. `ntn workers env push` — push `.env` secrets to remote
+3. `ntn workers deploy` — now deploy with secrets available
+
+Otherwise, the simpler flow:
+1. `ntn workers deploy` — build and publish
+2. `ntn workers env push` — push `.env` secrets to remote
+
+Then, if the sync uses OAuth, complete the OAuth flow before previewing.
+**Important:** `env push` must happen before `oauth start` — the deployed worker needs the client secret to exchange the authorization code for tokens.
+   - `ntn workers oauth show-redirect-url` — get the redirect URL
+   - Tell the user to configure this URL in their OAuth provider's app settings
+   - `ntn workers oauth start <oauthKey>` — opens browser to complete the OAuth flow
+4. `ntn workers sync trigger <syncKey> --preview` — execute remotely without writing to Notion
+   - Inspect the output: record count, property values, hasMore status
+   - If `hasMore: true`, continue: `ntn workers sync trigger <syncKey> --preview --context '<nextState>'`
+5. If the preview shows issues, fix the code and redeploy (go back to step 1)
+
+For backfill+delta pairs, preview both syncs:
+- `ntn workers sync trigger <backfillKey> --preview`
+- `ntn workers sync trigger <deltaKey> --preview`
+
+### Step 9: Go Live
+
+When the preview looks good:
+
+1. `ntn workers sync trigger <key>` — trigger a real sync
+2. `ntn workers sync status` — check that the sync is running and progressing
+3. `ntn workers runs list` then `ntn workers runs logs <runId>` — check for errors
+4. Run `ntn workers sync status` again to confirm progress (record count increasing, no errors)
+
+For backfill+delta pairs, trigger the backfill first to load all data, then
+let the delta sync's schedule handle ongoing changes:
+1. `ntn workers sync trigger <backfillKey>` — start the full dataset load
+2. Monitor with `ntn workers sync status` until the backfill completes
+3. The delta sync will run automatically on its configured schedule
+
+Tell the user: the first sync run is the backfill, which may take a while
+depending on dataset size. They should periodically run `ntn workers sync status`
+to monitor progress until the initial backfill completes. After that, the delta
+sync runs automatically on its configured schedule. To re-backfill later:
+`ntn workers sync state reset <backfillKey> && ntn workers sync trigger <backfillKey>`