chore: add fastapi example from markdown (#2251)

Author: harbournick

examples/collaboration/fastapi/.gitignore

@@ -0,0 +1,3 @@
+.superdoc-state/
+.venv/
+__pycache__/

examples/collaboration/fastapi/README.md

@@ -0,0 +1,81 @@
+# FastAPI + SuperDoc Collaboration (Barebones)
+
+Tiny demo focused on one thing: open a realtime collaboration session from Python and mutate it via HTTP.
+
+`main.py` is currently hardcoded for the local `@y/hub` server in `./yjs-hub`.
+It is also hardcoded to use the repo CLI at `apps/cli/src/index.ts` (via bun)
+and local state at `examples/collaboration/fastapi/.superdoc-state`.
+
+## 1) FastAPI setup
+
+```bash
+cd /Users/nickjbernal/dev/superdoc/examples/collaboration/fastapi
+uv venv .venv
+source .venv/bin/activate
+uv pip install -r requirements.txt
+```
+
+## 2) Start a collaboration server
+
+### Option A: Local `@y/hub` (for this example)
+
+From the FastAPI folder:
+
+```bash
+cd /Users/nickjbernal/dev/superdoc/examples/collaboration/fastapi
+./run-yjs-hub.sh
+```
+
+Or manually:
+
+```bash
+cd /Users/nickjbernal/dev/superdoc/examples/collaboration/fastapi/yjs-hub
+pnpm install --ignore-workspace --lockfile=false
+pnpm run deps:up
+pnpm run dev
+```
+
+`deps:up` requires Docker daemon running (Docker Desktop on macOS).
+If you already run Redis/Postgres locally, use:
+
+```bash
+./run-yjs-hub.sh --no-docker
+```
+
+The bundled `yjs-hub` demo is ephemeral by default (no persistence across server restarts).
+
+This serves websocket rooms at:
+
+```text
+ws://127.0.0.1:8081/v1/collaboration/:documentId
+```
+
+### Option B: Internal repo dev collab server
+
+```bash
+cd /Users/nickjbernal/dev/superdoc
+pnpm dev:collab
+```
+
+If you use Option B, update `main.py` to point back to that server URL.
+
+## 3) Start FastAPI
+
+```bash
+cd /Users/nickjbernal/dev/superdoc/examples/collaboration/fastapi
+uvicorn main:app --reload --port 8000
+```
+
+## 4) Test Python API
+
+```bash
+curl "http://127.0.0.1:8000/status"
+curl "http://127.0.0.1:8000/insert?text=hello%20world"
+```
+
+## Endpoints
+
+- `GET /` returns open result + collab config.
+- `GET /status` returns current document/session status.
+- `GET /insert?text=...` inserts text into the live collaborative doc.
+- `GET /download` exports the current session as `.docx` and downloads it.

examples/collaboration/fastapi/assets/doc-template.docx

@@ -0,0 +1,114 @@
+# Non-Disclosure Agreement
+
+**Effective Date:** January 15, 2026
+
+This Non-Disclosure Agreement ("Agreement") is entered into by and between the following parties:
+
+| Party | Name | Role |
+|---|---|---|
+| Disclosing Party | Meridian Dynamics Inc. | Provider of Confidential Information |
+| Receiving Party | Orion Consulting Group LLC | Recipient of Confidential Information |
+
+collectively referred to as the "Parties."
+
+## 1. Purpose
+
+The Disclosing Party intends to share certain proprietary and confidential information with the Receiving Party for the sole purpose of:
+
+1. Evaluating a potential business partnership between the Parties
+2. Conducting technical due diligence on the Disclosing Party's platform
+3. Preparing a joint proposal for the Albright Municipal Infrastructure Project
+
+## 2. Definition of confidential information
+
+"Confidential Information" means any non-public information disclosed by the Disclosing Party, whether in writing, orally, or by inspection, including but not limited to:
+
+- Trade secrets, inventions, and patent applications
+- Software source code, algorithms, and system architecture
+- Financial records, projections, and pricing models
+- Customer lists, vendor agreements, and sales data
+- Marketing strategies and product roadmaps
+- Employee records and compensation structures
+
+### 2.1 Exclusions
+
+Confidential Information does not include information that:
+
+- Was publicly available at the time of disclosure
+- Becomes publicly available through no fault of the Receiving Party
+- Was already known to the Receiving Party prior to disclosure, as documented in writing
+- Is independently developed by the Receiving Party without use of the Confidential Information
+- Is disclosed with the prior written consent of the Disclosing Party
+
+## 3. Obligations of the receiving party
+
+The Receiving Party agrees to:
+
+1. Hold all Confidential Information in strict confidence
+2. Not disclose any Confidential Information to third parties without prior written consent
+3. Limit internal access to personnel who:
+   - Have a legitimate need to know
+   - Are bound by confidentiality obligations no less restrictive than this Agreement
+4. Use the Confidential Information solely for the purposes outlined in Section 1
+5. Notify the Disclosing Party immediately upon discovery of any unauthorized disclosure
+
+### 3.1 Permitted disclosures
+
+The Receiving Party may disclose Confidential Information if required by:
+
+- A valid court order or subpoena
+- Applicable federal, state, or local law
+- A regulatory authority with jurisdiction over the Receiving Party
+
+provided that the Receiving Party gives the Disclosing Party prompt written notice and cooperates in seeking a protective order.
+
+## 4. Term and termination
+
+| Provision | Duration |
+|---|---|
+| Agreement term | 2 years from the Effective Date |
+| Confidentiality obligations | 5 years from the date of each disclosure |
+| Return of materials | 30 days after termination |
+
+Either Party may terminate this Agreement at any time by providing 30 days' written notice to the other Party. Upon termination, the Receiving Party shall:
+
+1. Cease all use of Confidential Information
+2. Return or destroy all copies of Confidential Information in its possession
+3. Provide written certification of destruction within 30 days
+
+## 5. Remedies
+
+The Parties acknowledge that:
+
+- Monetary damages may be insufficient to remedy a breach of this Agreement
+- The Disclosing Party shall be entitled to seek injunctive relief in addition to any other remedies available at law or in equity
+- The prevailing party in any legal action arising from this Agreement shall be entitled to recover reasonable attorneys' fees and costs
+
+## 6. General provisions
+
+### 6.1 Governing law
+
+This Agreement shall be governed by and construed in accordance with the laws of the State of Delaware, without regard to its conflict of laws principles.
+
+### 6.2 Entire agreement
+
+This Agreement constitutes the entire understanding between the Parties with respect to the subject matter hereof and supersedes all prior negotiations, representations, and agreements.
+
+### 6.3 Amendment
+
+No modification of this Agreement shall be effective unless made in writing and signed by both Parties.
+
+### 6.4 Severability
+
+If any provision of this Agreement is held to be invalid or unenforceable, the remaining provisions shall continue in full force and effect.
+
+---
+
+**IN WITNESS WHEREOF**, the Parties have executed this Agreement as of the Effective Date.
+
+| | Meridian Dynamics Inc. | Orion Consulting Group LLC |
+|---|---|---|
+| Signature | _________________________ | _________________________ |
+| Name | Dr. Elena Vasquez | Marcus Chen |
+| Title | Chief Executive Officer | Managing Partner |
+| Date | January 15, 2026 | January 15, 2026 |

examples/collaboration/fastapi/assets/fake-nda.md

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import logging
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from fastapi import FastAPI, Query
+from fastapi.responses import FileResponse
+from superdoc import SuperDocClient
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+EXAMPLE_ROOT = Path(__file__).resolve().parent
+
+# Hardcoded demo config.
+DOC_PATH = EXAMPLE_ROOT / "assets" / "doc-template.docx"
+MARKDOWN_PATH = EXAMPLE_ROOT / "assets" / "fake-nda.md"
+DOWNLOAD_PATH = EXAMPLE_ROOT / ".superdoc-state" / "download.docx"
+
+COLLAB_PROVIDER = "y-websocket"
+COLLAB_URL = "ws://127.0.0.1:8081/v1/collaboration"
+COLLAB_DOCUMENT_ID = "superdoc-dev-room"
+COLLAB_SYNC_TIMEOUT_MS = 60_000
+
+# Hardcode local CLI + state to keep behavior deterministic for this repo example.
+# Using .ts means the SDK will execute via bun.
+CLI_BIN = REPO_ROOT / "apps" / "cli" / "src" / "index.ts"
+CLI_STATE_DIR = EXAMPLE_ROOT / ".superdoc-state"
+CLIENT_ENV = {
+    "SUPERDOC_CLI_BIN": str(CLI_BIN),
+    "SUPERDOC_CLI_STATE_DIR": str(CLI_STATE_DIR),
+}
+
+# Keep open timeout above sync timeout, and watchdog above open timeout.
+OPEN_TIMEOUT_MS = 90_000
+WATCHDOG_TIMEOUT_MS = 120_000
+
+app = FastAPI(title="SuperDoc FastAPI Collaboration Demo")
+logger = logging.getLogger("uvicorn.error")
+
+try:
+    SUPERDOC_SDK_VERSION = version("superdoc-sdk")
+except PackageNotFoundError:
+    SUPERDOC_SDK_VERSION = "not installed"
+
+
+@app.on_event("startup")
+def on_startup() -> None:
+    logger.info("superdoc-sdk version: %s", SUPERDOC_SDK_VERSION)
+
+    client = SuperDocClient(
+        env=CLIENT_ENV,
+        watchdog_timeout_ms=WATCHDOG_TIMEOUT_MS,
+    )
+
+    open_result = client.doc.open(
+        {
+            "doc": str(DOC_PATH),
+            "collaboration": {
+                "providerType": COLLAB_PROVIDER,
+                "url": COLLAB_URL,
+                "documentId": COLLAB_DOCUMENT_ID,
+                "syncTimeoutMs": COLLAB_SYNC_TIMEOUT_MS,
+            },
+        },
+        timeout_ms=OPEN_TIMEOUT_MS,
+    )
+    markdown_content = MARKDOWN_PATH.read_text(encoding="utf-8")
+    client.doc.insert({"value": markdown_content, "type": "markdown"})
+
+    app.state.client = client
+    app.state.open_result = open_result
+
+
+@app.on_event("shutdown")
+def on_shutdown() -> None:
+    client = app.state.client
+    client.doc.close({})
+    client.dispose()
+
+
+@app.get("/")
+def root() -> dict:
+    return {
+        "ok": True,
+        "openResult": app.state.open_result,
+        "collab": {
+            "providerType": COLLAB_PROVIDER,
+            "url": COLLAB_URL,
+            "documentId": COLLAB_DOCUMENT_ID,
+        },
+    }
+
+
+@app.get("/status")
+def status() -> dict:
+    return app.state.client.doc.status({})
+
+
+@app.get("/insert")
+def insert(text: str = Query(...)) -> dict:
+    return app.state.client.doc.insert({"value": text})
+
+
+@app.get("/download")
+def download() -> FileResponse:
+    DOWNLOAD_PATH.parent.mkdir(parents=True, exist_ok=True)
+    app.state.client.doc.save({"out": str(DOWNLOAD_PATH), "force": True})
+    return FileResponse(
+        path=str(DOWNLOAD_PATH),
+        media_type="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        filename=DOWNLOAD_PATH.name,
+    )

examples/collaboration/fastapi/main.py

@@ -0,0 +1,3 @@
+fastapi>=0.110.0
+uvicorn>=0.27.0
+superdoc-sdk==1.0.0a20

examples/collaboration/fastapi/requirements.txt

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
+cd "$ROOT_DIR"
+
+echo "[collab] starting server from packages/superdoc (same as pnpm dev:collab)"
+pnpm --prefix packages/superdoc run collab-server

examples/collaboration/fastapi/run-collab-server.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$ROOT_DIR/yjs-hub"
+
+if ! node -e "require.resolve('@y/hub/package.json')" >/dev/null 2>&1; then
+  pnpm install --ignore-workspace --lockfile=false
+fi
+
+USE_DOCKER=1
+if [ "${1:-}" = "--no-docker" ]; then
+  USE_DOCKER=0
+fi
+
+if [ "$USE_DOCKER" -eq 1 ]; then
+  if docker info >/dev/null 2>&1; then
+    pnpm run deps:up
+  else
+    echo "[yjs-hub] Docker daemon is not running."
+    echo "[yjs-hub] Start Docker Desktop and retry, or run: ./run-yjs-hub.sh --no-docker"
+    echo "[yjs-hub] In --no-docker mode you must provide local Redis (6379) and Postgres (5432/yhub)."
+    exit 1
+  fi
+fi
+
+pnpm run dev