feat(mobile): service-role sendNotification for AppUser push

[gdauber1]

Summary

SDK counterpart of base44-dev/apper#11072 (UOU push Phase 3): expose mobile push sending to backend functions via the service-role client.

• base44.asServiceRole.mobile.sendNotification({ userId, title, content, actionLabel?, actionUrl?, metadata? })
• Posts to POST /apps/{appId}/mobile/notifications (service-role only on the backend)
• Client-side validation mirrors the API: title ≤ 100, content ≤ 500, actionLabel ≤ 50, metadata must be a plain object
• Not exposed on regular clients — base44.mobile stays undefined; frontend code cannot send pushes directly

Tests

tests/unit/mobile.test.ts: endpoint/payload shape, validation limits, frontend non-exposure. Full suite: 170 passed.

Sequencing

Land after base44-dev/apper#11072 merges; then publish the SDK version, then the builder prompt advert ships in apper as a follow-up.

🤖 Generated with Claude Code

[claude]

Claude finished @gdauber1's task —— View job

---

Code Review Summary

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

✅ Strengths

1. Security-First Design: The module is correctly restricted to service-role authentication only, preventing potential abuse from client-side code
2. Comprehensive Input Validation: All parameters are properly validated with appropriate length limits
3. Good Test Coverage: Unit tests cover the main functionality, validation edge cases, and security boundaries
4. Clean API Design: The interface is simple and intuitive with clear parameter names and types
5. Proper Documentation: JSDoc comments explain the service-role restriction clearly

🔍 Code Quality & Best Practices

Good practices observed:

• Proper TypeScript typing throughout
• Consistent error messages
• Clear separation between types and implementation
• Integration follows existing module patterns

Minor suggestions:

1. Type assertion in mobile.ts:78 could be cleaner:

   // Current
   return response as unknown as SendNotificationResult;
   
   // Suggested
   return response.data;

   The double assertion seems unnecessary since axios.post is already typed with the generic.

2. Consider extracting validation constants:

   const TITLE_MAX_LENGTH = 100;
   const CONTENT_MAX_LENGTH = 500;
   const ACTION_LABEL_MAX_LENGTH = 50;

   This would make the limits more maintainable and testable.

🐛 Potential Issues

No critical bugs found. The implementation is solid.

⚡ Performance Considerations

• The synchronous validation is appropriate for this use case
• No performance concerns identified

🔒 Security Analysis

Excellent security posture:

• ✅ Service-role only access prevents client-side abuse
• ✅ Proper token handling with on-behalf-of header for service role requests
• ✅ Input validation prevents injection attacks
• ✅ Length limits prevent resource exhaustion
• ✅ Test explicitly verifies the module is not exposed on the regular client

One consideration:

• The metadata field accepts Record<string, unknown> which is appropriately flexible but ensure the backend validates the size of this object to prevent payload abuse

🧪 Test Coverage

Coverage is good:

• ✅ Happy path test
• ✅ Security boundary test (service-role only)
• ✅ All validation edge cases
• ✅ Integration with nock for API mocking

Additional test suggestions:

1. Test behavior when API returns error responses
2. Test null/undefined handling for optional fields
3. Test very large metadata objects

📝 Documentation

The documentation updates are clear and helpful:

• README properly explains the service-role restriction
• Type definitions have good JSDoc comments
• Integration point in the client is well-documented

Overall Assessment

This is a well-implemented feature that follows security best practices and maintains consistency with the existing codebase. The service-role restriction is the correct approach for sensitive operations like push notifications. The code is production-ready with only minor suggestions for improvement.

Recommendation: ✅ Approve with minor suggestions

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.31-pr.195.c0f5839

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/sdk@0.8.31-pr.195.c0f5839"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.31-pr.195.c0f5839"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.31-pr.195.c0f5839
• 🔗 View this commit on GitHub

---

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

[claude]

Claude finished @gdauber1's task —— View job

---

Code Review for Mobile Push Notification SDK

I've completed my review of the mobile SDK implementation. Overall, this is a well-structured feature that follows security best practices.

✅ Strengths

1. Excellent Security Design

   • Service-role only restriction correctly prevents client-side abuse
   • Clear separation between user and service-role modules
   • Proper authentication token handling with on-behalf-of header
   • Comprehensive input validation with sensible length limits

2. Code Quality

   • Consistent with existing codebase patterns
   • Clean TypeScript interfaces with proper JSDoc comments
   • Well-organized module structure
   • Good separation of concerns between types and implementation

3. Input Validation

   • All required fields are properly validated
   • Length limits prevent resource exhaustion (title: 100, content: 500, actionLabel: 50)
   • Type checking for metadata ensures it's an object (not array)
   • Clear, descriptive error messages

📝 Minor Observations

1. Type Assertion Pattern (line 78 in mobile.ts)

   return response as unknown as SendNotificationResult;

   This double assertion is consistent with the codebase pattern. It's needed because the axios response interceptor returns response.data when interceptResponses is true, but TypeScript still thinks it's the full response object.

2. Validation Functions
   The validation helper functions are clean and reusable. Consider extracting validation constants for better maintainability:

   const VALIDATION_LIMITS = {
     TITLE_MAX_LENGTH: 100,
     CONTENT_MAX_LENGTH: 500,
     ACTION_LABEL_MAX_LENGTH: 50
   };

🧪 Test Coverage

Excellent coverage includes:

• ✅ Happy path with all parameters
• ✅ Service-role only access verification
• ✅ All validation edge cases (empty strings, length limits)
• ✅ Metadata type validation
• ✅ API mocking with nock

Additional test suggestions:

1. Test null/undefined handling for optional fields
2. Test API error responses (4xx, 5xx)
3. Test edge cases for metadata (empty object, very large objects)
4. Test validation for whitespace-only strings in required fields

🔒 Security Analysis

Strong security posture:

• ✅ No exposure in regular client (only asServiceRole)
• ✅ Prevents injection through proper validation
• ✅ Tests explicitly verify module is not exposed on regular client

Recommendation: Ensure the backend validates the size/depth of the metadata object to prevent potential DoS through extremely large payloads.

📚 Documentation

• README clearly explains the service-role restriction
• Type definitions have comprehensive JSDoc comments
• Good examples of usage in backend functions

🎯 Overall Assessment

This is a production-ready implementation that follows security best practices and maintains consistency with the existing SDK architecture. The service-role restriction is the correct approach for sensitive operations like push notifications.

Verdict: ✅ Approved - The code is well-written, secure, and ready for production use.