@clikgate/node 2.0.1 → 2.1.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.
Files changed (74) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +116 -7
  3. package/SECURITY.md +2 -1
  4. package/dist/cjs/client.d.ts +38 -10
  5. package/dist/cjs/client.js +50 -16
  6. package/dist/cjs/currency.d.ts +7 -0
  7. package/dist/cjs/currency.js +75 -0
  8. package/dist/cjs/enums.js +1 -1
  9. package/dist/cjs/event-types.d.ts +108 -0
  10. package/dist/cjs/event-types.js +109 -0
  11. package/dist/cjs/express.d.ts +11 -2
  12. package/dist/cjs/express.js +3 -2
  13. package/dist/cjs/fastify.d.ts +4 -1
  14. package/dist/cjs/fastify.js +3 -2
  15. package/dist/cjs/generated/index.d.ts +1759 -86
  16. package/dist/cjs/generated/index.js +1 -1
  17. package/dist/cjs/identity.js +1 -1
  18. package/dist/cjs/index.d.ts +9 -1
  19. package/dist/cjs/index.js +15 -1
  20. package/dist/cjs/installation.d.ts +47 -0
  21. package/dist/cjs/installation.js +83 -0
  22. package/dist/cjs/lookups.d.ts +128 -0
  23. package/dist/cjs/lookups.js +149 -0
  24. package/dist/cjs/models.d.ts +342 -0
  25. package/dist/cjs/models.js +2 -0
  26. package/dist/cjs/next.d.ts +22 -0
  27. package/dist/cjs/next.js +20 -0
  28. package/dist/cjs/pager.d.ts +5 -0
  29. package/dist/cjs/pager.js +40 -0
  30. package/dist/cjs/referrals.d.ts +169 -0
  31. package/dist/cjs/referrals.js +208 -0
  32. package/dist/cjs/resources.d.ts +34 -5
  33. package/dist/cjs/resources.js +43 -42
  34. package/dist/cjs/types.d.ts +57 -10
  35. package/dist/cjs/version.d.ts +1 -1
  36. package/dist/cjs/version.js +1 -1
  37. package/dist/cjs/webhooks.d.ts +3 -2
  38. package/dist/cjs/webhooks.js +43 -2
  39. package/dist/esm/client.d.ts +38 -10
  40. package/dist/esm/client.js +50 -16
  41. package/dist/esm/currency.d.ts +7 -0
  42. package/dist/esm/currency.js +67 -0
  43. package/dist/esm/enums.js +1 -1
  44. package/dist/esm/event-types.d.ts +108 -0
  45. package/dist/esm/event-types.js +106 -0
  46. package/dist/esm/express.d.ts +11 -2
  47. package/dist/esm/express.js +3 -2
  48. package/dist/esm/fastify.d.ts +4 -1
  49. package/dist/esm/fastify.js +3 -2
  50. package/dist/esm/generated/index.d.ts +1759 -86
  51. package/dist/esm/generated/index.js +1 -1
  52. package/dist/esm/identity.js +1 -1
  53. package/dist/esm/index.d.ts +9 -1
  54. package/dist/esm/index.js +4 -0
  55. package/dist/esm/installation.d.ts +47 -0
  56. package/dist/esm/installation.js +77 -0
  57. package/dist/esm/lookups.d.ts +128 -0
  58. package/dist/esm/lookups.js +142 -0
  59. package/dist/esm/models.d.ts +342 -0
  60. package/dist/esm/models.js +1 -0
  61. package/dist/esm/next.d.ts +22 -0
  62. package/dist/esm/next.js +19 -0
  63. package/dist/esm/pager.d.ts +5 -0
  64. package/dist/esm/pager.js +36 -0
  65. package/dist/esm/referrals.d.ts +169 -0
  66. package/dist/esm/referrals.js +204 -0
  67. package/dist/esm/resources.d.ts +34 -5
  68. package/dist/esm/resources.js +43 -42
  69. package/dist/esm/types.d.ts +57 -10
  70. package/dist/esm/version.d.ts +1 -1
  71. package/dist/esm/version.js +1 -1
  72. package/dist/esm/webhooks.d.ts +3 -2
  73. package/dist/esm/webhooks.js +42 -2
  74. package/package.json +2 -2
