---

✨ What it does

🔢 Inline cell	`spread_sync("id", "Sheet1", "B3")` → renders as the live value
📋 Range table	```spread-sync ``` block → Markdown table, headers/transpose/named ranges supported
✏️ Edit in place	Add editable: true → cells become editable, one button batchUpdates all changes
✍️ Explicit write	```spread-write ``` block + Push this block command
🛡️ Conflict-aware	Drive modifiedTime check before every push, Overwrite/Cancel prompt on mismatch
🔐 PKCE OAuth	Bring your own Google Cloud Desktop client. Refresh token encrypted via safeStorage
⚡ Smart caching	LRU + debounced persist, stale-while-revalidate, manual refresh commands
🌐 Resilient	429 backoff, offline-aware, dedicated error badges (no access, Excel format, etc.)

🚀 Install

cd /path/to/your/vault/.obsidian/plugins
git clone https://github.com/yut0takagi/obsidian-spread-sync.git spread-sync
cd spread-sync && npm install && npm run build

Then in Obsidian: Settings → Community plugins → enable Spread Sync.

⚙️ Setup (5 min)

Spread Sync uses your own Google Cloud OAuth credentials. You stay in control of scopes and quota.

Step 1 — Create a Google Cloud project

Open Google Cloud Console → create or select a project.

Step 2 — Enable APIs

APIs & Services → Library → enable:

• Google Sheets API
• Google Drive API

Step 3 — Configure OAuth consent screen

• User type: External
• Add scopes: .../auth/spreadsheets + .../auth/drive.metadata.readonly
• Publishing status: In production (avoids the 7-day refresh-token expiry of "Testing" mode)

Step 4 — Create OAuth client

Credentials → Create credentials → OAuth client ID → Application type: Desktop app. Copy both Client ID and Client secret.

Note: Google's docs explicitly say Desktop OAuth client secrets are not actually confidential (source). Storing it in your local Obsidian settings is consistent with how the official Google libraries handle it.

Step 5 — Paste into Obsidian

Settings → Spread Sync → OAuth credentials section. Paste both values. Click Sign in with Google. Done.

💡 Usage

Inline cell

The current store count is `spread_sync("<spreadsheet-id>", "Sheet1", "B3")`.

Range as a table

```spread-sync
id: <spreadsheet-id>
sheet: Sheet1
range: A1:D10
header: true        # optional, default true
transpose: false    # optional, default false
```

Editable table ✨

```spread-sync
id: <spreadsheet-id>
sheet: Sheet1
range: A1:D10
editable: true
```

Click any cell to edit.

Dirty cells highlight yellow.

Push button at the bottom batches all dirty cells into one values:batchUpdate.

Whole sheet

```spread-sync
id: <spreadsheet-id>
sheet: Sheet1
```

Named range

```spread-sync
id: <spreadsheet-id>
sheet: Sheet1
named: MonthlyKPI
```

Aliases

Set kpi → <long-spreadsheet-id> in settings, then reference as "@kpi":

```spread-sync
id: "@kpi"
sheet: Sheet1
range: A1:C5
```

Explicit write (one-shot)

```spread-write
id: <spreadsheet-id>
sheet: Sheet1
target: B3
value: 42
mode: replace       # or "append"
```

Place cursor inside the block → Command Palette → Spread Sync: Push this block.

For range writes:

target: A1:B2
value:
  - [1, 2]
  - [3, 4]

🎛️ Commands

Command	Description
Spread Sync: Refresh current file	Invalidate cache for the active file, force re-fetch
Spread Sync: Refresh all open files	Same, for every open markdown leaf
Spread Sync: Refresh by spreadsheet	Prompt for an id / URL / @alias and invalidate all its cache
Spread Sync: Push this block	Send the current spread-write block to Sheets

🚨 Error badges

Badge	Meaning
⚠ re-auth	Token expired / not signed in — click to re-sign-in
⚠ no access	403 / 404 from Sheets — check sharing or API enablement
⚠ Excel format	Sheet is a .xlsx uploaded to Drive — convert to native Google Sheets
⚠ syntax error	Block YAML / inline call is malformed (tooltip shows the parser error)
⚠ range error	Inline syntax got a multi-cell range, or editable got an invalid range
⚠ fetch failed	Generic API error — hover for full message
⚠ stale Nm	Last fetch failed; showing cached value N minutes old
⚠ offline	Network is down

🏗️ Architecture

Four isolated layers:

┌──────────────────────────────────────────────┐
│  Renderer   inline / block postprocessors    │
│             editable table widget            │
├──────────────────────────────────────────────┤
│  Auth       OAuth (PKCE) · safeStorage       │
│             localhost loopback callback      │
├──────────────────────────────────────────────┤
│  Sheets+Drive   pure HTTP (https.request)    │
│                read · batchRead · write      │
│                batchWrite · modifiedTime     │
│                429 backoff                   │
├──────────────────────────────────────────────┤
│  Storage    LRU cache · debounced persist    │
└──────────────────────────────────────────────┘

📋 Requirements

• Obsidian 1.4+
• Desktop only (Electron safeStorage not available on mobile)
• Node 18+ for build

🚧 Limitations

• editable: true only works with literal range: like A1:B2 (not named: or whole sheet, not transpose: true).
• No batchGet wiring yet — each inline expression is a separate API request (Phase 2).
• Push this block uses editor.setValue which resets cursor/undo history (Phase 2: replace with replaceRange).

🧪 Development

npm install
npm run dev     # esbuild watch mode
npm test        # vitest run — 59 tests across 8 files

Tests cover: parser, id resolver, cache, Sheets client (with nock), Drive client, OAuth client (PKCE + token exchange), TokenStore, table formatter. Renderer / commands / settings UI are verified manually in a real Obsidian vault.

📄 License

MIT — built by @yut0takagi.