From 7c60cc7bf6390fb6210c2172f60078575c2f83d6 Mon Sep 17 00:00:00 2001
From: Christoph Dyllick-Brenzinger <cdb@datamate.org>
Date: Tue, 18 Aug 2026 13:12:53 +0200
Subject: [PATCH] Document the two JavaScript APIs for contributors

docs/javascript/ describes the scripting API and the external seatable-api
client on shared pages. The two are not identical, but nothing in this
repository said so, so an editor had no way to know which methods need a
context marker. That is how methods ended up documented for readers whose
context does not have them.

- README: what the two contexts are, both kinds of divergence (columns are
  read-only in scripts; three methods differ only in name), the marker
  convention, and how to verify a method in either context
- scripts/dump-script-api.js: prints the method surface of `base` from a
  base's script editor -- the scripting API has no published package, so
  this is the only way to enumerate it

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                  | 43 ++++++++++++++++++++++++++++++++++++++
 scripts/dump-script-api.js | 31 +++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 scripts/dump-script-api.js

diff --git a/README.md b/README.md
index 0e1d76a0..8779845a 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,49 @@ git push
 ./preview.sh -stop
 ```
 
+## Editing the JavaScript reference
+
+Read this before touching `docs/javascript/`. These pages document **two different APIs** that both call their object `base`, and they are not identical:
+
+- **Script in SeaTable** — runs in the browser, no authentication. `base` is provided by the script environment.
+- **External client** — `npm install seatable-api`, runs in Node.js or a frontend app, authenticates with an API token.
+
+Most methods exist in both, but not all. The differences are not obvious and have caused documented methods to be `undefined` for readers in the wrong context. Two kinds of divergence exist:
+
+**Capability** — columns can only be created or modified from the external client. `insertColumn`, `renameColumn`, `modifyColumnType`, `addColumnOptions`, `deleteColumn` and the other write methods do not exist in a script. Scripts have read-only access to columns.
+
+**Naming** — the same method has different names in the two contexts:
+
+| Script in SeaTable | External client |
+|---|---|
+| `getRows` | `listRows` |
+| `updateLinks` | `updateLink` |
+| `getColumns` | `listColumns` (works in both) |
+
+### The marker convention
+
+Every method that is limited to one context carries a marker in its `!!! abstract` heading:
+
+```markdown
+!!! abstract "getShownColumns :material-tag-outline:{ title='Scripting only' }"
+!!! abstract "insertColumn :material-package-variant-closed:{ title='External client only' }"
+```
+
+The markers are the authoritative per-method record. **When you add or move a method, determine its context first and mark it** — do not assume parity. A missing marker is read as "works in both".
+
+### How to check a method
+
+The external client is machine-readable:
+
+```bash
+npm pack seatable-api && tar xzf seatable-api-*.tgz
+grep -oE 'key: "[a-zA-Z0-9_]+"' package/lib/base.js | sed 's/key: //' | tr -d '"' | sort -u
+```
+
+The scripting API is not — it lives in the SeaTable frontend, not in a published package. Run [`scripts/dump-script-api.js`](scripts/dump-script-api.js) in any base's script editor to get its current method list.
+
+Note that `dtable-sdk` on npm is **not** a reliable stand-in for the scripting API. The script environment wraps it and adds methods; the SDK contains no link methods at all, for example.
+
 # Feedback and Support
 
 Feel free to raise issues or reach out with any questions, feedback, or suggestions. We're here to support your SeaTable development endeavors! We welcome contributions and feedback from the SeaTable developer community.
diff --git a/scripts/dump-script-api.js b/scripts/dump-script-api.js
new file mode 100644
index 00000000..ec72a181
--- /dev/null
+++ b/scripts/dump-script-api.js
@@ -0,0 +1,31 @@
+/*
+ * Dump the method surface of `base` inside a SeaTable base.
+ *
+ * The JavaScript reference in docs/javascript/ describes two different APIs
+ * (see "Editing the JavaScript reference" in README.md). The scripting half
+ * has no machine-readable source, so this script is how you find out what it
+ * actually offers.
+ *
+ * Usage:
+ *   1. Open any base -> Scripts -> new JavaScript script
+ *   2. Paste this file, run it, read the output panel
+ *
+ * To check a single method without running the whole dump:
+ *   output.text(typeof base.insertColumn);   // "undefined" -> external client only
+ */
+
+const methods = new Set();
+
+for (let obj = base; obj && obj !== Object.prototype; obj = Object.getPrototypeOf(obj)) {
+    for (const name of Object.getOwnPropertyNames(obj)) {
+        try {
+            if (typeof base[name] === 'function') methods.add(name);
+        } catch (err) {
+            // property is a getter that throws -- not a method, skip it
+        }
+    }
+}
+
+output.text([...methods].sort().join('\n'));
+output.text('--- base.utils: ' + Object.keys(base.utils || {}).sort().join(', '));
+output.text('--- base.context: ' + Object.keys(base.context || {}).sort().join(', '));