@@ -0,0 +1,342 @@
1
+ import type * as Gen from './generated/index.js';
2
+ import type { ListPage } from './types.js';
3
+ /**
4
+ * Typed models of the referrals, privacy, people, installs and codes resources (SPEC sections 28-32).
5
+ * Keys are as the API sends them (snake_case); unknown keys are kept. `amount` (on reward sides) and `created`
6
+ * (on `getOrCreateReferrer`) are added by the SDK.
7
+ */
8
+ /** A referrer's counters, refreshed regularly (not live). */
9
+ export interface ReferrerStats {
10
+ /** Human clicks on the referrer's link. */
11
+ clicks: number;
12
+ /** Referrals of any status. */
13
+ installs: number;
14
+ /** Referrals past their first qualification step (rejected ones excluded). */
15
+ signups: number;
16
+ /** Open referrals. */
17
+ in_progress: number;
18
+ qualified: number;
19
+ disqualified: number;
20
+ rejected: number;
21
+ /** Share of referees (0 to 1) who uninstalled within 7 days; `null` when none is old enough yet. Absent until first refreshed. */
22
+ referee_uninstall_rate_7d?: number | null;
23
+ [key: string]: unknown;
24
+ }
25
+ /** A customer who refers others in a referral program. */
26
+ export interface Referrer {
27
+ object: 'referrer';
28
+ /** `rfr_…` */
29
+ id: string;
30
+ program_id: string;
31
+ /** Your customer ID (the `customerId` you passed), as the API names it. */
32
+ customer_user_id: string;
33
+ /** The same customer ID (added by the SDK). */
34
+ customerId: string;
35
+ display_name: string | null;
36
+ /** The referral code. */
37
+ code: string;
38
+ external_code: string | null;
39
+ link_id: string | null;
40
+ /** The code URL, else the short link. */
41
+ url: string | null;
42
+ short_url: string | null;
43
+ /** `active` or `blocked` (a plain string: new values can appear). */
44
+ status: 'active' | 'blocked' | (string & {});
45
+ blocked_reason: string | null;
46
+ blocked_at: string | null;
47
+ stats: ReferrerStats;
48
+ /** Your own free-form data about the referrer. */
49
+ attributes: Record<string, unknown>;
50
+ leaderboard_opt_out: boolean;
51
+ quality_score: number | null;
52
+ /** `good`, `watch` or `poor`; `null` until scored. */
53
+ quality_band: string | null;
54
+ last_activity_at: string | null;
55
+ created_at: string;
56
+ updated_at: string;
57
+ livemode: boolean;
58
+ [key: string]: unknown;
59
+ }
60
+ /** A referrer from `getOrCreateReferrer`: `created` is true when it was just created (the API answered 201). */
61
+ export interface ReferrerResult extends Referrer {
62
+ created: boolean;
63
+ }
64
+ /** One side's reward. Keys without a value are absent. */
65
+ export interface RewardSide {
66
+ /** The amount in the currency's minor units (kobo, cents), as the API sends it. */
67
+ amount_minor?: number;
68
+ /** ISO 4217 code, present with `amount_minor`. */
69
+ currency?: string;
70
+ /** The same amount in normal units as a decimal string with the currency's exponent (`"500.00"`). Added by the SDK. */
71
+ amount?: string;
72
+ /** The reward in words. */
73
+ description?: string;
74
+ [key: string]: unknown;
75
+ }
76
+ /** Reward information, for your records: Clikgate never pays rewards. */
77
+ export interface RewardInfo {
78
+ /** What the referrer gets. */
79
+ referrer?: RewardSide;
80
+ /** What the referee gets. */
81
+ referee?: RewardSide;
82
+ note?: string;
83
+ [key: string]: unknown;
84
+ }
85
+ /** A qualification step the referee completed. */
86
+ export interface ReferralStep {
87
+ /** The step's position in the program's steps (0 is the first). */
88
+ index: number;
89
+ /** The step's goal key; absent for identify steps. */
90
+ goal?: string;
91
+ /** `true` for an identify step; absent for goal steps. */
92
+ identify?: boolean;
93
+ completed_at: string;
94
+ source_id?: string | null;
95
+ [key: string]: unknown;
96
+ }
97
+ /** A referral: an install matched to a referrer, and its progress through the program's steps. */
98
+ export interface Referral {
99
+ object: 'referral';
100
+ /** `ref_…` */
101
+ id: string;
102
+ program_id: string;
103
+ referrer_id: string;
104
+ /** `installed`, `in_progress`, `holding`, `qualified`, `disqualified`, `rejected`, … (a plain string). */
105
+ status: string;
106
+ source: string;
107
+ match_type: string | null;
108
+ current_step: number;
109
+ steps_completed: ReferralStep[];
110
+ step_deadline_at: string | null;
111
+ hold_until: string | null;
112
+ qualified_at: string | null;
113
+ disqualified_at: string | null;
114
+ rejected_at: string | null;
115
+ reason: string | null;
116
+ reason_detail?: string | null;
117
+ reason_message?: string | null;
118
+ fraud_flags: string[];
119
+ referee_uninstalled_after_qualification: boolean;
120
+ program: {
121
+ id: string;
122
+ name: string;
123
+ [key: string]: unknown;
124
+ };
125
+ /** The referrer; `customerId` (added by the SDK) equals `customer_user_id`. */
126
+ referrer: {
127
+ id: string;
128
+ customer_user_id: string;
129
+ customerId: string;
130
+ code: string;
131
+ [key: string]: unknown;
132
+ };
133
+ /** The referee; `customerId` (added by the SDK) equals `customer_user_id` (`null` until identified). */
134
+ referee: {
135
+ install_id: string;
136
+ installation_id: string;
137
+ customer_user_id: string | null;
138
+ customerId: string | null;
139
+ [key: string]: unknown;
140
+ };
141
+ link: {
142
+ id: string;
143
+ [key: string]: unknown;
144
+ } | null;
145
+ click_id: string | null;
146
+ /** The program's reward when the referral qualified; absent when there was none. */
147
+ reward_snapshot?: RewardInfo | null;
148
+ /** The referral's status changes, when the API includes them. */
149
+ history?: ReferralStateChange[] | null;
150
+ created_at: string;
151
+ updated_at: string;
152
+ livemode: boolean;
153
+ [key: string]: unknown;
154
+ }
155
+ /** One status change of a referral. */
156
+ export interface ReferralStateChange {
157
+ from_status: string | null;
158
+ to_status: string;
159
+ reason: string | null;
160
+ actor: string;
161
+ created_at: string;
162
+ [key: string]: unknown;
163
+ }
164
+ /** One result of a job (only the keys that apply are present). */
165
+ export interface JobResult {
166
+ index?: number;
167
+ ok?: boolean;
168
+ referrer_id?: string;
169
+ link_id?: string;
170
+ created?: boolean;
171
+ /** Exports and downloads: a signed link to the file and when it stops working (Unix seconds). */
172
+ url?: string;
173
+ expires_at?: number;
174
+ rows?: number;
175
+ files?: number;
176
+ run_id?: string;
177
+ /** Test data resets: the kind of data deleted and how many rows. */
178
+ table?: string;
179
+ deleted?: number;
180
+ error?: {
181
+ type: string;
182
+ code: string;
183
+ message?: string;
184
+ param?: string | null;
185
+ [key: string]: unknown;
186
+ };
187
+ [key: string]: unknown;
188
+ }
189
+ /** A background job, e.g. a referrer import. */
190
+ export interface Job {
191
+ object: 'job';
192
+ id: string;
193
+ type: string;
194
+ status: string;
195
+ total: number;
196
+ succeeded: number;
197
+ failed: number;
198
+ results: JobResult[];
199
+ created_at: string;
200
+ finished_at: string | null;
201
+ livemode: boolean;
202
+ [key: string]: unknown;
203
+ }
204
+ /** A privacy request (access, export, delete or erasure). */
205
+ export interface PrivacyRequest {
206
+ object: 'privacy_request';
207
+ id: string;
208
+ app_id: string | null;
209
+ type: string;
210
+ subject_type: string;
211
+ /** `pending`, `running`, `completed` or `failed`. */
212
+ status: string;
213
+ /** Set once completed: an export's `{download_url, expires_at, installs, goal_name_events}`, or an erasure's counts. */
214
+ result: Gen.PrivacyExportResult | Record<string, number> | null;
215
+ error: string | null;
216
+ created_at: string;
217
+ completed_at: string | null;
218
+ livemode: boolean;
219
+ [key: string]: unknown;
220
+ }
221
+ /** A person: one customer across clicks, installs and your customer ID. */
222
+ export interface Person extends Gen.PersonInfoResponse {
223
+ object: 'person';
224
+ [key: string]: unknown;
225
+ }
226
+ /** A person as `people.search` lists them. */
227
+ export interface PersonSummary extends Gen.PersonSummaryResponse {
228
+ [key: string]: unknown;
229
+ }
230
+ /** An app install. */
231
+ export interface Install extends Gen.InstallInfoResponse {
232
+ object: 'install';
233
+ [key: string]: unknown;
234
+ }
235
+ /** A payment report decided by a trusted confirmation (`payment.*` webhooks). */
236
+ export interface PaymentReport extends Gen.PaymentReportInfoResponse {
237
+ object: 'payment_report';
238
+ [key: string]: unknown;
239
+ }
240
+ /** A conversion as `conversion.*` webhooks show it. */
241
+ export interface ConversionObject extends Gen.ConversionInfoResponse {
242
+ object: 'conversion';
243
+ [key: string]: unknown;
244
+ }
245
+ /** The answer of `codes.redeem`. */
246
+ export interface CodeRedemption {
247
+ object: 'code_redemption';
248
+ offline_touch_id: string;
249
+ code: {
250
+ code: string;
251
+ kind: string;
252
+ link_id: string | null;
253
+ campaign_id: string | null;
254
+ referrer_id: string | null;
255
+ program_id: string | null;
256
+ [key: string]: unknown;
257
+ };
258
+ /** The referral the redemption created or found; `null` otherwise. */
259
+ referral: Referral | null;
260
+ /** True once the touch is tied to an install. */
261
+ linked: boolean;
262
+ /** Why a referral code didn't create a referral (e.g. `already_referred`); `null` otherwise. */
263
+ referral_error?: {
264
+ code: string;
265
+ message: string;
266
+ [key: string]: unknown;
267
+ } | null;
268
+ livemode: boolean;
269
+ [key: string]: unknown;
270
+ }
271
+ /** A goal event as `goal.completed` and `goal.reversed` webhooks show it. */
272
+ export interface WebhookGoalEvent {
273
+ object: 'goal_event';
274
+ id: string;
275
+ goal: string | null;
276
+ /** Normal units as a decimal string. */
277
+ value: string | null;
278
+ value_minor: number | null;
279
+ currency: string | null;
280
+ first_for_click: boolean | null;
281
+ is_first_customer: boolean | null;
282
+ link: {
283
+ id: string;
284
+ [key: string]: unknown;
285
+ } | null;
286
+ campaign: {
287
+ id: string;
288
+ [key: string]: unknown;
289
+ } | null;
290
+ clicked_at: string | null;
291
+ occurred_at: string;
292
+ /** The attribution state, e.g. `attributed`. */
293
+ status: string;
294
+ received_as: string | null;
295
+ goal_group: {
296
+ id: string;
297
+ name: string;
298
+ [key: string]: unknown;
299
+ } | null;
300
+ /** Your reference; absent in private mode. */
301
+ reference?: string | null;
302
+ /** `goal.completed` only: the event's person. */
303
+ person?: {
304
+ id: string;
305
+ label?: string | null;
306
+ [key: string]: unknown;
307
+ } | null;
308
+ backfilled?: boolean | null;
309
+ livemode: boolean;
310
+ [key: string]: unknown;
311
+ }
312
+ /** One phone of a device change (a coarse model only). */
313
+ export interface DeviceChangeSide {
314
+ platform: string;
315
+ device_model: string | null;
316
+ [key: string]: unknown;
317
+ }
318
+ /** A customer moving to another phone (`kind: 'switch'`) or adding one (`second_device`): the `person.device_changed` object. */
319
+ export interface DeviceChange {
320
+ object: 'device_change';
321
+ /** `{device_change_id}:{kind}` */
322
+ id: string;
323
+ device_change_id: string;
324
+ person_id: string;
325
+ customer_id: string | null;
326
+ app_id: string;
327
+ kind: 'switch' | 'second_device' | (string & {});
328
+ from: DeviceChangeSide;
329
+ to: DeviceChangeSide;
330
+ from_last_seen_at: string | null;
331
+ to_first_open_at: string;
332
+ /** Days between the two phones, for a switch; `null` for a second device. */
333
+ gap_days: number | null;
334
+ livemode: boolean;
335
+ [key: string]: unknown;
336
+ }
337
+ /** One page of `people.search`. */
338
+ export type PersonSearchPage = ListPage<PersonSummary>;
339
+ /** The fields of `links.create` (the API's `AddLinkSchema`). */
340
+ export type LinkCreateParams = Gen.AddLinkSchema;
341
+ /** The fields of `links.update` (the API's `UpdateLinkSchema`); `null` clears a field. */
342
+ export type LinkUpdateParams = Gen.UpdateLinkSchema;
@@ -0,0 +1 @@
1
+ export {};
@@ -12,10 +12,17 @@
12
12
  * import { getClickId } from '@clikgate/node/next';
