docs: update controller documentation to reflect current interface by tarrencev · Pull Request #41 · cartridge-gg/docs

tarrencev · 2025-06-17T18:14:13Z

Updates the controller documentation to reflect the current state of the cartridge-gg/controller repository, focusing on the packages/controller package interface.

Changes

Improve getting started guide with Quick Start section and better examples
Update configuration documentation with current ControllerOptions interface
Enhance session documentation with clearer explanations of how sessions work
Fix consistency issues in session policy structure across examples
Update Starknet React integration to use current best practices
Add configuration examples with session policies for gaming use cases
Improve overview to better highlight current capabilities

Closes #40

Generated with Claude Code

- Improve getting started guide with Quick Start section and better examples - Update configuration documentation with current ControllerOptions interface - Enhance session documentation with clearer explanations of how sessions work - Fix consistency issues in session policy structure across examples - Update Starknet React integration to use current best practices - Add configuration examples with session policies for gaming use cases - Improve overview to better highlight current capabilities Co-authored-by: Tarrence van As <tarrencev@users.noreply.github.com>

vercel · 2025-06-17T18:14:18Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	Jun 17, 2025 6:25pm

claude · 2025-06-17T18:14:28Z

Claude finished @tarrencev's task —— View job

PR Review: Controller Documentation Updates

This PR successfully updates the controller documentation to reflect the current interface. The changes improve clarity, accuracy, and provide better examples across all integration patterns.

Review Summary:

✅ Strengths

Documentation Quality & Structure:

Excellent progressive disclosure in getting-started.mdx - moves from simple to complex examples
Well-organized ControllerOptions interface in configuration.md with clear categorization
Comprehensive examples across multiple frameworks (React, Svelte, Telegram)
Good use of TypeScript types throughout with proper commenting

Code Examples & Best Practices:

Examples follow current best practices (e.g., creating connectors outside components in getting-started.mdx:116)
Proper error handling demonstrated in svelte.md:77-80 and telegram.md:139-153
Good separation of configuration from implementation across all examples
Consistent use of modern async/await patterns

Security & Performance Considerations:

Session policies are well-documented with clear permission boundaries (sessions.md:70-119)
Proper RPC endpoint configuration for different networks
Good explanation of gasless transactions and paymaster integration
WebAssembly configuration properly documented for Next.js (telegram.md:160-205)

⚠️ Areas for Improvement

Minor Issues:

svelte.md:188-192 - Truncated policies example:
```
policies: [
    // ... your policies here
]
```
Should show the correct policies object structure instead of array format.
getting-started.mdx:177 - Missing link reference:
```
- Configure [Paymaster](/controller/configuration.md)
```
The configuration page doesn't contain paymaster-specific documentation.
Consistency in RPC URLs:
- Some examples use https://api.cartridge.gg/x/starknet/sepolia
- Others use https://api.cartridge.gg/x/starknet/mainnet
- Consider standardizing on Sepolia for examples unless mainnet is specifically needed

Suggestions for Enhancement:

Error Handling: While telegram.md shows good error handling patterns, consider adding similar patterns to the basic examples in getting-started.mdx
TypeScript Best Practices: The examples could benefit from more explicit typing, especially in the Svelte examples where any could be avoided
Testing Guidance: Consider adding a brief section about testing applications that use the Controller

🔍 Technical Observations

Session Policies: The updated policy structure is well-documented and the examples are realistic
Framework Integration: All integration patterns look correct and follow framework best practices
Configuration Options: The new ControllerOptions interface is well-structured and documented

✅ Security Assessment

No security concerns identified
Session policies properly scoped and explained
Good explanation of permission boundaries
Proper handling of sensitive operations (private keys, session management)

Overall Assessment

This is a high-quality documentation update that significantly improves the developer experience. The changes are well-structured, examples are practical, and the progressive complexity approach will help both new and experienced developers.

Recommendation: Approve with minor fixes ✅

The identified issues are minor and don't affect the core quality of the documentation. The improvements far outweigh any concerns.

tarrencev

@claude address these comments. There is no rpc config param but there is an optional chains param. chains can be used to provide custom rpc endpoints for slot katana instances

tarrencev · 2025-06-17T18:14:58Z

src/pages/controller/configuration.md

-    defaultChainId: constants.StarknetChainId.SN_SEPOLIA,
-
+    // RPC configuration
+    rpc?: string;  // RPC endpoint URL (defaults to Cartridge RPC)


Should remain as:

chains?: Chain[]; where Chain is

export type Chain = { rpcUrl: string; };

tarrencev · 2025-06-17T18:15:16Z

src/pages/controller/configuration.md

+    rpc?: string;  // RPC endpoint URL (defaults to Cartridge RPC)
+
+    // Chain configuration
+    chainId?: string;  // Chain ID (defaults to Sepolia)


hex encoded

tarrencev · 2025-06-17T18:15:43Z

src/pages/controller/configuration.md

+    // Advanced options
+    redirectUrl?: string;  // Custom redirect URL after session creation


not an option

Suggested change

// Advanced options

