sync

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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([
        { name: "To Do" },
        { name: "In Progress", color: "yellow" },
        { name: "Done", color: "green" },
      ]), // 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)
- Treat property order as product design, not API order. Put the title first,
  followed by the five properties that best help an end user recognize,
  evaluate, or act on the record.
- Keep opaque IDs, sync keys, timestamps used only for cursors, and other
  implementation metadata out of the first six properties. Include a user-facing
  identifier such as an order number or issue key early only when users genuinely
  rely on it.
- 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:

From makenotion/notion-cookbook, MIT.

More from makenotion/notion-cookbook