address review

Author: wixysam

src/modules/custom-integrations.types.ts

@@ -3,28 +3,19 @@
  */
 export interface CustomIntegrationCallParams {
   /**
-   * Request body to send to the external API. The payload is JSON-serialized before being sent.
+   * Request body payload to send to the external API.
    */
   payload?: Record<string, any>;
 
   /**
-   * Path parameters to substitute into the URL template.
-   * For example, if the API endpoint is `/repos/{owner}/{repo}/issues`,
-   * pass `{ owner: "myorg", repo: "myrepo" }`.
+   * Path parameters to substitute in the URL (e.g., `{ owner: "user", repo: "repo" }`).
    */
   pathParams?: Record<string, string>;
 
   /**
    * Query string parameters to append to the URL.
-   * For example, `{ state: "open", per_page: 50 }` becomes `?state=open&per_page=50`.
    */
   queryParams?: Record<string, any>;
-
-  /**
-   * Additional HTTP headers to include in the request.
-   * These headers are merged with any headers configured for the integration itself, with headers specified here taking precedence in case of conflicts.
-   */
-  headers?: Record<string, string>;
 }
 
 /**
@@ -42,69 +33,77 @@ export interface CustomIntegrationCallResponse {
   status_code: number;
 
   /**
-   * The parsed JSON response body from the external API.
-   * The structure depends on the API endpoint being called.
+   * The response data from the external API.
+   * Can be any JSON-serializable value depending on the external API's response.
    */
   data: any;
 }
 
 /**
- * Custom integrations module for calling workspace-level API integrations.
+ * Module for calling custom workspace-level API integrations.
+ *
+ * Custom integrations allow workspace administrators to connect any external API
+ * by importing an OpenAPI specification. Apps in the workspace can then call
+ * these integrations using this module.
+ *
+ * Unlike the built-in integrations (like `Core`), custom integrations:
+ * - Are defined per-workspace by importing OpenAPI specs
+ * - Use a slug-based identifier instead of package names
+ * - Proxy requests through Base44's backend (credentials never exposed to frontend)
+ *
+ * @example
+ * ```typescript
+ * // Call a custom CRM integration
+ * const response = await base44.integrations.custom.call(
+ *   "my-crm",         // integration slug (defined by workspace admin)
+ *   "get:/contacts",  // endpoint: method:path format
+ *   {
+ *     queryParams: { limit: 10 }
+ *   }
+ * );
+ *
+ * if (response.success) {
+ *   console.log("Contacts:", response.data);
+ * } else {
+ *   console.error("API returned error:", response.status_code);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Call with path params and request body payload
+ * const response = await base44.integrations.custom.call(
+ *   "github",
+ *   "post:/repos/{owner}/{repo}/issues",
+ *   {
+ *     pathParams: { owner: "myorg", repo: "myrepo" },
+ *     payload: {
+ *       title: "Bug report",
+ *       body: "Something is broken",
+ *       labels: ["bug"]
+ *     }
+ *   }
+ * );
+ * ```
  */
 export interface CustomIntegrationsModule {
   /**
    * Call a custom integration endpoint.
    *
-   * Custom integrations are external APIs that have been pre-configured by a workspace administrator who imports an OpenAPI specification. Each integration is identified by a slug and exposes operations defined in the specification.
-   *
-   * Requests are proxied through Base44's backend, so API credentials aren't exposed. That means you can safely use this method to call external APIs from frontend code.
-   *
-   * @param slug - The integration's unique identifier, as defined by the workspace admin.
-   * @param operationId - The operation ID from the OpenAPI specification, such as `"listIssues"` or `"getUser"`.
-   * @param params - Optional parameters to send to the external API.
+   * @param slug - The integration's unique identifier (slug), as defined by the workspace admin.
+   * @param endpoint - The endpoint in `method:path` format (e.g., `"get:/contacts"`, `"post:/users/{id}"`). The method is the HTTP verb (lowercase) and the path matches the OpenAPI specification.
+   * @param params - Optional parameters including payload, pathParams, and queryParams.
    * @returns Promise resolving to the integration call response.
    *
    * @throws {Error} If slug is not provided.
-   * @throws {Error} If operationId is not provided.
-   * @throws {Base44Error} If the integration or operation is not found (404).
+   * @throws {Error} If endpoint is not provided.
+   * @throws {Base44Error} If the integration or endpoint is not found (404).
    * @throws {Base44Error} If the external API call fails (502).
    * @throws {Base44Error} If the request times out (504).
-   *
-   * @example
-   * ```typescript
-   * // GET request with path and query parameters
-   * const response = await base44.integrations.custom.call(
-   *   "github",
-   *   "listRepoIssues",
-   *   {
-   *     pathParams: { owner: "myorg", repo: "myrepo" },
-   *     queryParams: { state: "open", per_page: 50 }
-   *   }
-   * );
-   *
-   * if (response.success) {
-   *   console.log("Found issues:", response.data.length);
-   * }
-   * ```
-   *
-   * @example
-   * ```typescript
-   * // POST request with a JSON body
-   * const response = await base44.integrations.custom.call(
-   *   "slack",
-   *   "postMessage",
-   *   {
-   *     payload: {
-   *       channel: "#general",
-   *       text: "Hello from Base44!"
-   *     }
-   *   }
-   * );
-   * ```
    */
   call(
     slug: string,
-    operationId: string,
+    endpoint: string,
     params?: CustomIntegrationCallParams
   ): Promise<CustomIntegrationCallResponse>;
 }

