@uidu/client 3.19.0 → 3.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uidu/client",
3
- "version": "3.19.0",
3
+ "version": "3.21.0",
4
4
  "description": "Typed GraphQL client for the uidu platform. Server-first, framework-agnostic.",
5
5
  "license": "MIT",
6
6
  "author": "uidu",
package/src/candidates.ts CHANGED
@@ -1,13 +1,23 @@
1
1
  import type { UiduClient } from './client';
2
2
  import {
3
+ CreateCandidateDocument,
4
+ type CreateCandidateMutationVariables,
3
5
  CreatePoolContactDocument,
4
6
  type CreatePoolContactMutationVariables,
7
+ DeletePoolContactDocument,
8
+ type DeletePoolContactMutationVariables,
5
9
  FindCandidatesDocument,
6
10
  type FindCandidatesQuery,
7
11
  type FindCandidatesQueryVariables,
8
12
  GetCandidateDocument,
9
13
  type GetCandidateQuery,
10
14
  type GetCandidateQueryVariables,
15
+ GetPoolDocument,
16
+ type GetPoolQuery,
17
+ type GetPoolQueryVariables,
18
+ ListCandidatesDocument,
19
+ type ListCandidatesQuery,
20
+ type ListCandidatesQueryVariables,
11
21
  ListPoolsDocument,
12
22
  type ListPoolsQuery,
13
23
  type ListPoolsQueryVariables,
@@ -20,6 +30,10 @@ import { nodes } from './utils/relay';
20
30
  // the person's `user` and `contact` with their pool consent and retention.
21
31
  // `Pool`s group contacts (a `PoolContact` is one contact in one pool).
22
32
  //
33
+ // A candidate's `sourceChannel` says how they arrived (`application`, `pool`,
34
+ // `import`, `manual`); `source` is the record they came through — an
35
+ // Application, a Pool, an Organization (e.g. the referring agency) or a User.
36
+ //
23
37
  // Everything here holds private personal data: reads and writes need an
24
38
  // account (Bearer / apiKey), server-side.
25
39
 
@@ -38,14 +52,42 @@ export type Pool = NonNullable<
38
52
  >[number]
39
53
  >['node']
40
54
  >;
55
+ export type CandidateListItem = NonNullable<
56
+ NonNullable<
57
+ NonNullable<
58
+ NonNullable<
59
+ ListCandidatesQuery['currentWorkspace']
60
+ >['candidates']['edges']
61
+ >[number]
62
+ >['node']
63
+ >;
64
+ export type PoolDetail = NonNullable<
65
+ NonNullable<GetPoolQuery['currentWorkspace']>['pool']
66
+ >;
67
+ export type PoolContact = NonNullable<
68
+ NonNullable<NonNullable<PoolDetail['poolContacts']['edges']>[number]>['node']
69
+ >;
70
+
71
+ /**
72
+ * The workspace's candidates with their custom fields, filtered with
73
+ * `params.filters` — `poolIds` (in), `source` (in, the GlobalIDs of the
74
+ * Application, Pool, Organization or User they came through) and
75
+ * `lastInteractionAt` (`>=`, `<=`, `between`); page with `first`/`after`.
76
+ */
77
+ export async function listCandidates(
78
+ client: UiduClient,
79
+ variables: ListCandidatesQueryVariables = {},
80
+ ): Promise<CandidateListItem[]> {
81
+ const result = await client.query(ListCandidatesDocument, variables);
82
+ return nodes(result.currentWorkspace?.candidates);
83
+ }
41
84
 
42
85
  /**
43
86
  * Rank the talent pool against a description (`term`) — and, with `callId`,
44
87
  * that call's applications too — and return the `candidates`, `applications`
45
88
  * and per-record `evidence`, or null when the viewer may not search.
46
89
  *
47
- * This is the only way to list candidates: the workspace has no plain
48
- * `candidates` connection. A blank `term` with a `callId` uses the call's own
90
+ * For a plain filtered list use {@link listCandidates}. A blank `term` with a `callId` uses the call's own
49
91
  * words; `near` + `withinKm` keep only those living close enough, and
50
92
  * `eligibleFor` only those of an age the contract allows.
51
93
  */
@@ -71,7 +113,22 @@ export async function getCandidate(
71
113
  }
72
114
 
73
115
  /**
74
- * Update a candidate: pool consent (`poolConsentAt`), `source`, or
116
+ * Add someone to the talent pool as a candidate: `attributes: { userId,
117
+ * sourceChannel?, sourceId?, poolConsentAt?, fieldValues? }`, where `sourceId`
118
+ * is the GlobalID of the Application, Pool, Organization or User they came
119
+ * through. Returns the mutation payload as-is (including any `errors`).
120
+ */
121
+ export async function createCandidate(
122
+ client: UiduClient,
123
+ variables: CreateCandidateMutationVariables,
124
+ ) {
125
+ const result = await client.mutate(CreateCandidateDocument, variables);
126
+ return result.createCandidate ?? null;
127
+ }
128
+
129
+ /**
130
+ * Update a candidate: pool consent (`poolConsentAt`), where they came from
131
+ * (`sourceChannel` + `sourceId`), custom `fieldValues`, or
75
132
  * `extendRetention: true` to push `retainUntil` out by another retention
76
133
  * period. Returns the mutation payload as-is (including any `errors`).
77
134
  */
@@ -92,6 +149,18 @@ export async function listPools(
92
149
  return nodes(result.currentWorkspace?.pools);
93
150
  }
94
151
 
152
+ /**
153
+ * One talent pool by GlobalID with a page of the contacts in it (`first` /
154
+ * `after`), or null.
155
+ */
156
+ export async function getPool(
157
+ client: UiduClient,
158
+ variables: GetPoolQueryVariables,
159
+ ): Promise<PoolDetail | null> {
160
+ const result = await client.query(GetPoolDocument, variables);
161
+ return result.currentWorkspace?.pool ?? null;
162
+ }
163
+
95
164
  /**
96
165
  * Add a contact to a pool (`attributes: { poolId, contactId }`). Returns the
97
166
  * mutation payload as-is (including any `errors`).
@@ -103,3 +172,15 @@ export async function createPoolContact(
103
172
  const result = await client.mutate(CreatePoolContactDocument, variables);
104
173
  return result.createPoolContact ?? null;
105
174
  }
175
+
176
+ /**
177
+ * Take a contact out of a pool, by the PoolContact's GlobalID. Returns the
178
+ * mutation payload as-is (including any `errors`).
179
+ */
180
+ export async function deletePoolContact(
181
+ client: UiduClient,
182
+ variables: DeletePoolContactMutationVariables,
183
+ ) {
184
+ const result = await client.mutate(DeletePoolContactDocument, variables);
185
+ return result.deletePoolContact ?? null;
186
+ }
@@ -0,0 +1,97 @@
1
+ import { beforeEach, describe, expect, it, vi } from 'vitest';
2
+
3
+ const request = vi.fn();
4
+
5
+ vi.mock('graphql-request', () => ({
6
+ GraphQLClient: class {
7
+ request = request;
8
+ },
9
+ ClientError: class extends Error {},
10
+ }));
11
+
12
+ const { createClient } = await import('./client');
13
+ const contracts = await import('./contracts');
14
+
15
+ const client = createClient({
16
+ endpoint: 'https://acme.uidu.org/graphql',
17
+ apiKey: 'key',
18
+ });
19
+
20
+ beforeEach(() => request.mockReset());
21
+
22
+ describe('writes', () => {
23
+ it('createContract sends its attributes, custom values included, and returns the payload', async () => {
24
+ const payload = { contract: { node: { id: 'c1' } }, errors: [] };
25
+ request.mockResolvedValue({ createContract: payload });
26
+ const input = {
27
+ attributes: {
28
+ workspaceId: 'w1',
29
+ name: 'JET HR',
30
+ startsOn: '2027-01-01',
31
+ counterpartId: 'o1',
32
+ fieldValues: { f1: 1.21 },
33
+ },
34
+ };
35
+
36
+ await expect(contracts.createContract(client, { input })).resolves.toEqual(
37
+ payload,
38
+ );
39
+ expect(JSON.stringify(request.mock.calls[0][0])).toContain(
40
+ 'createContract',
41
+ );
42
+ expect(request.mock.calls[0][1]).toEqual({ input });
43
+ });
44
+
45
+ it('activateContract signs it', async () => {
46
+ request.mockResolvedValue({
47
+ activateContract: {
48
+ contract: { id: 'c1', aasmState: 'active' },
49
+ errors: [],
50
+ },
51
+ });
52
+
53
+ const result = await contracts.activateContract(client, {
54
+ input: { id: 'c1' },
55
+ });
56
+
57
+ expect(result?.contract?.aasmState).toBe('active');
58
+ });
59
+
60
+ it('discardContract goes through the trash', async () => {
61
+ request.mockResolvedValue({
62
+ discardableDiscard: { discardable: { id: 'c1' }, errors: [] },
63
+ });
64
+
65
+ await contracts.discardContract(client, { input: { id: 'c1' } });
66
+
67
+ expect(JSON.stringify(request.mock.calls[0][0])).toContain(
68
+ 'discardableDiscard',
69
+ );
70
+ });
71
+
72
+ it('createContractItem adds a line in cents', async () => {
73
+ const payload = {
74
+ contractItem: { node: { id: 'i1', unitAmount: 9_050_000 } },
75
+ errors: [],
76
+ };
77
+ request.mockResolvedValue({ createContractItem: payload });
78
+ const input = {
79
+ attributes: { contractId: 'c1', unitAmount: 9_050_000, quantity: 1 },
80
+ };
81
+
82
+ await expect(
83
+ contracts.createContractItem(client, { input }),
84
+ ).resolves.toEqual(payload);
85
+ expect(request.mock.calls[0][1]).toEqual({ input });
86
+ });
87
+
88
+ it('returns null when the mutation has no payload', async () => {
89
+ request.mockResolvedValue({ updateContract: null });
90
+
91
+ await expect(
92
+ contracts.updateContract(client, {
93
+ input: { id: 'c1', attributes: { name: 'x' } },
94
+ }),
95
+ ).resolves.toBeNull();
96
+ });
97
+ });
package/src/contracts.ts CHANGED
@@ -1,5 +1,19 @@
1
1
  import type { UiduClient } from './client';
2
2
  import {
3
+ ActivateContractDocument,
4
+ type ActivateContractMutationVariables,
5
+ CreateContractDocument,
6
+ CreateContractItemDocument,
7
+ type CreateContractItemMutationVariables,
8
+ type CreateContractMutationVariables,
9
+ DeleteContractItemDocument,
10
+ type DeleteContractItemMutationVariables,
11
+ DiscardContractDocument,
12
+ type DiscardContractMutationVariables,
13
+ UpdateContractDocument,
14
+ UpdateContractItemDocument,
15
+ type UpdateContractItemMutationVariables,
16
+ type UpdateContractMutationVariables,
3
17
  GetContractDocument,
4
18
  type GetContractQuery,
5
19
  type GetContractQueryVariables,
@@ -12,7 +26,11 @@ import { nodes } from './utils/relay';
12
26
  // Contracts: an agreement with a counterpart (a Contact or an Organization),
13
27
  // booked on an analytic account. Like deals, a contract carries the custom
14
28
  // fields the workspace added to it: read them as `fieldValuesByShortname`
15
- // (`{ shortname: value }`) or `fieldValues`. Reads need an account (Bearer).
29
+ // (`{ shortname: value }`) or `fieldValues`, write them as `fieldValues`
30
+ // (`{ fieldGlobalId: value }`) on create and update. A contract is a draft
31
+ // until `activateContract` signs it; its money is in `contractItems`, one line
32
+ // each with an amount in cents and its own dates. The sector a contract
33
+ // belongs to is `analyticAccount.effectiveResponsibleCircle`.
16
34
 
17
35
  export type Contract = NonNullable<
18
36
  NonNullable<
@@ -42,3 +60,80 @@ export async function getContract(
42
60
  const result = await client.query(GetContractDocument, variables);
43
61
  return result.currentWorkspace?.contract ?? null;
44
62
  }
63
+
64
+ /**
65
+ * Create a contract: `{ input: { attributes: { workspaceId, name, startsOn,
66
+ * endsOn, counterpartId, analyticAccountId, fieldValues } } }`. `counterpartId`
67
+ * is an Organization or Contact (see `createOrganization` for a new client).
68
+ * The new contract starts as a draft. Returns the payload (with `errors`) or
69
+ * null; the contract is at `contract.node`.
70
+ */
71
+ export async function createContract(
72
+ client: UiduClient,
73
+ variables: CreateContractMutationVariables,
74
+ ) {
75
+ const result = await client.mutate(CreateContractDocument, variables);
76
+ return result.createContract ?? null;
77
+ }
78
+
79
+ /**
80
+ * Update a contract's terms, client, analytic account or custom `fieldValues`:
81
+ * `{ input: { id, attributes } }`. Returns the payload (with `errors`) or null.
82
+ */
83
+ export async function updateContract(
84
+ client: UiduClient,
85
+ variables: UpdateContractMutationVariables,
86
+ ) {
87
+ const result = await client.mutate(UpdateContractDocument, variables);
88
+ return result.updateContract ?? null;
89
+ }
90
+
91
+ /** Sign a draft contract (draft → active): `{ input: { id } }`. Returns the payload or null. */
92
+ export async function activateContract(
93
+ client: UiduClient,
94
+ variables: ActivateContractMutationVariables,
95
+ ) {
96
+ const result = await client.mutate(ActivateContractDocument, variables);
97
+ return result.activateContract ?? null;
98
+ }
99
+
100
+ /** Move a contract to the trash (restorable for 30 days): `{ input: { id } }`. Returns the payload or null. */
101
+ export async function discardContract(
102
+ client: UiduClient,
103
+ variables: DiscardContractMutationVariables,
104
+ ) {
105
+ const result = await client.mutate(DiscardContractDocument, variables);
106
+ return result.discardableDiscard ?? null;
107
+ }
108
+
109
+ /**
110
+ * Add an economic line to a contract: `{ input: { attributes: { contractId,
111
+ * description, quantity, unitAmount, startsAt, endsAt } } }`, with
112
+ * `unitAmount` in cents. Returns the payload (with `errors`) or null; the line
113
+ * is at `contractItem.node`.
114
+ */
115
+ export async function createContractItem(
116
+ client: UiduClient,
117
+ variables: CreateContractItemMutationVariables,
118
+ ) {
119
+ const result = await client.mutate(CreateContractItemDocument, variables);
120
+ return result.createContractItem ?? null;
121
+ }
122
+
123
+ /** Update a contract line: `{ input: { id, attributes } }`. Returns the payload (with `errors`) or null. */
124
+ export async function updateContractItem(
125
+ client: UiduClient,
126
+ variables: UpdateContractItemMutationVariables,
127
+ ) {
128
+ const result = await client.mutate(UpdateContractItemDocument, variables);
129
+ return result.updateContractItem ?? null;
130
+ }
131
+
132
+ /** Remove a contract line: `{ input: { id } }`. Returns the payload or null. */
133
+ export async function deleteContractItem(
134
+ client: UiduClient,
135
+ variables: DeleteContractItemMutationVariables,
136
+ ) {
137
+ const result = await client.mutate(DeleteContractItemDocument, variables);
138
+ return result.deleteContractItem ?? null;
139
+ }