Add Super Carl app package, search, and communication actions

components/super_carl/README.md

@@ -0,0 +1,23 @@
+# Overview
+
+Super Carl is an AI networking and relationship-search platform for finding people, companies, jobs, posts, and warm paths through a user's professional network.
+
+Use Super Carl on Pipedream to build workflows that qualify people and companies, check network readiness before search, find jobs with warm paths, and discover post or engagement signals.
+
+# Getting Started
+
+Super Carl uses API-key authentication. In Super Carl, open **Integrations**, go to the **API / MCP** section, and create or purchase an API key with the `search` scope. Paste that key into the Pipedream connected account when prompted.
+
+# Example Use Cases
+
+- **Get Network Summary** checks LinkedIn sync readiness and available network filters.
+- **Search People** finds people by role, company history, expertise, location, network relationship, or recent activity.
+- **Search Companies** finds companies by name, domain, funding, size, industry, location, growth, or technology.
+- **Search Jobs** finds jobs and can include warm-path people at each hiring company.
+- **Search Posts** finds posts, comments, likes, reactions, company mentions, and other public activity signals.
+
+# Troubleshooting
+
+If authentication fails, confirm that the API key has the `search` scope and has not been revoked. If a search returns weaker network-aware results than expected, run **Get Network Summary** to confirm the relevant LinkedIn, Gmail, or Super Carl network data is synced.
+
+For detailed API usage, see [Super Carl documentation](https://supercarl.ai/docs).

components/super_carl/actions/get-network-summary/get-network-summary.mjs

@@ -0,0 +1,47 @@
+import superCarl from "../../super_carl.app.mjs";
+import { cleanObject } from "../../common/utils.mjs";
+
+export default {
+  key: "super_carl-get-network-summary",
+  name: "Get Network Summary",
+  description: "Check Super Carl network readiness before running people, jobs, or warm-intro searches. Use this to inspect LinkedIn/Gmail/Super Carl graph sync status for the API key owner or a delegated team-seat user via Delegate User ID; low or unsynced counts can explain weak network-aware results. [See the documentation](https://supercarl.ai/docs/endpoints)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    superCarl,
+    delegateUserId: {
+      propDefinition: [
+        superCarl,
+        "delegateUserId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.superCarl.getNetworkSummary({
+      $,
+      params: cleanObject({
+        delegate_user_id: this.delegateUserId,
+      }),
+    });
+
+    const networks = Array.isArray(response?.networks)
+      ? response.networks
+      : [];
+    const linkedin = networks.find(({ key }) => key === "linkedin");
+    const status = linkedin
+      ? `${linkedin.count || 0} LinkedIn connections, sync ${
+        linkedin.needsSync
+          ? "needed"
+          : "ready"
+      }`
+      : `${networks.length} network entries returned`;
+
+    $.export("$summary", status);
+    return response;
+  },
+};

components/super_carl/actions/search-companies/search-companies.mjs

