Bonusly search by company, participations and reward redemption integrations with MCP optimized (#21701)

Author: Priyadharshan-Pdm

components/bonusly/actions/get-company-participation-report/get-company-participation-report.mjs

@@ -0,0 +1,68 @@
+// x-pd-ai: optimized
+import bonusly from "../../bonusly.app.mjs";
+
+export default {
+  key: "bonusly-get-company-participation-report",
+  name: "Get Company Participation Report",
+  description: "Return company-level recognition participation analytics - giving/receiving rates by group (department, location, etc.) or by manager and team, for a given date range. [See the documentation](https://docs.bonus.ly/reference/adminparticipationreport-1)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    bonusly,
+    reportView: {
+      type: "string",
+      label: "Report View",
+      description: "Which participation view to return.",
+      options: [
+        "giving_and_receiving",
+        "managers_and_teams",
+      ],
+    },
+    startDate: {
+      propDefinition: [
+        bonusly,
+        "startDate",
+      ],
+      description: "Start of the report's date range, in `YYYY-MM-DD` format, e.g. `2026-01-01`.",
+      optional: false,
+    },
+    endDate: {
+      propDefinition: [
+        bonusly,
+        "endDate",
+      ],
+      description: "End of the report's date range, in `YYYY-MM-DD` format, e.g. `2026-06-30`. Bonusly cannot report on the current or an ongoing month, so this must be no later than the last day of the previous month - for example, any time during August 2026 the latest valid value is `2026-07-31`. A later date is rejected.",
+      optional: false,
+    },
+    customPropertyGroup: {
+      type: "string",
+      label: "Custom Property Group",
+      description: "Grouping dimension to break the `giving_and_receiving` view down by, e.g. `department` or `location`. Ignored for the `managers_and_teams` view.",
+      optional: true,
+    },
+    includeTrend: {
+      type: "boolean",
+      label: "Include Trend",
+      description: "Set to `true` to include trend data alongside the current period's metrics.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.bonusly.getAdminParticipationReport({
+      $,
+      reportView: this.reportView,
+      startDate: this.startDate,
+      endDate: this.endDate,
+      customPropertyGroup: this.customPropertyGroup,
+      includeTrend: this.includeTrend,
+    });
+
+    $.export("$summary", `Retrieved ${this.reportView} participation report for ${this.startDate} to ${this.endDate}`);
+    return response;
+  },
+};

components/bonusly/actions/give-bonus/give-bonus.mjs

@@ -0,0 +1,56 @@
+// x-pd-ai: optimized
+import bonusly from "../../bonusly.app.mjs";
+
+export default {
+  key: "bonusly-give-bonus",
+  name: "Give Bonus",
+  description: "Send recognition (a bonus) to one or more colleagues on behalf of the authenticated caller. Do not include `@mentions` or the point amount in the `reason` yourself - Bonusly synthesizes those from `recipients` and `amount` automatically. [See the documentation](https://docs.bonus.ly/reference/giverecognition-1)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    bonusly,
+    recipients: {
+      type: "string[]",
+      label: "Recipients",
+      description: "One or more recipients - each entry can be a user ID, an email address, or a display name, e.g. `john.smith@company.com`. Use **Search Users** to look up one person by name, or **List Users In Department**, **List Users In Location**, or **List Top-Level Users** to recognize a whole roster at once.",
+    },
+    amount: {
+      type: "integer",
+      label: "Amount",
+      description: "Points to give. Pass `0` only if your company allows zero-point recognition.",
+      min: 0,
+    },
+    reason: {
+      type: "string",
+      label: "Reason",
+      description: "Free-form recognition message explaining why you're giving this bonus, e.g. `Great work on the product launch!`.",
+    },
+    hashtag: {
+      type: "string",
+      label: "Hashtag",
+      description: "One company hashtag, without the leading `#`, e.g. `teamwork`. Some Bonusly companies require a hashtag on every recognition - if the tool rejects the request for a missing hashtag, set one here.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.bonusly.giveRecognition({
+      $,
+      recipients: this.recipients,
+      amount: this.amount,
+      reason: this.reason,
+      hashtag: this.hashtag,
+    });
+
+    const names = response.recipients?.map(({ name }) => name).join(", ");
+    const bonusId = response.bonus_id
+      ? ` (bonus ID: ${response.bonus_id})`
+      : "";
+    $.export("$summary", `Gave ${this.amount} points to ${names || "recipient(s)"}${bonusId}`);
+    return response;
+  },
+};

