feat(api): add proxy passthrough to OpenConnector

README.md

@@ -235,7 +235,7 @@ Full runnable lifecycle — [`examples/project.ts`](./examples/project.ts).
 
 ## Self-hosted runtime
 
-Running the open-source Connector server yourself (localhost, Docker, your own infra)? **`OpenConnector`** is the personal client for it — both call paths you know (everything except `proxy` and `using()`), pointed at your own server:
+Running the open-source Connector server yourself (localhost, Docker, your own infra)? **`OpenConnector`** is the personal client for it — the same call surface you know (everything except `using()`), pointed at your own server:
 
 ```ts
 import { OpenConnector } from "@oomol-lab/connector";
@@ -244,6 +244,7 @@ const open = new OpenConnector(); // defaults to http://localhost:3000; a fresh
 
 await open.execute("hackernews.get_top_stories", {}); // path 1 — dynamic string
 await open.gmail.search_threads({ query: "from:boss" }); // path 2 — namespace sugar, same registry types
+await open.proxy("github", { endpoint: "/user", method: "GET" }); // path 3 — passthrough (endpoint must be a relative path)
 await open.catalog.search("send email", { limit: 5 }); // runtime extras: search, services, health
 await open.apps.list();
 ```
@@ -258,7 +259,7 @@ const open = new OpenConnector({
 ```
 
 > [!NOTE]
-> Connections, credentials, and OAuth setup are managed in the runtime's **web console** — that's server administration, deliberately outside this SDK. The client consumes what the console configured; connection selection has two layers (per-call `connectionName` over the client-level default — there is no `using()` scope and no `organization`). And as on the hosted client, a service id that collides with a member name (`execute` / `executeRaw` / `health` / `catalog` / `apps`) keeps working through `execute("<service>.<action>", …)` — only its namespace sugar is shadowed.
+> Connections, credentials, and OAuth setup are managed in the runtime's **web console** — that's server administration, deliberately outside this SDK. The client consumes what the console configured; connection selection has two layers (per-call `connectionName` over the client-level default — there is no `using()` scope and no `organization`). And as on the hosted client, a service id that collides with a member name (`execute` / `executeRaw` / `health` / `proxy` / `catalog` / `apps`) keeps working through `execute("<service>.<action>", …)` — only its namespace sugar is shadowed.
 
 Full runnable tour — [`examples/open.ts`](./examples/open.ts).
 

docs/README/README.fr.md

@@ -235,7 +235,7 @@ Cycle de vie complet exécutable — [`examples/project.ts`](../../examples/proj
 
 ## Runtime auto-hébergé
 
-Vous faites tourner vous-même le serveur Connector open source (localhost, Docker, votre propre infrastructure) ? **`OpenConnector`** en est le client personnel — les deux voies d'appel que vous connaissez (tout sauf `proxy` et `using()`), pointées vers votre propre serveur :
+Vous faites tourner vous-même le serveur Connector open source (localhost, Docker, votre propre infrastructure) ? **`OpenConnector`** en est le client personnel — la même surface d'appel que vous connaissez (tout sauf `using()`), pointée vers votre propre serveur :
 
 ```ts
 import { OpenConnector } from "@oomol-lab/connector";
@@ -244,6 +244,7 @@ const open = new OpenConnector(); // defaults to http://localhost:3000; a fresh
 
 await open.execute("hackernews.get_top_stories", {}); // path 1 — dynamic string
 await open.gmail.search_threads({ query: "from:boss" }); // path 2 — namespace sugar, same registry types
+await open.proxy("github", { endpoint: "/user", method: "GET" }); // path 3 — passthrough (endpoint must be a relative path)
 await open.catalog.search("send email", { limit: 5 }); // runtime extras: search, services, health
 await open.apps.list();
 ```
@@ -258,7 +259,7 @@ const open = new OpenConnector({
 ```
 
 > [!NOTE]
-> Les connexions, les identifiants et la configuration OAuth se gèrent dans la **console web** du runtime — il s'agit d'administration serveur, délibérément hors de ce SDK. Le client consomme ce que la console a configuré ; la sélection de connexion comporte deux couches (le `connectionName` par appel l'emporte sur la valeur par défaut au niveau du client — il n'y a ni portée `using()` ni `organization`). Et comme sur le client hébergé, un identifiant de service qui entre en collision avec un nom de membre (`execute` / `executeRaw` / `health` / `catalog` / `apps`) continue de fonctionner via `execute("<service>.<action>", …)` — seul son sucre de namespace est masqué.
+> Les connexions, les identifiants et la configuration OAuth se gèrent dans la **console web** du runtime — il s'agit d'administration serveur, délibérément hors de ce SDK. Le client consomme ce que la console a configuré ; la sélection de connexion comporte deux couches (le `connectionName` par appel l'emporte sur la valeur par défaut au niveau du client — il n'y a ni portée `using()` ni `organization`). Et comme sur le client hébergé, un identifiant de service qui entre en collision avec un nom de membre (`execute` / `executeRaw` / `health` / `proxy` / `catalog` / `apps`) continue de fonctionner via `execute("<service>.<action>", …)` — seul son sucre de namespace est masqué.
 
 Visite guidée complète exécutable — [`examples/open.ts`](../../examples/open.ts).
 

docs/README/README.ja.md

@@ -235,7 +235,7 @@ await user.execute("gmail.search_threads", { query: "from:ceo" });
 
 ## セルフホストランタイム
 
-オープンソースの Connector サーバーを自分で運用していますか?（localhost、Docker、あなた自身のインフラ）**`OpenConnector`** はそのための個人向けクライアントです — おなじみの両方の呼び出しパス（`proxy` と `using()` を除くすべて）を、あなた自身のサーバーに向けます:
+オープンソースの Connector サーバーを自分で運用していますか?（localhost、Docker、あなた自身のインフラ）**`OpenConnector`** はそのための個人向けクライアントです — おなじみの呼び出し一式（`using()` を除くすべて）を、あなた自身のサーバーに向けます:
 
 ```ts
 import { OpenConnector } from "@oomol-lab/connector";
@@ -244,6 +244,7 @@ const open = new OpenConnector(); // defaults to http://localhost:3000; a fresh
 
 await open.execute("hackernews.get_top_stories", {}); // path 1 — dynamic string
 await open.gmail.search_threads({ query: "from:boss" }); // path 2 — namespace sugar, same registry types
+await open.proxy("github", { endpoint: "/user", method: "GET" }); // path 3 — passthrough (endpoint must be a relative path)
 await open.catalog.search("send email", { limit: 5 }); // runtime extras: search, services, health
 await open.apps.list();
 ```
@@ -258,7 +259,7 @@ const open = new OpenConnector({
 ```
 
 > [!NOTE]
-> コネクション、認証情報、OAuth のセットアップは、ランタイムの **Web コンソール**で管理されます — これはサーバー管理であり、意図的にこの SDK の外に置かれています。クライアントはコンソールで設定された内容を利用します。コネクションの選択には2つの層があります（呼び出しごとの `connectionName` がクライアントレベルのデフォルトを上書きします — `using()` スコープも `organization` もありません）。そしてホスト型クライアントと同様に、メンバー名（`execute` / `executeRaw` / `health` / `catalog` / `apps`）と衝突するサービス id は、`execute("<service>.<action>", …)` を通じて動作し続けます — シャドウされるのはその名前空間シュガーだけです。
+> コネクション、認証情報、OAuth のセットアップは、ランタイムの **Web コンソール**で管理されます — これはサーバー管理であり、意図的にこの SDK の外に置かれています。クライアントはコンソールで設定された内容を利用します。コネクションの選択には2つの層があります（呼び出しごとの `connectionName` がクライアントレベルのデフォルトを上書きします — `using()` スコープも `organization` もありません）。そしてホスト型クライアントと同様に、メンバー名（`execute` / `executeRaw` / `health` / `proxy` / `catalog` / `apps`）と衝突するサービス id は、`execute("<service>.<action>", …)` を通じて動作し続けます — シャドウされるのはその名前空間シュガーだけです。
 
 完全に実行可能なツアーは [`examples/open.ts`](../../examples/open.ts) を参照。
 

docs/README/README.ru.md

@@ -235,7 +235,7 @@ await user.execute("gmail.search_threads", { query: "from:ceo" });
 
 ## Самостоятельно размещаемая среда выполнения
 
-Запускаете сервер Connector с открытым исходным кодом самостоятельно (localhost, Docker, ваша собственная инфраструктура)? **`OpenConnector`** — это персональный клиент для него — оба знакомых вам пути вызова (всё, кроме `proxy` и `using()`), направленные на ваш собственный сервер:
+Запускаете сервер Connector с открытым исходным кодом самостоятельно (localhost, Docker, ваша собственная инфраструктура)? **`OpenConnector`** — это персональный клиент для него — тот же знакомый вам набор вызовов (всё, кроме `using()`), направленный на ваш собственный сервер:
 
 ```ts
 import { OpenConnector } from "@oomol-lab/connector";
@@ -244,6 +244,7 @@ const open = new OpenConnector(); // defaults to http://localhost:3000; a fresh
 
 await open.execute("hackernews.get_top_stories", {}); // path 1 — dynamic string
 await open.gmail.search_threads({ query: "from:boss" }); // path 2 — namespace sugar, same registry types
+await open.proxy("github", { endpoint: "/user", method: "GET" }); // path 3 — passthrough (endpoint must be a relative path)
 await open.catalog.search("send email", { limit: 5 }); // runtime extras: search, services, health
 await open.apps.list();
 ```
@@ -258,7 +259,7 @@ const open = new OpenConnector({
 ```
 
 > [!NOTE]
-> Подключения, учётные данные и настройка OAuth управляются в **веб-консоли** среды выполнения — это администрирование сервера, намеренно вынесенное за пределы этого SDK. Клиент потребляет то, что настроено в консоли; выбор подключения имеет два уровня (`connectionName` на уровне вызова поверх значения по умолчанию на уровне клиента — здесь нет ни области `using()`, ни `organization`). И, как и на размещённом клиенте, идентификатор сервиса, совпадающий с именем члена (`execute` / `executeRaw` / `health` / `catalog` / `apps`), продолжает работать через `execute("<service>.<action>", …)` — затеняется только его синтаксический сахар пространства имён.
+> Подключения, учётные данные и настройка OAuth управляются в **веб-консоли** среды выполнения — это администрирование сервера, намеренно вынесенное за пределы этого SDK. Клиент потребляет то, что настроено в консоли; выбор подключения имеет два уровня (`connectionName` на уровне вызова поверх значения по умолчанию на уровне клиента — здесь нет ни области `using()`, ни `organization`). И, как и на размещённом клиенте, идентификатор сервиса, совпадающий с именем члена (`execute` / `executeRaw` / `health` / `proxy` / `catalog` / `apps`), продолжает работать через `execute("<service>.<action>", …)` — затеняется только его синтаксический сахар пространства имён.
 
 Полный запускаемый обзор — [`examples/open.ts`](../../examples/open.ts).
 

docs/README/README.zh-CN.md

@@ -235,7 +235,7 @@ await user.execute("gmail.search_threads", { query: "from:ceo" });
 
 ## 自托管运行时
 
-自己运行开源的 Connector 服务端(localhost、Docker、你自己的基础设施)?**`OpenConnector`** 就是为此准备的个人客户端——你熟悉的两种调用路径(除 `proxy` 和 `using()` 之外的一切),指向你自己的服务器:
+自己运行开源的 Connector 服务端(localhost、Docker、你自己的基础设施)?**`OpenConnector`** 就是为此准备的个人客户端——你熟悉的整套调用面(除 `using()` 之外的一切),指向你自己的服务器:
 
 ```ts
 import { OpenConnector } from "@oomol-lab/connector";
@@ -244,6 +244,7 @@ const open = new OpenConnector(); // defaults to http://localhost:3000; a fresh
 
 await open.execute("hackernews.get_top_stories", {}); // path 1 — dynamic string
 await open.gmail.search_threads({ query: "from:boss" }); // path 2 — namespace sugar, same registry types
+await open.proxy("github", { endpoint: "/user", method: "GET" }); // path 3 — passthrough (endpoint must be a relative path)
 await open.catalog.search("send email", { limit: 5 }); // runtime extras: search, services, health
 await open.apps.list();
 ```
@@ -258,7 +259,7 @@ const open = new OpenConnector({
 ```
 
 > [!NOTE]
-> 连接、凭证与 OAuth 配置都在运行时的 **Web 控制台**中管理——那属于服务端管理,有意排除在本 SDK 之外。客户端消费控制台所配置的内容;连接选择有两层(按调用的 `connectionName` 覆盖客户端级默认值——没有 `using()` 作用域,也没有 `organization`)。而且与托管客户端一样,当某个 service id 与成员名(`execute` / `executeRaw` / `health` / `catalog` / `apps`)冲突时,仍可通过 `execute("<service>.<action>", …)` 正常工作——只是它的命名空间语法糖会被遮蔽。
+> 连接、凭证与 OAuth 配置都在运行时的 **Web 控制台**中管理——那属于服务端管理,有意排除在本 SDK 之外。客户端消费控制台所配置的内容;连接选择有两层(按调用的 `connectionName` 覆盖客户端级默认值——没有 `using()` 作用域,也没有 `organization`)。而且与托管客户端一样,当某个 service id 与成员名(`execute` / `executeRaw` / `health` / `proxy` / `catalog` / `apps`)冲突时,仍可通过 `execute("<service>.<action>", …)` 正常工作——只是它的命名空间语法糖会被遮蔽。
 
 完整可运行的示例导览见 [`examples/open.ts`](../../examples/open.ts)。
 

docs/README/README.zh-TW.md

@@ -235,7 +235,7 @@ await user.execute("gmail.search_threads", { query: "from:ceo" });
 
 ## 自架執行環境
 
-自己在跑開源的 Connector 伺服器嗎（localhost、Docker、你自己的基礎設施）？**`OpenConnector`** 就是為它準備的個人用戶端——你熟悉的兩種呼叫路徑（除了 `proxy` 與 `using()` 之外的一切），指向你自己的伺服器：
+自己在跑開源的 Connector 伺服器嗎（localhost、Docker、你自己的基礎設施）？**`OpenConnector`** 就是為它準備的個人用戶端——你熟悉的整套呼叫面（除了 `using()` 之外的一切），指向你自己的伺服器：
 
 ```ts
 import { OpenConnector } from "@oomol-lab/connector";
@@ -244,6 +244,7 @@ const open = new OpenConnector(); // defaults to http://localhost:3000; a fresh
 
 await open.execute("hackernews.get_top_stories", {}); // path 1 — dynamic string
 await open.gmail.search_threads({ query: "from:boss" }); // path 2 — namespace sugar, same registry types
+await open.proxy("github", { endpoint: "/user", method: "GET" }); // path 3 — passthrough (endpoint must be a relative path)
 await open.catalog.search("send email", { limit: 5 }); // runtime extras: search, services, health
 await open.apps.list();
 ```
@@ -258,7 +259,7 @@ const open = new OpenConnector({
 ```
 
 > [!NOTE]
-> Connection、憑證與 OAuth 設定都在執行環境的 **web console** 中管理——那屬於伺服器管理，刻意排除在這個 SDK 之外。用戶端只消費 console 所設定好的內容；connection 的選取有兩層（逐次呼叫的 `connectionName` 覆蓋用戶端層級的預設值——沒有 `using()` 範圍，也沒有 `organization`）。而且和託管用戶端一樣，當某個 service id 與成員名稱（`execute` / `executeRaw` / `health` / `catalog` / `apps`）衝突時，仍可透過 `execute("<service>.<action>", …)` 正常運作——只有它的 namespace sugar 會被遮蔽。
+> Connection、憑證與 OAuth 設定都在執行環境的 **web console** 中管理——那屬於伺服器管理，刻意排除在這個 SDK 之外。用戶端只消費 console 所設定好的內容；connection 的選取有兩層（逐次呼叫的 `connectionName` 覆蓋用戶端層級的預設值——沒有 `using()` 範圍，也沒有 `organization`）。而且和託管用戶端一樣，當某個 service id 與成員名稱（`execute` / `executeRaw` / `health` / `proxy` / `catalog` / `apps`）衝突時，仍可透過 `execute("<service>.<action>", …)` 正常運作——只有它的 namespace sugar 會被遮蔽。
 
 完整可執行導覽——[`examples/open.ts`](../../examples/open.ts)。
 

examples/open.ts

@@ -2,7 +2,7 @@
  * OpenConnector — the personal client for the open-source, self-hosted Connector runtime.
  *
  * It mirrors the core `Connector` surface (execute + `open.<service>.<action>` namespace sugar,
- * catalog / apps / health) against the server YOU run. Connections and credentials are managed in
+ * proxy passthrough, catalog / apps / health) against the server YOU run. Connections and credentials are managed in
  * the runtime's web console — the SDK only consumes them. Auth is a single optional runtime token
  * (`oct_…`, minted in that console); a fresh instance answers without one.
  *
@@ -44,6 +44,12 @@ async function main() {
   const raw = await open.executeRaw("github.get_current_user", {}, { connectionName: "work" });
   console.log("executionId:", raw.executionId);
 
+  // --- Proxy an endpoint that has no action yet ---------------------------------------------------
+  // Path 3 — reach a provider endpoint directly, credentials injected server-side. The runtime
+  // requires a RELATIVE `endpoint` (starting with `/`); pick a connection with `connectionName`.
+  const repos = await open.proxy("github", { endpoint: "/user/repos", method: "GET", query: { per_page: 5 } });
+  console.log("proxy status:", repos.status, "repos:", Array.isArray(repos.data) ? repos.data.length : repos.data);
+
   // --- Inspect what's connected ------------------------------------------------------------------
   const apps = await open.apps.list();
   console.log("connected apps:", apps.map((app) => `${app.service}:${app.connectionName}`));