@thejob/groups-client

Typed client for the thejob-group-service HTTP API. One method per endpoint.

import { GroupsClient } from '@thejob/groups-client';

const groups = new GroupsClient({
  baseUrl: process.env.GROUP_SERVICE_URL!,
  apiKey: process.env.GROUP_SERVICE_API_KEY, // backend-to-backend
});

const { results, total } = await groups.listGroups({
  filter: { status: ['active'], isDiscoverable: true },
  limit: 6,
});

total is the count for the FILTER, not the number of rows returned, so a digest showing six cards under "14 groups" stays honest when limit changes.

The filter is nested, unlike jobs/users

This is the one place this client differs from @thejob/jobs-client and @thejob/users-client, and it is worth knowing before you hand-build a URL.

Those services read facets from the top level. group-service reads them from a filter[...] wrapper and splits each value on commas:

{ filter: { countries: ['in', 'se'] } }   ->   ?filter[countries]=in,se

The client owns that encoding. Two consequences you would otherwise hit:

• Never send a nested array. filter[countries][0]=in makes the service's greedy /^filter\[(.+)\]$/ read the field name as countries][0, which used to mean 200 OK with zero rows and no error. The service now rejects it with a 400, and this client never produces it.
• A filter value cannot contain a comma. The service splits unconditionally with no escape convention, so the client throws rather than let a value shred into terms that match nothing.

Facets

The vocabulary is GroupFilterSchema in @thejob/schema — the same declaration group-service validates incoming keys against, so a facet cannot exist on one side and not the other. An unknown key is a 400 that lists what is supported.

countries and featuredMarkets are stored LOWERCASE (in, se, ww), unlike the uppercase ISO codes users and jobs use. Send them lowercase.

Auth

apiKey sends x-api-key (backend-to-backend). token sends Authorization: Bearer for the user-scoped routes (joining, inviting, anything behind requireUser).

Any non-2xx throws GroupsClientError, carrying status and the parsed body.