components/bonusly/actions/list-departments/list-departments.mjs

@@ -0,0 +1,52 @@
+// x-pd-ai: optimized
+import bonusly from "../../bonusly.app.mjs";
+
+export default {
+  key: "bonusly-list-departments",
+  name: "List Departments",
+  description: "List the distinct departments configured for users in the authenticated caller's company, with a user count for each. Call this first to discover the exact department names accepted by **List Users In Department**, which matches exactly and returns nothing for a misspelled or differently-cased name. [See the documentation](https://docs.bonus.ly/reference/listdepartments)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    bonusly,
+    search: {
+      propDefinition: [
+        bonusly,
+        "search",
+      ],
+      description: "Narrow the results to departments whose name starts with this text, e.g. `Eng` matches `Engineering`. This is a prefix match, so it will not match text in the middle of a name. Omit to return every department.",
+    },
+    pageSize: {
+      propDefinition: [
+        bonusly,
+        "pageSize",
+      ],
+      description: "Maximum number of departments to return in this page. Defaults to Bonusly's standard page size if omitted.",
+    },
+    cursor: {
+      propDefinition: [
+        bonusly,
+        "cursor",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.bonusly.listDepartments({
+      $,
+      search: this.search,
+      pageSize: this.pageSize,
+      cursor: this.cursor,
+    });
+
+    const morePages = response.next_cursor
+      ? " (more pages available)"
+      : "";
+    $.export("$summary", `Found ${response.departments?.length ?? 0} department(s)${morePages}`);
+    return response;
+  },
+};

components/bonusly/actions/list-locations/list-locations.mjs

@@ -0,0 +1,52 @@
+// x-pd-ai: optimized
+import bonusly from "../../bonusly.app.mjs";
+
+export default {
+  key: "bonusly-list-locations",
+  name: "List Locations",
+  description: "List the distinct locations configured for users in the authenticated caller's company, with a user count for each. Call this first to discover the exact location names accepted by **List Users In Location**, which matches exactly and returns nothing for a misspelled or differently-cased name. [See the documentation](https://docs.bonus.ly/reference/listlocations)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    bonusly,
+    search: {
+      propDefinition: [
+        bonusly,
+        "search",
+      ],
+      description: "Narrow the results to locations whose name starts with this text, e.g. `Ber` matches `Berlin`. This is a prefix match, so it will not match text in the middle of a name. Omit to return every location.",
+    },
+    pageSize: {
+      propDefinition: [
+        bonusly,
+        "pageSize",
+      ],
+      description: "Maximum number of locations to return in this page. Defaults to Bonusly's standard page size if omitted.",
+    },
+    cursor: {
+      propDefinition: [
+        bonusly,
+        "cursor",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.bonusly.listLocations({
+      $,
+      search: this.search,
+      pageSize: this.pageSize,
+      cursor: this.cursor,
+    });
+
+    const morePages = response.next_cursor
+      ? " (more pages available)"
+      : "";
+    $.export("$summary", `Found ${response.locations?.length ?? 0} location(s)${morePages}`);
+    return response;
+  },
+};

components/bonusly/actions/list-reward-redemptions/list-reward-redemptions.mjs

@@ -0,0 +1,101 @@
+// x-pd-ai: optimized
+import bonusly from "../../bonusly.app.mjs";
+
+export default {
+  key: "bonusly-list-reward-redemptions",
+  name: "List Reward Redemptions",
+  description: "Return paginated reward redemption records for the caller's company, with optional filtering by user email, date range, and fulfillment status. This is a company-wide admin report, not just the caller's own redemptions. [See the documentation](https://docs.bonus.ly/reference/adminrewardsredemptionsreport-1)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    bonusly,
+    userEmail: {
+      type: "string",
+      label: "User Email",
+      description: "Filter to redemptions made by this user's email address, e.g. `john.smith@company.com`.",
+      optional: true,
+    },
+    startDate: {
+      propDefinition: [
+        bonusly,
+        "startDate",
+      ],
+      description: "Only include redemptions on or after this date, e.g. `2026-01-01`.",
+    },
+    endDate: {
+      propDefinition: [
+        bonusly,
+        "endDate",
+      ],
+      description: "Only include redemptions on or before this date, e.g. `2026-06-30`.",
+    },
+    unfulfilled: {
+      type: "boolean",
+      label: "Unfulfilled Only",
+      description: "Set to `true` to return only redemptions that haven't been fulfilled yet.",
+      optional: true,
+    },
+    aasmState: {
+      type: "string",
+      label: "State",
+      description: "Filter by the redemption's internal state (e.g. `approved`, `pending`, `declined`). Bonusly's docs don't publish the full list of accepted values, so confirm against a real redemption's `aasm_state` field if this filter returns no results. Leave blank to include redemptions in any state.",
+      optional: true,
+    },
+    range: {
+      type: "string",
+      label: "Range",
+      description: "A predefined date range shortcut, if supported by your Bonusly plan (e.g. `this_month`). `Start Date`/`End Date` take precedence when both are set.",
+      optional: true,
+    },
+    page: {
+      type: "integer",
+      label: "Page",
+      description: "Page number to fetch, starting at `1`.",
+      min: 1,
+      optional: true,
+    },
+    perPage: {
+      type: "integer",
+      label: "Per Page",
+      description: "Number of redemptions to return per page.",
+      min: 1,
+      max: 100,
+      optional: true,
+    },
+    sort: {
+      type: "string",
+      label: "Sort Field",
+      description: "Field to sort results by, e.g. `created_at`.",
+      optional: true,
+    },
+    direction: {
+      type: "string",
+      label: "Sort Direction",
+      description: "Sort direction for the `Sort Field`, e.g. `asc` or `desc`.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.bonusly.getAdminRewardsRedemptionsReport({
+      $,
+      userEmail: this.userEmail,
+      startDate: this.startDate,
+      endDate: this.endDate,
+      unfulfilled: this.unfulfilled,
+      aasmState: this.aasmState,
+      range: this.range,
+      page: this.page,
+      perPage: this.perPage,
+      sort: this.sort,
+      direction: this.direction,
+    });
+
+    $.export("$summary", `Found ${response.pagination?.total_count ?? 0} reward redemption(s)`);
+    return response;
+  },
+};