13
13
  * const clickId = getClickId(await cookies());
14
14
  *
15
+ * // app/api/login/route.ts: the app's Clikgate-Installation header
16
+ * import { headers } from 'next/headers';
17
+ * import { getInstallation } from '@clikgate/node/next';
18
+ * const installation = getInstallation(await headers());
19
+ *
15
20
  * @packageDocumentation
16
21
  */
17
22
  import { NextResponse, type NextRequest } from 'next/server.js';
18
23
  import { type KeepRoute, type KeepRouteOptions, type PersistOptions } from './click-ids.js';
24
+ import { type Installation } from './installation.js';
25
+ export type { Installation } from './installation.js';
19
26
  /** A cookie store: `request.cookies` or the awaited `cookies()` from `next/headers`. */
20
27
  export interface CookieStoreLike {
21
28
  get(name: string): {
@@ -79,3 +86,18 @@ export declare function getClickId(store: CookieStoreLike, clickIdParam?: string
79
86
  export declare function keepRoute(options?: KeepRouteOptions & {
80
87
  clickIdParam?: string;
81
88
  }): KeepRoute;
89
+ /** A header store: the awaited `headers()` from `next/headers`, `request.headers` or a Fetch `Headers`. */
90
+ export interface HeaderStoreLike {
91
+ get(name: string): string | null;
92
+ }
93
+ /**
94
+ * Read the app installation from the `Clikgate-Installation` header, e.g. `getInstallation(await headers())` in a
95
+ * route handler or server action, or `getInstallation(request.headers)`. `null` when it is missing or invalid.
96
+ *
97
+ * @example
98
+ * import { headers } from 'next/headers';
99
+ * const user = await requireSignedInUser(); // your own sign-in check first
100
+ * const installation = getInstallation(await headers());
101
+ * if (installation) await clikgate.identifyUser({ ...installation, customerId: user.id });
102
+ */
103
+ export declare function getInstallation(store: HeaderStoreLike | null | undefined): Installation | null;
package/dist/esm/next.js CHANGED
@@ -12,10 +12,16 @@
12
12
  * import { getClickId } from '@clikgate/node/next';
13
13
  * const clickId = getClickId(await cookies());
14
14
  *
15
+ * // app/api/login/route.ts: the app's Clikgate-Installation header
16
+ * import { headers } from 'next/headers';
17
+ * import { getInstallation } from '@clikgate/node/next';
18
+ * const installation = getInstallation(await headers());
19
+ *
15
20
  * @packageDocumentation
16
21
  */
17
22
  import { NextResponse } from 'next/server.js';
18
23
  import { ClickIds, keptMarkerHeader } from './click-ids.js';
24
+ import { installationFromRequest } from './installation.js';
19
25
  function helpersFor(param) {
20
26
  const name = param ?? (typeof process !== 'undefined' ? process.env.CLIKGATE_CLICK_ID_PARAM : undefined) ?? 'cgid';
21
27
  return new ClickIds(() => name);
@@ -94,3 +100,16 @@ export function keepRoute(options = {}) {
94
100
  const { clickIdParam, ...rest } = options;
95
101
  return helpersFor(clickIdParam).keepRoute(rest);
96
102
  }
103
+ /**
104
+ * Read the app installation from the `Clikgate-Installation` header, e.g. `getInstallation(await headers())` in a
105
+ * route handler or server action, or `getInstallation(request.headers)`. `null` when it is missing or invalid.
106
+ *
107
+ * @example
108
+ * import { headers } from 'next/headers';
109
+ * const user = await requireSignedInUser(); // your own sign-in check first
110
+ * const installation = getInstallation(await headers());
111
+ * if (installation) await clikgate.identifyUser({ ...installation, customerId: user.id });
112
+ */
113
+ export function getInstallation(store) {
114
+ return store ? installationFromRequest({ headers: store }) : null;
115
+ }
@@ -0,0 +1,5 @@
1
+ /** An async iterator over every item of a list, fetching pages lazily. */
2
+ export interface PageIterator<T> extends AsyncIterable<T> {
3
+ /** Collect up to `max` items (default: all). */
4
+ toArray(max?: number): Promise<T[]>;
5
+ }
@@ -0,0 +1,36 @@
1
+ /** @internal Iterate pages: `fetch(cursor)` returns the page after `cursor` (`null` for the first). */
2
+ export function paginate(fetch) {
3
+ async function* iterate() {
4
+ let cursor = null;
5
+ for (;;) {
6
+ const page = await fetch(cursor);
7
+ for (const item of page.data ?? [])
8
+ yield item;
9
+ if (!page.has_more || !page.next_cursor)
10
+ return;
11
+ cursor = page.next_cursor;
12
+ }
13
+ }
14
+ return {
15
+ [Symbol.asyncIterator]: iterate,
16
+ async toArray(max = Number.POSITIVE_INFINITY) {
17
+ const out = [];
18
+ if (max <= 0)
19
+ return out;
20
+ for await (const item of iterate()) {
21
+ out.push(item);
22
+ if (out.length >= max)
23
+ break;
24
+ }
25
+ return out;
26
+ },
27
+ };
28
+ }
29
+ /** @internal Copy `params` without `undefined` values. */
30
+ export function defined(params) {
31
+ const out = {};
32
+ for (const [k, v] of Object.entries(params))
33
+ if (v !== undefined)
34
+ out[k] = v;
35
+ return out;
36
+ }
@@ -0,0 +1,169 @@
1
+ import { type RequestOptions } from './http.js';
2
+ import { type MoneyInput } from './money.js';
3
+ import { type PageIterator } from './pager.js';
4
+ import type { Job, Referral, Referrer, ReferrerResult } from './models.js';
5
+ import type { ListPage } from './types.js';
6
+ /** Fields of `referrals.getOrCreateReferrer`. */
7
+ export interface ReferrerCreateParams {
8
+ /** Your customer ID (sent as `customer_user_id`). */
9
+ customerId: string;
10
+ displayName?: string;
11
+ /** A code the customer already had in your own system. */
12
+ externalCode?: string;
13
+ }
14
+ /** Look a referrer up by your customer ID or by their code (exactly one). */
15
+ export type ReferrerLookup = {
16
+ customerId: string;
17
+ code?: undefined;
18
+ } | {
19
+ code: string;
20
+ customerId?: undefined;
21
+ };
22
+ /** Filters of `referrals.list` / `listPage`. */
23
+ export interface ReferralListParams {
24
+ programId?: string;
25
+ referrerId?: string;
26
+ /** The referee's customer ID (sent as `referee_customer_user_id`). */
27
+ refereeCustomerId?: string;
28
+ status?: string;
29
+ from?: Date | string;
30
+ to?: Date | string;
31
+ /** 1-100 per page. */
32
+ limit?: number;
33
+ startingAfter?: string;
34
+ endingBefore?: string;
35
+ }
36
+ /** Fields of `referrals.completeStep`. */
37
+ export interface CompleteStepParams {
38
+ /** The step's goal key. */
39
+ goal: string;
40
+ /** When the step happened (required by the API). */
41
+ occurredAt: Date | string;
42
+ /** Normal units (SPEC section 8). */
43
+ value?: MoneyInput;
44
+ currency?: string;
45
+ }
46
+ /** One row of `referrals.importReferrers`. */
47
+ export interface ReferrerImportRow {
48
+ customerId: string;
49
+ externalCode?: string;
50
+ displayName?: string;
51
+ }
52
+ /** Fields of `referrals.updateReferrer`. */
53
+ export interface ReferrerUpdateParams {
54
+ displayName?: string | null;
55
+ /** Your own free-form data about the referrer. */
56
+ attributes?: Record<string, unknown> | null;
57
+ }
58
+ /** The API's limit of referrers per import request. */
59
+ export declare const REFERRER_IMPORT_BATCH = 1000;
60
+ /** Referrals: referrers, referrals, manual overrides, qualification steps and imports. */
61
+ export declare class Referrals {
62
+ private readonly core;
63
+ private call;
64
+ /**
65
+ * Get the referrer for one of your customers in a program, creating it (with its code and link) the first time.
66
+ * `created` is true when it was just created.
67
+ *
68
+ * @example
69
+ * const referrer = await clikgate.referrals.getOrCreateReferrer('rpg_01J…', { customerId: user.id, displayName: user.firstName });
70
+ * console.log(referrer.code, referrer.url, referrer.created);
71
+ */
72
+ getOrCreateReferrer(programId: string, params: ReferrerCreateParams, requestOptions?: RequestOptions): Promise<ReferrerResult>;
73
+ /**
74
+ * Fetch a referrer by ID.
75
+ *
76
+ * @example
77
+ * const referrer = await clikgate.referrals.getReferrer('rfr_01J…');
78
+ */
79
+ getReferrer(referrerId: string, requestOptions?: RequestOptions): Promise<Referrer>;
80
+ /**
81
+ * Find a referrer by your customer ID or by code. Returns `null` when there is none (404); other errors throw.
82
+ *
83
+ * @example
84
+ * const referrer = await clikgate.referrals.findReferrer('rpg_01J…', { customerId: user.id });
85
+ * if (!referrer) { … }
86
+ */
87
+ findReferrer(programId: string, lookup: ReferrerLookup, requestOptions?: RequestOptions): Promise<Referrer | null>;
88
+ /**
89
+ * Fetch a referral by ID. Reward sides carry `amount` (normal units) next to `amount_minor`.
90
+ *
91
+ * @example
92
+ * const referral = await clikgate.referrals.get('ref_01J…');
93
+ * console.log(referral.status, referral.reward_snapshot?.referrer?.amount);
94
+ */
95
+ get(referralId: string, requestOptions?: RequestOptions): Promise<Referral>;
96
+ /**
97
+ * Fetch one page of referrals.
98
+ *
99
+ * @example
100
+ * const page = await clikgate.referrals.listPage({ programId: 'rpg_01J…', status: 'qualified', limit: 100 });
101
+ */
102
+ listPage(params?: ReferralListParams, requestOptions?: RequestOptions): Promise<ListPage<Referral>>;
103
+ /**
104
+ * Iterate over every referral, fetching pages lazily.
105
+ *
106
+ * @example
107
+ * for await (const referral of clikgate.referrals.list({ programId: 'rpg_01J…', status: 'qualified' })) {
108
+ * console.log(referral.id, referral.referee.customer_user_id);
109
+ * }
110
+ */
111
+ list(params?: ReferralListParams, requestOptions?: RequestOptions): PageIterator<Referral>;
112
+ /**
113
+ * Qualify a referral by hand (a manual override), with your reason.
114
+ *
115
+ * @example
116
+ * await clikgate.referrals.qualify('ref_01J…', { reason: 'Checked by support' });
117
+ */
118
+ qualify(referralId: string, params: {
119
+ reason: string;
120
+ }, requestOptions?: RequestOptions): Promise<Referral>;
121
+ /**
122
+ * Disqualify a referral by hand (a manual override), with your reason.
123
+ *
124
+ * @example
125
+ * await clikgate.referrals.disqualify('ref_01J…', { reason: 'Same household' });
126
+ */
127
+ disqualify(referralId: string, params: {
128
+ reason: string;
129
+ }, requestOptions?: RequestOptions): Promise<Referral>;
130
+ private override;
131
+ /**
132
+ * Complete the referral's current qualification step from your server (a goal it can't see otherwise).
133
+ *
134
+ * @example
135
+ * await clikgate.referrals.completeStep('ref_01J…', { goal: 'first_order', occurredAt: order.paidAt, value: '1500.50', currency: 'NGN' });
136
+ */
137
+ completeStep(referralId: string, params: CompleteStepParams, requestOptions?: RequestOptions): Promise<Referral>;
138
+ /**
139
+ * Import referrers (customers who already refer others, with their old codes). Rows are sent in batches of 1000;
140
+ * the result is one job per batch.
141
+ *
142
+ * @example
143
+ * const jobs = await clikgate.referrals.importReferrers('rpg_01J…', [{ customerId: 'user-42', externalCode: 'ADA-OLD' }]);
144
+ */
145
+ importReferrers(programId: string, rows: ReferrerImportRow[], requestOptions?: RequestOptions): Promise<Job[]>;
146
+ /**
147
+ * Block a referrer: their code and link stop creating referrals.
148
+ *
149
+ * @example
150
+ * await clikgate.referrals.blockReferrer('rfr_01J…', { reason: 'Fake installs' });
151
+ */
152
+ blockReferrer(referrerId: string, params?: {
153
+ reason?: string;
154
+ }, requestOptions?: RequestOptions): Promise<Referrer>;
155
+ /**
156
+ * Unblock a referrer.
157
+ *
158
+ * @example
159
+ * await clikgate.referrals.unblockReferrer('rfr_01J…');
160
+ */
161
+ unblockReferrer(referrerId: string, requestOptions?: RequestOptions): Promise<Referrer>;
162
+ /**
163
+ * Update a referrer's display name or your own attributes (`null` clears).
164
+ *
165
+ * @example
166
+ * await clikgate.referrals.updateReferrer('rfr_01J…', { displayName: 'Ada O.', attributes: { tier: 'gold' } });
167
+ */
168
+ updateReferrer(referrerId: string, params: ReferrerUpdateParams, requestOptions?: RequestOptions): Promise<Referrer>;
169
+ }