@clikgate/node 2.0.0 → 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 (86) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +126 -6
  3. package/SECURITY.md +2 -1
  4. package/dist/cjs/client.d.ts +54 -10
  5. package/dist/cjs/client.js +75 -16
  6. package/dist/cjs/currency.d.ts +7 -0
  7. package/dist/cjs/currency.js +75 -0
  8. package/dist/cjs/customer-id.d.ts +26 -0
  9. package/dist/cjs/customer-id.js +52 -0
  10. package/dist/cjs/enums.js +1 -1
  11. package/dist/cjs/errors.d.ts +1 -1
  12. package/dist/cjs/event-types.d.ts +108 -0
  13. package/dist/cjs/event-types.js +109 -0
  14. package/dist/cjs/express.d.ts +11 -2
  15. package/dist/cjs/express.js +3 -2
  16. package/dist/cjs/fastify.d.ts +4 -1
  17. package/dist/cjs/fastify.js +3 -2
  18. package/dist/cjs/generated/index.d.ts +2015 -83
  19. package/dist/cjs/generated/index.js +83 -3
  20. package/dist/cjs/identity.d.ts +12 -2
  21. package/dist/cjs/identity.js +37 -3
  22. package/dist/cjs/index.d.ts +11 -1
  23. package/dist/cjs/index.js +21 -1
  24. package/dist/cjs/installation.d.ts +47 -0
  25. package/dist/cjs/installation.js +83 -0
  26. package/dist/cjs/known-customers.d.ts +45 -0
  27. package/dist/cjs/known-customers.js +95 -0
  28. package/dist/cjs/lookups.d.ts +128 -0
  29. package/dist/cjs/lookups.js +149 -0
  30. package/dist/cjs/models.d.ts +342 -0
  31. package/dist/cjs/models.js +2 -0
  32. package/dist/cjs/next.d.ts +22 -0
  33. package/dist/cjs/next.js +20 -0
  34. package/dist/cjs/pager.d.ts +5 -0
  35. package/dist/cjs/pager.js +40 -0
  36. package/dist/cjs/referrals.d.ts +169 -0
  37. package/dist/cjs/referrals.js +208 -0
  38. package/dist/cjs/resources.d.ts +34 -5
  39. package/dist/cjs/resources.js +43 -42
  40. package/dist/cjs/types.d.ts +57 -10
  41. package/dist/cjs/version.d.ts +1 -1
  42. package/dist/cjs/version.js +1 -1
  43. package/dist/cjs/webhooks.d.ts +3 -2
  44. package/dist/cjs/webhooks.js +43 -2
  45. package/dist/esm/client.d.ts +54 -10
  46. package/dist/esm/client.js +75 -16
  47. package/dist/esm/currency.d.ts +7 -0
  48. package/dist/esm/currency.js +67 -0
  49. package/dist/esm/customer-id.d.ts +26 -0
  50. package/dist/esm/customer-id.js +47 -0
  51. package/dist/esm/enums.js +1 -1
  52. package/dist/esm/errors.d.ts +1 -1
  53. package/dist/esm/event-types.d.ts +108 -0
  54. package/dist/esm/event-types.js +106 -0
  55. package/dist/esm/express.d.ts +11 -2
  56. package/dist/esm/express.js +3 -2
  57. package/dist/esm/fastify.d.ts +4 -1
  58. package/dist/esm/fastify.js +3 -2
  59. package/dist/esm/generated/index.d.ts +2015 -83
  60. package/dist/esm/generated/index.js +80 -1
  61. package/dist/esm/identity.d.ts +12 -2
  62. package/dist/esm/identity.js +36 -3
  63. package/dist/esm/index.d.ts +11 -1
  64. package/dist/esm/index.js +6 -0
  65. package/dist/esm/installation.d.ts +47 -0
  66. package/dist/esm/installation.js +77 -0
  67. package/dist/esm/known-customers.d.ts +45 -0
  68. package/dist/esm/known-customers.js +90 -0
  69. package/dist/esm/lookups.d.ts +128 -0
  70. package/dist/esm/lookups.js +142 -0
  71. package/dist/esm/models.d.ts +342 -0
  72. package/dist/esm/models.js +1 -0
  73. package/dist/esm/next.d.ts +22 -0
  74. package/dist/esm/next.js +19 -0
  75. package/dist/esm/pager.d.ts +5 -0
  76. package/dist/esm/pager.js +36 -0
  77. package/dist/esm/referrals.d.ts +169 -0
  78. package/dist/esm/referrals.js +204 -0
  79. package/dist/esm/resources.d.ts +34 -5
  80. package/dist/esm/resources.js +43 -42
  81. package/dist/esm/types.d.ts +57 -10
  82. package/dist/esm/version.d.ts +1 -1
  83. package/dist/esm/version.js +1 -1
  84. package/dist/esm/webhooks.d.ts +3 -2
  85. package/dist/esm/webhooks.js +42 -2
  86. package/package.json +2 -2
