@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.
- package/CHANGELOG.md +25 -0
- package/README.md +116 -7
- package/SECURITY.md +2 -1
- package/dist/cjs/client.d.ts +38 -10
- package/dist/cjs/client.js +50 -16
- package/dist/cjs/currency.d.ts +7 -0
- package/dist/cjs/currency.js +75 -0
- package/dist/cjs/enums.js +1 -1
- package/dist/cjs/event-types.d.ts +108 -0
- package/dist/cjs/event-types.js +109 -0
- package/dist/cjs/express.d.ts +11 -2
- package/dist/cjs/express.js +3 -2
- package/dist/cjs/fastify.d.ts +4 -1
- package/dist/cjs/fastify.js +3 -2
- package/dist/cjs/generated/index.d.ts +1759 -86
- package/dist/cjs/generated/index.js +1 -1
- package/dist/cjs/identity.js +1 -1
- package/dist/cjs/index.d.ts +9 -1
- package/dist/cjs/index.js +15 -1
- package/dist/cjs/installation.d.ts +47 -0
- package/dist/cjs/installation.js +83 -0
- package/dist/cjs/lookups.d.ts +128 -0
- package/dist/cjs/lookups.js +149 -0
- package/dist/cjs/models.d.ts +342 -0
- package/dist/cjs/models.js +2 -0
- package/dist/cjs/next.d.ts +22 -0
- package/dist/cjs/next.js +20 -0
- package/dist/cjs/pager.d.ts +5 -0
- package/dist/cjs/pager.js +40 -0
- package/dist/cjs/referrals.d.ts +169 -0
- package/dist/cjs/referrals.js +208 -0
- package/dist/cjs/resources.d.ts +34 -5
- package/dist/cjs/resources.js +43 -42
- package/dist/cjs/types.d.ts +57 -10
- package/dist/cjs/version.d.ts +1 -1
- package/dist/cjs/version.js +1 -1
- package/dist/cjs/webhooks.d.ts +3 -2
- package/dist/cjs/webhooks.js +43 -2
- package/dist/esm/client.d.ts +38 -10
- package/dist/esm/client.js +50 -16
- package/dist/esm/currency.d.ts +7 -0
- package/dist/esm/currency.js +67 -0
- package/dist/esm/enums.js +1 -1
- package/dist/esm/event-types.d.ts +108 -0
- package/dist/esm/event-types.js +106 -0
- package/dist/esm/express.d.ts +11 -2
- package/dist/esm/express.js +3 -2
- package/dist/esm/fastify.d.ts +4 -1
- package/dist/esm/fastify.js +3 -2
- package/dist/esm/generated/index.d.ts +1759 -86
- package/dist/esm/generated/index.js +1 -1
- package/dist/esm/identity.js +1 -1
- package/dist/esm/index.d.ts +9 -1
- package/dist/esm/index.js +4 -0
- package/dist/esm/installation.d.ts +47 -0
- package/dist/esm/installation.js +77 -0
- package/dist/esm/lookups.d.ts +128 -0
- package/dist/esm/lookups.js +142 -0
- package/dist/esm/models.d.ts +342 -0
- package/dist/esm/models.js +1 -0
- package/dist/esm/next.d.ts +22 -0
- package/dist/esm/next.js +19 -0
- package/dist/esm/pager.d.ts +5 -0
- package/dist/esm/pager.js +36 -0
- package/dist/esm/referrals.d.ts +169 -0
- package/dist/esm/referrals.js +204 -0
- package/dist/esm/resources.d.ts +34 -5
- package/dist/esm/resources.js +43 -42
- package/dist/esm/types.d.ts +57 -10
- package/dist/esm/version.d.ts +1 -1
- package/dist/esm/version.js +1 -1
- package/dist/esm/webhooks.d.ts +3 -2
- package/dist/esm/webhooks.js +42 -2
- package/package.json +2 -2
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
import { NotFoundError, localError } from './errors.js';
|
|
2
|
+
import { encodePathSegment, formatDate, requireId } from './http.js';
|
|
3
|
+
import { formatValue } from './money.js';
|
|
4
|
+
import { toReferral, toReferrer, toReferrerResult } from './currency.js';
|
|
5
|
+
import { defined, paginate } from './pager.js';
|
|
6
|
+
/** The API's limit of referrers per import request. */
|
|
7
|
+
export const REFERRER_IMPORT_BATCH = 1000;
|
|
8
|
+
/** Referrals: referrers, referrals, manual overrides, qualification steps and imports. */
|
|
9
|
+
export class Referrals {
|
|
10
|
+
core;
|
|
11
|
+
/** @internal */
|
|
12
|
+
constructor(core) {
|
|
13
|
+
this.core = core;
|
|
14
|
+
}
|
|
15
|
+
async call(method, path, init, requestOptions) {
|
|
16
|
+
const { status, data } = await this.core.requester.request({ method, path, ...init, ...requestOptions });
|
|
17
|
+
return { status, data };
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Get the referrer for one of your customers in a program, creating it (with its code and link) the first time.
|
|
21
|
+
* `created` is true when it was just created.
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* const referrer = await clikgate.referrals.getOrCreateReferrer('rpg_01J…', { customerId: user.id, displayName: user.firstName });
|
|
25
|
+
* console.log(referrer.code, referrer.url, referrer.created);
|
|
26
|
+
*/
|
|
27
|
+
async getOrCreateReferrer(programId, params, requestOptions = {}) {
|
|
28
|
+
const program = encodePathSegment(requireId(programId, 'program_id'));
|
|
29
|
+
const body = defined({ customer_user_id: requireId(params?.customerId, 'customer_id'), display_name: params.displayName, external_code: params.externalCode });
|
|
30
|
+
const { status, data } = await this.call('POST', `/v1/referral-programs/${program}/referrers`, { body }, requestOptions);
|
|
31
|
+
return toReferrerResult(data, status);
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Fetch a referrer by ID.
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* const referrer = await clikgate.referrals.getReferrer('rfr_01J…');
|
|
38
|
+
*/
|
|
39
|
+
async getReferrer(referrerId, requestOptions = {}) {
|
|
40
|
+
const { data } = await this.call('GET', `/v1/referrers/${encodePathSegment(requireId(referrerId, 'referrer_id'))}`, {}, requestOptions);
|
|
41
|
+
return toReferrer(data);
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Find a referrer by your customer ID or by code. Returns `null` when there is none (404); other errors throw.
|
|
45
|
+
*
|
|
46
|
+
* @example
|
|
47
|
+
* const referrer = await clikgate.referrals.findReferrer('rpg_01J…', { customerId: user.id });
|
|
48
|
+
* if (!referrer) { … }
|
|
49
|
+
*/
|
|
50
|
+
async findReferrer(programId, lookup, requestOptions = {}) {
|
|
51
|
+
const program = encodePathSegment(requireId(programId, 'program_id'));
|
|
52
|
+
const hasCustomer = lookup?.customerId !== undefined && lookup?.customerId !== null;
|
|
53
|
+
const hasCode = lookup?.code !== undefined && lookup?.code !== null;
|
|
54
|
+
if (hasCustomer === hasCode)
|
|
55
|
+
throw localError('invalid_argument', 'Pass exactly one of customerId and code.', 'customer_id');
|
|
56
|
+
const path = hasCustomer
|
|
57
|
+
? `/v1/referral-programs/${program}/referrers/by-user/${encodePathSegment(requireId(lookup.customerId, 'customer_id'))}`
|
|
58
|
+
: `/v1/referral-programs/${program}/referrers/by-code/${encodePathSegment(requireId(lookup.code, 'code'))}`;
|
|
59
|
+
try {
|
|
60
|
+
const { data } = await this.call('GET', path, {}, requestOptions);
|
|
61
|
+
return toReferrer(data);
|
|
62
|
+
}
|
|
63
|
+
catch (err) {
|
|
64
|
+
if (err instanceof NotFoundError)
|
|
65
|
+
return null;
|
|
66
|
+
throw err;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
/**
|
|
70
|
+
* Fetch a referral by ID. Reward sides carry `amount` (normal units) next to `amount_minor`.
|
|
71
|
+
*
|
|
72
|
+
* @example
|
|
73
|
+
* const referral = await clikgate.referrals.get('ref_01J…');
|
|
74
|
+
* console.log(referral.status, referral.reward_snapshot?.referrer?.amount);
|
|
75
|
+
*/
|
|
76
|
+
async get(referralId, requestOptions = {}) {
|
|
77
|
+
const { data } = await this.call('GET', `/v1/referrals/${encodePathSegment(requireId(referralId, 'referral_id'))}`, {}, requestOptions);
|
|
78
|
+
return toReferral(data);
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* Fetch one page of referrals.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* const page = await clikgate.referrals.listPage({ programId: 'rpg_01J…', status: 'qualified', limit: 100 });
|
|
85
|
+
*/
|
|
86
|
+
async listPage(params = {}, requestOptions = {}) {
|
|
87
|
+
const query = defined({
|
|
88
|
+
program_id: params.programId,
|
|
89
|
+
referrer_id: params.referrerId,
|
|
90
|
+
referee_customer_user_id: params.refereeCustomerId,
|
|
91
|
+
status: params.status,
|
|
92
|
+
from: params.from,
|
|
93
|
+
to: params.to,
|
|
94
|
+
limit: params.limit,
|
|
95
|
+
starting_after: params.startingAfter,
|
|
96
|
+
ending_before: params.endingBefore,
|
|
97
|
+
});
|
|
98
|
+
const { data } = await this.call('GET', '/v1/referrals', { query }, requestOptions);
|
|
99
|
+
return { ...data, data: (data?.data ?? []).map(toReferral) };
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Iterate over every referral, fetching pages lazily.
|
|
103
|
+
*
|
|
104
|
+
* @example
|
|
105
|
+
* for await (const referral of clikgate.referrals.list({ programId: 'rpg_01J…', status: 'qualified' })) {
|
|
106
|
+
* console.log(referral.id, referral.referee.customer_user_id);
|
|
107
|
+
* }
|
|
108
|
+
*/
|
|
109
|
+
list(params = {}, requestOptions = {}) {
|
|
110
|
+
return paginate((cursor) => this.listPage(cursor ? { ...params, startingAfter: cursor } : params, requestOptions));
|
|
111
|
+
}
|
|
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
|
+
async qualify(referralId, params, requestOptions = {}) {
|
|
119
|
+
return this.override(referralId, 'qualify', params?.reason, requestOptions);
|
|
120
|
+
}
|
|
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
|
+
async disqualify(referralId, params, requestOptions = {}) {
|
|
128
|
+
return this.override(referralId, 'disqualify', params?.reason, requestOptions);
|
|
129
|
+
}
|
|
130
|
+
async override(referralId, action, reason, requestOptions) {
|
|
131
|
+
const path = `/v1/referrals/${encodePathSegment(requireId(referralId, 'referral_id'))}/override`;
|
|
132
|
+
const { data } = await this.call('POST', path, { body: { action, reason } }, requestOptions);
|
|
133
|
+
return toReferral(data);
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* Complete the referral's current qualification step from your server (a goal it can't see otherwise).
|
|
137
|
+
*
|
|
138
|
+
* @example
|
|
139
|
+
* await clikgate.referrals.completeStep('ref_01J…', { goal: 'first_order', occurredAt: order.paidAt, value: '1500.50', currency: 'NGN' });
|
|
140
|
+
*/
|
|
141
|
+
async completeStep(referralId, params, requestOptions = {}) {
|
|
142
|
+
const path = `/v1/referrals/${encodePathSegment(requireId(referralId, 'referral_id'))}/steps`;
|
|
143
|
+
if (params?.occurredAt === undefined || params.occurredAt === null || params.occurredAt === '')
|
|
144
|
+
throw localError('invalid_argument', 'occurredAt is required: when the step happened.', 'occurred_at');
|
|
145
|
+
const value = params.value === undefined || params.value === null ? undefined : formatValue(params.value, (m) => this.core.warn('inexact_number', m));
|
|
146
|
+
const body = defined({ goal: params.goal, occurred_at: formatDate(params.occurredAt), value, currency: params.currency });
|
|
147
|
+
const { data } = await this.call('POST', path, { body }, requestOptions);
|
|
148
|
+
return toReferral(data);
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Import referrers (customers who already refer others, with their old codes). Rows are sent in batches of 1000;
|
|
152
|
+
* the result is one job per batch.
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* const jobs = await clikgate.referrals.importReferrers('rpg_01J…', [{ customerId: 'user-42', externalCode: 'ADA-OLD' }]);
|
|
156
|
+
*/
|
|
157
|
+
async importReferrers(programId, rows, requestOptions = {}) {
|
|
158
|
+
const program = encodePathSegment(requireId(programId, 'program_id'));
|
|
159
|
+
if (!Array.isArray(rows))
|
|
160
|
+
throw localError('invalid_argument', 'rows must be a list.', 'rows');
|
|
161
|
+
const wire = rows.map((r, i) => defined({ customer_user_id: requireId(r?.customerId, `rows[${i}].customer_id`), external_code: r.externalCode, display_name: r.displayName }));
|
|
162
|
+
const jobs = [];
|
|
163
|
+
const batches = Math.ceil(wire.length / REFERRER_IMPORT_BATCH);
|
|
164
|
+
for (let b = 0; b < batches; b++) {
|
|
165
|
+
const key = requestOptions.idempotencyKey && batches > 1 ? `${requestOptions.idempotencyKey}-${b}` : requestOptions.idempotencyKey;
|
|
166
|
+
const body = { referrers: wire.slice(b * REFERRER_IMPORT_BATCH, (b + 1) * REFERRER_IMPORT_BATCH) };
|
|
167
|
+
const { data } = await this.call('POST', `/v1/referral-programs/${program}/referrers/import`, { body }, { ...requestOptions, idempotencyKey: key });
|
|
168
|
+
jobs.push(data);
|
|
169
|
+
}
|
|
170
|
+
return jobs;
|
|
171
|
+
}
|
|
172
|
+
/**
|
|
173
|
+
* Block a referrer: their code and link stop creating referrals.
|
|
174
|
+
*
|
|
175
|
+
* @example
|
|
176
|
+
* await clikgate.referrals.blockReferrer('rfr_01J…', { reason: 'Fake installs' });
|
|
177
|
+
*/
|
|
178
|
+
async blockReferrer(referrerId, params = {}, requestOptions = {}) {
|
|
179
|
+
const path = `/v1/referrers/${encodePathSegment(requireId(referrerId, 'referrer_id'))}/block`;
|
|
180
|
+
const { data } = await this.call('POST', path, { body: defined({ reason: params?.reason }) }, requestOptions);
|
|
181
|
+
return toReferrer(data);
|
|
182
|
+
}
|
|
183
|
+
/**
|
|
184
|
+
* Unblock a referrer.
|
|
185
|
+
*
|
|
186
|
+
* @example
|
|
187
|
+
* await clikgate.referrals.unblockReferrer('rfr_01J…');
|
|
188
|
+
*/
|
|
189
|
+
async unblockReferrer(referrerId, requestOptions = {}) {
|
|
190
|
+
const { data } = await this.call('POST', `/v1/referrers/${encodePathSegment(requireId(referrerId, 'referrer_id'))}/unblock`, {}, requestOptions);
|
|
191
|
+
return toReferrer(data);
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Update a referrer's display name or your own attributes (`null` clears).
|
|
195
|
+
*
|
|
196
|
+
* @example
|
|
197
|
+
* await clikgate.referrals.updateReferrer('rfr_01J…', { displayName: 'Ada O.', attributes: { tier: 'gold' } });
|
|
198
|
+
*/
|
|
199
|
+
async updateReferrer(referrerId, params, requestOptions = {}) {
|
|
200
|
+
const body = defined({ display_name: params?.displayName, attributes: params?.attributes });
|
|
201
|
+
const { data } = await this.call('PATCH', `/v1/referrers/${encodePathSegment(requireId(referrerId, 'referrer_id'))}`, { body }, requestOptions);
|
|
202
|
+
return toReferrer(data);
|
|
203
|
+
}
|
|
204
|
+
}
|
package/dist/esm/resources.d.ts
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
import { type RequestOptions } from './http.js';
|
|
2
2
|
import type { Click, Conversion, GoalEvent, Link, LinkUpdateResult, ListPage, QrCode } from './types.js';
|
|
3
|
+
import type { LinkCreateParams, LinkUpdateParams } from './models.js';
|
|
4
|
+
import { type PageIterator } from './pager.js';
|
|
3
5
|
type Params = Record<string, unknown>;
|
|
4
6
|
/** Conversions: the older API. New integrations should use goals. */
|
|
5
7
|
export declare class Conversions {
|
|
@@ -36,11 +38,8 @@ export interface QrOptions {
|
|
|
36
38
|
dark?: string;
|
|
37
39
|
light?: string;
|
|
38
40
|
}
|
|
39
|
-
/** An async iterator over every link
|
|
40
|
-
export
|
|
41
|
-
/** Collect up to `max` links (default: all). */
|
|
42
|
-
toArray(max?: number): Promise<Link[]>;
|
|
43
|
-
}
|
|
41
|
+
/** An async iterator over every link. */
|
|
42
|
+
export type LinkIterator = PageIterator<Link>;
|
|
44
43
|
/** Links: create, read, update (with approvals and locks), list and QR codes. */
|
|
45
44
|
export declare class Links {
|
|
46
45
|
private readonly core;
|
|
@@ -51,6 +50,7 @@ export declare class Links {
|
|
|
51
50
|
* const link = await clikgate.links.create({ destination_url: 'https://example.com/spring', og_title: 'Spring sale', og_image_url: 'https://example.com/og.png' });
|
|
52
51
|
* console.log(link.short_url, link.warnings);
|
|
53
52
|
*/
|
|
53
|
+
create(params: LinkCreateParams, requestOptions?: RequestOptions): Promise<Link>;
|
|
54
54
|
create(params: Params, requestOptions?: RequestOptions): Promise<Link>;
|
|
55
55
|
/**
|
|
56
56
|
* Fetch a link by ID.
|
|
@@ -68,6 +68,7 @@ export declare class Links {
|
|
|
68
68
|
* const result = await clikgate.links.update('lnk_01J…', { destination_url: 'https://example.com/summer' });
|
|
69
69
|
* if (!result.applied) console.log('waiting for approval:', result.change_request.id);
|
|
70
70
|
*/
|
|
71
|
+
update(id: string, params: LinkUpdateParams, requestOptions?: RequestOptions): Promise<LinkUpdateResult>;
|
|
71
72
|
update(id: string, params: Params, requestOptions?: RequestOptions): Promise<LinkUpdateResult>;
|
|
72
73
|
/**
|
|
73
74
|
* Fetch one page of links (`limit` 1–100, `starting_after`, `ending_before`, filters such as `status`, `tag`, `campaign_id`).
|
|
@@ -85,6 +86,34 @@ export declare class Links {
|
|
|
85
86
|
* }
|
|
86
87
|
*/
|
|
87
88
|
list(params?: Params, requestOptions?: RequestOptions): LinkIterator;
|
|
89
|
+
/**
|
|
90
|
+
* Archive a link (`DELETE /v1/links/{id}`): it stops redirecting. Returns the archived link.
|
|
91
|
+
*
|
|
92
|
+
* @example
|
|
93
|
+
* const link = await clikgate.links.archive('lnk_01J…');
|
|
94
|
+
*/
|
|
95
|
+
archive(id: string, requestOptions?: RequestOptions): Promise<Link>;
|
|
96
|
+
/**
|
|
97
|
+
* Fetch a link by your own external reference (`external_reference`).
|
|
98
|
+
*
|
|
99
|
+
* @example
|
|
100
|
+
* const link = await clikgate.links.getByReference('order-1001');
|
|
101
|
+
*/
|
|
102
|
+
getByReference(reference: string, requestOptions?: RequestOptions): Promise<Link>;
|
|
103
|
+
/**
|
|
104
|
+
* Pause a link: visitors see the paused page until you resume it.
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* const link = await clikgate.links.pause('lnk_01J…');
|
|
108
|
+
*/
|
|
109
|
+
pause(id: string, requestOptions?: RequestOptions): Promise<Link>;
|
|
110
|
+
/**
|
|
111
|
+
* Resume a paused link.
|
|
112
|
+
*
|
|
113
|
+
* @example
|
|
114
|
+
* const link = await clikgate.links.resume('lnk_01J…');
|
|
115
|
+
*/
|
|
116
|
+
resume(id: string, requestOptions?: RequestOptions): Promise<Link>;
|
|
88
117
|
/**
|
|
89
118
|
* Download the link's QR code.
|
|
90
119
|
*
|
package/dist/esm/resources.js
CHANGED
|
@@ -2,6 +2,7 @@ import { guardPayload } from './guard.js';
|
|
|
2
2
|
import { encodePathSegment, requireId } from './http.js';
|
|
3
3
|
import { formatValue } from './money.js';
|
|
4
4
|
import { checkHashedFields } from './ads-hashing.js';
|
|
5
|
+
import { paginate } from './pager.js';
|
|
5
6
|
function withFormattedValue(core, params) {
|
|
6
7
|
const out = {};
|
|
7
8
|
for (const [k, v] of Object.entries(params))
|
|
@@ -62,13 +63,6 @@ export class Links {
|
|
|
62
63
|
constructor(core) {
|
|
63
64
|
this.core = core;
|
|
64
65
|
}
|
|
65
|
-
/**
|
|
66
|
-
* Create a link. The result's `warnings` include `no_preview` when there is no preview title and image.
|
|
67
|
-
*
|
|
68
|
-
* @example
|
|
69
|
-
* const link = await clikgate.links.create({ destination_url: 'https://example.com/spring', og_title: 'Spring sale', og_image_url: 'https://example.com/og.png' });
|
|
70
|
-
* console.log(link.short_url, link.warnings);
|
|
71
|
-
*/
|
|
72
66
|
async create(params, requestOptions = {}) {
|
|
73
67
|
const { data } = await this.core.requester.request({ method: 'POST', path: '/v1/links', body: params, ...requestOptions });
|
|
74
68
|
return data;
|
|
@@ -83,15 +77,6 @@ export class Links {
|
|
|
83
77
|
const { data } = await this.core.requester.request({ method: 'GET', path: `/v1/links/${encodePathSegment(requireId(id))}`, ...requestOptions });
|
|
84
78
|
return data;
|
|
85
79
|
}
|
|
86
|
-
/**
|
|
87
|
-
* Update a link. With two-person approval on, a destination change answers `202` and waits for a
|
|
88
|
-
* second person: the result is `{ applied: false, change_request }`. A locked link throws {@link LinkLockedError}.
|
|
89
|
-
* An explicit `null` clears a field.
|
|
90
|
-
*
|
|
91
|
-
* @example
|
|
92
|
-
* const result = await clikgate.links.update('lnk_01J…', { destination_url: 'https://example.com/summer' });
|
|
93
|
-
* if (!result.applied) console.log('waiting for approval:', result.change_request.id);
|
|
94
|
-
*/
|
|
95
80
|
async update(id, params, requestOptions = {}) {
|
|
96
81
|
const { status, data } = await this.core.requester.request({
|
|
97
82
|
method: 'PATCH',
|
|
@@ -123,32 +108,48 @@ export class Links {
|
|
|
123
108
|
* }
|
|
124
109
|
*/
|
|
125
110
|
list(params = {}, requestOptions = {}) {
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
111
|
+
return paginate((cursor) => this.listPage(cursor ? { ...params, starting_after: cursor } : params, requestOptions));
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Archive a link (`DELETE /v1/links/{id}`): it stops redirecting. Returns the archived link.
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* const link = await clikgate.links.archive('lnk_01J…');
|
|
118
|
+
*/
|
|
119
|
+
async archive(id, requestOptions = {}) {
|
|
120
|
+
const { data } = await this.core.requester.request({ method: 'DELETE', path: `/v1/links/${encodePathSegment(requireId(id))}`, ...requestOptions });
|
|
121
|
+
return data;
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Fetch a link by your own external reference (`external_reference`).
|
|
125
|
+
*
|
|
126
|
+
* @example
|
|
127
|
+
* const link = await clikgate.links.getByReference('order-1001');
|
|
128
|
+
*/
|
|
129
|
+
async getByReference(reference, requestOptions = {}) {
|
|
130
|
+
const path = `/v1/links/by-reference/${encodePathSegment(requireId(reference, 'reference'))}`;
|
|
131
|
+
const { data } = await this.core.requester.request({ method: 'GET', path, ...requestOptions });
|
|
132
|
+
return data;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Pause a link: visitors see the paused page until you resume it.
|
|
136
|
+
*
|
|
137
|
+
* @example
|
|
138
|
+
* const link = await clikgate.links.pause('lnk_01J…');
|
|
139
|
+
*/
|
|
140
|
+
async pause(id, requestOptions = {}) {
|
|
141
|
+
const { data } = await this.core.requester.request({ method: 'POST', path: `/v1/links/${encodePathSegment(requireId(id))}/pause`, ...requestOptions });
|
|
142
|
+
return data;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Resume a paused link.
|
|
146
|
+
*
|
|
147
|
+
* @example
|
|
148
|
+
* const link = await clikgate.links.resume('lnk_01J…');
|
|
149
|
+
*/
|
|
150
|
+
async resume(id, requestOptions = {}) {
|
|
151
|
+
const { data } = await this.core.requester.request({ method: 'POST', path: `/v1/links/${encodePathSegment(requireId(id))}/resume`, ...requestOptions });
|
|
152
|
+
return data;
|
|
152
153
|
}
|
|
153
154
|
/**
|
|
154
155
|
* Download the link's QR code.
|
package/dist/esm/types.d.ts
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
import type { GoalKind, GoalStatus, Provider } from './enums.js';
|
|
2
|
+
import type { LinkInfoResponse } from './generated/index.js';
|
|
3
|
+
import type { EventTypeValue } from './event-types.js';
|
|
4
|
+
import type { ConversionObject, DeviceChange, Install, PaymentReport, Referral, Referrer, WebhookGoalEvent } from './models.js';
|
|
2
5
|
/** Wire objects returned by the hand-written resources. Keys are as the API sends them (snake_case). */
|
|
3
6
|
/** Where a goal event was attributed. */
|
|
4
7
|
export interface GoalAttribution {
|
|
@@ -86,8 +89,8 @@ export interface LinkWarning {
|
|
|
86
89
|
message: string;
|
|
87
90
|
param?: string | null;
|
|
88
91
|
}
|
|
89
|
-
/** A link (`/v1/links`)
|
|
90
|
-
export interface Link {
|
|
92
|
+
/** A link (`/v1/links`): every field of the API's link, plus any newer field (kept as is). */
|
|
93
|
+
export interface Link extends Omit<LinkInfoResponse, 'object' | 'warnings' | 'metadata' | 'domain_badge' | 'locked'> {
|
|
91
94
|
object: 'link';
|
|
92
95
|
id: string;
|
|
93
96
|
short_url: string;
|
|
@@ -194,25 +197,69 @@ export interface ServerSdkConfig {
|
|
|
194
197
|
minimum_sdk_versions: Partial<Record<'node' | 'python' | 'php' | 'java' | 'dotnet', string>>;
|
|
195
198
|
[key: string]: unknown;
|
|
196
199
|
}
|
|
197
|
-
/**
|
|
198
|
-
export interface
|
|
200
|
+
/** Typed accessors of a verified webhook event (SPEC 29). Each gives `null` for an event of another family. */
|
|
201
|
+
export interface WebhookEventAccessors {
|
|
202
|
+
/** `referral.*`: the referral, with reward amounts. */
|
|
203
|
+
asReferral(): Referral | null;
|
|
204
|
+
/** `referrer.*`: the referrer. */
|
|
205
|
+
asReferrer(): Referrer | null;
|
|
206
|
+
/** `goal.completed` / `goal.reversed`: the goal event as webhooks show it. */
|
|
207
|
+
asGoalEvent(): WebhookGoalEvent | null;
|
|
208
|
+
/** `install.*`: the install. */
|
|
209
|
+
asInstall(): Install | null;
|
|
210
|
+
/** `payment.*`: the payment report. */
|
|
211
|
+
asPayment(): PaymentReport | null;
|
|
212
|
+
/** `conversion.*`: the conversion. */
|
|
213
|
+
asConversion(): ConversionObject | null;
|
|
214
|
+
/** `person.device_changed`: the device change. */
|
|
215
|
+
asDeviceChange(): DeviceChange | null;
|
|
216
|
+
/** The same event, typed as the union discriminated by `type`. */
|
|
217
|
+
typed(): TypedWebhookEvent;
|
|
218
|
+
}
|
|
219
|
+
/** A webhook event's `data`. */
|
|
220
|
+
export interface WebhookEventData<T> {
|
|
221
|
+
object: T;
|
|
222
|
+
previous_attributes?: Record<string, unknown> | null;
|
|
223
|
+
[key: string]: unknown;
|
|
224
|
+
}
|
|
225
|
+
/** A webhook event. `data` is the raw payload; the `as…()` accessors give typed objects. */
|
|
226
|
+
export interface WebhookEvent<T = Record<string, unknown>> extends WebhookEventAccessors {
|
|
199
227
|
id: string;
|
|
200
228
|
object: 'event';
|
|
201
|
-
/** e.g. `goal.completed`, `link.destination_changed
|
|
229
|
+
/** e.g. `referral.qualified`, `goal.completed`, `link.destination_changed`. Compare with `EventType`. */
|
|
202
230
|
type: string;
|
|
203
231
|
api_version: string;
|
|
204
232
|
created_at: string;
|
|
205
233
|
organization_id: string;
|
|
206
234
|
livemode: boolean;
|
|
207
|
-
data:
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
235
|
+
data: WebhookEventData<T>;
|
|
236
|
+
[key: string]: unknown;
|
|
237
|
+
}
|
|
238
|
+
/** One member of {@link TypedWebhookEvent}. */
|
|
239
|
+
export interface WebhookEventOf<Type extends string, T> extends WebhookEventAccessors {
|
|
240
|
+
id: string;
|
|
241
|
+
object: 'event';
|
|
242
|
+
type: Type;
|
|
243
|
+
api_version: string;
|
|
244
|
+
created_at: string;
|
|
245
|
+
organization_id: string;
|
|
246
|
+
livemode: boolean;
|
|
247
|
+
data: WebhookEventData<T>;
|
|
212
248
|
[key: string]: unknown;
|
|
213
249
|
}
|
|
250
|
+
type Family<P extends string> = Extract<EventTypeValue, `${P}.${string}`>;
|
|
251
|
+
type Typed = Family<'referral'> | Family<'referrer'> | Family<'goal'> | Family<'install'> | Family<'payment'> | Family<'conversion'> | 'person.device_changed';
|
|
252
|
+
/**
|
|
253
|
+
* Every webhook event this SDK release knows, discriminated by `type` (`event.typed()`):
|
|
254
|
+
*
|
|
255
|
+
* @example
|
|
256
|
+
* const e = event.typed();
|
|
257
|
+
* if (e.type === EventType.ReferralQualified) console.log(e.data.object.referrer.customer_user_id);
|
|
258
|
+
*/
|
|
259
|
+
export type TypedWebhookEvent = WebhookEventOf<Family<'referral'>, Referral> | WebhookEventOf<Family<'referrer'>, Referrer> | WebhookEventOf<Family<'goal'>, WebhookGoalEvent> | WebhookEventOf<Family<'install'>, Install> | WebhookEventOf<Family<'payment'>, PaymentReport> | WebhookEventOf<Family<'conversion'>, ConversionObject> | WebhookEventOf<'person.device_changed', DeviceChange> | WebhookEventOf<Exclude<EventTypeValue, Typed>, Record<string, unknown>>;
|
|
214
260
|
/** QR code bytes. */
|
|
215
261
|
export interface QrCode {
|
|
216
262
|
contentType: string;
|
|
217
263
|
data: Uint8Array;
|
|
218
264
|
}
|
|
265
|
+
export {};
|
package/dist/esm/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The SDK version (kept equal to package.json by `npm run check:version`). */
|
|
2
|
-
export declare const VERSION = "2.0
|
|
2
|
+
export declare const VERSION = "2.1.0";
|
package/dist/esm/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The SDK version (kept equal to package.json by `npm run check:version`). */
|
|
2
|
-
export const VERSION = '2.0
|
|
2
|
+
export const VERSION = '2.1.0';
|
package/dist/esm/webhooks.d.ts
CHANGED
|
@@ -18,10 +18,11 @@ export declare const webhooks: {
|
|
|
18
18
|
*
|
|
19
19
|
* @example
|
|
20
20
|
* import express from 'express';
|
|
21
|
-
* import { webhooks } from '@clikgate/node';
|
|
21
|
+
* import { webhooks, EventType } from '@clikgate/node';
|
|
22
22
|
* app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
|
|
23
23
|
* const event = webhooks.verify(req.body, req.get('Clikgate-Signature'), process.env.CLIKGATE_WEBHOOK_SECRET!);
|
|
24
|
-
*
|
|
24
|
+
* const referral = event.asReferral(); // null for other event types
|
|
25
|
+
* if (referral && event.type === EventType.ReferralQualified) { … } // dedupe on event.id: delivery is at-least-once
|
|
25
26
|
* res.sendStatus(200);
|
|
26
27
|
* });
|
|
27
28
|
*/
|
package/dist/esm/webhooks.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { createHmac, timingSafeEqual } from 'node:crypto';
|
|
2
2
|
import { SignatureVerificationError, localError } from './errors.js';
|
|
3
|
+
import { toReferral, toReferrer } from './currency.js';
|
|
3
4
|
const fail = (code, message) => new SignatureVerificationError({ message, code });
|
|
4
5
|
function toBytes(raw) {
|
|
5
6
|
if (typeof raw === 'string')
|
|
@@ -66,6 +67,44 @@ function verifyWith(rawBody, signatureHeader, secrets, options) {
|
|
|
66
67
|
}
|
|
67
68
|
if (!event || typeof event !== 'object' || Array.isArray(event))
|
|
68
69
|
throw fail('invalid_payload', 'The body is not an event object.');
|
|
70
|
+
return withAccessors(event);
|
|
71
|
+
}
|
|
72
|
+
function objectOf(event, family) {
|
|
73
|
+
const type = event.type;
|
|
74
|
+
if (typeof type !== 'string' || !type.startsWith(`${family}.`))
|
|
75
|
+
return null;
|
|
76
|
+
const data = event.data;
|
|
77
|
+
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
78
|
+
return null;
|
|
79
|
+
const object = data.object;
|
|
80
|
+
return object && typeof object === 'object' && !Array.isArray(object) ? object : null;
|
|
81
|
+
}
|
|
82
|
+
/** @internal Add the typed accessors as non-enumerable methods (JSON.stringify(event) is unchanged). */
|
|
83
|
+
export function withAccessors(event) {
|
|
84
|
+
const accessors = {
|
|
85
|
+
asReferral: () => {
|
|
86
|
+
const o = objectOf(event, 'referral');
|
|
87
|
+
return o ? toReferral(o) : null;
|
|
88
|
+
},
|
|
89
|
+
asReferrer: () => {
|
|
90
|
+
const o = objectOf(event, 'referrer');
|
|
91
|
+
return o ? toReferrer(o) : null;
|
|
92
|
+
},
|
|
93
|
+
asGoalEvent: () => objectOf(event, 'goal'),
|
|
94
|
+
asInstall: () => objectOf(event, 'install'),
|
|
95
|
+
asPayment: () => objectOf(event, 'payment'),
|
|
96
|
+
asConversion: () => objectOf(event, 'conversion'),
|
|
97
|
+
asDeviceChange: () => {
|
|
98
|
+
if (event.type !== 'person.device_changed')
|
|
99
|
+
return null;
|
|
100
|
+
const data = event.data;
|
|
101
|
+
const object = data && typeof data === 'object' ? data.object : null;
|
|
102
|
+
return object && typeof object === 'object' && !Array.isArray(object) ? object : null;
|
|
103
|
+
},
|
|
104
|
+
typed: () => event,
|
|
105
|
+
};
|
|
106
|
+
for (const [name, fn] of Object.entries(accessors))
|
|
107
|
+
Object.defineProperty(event, name, { value: fn, enumerable: false, writable: true, configurable: true });
|
|
69
108
|
return event;
|
|
70
109
|
}
|
|
71
110
|
/**
|
|
@@ -78,10 +117,11 @@ export const webhooks = {
|
|
|
78
117
|
*
|
|
79
118
|
* @example
|
|
80
119
|
* import express from 'express';
|
|
81
|
-
* import { webhooks } from '@clikgate/node';
|
|
120
|
+
* import { webhooks, EventType } from '@clikgate/node';
|
|
82
121
|
* app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
|
|
83
122
|
* const event = webhooks.verify(req.body, req.get('Clikgate-Signature'), process.env.CLIKGATE_WEBHOOK_SECRET!);
|
|
84
|
-
*
|
|
123
|
+
* const referral = event.asReferral(); // null for other event types
|
|
124
|
+
* if (referral && event.type === EventType.ReferralQualified) { … } // dedupe on event.id: delivery is at-least-once
|
|
85
125
|
* res.sendStatus(200);
|
|
86
126
|
* });
|
|
87
127
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clikgate/node",
|
|
3
|
-
"version": "2.0
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "The official Clikgate server SDK for Node.js and TypeScript: send goals in three lines, keep the click ID, verify webhooks, with private mode built in.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"clikgate",
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"directory": "server/node"
|
|
24
24
|
},
|
|
25
25
|
"license": "MIT",
|
|
26
|
-
"author": "Clikgate <
|
|
26
|
+
"author": "Clikgate <dev@clikgate.com> (https://clikgate.com)",
|
|
27
27
|
"type": "module",
|
|
28
28
|
"sideEffects": false,
|
|
29
29
|
"engines": {
|