Add mobile module to Base44 SDK for push notifications

[gdauber1]

Summary

Adds mobile native capabilities to the Base44 SDK, enabling LLM-generated apps to send push notifications to users via base44.mobile.sendNotification().

This PR implements the SDK side of mobile native features, complementing the backend mobile API.

Changes

SDK Mobile Module

• ✅ Created mobile module with sendNotification() method
• ✅ Added TypeScript type definitions for mobile notifications
• ✅ Integrated mobile module into Base44Client interface
• ✅ Exported mobile types from index.ts

Documentation

• ✅ Updated README with comprehensive mobile features section
• ✅ Added notification channels documentation
• ✅ Included common use cases (orders, chat, reminders)
• ✅ Added error handling patterns

Examples

• ✅ Created examples/mobile-notifications.ts with 10 practical examples
• ✅ Covers: basic notifications, action buttons, channels, error handling, bulk notifications, retry logic

Usage

```typescript
import { base44 } from "@/api/base44Client";

// Send mobile push notification
await base44.mobile.sendNotification({
userId: 'user_123',
title: 'New Message!',
content: 'You have a new message from John',
actionLabel: 'View Message',
actionUrl: '/messages/456',
channels: ['mobile_push']
});
```

Files Changed

• Created: `src/modules/mobile.ts` - Mobile module implementation
• Created: `src/modules/mobile.types.ts` - TypeScript type definitions
• Created: `examples/mobile-notifications.ts` - 10 comprehensive examples
• Modified: `src/client.ts` - Initialize mobile module
• Modified: `src/client.types.ts` - Add MobileModule interface
• Modified: `src/index.ts` - Export mobile types
• Modified: `README.md` - Add mobile features documentation

Features

• ✅ Send push notifications to mobile devices (iOS/Android)
• ✅ Send in-app notifications to web interface
• ✅ Support for action buttons with deep links
• ✅ Multi-channel delivery (mobile_push + in_app)
• ✅ Graceful error handling and degradation
• ✅ Full TypeScript type safety

Testing

The SDK compiles successfully:
```bash
npm run build # ✅ Passes
```

Examples

See examples/mobile-notifications.ts for comprehensive usage examples including:

• Basic push notifications
• Notifications with action buttons
• Multi-channel delivery
• Order/delivery updates
• Chat messaging notifications
• Event reminders
• Bulk notifications
• Error handling and retry logic

Documentation

Updated README.md with complete mobile features documentation including:

• API usage examples
• Channel options (mobile_push vs in_app)
• Common use cases (orders, chat, events)
• Error handling patterns

Co-Authored-By: Claude Sonnet 4.5 [email protected]

[claude]

Claude finished @gdauber1's task —— View job

---

Code Review for Mobile Module PR

I've completed my review of the mobile module implementation. Here's my comprehensive feedback:

✅ Code Quality and Best Practices

Strengths:

• Clean, modular architecture following established SDK patterns
• Well-documented TypeScript interfaces with JSDoc comments
• Consistent error handling across the module
• Good use of optional parameters and sensible defaults
• Clear separation between types (mobile.types.ts) and implementation (mobile.ts)

Minor Improvements:

1. The metadata field in SendNotificationParams (mobile.types.ts:32) uses any type. Consider using a more specific type or unknown:

   metadata?: Record<string, unknown>;

⚠️ Potential Issues

1. Input Validation: The implementation doesn't validate input lengths against the documented limits:

   • Title: max 100 characters
   • Content: max 500 characters
   • Action label: max 50 characters

   Consider adding validation before sending to the API:

   if (params.title.length > 100) {
     throw new Error('Title must be 100 characters or less');
   }

2. HTML Content Security: The content field supports HTML (mobile.types.ts:23) but there's no mention of sanitization. This could be a potential XSS risk if user-generated content is passed directly.

3. Missing Service Role Support: The mobile module is only added to the user modules in client.ts:160, not to the service role modules. This means base44.asServiceRole.mobile won't work, which might be needed for server-side bulk notifications.

🚀 Performance Considerations

1. Bulk Notifications: The example shows sending bulk notifications using Promise.allSettled, which is good. However, for large user lists, consider:

   • Rate limiting to avoid overwhelming the API
   • Batch processing with pagination
   • Queue-based processing for very large sets

2. Retry Logic: The retry example uses exponential backoff (good!), but consider:

   • Adding jitter to prevent thundering herd
   • Making retry delays configurable
   • Using a circuit breaker pattern for repeated failures

🔒 Security Concerns

1. Authorization: The module correctly delegates auth to the API layer through the axios instance
2. User Privacy: Good practice showing user ID validation (404 handling)
3. HTML Content: As mentioned above, ensure HTML content is properly sanitized server-side
4. Sensitive Data: The examples appropriately avoid including sensitive data in notifications

🧪 Test Coverage