@@ -0,0 +1,128 @@
1
+ import { type RequestOptions } from './http.js';
2
+ import { type PageIterator } from './pager.js';
3
+ import type { CodeRedemption, Install, Person, PersonSearchPage, PersonSummary, PrivacyRequest } from './models.js';
4
+ /** Fields of `privacy.createRequest`. */
5
+ export interface PrivacyRequestParams {
6
+ type: 'access' | 'export' | 'delete' | 'erasure' | (string & {});
7
+ subjectType: 'installation' | 'customer_user' | 'email' | 'phone' | 'person' | 'click' | (string & {});
8
+ subjectId: string;
9
+ appId?: string;
10
+ }
11
+ /** Privacy requests: access, export, delete or erase a subject's data. */
12
+ export declare class Privacy {
13
+ private readonly core;
14
+ /**
15
+ * Ask for a subject's data to be exported, or erased. The request completes in the background.
16
+ *
17
+ * @example
18
+ * const request = await clikgate.privacy.createRequest({ type: 'erasure', subjectType: 'customer_user', subjectId: user.id });
19
+ */
20
+ createRequest(params: PrivacyRequestParams, requestOptions?: RequestOptions): Promise<PrivacyRequest>;
21
+ /**
22
+ * Fetch a privacy request (an export's `result` has its download link once completed).
23
+ *
24
+ * @example
25
+ * const request = await clikgate.privacy.getRequest('prq_01J…');
26
+ */
27
+ getRequest(requestId: string, requestOptions?: RequestOptions): Promise<PrivacyRequest>;
28
+ }
29
+ /** Options of `people.searchPage`. */
30
+ export interface PeopleSearchOptions {
31
+ cursor?: string;
32
+ /** 1-50 per page. */
33
+ limit?: number;
34
+ }
35
+ /** People: one customer across clicks, installs and your customer ID. */
36
+ export declare class People {
37
+ private readonly core;
38
+ /**
39
+ * Fetch a person.
40
+ *
41
+ * @example
42
+ * const person = await clikgate.people.get('per_01J…');
43
+ */
44
+ get(personId: string, requestOptions?: RequestOptions): Promise<Person>;
45
+ /**
46
+ * Fetch one page of people matching a label, customer ID or click ID. The text is sent in the body, never in the URL.
47
+ *
48
+ * @example
49
+ * const page = await clikgate.people.searchPage('Ada', { limit: 20 });
50
+ */
51
+ searchPage(q: string, options?: PeopleSearchOptions, requestOptions?: RequestOptions): Promise<PersonSearchPage>;
52
+ /**
53
+ * Iterate over every person matching the text, fetching pages lazily.
54
+ *
55
+ * @example
56
+ * for await (const person of clikgate.people.search('Ada')) console.log(person.id, person.label);
57
+ */
58
+ search(q: string, options?: Omit<PeopleSearchOptions, 'cursor'>, requestOptions?: RequestOptions): PageIterator<PersonSummary>;
59
+ /**
60
+ * Set a person's label (`null` clears it).
61
+ *
62
+ * @example
63
+ * await clikgate.people.setLabel('per_01J…', 'Ada (VIP)');
64
+ */
65
+ setLabel(personId: string, label: string | null, requestOptions?: RequestOptions): Promise<Person>;
66
+ }
67
+ /** Installs of your apps. */
68
+ export declare class Installs {
69
+ private readonly core;
70
+ /**
71
+ * The latest install of one of your customers (the customer ID you sent with `identifyUser`).
72
+ * The API currently needs `appId`.
73
+ *
74
+ * @example
75
+ * const install = await clikgate.installs.getByCustomer(user.id, { appId: 'app_01J…' });
76
+ */
77
+ getByCustomer(customerId: string, options?: {
78
+ appId?: string;
79
+ }, requestOptions?: RequestOptions): Promise<Install>;
80
+ /**
81
+ * An install by its installation ID (from the `Clikgate-Installation` header). The API currently needs `appId`.
82
+ *
83
+ * @example
84
+ * const install = await clikgate.installs.getByInstallation(installation.installationId, { appId: installation.appId });
85
+ */
86
+ getByInstallation(installationId: string, options?: {
87
+ appId?: string;
88
+ }, requestOptions?: RequestOptions): Promise<Install>;
89
+ }
90
+ /** Fields of `codes.redeem`. */
91
+ export interface CodeRedeemParams {
92
+ /** Your ID for this redemption (a receipt or ticket number). */
93
+ externalId: string;
94
+ code: string;
95
+ channel: 'ussd' | 'sms_keyword' | 'agent' | 'pos' | 'in_store' | 'call_center' | 'event' | 'print' | 'radio' | 'other' | (string & {});
96
+ appId?: string;
97
+ occurredAt?: Date | string;
98
+ /** Your own free-form data. */
99
+ metadata?: Record<string, unknown>;
100
+ /** Who redeemed it: `{ type, id? }` (e.g. `{ type: 'customer_user', id: user.id }`), sent as given. */
101
+ subject?: {
102
+ type: string;
103
+ id?: string | null;
104
+ [key: string]: unknown;
105
+ };
106
+ /** The agent who took the redemption. */
107
+ agentId?: string;
108
+ /** Where: `{ country?, region?, city?, store_id? }`, sent as given. */
109
+ location?: {
110
+ country?: string | null;
111
+ region?: string | null;
112
+ city?: string | null;
113
+ store_id?: string | null;
114
+ [key: string]: unknown;
115
+ };
116
+ }
117
+ /** Offline and referral codes. */
118
+ export declare class Codes {
119
+ private readonly core;
120
+ /**
121
+ * Redeem a code received offline (USSD, a till, an agent). A referral code can create a referral.
122
+ *
123
+ * @example
124
+ * const redemption = await clikgate.codes.redeem({ externalId: 'POS-991', code: 'ADA42', channel: 'pos' });
125
+ * if (redemption.referral) console.log(redemption.referral.id);
126
+ */
127
+ redeem(params: CodeRedeemParams, requestOptions?: RequestOptions): Promise<CodeRedemption>;
128
+ }
@@ -0,0 +1,142 @@
1
+ import { encodePathSegment, formatDate, requireId } from './http.js';
2
+ import { toReferral } from './currency.js';
3
+ import { defined, paginate } from './pager.js';
4
+ /** Privacy requests: access, export, delete or erase a subject's data. */
5
+ export class Privacy {
6
+ core;
7
+ /** @internal */
8
+ constructor(core) {
9
+ this.core = core;
10
+ }
11
+ /**
12
+ * Ask for a subject's data to be exported, or erased. The request completes in the background.
13
+ *
14
+ * @example
15
+ * const request = await clikgate.privacy.createRequest({ type: 'erasure', subjectType: 'customer_user', subjectId: user.id });
16
+ */
17
+ async createRequest(params, requestOptions = {}) {
18
+ const body = defined({ type: params.type, subject_type: params.subjectType, subject_id: params.subjectId, app_id: params.appId });
19
+ const { data } = await this.core.requester.request({ method: 'POST', path: '/v1/privacy/requests', body, ...requestOptions });
20
+ return data;
21
+ }
22
+ /**
23
+ * Fetch a privacy request (an export's `result` has its download link once completed).
24
+ *
25
+ * @example
26
+ * const request = await clikgate.privacy.getRequest('prq_01J…');
27
+ */
28
+ async getRequest(requestId, requestOptions = {}) {
29
+ const path = `/v1/privacy/requests/${encodePathSegment(requireId(requestId, 'request_id'))}`;
30
+ const { data } = await this.core.requester.request({ method: 'GET', path, ...requestOptions });
31
+ return data;
32
+ }
33
+ }
34
+ /** People: one customer across clicks, installs and your customer ID. */
35
+ export class People {
36
+ core;
37
+ /** @internal */
38
+ constructor(core) {
39
+ this.core = core;
40
+ }
41
+ /**
42
+ * Fetch a person.
43
+ *
44
+ * @example
45
+ * const person = await clikgate.people.get('per_01J…');
46
+ */
47
+ async get(personId, requestOptions = {}) {
48
+ const { data } = await this.core.requester.request({ method: 'GET', path: `/v1/people/${encodePathSegment(requireId(personId, 'person_id'))}`, ...requestOptions });
49
+ return data;
50
+ }
51
+ /**
52
+ * Fetch one page of people matching a label, customer ID or click ID. The text is sent in the body, never in the URL.
53
+ *
54
+ * @example
55
+ * const page = await clikgate.people.searchPage('Ada', { limit: 20 });
56
+ */
57
+ async searchPage(q, options = {}, requestOptions = {}) {
58
+ const body = defined({ q, cursor: options.cursor, limit: options.limit });
59
+ const { data } = await this.core.requester.request({ method: 'POST', path: '/v1/people/search', body, ...requestOptions });
60
+ return data;
61
+ }
62
+ /**
63
+ * Iterate over every person matching the text, fetching pages lazily.
64
+ *
65
+ * @example
66
+ * for await (const person of clikgate.people.search('Ada')) console.log(person.id, person.label);
67
+ */
68
+ search(q, options = {}, requestOptions = {}) {
69
+ return paginate((cursor) => this.searchPage(q, { ...options, cursor: cursor ?? undefined }, requestOptions));
70
+ }
71
+ /**
72
+ * Set a person's label (`null` clears it).
73
+ *
74
+ * @example
75
+ * await clikgate.people.setLabel('per_01J…', 'Ada (VIP)');
76
+ */
77
+ async setLabel(personId, label, requestOptions = {}) {
78
+ const { data } = await this.core.requester.request({ method: 'PATCH', path: `/v1/people/${encodePathSegment(requireId(personId, 'person_id'))}`, body: { label }, ...requestOptions });
79
+ return data;
80
+ }
81
+ }
82
+ /** Installs of your apps. */
83
+ export class Installs {
84
+ core;
85
+ /** @internal */
86
+ constructor(core) {
87
+ this.core = core;
88
+ }
89
+ /**
90
+ * The latest install of one of your customers (the customer ID you sent with `identifyUser`).
91
+ * The API currently needs `appId`.
92
+ *
93
+ * @example
94
+ * const install = await clikgate.installs.getByCustomer(user.id, { appId: 'app_01J…' });
95
+ */
96
+ async getByCustomer(customerId, options = {}, requestOptions = {}) {
97
+ const path = `/v1/installs/by-customer-user/${encodePathSegment(requireId(customerId, 'customer_id'))}`;
98
+ const { data } = await this.core.requester.request({ method: 'GET', path, query: defined({ app_id: options.appId }), ...requestOptions });
99
+ return data;
100
+ }
101
+ /**
102
+ * An install by its installation ID (from the `Clikgate-Installation` header). The API currently needs `appId`.
103
+ *
104
+ * @example
105
+ * const install = await clikgate.installs.getByInstallation(installation.installationId, { appId: installation.appId });
106
+ */
107
+ async getByInstallation(installationId, options = {}, requestOptions = {}) {
108
+ const path = `/v1/installs/by-installation/${encodePathSegment(requireId(installationId, 'installation_id'))}`;
109
+ const { data } = await this.core.requester.request({ method: 'GET', path, query: defined({ app_id: options.appId }), ...requestOptions });
110
+ return data;
111
+ }
112
+ }
113
+ /** Offline and referral codes. */
114
+ export class Codes {
115
+ core;
116
+ /** @internal */
117
+ constructor(core) {
118
+ this.core = core;
119
+ }
120
+ /**
121
+ * Redeem a code received offline (USSD, a till, an agent). A referral code can create a referral.
122
+ *
123
+ * @example
124
+ * const redemption = await clikgate.codes.redeem({ externalId: 'POS-991', code: 'ADA42', channel: 'pos' });
125
+ * if (redemption.referral) console.log(redemption.referral.id);
126
+ */
127
+ async redeem(params, requestOptions = {}) {
128
+ const body = defined({
129
+ external_id: params.externalId,
130
+ code: params.code,
131
+ channel: params.channel,
132
+ app_id: params.appId,
133
+ occurred_at: params.occurredAt === undefined || params.occurredAt === null ? undefined : formatDate(params.occurredAt),
134
+ metadata: params.metadata ?? undefined,
135
+ subject: params.subject ?? undefined,
136
+ agent_id: params.agentId ?? undefined,
137
+ location: params.location ?? undefined,
138
+ });
139
+ const { data } = await this.core.requester.request({ method: 'POST', path: '/v1/codes/redeem', body, ...requestOptions });
140
+ return data && data.referral ? { ...data, referral: toReferral(data.referral) } : data;
141
+ }
142
+ }
@@ -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
+ }