feat: add 5 end-to-end provider examples (#1)

* feat: add end-to-end provider examples

Five runnable TypeScript examples covering the core provider patterns:
- Nango GitHub proxy with optional baseUrl override
- Composio proxy with toolkit/action resolution
- Provider + Adapter webhook→writeback flow (core pattern)
- Multi-provider registry in a single app
- Health checks and connection listing

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix composio example field names

* fix: address Devin review feedback

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: khaliqgant

examples/01-nango-github-proxy/README.md

@@ -0,0 +1,34 @@
+# 01 — Nango GitHub Proxy
+
+Proxy GitHub API requests through Nango with automatic OAuth token injection.
+
+## Key concepts
+
+- **`baseUrl` is optional** — the provider resolves it from the connection's provider-config-key.
+- Override `baseUrl` when targeting a non-default API host (e.g. `uploads.github.com`).
+- No `RelayFileClient` needed for Nango — just `secretKey`.
+
+## Setup
+
+```bash
+export NANGO_SECRET_KEY="your-nango-secret-key"
+export NANGO_CONNECTION_ID="conn_github_demo"
+```
+
+## Run
+
+```bash
+npx tsx examples/01-nango-github-proxy/index.ts
+```
+
+## Mock testing
+
+Without real credentials the Nango API will reject requests. To test the
+wiring locally, swap in a mock `fetch` via the provider config:
+
+```ts
+const nango = new NangoProvider({
+  secretKey: "mock",
+  fetch: async () => new Response(JSON.stringify({ ok: true }), { status: 200 }),
+});
+```

examples/01-nango-github-proxy/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Example 01 — Nango GitHub Proxy
+ *
+ * Demonstrates NangoProvider proxying GitHub API requests.
+ * baseUrl is optional: the provider resolves it from the connection
+ * when omitted, or you can override it for non-default API hosts
+ * like uploads.github.com.
+ */
+
+import { NangoProvider } from "@relayfile/provider-nango";
+
+// ── Config ──────────────────────────────────────────────────────────
+// In production, pull from environment variables.
+// For local testing you can hardcode or use a .env loader.
+const NANGO_SECRET_KEY = process.env.NANGO_SECRET_KEY ?? "nango-mock-secret-key";
+const CONNECTION_ID = process.env.NANGO_CONNECTION_ID ?? "conn_github_demo";
+
+async function main() {
+  // Nango does not require a RelayFileClient — just the secret key.
+  const nango = new NangoProvider({
+    secretKey: NANGO_SECRET_KEY,
+    // baseUrl is optional; defaults to https://api.nango.dev
+  });
+
+  console.log("Provider:", nango.name);
+
+  // ── 1. Proxy without baseUrl ──────────────────────────────────────
+  // The provider resolves the target API host from the connection's
+  // provider-config-key (e.g. "github" → api.github.com).
+  console.log("\n--- List pull requests (baseUrl omitted) ---");
+  const pulls = await nango.proxy({
+    method: "GET",
+    endpoint: "/repos/acme/api/pulls",
+    connectionId: CONNECTION_ID,
+    query: { state: "open", per_page: "5" },
+  });
+  console.log("Status:", pulls.status);
+  console.log("Data:", JSON.stringify(pulls.data, null, 2));
+
+  // ── 2. Proxy WITH baseUrl override ────────────────────────────────
+  // uploads.github.com is a different host from the default
+  // api.github.com — pass it explicitly.
+  console.log("\n--- List release assets (baseUrl override) ---");
+  const assets = await nango.proxy({
+    method: "GET",
+    baseUrl: "https://uploads.github.com",
+    endpoint: "/repos/acme/api/releases/1/assets",
+    connectionId: CONNECTION_ID,
+  });
+  console.log("Status:", assets.status);
+  console.log("Data:", JSON.stringify(assets.data, null, 2));
+
+  // ── 3. POST example ──────────────────────────────────────────────
+  console.log("\n--- Create issue comment ---");
+  const comment = await nango.proxy({
+    method: "POST",
+    endpoint: "/repos/acme/api/issues/42/comments",
+    connectionId: CONNECTION_ID,
+    body: { body: "Automated comment from relayfile provider" },
+  });
+  console.log("Status:", comment.status);
+  console.log("Data:", JSON.stringify(comment.data, null, 2));
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});

examples/02-composio-proxy/README.md

@@ -0,0 +1,35 @@
+# 02 — Composio Proxy
+
+Proxy API calls and execute actions through Composio connected accounts.
+
+## Key concepts
+
+- **Toolkit resolution** — `lookupAction()` maps a proxy request to the right Composio action/toolkit.
+- **`baseUrl` is optional** — resolved from the connected account.
+- **Action execution** — call Composio actions directly with `executeAction()`.
+- No `RelayFileClient` needed for Composio — just `apiKey`.
+
+## Setup
+
+```bash
+export COMPOSIO_API_KEY="your-composio-api-key"
+export COMPOSIO_ENTITY_ID="entity_demo"
+export COMPOSIO_CONNECTION_ID="conn_composio_demo"
+```
+
+## Run
+
+```bash
+npx tsx examples/02-composio-proxy/index.ts
+```
+
+## Mock testing
+
+Swap in a mock `fetch` to test locally without real credentials:
+
+```ts
+const composio = new ComposioProvider({
+  apiKey: "mock",
+  fetch: async () => new Response(JSON.stringify({ items: [] }), { status: 200 }),
+});
+```