@@ -0,0 +1,116 @@
+import superCarl from "../../super_carl.app.mjs";
+import {
+  cleanObject,
+  countSummary,
+  parseObjectProp,
+  requireQueryOrFilters,
+} from "../../common/utils.mjs";
+
+export default {
+  key: "super_carl-search-companies",
+  name: "Search Companies",
+  description: "Search companies by name, domain, funding, size, industry, location, growth, or technology. [See the documentation](https://supercarl.ai/docs)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    superCarl,
+    query: {
+      propDefinition: [
+        superCarl,
+        "query",
+      ],
+    },
+    filters: {
+      propDefinition: [
+        superCarl,
+        "filters",
+      ],
+    },
+    previewLimit: {
+      propDefinition: [
+        superCarl,
+        "previewLimit",
+      ],
+    },
+    resolveOnly: {
+      type: "boolean",
+      label: "Resolve Only",
+      description: "Return only company disambiguation metadata for a named company, domain, or LinkedIn company URL. Example query values: `stripe.com`, `https://www.linkedin.com/company/stripe`, or `Stripe`.",
+      optional: true,
+      default: false,
+    },
+    resultMode: {
+      type: "string",
+      label: "Result Mode",
+      description: "Level of company-row detail to return. Use `preview` for fast, compact rows, or `detailed` when the workflow needs richer company metadata.",
+      optional: true,
+      default: "preview",
+      options: [
+        "preview",
+        "detailed",
+      ],
+    },
+    rankMode: {
+      type: "string",
+      label: "Rank Mode",
+      description: "Optional ranking mode. Use `default` for normal search order, or `llm` to use a deeper retrieval pool and LLM reranking when company fit matters more than speed.",
+      optional: true,
+      options: [
+        "default",
+        "llm",
+      ],
+    },
+    includeEvidenceText: {
+      type: "boolean",
+      label: "Include Evidence Text",
+      description: "Include supporting evidence text on company rows when available.",
+      optional: true,
+      default: false,
+    },
+    delegateUserId: {
+      propDefinition: [
+        superCarl,
+        "delegateUserId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const filters = parseObjectProp(this.filters, "Filters");
+    requireQueryOrFilters({
+      query: this.query,
+      filters,
+    });
+
+    const response = await this.superCarl.searchCompanies({
+      $,
+      data: cleanObject({
+        query: this.query,
+        filters,
+        preview_limit: this.previewLimit,
+        resolve_only: this.resolveOnly,
+        result_mode: this.resultMode,
+        rank_mode: this.rankMode === "default"
+          ? undefined
+          : this.rankMode,
+        include_evidence_text: this.includeEvidenceText,
+        delegate_user_id: this.delegateUserId,
+      }),
+    });
+
+    const total = response?.pagination?.total
+      ?? response?.result_count
+      ?? response?.result_count_estimate;
+
+    $.export("$summary", countSummary({
+      total,
+      rows: response?.companies,
+      rowLabel: "companies",
+    }));
+    return response;
+  },
+};

components/super_carl/actions/search-jobs/search-jobs.mjs

@@ -0,0 +1,99 @@
+import superCarl from "../../super_carl.app.mjs";
+import {
+  cleanObject,
+  countSummary,
+  parseObjectProp,
+  requireQueryOrFilters,
+} from "../../common/utils.mjs";
+
+export default {
+  key: "super_carl-search-jobs",
+  name: "Search Jobs",
+  description: "Search jobs when the workflow needs hiring-company opportunities, role fit, or warm paths into employers. Use Search People for candidate/advisor discovery, and enable With People when the workflow should return 1st/2nd-degree contacts at each hiring company. [See the documentation](https://supercarl.ai/docs/endpoints)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    superCarl,
+    query: {
+      propDefinition: [
+        superCarl,
+        "query",
+      ],
+    },
+    filters: {
+      propDefinition: [
+        superCarl,
+        "filters",
+      ],
+    },
+    withPeople: {
+      type: "boolean",
+      label: "With People",
+      description: "Include 1st and 2nd degree people at each hiring company.",
+      optional: true,
+      default: false,
+    },
+    previewLimit: {
+      propDefinition: [
+        superCarl,
+        "previewLimit",
+      ],
+    },
+    peoplePerCompany: {
+      type: "integer",
+      label: "People Per Company",
+      description: "Maximum people to include per hiring company when With People is enabled.",
+      optional: true,
+      default: 3,
+      min: 1,
+      max: 10,
+    },
+    ranking: {
+      type: "object",
+      label: "Ranking",
+      description: "Optional ranking configuration JSON, for example `{ \"intent\": \"warm_intro\" }`.",
+      optional: true,
+    },
+    delegateUserId: {
+      propDefinition: [
+        superCarl,
+        "delegateUserId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const filters = parseObjectProp(this.filters, "Filters");
+    const ranking = parseObjectProp(this.ranking, "Ranking");
+    requireQueryOrFilters({
+      query: this.query,
+      filters,
+    });
+
+    const response = await this.superCarl.searchJobs({
+      $,
+      withPeople: this.withPeople,
+      data: cleanObject({
+        query: this.query,
+        filters,
+        preview_limit: this.previewLimit,
+        people_per_company: this.withPeople
+          ? this.peoplePerCompany
+          : undefined,
+        ranking,
+        delegate_user_id: this.delegateUserId,
+      }),
+    });
+
+    $.export("$summary", countSummary({
+      total: response?.total,
+      rows: response?.results,
+      rowLabel: "jobs",
+    }));
+    return response;
+  },
+};

components/super_carl/actions/search-people/search-people.mjs

@@ -0,0 +1,102 @@
+import superCarl from "../../super_carl.app.mjs";
+import {
+  cleanObject,
+  countSummary,
+  parseObjectProp,
+  requireQueryOrFilters,
+} from "../../common/utils.mjs";
+
+export default {
+  key: "super_carl-search-people",
+  name: "Search People",
+  description: "Search people by role, company history, expertise, location, network relationship, or recent activity. Keep Preview enabled for fast counts and lightweight rows; disable Preview when you need full rows and Evidence Format, since Evidence Format is ignored during preview. Use Search Companies first when a named employer is ambiguous. [See the documentation](https://supercarl.ai/docs/endpoints)",
+  version: "0.0.1",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  type: "action",
+  props: {
+    superCarl,
+    query: {
+      propDefinition: [
+        superCarl,
+        "query",
+      ],
+    },
+    filters: {
+      propDefinition: [
+        superCarl,
+        "filters",
+      ],
+    },
+    preview: {
+      type: "boolean",
+      label: "Preview",
+      description: "Use the fast preview route. Turn off for full rows with selected evidence detail.",
+      optional: true,
+      default: true,
+    },
+    limit: {
+      propDefinition: [
+        superCarl,
+        "limit",
+      ],
+    },
+    offset: {
+      propDefinition: [
+        superCarl,
+        "offset",
+      ],
+    },
+    evidenceFormat: {
+      propDefinition: [
+        superCarl,
+        "evidenceFormat",
+      ],
+    },
+    relationshipDetail: {
+      propDefinition: [
+        superCarl,
+        "relationshipDetail",
+      ],
+    },
+    delegateUserId: {
+      propDefinition: [
+        superCarl,
+        "delegateUserId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const filters = parseObjectProp(this.filters, "Filters");
+    requireQueryOrFilters({
+      query: this.query,
+      filters,
+    });
+
+    const response = await this.superCarl.searchPeople({
+      $,
+      preview: this.preview,
+      data: cleanObject({
+        query: this.query,
+        filters,
+        limit: this.limit,
+        offset: this.offset,
+        evidence_format: this.preview
+          ? undefined
+          : this.evidenceFormat,
+        relationship_detail: this.relationshipDetail,
+        delegate_user_id: this.delegateUserId,
+      }),
+    });
+
+    $.export("$summary", countSummary({
+      total: response?.total_count ?? response?.total,
+      rows: response?.users,
+      rowLabel: "people",
+    }));
+    return response;
+  },
+};