Critical Gap: No tests found for the mobile module. This is the most significant issue. Consider adding:

1. Unit Tests for:

   • createMobileModule function
   • Parameter validation
   • Error handling scenarios
   • Different channel configurations

2. Integration Tests for:

   • Successful notification sending
   • Error responses (404, 403, 500)
   • Channel-specific behaviors
   • Retry behavior

Example test structure:

// tests/unit/mobile.test.ts
describe('MobileModule', () => {
  describe('sendNotification', () => {
    it('should send notification with required params');
    it('should handle channel selection correctly');
    it('should throw on invalid userId');
    // etc.
  });
});

📝 Additional Recommendations

1. Type Safety: Consider creating branded types for userId to prevent accidental string mixing:

   type UserId = string & { __brand: 'UserId' };

2. Channel Expansion: The enum for channels is good. Consider if you need a registry pattern for future channel additions.

3. Observability: Consider adding optional callbacks or events for notification status tracking:

   onSent?: (result: NotificationResult) => void;
   onFailed?: (error: Error) => void;

4. Documentation: The README examples are excellent and comprehensive. Consider adding:

   • Common error scenarios and solutions
   • Best practices for notification content
   • Guidelines on channel selection

Summary

This is a well-implemented feature that follows SDK conventions. The main concerns are:

1. Missing tests (critical)
2. Input validation for character limits
3. Service role support might be needed
4. HTML content security considerations

The code is production-ready with these issues addressed. The examples are particularly well done and will help developers quickly understand the feature.

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/[email protected]

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/[email protected]"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/[email protected]"
  }
}

• 📦 Preview Package: @base44-preview/[email protected]
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}

[claude]

Claude finished @gdauber1's task —— View job

---

🔍 Code Review Complete

Review Checklist:

• Examine code structure and implementation
• Check for potential bugs or issues
• Analyze performance considerations
• Assess security concerns
• Evaluate test coverage
• Review documentation and examples

---

Overall Assessment

This is an excellent implementation of the mobile module for the Base44 SDK. The code is clean, well-structured, and follows SDK conventions. I'm particularly impressed that my previous review feedback has been addressed comprehensively.

✅ Code Quality and Best Practices

Strengths:

• Clean, modular architecture that aligns with SDK patterns
• Excellent TypeScript types with comprehensive JSDoc documentation
• Proper separation of concerns (types vs implementation)
• Clear and consistent naming conventions
• Good error handling throughout

Improvements from Previous Review:

• ✅ Input validation has been added for character limits (mobile.ts:19-37)
• ✅ Comprehensive test suite has been added (tests/unit/mobile.test.ts)
• ✅ Service role support has been implemented (client.ts:193)
• ✅ The metadata type now uses Record<string, unknown> instead of any

🛡️ Security Considerations

1. HTML Content: The content field supports HTML (mobile.types.ts:23). While the SDK properly passes this to the API, ensure the backend sanitizes HTML content to prevent XSS attacks.

2. Authorization: Correctly delegates auth through the axios instance, maintaining security boundaries.

3. No Sensitive Data in Examples: The examples appropriately demonstrate avoiding sensitive data in notifications.

🚀 Performance Considerations

1. Input Validation: Validates parameters client-side before API calls, preventing unnecessary network requests.

2. Error Handling: Proper error propagation allows consumers to implement retry logic as shown in examples.

3. Bulk Operations: The examples demonstrate using Promise.allSettled for bulk notifications, which is a good pattern.

🧪 Test Coverage - Excellent!

The test suite (270 lines) is comprehensive and covers:

• ✅ Basic notification sending with required and optional parameters
• ✅ Channel-specific behavior (mobile_push, in_app, both)
• ✅ Input validation for all character limits (title: 100, content: 500, action label: 50)
• ✅ Boundary testing (exactly at limits)
• ✅ Error handling (API errors, 404 responses)
• ✅ Partial channel failures
• ✅ Metadata passing
• ✅ HTML content handling
• ✅ Validation occurs before API calls

📚 Documentation and Examples

Excellent documentation:

• Comprehensive README section with clear usage examples
• 10 practical examples in mobile-notifications.ts covering common use cases
• Clear channel explanations
• Error handling patterns
• TypeScript interfaces are well-documented with JSDoc

Minor Suggestions

1. Rate Limiting: Consider documenting rate limits if the API has any, to help developers implement appropriate throttling.

2. Notification Tracking: The NotificationResult includes a notificationId for in-app notifications. Consider documenting how developers can use this for tracking delivery status.

3. Future Enhancement: Consider supporting notification priorities or time-to-live (TTL) settings in future iterations.

Summary

This PR is production-ready. The implementation is solid, follows best practices, and addresses all concerns from the previous review. The addition of comprehensive tests and proper service role support makes this a robust feature addition to the SDK.

Great work on implementing the feedback and creating a well-documented, thoroughly tested mobile module! 🎉