feat: expose Firebase error information to SDK users

[putcho01]

Discussion

This PR exposes Firebase error information to SDK users by making error codes and details publicly accessible through the errorutils package.

Previously, SDK users could only check for specific error conditions using boolean helper functions (e.g., IsNotFound(), messaging.IsUnregistered()). They had no programmatic access to the underlying error codes or Firebase-specific error details stored in the internal Ext map.

This PR introduces a public FirebaseError type and AsFirebaseError() function that allows users to:

• Access platform-wide error codes (e.g., INVALID_ARGUMENT, NOT_FOUND)
• Access service-specific error codes (e.g., UNREGISTERED, QUOTA_EXCEEDED for FCM, USER_NOT_FOUND for Auth)
• Retrieve the HTTP response for debugging
• Write generic error handling logic that works across all Firebase services

Motivation

Users need to distinguish between different types of Firebase errors to take appropriate actions. For example:

• When FCM returns UNREGISTERED, the device token should be removed from the database
• When FCM returns QUOTA_EXCEEDED, the application should implement backoff/retry logic
• When Auth returns ID_TOKEN_EXPIRED, the user should be prompted to re-authenticate

Without programmatic access to these error codes, users must rely on ~30+ boolean helper functions scattered across different packages, making it difficult to write maintainable error handling code.

Testing

• Added comprehensive unit tests covering all error types and conversion scenarios
• Added example tests demonstrating common usage patterns
• Verified that existing messaging and auth packages already populate error codes correctly in the Ext map

Notes

• The internal.FirebaseError type remains unchanged to maintain internal implementation stability
• The public FirebaseError is a lightweight wrapper that extracts information from the internal error
• Memory overhead is minimal as only pointers and small metadata are copied
• Future services can easily add their own service-specific error codes following the same pattern

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.