[Docs][util] - Generate SDK documentation so its always up to date

docs/.gitignore

@@ -31,5 +31,6 @@ next-env.d.ts
 /content/api/
 /content/dashboard/
 /public/openapi/
+/public/sdk-docs/
 /openapi/
 

docs/code-examples/index.ts

@@ -3,6 +3,7 @@ import { apiKeysExamples } from './api-keys';
 import { conceptsExamples } from './concepts';
 import { customizationExamples } from './customization';
 import { paymentsExamples } from './payments';
+import { sdkEmailsExamples } from './sdk-emails';
 import { selfHostExamples } from './self-host';
 import { setupExamples } from './setup';
 import { viteExamples } from './vite-example';
@@ -12,6 +13,9 @@ const allExamples: Record<string, Record<string, Record<string, CodeExample[]>>>
   'apps': {...apiKeysExamples, ...paymentsExamples },
   'concepts': conceptsExamples,
   'getting-started': viteExamples,
+  'sdk': {
+    ...sdkEmailsExamples,
+  },
   'others': selfHostExamples,
   'customization': customizationExamples,
 };

docs/code-examples/sdk-emails.ts

@@ -0,0 +1,168 @@
+
+export const sdkEmailsExamples = {
+  'types/email': {
+    'send-html-email': [
+      {
+        language: 'JavaScript',
+        framework: 'Next.js',
+        variant: 'client' as const,
+        code: `// ⚠️ Email sending is not available on the client side
+// 
+// The sendEmail() method requires SECRET_SERVER_KEY and can only
+// be used from server-side code (Server Components, API routes, etc.)
+//
+// To send emails from a client component, create an API route that
+// calls stackServerApp.sendEmail() and call it from your client code.
+
+// Example: Call a server API route from client
+async function sendEmailFromClient() {
+  const response = await fetch('/api/send-email', {
+    method: 'POST',
+    body: JSON.stringify({
+      userIds: ['user-1', 'user-2'],
+      subject: 'Welcome!',
+      html: '<h1>Welcome!</h1>'
+    })
+  });
+
+  return response.json();
+}`,
+        highlightLanguage: 'typescript',
+        filename: 'app/components/send-email-button.tsx'
+      },
+      {
+        language: 'JavaScript',
+        framework: 'Next.js',
+        variant: 'server' as const,
+        code: `import { stackServerApp } from "@/stack";
+
+export default async function SendWelcomeEmail() {
+  const result = await stackServerApp.sendEmail({
+    userIds: ['user-1', 'user-2'],
+    subject: 'Welcome to our platform!',
+    html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
+  });
+
+  if (result.status === 'error') {
+    console.error('Failed to send email:', result.error);
+  }
+
+  return <div>Email sent!</div>;
+}`,
+        highlightLanguage: 'typescript',
+        filename: 'app/api/send-email/route.ts'
+      },
+      {
+        language: 'Python',
+        framework: 'Flask',
+        code: `import requests
+
+def send_welcome_email():
+    response = requests.post(
+        'https://api.stack-auth.com/api/v1/emails/send',
+        headers={
+            'x-stack-access-type': 'server',
+            'x-stack-project-id': stack_project_id,
+            'x-stack-secret-server-key': stack_secret_server_key,
+        },
+        json={
+            'user_ids': ['user-1', 'user-2'],
+            'subject': 'Welcome to our platform!',
+            'html': '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
+        }
+    )
+
+    return response.json()`,
+        highlightLanguage: 'python',
+        filename: 'send_email.py'
+      }
+    ],
+    'send-template-email': [
+      {
+        language: 'JavaScript',
+        framework: 'Next.js',
+        variant: 'client' as const,
+        code: `// ⚠️ Email sending is not available on the client side
+// 
+// The sendEmail() method requires SECRET_SERVER_KEY and can only
+// be used from server-side code (Server Components, API routes, etc.)
+//
+// To send emails from a client component, create an API route that
+// calls stackServerApp.sendEmail() and call it from your client code.
+
+// Example: Call a server API route from client
+async function sendTemplateEmailFromClient() {
+  const response = await fetch('/api/send-template-email', {
+    method: 'POST',
+    body: JSON.stringify({
+      userId: 'user-1',
+      templateId: 'welcome-template',
+      variables: { userName: 'John Doe' }
+    })
+  });
+
+  return response.json();
+}`,
+        highlightLanguage: 'typescript',
+        filename: 'app/components/send-email-button.tsx'
+      },
+      {
+        language: 'JavaScript',
+        framework: 'Next.js',
+        variant: 'server' as const,
+        code: `import { stackServerApp } from "@/stack";
+
+export default async function SendTemplateEmail() {
+  const result = await stackServerApp.sendEmail({
+    userIds: ['user-1'],
+    templateId: 'welcome-template',
+    variables: {
+      userName: 'John Doe',
+      activationUrl: 'https://app.com/activate/token123'
+    },
+    subject: 'Welcome aboard!',
+    notificationCategoryName: 'product_updates'
+  });
+
+  if (result.status === 'error') {
+    console.error('Failed to send email:', result.error);
+  }
+
+  return <div>Template email sent!</div>;
+}`,
+        highlightLanguage: 'typescript',
+        filename: 'app/api/send-template-email/route.ts'
+      },
+      {
+        language: 'Python',
+        framework: 'Flask',
+        code: `import requests
+
+def send_template_email():
+    response = requests.post(
+        'https://api.stack-auth.com/api/v1/emails/send',
+        headers={
+            'x-stack-access-type': 'server',
+            'x-stack-project-id': stack_project_id,
+            'x-stack-secret-server-key': stack_secret_server_key,
+        },
+        json={
+            'user_ids': ['user-1'],
+            'template_id': 'welcome-template',
+            'variables': {
+                'userName': 'John Doe',
+                'activationUrl': 'https://app.com/activate/token123'
+            },
+            'subject': 'Welcome aboard!',
+            'notification_category_name': 'product_updates'
+        }
+    )
+
+    return response.json()`,
+        highlightLanguage: 'python',
+        filename: 'send_template_email.py'
+      }
+    ]
+  }
+};
+

