feat(connectors): add getConnection({ connectorId }) overload for BYO_SHARED

[cowchimp]

Backend functions can now retrieve the OAuth access token + connection config for a workspace-registered connector (backed by an OrganizationConnector that the app builder consented to) via a new overload on getConnection:

await base44.asServiceRole.connectors.getConnection({ connectorId: "..." });

Existing string-arg callers are unchanged — they continue to resolve to the platform-SHARED path. The overload dispatches on argument shape (string vs object) and hits a new server route GET /apps/{app_id}/external-auth/tokens/by-connector/{connector_id} for the workspace-connector lookup.

[claude]

Claude finished @cowchimp's task —— View job

---

PR Review: Add getConnection({ connectorId }) overload for BYO_SHARED

Summary

This PR adds support for workspace-registered connectors by introducing a new overload for the getConnection method. The implementation allows backend functions to retrieve OAuth access tokens for connectors using a connector ID rather than just integration type strings.

Code Quality and Best Practices ✅

Strengths:

• Clean implementation of function overloading that maintains backward compatibility
• Clear separation of concerns between the two code paths
• Consistent error handling patterns across both overloads
• Type definitions are well-documented with comprehensive examples
• Follows existing code patterns and conventions in the codebase

Minor suggestions:

• The error message on line 59 in connectors.ts could be more specific for the object case: "Connector ID or integration type is required"

Potential Bugs or Issues ⚠️

1. Type assertion concerns (connectors.ts:53-60):

   • The type narrowing could be more robust. Consider using a type guard function to ensure type safety
   • Edge case: What if someone passes { connectorId: 123 } (number instead of string)?

2. Response type mismatch (connectors.ts:62):

   • The function expects ConnectorAccessTokenResponse but doesn't validate the actual response structure from the new endpoint
   • Both endpoints should ideally return the same response structure

Performance Considerations ✅

• No significant performance concerns identified
• The conditional logic for URL selection is minimal and efficient
• HTTP requests are the main bottleneck, which is unavoidable

Security Concerns 🔒

1. Input validation: The connectorId validation only checks for emptiness and string type. Consider:

   • Adding format validation (e.g., alphanumeric + hyphens only)
   • Maximum length validation to prevent potential DoS

2. Authorization: The code doesn't show how authorization is handled for the new endpoint. Ensure:

   • The service role token has appropriate permissions for the new endpoint
   • Connector access is properly scoped to the requesting app

Test Coverage ✅

Well covered:

• Happy path for both string and object overloads
• Null/undefined connection_config handling
• Error cases for empty strings and invalid types

Missing test cases:

1. Invalid connectorId format (special characters, extremely long strings)
2. Network error handling scenarios
3. Invalid response structure from the new endpoint
4. Edge case: { connectorId: null } or { connectorId: undefined }

Recommendations

1. Add stricter input validation:

   const CONNECTOR_ID_PATTERN = /^[a-zA-Z0-9-_]+$/;
   const MAX_CONNECTOR_ID_LENGTH = 100;
   
   if (!CONNECTOR_ID_PATTERN.test(arg.connectorId) || 
       arg.connectorId.length > MAX_CONNECTOR_ID_LENGTH) {
     throw new Error("Invalid connector ID format");
   }

2. Consider adding a type guard:

   function isConnectorIdArg(arg: unknown): arg is { connectorId: string } {
     return typeof arg === 'object' && 
            arg !== null && 
            'connectorId' in arg &&
            typeof (arg as any).connectorId === 'string';
   }

3. Add integration tests to verify the actual API endpoints work as expected

Overall Assessment

This is a well-implemented feature that extends the SDK's capabilities while maintaining backward compatibility. The code follows established patterns and includes good documentation. With the suggested improvements around input validation and test coverage, this will be a solid addition to the SDK.

---

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.26-pr.160.6071150

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.26-pr.160.6071150"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.26-pr.160.6071150"
  }
}

• 📦 Preview Package: @base44-preview/sdk@0.8.26-pr.160.6071150
• 🔗 View this commit on GitHub

---

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