feat: mocks target ClientInterface exclusively + SearchUsers + docs cleanup (#196)

* feat: generated mocks implement ClientInterface for non-streaming services

Generated Mock*Service types now satisfy both *Service and
*ServiceClientInterface for services without streaming methods.
This eliminates the need to hand-write verbose mock structs with
panic stubs for Close/Group/WithGroup when tests depend on the
client interface.

For streaming services the mock remains unchanged because Service
and ClientInterface have incompatible streaming method signatures.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: streaming service mocks target ClientInterface with client-side signatures

Streaming mocks (LimitOrderService, TransactionService) now use client-side
method signatures returning (StreamClient, error) instead of server-side
signatures accepting a stream parameter. All mocks uniformly implement
*ServiceClientInterface with Close(), Group(), and WithGroup() methods.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* update deps

* correct version specification

* chore: update release command and remove outdated hand-written TS docs

Add Step 6 to release command to merge the 5 auto-generated version-bump
PRs after deployment workflows complete. Remove obsolete CLAUDE.md guidance
about hand-written TypeScript client wrappers (all now auto-generated by
protoc-gen-meshts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: prettier formatting in ts-old groupHeaderInterceptor

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix versions

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: BRBussy

.claude/commands/release.md

@@ -93,12 +93,34 @@ Expected completion times:
 
 If any workflow fails, check logs with `gh run view <run-id> --log-failed` and fix.
 
-### Step 6: Report Results
+### Step 6: Merge Auto-Generated Version PRs
+
+After all workflows complete successfully, 5 auto-generated PRs will exist that bump version files back into master. Merge all of them:
+
+**Expected PRs (by branch name):**
+- `chore/pypi-version-update-$1` — updates `pyproject.toml`
+- `chore/maven-version-update-$1` — updates `java/pom.xml`
+- `chore/npm-ts-node-version-update-$1` — updates `ts-node/package.json`
+- `chore/npm-ts-web-version-update-$1` — updates `ts-web/package.json`
+- `chore/npm-ts-old-version-update-$1` — updates `ts-old/package.json`
+
+1. List PRs to confirm they all exist: `gh pr list --limit 10`
+2. Merge each PR and delete its branch:
+```bash
+gh pr merge chore/pypi-version-update-$1 --merge --delete-branch
+gh pr merge chore/maven-version-update-$1 --merge --delete-branch
+gh pr merge chore/npm-ts-node-version-update-$1 --merge --delete-branch
+gh pr merge chore/npm-ts-web-version-update-$1 --merge --delete-branch
+gh pr merge chore/npm-ts-old-version-update-$1 --merge --delete-branch
+```
+3. If any PR is missing, the corresponding workflow may still be running or may have failed — check `gh run list --limit 15`
+
+### Step 7: Report Results
 
 Show the user:
 1. All 8 releases created with links
 2. All workflow statuses (success/failure) - verify all triggered via `push` event
-3. List of auto-generated PRs to merge: `gh pr list --limit 10`
+3. All 5 version-bump PRs merged successfully
 
 ---
 

CLAUDE.md

@@ -380,31 +380,6 @@ Before testing, validate your development environment:
 - **Extension Tag Management**: Be careful with protobuf extension tag conflicts across option files
 - **Response Message Cleanup**: Remove unused response messages when methods return resources directly
 
-### TypeScript Hand-Written Code Maintenance
-- **Post-Generation Updates**: After running `./dev/tool.sh generate` or `./dev/tool.sh all`, hand-written TypeScript client wrappers may need updates:
-  - Method name changes: `get()` → `getResource()`, `create()` → `createResource()`
-  - Return type changes: Get/Create methods return resources directly, not response wrappers
-  - Import statement updates: Remove imports for deleted response message types
-  - Add imports for resource types (e.g., `import { Client } from "./client_pb"`)
-  - **Missing Method Detection**: Compare wrapper methods to generated service interface to ensure all RPC methods are exposed
-- **Breaking Change Detection**: TypeScript compilation errors after generation indicate needed updates:
-  - Missing exported members = removed response types that need import cleanup
-  - Missing properties on service clients = method name changes
-  - Use `yarn build` and `yarn lint` in `/ts` to validate all changes
-- **Hand-Written Client Pattern**: Client wrapper classes in `*_grpc_web.ts` files should:
-  - Mirror the generated gRPC service interface exactly
-  - Use consistent method naming with resource names included
-  - Return the same types as the generated service (resources directly for Get/Create)
-  - Maintain proper JSDoc documentation with updated parameter and return types
-  - Include ALL methods from the corresponding protobuf service definition
-- **Client Wrapper Validation Process**:
-  1. After protobuf changes, run `./dev/tool.sh all` to regenerate code
-  2. Check each `*_grpc_web.ts` file to ensure all service methods are wrapped
-  3. Update imports to include all required request/response types
-  4. Run `yarn build` and `yarn lint` in `/ts` to verify compilation
-  5. Look for methods in `service_grpc_web_pb.d.ts` that aren't in the wrapper client
-- **Orphaned File Cleanup**: Remove hand-written files when their corresponding proto services are deleted
-
 ## Protobuf Refactoring Best Practices
 
 ### Role and Method Type Management
@@ -419,14 +394,12 @@ Before testing, validate your development environment:
 1. Modify protobuf files in `/proto/` directory
 2. Run `buf lint` to validate changes
 3. Run `./dev/tool.sh all` to regenerate all client libraries
-4. Check TypeScript client wrappers for missing methods or imports
-5. Run language-specific tests and linting to verify correctness
+4. Run language-specific tests and linting to verify correctness
 
 ### Protobuf Syntax for Options
 
 When adding options to protobuf files, keep the following in mind:
 
 - **Option Syntax:** Custom options for services or methods should be declared directly. The correct syntax is `option (custom.option) = VALUE;` and not `option (custom.option) = { key: VALUE };`.
 - **Enum Scopes:** When referencing enums from an imported `.proto` file (like `method_type.proto` or `role.proto`), you should use the enum value directly (e.g., `METHOD_TYPE_READ`) without the fully qualified package path, as long as the necessary import statement is present.
-- **Option Scopes (`FileOptions` vs. `ServiceOptions`):** It's critical to apply options at the correct level. For example, `standard_roles` is a `FileOption` and must be declared at the top level of the file, not within a `service` definition, which uses `ServiceOptions`.
-- **TypeScript Wrapper Dependencies:** When adding new RPC methods, you must manually update any hand-written client wrappers. This includes not only adding the new client method but also importing the newly generated request/response message types (e.g., `GetApiUserByKeyHashRequest` from `service_pb.ts`).
+- **Option Scopes (`FileOptions` vs. `ServiceOptions`):** It's critical to apply options at the correct level. For example, `standard_roles` is a `FileOption` and must be declared at the top level of the file, not within a `service` definition, which uses `ServiceOptions`.

docs/docs/api-reference/iam/user/v1/service/search-users/example.go

@@ -0,0 +1,35 @@
+package main
+
+import (
+	"context"
+	"log"
+
+	userv1 "github.com/meshtrade/api/go/iam/user/v1"
+)
+
+func main() {
+	ctx := context.Background()
+
+	// Default configuration is used and credentials come from MESH_API_CREDENTIALS
+	// environment variable or default discovery methods. Zero config required
+	// unless you want custom configuration.
+	service, err := userv1.NewUserService()
+	if err != nil {
+		log.Fatalf("Failed to create service: %v", err)
+	}
+	defer service.Close()
+
+	// Create request with service-specific parameters
+	request := &userv1.SearchUsersRequest{
+		// FIXME: Populate service-specific request fields
+	}
+
+	// Call the SearchUsers method
+	response, err := service.SearchUsers(ctx, request)
+	if err != nil {
+		log.Fatalf("SearchUsers failed: %v", err)
+	}
+
+	// FIXME: Add relevant response object usage
+	log.Printf("SearchUsers successful: %+v", response)
+}

docs/docs/api-reference/iam/user/v1/service/search-users/example.java

@@ -0,0 +1,28 @@
+import co.meshtrade.api.iam.user.v1.UserService;
+import co.meshtrade.api.iam.user.v1.Service.SearchUsersRequest;
+import co.meshtrade.api.iam.user.v1.Service.SearchUsersResponse;
+
+import java.util.Optional;
+
+public class SearchUsersExample {
+    public static void main(String[] args) {
+        // Default configuration is used and credentials come from MESH_API_CREDENTIALS
+        // environment variable or default discovery methods. Zero config required
+        // unless you want custom configuration.
+        try (UserService service = new UserService()) {
+            // Create request with service-specific parameters
+            SearchUsersRequest request = SearchUsersRequest.newBuilder()
+                // FIXME: Populate service-specific request fields
+                .build();
+
+            // Call the SearchUsers method
+            SearchUsersResponse response = service.searchUsers(request, Optional.empty());
+
+            // FIXME: Add relevant response object usage
+            System.out.println("SearchUsers successful: " + response);
+        } catch (Exception e) {
+            System.err.println("SearchUsers failed: " + e.getMessage());
+            e.printStackTrace();
+        }
+    }
+}

docs/docs/api-reference/iam/user/v1/service/search-users/example.py

@@ -0,0 +1,27 @@
+from meshtrade.iam.user.v1 import (
+    SearchUsersRequest,
+    UserService,
+)
+
+
+def main():
+    # Default configuration is used and credentials come from MESH_API_CREDENTIALS
+    # environment variable or default discovery methods. Zero config required
+    # unless you want custom configuration.
+    service = UserService()
+
+    with service:
+        # Create request with service-specific parameters
+        request = SearchUsersRequest(
+            # FIXME: Populate service-specific request fields
+        )
+
+        # Call the SearchUsers method
+        response = service.search_users(request)
+
+        # FIXME: Add relevant response object usage
+        print("SearchUsers successful:", response)
+
+
+if __name__ == "__main__":
+    main()