docs: add getConnection() JSDoc, update deprecated rendering pipeline

Update connectors.types.ts with getConnection() examples and description,
simplify deprecation message, and add deprecated method post-processing
to the doc generation pipeline (emoji in heading, Danger callout above signature).

Made-with: Cursor

Author: wixysam

.claude/skills/sdk-docs-writing/SKILL.md

@@ -174,6 +174,7 @@ const records = await base44.entities.MyEntity.list();
 - **Avoid gerunds** in section headings within JSDoc. Prefer imperatives or noun phrases.
 - **State environment constraints** when a method is browser-only: "Requires a browser environment and can't be used in the backend."
 - **Document side effects** explicitly (e.g., "automatically sets the token for subsequent requests").
+- **Link method references.** When mentioning another SDK method or module by name in JSDoc prose, always use `{@link}` or `{@linkcode}` to create a cross-reference. Never leave a method name as plain text when a link target exists.
 
 ## Doc generation pipeline
 

scripts/mintlify-post-processing/file-processing/file-processing.js

@@ -1017,6 +1017,123 @@ function applySignatureCleanup(dir) {
   }
 }
 
+/**
+ * Transforms deprecated method sections:
+ * 1. Removes ~~strikethrough~~ and prepends a warning emoji to the heading
+ * 2. Extracts the #### Deprecated block, removes it, and re-inserts it as a
+ *    <Danger> callout between the heading and the signature blockquote
+ */
+function processDeprecatedMethods(content) {
+  const lines = content.split("\n");
+  let modified = false;
+  let inFence = false;
+
+  // First pass: find all deprecated sections and collect their info
+  const deprecatedSections = [];
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    if (trimmed === "#### Deprecated") {
+      const start = i;
+      let end = i + 1;
+      let message = "";
+      // The first non-empty line after "#### Deprecated" is the deprecation message.
+      // Any subsequent lines are description text that TypeDoc misplaced here.
+      while (end < lines.length) {
+        const t = lines[end].trim();
+        if (t.startsWith("#### ") || t.startsWith("### ") || t.startsWith("## ") || t === "***") break;
+        if (!message && t) {
+          message = t;
+        }
+        end++;
+      }
+      deprecatedSections.push({ start, end, message });
+    }
+  }
+
+  if (deprecatedSections.length === 0) {
+    return { content, modified: false };
+  }
+
+  // Remove deprecated sections bottom-up so indices stay valid
+  for (let s = deprecatedSections.length - 1; s >= 0; s--) {
+    const { start, end } = deprecatedSections[s];
+    lines.splice(start, end - start);
+    modified = true;
+  }
+
+  // Second pass: transform headings and insert Danger callouts
+  inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+
+    // Match deprecated heading: ### ~~methodName()~~ (TypeDoc wraps deprecated names in ~~)
+    const headingMatch = trimmed.match(/^###\s+~~(.+?)~~\s*$/);
+    if (!headingMatch) continue;
+
+    // Remove strikethrough and prepend warning emoji
+    lines[i] = lines[i].replace(
+      /^(###\s+)~~(.+?)~~\s*$/,
+      "$1\u26A0\uFE0F $2"
+    );
+    modified = true;
+
+    // Find the matching deprecated message by method name
+    const methodName = headingMatch[1].replace(/\(\)$/, "");
+    const section = deprecatedSections.find((sec) =>
+      sec.message.toLowerCase().includes(methodName.toLowerCase()) ||
+      deprecatedSections.length === 1
+    ) || deprecatedSections.shift();
+
+    if (!section || !section.message) continue;
+
+    // Insert Danger callout right after the heading (before the signature)
+    const dangerBlock = [
+      "",
+      "<Danger>",
+      `**Deprecated:** ${section.message}`,
+      "</Danger>",
+      "",
+    ];
+    lines.splice(i + 1, 0, ...dangerBlock);
+  }
+
+  return { content: lines.join("\n"), modified };
+}
+
+function applyDeprecatedMethodProcessing(dir) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const entryPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      applyDeprecatedMethodProcessing(entryPath);
+    } else if (
+      entry.isFile() &&
+      (entry.name.endsWith(".mdx") || entry.name.endsWith(".md"))
+    ) {
+      const content = fs.readFileSync(entryPath, "utf-8");
+      const { content: updated, modified } = processDeprecatedMethods(content);
+      if (modified) {
+        fs.writeFileSync(entryPath, updated, "utf-8");
+        console.log(
+          `Processed deprecated methods: ${path.relative(DOCS_DIR, entryPath)}`
+        );
+      }
+    }
+  }
+}
+
 function demoteNonCallableHeadings(content) {
   const lines = content.split("\n");
   let inFence = false;
@@ -1919,6 +2036,9 @@ function main() {
   // Clean up signatures: fix truncated generics, simplify keyof constraints, break long lines
   applySignatureCleanup(DOCS_DIR);
 
+  // Transform deprecated methods: add badge to heading, move deprecation notice to Warning callout
+  applyDeprecatedMethodProcessing(DOCS_DIR);
+
   applyHeadingDemotion(DOCS_DIR);
 
   // Group intro sections (Built-in User Entity, Generated Types, etc.) under Overview

src/modules/connectors.types.ts

@@ -29,7 +29,7 @@ export interface ConnectorAccessTokenResponse {
 }
 
 /**
- * Camel-cased connection details returned by {@linkcode ConnectorsModule.getConnection | getConnection()}.
+ * Connection details.
  */
 export interface ConnectorConnectionResponse {
   /** The OAuth access token for the external service. */
@@ -50,7 +50,7 @@ export interface ConnectorConnectionResponse {
  *
  * ## Available connectors
  *
- * All connectors work through [`getAccessToken()`](#getaccesstoken). Pass the integration type string and use the returned OAuth token to call the external service's API directly.
+ * All connectors work through [`getConnection()`](#getconnection). Pass the integration type string and use the returned OAuth token to call the external service's API directly.
  *
  * | Service | Type identifier |
  * |---|---|
@@ -88,7 +88,7 @@ export interface ConnectorsModule {
   /**
    * Retrieves an OAuth access token for a specific [external integration type](#available-connectors).
    *
-   * @deprecated Use {@link getConnection} and use the returned `accessToken` (and `connectionConfig` when needed) instead.
+   * @deprecated Use {@link getConnection} instead.
    *
    * Returns the OAuth token string for an external service that an app builder
    * has connected to. This token represents the connected app builder's account
@@ -159,37 +159,63 @@ export interface ConnectorsModule {
    * Retrieves the OAuth access token and connection configuration for a specific external integration type.
    *
    * Returns both the OAuth token and any additional connection configuration
-   * that the connector provides. This is useful when the external service requires
-   * extra parameters beyond the access token (e.g., a shop domain, account ID, or API base URL).
+   * that the connector provides. Some connectors require connection-specific
+   * parameters to build API requests. For example, a service might need a
+   * subdomain to construct the API URL (`{subdomain}.example.com`), which
+   * is available in `connectionConfig`. Most connectors only need the
+   * `accessToken`; `connectionConfig` will be `null` when there are no
+   * extra parameters.
    *
    * @param integrationType - The type of integration, such as `'googlecalendar'`, `'slack'`, or `'github'`.
    * @returns Promise resolving to a {@link ConnectorConnectionResponse} with `accessToken` and `connectionConfig`.
    *
    * @example
    * ```typescript
-   * // Basic usage
-   * const connection = await base44.asServiceRole.connectors.getConnection('googlecalendar');
-   * console.log(connection.accessToken);
-   * console.log(connection.connectionConfig);
+   * // Google Calendar connection
+   * // Get Google Calendar OAuth token and fetch upcoming events
+   * const { accessToken } = await base44.asServiceRole.connectors.getConnection('googlecalendar');
+   *
+   * const timeMin = new Date().toISOString();
+   * const url = `https://www.googleapis.com/calendar/v3/calendars/primary/events?maxResults=10&orderBy=startTime&singleEvents=true&timeMin=${timeMin}`;
+   *
+   * const calendarResponse = await fetch(url, {
+   *   headers: { Authorization: `Bearer ${accessToken}` }
+   * });
+   *
+   * const events = await calendarResponse.json();
    * ```
    *
    * @example
    * ```typescript
-   * // Shopify: connectionConfig has subdomain (e.g. "my-store" for my-store.myshopify.com)
-   * const connection = await base44.asServiceRole.connectors.getConnection('shopify');
-   * const { accessToken, connectionConfig } = connection;
-   * const shop = connectionConfig?.subdomain
-   *   ? `https://${connectionConfig.subdomain}.myshopify.com`
-   *   : null;
-   *
-   * if (shop) {
-   *   const response = await fetch(
-   *     `${shop}/admin/api/2024-01/products.json?limit=10`,
-   *     { headers: { 'X-Shopify-Access-Token': accessToken } }
-   *   );
-   *   const { products } = await response.json();
-   * }
+   * // Slack connection
+   * // Get Slack OAuth token and list channels
+   * const { accessToken } = await base44.asServiceRole.connectors.getConnection('slack');
+   *
+   * const url = 'https://slack.com/api/conversations.list?types=public_channel,private_channel&limit=100';
+   *
+   * const slackResponse = await fetch(url, {
+   *   headers: { Authorization: `Bearer ${accessToken}` }
+   * });
+   *
+   * const data = await slackResponse.json();
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Using connectionConfig
+   * // Some connectors return a subdomain or other params needed to build the API URL
+   * const { accessToken, connectionConfig } = await base44.asServiceRole.connectors.getConnection('myservice');
+   *
+   * const subdomain = connectionConfig?.subdomain;
+   * const response = await fetch(
+   *   `https://${subdomain}.example.com/api/v1/resources`,
+   *   { headers: { Authorization: `Bearer ${accessToken}` } }
+   * );
+   *
+   * const data = await response.json();
    * ```
    */
-  getConnection(integrationType: ConnectorIntegrationType): Promise<ConnectorConnectionResponse>;
+  getConnection(
+    integrationType: ConnectorIntegrationType,
+  ): Promise<ConnectorConnectionResponse>;
 }