examples/02-composio-proxy/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Example 02 — Composio Proxy
+ *
+ * Demonstrates ComposioProvider proxy and toolkit resolution.
+ * The provider resolves which action/toolkit to invoke from the
+ * connected account when baseUrl is omitted.
+ */
+
+import { ComposioProvider } from "@relayfile/provider-composio";
+
+// ── Config ──────────────────────────────────────────────────────────
+const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY ?? "composio-mock-api-key";
+const ENTITY_ID = process.env.COMPOSIO_ENTITY_ID ?? "entity_demo";
+const CONNECTION_ID = process.env.COMPOSIO_CONNECTION_ID ?? "conn_composio_demo";
+
+async function main() {
+  // Composio does not require a RelayFileClient — just the API key.
+  const composio = new ComposioProvider({
+    apiKey: COMPOSIO_API_KEY,
+    // baseUrl defaults to https://backend.composio.dev/api/v3
+  });
+
+  console.log("Provider:", composio.name);
+
+  // ── 1. Proxy through connected account ────────────────────────────
+  // baseUrl is optional — the provider resolves it from the account.
+  console.log("\n--- Proxy: list GitHub repos via Composio ---");
+  const repos = await composio.proxy({
+    method: "GET",
+    endpoint: "/user/repos",
+    connectionId: CONNECTION_ID,
+    query: { per_page: "5" },
+  });
+  console.log("Status:", repos.status);
+  console.log("Data:", JSON.stringify(repos.data, null, 2));
+
+  // ── 2. Toolkit / action resolution ────────────────────────────────
+  // lookupAction resolves which Composio action maps to a proxy request.
+  console.log("\n--- Action lookup ---");
+  const lookup = await composio.lookupAction({
+    method: "POST",
+    endpoint: "/repos/acme/api/issues",
+    connectionId: CONNECTION_ID,
+    body: { title: "Bug report", body: "Details here" },
+  });
+  console.log("Matched by:", lookup.matchedBy);
+  console.log("Toolkit:", lookup.toolkitSlug ?? "(none)");
+  console.log("Action:", lookup.toolSlug ?? "(none)");
+
+  // ── 3. Execute an action directly ─────────────────────────────────
+  console.log("\n--- Execute action: GITHUB_CREATE_ISSUE ---");
+  const result = await composio.executeAction(
+    "GITHUB_CREATE_ISSUE",
+    ENTITY_ID,
+    { owner: "acme", repo: "api", title: "Filed by relayfile" },
+  );
+  console.log("Execution successful:", result.successful);
+  console.log("Result:", JSON.stringify(result.data, null, 2));
+
+  // ── 4. List connected accounts ────────────────────────────────────
+  console.log("\n--- Connected accounts ---");
+  const accounts = await composio.listConnectedAccounts();
+  console.log("Total:", accounts.total);
+  for (const account of accounts.items) {
+    console.log(`  - ${account.id} (${account.status})`);
+  }
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});

examples/03-provider-with-adapter/README.md

@@ -0,0 +1,54 @@
+# 03 — Provider + Adapter
+
+**This is the most important example.** It demonstrates the core relayfile pattern: providers handle auth while adapters normalize data and write back.
+
+## Flow
+
+```
+Webhook (GitHub event)
+  → NangoProvider.handleWebhook()   — normalizes into NormalizedWebhook
+  → GitHubAdapter.mapWebhookToPath() — maps to VFS path
+  → GitHubAdapter.writeback()        — calls provider.proxy() to post back
+  → NangoProvider.proxy()            — injects OAuth token, forwards to GitHub
+```
+
+## Key concepts
+
+- **Provider** = auth layer. Handles OAuth tokens, proxies API calls.
+- **Adapter** = data layer. Normalizes webhooks, maps to VFS paths, writes back through the provider.
+- Agents never see the provider or adapter — they just read/write files.
+- `baseUrl` is optional on writeback — the provider resolves it.
+
+## Setup
+
+```bash
+export NANGO_SECRET_KEY="your-nango-secret-key"
+export NANGO_CONNECTION_ID="conn_github_demo"
+```
+
+## Run
+
+```bash
+npx tsx examples/03-provider-with-adapter/index.ts
+```
+
+The example uses mock webhook data so it runs without real GitHub events. The writeback call will fail without valid credentials — this is expected and handled.
+
+## In production
+
+Replace `GitHubAdapterStub` with the real `@relayfile/adapter-github`:
+
+```ts
+import { GitHubAdapter } from "@relayfile/adapter-github";
+import { NangoProvider } from "@relayfile/provider-nango";
+
+const provider = new NangoProvider({ secretKey: process.env.NANGO_SECRET_KEY! });
+const adapter = new GitHubAdapter({ provider });
+
+await adapter.writeback({
+  provider,
+  connectionId: "conn_abc",
+  path: "/github/repos/acme/api/pulls/42/comments",
+  payload: { body: "Looks good!" },
+});
+```

