@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.
- package/CHANGELOG.md +35 -0
- package/README.md +126 -6
- package/SECURITY.md +2 -1
- package/dist/cjs/client.d.ts +54 -10
- package/dist/cjs/client.js +75 -16
- package/dist/cjs/currency.d.ts +7 -0
- package/dist/cjs/currency.js +75 -0
- package/dist/cjs/customer-id.d.ts +26 -0
- package/dist/cjs/customer-id.js +52 -0
- package/dist/cjs/enums.js +1 -1
- package/dist/cjs/errors.d.ts +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 +2015 -83
- package/dist/cjs/generated/index.js +83 -3
- package/dist/cjs/identity.d.ts +12 -2
- package/dist/cjs/identity.js +37 -3
- package/dist/cjs/index.d.ts +11 -1
- package/dist/cjs/index.js +21 -1
- package/dist/cjs/installation.d.ts +47 -0
- package/dist/cjs/installation.js +83 -0
- package/dist/cjs/known-customers.d.ts +45 -0
- package/dist/cjs/known-customers.js +95 -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 +54 -10
- package/dist/esm/client.js +75 -16
- package/dist/esm/currency.d.ts +7 -0
- package/dist/esm/currency.js +67 -0
- package/dist/esm/customer-id.d.ts +26 -0
- package/dist/esm/customer-id.js +47 -0
- package/dist/esm/enums.js +1 -1
- package/dist/esm/errors.d.ts +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 +2015 -83
- package/dist/esm/generated/index.js +80 -1
- package/dist/esm/identity.d.ts +12 -2
- package/dist/esm/identity.js +36 -3
- package/dist/esm/index.d.ts +11 -1
- package/dist/esm/index.js +6 -0
- package/dist/esm/installation.d.ts +47 -0
- package/dist/esm/installation.js +77 -0
- package/dist/esm/known-customers.d.ts +45 -0
- package/dist/esm/known-customers.js +90 -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
package/dist/cjs/next.js
CHANGED
|
@@ -5,6 +5,7 @@ exports.applyClikgate = applyClikgate;
|
|
|
5
5
|
exports.createClikgateProxy = createClikgateProxy;
|
|
6
6
|
exports.getClickId = getClickId;
|
|
7
7
|
exports.keepRoute = keepRoute;
|
|
8
|
+
exports.getInstallation = getInstallation;
|
|
8
9
|
/**
|
|
9
10
|
* Next.js add-on: keeps the click ID (SPEC section 17). Next.js 16 calls request middleware a
|
|
10
11
|
* "proxy" (`proxy.ts`, exporting `proxy`); `middleware.ts` still works but is deprecated.
|
|
@@ -19,10 +20,16 @@ exports.keepRoute = keepRoute;
|
|
|
19
20
|
* import { getClickId } from '@clikgate/node/next';
|
|
20
21
|
* const clickId = getClickId(await cookies());
|
|
21
22
|
*
|
|
23
|
+
* // app/api/login/route.ts: the app's Clikgate-Installation header
|
|
24
|
+
* import { headers } from 'next/headers';
|
|
25
|
+
* import { getInstallation } from '@clikgate/node/next';
|
|
26
|
+
* const installation = getInstallation(await headers());
|
|
27
|
+
*
|
|
22
28
|
* @packageDocumentation
|
|
23
29
|
*/
|
|
24
30
|
const server_js_1 = require("next/server.js");
|
|
25
31
|
const click_ids_js_1 = require("./click-ids.js");
|
|
32
|
+
const installation_js_1 = require("./installation.js");
|
|
26
33
|
function helpersFor(param) {
|
|
27
34
|
const name = param ?? (typeof process !== 'undefined' ? process.env.CLIKGATE_CLICK_ID_PARAM : undefined) ?? 'cgid';
|
|
28
35
|
return new click_ids_js_1.ClickIds(() => name);
|
|
@@ -101,3 +108,16 @@ function keepRoute(options = {}) {
|
|
|
101
108
|
const { clickIdParam, ...rest } = options;
|
|
102
109
|
return helpersFor(clickIdParam).keepRoute(rest);
|
|
103
110
|
}
|
|
111
|
+
/**
|
|
112
|
+
* Read the app installation from the `Clikgate-Installation` header, e.g. `getInstallation(await headers())` in a
|
|
113
|
+
* route handler or server action, or `getInstallation(request.headers)`. `null` when it is missing or invalid.
|
|
114
|
+
*
|
|
115
|
+
* @example
|
|
116
|
+
* import { headers } from 'next/headers';
|
|
117
|
+
* const user = await requireSignedInUser(); // your own sign-in check first
|
|
118
|
+
* const installation = getInstallation(await headers());
|
|
119
|
+
* if (installation) await clikgate.identifyUser({ ...installation, customerId: user.id });
|
|
120
|
+
*/
|
|
121
|
+
function getInstallation(store) {
|
|
122
|
+
return store ? (0, installation_js_1.installationFromRequest)({ headers: store }) : null;
|
|
123
|
+
}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.paginate = paginate;
|
|
4
|
+
exports.defined = defined;
|
|
5
|
+
/** @internal Iterate pages: `fetch(cursor)` returns the page after `cursor` (`null` for the first). */
|
|
6
|
+
function paginate(fetch) {
|
|
7
|
+
async function* iterate() {
|
|
8
|
+
let cursor = null;
|
|
9
|
+
for (;;) {
|
|
10
|
+
const page = await fetch(cursor);
|
|
11
|
+
for (const item of page.data ?? [])
|
|
12
|
+
yield item;
|
|
13
|
+
if (!page.has_more || !page.next_cursor)
|
|
14
|
+
return;
|
|
15
|
+
cursor = page.next_cursor;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
return {
|
|
19
|
+
[Symbol.asyncIterator]: iterate,
|
|
20
|
+
async toArray(max = Number.POSITIVE_INFINITY) {
|
|
21
|
+
const out = [];
|
|
22
|
+
if (max <= 0)
|
|
23
|
+
return out;
|
|
24
|
+
for await (const item of iterate()) {
|
|
25
|
+
out.push(item);
|
|
26
|
+
if (out.length >= max)
|
|
27
|
+
break;
|
|
28
|
+
}
|
|
29
|
+
return out;
|
|
30
|
+
},
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
/** @internal Copy `params` without `undefined` values. */
|
|
34
|
+
function defined(params) {
|
|
35
|
+
const out = {};
|
|
36
|
+
for (const [k, v] of Object.entries(params))
|
|
37
|
+
if (v !== undefined)
|
|
38
|
+
out[k] = v;
|
|
39
|
+
return out;
|
|
40
|
+
}
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Referrals = exports.REFERRER_IMPORT_BATCH = void 0;
|
|
4
|
+
const errors_js_1 = require("./errors.js");
|
|
5
|
+
const http_js_1 = require("./http.js");
|
|
6
|
+
const money_js_1 = require("./money.js");
|
|
7
|
+
const currency_js_1 = require("./currency.js");
|
|
8
|
+
const pager_js_1 = require("./pager.js");
|
|
9
|
+
/** The API's limit of referrers per import request. */
|
|
10
|
+
exports.REFERRER_IMPORT_BATCH = 1000;
|
|
11
|
+
/** Referrals: referrers, referrals, manual overrides, qualification steps and imports. */
|
|
12
|
+
class Referrals {
|
|
13
|
+
core;
|
|
14
|
+
/** @internal */
|
|
15
|
+
constructor(core) {
|
|
16
|
+
this.core = core;
|
|
17
|
+
}
|
|
18
|
+
async call(method, path, init, requestOptions) {
|
|
19
|
+
const { status, data } = await this.core.requester.request({ method, path, ...init, ...requestOptions });
|
|
20
|
+
return { status, data };
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Get the referrer for one of your customers in a program, creating it (with its code and link) the first time.
|
|
24
|
+
* `created` is true when it was just created.
|
|
25
|
+
*
|
|
26
|
+
* @example
|
|
27
|
+
* const referrer = await clikgate.referrals.getOrCreateReferrer('rpg_01J…', { customerId: user.id, displayName: user.firstName });
|
|
28
|
+
* console.log(referrer.code, referrer.url, referrer.created);
|
|
29
|
+
*/
|
|
30
|
+
async getOrCreateReferrer(programId, params, requestOptions = {}) {
|
|
31
|
+
const program = (0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(programId, 'program_id'));
|
|
32
|
+
const body = (0, pager_js_1.defined)({ customer_user_id: (0, http_js_1.requireId)(params?.customerId, 'customer_id'), display_name: params.displayName, external_code: params.externalCode });
|
|
33
|
+
const { status, data } = await this.call('POST', `/v1/referral-programs/${program}/referrers`, { body }, requestOptions);
|
|
34
|
+
return (0, currency_js_1.toReferrerResult)(data, status);
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Fetch a referrer by ID.
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* const referrer = await clikgate.referrals.getReferrer('rfr_01J…');
|
|
41
|
+
*/
|
|
42
|
+
async getReferrer(referrerId, requestOptions = {}) {
|
|
43
|
+
const { data } = await this.call('GET', `/v1/referrers/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referrerId, 'referrer_id'))}`, {}, requestOptions);
|
|
44
|
+
return (0, currency_js_1.toReferrer)(data);
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Find a referrer by your customer ID or by code. Returns `null` when there is none (404); other errors throw.
|
|
48
|
+
*
|
|
49
|
+
* @example
|
|
50
|
+
* const referrer = await clikgate.referrals.findReferrer('rpg_01J…', { customerId: user.id });
|
|
51
|
+
* if (!referrer) { … }
|
|
52
|
+
*/
|
|
53
|
+
async findReferrer(programId, lookup, requestOptions = {}) {
|
|
54
|
+
const program = (0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(programId, 'program_id'));
|
|
55
|
+
const hasCustomer = lookup?.customerId !== undefined && lookup?.customerId !== null;
|
|
56
|
+
const hasCode = lookup?.code !== undefined && lookup?.code !== null;
|
|
57
|
+
if (hasCustomer === hasCode)
|
|
58
|
+
throw (0, errors_js_1.localError)('invalid_argument', 'Pass exactly one of customerId and code.', 'customer_id');
|
|
59
|
+
const path = hasCustomer
|
|
60
|
+
? `/v1/referral-programs/${program}/referrers/by-user/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(lookup.customerId, 'customer_id'))}`
|
|
61
|
+
: `/v1/referral-programs/${program}/referrers/by-code/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(lookup.code, 'code'))}`;
|
|
62
|
+
try {
|
|
63
|
+
const { data } = await this.call('GET', path, {}, requestOptions);
|
|
64
|
+
return (0, currency_js_1.toReferrer)(data);
|
|
65
|
+
}
|
|
66
|
+
catch (err) {
|
|
67
|
+
if (err instanceof errors_js_1.NotFoundError)
|
|
68
|
+
return null;
|
|
69
|
+
throw err;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* Fetch a referral by ID. Reward sides carry `amount` (normal units) next to `amount_minor`.
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* const referral = await clikgate.referrals.get('ref_01J…');
|
|
77
|
+
* console.log(referral.status, referral.reward_snapshot?.referrer?.amount);
|
|
78
|
+
*/
|
|
79
|
+
async get(referralId, requestOptions = {}) {
|
|
80
|
+
const { data } = await this.call('GET', `/v1/referrals/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referralId, 'referral_id'))}`, {}, requestOptions);
|
|
81
|
+
return (0, currency_js_1.toReferral)(data);
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Fetch one page of referrals.
|
|
85
|
+
*
|
|
86
|
+
* @example
|
|
87
|
+
* const page = await clikgate.referrals.listPage({ programId: 'rpg_01J…', status: 'qualified', limit: 100 });
|
|
88
|
+
*/
|
|
89
|
+
async listPage(params = {}, requestOptions = {}) {
|
|
90
|
+
const query = (0, pager_js_1.defined)({
|
|
91
|
+
program_id: params.programId,
|
|
92
|
+
referrer_id: params.referrerId,
|
|
93
|
+
referee_customer_user_id: params.refereeCustomerId,
|
|
94
|
+
status: params.status,
|
|
95
|
+
from: params.from,
|
|
96
|
+
to: params.to,
|
|
97
|
+
limit: params.limit,
|
|
98
|
+
starting_after: params.startingAfter,
|
|
99
|
+
ending_before: params.endingBefore,
|
|
100
|
+
});
|
|
101
|
+
const { data } = await this.call('GET', '/v1/referrals', { query }, requestOptions);
|
|
102
|
+
return { ...data, data: (data?.data ?? []).map(currency_js_1.toReferral) };
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* Iterate over every referral, fetching pages lazily.
|
|
106
|
+
*
|
|
107
|
+
* @example
|
|
108
|
+
* for await (const referral of clikgate.referrals.list({ programId: 'rpg_01J…', status: 'qualified' })) {
|
|
109
|
+
* console.log(referral.id, referral.referee.customer_user_id);
|
|
110
|
+
* }
|
|
111
|
+
*/
|
|
112
|
+
list(params = {}, requestOptions = {}) {
|
|
113
|
+
return (0, pager_js_1.paginate)((cursor) => this.listPage(cursor ? { ...params, startingAfter: cursor } : params, requestOptions));
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Qualify a referral by hand (a manual override), with your reason.
|
|
117
|
+
*
|
|
118
|
+
* @example
|
|
119
|
+
* await clikgate.referrals.qualify('ref_01J…', { reason: 'Checked by support' });
|
|
120
|
+
*/
|
|
121
|
+
async qualify(referralId, params, requestOptions = {}) {
|
|
122
|
+
return this.override(referralId, 'qualify', params?.reason, requestOptions);
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Disqualify a referral by hand (a manual override), with your reason.
|
|
126
|
+
*
|
|
127
|
+
* @example
|
|
128
|
+
* await clikgate.referrals.disqualify('ref_01J…', { reason: 'Same household' });
|
|
129
|
+
*/
|
|
130
|
+
async disqualify(referralId, params, requestOptions = {}) {
|
|
131
|
+
return this.override(referralId, 'disqualify', params?.reason, requestOptions);
|
|
132
|
+
}
|
|
133
|
+
async override(referralId, action, reason, requestOptions) {
|
|
134
|
+
const path = `/v1/referrals/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referralId, 'referral_id'))}/override`;
|
|
135
|
+
const { data } = await this.call('POST', path, { body: { action, reason } }, requestOptions);
|
|
136
|
+
return (0, currency_js_1.toReferral)(data);
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Complete the referral's current qualification step from your server (a goal it can't see otherwise).
|
|
140
|
+
*
|
|
141
|
+
* @example
|
|
142
|
+
* await clikgate.referrals.completeStep('ref_01J…', { goal: 'first_order', occurredAt: order.paidAt, value: '1500.50', currency: 'NGN' });
|
|
143
|
+
*/
|
|
144
|
+
async completeStep(referralId, params, requestOptions = {}) {
|
|
145
|
+
const path = `/v1/referrals/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referralId, 'referral_id'))}/steps`;
|
|
146
|
+
if (params?.occurredAt === undefined || params.occurredAt === null || params.occurredAt === '')
|
|
147
|
+
throw (0, errors_js_1.localError)('invalid_argument', 'occurredAt is required: when the step happened.', 'occurred_at');
|
|
148
|
+
const value = params.value === undefined || params.value === null ? undefined : (0, money_js_1.formatValue)(params.value, (m) => this.core.warn('inexact_number', m));
|
|
149
|
+
const body = (0, pager_js_1.defined)({ goal: params.goal, occurred_at: (0, http_js_1.formatDate)(params.occurredAt), value, currency: params.currency });
|
|
150
|
+
const { data } = await this.call('POST', path, { body }, requestOptions);
|
|
151
|
+
return (0, currency_js_1.toReferral)(data);
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Import referrers (customers who already refer others, with their old codes). Rows are sent in batches of 1000;
|
|
155
|
+
* the result is one job per batch.
|
|
156
|
+
*
|
|
157
|
+
* @example
|
|
158
|
+
* const jobs = await clikgate.referrals.importReferrers('rpg_01J…', [{ customerId: 'user-42', externalCode: 'ADA-OLD' }]);
|
|
159
|
+
*/
|
|
160
|
+
async importReferrers(programId, rows, requestOptions = {}) {
|
|
161
|
+
const program = (0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(programId, 'program_id'));
|
|
162
|
+
if (!Array.isArray(rows))
|
|
163
|
+
throw (0, errors_js_1.localError)('invalid_argument', 'rows must be a list.', 'rows');
|
|
164
|
+
const wire = rows.map((r, i) => (0, pager_js_1.defined)({ customer_user_id: (0, http_js_1.requireId)(r?.customerId, `rows[${i}].customer_id`), external_code: r.externalCode, display_name: r.displayName }));
|
|
165
|
+
const jobs = [];
|
|
166
|
+
const batches = Math.ceil(wire.length / exports.REFERRER_IMPORT_BATCH);
|
|
167
|
+
for (let b = 0; b < batches; b++) {
|
|
168
|
+
const key = requestOptions.idempotencyKey && batches > 1 ? `${requestOptions.idempotencyKey}-${b}` : requestOptions.idempotencyKey;
|
|
169
|
+
const body = { referrers: wire.slice(b * exports.REFERRER_IMPORT_BATCH, (b + 1) * exports.REFERRER_IMPORT_BATCH) };
|
|
170
|
+
const { data } = await this.call('POST', `/v1/referral-programs/${program}/referrers/import`, { body }, { ...requestOptions, idempotencyKey: key });
|
|
171
|
+
jobs.push(data);
|
|
172
|
+
}
|
|
173
|
+
return jobs;
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Block a referrer: their code and link stop creating referrals.
|
|
177
|
+
*
|
|
178
|
+
* @example
|
|
179
|
+
* await clikgate.referrals.blockReferrer('rfr_01J…', { reason: 'Fake installs' });
|
|
180
|
+
*/
|
|
181
|
+
async blockReferrer(referrerId, params = {}, requestOptions = {}) {
|
|
182
|
+
const path = `/v1/referrers/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referrerId, 'referrer_id'))}/block`;
|
|
183
|
+
const { data } = await this.call('POST', path, { body: (0, pager_js_1.defined)({ reason: params?.reason }) }, requestOptions);
|
|
184
|
+
return (0, currency_js_1.toReferrer)(data);
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* Unblock a referrer.
|
|
188
|
+
*
|
|
189
|
+
* @example
|
|
190
|
+
* await clikgate.referrals.unblockReferrer('rfr_01J…');
|
|
191
|
+
*/
|
|
192
|
+
async unblockReferrer(referrerId, requestOptions = {}) {
|
|
193
|
+
const { data } = await this.call('POST', `/v1/referrers/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referrerId, 'referrer_id'))}/unblock`, {}, requestOptions);
|
|
194
|
+
return (0, currency_js_1.toReferrer)(data);
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* Update a referrer's display name or your own attributes (`null` clears).
|
|
198
|
+
*
|
|
199
|
+
* @example
|
|
200
|
+
* await clikgate.referrals.updateReferrer('rfr_01J…', { displayName: 'Ada O.', attributes: { tier: 'gold' } });
|
|
201
|
+
*/
|
|
202
|
+
async updateReferrer(referrerId, params, requestOptions = {}) {
|
|
203
|
+
const body = (0, pager_js_1.defined)({ display_name: params?.displayName, attributes: params?.attributes });
|
|
204
|
+
const { data } = await this.call('PATCH', `/v1/referrers/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(referrerId, 'referrer_id'))}`, { body }, requestOptions);
|
|
205
|
+
return (0, currency_js_1.toReferrer)(data);
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
exports.Referrals = Referrals;
|
package/dist/cjs/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/cjs/resources.js
CHANGED
|
@@ -5,6 +5,7 @@ const guard_js_1 = require("./guard.js");
|
|
|
5
5
|
const http_js_1 = require("./http.js");
|
|
6
6
|
const money_js_1 = require("./money.js");
|
|
7
7
|
const ads_hashing_js_1 = require("./ads-hashing.js");
|
|
8
|
+
const pager_js_1 = require("./pager.js");
|
|
8
9
|
function withFormattedValue(core, params) {
|
|
9
10
|
const out = {};
|
|
10
11
|
for (const [k, v] of Object.entries(params))
|
|
@@ -66,13 +67,6 @@ class Links {
|
|
|
66
67
|
constructor(core) {
|
|
67
68
|
this.core = core;
|
|
68
69
|
}
|
|
69
|
-
/**
|
|
70
|
-
* Create a link. The result's `warnings` include `no_preview` when there is no preview title and image.
|
|
71
|
-
*
|
|
72
|
-
* @example
|
|
73
|
-
* const link = await clikgate.links.create({ destination_url: 'https://example.com/spring', og_title: 'Spring sale', og_image_url: 'https://example.com/og.png' });
|
|
74
|
-
* console.log(link.short_url, link.warnings);
|
|
75
|
-
*/
|
|
76
70
|
async create(params, requestOptions = {}) {
|
|
77
71
|
const { data } = await this.core.requester.request({ method: 'POST', path: '/v1/links', body: params, ...requestOptions });
|
|
78
72
|
return data;
|
|
@@ -87,15 +81,6 @@ class Links {
|
|
|
87
81
|
const { data } = await this.core.requester.request({ method: 'GET', path: `/v1/links/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(id))}`, ...requestOptions });
|
|
88
82
|
return data;
|
|
89
83
|
}
|
|
90
|
-
/**
|
|
91
|
-
* Update a link. With two-person approval on, a destination change answers `202` and waits for a
|
|
92
|
-
* second person: the result is `{ applied: false, change_request }`. A locked link throws {@link LinkLockedError}.
|
|
93
|
-
* An explicit `null` clears a field.
|
|
94
|
-
*
|
|
95
|
-
* @example
|
|
96
|
-
* const result = await clikgate.links.update('lnk_01J…', { destination_url: 'https://example.com/summer' });
|
|
97
|
-
* if (!result.applied) console.log('waiting for approval:', result.change_request.id);
|
|
98
|
-
*/
|
|
99
84
|
async update(id, params, requestOptions = {}) {
|
|
100
85
|
const { status, data } = await this.core.requester.request({
|
|
101
86
|
method: 'PATCH',
|
|
@@ -127,32 +112,48 @@ class Links {
|
|
|
127
112
|
* }
|
|
128
113
|
*/
|
|
129
114
|
list(params = {}, requestOptions = {}) {
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
115
|
+
return (0, pager_js_1.paginate)((cursor) => this.listPage(cursor ? { ...params, starting_after: cursor } : params, requestOptions));
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Archive a link (`DELETE /v1/links/{id}`): it stops redirecting. Returns the archived link.
|
|
119
|
+
*
|
|
120
|
+
* @example
|
|
121
|
+
* const link = await clikgate.links.archive('lnk_01J…');
|
|
122
|
+
*/
|
|
123
|
+
async archive(id, requestOptions = {}) {
|
|
124
|
+
const { data } = await this.core.requester.request({ method: 'DELETE', path: `/v1/links/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(id))}`, ...requestOptions });
|
|
125
|
+
return data;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Fetch a link by your own external reference (`external_reference`).
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* const link = await clikgate.links.getByReference('order-1001');
|
|
132
|
+
*/
|
|
133
|
+
async getByReference(reference, requestOptions = {}) {
|
|
134
|
+
const path = `/v1/links/by-reference/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(reference, 'reference'))}`;
|
|
135
|
+
const { data } = await this.core.requester.request({ method: 'GET', path, ...requestOptions });
|
|
136
|
+
return data;
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Pause a link: visitors see the paused page until you resume it.
|
|
140
|
+
*
|
|
141
|
+
* @example
|
|
142
|
+
* const link = await clikgate.links.pause('lnk_01J…');
|
|
143
|
+
*/
|
|
144
|
+
async pause(id, requestOptions = {}) {
|
|
145
|
+
const { data } = await this.core.requester.request({ method: 'POST', path: `/v1/links/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(id))}/pause`, ...requestOptions });
|
|
146
|
+
return data;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Resume a paused link.
|
|
150
|
+
*
|
|
151
|
+
* @example
|
|
152
|
+
* const link = await clikgate.links.resume('lnk_01J…');
|
|
153
|
+
*/
|
|
154
|
+
async resume(id, requestOptions = {}) {
|
|
155
|
+
const { data } = await this.core.requester.request({ method: 'POST', path: `/v1/links/${(0, http_js_1.encodePathSegment)((0, http_js_1.requireId)(id))}/resume`, ...requestOptions });
|
|
156
|
+
return data;
|
|
156
157
|
}
|
|
157
158
|
/**
|
|
158
159
|
* Download the link's QR code.
|