docs/content/docs/sdk/hooks/use-stack-app.mdx

@@ -4,7 +4,7 @@ title: useStackApp
 
 The `useStackApp` hook returns a `StackClientApp` object from the one that you provided in the [`StackProvider` component](../../components/stack-provider.mdx). If you want to learn more about the `StackClientApp` object, check out the [StackApp](../objects/stack-app.mdx) documentation.
 
-Example:
+## Usage Example
 
 ```jsx
 import { useStackApp } from "@stackframe/stack";
@@ -14,3 +14,7 @@ function MyComponent() {
   return <div>Sign In URL: {stackApp.urls.signIn}</div>;
 }
 ```
+
+## API Reference
+
+<HookFromJson hookName="useStackApp" />

docs/content/docs/sdk/hooks/use-user.mdx

@@ -5,3 +5,7 @@ title: useUser
 This standalone React hook is an alias for `useStackApp().useUser()`. It only exists for convenience; it does not have any additional functionality.
 
 For more information, please refer to the [documentation for `stackClientApp.useUser()`](../objects/stack-app.mdx#stackclientappuseuseroptions).
+
+## API Reference
+
+<HookFromJson hookName="useUser" />

docs/content/docs/sdk/index.mdx

@@ -17,7 +17,7 @@ export const sdkSections = [
     ]
   },
   {
-    title: "Users & user data",
+    title: "Users & User Data",
     items: [
       { name: "CurrentUser", href: "types/user#currentuser", icon: "type" },
       { name: "ServerUser", href: "types/user#serveruser", icon: "type" },
@@ -26,6 +26,14 @@ export const sdkSections = [
       { name: "ServerContactChannel", href: "types/contact-channel#servercontactchannel", icon: "type" },
     ]
   },
+  {
+    title: "Authentication",
+    items: [
+      { name: "OAuthProvider", href: "types/connected-account#oauthprovider", icon: "type" },
+      { name: "OAuthConnection", href: "types/connected-account#oauthconnection", icon: "type" },
+      { name: "ActiveSession", href: "types/connected-account#activesession", icon: "type" },
+    ]
+  },
   {
     title: "Teams",
     items: [
@@ -39,6 +47,15 @@ export const sdkSections = [
       { name: "ServerTeamProfile", href: "types/team-profile#serverteamprofile", icon: "type" },
     ]
   },
+  {
+    title: "API Keys",
+    items: [
+      { name: "UserApiKey", href: "types/api-key#userapikey", icon: "type" },
+      { name: "UserApiKeyFirstView", href: "types/api-key#userapikeyfirstview", icon: "type" },
+      { name: "TeamApiKey", href: "types/api-key#teamapikey", icon: "type" },
+      { name: "TeamApiKeyFirstView", href: "types/api-key#teamapikeyfirstview", icon: "type" },
+    ]
+  },
   {
     title: "Email",
     items: [

docs/content/docs/sdk/meta.json

@@ -11,15 +11,19 @@
     "types/user",
     "types/team",
     "types/team-user",
-    "types/team-permission",
     "types/team-profile",
     "types/contact-channel",
-    "types/email",
+    "types/team-permission",
     "types/api-key",
+    "types/item",
     "types/project",
     "types/connected-account",
-    "types/item",
-    "types/customer",
+    "---Mixins---",
+    "mixins/customer",
+    "mixins/auth",
+    "mixins/connection",
+    "---Shared Types---",
+    "types/email",
     "---Hooks---",
     "hooks/use-stack-app",
     "hooks/use-user"

docs/content/docs/sdk/mixins/auth.mdx

@@ -0,0 +1,11 @@
+---
+title: Auth
+full: true
+---
+
+The `Auth` mixin provides session and authentication functionality. It is included in `CurrentUser`.
+
+# `Auth`
+
+<TypeFromJson typeName="Auth" />
+

docs/content/docs/sdk/mixins/connection.mdx

@@ -0,0 +1,11 @@
+---
+title: Connection
+full: true
+---
+
+The `Connection` mixin provides the base interface for OAuth connections. It is included in `OAuthConnection`.
+
+# `Connection`
+
+<TypeFromJson typeName="Connection" />
+

docs/content/docs/sdk/mixins/customer.mdx

@@ -0,0 +1,11 @@
+---
+title: Customer
+full: true
+---
+
+The `Customer` mixin provides payment and billing functionality. It is included in both `CurrentUser` and `Team` types.
+
+# `Customer`
+
+<TypeFromJson typeName="Customer" />
+