examples/03-provider-with-adapter/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Example 03 — Provider + Adapter (MOST IMPORTANT)
+ *
+ * Shows the core relayfile pattern: a Provider handles auth while an
+ * Adapter normalizes data and writes back through the provider.
+ *
+ * Flow:
+ *   Webhook → NangoProvider.handleWebhook() normalizes the event
+ *   → GitHubAdapter maps it to a VFS path
+ *   → Adapter writes back through NangoProvider.proxy()
+ *
+ * This example simulates the full cycle with mock webhook data.
+ */
+
+import { NangoProvider } from "@relayfile/provider-nango";
+import type { NormalizedWebhook, ProxyResponse } from "@relayfile/provider-nango";
+
+// ── Config ──────────────────────────────────────────────────────────
+const NANGO_SECRET_KEY = process.env.NANGO_SECRET_KEY ?? "nango-mock-secret-key";
+const CONNECTION_ID = process.env.NANGO_CONNECTION_ID ?? "conn_github_demo";
+
+// ── Mock adapter ────────────────────────────────────────────────────
+// In production you would import GitHubAdapter from @relayfile/adapter-github.
+// This minimal adapter demonstrates the contract between adapter and provider.
+
+interface AdapterWritebackRequest {
+  connectionId: string;
+  path: string;
+  payload: Record<string, unknown>;
+}
+
+class GitHubAdapterStub {
+  constructor(private provider: NangoProvider) {}
+
+  /**
+   * Convert a normalized webhook into a VFS path.
+   * Real adapters do richer mapping; this shows the shape.
+   */
+  mapWebhookToPath(webhook: NormalizedWebhook): string {
+    const { provider, objectType, objectId, eventType } = webhook;
+    // Example: /github/repos/acme/api/issues/42
+    return `/${provider}/${objectType}/${objectId}`;
+  }
+
+  /**
+   * Write back to the external API through the provider.
+   * The provider handles OAuth — the adapter just describes the request.
+   */
+  async writeback(request: AdapterWritebackRequest): Promise<ProxyResponse> {
+    console.log(`[Adapter] Writing back to ${request.path}`);
+    return this.provider.proxy({
+      method: "POST",
+      endpoint: request.path,
+      connectionId: request.connectionId,
+      body: request.payload,
+      // baseUrl omitted — provider resolves from connection
+    });
+  }
+}
+
+// ── Mock webhook payload ────────────────────────────────────────────
+// Simulates a Nango forward-webhook for a GitHub pull_request event.
+const mockWebhookPayload = {
+  type: "forward",
+  connectionId: CONNECTION_ID,
+  providerConfigKey: "github",
+  payload: {
+    action: "opened",
+    pull_request: {
+      number: 99,
+      title: "Add relayfile examples",
+      html_url: "https://github.com/acme/api/pull/99",
+      user: { login: "agent-bot" },
+    },
+    repository: {
+      full_name: "acme/api",
+    },
+  },
+};
+
+async function main() {
+  const nango = new NangoProvider({
+    secretKey: NANGO_SECRET_KEY,
+  });
+  const adapter = new GitHubAdapterStub(nango);
+
+  console.log("Provider:", nango.name);
+
+  // ── Step 1: Normalize the incoming webhook ────────────────────────
+  console.log("\n--- Step 1: Normalize webhook ---");
+  const webhook = await nango.handleWebhook(mockWebhookPayload);
+  console.log("Provider:", webhook.provider);
+  console.log("Event:", webhook.eventType);
+  console.log("Object:", webhook.objectType, webhook.objectId);
+  console.log("Connection:", webhook.connectionId);
+
+  // ── Step 2: Adapter maps webhook to VFS path ─────────────────────
+  console.log("\n--- Step 2: Map to VFS path ---");
+  const vfsPath = adapter.mapWebhookToPath(webhook);
+  console.log("VFS path:", vfsPath);
+
+  // ── Step 3: Adapter writes back through provider ──────────────────
+  console.log("\n--- Step 3: Writeback through provider ---");
+  try {
+    const response = await adapter.writeback({
+      connectionId: CONNECTION_ID,
+      path: "/repos/acme/api/pulls/99/comments",
+      payload: { body: "Thanks for the PR! Reviewing now." },
+    });
+    console.log("Writeback status:", response.status);
+    console.log("Writeback data:", JSON.stringify(response.data, null, 2));
+  } catch (err) {
+    // Expected when running without real credentials
+    console.log("Writeback failed (expected without real credentials):", (err as Error).message);
+  }
+
+  // ── Step 4: Show the full flow ────────────────────────────────────
+  console.log("\n--- Full flow summary ---");
+  console.log("1. Webhook received from Nango (GitHub push event)");
+  console.log("2. Provider normalized it into a NormalizedWebhook");
+  console.log("3. Adapter mapped it to VFS path:", vfsPath);
+  console.log("4. Adapter wrote back through provider.proxy()");
+  console.log("5. Provider injected OAuth token and forwarded to GitHub API");
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});