feat(connectrpc): add API consumption docs for Cosmo ConnectRPC

docs/cli/router/plugin/build.mdx

@@ -48,7 +48,7 @@ If you only want to generate code but not compile the binary (useful when you're
 
 The build command will automatically check for and install the necessary toolchain (like protoc, protoc-gen-go, etc.) when required tools can't be found in the right version on your system. You can control this behavior with the `--skip-tools-installation` and `--force-tools-installation` flags.
 
-For debugging your plugin, use the `--debug` flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the [debugging guide](./debug) for detailed instructions.
+For debugging your plugin, use the `--debug` flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the [debugging guide](/router/gRPC/plugins/debugging) for detailed instructions.
 
 You can also install the dependencies manually and use an IDE with Go support. The following table shows the current versions and download links for the required tools:
 

docs/cli/router/plugin/test.mdx

@@ -43,7 +43,7 @@ Testing your plugin is an important step to ensure that your resolvers work corr
 
 The build command will automatically check for and install the necessary toolchain (like protoc, protoc-gen-go, etc.) when required tools can't be found in the right version on your system. You can control this behavior with the `--skip-tools-installation` and `--force-tools-installation` flags.
 
-For debugging your plugin, use the `--debug` flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the [debugging guide](./debug) for detailed instructions.
+For debugging your plugin, use the `--debug` flag to build with debug symbols. This enables debugging with tools like Delve, GoLand, or VS Code. See the [debugging guide](/router/gRPC/plugins/debugging) for detailed instructions.
 
 You can also install the dependencies manually and use an IDE with Go support. The following table shows the current versions and download links for the required tools:
 

docs/connect-rpc/consume-via-grpc.mdx

@@ -0,0 +1,74 @@
+---
+title: "Consume gRPC"
+description: "Interact with your API using high-performance gRPC clients and standard tooling like grpcurl." 
+icon: "tower-broadcast"
+---
+
+This page demonstrates how your platform enables API consumers to interact with the API using standard gRPC tooling.
+
+Platform teams can adapt the examples on this page when creating consumer-facing documentation to ensure a consistent and supported API consumption experience.
+
+---
+
+For internal microservices, backend systems, or high-performance mobile applications, consumers can interact with the API using the binary gRPC protocol over HTTP/2.
+
+## Prerequisites
+
+To consume the API via standard gRPC clients, consumers need two things provided by the platform team:
+
+1. Connection Details: The host and port where the router's ConnectRPC server is listening (e.g., localhost:5026).
+
+2. Service Definitions: The service.proto file generated during the build step. This file is required to define the available services, methods, and message structures for binary serialization.
+
+## Ad-Hoc testing with `grpcurl`
+
+`grpcurl` is a widely used command-line tool that lets you interact with gRPC servers, similar to how `curl` works for HTTP. 
+It is excellent for testing and debugging without generating code.
+
+### Command structure
+
+To make a request, you need to point `grpcurl` to your local `.proto` definition file, specify the plaintext flag (unless TLS is configured), provide the request data as JSON, and specify the target endpoint and fully qualified method name.
+
+In production environments, TLS is typically enabled and the `-plaintext` flag should be omitted.
+
+```bash
+grpcurl -plaintext \
+  -proto <path_to_service.proto> \
+  -d '<json_request_body>' \
+  <host>:<port> \
+  <package_name>.<ServiceName>/<MethodName>
+```
+
+## Examples
+
+The following examples assume the router is listening locally on port `5026` and the proto definitions are available in a local `./services/service.proto` file.
+
+### GetEmployeeById
+
+Retrieve an employee by their ID.
+
+```bash
+grpcurl -plaintext \
+  -proto ./services/service.proto \
+  -d '{"id": 1}' \
+  localhost:5026 \
+  employees.v1.HrService/GetEmployeeById
+```
+
+### UpdateEmployeeMood
+
+Update data on the server.
+
+```bash
+grpcurl -plaintext \
+  -proto ./services/service.proto \
+  -d '{"id": 1, "mood": "MOOD_HAPPY"}' \
+  localhost:5026 \
+  employees.v1.HrService/UpdateEmployeeMood
+```
+
+## Programmatic gRPC Clients
+
+While `grpcurl` is useful for testing, nearly every major programming language has robust library support for gRPC. Consumers can use standard `protoc` code generation tools against the provided `service.proto` file to build high-performance, typed clients for backend services.
+
+<Note> For the best developer experience in languages like TypeScript, Go, and Kotlin, we recommend using the pre-generated [SDKs](/connect-rpc/consume-via-sdks) instead of raw gRPC clients. </Note>

docs/connect-rpc/consume-via-rest-openapi.mdx

@@ -0,0 +1,102 @@
+---
+title: "Consume REST / OpenAPI"
+description: "Interact with your API using standard HTTP/JSON requests, suitable for standard clients like cURL, Postman, or browsers." 
+icon: "arrow-right-arrow-left"
+---
+
+This page demonstrates how your platform enables API consumers to interact with the API using standard HTTP tooling and OpenAPI specifications. 
+
+Platform teams can adapt the examples on this page when creating consumer-facing documentation to ensure a consistent and supported API consumption experience.
+
+Every GraphQL operation defined in your contract is automatically exposed as a standard HTTP endpoint supporting JSON encoding. 
+This allows any HTTP client to interact with your API without needing specific gRPC or GraphQL knowledge.
+
+## OpenAPI Specification
+
+If your platform team has generated an OpenAPI specification (e.g. `service.openapi.yaml`) as part of the build process, you can import it into tools like Swagger UI, Redoc, or Postman to explore the API interactively and see the exact request and response contracts.
+
+To learn how to generate the OpenAPI specification file, see [Generate & Distribute SDKs](/connect-rpc/produce-generate-distribute-sdks).
+
+## HTTP POST requests
+
+The standard method for calling any RPC method (both Queries and Mutations) is via an HTTP POST request with a JSON body.
+
+### Required Headers
+
+When making a `POST` request, you must include the following headers to indicate you are using the Connect protocol with JSON:
+
+- `Content-Type: application/json`
+
+- `Connect-Protocol-Version: 1`
+
+### Endpoint URL Structure
+
+The URL structure follows the pattern: `http(s)://<host>:<port>/<package>.<Service>/<Method>`
+
+For example: `http://localhost:5026/employees.v1.HrService/GetEmployeeById`
+
+### Examples
+
+#### Query with Arguments (POST)
+
+Retrieve an employee by ID. The arguments are passed as a JSON object in the request body.
+
+```bash
+curl -X POST http://localhost:5026/employees.v1.HrService/GetEmployeeById \
+  -H "Content-Type: application/json" \
+  -H "Connect-Protocol-Version: 1" \
+  -d '{"id": 1}'
+```
+
+#### Mutation (POST)
+
+Mutations — operations that modify data and have side effects — must use HTTP POST.
+
+```bash
+curl -X POST http://localhost:5026/employees.v1.HrService/UpdateEmployeeMood \
+  -H "Content-Type: application/json" \
+  -H "Connect-Protocol-Version: 1" \
+  -d '{"id": 1, "mood": "MOOD_HAPPY"}'
+```
+
+### HTTP GET Requests (Caching)
+
+GraphQL Query operations are marked as idempotent (`NO_SIDE_EFFECTS`) in the generated protocol buffers. This enables them to be called via HTTP GET requests.
+
+Using GET is highly recommended for read-only operations because it allows responses to be cached by standard CDNs and browser caches, significantly improving performance.
+
+#### Constructing the GET request
+
+Since GET requests do not have a body, arguments must be passed via query parameters. The request requires three specific parameters:
+
+- `connect=v1`: Specifies the protocol version.
+- `encoding=json`: Specifies the format of the message data.
+- `message={...}`: A URL-encoded JSON object containing the arguments.
+
+These parameters are required by the Connect protocol when using HTTP GET with JSON encoding.
+
+### Examples
+
+#### Query without arguments (GET)
+
+Retrieve all employees. The message is an empty JSON object `{}`.
+
+```bash
+curl --get \
+  --data-urlencode 'encoding=json' \
+  --data-urlencode 'message={}' \
+  --data-urlencode 'connect=v1' \
+  http://localhost:5026/employees.v1.HrService/GetEmployees
+```
+
+#### Query with arguments (GET)
+
+Retrieve an employee by ID. The message contains the arguments `{"id": 1}`.
+
+```bash
+curl --get \
+  --data-urlencode 'encoding=json' \
+  --data-urlencode 'message={"id": 1}' \
+  --data-urlencode 'connect=v1' \
+  http://localhost:5026/employees.v1.HrService/GetEmployeeById
+```

docs/connect-rpc/consume-via-sdks.mdx

@@ -0,0 +1,111 @@
+---
+title: "Consume SDKs"
+description: "Learn how to install and use the pre-generated, type-safe client libraries for TypeScript and Go"
+icon: "brackets-curly"
+---
+
+This page demonstrates the developer experience your platform team enables for API consumers using generated SDKs.
+
+Platform teams can adapt the examples on this page when creating consumer-facing documentation to ensure a consistent and supported API consumption experience.
+
+Once your platform team has generated and distributed the client SDKs, consuming the API is straightforward.
+
+You do not need to deal with GraphQL queries, Protocol Buffer definitions, or generation tooling. You simply install a library and interact with strongly typed objects and methods native to your programming language.
+
+This guide assumes you have been provided with the package name or repository URL for the generated SDKs.
+
+<Note>
+The examples below demonstrate TypeScript and Go SDKs. ConnectRPC supports many other languages including Python, Swift, Kotlin, and more. For a complete list of supported languages and their SDKs, see the [official Buf documentation](https://buf.build/docs/bsr/generated-sdks/#supported-languages).
+</Note>
+
+## TypeScript / JavaScript example
+
+The generated TypeScript client provides full type safety for requests and responses, along with autocomplete in your IDE.
+
+### 1. Installation
+
+Install the generated SDK package provided by your platform team, along with the required Connect runtime libraries.
+
+Note: Replace `@my-org/sdk` with the actual package name provided by your team.
+
+```bash
+npm install @my-org/sdk @connectrpc/connect @connectrpc/connect-web
+```
+
+### 2. Usage Example
+
+To make a request, you create a transport (configuring the base URL) and then instantiate the client for the desired service.
+
+```ts
+import { createPromiseClient } from "@connectrpc/connect";
+import { createConnectTransport } from "@connectrpc/connect-web";
+// Import the service definition from your generated SDK package
+import { HrService } from "@my-org/sdk/employees/v1/service_connect";
+
+const transport = createConnectTransport({
+  baseUrl: "http://localhost:5026",
+});
+
+const client = createPromiseClient(HrService, transport);
+
+async function fetchEmployee() {
+  // Request and response objects are fully typed
+  const response = await client.getEmployeeById({ id: 1 });
+  console.log(`Fetched employee: ${response.employee?.details?.forename}`);
+}
+
+fetchEmployee();
+```
+
+## Go example
+
+The generated Go SDK provides idiomatic Go structs and interfaces for interacting with the API.
+
+### 1. Installation
+
+Download the generated Go module provided by your platform team, along with the required Connect runtime.
+
+Note: Replace `github.com/my-org/sdk` with the actual module path provided by your team.
+
+```bash
+go get github.com/my-org/sdk
+```
+
+### 2. Usage Example
+
+Instantiate the service client using a standard HTTP client and the base URL of the router.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+    "net/http"
+
+    "connectrpc.com/connect"
+    // Import the generated packages from your SDK module
+    employeesv1 "github.com/my-org/sdk/gen/go/employees/v1"
+    "github.com/my-org/sdk/gen/go/employees/v1/employeesv1connect"
+)
+
+func main() {
+    client := employeesv1connect.NewHrServiceClient(
+        http.DefaultClient,
+        "http://localhost:5026",
+    )
+
+    req := connect.NewRequest(&employeesv1.GetEmployeeByIdRequest{
+        Id: 1,
+    })
+
+    res, err := client.GetEmployeeById(context.Background(), req)
+    if err != nil {
+        log.Fatal(err)
+    }
+
+    // Response data is strongly typed
+    fmt.Printf("Fetched employee: %s\n", res.Msg.Employee.Details.Forename)
+}
+```