feat: add inkreach CLI + inkreach-teable-ops skill

A self-built CLI and companion agent skill for operating a deployed inkreach-teable instance — configuring tables, fields, records, views, and the project's OWN automation engine. Why not the official 'teable' CLI: inkreach-teable's automation is self-built with a different contract: - conditions (not filter), fieldIds (not watchFieldIds) - recordCondition (not recordMatchesConditions) - webhook route /api/webhook/{baseId}/{wfId} (not the /base//workflow/ form) - scheduledTime backend honors only timing.type + timing.interval The official CLI targets the upstream contract and 404s/misconfigures here. Table/field/record/view APIs ARE upstream-compatible, but automation is not. inkreach CLI (packages/inkreach-cli/): - Node.js + commander, zero extra runtime deps - Uses node:http (NOT fetch — Node 24 fetch drops Authorization header) - Commands: auth (login/status/token), base/table/field/record/view, workflow (list/get/create/update/delete/activate/deactivate/test), trigger set (8 types, builds correct config keys), action add/update/delete (6 types), secret, runs (list/get/rerun), fire (button-click/webhook), sql - --json mode for agent parsing; GET->modify->PUT whole-graph for node edits - Verified end-to-end: create workflow -> set webhook trigger -> add script action -> activate -> fire webhook -> runs list (succeeded) inkreach-teable-ops skill (.agents/skills/inkreach-teable-ops/): - SKILL.md entry: module map, routing rules, 11 key constraints (the real contract keys), execution rules, error recovery - guides/: cli-reference, automation-guide, tables-fields, instance-access, development (build/restart, known gotchas) - api-reference/: trigger-types (8 triggers, exact config), action-types (6 actions, sandbox globals), field-types (21 types incl. Button) - metadata.json + install.sh
2026-08-05 02:04:39 +08:00
commit 5fa843df05
24 changed files with 4380 additions and 0 deletions
@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = exports.Client = void 0;
+/**
+ * High-level API client. Each method maps to one REST endpoint of the
+ * inkreach-teable backend, using the SELF-BUILT contract (not official teable).
+ *
+ * Base/table/field/record/view endpoints are compatible with official teable
+ * open-api; workflow/automation endpoints use the project's own contract.
+ */
+const request_1 = require("./request");
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return request_1.ApiError; } });
+class Client {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get headers() {
+        return this.cfg.token ? { Authorization: `Bearer ${this.cfg.token}` } : {};
+    }
+    async call(method, p, body) {
+        const res = await (0, request_1.request)(this.cfg.endpoint, p, { method, headers: this.headers, body });
+        return res.data;
+    }
+    // ---- auth / user ----
+    getMe() {
+        // GET /api/auth/user — @TokenAccess() enabled, works with PAT.
+        // (/api/auth/user/me is session-only and 403s for PAT.)
+        return this.call('GET', '/api/auth/user');
+    }
+    // ---- access tokens (PAT) ----
+    listAccessTokens() {
+        return this.call('GET', '/api/access-token');
+    }
+    createAccessToken(body) {
+        return this.call('POST', '/api/access-token', body);
+    }
+    deleteAccessToken(id) {
+        return this.call('DELETE', `/api/access-token/${id}`);
+    }
+    // ---- base ----
+    listBases() {
+        // GET /api/base/access/all — lists bases the user can access.
+        return this.call('GET', '/api/base/access/all');
+    }
+    getBase(baseId) {
+        return this.call('GET', `/api/base/${baseId}`);
+    }
+    // ---- table ----
+    listTables(baseId) {
+        return this.call('GET', `/api/base/${baseId}/table`);
+    }
+    getTable(tableId) {
+        return this.call('GET', `/api/table/${tableId}`);
+    }
+    createTable(baseId, body) {
+        return this.call('POST', `/api/base/${baseId}/table`, body);
+    }
+    updateTable(tableId, body) {
+        return this.call('PUT', `/api/table/${tableId}`, body);
+    }
+    deleteTable(tableId) {
+        return this.call('DELETE', `/api/table/${tableId}`);
+    }
+    // ---- field ----
+    listFields(tableId) {
+        return this.call('GET', `/api/table/${tableId}/field`);
+    }
+    getField(fieldId) {
+        return this.call('GET', `/api/field/${fieldId}`);
+    }
+    createField(tableId, body) {
+        return this.call('POST', `/api/table/${tableId}/field`, body);
+    }
+    updateField(fieldId, body) {
+        return this.call('PUT', `/api/field/${fieldId}`, body);
+    }
+    deleteField(fieldId) {
+        return this.call('DELETE', `/api/field/${fieldId}`);
+    }
+    // ---- record ----
+    getRecords(tableId, query) {
+        const qs = query ? '?' + new URLSearchParams(this.flattenQuery(query)).toString() : '';
+        return this.call('GET', `/api/table/${tableId}/record${qs}`);
+    }
+    /** Flatten search[] tuple arrays into repeated query keys (Teable expects search[]=...). */
+    flattenQuery(query) {
+        const out = {};
+        for (const [k, v] of Object.entries(query)) {
+            if (v === undefined || v === null)
+                continue;
+            if (Array.isArray(v)) {
+                v.forEach((item) => {
+                    out[`${k}[]`] = typeof item === 'object' ? JSON.stringify(item) : String(item);
+                });
+            }
+            else if (typeof v === 'object') {
+                out[k] = JSON.stringify(v);
+            }
+            else {
+                out[k] = String(v);
+            }
+        }
+        return out;
+    }
+    getRecord(recordId, query) {
+        const qs = query ? '?' + new URLSearchParams(this.flattenQuery(query)).toString() : '';
+        return this.call('GET', `/api/record/${recordId}${qs}`);
+    }
+    createRecord(tableId, body) {
+        return this.call('POST', `/api/table/${tableId}/record`, body);
+    }
+    updateRecord(tableId, body) {
+        return this.call('PATCH', `/api/table/${tableId}/record`, body);
+    }
+    updateRecordOne(recordId, body) {
+        return this.call('PATCH', `/api/record/${recordId}`, body);
+    }
+    deleteRecord(tableId, body) {
+        return this.call('DELETE', `/api/table/${tableId}/record`, body);
+    }
+    // ---- view ----
+    listViews(tableId) {
+        return this.call('GET', `/api/table/${tableId}/view`);
+    }
+    getView(viewId) {
+        return this.call('GET', `/api/view/${viewId}`);
+    }
+    createView(tableId, body) {
+        return this.call('POST', `/api/table/${tableId}/view`, body);
+    }
+    updateView(viewId, body) {
+        return this.call('PATCH', `/api/view/${viewId}`, body);
+    }
+    deleteView(viewId) {
+        return this.call('DELETE', `/api/view/${viewId}`);
+    }
+    // ---- workflow (self-built contract) ----
+    listWorkflows(baseId) {
+        return this.call('GET', `/api/base/${baseId}/workflow`);
+    }
+    getWorkflow(workflowId) {
+        return this.call('GET', `/api/base/any/workflow/${workflowId}`);
+    }
+    /**
+     * Get workflow by explicit baseId + workflowId. getWorkflow() above hits a
+     * route that resolves base from the workflow itself, but some auth/permission
+     * paths need the base-scoped route. Prefer this when baseId is known.
+     */
+    getWorkflowInBase(baseId, workflowId) {
+        return this.call('GET', `/api/base/${baseId}/workflow/${workflowId}`);
+    }
+    createWorkflow(baseId, body) {
+        return this.call('POST', `/api/base/${baseId}/workflow`, body);
+    }
+    updateWorkflow(baseId, workflowId, body) {
+        return this.call('PATCH', `/api/base/${baseId}/workflow/${workflowId}`, body);
+    }
+    deleteWorkflow(baseId, workflowId) {
+        return this.call('DELETE', `/api/base/${baseId}/workflow/${workflowId}`);
+    }
+    activateWorkflow(baseId, workflowId) {
+        return this.call('POST', `/api/base/${baseId}/workflow/${workflowId}/activate`);
+    }
+    deactivateWorkflow(baseId, workflowId) {
+        return this.call('POST', `/api/base/${baseId}/workflow/${workflowId}/deactivate`);
+    }
+    testWorkflow(baseId, workflowId) {
+        return this.call('POST', `/api/base/${baseId}/workflow/${workflowId}/test`);
+    }
+    /** PUT /node — whole-graph replacement (delete-all + create-all in a txn). */
+    replaceNodes(baseId, workflowId, body) {
+        return this.call('PUT', `/api/base/${baseId}/workflow/${workflowId}/node`, body);
+    }
+    // ---- secrets ----
+    listSecrets(baseId, workflowId) {
+        return this.call('GET', `/api/base/${baseId}/workflow/${workflowId}/secret`);
+    }
+    createSecret(baseId, workflowId, body) {
+        return this.call('POST', `/api/base/${baseId}/workflow/${workflowId}/secret`, body);
+    }
+    updateSecret(baseId, workflowId, secretId, body) {
+        return this.call('PATCH', `/api/base/${baseId}/workflow/${workflowId}/secret/${secretId}`, body);
+    }
+    deleteSecret(baseId, workflowId, secretId) {
+        return this.call('DELETE', `/api/base/${baseId}/workflow/${workflowId}/secret/${secretId}`);
+    }
+    // ---- execution history ----
+    listExecutions(baseId, workflowId) {
+        return this.call('GET', `/api/base/${baseId}/workflow/${workflowId}/execution`);
+    }
+    getExecution(baseId, workflowId, executionId) {
+        return this.call('GET', `/api/base/${baseId}/workflow/${workflowId}/execution/${executionId}`);
+    }
+    rerunExecution(baseId, workflowId, executionId) {
+        return this.call('POST', `/api/base/${baseId}/workflow/${workflowId}/execution/${executionId}/rerun`);
+    }
+    // ---- trigger (manual fire for testing) ----
+    fireButtonClick(tableId, recordId, fieldId) {
+        return this.call('POST', `/api/table/${tableId}/record/${recordId}/${fieldId}/button-click`);
+    }
+    fireWebhook(baseId, workflowId, body) {
+        // NOTE: real backend route is /api/webhook/{baseId}/{workflowId} (no /base/ /workflow/ segments)
+        return this.call('POST', `/api/webhook/${baseId}/${workflowId}`, body);
+    }
+    // ---- SQL (read-only) ----
+    sql(baseId, sql) {
+        return this.call('POST', `/api/base/${baseId}/sql`, { sql });
+    }
+}
+exports.Client = Client;