From 764c31f736592647d70adea2ee87d7cecce50b28 Mon Sep 17 00:00:00 2001
From: Dion Low <dion@withampersand.com>
Date: Thu, 24 Jul 2025 14:14:29 -0700
Subject: [PATCH] docs: move AmpersandContextProvider README to root

---
 README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/README.md b/README.md
index a4e075116..9dde00503 100644
--- a/README.md
+++ b/README.md
@@ -96,3 +96,97 @@ To read this license, please see [LICENSE.md](https://github.com/amp-labs/react/
 ## Local Development
 
 Please see [CONTRIBUTING.md](https://github.com/amp-labs/react/blob/main/CONTRIBUTING.md).
+
+# AmpersandProvider with JWT Token Support
+
+The `AmpersandProvider` now supports both API key and JWT token authentication methods.
+
+## Usage
+
+### API Key Authentication (Existing)
+
+```tsx
+import { AmpersandProvider } from './AmpersandContextProvider';
+
+function App() {
+  return (
+    <AmpersandProvider
+      options={{
+        apiKey: "your-api-key-here",
+        project: "your-project-id"
+      }}
+    >
+      {/* Your app components */}
+    </AmpersandProvider>
+  );
+}
+```
+
+### JWT Token Authentication (New)
+
+```tsx
+import { AmpersandProvider } from './AmpersandContextProvider';
+
+function App() {
+  const getToken = async (consumerRef: string, groupRef: string): Promise<string> => {
+    // Your custom token retrieval logic here
+    // This could involve calling your auth service, checking sessionStorage, etc.
+    const response = await fetch('/api/auth/token', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ consumerRef, groupRef }),
+    });
+    
+    const data = await response.json();
+    return data.token;
+  };
+
+  return (
+    <AmpersandProvider
+      options={{
+        getToken,
+        project: "your-project-id"
+      }}
+    >
+      {/* Your app components */}
+    </AmpersandProvider>
+  );
+}
+```
+
+## Features
+
+### JWT Token Caching
+
+The JWT token provider automatically caches tokens in both memory and sessionStorage:
+
+- **Memory Cache**: Fast access for the current session
+- **sessionStorage**: Persistence across browser tabs/windows within the same session
+- **Automatic Expiration**: Tokens are automatically refreshed when they expire
+- **Cache Key**: Tokens are cached using the pattern `{consumerRef}:{groupRef}`
+
+### Authentication Methods
+
+The provider supports two mutually exclusive authentication methods:
+
+1. **API Key**: Traditional API key authentication
+2. **JWT Token**: Dynamic token retrieval with caching
+
+You cannot use both methods simultaneously - the provider will throw an error if both `apiKey` and `getToken` are provided.
+
+### Error Handling
+
+- If neither `apiKey` nor `getToken` is provided, the provider will throw an error
+- If both are provided, the provider will throw an error
+- JWT token retrieval failures are properly handled and logged
+
+## API Service Integration
+
+The `useAPI` hook automatically detects which authentication method is available and configures the API service accordingly:
+
+- **API Key**: Uses `X-Api-Key` header
+- **JWT Token**: Uses `Authorization: Bearer {token}` header
+
+The API service will automatically retrieve fresh tokens when needed, handling the caching and refresh logic transparently.
\ No newline at end of file