feat: unified open entrypoint with auto-login and standalone support

[broody]

Description

This PR simplifies the user experience for interacting with Controller UI components by introducing a unified entrypoint and automatic authentication. Previously, users were required to be logged in before they could access specific UI pages like starter packs or settings.

Key Changes

• Unified open Entrypoint: Refactored the open method to be the single entrypoint for all UI actions, including both iframe-based pages and the standalone redirect flow.
  • Supported targets: settings, starterpack, profile, purchase-credits, execute, and standalone.
• Auto-Login (ensureConnected): Added logic to automatically trigger the connection flow if a user attempts to open a UI component while logged out. The iframe now remains open after a successful login to transition seamlessly to the requested page.
• Standalone Flow Integration: The legacy redirect-based open method has been made private (openStandalone) and is now accessed via open({ target: 'standalone' }).
• Refactored UI Methods: Updated openSettings, openStarterPack, openProfile, and others to be wrappers around the new unified open logic. These methods are now async and handle authentication automatically.
• Connector Enhancements: Exposed the unified open method in @cartridge/connector, along with shorthands for common UI actions.

Usage Comparison

1. Opening Settings

Previous way (requires user to be connected):

if (controller.isReady() && controller.address) {
  controller.openSettings();
}

New way (automatically handles login if needed):

await controller.open({ target: 'settings' });
// or via the updated shorthand
await controller.openSettings();

2. Opening a Starterpack

Previous way:

await controller.openStarterPack(1);

New way:

await controller.open({ target: 'starterpack', id: 1 });
// shorthand still works but now handles auto-login
await controller.openStarterPack(1);

3. Standalone Redirect Flow

Previous way:

controller.open({ redirectUrl: window.location.href });

New way:

await controller.open({ 
  target: 'standalone', 
  options: { redirectUrl: window.location.href } 
});

Impact

• Reduces the 'two-step' process (login then open) to a single step for end-users.
• Improves API consistency and type safety across the controller and connector packages.
• Provides a more extensible foundation for future UI components.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
controller-example-next	Ready	Preview	Feb 5, 2026 1:47am
keychain	Ready	Preview	Feb 5, 2026 1:47am
keychain-storybook	Ready	Preview	Feb 5, 2026 1:47am