src/modules/integrations.types.ts

@@ -351,28 +351,22 @@ export interface CoreIntegrations {
 }
 
 /**
- * Integrations module for calling integration methods.
+ * Integrations module for calling integration endpoints.
  *
- * This module provides access to integration methods for interacting with external services. Unlike the connectors module that gives you raw OAuth tokens, integrations provide pre-built functions that Base44 executes on your behalf.
+ * This module provides access to integration endpoints for interacting with external
+ * services. Integrations are organized into packages. Base44 provides built-in integrations
+ * in the `Core` package.
  *
- * There are two types of integrations:
+ * Unlike the connectors module that gives you raw OAuth tokens, integrations provide
+ * pre-built functions that Base44 executes on your behalf.
  *
- * - **Built-in integrations** (`Core`): Pre-built functions provided by Base44 for common tasks such as AI-powered text generation, image creation, file uploads, and email. Access core integration methods using:
- *   ```
- *   base44.integrations.Core.FunctionName(params)
- *   ```
- *
- * - **Custom integrations** (`custom`): Pre-configured external APIs. Custom integration calls are proxied through Base44's backend, so credentials are never exposed to the frontend. Access custom integration methods using:
- *   ```
- *   base44.integrations.custom.call(slug, operationId, params)
- *   ```
- *
- *   <Info>To call a custom integration, it must be pre-configured by a workspace administrator who imports an OpenAPI specification.</Info>
+ * Integration endpoints are accessed dynamically using the pattern:
+ * `base44.integrations.PackageName.EndpointName(params)`
  *
  * This module is available to use with a client in all authentication modes:
  *
- * - **Anonymous or User authentication** (`base44.integrations`): Integration methods are invoked with the current user's permissions. Anonymous users invoke methods without authentication, while authenticated users invoke methods with their authentication context.
- * - **Service role authentication** (`base44.asServiceRole.integrations`): Integration methods are invoked with elevated admin-level permissions. The methods execute with admin authentication context.
+ * - **Anonymous or User authentication** (`base44.integrations`): Integration endpoints are invoked with the current user's permissions. Anonymous users invoke endpoints without authentication, while authenticated users invoke endpoints with their authentication context.
+ * - **Service role authentication** (`base44.asServiceRole.integrations`): Integration endpoints are invoked with elevated admin-level permissions. The endpoints execute with admin authentication context.
  */
 export type IntegrationsModule = {
   /**
@@ -381,7 +375,22 @@ export type IntegrationsModule = {
   Core: CoreIntegrations;
 
   /**
-   * Custom integrations module for calling pre-configured external APIs.
+   * Custom integrations module for calling workspace-level API integrations.
+   *
+   * Allows calling external APIs that workspace admins have configured
+   * by importing OpenAPI specifications.
+   *
+   * @example
+   * ```typescript
+   * const response = await base44.integrations.custom.call(
+   *   "github",        // integration slug
+   *   "listIssues",    // operation ID
+   *   {
+   *     pathParams: { owner: "myorg", repo: "myrepo" },
+   *     queryParams: { state: "open" }
+   *   }
+   * );
+   * ```
    */
   custom: CustomIntegrationsModule;
 } & {