@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/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/cjs/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.
|
|
2
|
+
export declare const VERSION = "2.1.0";
|
package/dist/cjs/version.js
CHANGED
package/dist/cjs/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/cjs/webhooks.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.webhooks = void 0;
|
|
4
|
+
exports.withAccessors = withAccessors;
|
|
4
5
|
const node_crypto_1 = require("node:crypto");
|
|
5
6
|
const errors_js_1 = require("./errors.js");
|
|
7
|
+
const currency_js_1 = require("./currency.js");
|
|
6
8
|
const fail = (code, message) => new errors_js_1.SignatureVerificationError({ message, code });
|
|
7
9
|
function toBytes(raw) {
|
|
8
10
|
if (typeof raw === 'string')
|
|
@@ -69,6 +71,44 @@ function verifyWith(rawBody, signatureHeader, secrets, options) {
|
|
|
69
71
|
}
|
|
70
72
|
if (!event || typeof event !== 'object' || Array.isArray(event))
|
|
71
73
|
throw fail('invalid_payload', 'The body is not an event object.');
|
|
74
|
+
return withAccessors(event);
|
|
75
|
+
}
|
|
76
|
+
function objectOf(event, family) {
|
|
77
|
+
const type = event.type;
|
|
78
|
+
if (typeof type !== 'string' || !type.startsWith(`${family}.`))
|
|
79
|
+
return null;
|
|
80
|
+
const data = event.data;
|
|
81
|
+
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
82
|
+
return null;
|
|
83
|
+
const object = data.object;
|
|
84
|
+
return object && typeof object === 'object' && !Array.isArray(object) ? object : null;
|
|
85
|
+
}
|
|
86
|
+
/** @internal Add the typed accessors as non-enumerable methods (JSON.stringify(event) is unchanged). */
|
|
87
|
+
function withAccessors(event) {
|
|
88
|
+
const accessors = {
|
|
89
|
+
asReferral: () => {
|
|
90
|
+
const o = objectOf(event, 'referral');
|
|
91
|
+
return o ? (0, currency_js_1.toReferral)(o) : null;
|
|
92
|
+
},
|
|
93
|
+
asReferrer: () => {
|
|
94
|
+
const o = objectOf(event, 'referrer');
|
|
95
|
+
return o ? (0, currency_js_1.toReferrer)(o) : null;
|
|
96
|
+
},
|
|
97
|
+
asGoalEvent: () => objectOf(event, 'goal'),
|
|
98
|
+
asInstall: () => objectOf(event, 'install'),
|
|
99
|
+
asPayment: () => objectOf(event, 'payment'),
|
|
100
|
+
asConversion: () => objectOf(event, 'conversion'),
|
|
101
|
+
asDeviceChange: () => {
|
|
102
|
+
if (event.type !== 'person.device_changed')
|
|
103
|
+
return null;
|
|
104
|
+
const data = event.data;
|
|
105
|
+
const object = data && typeof data === 'object' ? data.object : null;
|
|
106
|
+
return object && typeof object === 'object' && !Array.isArray(object) ? object : null;
|
|
107
|
+
},
|
|
108
|
+
typed: () => event,
|
|
109
|
+
};
|
|
110
|
+
for (const [name, fn] of Object.entries(accessors))
|
|
111
|
+
Object.defineProperty(event, name, { value: fn, enumerable: false, writable: true, configurable: true });
|
|
72
112
|
return event;
|
|
73
113
|
}
|
|
74
114
|
/**
|
|
@@ -81,10 +121,11 @@ exports.webhooks = {
|
|
|
81
121
|
*
|
|
82
122
|
* @example
|
|
83
123
|
* import express from 'express';
|
|
84
|
-
* import { webhooks } from '@clikgate/node';
|
|
124
|
+
* import { webhooks, EventType } from '@clikgate/node';
|
|
85
125
|
* app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
|
|
86
126
|
* const event = webhooks.verify(req.body, req.get('Clikgate-Signature'), process.env.CLIKGATE_WEBHOOK_SECRET!);
|
|
87
|
-
*
|
|
127
|
+
* const referral = event.asReferral(); // null for other event types
|
|
128
|
+
* if (referral && event.type === EventType.ReferralQualified) { … } // dedupe on event.id: delivery is at-least-once
|
|
88
129
|
* res.sendStatus(200);
|
|
89
130
|
* });
|
|
90
131
|
*/
|
package/dist/esm/client.d.ts
CHANGED
|
@@ -1,28 +1,47 @@
|
|
|
1
1
|
import { ClickIds } from './click-ids.js';
|
|
2
2
|
import { type OnError } from './core.js';
|
|
3
3
|
import { type IdentityTokenOptions } from './identity.js';
|
|
4
|
+
import { type Installation } from './installation.js';
|
|
4
5
|
import type { RequestOptions } from './http.js';
|
|
5
6
|
import { ApiClient } from './generated/index.js';
|
|
6
7
|
import { Goals, type GoalOptions } from './goals.js';
|
|
7
8
|
import { type Clock } from './http.js';
|
|
8
9
|
import { type Logger } from './logger.js';
|
|
9
10
|
import { Payments } from './payments.js';
|
|
11
|
+
import { KnownCustomers } from './known-customers.js';
|
|
10
12
|
import { Clicks, Conversions, Links } from './resources.js';
|
|
13
|
+
import { Referrals } from './referrals.js';
|
|
14
|
+
import { Codes, Installs, People, Privacy } from './lookups.js';
|
|
11
15
|
import { type FetchLike } from './transport.js';
|
|
12
16
|
import type { ServerSdkConfig } from './types.js';
|
|
13
17
|
import { webhooks } from './webhooks.js';
|
|
14
18
|
/** Client options (SPEC section 3). Every option is optional. */
|
|
15
|
-
/** `identifyUser()`: at least one of `clickId`, `
|
|
19
|
+
/** `identifyUser()`: at least one of `clickId`, an installation (`installation` or `installationId`), `customerId`. */
|
|
16
20
|
export interface IdentifyUserParams {
|
|
17
21
|
/** The Clikgate click ID you kept (`clk_…`). */
|
|
18
22
|
clickId?: string | null;
|
|
19
|
-
/**
|
|
23
|
+
/**
|
|
24
|
+
* The app's installation: the raw `Clikgate-Installation` header your app sent (`<app_id>:<installation_id>`), or
|
|
25
|
+
* the parsed `Installation` the framework helpers give (`req.clikgate.installation`, `getInstallation(...)`). It
|
|
26
|
+
* fills `appId` and `installationId`. Missing or invalid values (either form) are ignored, never sent. Not used when
|
|
27
|
+
* `installationId` is given.
|
|
28
|
+
*/
|
|
29
|
+
installation?: string | Installation | null;
|
|
30
|
+
/** The app the installation belongs to. Optional: without it Clikgate finds the app. Only with `installationId`. */
|
|
20
31
|
appId?: string | null;
|
|
32
|
+
/** The SDK's installation ID, sent by your app. */
|
|
21
33
|
installationId?: string | null;
|
|
22
|
-
/** Your
|
|
34
|
+
/** Your signed-in user's ID. Never read it from the request. With a click or installation, links it to this customer. */
|
|
23
35
|
customerId?: string | null;
|
|
24
36
|
/** A label your team sees instead of the click ID (1–80 characters, `''` clears it). */
|
|
25
37
|
label?: string | null;
|
|
38
|
+
/**
|
|
39
|
+
* When this customer became your customer: `'YYYY-MM-DD'`, an ISO 8601 date-time with offset, a
|
|
40
|
+
* `Date` or Unix seconds. Needs `customerId`. Clikgate keeps the earliest date it gets. Not in private mode.
|
|
41
|
+
*/
|
|
42
|
+
customerSince?: string | Date | number | null;
|
|
43
|
+
/** `true` lets `customerSince` move a wrong date later (audit-logged). Default: the earliest date is kept. */
|
|
44
|
+
customerSinceReplace?: boolean | null;
|
|
26
45
|
}
|
|
27
46
|
/** The answer of `identifyUser()`. */
|
|
28
47
|
export interface PersonIdentified {
|
|
@@ -30,6 +49,10 @@ export interface PersonIdentified {
|
|
|
30
49
|
person_id: string;
|
|
31
50
|
/** `plan`: below Growth the label isn't stored; `lower_rank`: a label your team set was kept. */
|
|
32
51
|
label_ignored: 'plan' | 'lower_rank' | null;
|
|
52
|
+
/** Why `customerSince` wasn't used: `unverified` or `invalid`. */
|
|
53
|
+
customer_since_ignored?: 'unverified' | 'invalid' | null;
|
|
54
|
+
/** The customer ID looks like an email, phone number or national ID: use your own user ID instead. */
|
|
55
|
+
customer_id_warning?: 'looks_like_email' | 'looks_like_phone' | 'looks_like_national_id' | null;
|
|
33
56
|
}
|
|
34
57
|
export interface ClikgateOptions {
|
|
35
58
|
/** `cg_live_…` or `cg_test_…`. Default: `process.env.CLIKGATE_API_KEY`. The mode comes from the prefix. */
|
|
@@ -92,6 +115,18 @@ export declare class Clikgate {
|
|
|
92
115
|
readonly links: Links;
|
|
93
116
|
/** Clicks. */
|
|
94
117
|
readonly clicks: Clicks;
|
|
118
|
+
/** Existing customers from before you added Clikgate: `import()` and `remove()`. */
|
|
119
|
+
readonly knownCustomers: KnownCustomers;
|
|
120
|
+
/** Referrals: referrers (`getOrCreateReferrer`, `findReferrer`), referrals, overrides, steps and imports. */
|
|
121
|
+
readonly referrals: Referrals;
|
|
122
|
+
/** Privacy requests: `createRequest`, `getRequest`. */
|
|
123
|
+
readonly privacy: Privacy;
|
|
124
|
+
/** People: `get`, `search`, `setLabel`. */
|
|
125
|
+
readonly people: People;
|
|
126
|
+
/** Installs: `getByCustomer`, `getByInstallation`. */
|
|
127
|
+
readonly installs: Installs;
|
|
128
|
+
/** Offline and referral codes: `redeem`. */
|
|
129
|
+
readonly codes: Codes;
|
|
95
130
|
/** Click-ID helpers using this client's `clickIdParam` (or the organisation's from config). */
|
|
96
131
|
readonly clickIds: ClickIds;
|
|
97
132
|
/** Every API-key operation, generated from openapi.json ("advanced"). */
|
|
@@ -129,20 +164,29 @@ export declare class Clikgate {
|
|
|
129
164
|
*/
|
|
130
165
|
createIdentityToken(customerId: string, options?: IdentityTokenOptions): string;
|
|
131
166
|
/**
|
|
132
|
-
* Tell Clikgate who a person is (`POST /v1/people/identify`): a click (`clickId`), an app installation
|
|
133
|
-
* `installationId`) or your `customerId`, at least one. With a click or installation, `customerId` links it to that
|
|
167
|
+
* Tell Clikgate who a person is (`POST /v1/people/identify`): a click (`clickId`), an app installation
|
|
168
|
+
* (`installation`, or `installationId` with an optional `appId`) or your `customerId`, at least one. With a click or installation, `customerId` links it to that
|
|
134
169
|
* customer. `label` is what your team sees instead of the click ID (1–80 characters, `''` clears it; Growth and
|
|
135
170
|
* up). Always verified (your server), so it also satisfies a referral program's `require_identity_token`.
|
|
136
171
|
* In private mode `customerId` is refused locally (the guard) and `label` needs "Allow labels in private mode".
|
|
172
|
+
* `customerSince` is when they became your customer, so existing customers are never counted as
|
|
173
|
+
* referrals or new customers; it is refused in private mode too.
|
|
137
174
|
*
|
|
138
|
-
* Path B of https://clikgate.com/docs/identify-users (no identity secret or token): the app
|
|
139
|
-
* `
|
|
140
|
-
*
|
|
141
|
-
*
|
|
175
|
+
* Path B of https://clikgate.com/docs/identify-users (no identity secret or token): the app sends the
|
|
176
|
+
* `Clikgate-Installation` header (from the mobile SDK) to your server. After your own sign-in check succeeds, and at
|
|
177
|
+
* every signed-in app open, pass the header as `installation` with your signed-in user's ID as `customerId` (never a
|
|
178
|
+
* customer ID read from the request). When the header is missing or invalid (tracking is off), skip the call.
|
|
179
|
+
* `appId` is optional: Clikgate finds the app. If the installation ID is in several of your apps, the API answers
|
|
180
|
+
* `409 installation_in_several_apps` (a `ConflictError`, param `app_id`): send `appId` too. Clikgate accepts
|
|
181
|
+
* installations active in the last 7 days.
|
|
142
182
|
*
|
|
143
183
|
* @example
|
|
144
184
|
* await clikgate.identifyUser({ clickId: order.clickId, customerId: 'user_42', label: 'Ada (VIP)' });
|
|
145
|
-
*
|
|
185
|
+
* // after your sign-in check: the header from the app, your user's ID
|
|
186
|
+
* const installation = req.get('Clikgate-Installation');
|
|
187
|
+
* if (parseInstallationHeader(installation)) await clikgate.identifyUser({ installation, customerId: req.user.id });
|
|
188
|
+
* // or the parsed installation from the Express middleware
|
|
189
|
+
* if (req.clikgate.installation) await clikgate.identifyUser({ installation: req.clikgate.installation, customerId: req.user.id });
|
|
146
190
|
*/
|
|
147
191
|
identifyUser(params: IdentifyUserParams, requestOptions?: RequestOptions): Promise<PersonIdentified>;
|
|
148
192
|
/**
|
package/dist/esm/client.js
CHANGED
|
@@ -4,16 +4,32 @@ import { Core } from './core.js';
|
|
|
4
4
|
import { ConfigurationError, localError } from './errors.js';
|
|
5
5
|
import { createIdentityTokenWith } from './identity.js';
|
|
6
6
|
import { guardPayload } from './guard.js';
|
|
7
|
+
import { toInstallation } from './installation.js';
|
|
7
8
|
import { ApiClient } from './generated/index.js';
|
|
8
9
|
import { GoalQueue, Goals, asClikgateError, buildGoalWire, checkBeforeSend } from './goals.js';
|
|
9
10
|
import { Requester, systemClock } from './http.js';
|
|
10
11
|
import { consoleLogger } from './logger.js';
|
|
11
12
|
import { Payments } from './payments.js';
|
|
13
|
+
import { KnownCustomers } from './known-customers.js';
|
|
12
14
|
import { Clicks, Conversions, Links } from './resources.js';
|
|
15
|
+
import { Referrals } from './referrals.js';
|
|
16
|
+
import { Codes, Installs, People, Privacy } from './lookups.js';
|
|
13
17
|
import { registerShutdown, unregisterShutdown } from './shutdown.js';
|
|
14
18
|
import { fetchTransport, nodeTransport } from './transport.js';
|
|
15
19
|
import { userAgent } from './user-agent.js';
|
|
16
20
|
import { webhooks } from './webhooks.js';
|
|
21
|
+
/** @internal The wire form of identifyUser's customerSince. */
|
|
22
|
+
function sinceWire(value) {
|
|
23
|
+
if (typeof value === 'string') {
|
|
24
|
+
if (!/^\d{4}-\d{2}-\d{2}(T.+)?$/.test(value))
|
|
25
|
+
throw localError('invalid_argument', "customerSince must be 'YYYY-MM-DD', an ISO 8601 date-time, a Date or Unix seconds.", 'customer_since');
|
|
26
|
+
return value;
|
|
27
|
+
}
|
|
28
|
+
const ms = value instanceof Date ? value.getTime() : typeof value === 'number' && Number.isSafeInteger(value) ? value * 1000 : Number.NaN;
|
|
29
|
+
if (!Number.isFinite(ms))
|
|
30
|
+
throw localError('invalid_argument', "customerSince must be 'YYYY-MM-DD', an ISO 8601 date-time, a Date or Unix seconds.", 'customer_since');
|
|
31
|
+
return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
|
|
32
|
+
}
|
|
17
33
|
const KEY = /^cg_(live|test)_[A-Za-z0-9_]+$/;
|
|
18
34
|
const PARAM = /^[A-Za-z0-9_]{1,32}$/;
|
|
19
35
|
const LOCAL = new Set(['localhost', '127.0.0.1', '[::1]']);
|
|
@@ -54,6 +70,18 @@ export class Clikgate {
|
|
|
54
70
|
links;
|
|
55
71
|
/** Clicks. */
|
|
56
72
|
clicks;
|
|
73
|
+
/** Existing customers from before you added Clikgate: `import()` and `remove()`. */
|
|
74
|
+
knownCustomers;
|
|
75
|
+
/** Referrals: referrers (`getOrCreateReferrer`, `findReferrer`), referrals, overrides, steps and imports. */
|
|
76
|
+
referrals;
|
|
77
|
+
/** Privacy requests: `createRequest`, `getRequest`. */
|
|
78
|
+
privacy;
|
|
79
|
+
/** People: `get`, `search`, `setLabel`. */
|
|
80
|
+
people;
|
|
81
|
+
/** Installs: `getByCustomer`, `getByInstallation`. */
|
|
82
|
+
installs;
|
|
83
|
+
/** Offline and referral codes: `redeem`. */
|
|
84
|
+
codes;
|
|
57
85
|
/** Click-ID helpers using this client's `clickIdParam` (or the organisation's from config). */
|
|
58
86
|
clickIds;
|
|
59
87
|
/** Every API-key operation, generated from openapi.json ("advanced"). */
|
|
@@ -72,7 +100,7 @@ export class Clikgate {
|
|
|
72
100
|
throw new ConfigurationError({ message: 'No API key: pass { apiKey } or set CLIKGATE_API_KEY (cg_live_… or cg_test_…).', code: 'missing_api_key', param: 'apiKey' });
|
|
73
101
|
const m = KEY.exec(apiKey);
|
|
74
102
|
if (!m)
|
|
75
|
-
throw new ConfigurationError({ message: `The API key is ${keyType(apiKey)}. Server SDKs need a cg_live_… or cg_test_… API key from Developers
|
|
103
|
+
throw new ConfigurationError({ message: `The API key is ${keyType(apiKey)}. Server SDKs need a cg_live_… or cg_test_… API key from Developers › API keys & clients.`, code: 'invalid_api_key', param: 'apiKey' });
|
|
76
104
|
this.mode = m[1];
|
|
77
105
|
const baseUrl = (options.baseUrl ?? process.env.CLIKGATE_BASE_URL ?? 'https://api.clikgate.com').replace(/\/+$/, '');
|
|
78
106
|
let parsed;
|
|
@@ -113,6 +141,12 @@ export class Clikgate {
|
|
|
113
141
|
this.payments = new Payments(this.core);
|
|
114
142
|
this.links = new Links(this.core);
|
|
115
143
|
this.clicks = new Clicks(this.core);
|
|
144
|
+
this.knownCustomers = new KnownCustomers(this.core);
|
|
145
|
+
this.referrals = new Referrals(this.core);
|
|
146
|
+
this.privacy = new Privacy(this.core);
|
|
147
|
+
this.people = new People(this.core);
|
|
148
|
+
this.installs = new Installs(this.core);
|
|
149
|
+
this.codes = new Codes(this.core);
|
|
116
150
|
const explicitParam = options.clickIdParam;
|
|
117
151
|
this.clickIds = new ClickIds(() => explicitParam ?? configCache.peek()?.click_id_param ?? 'cgid');
|
|
118
152
|
this.api = new ApiClient(requester);
|
|
@@ -180,40 +214,65 @@ export class Clikgate {
|
|
|
180
214
|
return createIdentityTokenWith(this.identitySource, customerId, options);
|
|
181
215
|
}
|
|
182
216
|
/**
|
|
183
|
-
* Tell Clikgate who a person is (`POST /v1/people/identify`): a click (`clickId`), an app installation
|
|
184
|
-
* `installationId`) or your `customerId`, at least one. With a click or installation, `customerId` links it to that
|
|
217
|
+
* Tell Clikgate who a person is (`POST /v1/people/identify`): a click (`clickId`), an app installation
|
|
218
|
+
* (`installation`, or `installationId` with an optional `appId`) or your `customerId`, at least one. With a click or installation, `customerId` links it to that
|
|
185
219
|
* customer. `label` is what your team sees instead of the click ID (1–80 characters, `''` clears it; Growth and
|
|
186
220
|
* up). Always verified (your server), so it also satisfies a referral program's `require_identity_token`.
|
|
187
221
|
* In private mode `customerId` is refused locally (the guard) and `label` needs "Allow labels in private mode".
|
|
222
|
+
* `customerSince` is when they became your customer, so existing customers are never counted as
|
|
223
|
+
* referrals or new customers; it is refused in private mode too.
|
|
188
224
|
*
|
|
189
|
-
* Path B of https://clikgate.com/docs/identify-users (no identity secret or token): the app
|
|
190
|
-
* `
|
|
191
|
-
*
|
|
192
|
-
*
|
|
225
|
+
* Path B of https://clikgate.com/docs/identify-users (no identity secret or token): the app sends the
|
|
226
|
+
* `Clikgate-Installation` header (from the mobile SDK) to your server. After your own sign-in check succeeds, and at
|
|
227
|
+
* every signed-in app open, pass the header as `installation` with your signed-in user's ID as `customerId` (never a
|
|
228
|
+
* customer ID read from the request). When the header is missing or invalid (tracking is off), skip the call.
|
|
229
|
+
* `appId` is optional: Clikgate finds the app. If the installation ID is in several of your apps, the API answers
|
|
230
|
+
* `409 installation_in_several_apps` (a `ConflictError`, param `app_id`): send `appId` too. Clikgate accepts
|
|
231
|
+
* installations active in the last 7 days.
|
|
193
232
|
*
|
|
194
233
|
* @example
|
|
195
234
|
* await clikgate.identifyUser({ clickId: order.clickId, customerId: 'user_42', label: 'Ada (VIP)' });
|
|
196
|
-
*
|
|
235
|
+
* // after your sign-in check: the header from the app, your user's ID
|
|
236
|
+
* const installation = req.get('Clikgate-Installation');
|
|
237
|
+
* if (parseInstallationHeader(installation)) await clikgate.identifyUser({ installation, customerId: req.user.id });
|
|
238
|
+
* // or the parsed installation from the Express middleware
|
|
239
|
+
* if (req.clikgate.installation) await clikgate.identifyUser({ installation: req.clikgate.installation, customerId: req.user.id });
|
|
197
240
|
*/
|
|
198
241
|
async identifyUser(params, requestOptions = {}) {
|
|
199
242
|
const p = (params ?? {});
|
|
200
|
-
|
|
201
|
-
|
|
243
|
+
let appId = p.appId;
|
|
244
|
+
let installationId = p.installationId;
|
|
245
|
+
if (installationId == null && p.installation != null) {
|
|
246
|
+
const fromHeader = toInstallation(p.installation);
|
|
247
|
+
if (fromHeader) {
|
|
248
|
+
appId = appId ?? fromHeader.appId;
|
|
249
|
+
installationId = fromHeader.installationId;
|
|
250
|
+
}
|
|
202
251
|
}
|
|
203
|
-
if (
|
|
204
|
-
throw localError('invalid_request', 'Send
|
|
252
|
+
if (appId != null && installationId == null) {
|
|
253
|
+
throw localError('invalid_request', 'Send installationId with appId.', 'installation_id');
|
|
254
|
+
}
|
|
255
|
+
if (p.clickId == null && installationId == null && p.customerId == null) {
|
|
256
|
+
throw localError('invalid_request', 'Send clickId, an installation (installation or installationId), or customerId.', 'click_id');
|
|
205
257
|
}
|
|
206
258
|
const body = {};
|
|
207
259
|
if (p.clickId != null)
|
|
208
260
|
body.click_id = p.clickId;
|
|
209
|
-
if (
|
|
210
|
-
body.app_id =
|
|
211
|
-
if (
|
|
212
|
-
body.installation_id =
|
|
261
|
+
if (appId != null)
|
|
262
|
+
body.app_id = appId;
|
|
263
|
+
if (installationId != null)
|
|
264
|
+
body.installation_id = installationId;
|
|
213
265
|
if (p.customerId != null)
|
|
214
266
|
body.customer_id = p.customerId;
|
|
215
267
|
if (p.label != null)
|
|
216
268
|
body.label = p.label;
|
|
269
|
+
if (p.customerSince != null) {
|
|
270
|
+
if (p.customerId == null)
|
|
271
|
+
throw localError('invalid_request', 'customerSince needs customerId.', 'customer_since');
|
|
272
|
+
body.customer_since = sinceWire(p.customerSince);
|
|
273
|
+
}
|
|
274
|
+
if (p.customerSinceReplace === true)
|
|
275
|
+
body.customer_since_replace = true;
|
|
217
276
|
const state = await this.core.guardState();
|
|
218
277
|
if (state.guard)
|
|
219
278
|
guardPayload('identify', body);
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** The ISO 4217 minor-unit exponent of a currency (2 when unknown). */
|
|
2
|
+
export declare function currencyExponent(currency: string): number;
|
|
3
|
+
/**
|
|
4
|
+
* Minor units to a decimal string in normal units, with exactly the currency's exponent of fraction digits
|
|
5
|
+
* (`50000` NGN → `"500.00"`, `1500` JPY → `"1500"`). No float is involved.
|
|
6
|
+
*/
|
|
7
|
+
export declare function minorToAmount(amountMinor: number | bigint, currency: string): string;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** ISO 4217 exponents other than 2 (the backend's list); every other code has 2. */
|
|
2
|
+
const EXPONENTS = {
|
|
3
|
+
BHD: 3, BIF: 0, CLF: 4, CLP: 0, DJF: 0, GNF: 0, IQD: 3, ISK: 0, JOD: 3, JPY: 0, KMF: 0, KRW: 0, KWD: 3,
|
|
4
|
+
LYD: 3, OMR: 3, PYG: 0, RWF: 0, TND: 3, UGX: 0, UYI: 0, UYW: 4, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
|
|
5
|
+
};
|
|
6
|
+
/** The ISO 4217 minor-unit exponent of a currency (2 when unknown). */
|
|
7
|
+
export function currencyExponent(currency) {
|
|
8
|
+
return EXPONENTS[currency.toUpperCase()] ?? 2;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* Minor units to a decimal string in normal units, with exactly the currency's exponent of fraction digits
|
|
12
|
+
* (`50000` NGN → `"500.00"`, `1500` JPY → `"1500"`). No float is involved.
|
|
13
|
+
*/
|
|
14
|
+
export function minorToAmount(amountMinor, currency) {
|
|
15
|
+
const exp = currencyExponent(currency);
|
|
16
|
+
const n = typeof amountMinor === 'bigint' ? amountMinor : BigInt(Math.trunc(amountMinor));
|
|
17
|
+
const negative = n < 0n;
|
|
18
|
+
const digits = (negative ? -n : n).toString().padStart(exp + 1, '0');
|
|
19
|
+
const whole = exp === 0 ? digits : `${digits.slice(0, -exp)}.${digits.slice(-exp)}`;
|
|
20
|
+
return negative ? `-${whole}` : whole;
|
|
21
|
+
}
|
|
22
|
+
function isObject(v) {
|
|
23
|
+
return typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
24
|
+
}
|
|
25
|
+
function side(v) {
|
|
26
|
+
if (!isObject(v))
|
|
27
|
+
return v;
|
|
28
|
+
const out = { ...v };
|
|
29
|
+
if ((typeof v.amount_minor === 'number' || typeof v.amount_minor === 'bigint') && typeof v.currency === 'string' && v.currency !== '') {
|
|
30
|
+
out.amount = minorToAmount(v.amount_minor, v.currency);
|
|
31
|
+
}
|
|
32
|
+
return out;
|
|
33
|
+
}
|
|
34
|
+
/** @internal Add `amount` next to each reward side's `amount_minor`. */
|
|
35
|
+
export function rewardInfo(v) {
|
|
36
|
+
if (!isObject(v))
|
|
37
|
+
return v;
|
|
38
|
+
const out = { ...v };
|
|
39
|
+
if ('referrer' in v)
|
|
40
|
+
out.referrer = side(v.referrer);
|
|
41
|
+
if ('referee' in v)
|
|
42
|
+
out.referee = side(v.referee);
|
|
43
|
+
return out;
|
|
44
|
+
}
|
|
45
|
+
/** @internal A referral with reward amounts. */
|
|
46
|
+
export function toReferral(data) {
|
|
47
|
+
if (!isObject(data))
|
|
48
|
+
return data;
|
|
49
|
+
const out = { ...data };
|
|
50
|
+
if (isObject(data.reward_snapshot))
|
|
51
|
+
out.reward_snapshot = rewardInfo(data.reward_snapshot);
|
|
52
|
+
if (isObject(data.referrer))
|
|
53
|
+
out.referrer = { ...data.referrer, customerId: data.referrer.customer_user_id };
|
|
54
|
+
if (isObject(data.referee))
|
|
55
|
+
out.referee = { ...data.referee, customerId: data.referee.customer_user_id ?? null };
|
|
56
|
+
return out;
|
|
57
|
+
}
|
|
58
|
+
/** @internal A referrer with `customerId` next to `customer_user_id`. */
|
|
59
|
+
export function toReferrer(data) {
|
|
60
|
+
if (!isObject(data))
|
|
61
|
+
return data;
|
|
62
|
+
return { ...data, customerId: data.customer_user_id };
|
|
63
|
+
}
|
|
64
|
+
/** @internal A referrer with `created`. */
|
|
65
|
+
export function toReferrerResult(data, status) {
|
|
66
|
+
return { ...toReferrer(data), created: status === 201 };
|
|
67
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Your customer IDs, in one canonical form: the same form the API stores and checks, so an ID
|
|
3
|
+
* sent from your server, an import and an identity token always match.
|
|
4
|
+
*
|
|
5
|
+
* - canonical form: Unicode NFC, trimmed of Unicode whitespace (and U+FEFF) at both ends, case kept;
|
|
6
|
+
* - warnings (first match wins): `empty`, `too_long` (more than 128 characters), `looks_like_email`,
|
|
7
|
+
* `looks_like_national_id` (exactly 11 digits, unless `allow11DigitIds`), `looks_like_phone`.
|
|
8
|
+
*
|
|
9
|
+
* Use your own stable user ID (for example `u_10482`), never an email, phone number, BVN or NIN.
|
|
10
|
+
*/
|
|
11
|
+
/** The longest customer ID kept as a known customer, in Unicode code points. */
|
|
12
|
+
export declare const CUSTOMER_ID_MAX_LENGTH = 128;
|
|
13
|
+
/** Why a customer ID can't be used as a known customer (the API's refusal reasons for the same checks). */
|
|
14
|
+
export type CustomerIdWarning = 'empty' | 'too_long' | 'looks_like_email' | 'looks_like_national_id' | 'looks_like_phone';
|
|
15
|
+
/** The canonical form of a customer ID: NFC, trimmed, case kept. */
|
|
16
|
+
export declare function canonicalCustomerId(customerId: string): string;
|
|
17
|
+
/**
|
|
18
|
+
* Why Clikgate wouldn't keep this ID as a known customer, or `null` when it's fine.
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* customerIdWarning('ada@example.com'); // 'looks_like_email'
|
|
22
|
+
* customerIdWarning('u_10482'); // null
|
|
23
|
+
*/
|
|
24
|
+
export declare function customerIdWarning(customerId: string, options?: {
|
|
25
|
+
allow11DigitIds?: boolean;
|
|
26
|
+
}): CustomerIdWarning | null;
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Your customer IDs, in one canonical form: the same form the API stores and checks, so an ID
|
|
3
|
+
* sent from your server, an import and an identity token always match.
|
|
4
|
+
*
|
|
5
|
+
* - canonical form: Unicode NFC, trimmed of Unicode whitespace (and U+FEFF) at both ends, case kept;
|
|
6
|
+
* - warnings (first match wins): `empty`, `too_long` (more than 128 characters), `looks_like_email`,
|
|
7
|
+
* `looks_like_national_id` (exactly 11 digits, unless `allow11DigitIds`), `looks_like_phone`.
|
|
8
|
+
*
|
|
9
|
+
* Use your own stable user ID (for example `u_10482`), never an email, phone number, BVN or NIN.
|
|
10
|
+
*/
|
|
11
|
+
/** Unicode White_Space characters plus U+FEFF (the byte-order mark). */
|
|
12
|
+
const TRIM = '\t\n\u000b\u000c\r \u0085\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff';
|
|
13
|
+
/** The longest customer ID kept as a known customer, in Unicode code points. */
|
|
14
|
+
export const CUSTOMER_ID_MAX_LENGTH = 128;
|
|
15
|
+
/** The canonical form of a customer ID: NFC, trimmed, case kept. */
|
|
16
|
+
export function canonicalCustomerId(customerId) {
|
|
17
|
+
const s = customerId.normalize('NFC');
|
|
18
|
+
let start = 0;
|
|
19
|
+
let end = s.length;
|
|
20
|
+
while (start < end && TRIM.includes(s[start]))
|
|
21
|
+
start++;
|
|
22
|
+
while (end > start && TRIM.includes(s[end - 1]))
|
|
23
|
+
end--;
|
|
24
|
+
return s.slice(start, end);
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Why Clikgate wouldn't keep this ID as a known customer, or `null` when it's fine.
|
|
28
|
+
*
|
|
29
|
+
* @example
|
|
30
|
+
* customerIdWarning('ada@example.com'); // 'looks_like_email'
|
|
31
|
+
* customerIdWarning('u_10482'); // null
|
|
32
|
+
*/
|
|
33
|
+
export function customerIdWarning(customerId, options = {}) {
|
|
34
|
+
const cid = canonicalCustomerId(customerId);
|
|
35
|
+
if (cid === '')
|
|
36
|
+
return 'empty';
|
|
37
|
+
if ([...cid].length > CUSTOMER_ID_MAX_LENGTH)
|
|
38
|
+
return 'too_long';
|
|
39
|
+
const at = cid.indexOf('@');
|
|
40
|
+
if (at >= 0 && cid.slice(at + 1).includes('.'))
|
|
41
|
+
return 'looks_like_email';
|
|
42
|
+
if (/^[0-9]{11}$/.test(cid))
|
|
43
|
+
return options.allow11DigitIds ? null : 'looks_like_national_id';
|
|
44
|
+
if (/^\+?[0-9]{10,15}$/.test(cid.replace(/[ -]/g, '')))
|
|
45
|
+
return 'looks_like_phone';
|
|
46
|
+
return null;
|
|
47
|
+
}
|
package/dist/esm/enums.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// Generated by server/codegen/generate.mjs from openapi.json (GoalKind, GoalStatus, Provider). Do not edit by hand.
|
|
2
|
-
// Source sha256
|
|
2
|
+
// Source sha256 3efd1f4fb7547b9b836402740027ff175d44649333c4b3a0003260c6ec5bd358.
|
|
3
3
|
/** A goal's kind, set in the goal's settings (never in a goal call): `standard` or `payment`. */
|
|
4
4
|
export const GoalKind = {
|
|
5
5
|
Standard: 'standard',
|