components/bonusly/actions/list-top-level-users/list-top-level-users.mjs

@@ -0,0 +1,52 @@
+// x-pd-ai: optimized
+import bonusly from "../../bonusly.app.mjs";
+
+export default {
+  key: "bonusly-list-top-level-users",
+  name: "List Top-Level Users",
+  description: "List the users in the authenticated caller's company who have no manager - the roots of the org chart, typically executives. Use this to answer who sits at the top of the company, or as a starting point when you have no other identifier to work from. Takes no required input. [See the documentation](https://docs.bonus.ly/reference/listtoplevelusers)",
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    bonusly,
+    search: {
+      propDefinition: [
+        bonusly,
+        "search",
+      ],
+      description: "Narrow the results by matching this text against user names or emails, e.g. `john` or `john.smith@company.com`. Omit to return every top-level user.",
+    },
+    pageSize: {
+      propDefinition: [
+        bonusly,
+        "pageSize",
+      ],
+      description: "Maximum number of users to return in this page. Defaults to Bonusly's standard page size if omitted.",
+    },
+    cursor: {
+      propDefinition: [
+        bonusly,
+        "cursor",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.bonusly.listTopLevelUsers({
+      $,
+      search: this.search,
+      pageSize: this.pageSize,
+      cursor: this.cursor,
+    });
+
+    const morePages = response.next_cursor
+      ? " (more pages available)"
+      : "";
+    $.export("$summary", `Found ${response.users?.length ?? 0} top-level user(s)${morePages}`);
+    return response;
+  },
+};