feat: enhance ox optional dependency with proper error handling and utility functions

[Bvvvp009]

Summary

This PR enhances the existing optional ox dependency implementation by adding proper error handling, centralized utility functions, and improved documentation. While ox is already marked as optional in package.json, the code still directly imports it without graceful fallbacks.

Current State

The main repository already has ox marked as an optional peer dependency:

"peerDependencies": {
    "viem": "^2.28.1", 
    "ox": "^0.6.7"
},
"peerDependenciesMeta": {
    "ox": {
        "optional": true
    }
}

However, the codebase still directly imports ox in multiple files, which causes runtime errors when the package is not installed.

Problem

Even though ox is marked as optional, users still encounter confusing errors when trying to use WebAuthn functionality without having ox installed. The current implementation lacks:

• Proper error handling for missing ox package
• Centralized utility for optional imports
• Clear user guidance when ox is required
• Graceful degradation when WebAuthn features aren't needed

Solution

• Created a centralized utility module (packages/permissionless/utils/ox.ts) to handle optional imports with proper error handling
• Updated all files that import ox to use the new utility with clear error messages
• Enhanced documentation with installation instructions for WebAuthn functionality
• Fixed Windows build script compatibility

Changes Made

New Files

• packages/permissionless/utils/ox.ts - Centralized utility for optional ox imports with comprehensive error handling

Enhanced Files

• packages/permissionless/README.md - Added "Optional Dependencies" section with clear installation instructions
• packages/permissionless/utils/index.ts - Exported new ox utility functions

Updated Files Using ox (now with proper error handling)

• packages/permissionless/accounts/kernel/toKernelSmartAccount.ts - WebAuthn account creation
• packages/permissionless/accounts/kernel/utils/signMessage.ts - WebAuthn signature handling
• packages/permissionless/accounts/safe/toSafeSmartAccount.ts - WebAuthn public key handling
• packages/permissionless/accounts/safe/signUserOperation.ts - WebAuthn signature handling
• packages/permissionless/actions/passkeyServer/startAuthentication.ts - WebAuthn authentication
• packages/permissionless/actions/passkeyServer/startRegistration.ts - WebAuthn registration
• packages/permissionless/actions/passkeyServer/verifyAuthentication.ts - WebAuthn verification
• packages/permissionless/actions/passkeyServer/verifyRegistration.ts - WebAuthn verification
• packages/wagmi-demo/src/PasskeyServerDemo.tsx - Demo component

Build Script Fix

• package.json (root) - Fixed Windows compatibility by replacing printf with echo in build scripts

Benefits

• Better Developer Experience: Clear, actionable error messages when ox is missing
• Graceful Degradation: Library works without ox for non-WebAuthn use cases
• Centralized Management: Single utility module handles all ox-related imports
• Improved Documentation: Clear guidance for WebAuthn installation
• Cross-Platform Support: Fixed Windows build script compatibility

Before vs After

Before (Current State)

import { Base64 } from "ox" // ❌ Fails if ox not installed

After (Our Enhancement)

import { getOxExports } from "../../utils/ox.js"
const { Base64 } = await getOxExports() // ✅ Graceful error handling

Testing

• ✅ Build process works correctly
• ✅ All TypeScript types maintained
• ✅ Error handling provides clear guidance when ox is missing
• ✅ Existing functionality preserved
• ✅ WebAuthn features work when ox is installed

Usage Examples

Without WebAuthn (works fine)

npm install permissionless
# ✅ No errors, library works for basic functionality

With WebAuthn (clear guidance)

npm install permissionless
# Try to use WebAuthn feature...
# ❌ Error: "The 'ox' package is required for WebAuthn functionality. Please install it: npm install ox"
npm install ox
# ✅ WebAuthn features now work

This enhancement makes the existing optional dependency implementation much more robust and user-friendly.

Closes #399

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8287811

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR