Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

6.1 KB
Raw Blame
import { z } from 'zod';
import { ApiKeyRole } from '../../../modules/auth/entities/api-key.entity';
import type { GroupService } from '../../../modules/group/group.service';
import {
  GROUP_DESCRIPTION_MAX_LENGTH,
  GROUP_NAME_MAX_LENGTH,
  GROUP_PARTICIPANTS_MAX,
} from '../../../modules/group/dto/group.dto';
import { defineTool, type AnyToolDescriptor } from '../tool-descriptor';
import { paginate } from '../../../common/utils/paginate';

const sessionId = z.string().min(1).describe('Session UUID (the session id, not the name)');

export function groupTools(group: GroupService): AnyToolDescriptor[] {
  return [
    defineTool({
      name: 'GroupFindAll',
      chatScope: 'filtered',
      description: 'List all groups the session is a member of. Use limit/offset to page.',
      tier: 'read',
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        limit: z.number().int().min(1).max(1000).optional(),
        offset: z.number().int().min(0).optional(),
      }),
      handler: async (input, apiKey, chatScope) => {
        if (!chatScope?.isRestricted(apiKey)) {
          return group.getGroups(input.sessionId, { limit: input.limit, offset: input.offset });
        }
        const visible = await chatScope.filter(apiKey, await group.listGroups(input.sessionId), item => item.id);
        return paginate(visible, input.limit, input.offset);
      },
    }),
    defineTool({
      name: 'GroupFindOne',
      chatScope: ['groupId'],
      description: 'Get detailed info for a specific group including participants list.',
      tier: 'read',
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        groupId: z.string().min(1).describe('Group JID (e.g. [email protected])'),
      }),
      handler: input => group.getGroupInfo(input.sessionId, input.groupId),
    }),
    defineTool({
      name: 'GroupGetInviteCode',
      description:
        'Get the invite code and link for a group. Requires OPERATOR role: the code is a ' +
        'transferable join capability, not plain read data.',
      tier: 'read',
      requiredRole: ApiKeyRole.OPERATOR,
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        groupId: z.string().min(1).describe('Group JID (e.g. [email protected])'),
      }),
      handler: async input => {
        const inviteCode = await group.getGroupInviteCode(input.sessionId, input.groupId);
        return { inviteCode, inviteLink: `https://chat.whatsapp.com/${inviteCode}` };
      },
    }),
    defineTool({
      name: 'GroupCreate',
      description:
        'Create a new WhatsApp group with a name and initial participants. ' +
        'Requires the Baileys engine; whatsapp-web.js answers 501 and a retry cannot succeed. Requires OPERATOR role.',
      tier: 'write',
      requiredRole: ApiKeyRole.OPERATOR,
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        name: z.string().min(1).max(GROUP_NAME_MAX_LENGTH).describe('Group subject/name'),
        participants: z
          .array(z.string())
          .min(1)
          .max(GROUP_PARTICIPANTS_MAX)
          .describe('Participant WhatsApp JIDs (e.g. [email protected])'),
      }),
      handler: input => group.createGroup(input.sessionId, input.name, input.participants),
    }),
    defineTool({
      name: 'GroupAddParticipants',
      description:
        'Add participants to an existing group. The returned `results` carry the per-participant outcome (a partial refusal does not fail the batch). Requires OPERATOR role.',
      tier: 'write',
      requiredRole: ApiKeyRole.OPERATOR,
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        groupId: z.string().min(1).describe('Group JID (e.g. [email protected])'),
        participants: z
          .array(z.string())
          .min(1)
          .max(GROUP_PARTICIPANTS_MAX)
          .describe('Participant WhatsApp JIDs to add'),
      }),
      handler: async input => {
        const results = await group.addParticipants(input.sessionId, input.groupId, input.participants);
        // Derive the verdict from the per-participant outcomes instead of asserting it: a batch in
        // which every participant was refused (not registered, already a member) must not report
        // success to an agent that only reads the top-level fields.
        const added = results.filter(r => r.success).length;
        return {
          success: added > 0,
          message:
            added === results.length
              ? 'Participants added'
              : `${added}/${results.length} participants added; see results for per-participant outcomes`,
          results,
        };
      },
    }),
    defineTool({
      name: 'GroupSetSubject',
      chatScope: ['groupId'],
      description: 'Change the group name/subject. Requires OPERATOR role.',
      tier: 'write',
      destructive: true,
      requiredRole: ApiKeyRole.OPERATOR,
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        groupId: z.string().min(1).describe('Group JID (e.g. [email protected])'),
        subject: z.string().min(1).max(GROUP_NAME_MAX_LENGTH).describe('New group subject/name'),
      }),
      handler: async input => {
        await group.setGroupSubject(input.sessionId, input.groupId, input.subject);
        return { success: true, message: 'Group subject updated' };
      },
    }),
    defineTool({
      name: 'GroupSetDescription',
      chatScope: ['groupId'],
      description: 'Change the group description. Pass empty string to clear it. Requires OPERATOR role.',
      tier: 'write',
      destructive: true,
      requiredRole: ApiKeyRole.OPERATOR,
      sessionScoped: true,
      inputSchema: z.object({
        sessionId,
        groupId: z.string().min(1).describe('Group JID (e.g. [email protected])'),
        description: z
          .string()
          .max(GROUP_DESCRIPTION_MAX_LENGTH)
          .describe('New group description (may be empty to clear)'),
      }),
      handler: async input => {
        await group.setGroupDescription(input.sessionId, input.groupId, input.description);
        return { success: true, message: 'Group description updated' };
      },
    }),
  ];
}