From 3851b6c47855a7a6116281458273e6502e10f303 Mon Sep 17 00:00:00 2001
From: Henrik Jess Nielsen <lrihni@egmont.com>
Date: Sat, 23 May 2026 01:40:43 +0200
Subject: [PATCH] docs: add docstrings with Tink API links to all demo step
 handlers

---
 src/routes/demo.py | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/src/routes/demo.py b/src/routes/demo.py
index ee764c9..dfc8ffd 100644
--- a/src/routes/demo.py
+++ b/src/routes/demo.py
@@ -130,6 +130,11 @@ async def debug_session(request: Request):
 
 @router.get("/demo/step/1", response_class=HTMLResponse)
 async def step1(request: Request):
+    """
+    Step 1: Client Credentials authentication.
+    Fetches an app-level token with scope 'user:create,authorization:grant'.
+    Docs: https://docs.tink.com/api#connectivity/oauth/create-an-oauth-token
+    """
     sess = _session(request)
     client = _client(log_cb=_logger(sess))
     s = get_settings()
@@ -169,6 +174,10 @@ async def step1(request: Request):
 
 @router.get("/demo/step/2", response_class=HTMLResponse)
 async def step2_get(request: Request):
+    """
+    Step 2 (GET): Render user creation form.
+    Shows existing user if already created in this session.
+    """
     sess = _session(request)
     s = get_settings()
     app_token = _load_token(sess, "app_token")
@@ -196,6 +205,12 @@ async def step2_get(request: Request):
 async def step2_post(request: Request,
                      customer_name: str = Form(default=""),
                      market: str = Form(default="DK")):
+    """
+    Step 2 (POST): Create a Tink user tied to a customer reference.
+    external_user_id is built from the customer name + random hex suffix to ensure uniqueness.
+    Tink returns a user_id (UUID) that is stored in session for subsequent calls.
+    Docs: https://docs.tink.com/api#user/create-user
+    """
     sess = _session(request)
     s = get_settings()
     app_token = _load_token(sess, "app_token")
@@ -259,6 +274,13 @@ CONSOLE_CALLBACK = "https://console.tink.com/callback"
 
 @router.get("/demo/step/3", response_class=HTMLResponse)
 async def step3_get(request: Request):
+    """
+    Step 3: Bank connection via Tink Link.
+    Calls authorization-grant/delegate to get a one-time code, then builds the
+    Tink Link URL that redirects the user to select and log into their bank.
+    After successful bank login, Tink redirects back to /callback with an auth code.
+    Docs: https://docs.tink.com/resources/tink-link/tink-link-web-permanent-users
+    """
     sess = _session(request)
     s = get_settings()
     client = _client(log_cb=_logger(sess))
@@ -452,6 +474,11 @@ async def tink_callback(request: Request, code: Optional[str] = None,
 
 @router.get("/demo/step/4", response_class=HTMLResponse)
 async def step4(request: Request):
+    """
+    Step 4: List accounts (v2 endpoint).
+    Requires a user_token from the callback. Falls back to mock data if demo_mode is set.
+    Docs: https://docs.tink.com/api#account-service-v2/account/list-accounts
+    """
     sess = _session(request)
     s = get_settings()
     user_token = _load_token(sess, "user_token")
@@ -501,6 +528,11 @@ async def step4(request: Request):
 
 @router.get("/demo/step/5", response_class=HTMLResponse)
 async def step5(request: Request, account_id: Optional[str] = None):
+    """
+    Step 5: List transactions (v2 endpoint), optionally filtered by account_id.
+    Uses cursor-based pagination via nextPageToken.
+    Docs: https://docs.tink.com/api#transaction-service-v2/transaction/list-transactions
+    """
     sess = _session(request)
     s = get_settings()
     user_token = _load_token(sess, "user_token")
@@ -549,6 +581,12 @@ async def step5(request: Request, account_id: Optional[str] = None):
 
 @router.get("/demo/step/6", response_class=HTMLResponse)
 async def step6(request: Request):
+    """
+    Step 6: Webhooks — list existing and register a new endpoint.
+    Demonstrates real-time event delivery (account updates, new transactions).
+    Webhook receiver is at /webhooks/tink — logs payloads to api_log.
+    Docs: https://docs.tink.com/api#webhook/create-webhook-endpoint
+    """
     sess = _session(request)
     s = get_settings()
     is_demo = sess.get("demo_mode") or s.demo_mode