Finish writing Zendesk auth provider docs

Author: EricGustin

Makefile

@@ -15,3 +15,16 @@ build: ## Build the docs site
 
 run: ## Run the docs site locally
 	@pnpm dev
+
+ruin:
+	@echo "\033[31m\033[1m💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m🔥  With but a single command, the realm   🔥\033[0m"
+	@echo "\033[31m\033[1m🔥  of order shall collapse into chaos.    🔥\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m⚡  Beware, for what is ruined today may   ⚡\033[0m"
+	@echo "\033[31m\033[1m⚡  take an eternity to rebuild.           ⚡\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m🎃      - The Elders of Makefile           🎃\033[0m"
+	@echo "\033[31m\033[1m👻                                          👻\033[0m"
+	@echo "\033[31m\033[1m💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️💀☠️\033[0m"

examples/code/integrations/zendesk/custom_auth.js

@@ -0,0 +1,23 @@
+import { Arcade } from "@arcadeai/arcadejs";
+
+const client = new Arcade(); // Automatically finds the `ARCADE_API_KEY` env variable
+
+const userId = "{arcade_user_id}";
+
+// Start the authorization process
+let authResponse = await client.auth.start(userId, {
+  provider: "zendesk",
+  scopes: ["read_account"],
+});
+
+if (authResponse.status !== "completed") {
+  console.log("Please complete the authorization challenge in your browser:");
+  console.log(authResponse.url);
+}
+
+// Wait for the authorization to complete
+authResponse = await client.auth.waitForCompletion(authResponse);
+
+const token = authResponse.context.token;
+
+// Do something interesting with the token...

examples/code/integrations/zendesk/custom_auth.py

@@ -0,0 +1,21 @@
+from arcadepy import Arcade
+
+client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
+
+# Start the authorization process
+auth_response = client.auth.start(
+    user_id="{arcade_user_id}",
+    provider="zendesk",
+    scopes=["read_account"],
+)
+
+if auth_response.status != "completed":
+    print("Please complete the authorization challenge in your browser:")
+    print(auth_response.url)
+
+# Wait for the authorization to complete
+auth_response = client.auth.wait_for_completion(auth_response)
+
+token = auth_response.context.token
+
+# Do something interesting with the token...

examples/code/integrations/zendesk/custom_tool.py

@@ -0,0 +1,31 @@
+from typing import Annotated, Any
+
+from arcade_tdk import ToolContext, tool
+from arcade_tdk.auth import OAuth2
+
+import httpx
+
+
+@tool(
+  requires_auth=OAuth2(id="zendesk", scopes=["read"]),
+  requires_secrets=["ZENDESK_SUBDOMAIN"],
+)
+async def get_tickets(
+  context: ToolContext
+) -> Annotated[dict[str, Any], "Recent tickets from Zendesk"]:
+    """Get recent tickets from Zendesk including basic ticket information"""
+    token = context.get_auth_token_or_empty()
+    subdomain = context.get_secret("ZENDESK_SUBDOMAIN")
+    url = f"https://{subdomain}.zendesk.com/api/v2/tickets.json"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(url, headers=headers)
+        resp.raise_for_status()
+        data = resp.json()
+
+        return {"tickets": data}

pages/home/auth-providers/zendesk.mdx

@@ -17,16 +17,17 @@ This page describes how to use and configure Zendesk auth with Arcade.
 This auth provider is used by:
 
 - The [Arcade Zendesk toolkit](/toolkits/customer-support/zendesk), which provides pre-built tools for interacting with Zendesk services
-- Your [app code](#calling-zendesk-apis-directly) that needs to call Zendesk APIs
-- Or, your [custom tools](#create-your-own-zendesk-tools) that need to call Zendesk APIs
+- Your [app code](#using-zendesk-auth-in-app-code) that needs to call Zendesk APIs
+- Or, your [custom tools](#using-zendesk-auth-in-custom-tools) that need to call Zendesk APIs
 
 ## Create a Zendesk app
 
-To create a Zendesk app, there are two important guides from Zendesk that you can follow:
+### Additional guides
+The following two guides from Zendesk will be helpful additional information as you progress through this guide:
 1. [Using OAuth authentication with your application](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application)
 2. [Set up a global OAuth client](https://developer.zendesk.com/documentation/marketplace/building-a-marketplace-app/set-up-a-global-oauth-client/)
 
-For a more streamlined set of instructions, follow the steps below:
+### Creating a Zendesk app for Arcade
 1. Create your Organization in the [Zendesk Marketplace portal](https://apps.zendesk.com/).
 1. Create a Zendesk support account at https://www.zendesk.com/login . If you need a global OAuth client, then the subdomain MUST begin with "d3v-". You will need a global OAuth client if your app will use integrations/tools for multiple customers with their own Zendesk instances (multiple subdomains).
 1. In [the Admin Center](https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb), click "Apps and integrations" in the sidebar, then select APIs > OAuth clients > Add OAuth client.
@@ -156,15 +157,15 @@ Use `client.auth.start()` to get a user token for Zendesk APIs:
 <Tabs items={["Python", "JavaScript"]} storageKey="preferredLanguage">
 <Tabs.Tab>
 
-```python file=<rootDir>/examples/code/integrations/zendesk/custom_auth.py {8-12}
+```python file=<rootDir>/examples/code/integrations/zendesk/custom_auth.py {6-10}
 
 ```
 
 </Tabs.Tab>
 
 <Tabs.Tab>
 
-```javascript file=<rootDir>/examples/code/integrations/zendesk/custom_auth.js {8-10}
+```javascript file=<rootDir>/examples/code/integrations/zendesk/custom_auth.js {8-11}
 
 ```
 
@@ -174,10 +175,10 @@ Use `client.auth.start()` to get a user token for Zendesk APIs:
 
 ## Using Zendesk auth in custom tools
 
-You can author your own [custom tools](/home/build-tools/create-a-toolkit) that interact with Zendesk APIs.
+If the [Arcade Zendesk toolkit](/toolkits/customer-support/zendesk) does not meet your needs, you can author your own [custom tools](/home/build-tools/create-a-toolkit) that interact with Zendesk APIs.
 
 Use the `OAuth2()` auth class to specify that a tool requires authorization with Zendesk. The `context.authorization.token` field will be automatically populated with the user's Zendesk token:
 
-```python file=<rootDir>/examples/code/integrations/zendesk/custom_tool.py {5-6,9-13,20}
+```python file=<rootDir>/examples/code/integrations/zendesk/custom_tool.py
 
 ```