connectors initiate method

Author: cowchimp

src/modules/connectors.ts

@@ -2,6 +2,7 @@ import { AxiosInstance } from "axios";
 import {
   ConnectorIntegrationType,
   ConnectorAccessTokenResponse,
+  ConnectorInitiateResponse,
   ConnectorsModule,
 } from "./connectors.types.js";
 
@@ -34,5 +35,21 @@ export function createConnectorsModule(
       // @ts-expect-error
       return response.access_token;
     },
+
+    async initiate(
+      integrationType: ConnectorIntegrationType
+    ): Promise<string> {
+      if (!integrationType || typeof integrationType !== "string") {
+        throw new Error("Integration type is required and must be a string");
+      }
+
+      const response = await axios.post<ConnectorInitiateResponse>(
+        `/apps/${appId}/end-user-auth/initiate`,
+        { integration_type: integrationType }
+      );
+
+      // @ts-expect-error
+      return response.redirect_url;
+    },
   };
 }

src/modules/connectors.types.ts

@@ -24,6 +24,13 @@ export interface ConnectorAccessTokenResponse {
   access_token: string;
 }
 
+/**
+ * Response from the connectors initiate endpoint.
+ */
+export interface ConnectorInitiateResponse {
+  redirect_url: string;
+}
+
 /**
  * Connectors module for managing OAuth tokens for external services.
  *
@@ -85,4 +92,24 @@ export interface ConnectorsModule {
    * ```
    */
   getAccessToken(integrationType: ConnectorIntegrationType): Promise<string>;
+
+  /**
+   * Initiates the end-user OAuth flow for a specific external integration type.
+   *
+   * Returns a redirect URL that the end user should be redirected to in order to
+   * authenticate with the external service.
+   *
+   * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, or `'github'`.
+   * @returns Promise resolving to the redirect URL string.
+   *
+   * @example
+   * ```typescript
+   * // Initiate Google Calendar OAuth for the end user
+   * const redirectUrl = await base44.asServiceRole.connectors.initiate('googlecalendar');
+   *
+   * // Redirect the user to the OAuth provider
+   * res.redirect(redirectUrl);
+   * ```
+   */
+  initiate(integrationType: ConnectorIntegrationType): Promise<string>;
 }