redirectUrl?: string; // Custom redirect URL after session creation

tarrencev · 2025-06-17T18:17:28Z

src/pages/controller/examples/svelte.md

-    ],
-    rpc: "https://api.cartridge.gg/x/starknet/mainnet" // sepolia, mainnet, or slot
+    },
+    rpc: "https://api.cartridge.gg/x/starknet/sepolia" // sepolia or mainnet


Suggested change

rpc: "https://api.cartridge.gg/x/starknet/sepolia" // sepolia or mainnet

tarrencev · 2025-06-17T18:18:36Z

src/pages/controller/getting-started.mdx

+const controller = new Controller({
+  rpc: "https://api.cartridge.gg/x/starknet/sepolia", // or mainnet
+});


Suggested change

const controller = new Controller({

rpc: "https://api.cartridge.gg/x/starknet/sepolia", // or mainnet

});

const controller = new Controller();

tarrencev · 2025-06-17T18:19:05Z

src/pages/controller/getting-started.mdx

+const connector = new ControllerConnector({
+  rpc: "https://api.cartridge.gg/x/starknet/sepolia",
+});


Suggested change

const connector = new ControllerConnector({

rpc: "https://api.cartridge.gg/x/starknet/sepolia",

});

const connector = new ControllerConnector();

claude · 2025-06-17T18:21:37Z

Claude finished @tarrencev's task —— View job

✅ PR Review Comments Addressed

Successfully addressed all review comments about configuration parameters and code examples.

Completed Tasks:

Read repository setup instructions (CLAUDE.md)
Read current state of affected files
Fix configuration.md - correct chains parameter documentation
Fix configuration.md - change to "hex encoded" on line 18
Fix configuration.md - remove incorrect option on line 29
Fix svelte.md - address suggestion on line 60
Fix getting-started.mdx - correct Controller instantiation on line 56
Fix getting-started.mdx - correct ControllerConnector instantiation on line 118
Commit changes to the PR branch

Summary of Changes:

✅ configuration.md:

Replaced rpc?: string with chains?: Chain[] and added Chain type definition
Updated chainId comment to "hex encoded"
Removed redirectUrl option
Updated category descriptions to remove "RPC &" prefix

✅ svelte.md:

Removed rpc parameter from Controller instantiation on line 60

✅ getting-started.mdx:

Simplified Controller instantiation to new Controller() on line 56
Simplified ControllerConnector instantiation to new ControllerConnector() on line 118
Removed additional rpc parameter from session policies example

All changes have been committed to the PR branch as requested. The documentation now correctly reflects the chains parameter for custom RPC endpoints instead of the deprecated rpc parameter.

Commit: eda8ea0

- Replace rpc parameter with chains parameter in ControllerOptions - Add Chain type definition with rpcUrl property - Update chainId description to specify hex encoding - Remove redirectUrl option from ControllerOptions - Simplify Controller and ControllerConnector instantiation examples - Remove rpc parameters from all code examples Co-authored-by: Tarrence van As <tarrencev@users.noreply.github.com>

tarrencev commented Jun 17, 2025

View reviewed changes

vercel bot deployed to Preview June 17, 2025 18:25 View deployment

tarrencev merged commit c311719 into main Jun 17, 2025
1 of 2 checks passed

tarrencev deleted the claude/issue-40-20250617_175857 branch June 17, 2025 18:48

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: update controller documentation to reflect current interface#41

docs: update controller documentation to reflect current interface#41
tarrencev merged 2 commits intomainfrom
claude/issue-40-20250617_175857

tarrencev commented Jun 17, 2025

Uh oh!

vercel bot commented Jun 17, 2025 •

edited

Loading

Uh oh!

claude bot commented Jun 17, 2025 •

edited

Loading

Uh oh!

tarrencev left a comment

Uh oh!

tarrencev Jun 17, 2025

Uh oh!

tarrencev Jun 17, 2025

Uh oh!

tarrencev Jun 17, 2025

Uh oh!

tarrencev Jun 17, 2025

Uh oh!

tarrencev Jun 17, 2025

Uh oh!

tarrencev Jun 17, 2025

Uh oh!

claude bot commented Jun 17, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		// Advanced options
		redirectUrl?: string; // Custom redirect URL after session creation

Conversation

tarrencev commented Jun 17, 2025

Changes

Uh oh!

vercel bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review: Controller Documentation Updates

Review Summary:

✅ Strengths

⚠️ Areas for Improvement

🔍 Technical Observations

✅ Security Assessment

Overall Assessment

Uh oh!

tarrencev left a comment

Choose a reason for hiding this comment

Uh oh!

tarrencev Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

tarrencev Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

tarrencev Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

tarrencev Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

tarrencev Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

tarrencev Jun 17, 2025

Choose a reason for hiding this comment

Uh oh!

claude bot commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ PR Review Comments Addressed

Completed Tasks:

Summary of Changes:

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

vercel bot commented Jun 17, 2025 •

edited

Loading

claude bot commented Jun 17, 2025 •

edited

Loading

claude bot commented Jun 17, 2025 •

edited

Loading