@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
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// Generated by server/codegen/generate.mjs from openapi.json. Do not edit by hand.
|
|
2
|
-
// Source sha256
|
|
2
|
+
// Source sha256 3efd1f4fb7547b9b836402740027ff175d44649333c4b3a0003260c6ec5bd358; OpenAPI Generator 7.26.0 (typescript-fetch, custom templates).
|
|
3
3
|
/* eslint-disable */
|
|
4
4
|
import { encodePathSegment } from '../http.js';
|
|
5
5
|
/**
|
|
@@ -913,6 +913,19 @@ export class AnalyticsApi {
|
|
|
913
913
|
const { data } = await this.r.request({ method: 'GET', path, query, ...options });
|
|
914
914
|
return data;
|
|
915
915
|
}
|
|
916
|
+
/**
|
|
917
|
+
* Device Changes Report
|
|
918
|
+
*
|
|
919
|
+
* `GET /v1/analytics/device-changes`
|
|
920
|
+
*
|
|
921
|
+
* @example
|
|
922
|
+
* await clikgate.api.analytics.deviceChangesReport();
|
|
923
|
+
*/
|
|
924
|
+
async deviceChangesReport(query = {}, options = {}) {
|
|
925
|
+
const path = `/v1/analytics/device-changes`;
|
|
926
|
+
const { data } = await this.r.request({ method: 'GET', path, query, ...options });
|
|
927
|
+
return data;
|
|
928
|
+
}
|
|
916
929
|
/**
|
|
917
930
|
* Explore
|
|
918
931
|
*
|
|
@@ -1703,6 +1716,21 @@ export class AppsApi {
|
|
|
1703
1716
|
const { data } = await this.r.request({ method: 'GET', path, ...options });
|
|
1704
1717
|
return data;
|
|
1705
1718
|
}
|
|
1719
|
+
/**
|
|
1720
|
+
* Iphone Deferred Deep Link Match Rate
|
|
1721
|
+
*
|
|
1722
|
+
* iOS first launches in the period (rolling, ending now) and what the iOS SDK's pasteboard step found: `attempted` (the paste flow ran), `matched` (attributed by the pasteboard token), `match_rate` (matched / attempted, `null` when nothing was attempted) and the outcome breakdown. Measured, never estimated. iOS apps only: an Android app answers 422 `platform_not_ios`.
|
|
1723
|
+
*
|
|
1724
|
+
* `GET /v1/apps/{app_id}/iphone-deferred-match-rate`
|
|
1725
|
+
*
|
|
1726
|
+
* @example
|
|
1727
|
+
* await clikgate.api.apps.iphoneDeferredDeepLinkMatchRate('app_…');
|
|
1728
|
+
*/
|
|
1729
|
+
async iphoneDeferredDeepLinkMatchRate(appId, query = {}, options = {}) {
|
|
1730
|
+
const path = `/v1/apps/${encodePathSegment(appId)}/iphone-deferred-match-rate`;
|
|
1731
|
+
const { data } = await this.r.request({ method: 'GET', path, query, ...options });
|
|
1732
|
+
return data;
|
|
1733
|
+
}
|
|
1706
1734
|
/**
|
|
1707
1735
|
* Link Subdomain Availability
|
|
1708
1736
|
*
|
|
@@ -4614,6 +4642,42 @@ export class JobsApi {
|
|
|
4614
4642
|
return data;
|
|
4615
4643
|
}
|
|
4616
4644
|
}
|
|
4645
|
+
/**
|
|
4646
|
+
* KnownCustomers: generated from openapi.json. See https://clikgate.com/docs/api.
|
|
4647
|
+
*/
|
|
4648
|
+
export class KnownCustomersApi {
|
|
4649
|
+
r;
|
|
4650
|
+
/** @internal */
|
|
4651
|
+
constructor(r) {
|
|
4652
|
+
this.r = r;
|
|
4653
|
+
}
|
|
4654
|
+
/**
|
|
4655
|
+
* Import Known Customers
|
|
4656
|
+
*
|
|
4657
|
+
* `POST /v1/known-customers/import`
|
|
4658
|
+
*
|
|
4659
|
+
* @example
|
|
4660
|
+
* await clikgate.api.knownCustomers.importKnownCustomers({ … });
|
|
4661
|
+
*/
|
|
4662
|
+
async importKnownCustomers(body, options = {}) {
|
|
4663
|
+
const path = `/v1/known-customers/import`;
|
|
4664
|
+
const { data } = await this.r.request({ method: 'POST', path, body, ...options });
|
|
4665
|
+
return data;
|
|
4666
|
+
}
|
|
4667
|
+
/**
|
|
4668
|
+
* Remove Known Customer
|
|
4669
|
+
*
|
|
4670
|
+
* `POST /v1/known-customers/remove`
|
|
4671
|
+
*
|
|
4672
|
+
* @example
|
|
4673
|
+
* await clikgate.api.knownCustomers.removeKnownCustomer({ … });
|
|
4674
|
+
*/
|
|
4675
|
+
async removeKnownCustomer(body, options = {}) {
|
|
4676
|
+
const path = `/v1/known-customers/remove`;
|
|
4677
|
+
const { data } = await this.r.request({ method: 'POST', path, body, ...options });
|
|
4678
|
+
return data;
|
|
4679
|
+
}
|
|
4680
|
+
}
|
|
4617
4681
|
/**
|
|
4618
4682
|
* Leaderboards: generated from openapi.json. See https://clikgate.com/docs/api.
|
|
4619
4683
|
*/
|
|
@@ -6857,6 +6921,19 @@ export class PeopleApi {
|
|
|
6857
6921
|
const { data } = await this.r.request({ method: 'GET', path, ...options });
|
|
6858
6922
|
return data;
|
|
6859
6923
|
}
|
|
6924
|
+
/**
|
|
6925
|
+
* Fetch Person Device Changes
|
|
6926
|
+
*
|
|
6927
|
+
* `GET /v1/people/{person_id}/device-changes`
|
|
6928
|
+
*
|
|
6929
|
+
* @example
|
|
6930
|
+
* await clikgate.api.people.fetchPersonDeviceChanges('<person_id>');
|
|
6931
|
+
*/
|
|
6932
|
+
async fetchPersonDeviceChanges(personId, options = {}) {
|
|
6933
|
+
const path = `/v1/people/${encodePathSegment(personId)}/device-changes`;
|
|
6934
|
+
const { data } = await this.r.request({ method: 'GET', path, ...options });
|
|
6935
|
+
return data;
|
|
6936
|
+
}
|
|
6860
6937
|
/**
|
|
6861
6938
|
* Identify Person
|
|
6862
6939
|
*
|
|
@@ -8668,6 +8745,7 @@ export class ApiClient {
|
|
|
8668
8745
|
inbound;
|
|
8669
8746
|
installs;
|
|
8670
8747
|
jobs;
|
|
8748
|
+
knownCustomers;
|
|
8671
8749
|
leaderboards;
|
|
8672
8750
|
links;
|
|
8673
8751
|
migration;
|
|
@@ -8727,6 +8805,7 @@ export class ApiClient {
|
|
|
8727
8805
|
this.inbound = new InboundApi(r);
|
|
8728
8806
|
this.installs = new InstallsApi(r);
|
|
8729
8807
|
this.jobs = new JobsApi(r);
|
|
8808
|
+
this.knownCustomers = new KnownCustomersApi(r);
|
|
8730
8809
|
this.leaderboards = new LeaderboardsApi(r);
|
|
8731
8810
|
this.links = new LinksApi(r);
|
|
8732
8811
|
this.migration = new MigrationApi(r);
|
package/dist/esm/identity.d.ts
CHANGED
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
* person signed in to your app. The app passes the token to the mobile SDK's `identifyUser()`.
|
|
4
4
|
*
|
|
5
5
|
* `token = base64url_nopad(HMAC_SHA256(secret, customerId + "." + issuedAt)) + "." + issuedAt`, the same signer
|
|
6
|
-
* Clikgate verifies with.
|
|
6
|
+
* Clikgate verifies with. With `customerSince` the token is version 2 and also carries the date the
|
|
7
|
+
* person became your customer: `signature.issuedAt.customerSince`. No network call.
|
|
8
|
+
* Guide: https://clikgate.com/docs/identify-users
|
|
7
9
|
*/
|
|
8
10
|
export interface IdentityTokenOptions {
|
|
9
11
|
/** The Clikgate app ID (`app_…`). Picks that app's secret from `identitySecrets` / `CLIKGATE_IDENTITY_SECRETS`. */
|
|
@@ -12,6 +14,11 @@ export interface IdentityTokenOptions {
|
|
|
12
14
|
secret?: string | null;
|
|
13
15
|
/** Unix seconds the token was issued at. Default: now. */
|
|
14
16
|
issuedAt?: number;
|
|
17
|
+
/**
|
|
18
|
+
* When this person became your customer (their account's creation time): a `Date` or Unix seconds. Makes a version 2
|
|
19
|
+
* token, so Clikgate can tell an existing customer from a new one (referrals, new customers). Not in private mode.
|
|
20
|
+
*/
|
|
21
|
+
customerSince?: Date | number | null;
|
|
15
22
|
}
|
|
16
23
|
/** The single secret's environment variable. */
|
|
17
24
|
export declare const IDENTITY_SECRET_ENV = "CLIKGATE_IDENTITY_SECRET";
|
|
@@ -23,10 +30,13 @@ export declare const IDENTITY_SECRETS_ENV = "CLIKGATE_IDENTITY_SECRETS";
|
|
|
23
30
|
* secret from `CLIKGATE_IDENTITY_SECRETS` (a JSON map). No network call; no API key needed.
|
|
24
31
|
*
|
|
25
32
|
* Throws {@link ClikgateServerOnlyError} in a browser or React Native, `ConfigurationError` when no secret is set,
|
|
26
|
-
*
|
|
33
|
+
* `InvalidRequestError` (`invalid_customer_id`) for an empty or over-long customer ID, and `InvalidRequestError`
|
|
34
|
+
* (`invalid_argument`, param `customer_since`) for an account date before 1990 or after the token's issue time.
|
|
27
35
|
*
|
|
28
36
|
* @example
|
|
29
37
|
* import { createIdentityToken } from '@clikgate/node';
|
|
30
38
|
* res.json({ user, clikgateIdentityToken: createIdentityToken(user.id) });
|
|
39
|
+
* // With the account date (version 2), so existing customers are never counted as referrals or new customers:
|
|
40
|
+
* res.json({ user, clikgateIdentityToken: createIdentityToken(user.id, { customerSince: user.createdAt }) });
|
|
31
41
|
*/
|
|
32
42
|
export declare function createIdentityToken(customerId: string, options?: IdentityTokenOptions): string;
|
package/dist/esm/identity.js
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
import { createHmac } from 'node:crypto';
|
|
2
|
+
import { canonicalCustomerId } from './customer-id.js';
|
|
2
3
|
import { ClikgateServerOnlyError, ConfigurationError, localError } from './errors.js';
|
|
3
4
|
/** The single secret's environment variable. */
|
|
4
5
|
export const IDENTITY_SECRET_ENV = 'CLIKGATE_IDENTITY_SECRET';
|
|
5
6
|
/** The per-app map's environment variable: a JSON object `{"app_…": "cgis_…"}`. */
|
|
6
7
|
export const IDENTITY_SECRETS_ENV = 'CLIKGATE_IDENTITY_SECRETS';
|
|
7
8
|
const MAX_CUSTOMER_ID = 255;
|
|
9
|
+
/** 1990-01-01: earlier account dates are refused. */
|
|
10
|
+
const MIN_CUSTOMER_SINCE = 631_152_000;
|
|
11
|
+
/** The clock allowance for an account date after `issuedAt`. */
|
|
12
|
+
const CLOCK_ALLOWANCE = 300;
|
|
8
13
|
/** @internal True in a browser (window or document) or React Native. */
|
|
9
14
|
export function isBrowserOrMobile(g = globalThis) {
|
|
10
15
|
if (typeof g.window !== 'undefined' || typeof g.document !== 'undefined')
|
|
@@ -50,7 +55,7 @@ function resolveSecret(options, source) {
|
|
|
50
55
|
}
|
|
51
56
|
throw new ConfigurationError({
|
|
52
57
|
message: appId === null
|
|
53
|
-
? `No identity secret: set ${IDENTITY_SECRET_ENV} on your server (
|
|
58
|
+
? `No identity secret: set ${IDENTITY_SECRET_ENV} on your server (Developers › SDKs › your app › Set up identity › Identity secret).`
|
|
54
59
|
: `No identity secret for this app: add it to ${IDENTITY_SECRETS_ENV} or set ${IDENTITY_SECRET_ENV}.`,
|
|
55
60
|
code: 'missing_identity_secret',
|
|
56
61
|
param: 'secret',
|
|
@@ -61,6 +66,22 @@ export function signIdentityToken(secret, customerId, issuedAt) {
|
|
|
61
66
|
const sig = createHmac('sha256', Buffer.from(secret, 'utf8')).update(Buffer.from(`${customerId}.${issuedAt}`, 'utf8')).digest('base64url');
|
|
62
67
|
return `${sig}.${issuedAt}`;
|
|
63
68
|
}
|
|
69
|
+
/**
|
|
70
|
+
* @internal Version 2: the MAC input is
|
|
71
|
+
* `"v2\n" + utf8Length(cid) + ":" + cid + "\n" + issuedAt + "\n" + customerSince`, cid in canonical form.
|
|
72
|
+
*/
|
|
73
|
+
export function signIdentityTokenV2(secret, customerId, issuedAt, customerSince) {
|
|
74
|
+
const cid = canonicalCustomerId(customerId);
|
|
75
|
+
const msg = `v2\n${Buffer.byteLength(cid, 'utf8')}:${cid}\n${issuedAt}\n${customerSince}`;
|
|
76
|
+
const sig = createHmac('sha256', Buffer.from(secret, 'utf8')).update(Buffer.from(msg, 'utf8')).digest('base64url');
|
|
77
|
+
return `${sig}.${issuedAt}.${customerSince}`;
|
|
78
|
+
}
|
|
79
|
+
function sinceSeconds(value) {
|
|
80
|
+
const s = value instanceof Date ? Math.floor(value.getTime() / 1000) : value;
|
|
81
|
+
if (typeof s !== 'number' || !Number.isSafeInteger(s))
|
|
82
|
+
throw localError('invalid_argument', 'customerSince must be a Date or whole Unix seconds.', 'customer_since');
|
|
83
|
+
return s;
|
|
84
|
+
}
|
|
64
85
|
/** @internal createIdentityToken with an explicit secret source (the client's options). */
|
|
65
86
|
export function createIdentityTokenWith(source, customerId, options = {}) {
|
|
66
87
|
if (isBrowserOrMobile())
|
|
@@ -73,7 +94,16 @@ export function createIdentityTokenWith(source, customerId, options = {}) {
|
|
|
73
94
|
const issuedAt = o.issuedAt ?? Math.floor(Date.now() / 1000);
|
|
74
95
|
if (!Number.isSafeInteger(issuedAt) || issuedAt < 0)
|
|
75
96
|
throw localError('invalid_argument', 'issuedAt must be whole Unix seconds.', 'issued_at');
|
|
76
|
-
|
|
97
|
+
if (o.customerSince == null)
|
|
98
|
+
return signIdentityToken(resolveSecret(o, source), customerId, issuedAt);
|
|
99
|
+
const since = sinceSeconds(o.customerSince);
|
|
100
|
+
if (since < MIN_CUSTOMER_SINCE || since > issuedAt + CLOCK_ALLOWANCE) {
|
|
101
|
+
throw localError('invalid_argument', 'customerSince must be between 1990 and the time the token is issued.', 'customer_since');
|
|
102
|
+
}
|
|
103
|
+
const cid = canonicalCustomerId(customerId);
|
|
104
|
+
if (cid === '')
|
|
105
|
+
throw localError('invalid_customer_id', 'customerId must be your own user ID as a string of 1-255 characters (never an email or phone number).', 'customer_id');
|
|
106
|
+
return signIdentityTokenV2(resolveSecret(o, source), cid, issuedAt, since);
|
|
77
107
|
}
|
|
78
108
|
/**
|
|
79
109
|
* Create an identity token for the signed-in user. Return it in your sign-in and "current user"
|
|
@@ -81,11 +111,14 @@ export function createIdentityTokenWith(source, customerId, options = {}) {
|
|
|
81
111
|
* secret from `CLIKGATE_IDENTITY_SECRETS` (a JSON map). No network call; no API key needed.
|
|
82
112
|
*
|
|
83
113
|
* Throws {@link ClikgateServerOnlyError} in a browser or React Native, `ConfigurationError` when no secret is set,
|
|
84
|
-
*
|
|
114
|
+
* `InvalidRequestError` (`invalid_customer_id`) for an empty or over-long customer ID, and `InvalidRequestError`
|
|
115
|
+
* (`invalid_argument`, param `customer_since`) for an account date before 1990 or after the token's issue time.
|
|
85
116
|
*
|
|
86
117
|
* @example
|
|
87
118
|
* import { createIdentityToken } from '@clikgate/node';
|
|
88
119
|
* res.json({ user, clikgateIdentityToken: createIdentityToken(user.id) });
|
|
120
|
+
* // With the account date (version 2), so existing customers are never counted as referrals or new customers:
|
|
121
|
+
* res.json({ user, clikgateIdentityToken: createIdentityToken(user.id, { customerSince: user.createdAt }) });
|
|
89
122
|
*/
|
|
90
123
|
export function createIdentityToken(customerId, options = {}) {
|
|
91
124
|
return createIdentityTokenWith({}, customerId, options);
|
package/dist/esm/index.d.ts
CHANGED
|
@@ -12,6 +12,9 @@
|
|
|
12
12
|
export { Clikgate, type ClikgateOptions, type IdentifyUserParams, type PersonIdentified } from './client.js';
|
|
13
13
|
export { ClickIds, clickIds, isValid as isValidClickId, CLICK_ID_PATTERN, CLICK_ID_HEADER, KEPT_COOKIE, KEPT_BY, BROWSER_ENGINES, PLATFORMS, type PersistOptions, type RequestLike, type ResponseLike, type KeptBy, type BrowserEngine, type Platform, type ClickContext, type KeepRoute, type KeepRouteOptions, type KeepInput, type KeepResult, } from './click-ids.js';
|
|
14
14
|
export { webhooks, type VerifyOptions, type RawBody } from './webhooks.js';
|
|
15
|
+
export { parseInstallationHeader, installationFromRequest, INSTALLATION_HEADER, INSTALLATION_HEADER_MAX_LENGTH, INSTALLATION_PATTERN, type Installation, type HeadersLike, } from './installation.js';
|
|
16
|
+
export { canonicalCustomerId, customerIdWarning, CUSTOMER_ID_MAX_LENGTH, type CustomerIdWarning } from './customer-id.js';
|
|
17
|
+
export { KNOWN_CUSTOMERS_BATCH, type KnownCustomers, type KnownCustomer, type KnownCustomerRefusal, type KnownCustomersImportResult } from './known-customers.js';
|
|
15
18
|
export { createIdentityToken, IDENTITY_SECRET_ENV, IDENTITY_SECRETS_ENV, type IdentityTokenOptions } from './identity.js';
|
|
16
19
|
export { formatValue, type MoneyInput } from './money.js';
|
|
17
20
|
export { hashForAds, type HashForAdsInput, type HashedIdentifiers } from './ads-hashing.js';
|
|
@@ -22,9 +25,16 @@ export type { Logger, WarningCode } from './logger.js';
|
|
|
22
25
|
export type { Clock, RequestOptions } from './http.js';
|
|
23
26
|
export type { FetchLike } from './transport.js';
|
|
24
27
|
export type { QrOptions, LinkIterator, Conversions, Links, Clicks } from './resources.js';
|
|
28
|
+
export { REFERRER_IMPORT_BATCH } from './referrals.js';
|
|
29
|
+
export type { Referrals, ReferrerCreateParams, ReferrerLookup, ReferralListParams, CompleteStepParams, ReferrerImportRow, ReferrerUpdateParams, } from './referrals.js';
|
|
30
|
+
export type { Privacy, PrivacyRequestParams, People, PeopleSearchOptions, Installs, Codes, CodeRedeemParams } from './lookups.js';
|
|
31
|
+
export type { PageIterator } from './pager.js';
|
|
32
|
+
export { EventType, type EventTypeValue } from './event-types.js';
|
|
33
|
+
export { currencyExponent, minorToAmount } from './currency.js';
|
|
34
|
+
export type { Referrer, ReferrerResult, ReferrerStats, Referral, ReferralStep, RewardInfo, RewardSide, Job, JobResult, PrivacyRequest, Person, PersonSummary, PersonSearchPage, Install, PaymentReport, ConversionObject, CodeRedemption, WebhookGoalEvent, DeviceChange, DeviceChangeSide, ReferralStateChange, LinkCreateParams, LinkUpdateParams, } from './models.js';
|
|
25
35
|
export type { Goals } from './goals.js';
|
|
26
36
|
export { buildFromPaystack, buildFromFlutterwave, buildFromMonnify, buildFromStripe, type Payments, type PaymentStatus, type PaymentConfirmParams, type PaymentConfirmation, type PaymentConfirmationBody, type PaymentHelperOptions, } from './payments.js';
|
|
27
|
-
export type { GoalEvent, GoalAttribution, GoalPayment, GoalBatchItem, GoalBatchResult, Link, LinkWarning, LinkChangeRequest, LinkUpdateResult, Click, Conversion, ListPage, ServerSdkConfig, ConfigGoal, WebhookEvent, QrCode, } from './types.js';
|
|
37
|
+
export type { GoalEvent, GoalAttribution, GoalPayment, GoalBatchItem, GoalBatchResult, Link, LinkWarning, LinkChangeRequest, LinkUpdateResult, Click, Conversion, ListPage, ServerSdkConfig, ConfigGoal, WebhookEvent, WebhookEventAccessors, WebhookEventData, WebhookEventOf, TypedWebhookEvent, QrCode, } from './types.js';
|
|
28
38
|
export { ClikgateError, ConfigurationError, AuthenticationError, PermissionError, InvalidRequestError, PrivateModeFieldRejectedError, NotFoundError, ConflictError, LinkLockedError, IdempotencyError, RateLimitError, ServerError, NetworkError, TimeoutError, SignatureVerificationError, ClikgateServerOnlyError, type KnownErrorCode, } from './errors.js';
|
|
29
39
|
export { VERSION } from './version.js';
|
|
30
40
|
/** Types of the generated `clikgate.api.*` layer (request bodies and responses, as in openapi.json). */
|
package/dist/esm/index.js
CHANGED
|
@@ -12,10 +12,16 @@
|
|
|
12
12
|
export { Clikgate } from './client.js';
|
|
13
13
|
export { ClickIds, clickIds, isValid as isValidClickId, CLICK_ID_PATTERN, CLICK_ID_HEADER, KEPT_COOKIE, KEPT_BY, BROWSER_ENGINES, PLATFORMS, } from './click-ids.js';
|
|
14
14
|
export { webhooks } from './webhooks.js';
|
|
15
|
+
export { parseInstallationHeader, installationFromRequest, INSTALLATION_HEADER, INSTALLATION_HEADER_MAX_LENGTH, INSTALLATION_PATTERN, } from './installation.js';
|
|
16
|
+
export { canonicalCustomerId, customerIdWarning, CUSTOMER_ID_MAX_LENGTH } from './customer-id.js';
|
|
17
|
+
export { KNOWN_CUSTOMERS_BATCH } from './known-customers.js';
|
|
15
18
|
export { createIdentityToken, IDENTITY_SECRET_ENV, IDENTITY_SECRETS_ENV } from './identity.js';
|
|
16
19
|
export { formatValue } from './money.js';
|
|
17
20
|
export { hashForAds } from './ads-hashing.js';
|
|
18
21
|
export { GoalKind, GoalStatus, Provider } from './enums.js';
|
|
22
|
+
export { REFERRER_IMPORT_BATCH } from './referrals.js';
|
|
23
|
+
export { EventType } from './event-types.js';
|
|
24
|
+
export { currencyExponent, minorToAmount } from './currency.js';
|
|
19
25
|
export { buildFromPaystack, buildFromFlutterwave, buildFromMonnify, buildFromStripe, } from './payments.js';
|
|
20
26
|
export { ClikgateError, ConfigurationError, AuthenticationError, PermissionError, InvalidRequestError, PrivateModeFieldRejectedError, NotFoundError, ConflictError, LinkLockedError, IdempotencyError, RateLimitError, ServerError, NetworkError, TimeoutError, SignatureVerificationError, ClikgateServerOnlyError, } from './errors.js';
|
|
21
27
|
export { VERSION } from './version.js';
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `Clikgate-Installation` header (SPEC section 24): the mobile SDKs give the app a value
|
|
3
|
+
* `<app_id>:<installation_id>` to send to its own backend at sign-in and on signed-in requests. It is
|
|
4
|
+
* not a secret. Your server passes it to `identifyUser({ installation })`, so it never needs to know
|
|
5
|
+
* which Clikgate app ID belongs to which platform.
|
|
6
|
+
*
|
|
7
|
+
* The header only names the app installation. The customer ID always comes from your own signed-in
|
|
8
|
+
* user, never from the request.
|
|
9
|
+
*
|
|
10
|
+
* @packageDocumentation
|
|
11
|
+
*/
|
|
12
|
+
/** The header name the app sends to your backend. */
|
|
13
|
+
export declare const INSTALLATION_HEADER = "Clikgate-Installation";
|
|
14
|
+
/** Longer header values are refused before they are looked at. */
|
|
15
|
+
export declare const INSTALLATION_HEADER_MAX_LENGTH = 128;
|
|
16
|
+
/** `app_` + a 26-character ID, one colon, a lowercase UUID. */
|
|
17
|
+
export declare const INSTALLATION_PATTERN: RegExp;
|
|
18
|
+
/** An app installation read from the `Clikgate-Installation` header. */
|
|
19
|
+
export interface Installation {
|
|
20
|
+
/** The Clikgate app ID (`app_…`). */
|
|
21
|
+
appId: string;
|
|
22
|
+
/** The SDK's installation ID (a lowercase UUID). */
|
|
23
|
+
installationId: string;
|
|
24
|
+
}
|
|
25
|
+
/** A request with headers: Node's `IncomingMessage`, Express, Fastify, a Fetch `Request` or `{ headers }`. */
|
|
26
|
+
export interface HeadersLike {
|
|
27
|
+
headers?: Headers | Record<string, string | string[] | undefined> | {
|
|
28
|
+
get(name: string): string | null;
|
|
29
|
+
} | null;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* Parse a `Clikgate-Installation` header value. Returns `null` for anything that isn't exactly
|
|
33
|
+
* `<app_id>:<installation_id>` (after trimming, at most 128 characters, lowercase UUID). Never throws.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* const installation = parseInstallationHeader(req.get('Clikgate-Installation'));
|
|
37
|
+
* // { appId: 'app_01J…', installationId: '3f2b…' } or null
|
|
38
|
+
*/
|
|
39
|
+
export declare function parseInstallationHeader(value: unknown): Installation | null;
|
|
40
|
+
/**
|
|
41
|
+
* The installation from a request's `Clikgate-Installation` header, or `null` when it is missing or
|
|
42
|
+
* invalid. Never throws.
|
|
43
|
+
*
|
|
44
|
+
* @example
|
|
45
|
+
* const installation = installationFromRequest(req);
|
|
46
|
+
*/
|
|
47
|
+
export declare function installationFromRequest(request: HeadersLike | null | undefined): Installation | null;
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `Clikgate-Installation` header (SPEC section 24): the mobile SDKs give the app a value
|
|
3
|
+
* `<app_id>:<installation_id>` to send to its own backend at sign-in and on signed-in requests. It is
|
|
4
|
+
* not a secret. Your server passes it to `identifyUser({ installation })`, so it never needs to know
|
|
5
|
+
* which Clikgate app ID belongs to which platform.
|
|
6
|
+
*
|
|
7
|
+
* The header only names the app installation. The customer ID always comes from your own signed-in
|
|
8
|
+
* user, never from the request.
|
|
9
|
+
*
|
|
10
|
+
* @packageDocumentation
|
|
11
|
+
*/
|
|
12
|
+
/** The header name the app sends to your backend. */
|
|
13
|
+
export const INSTALLATION_HEADER = 'Clikgate-Installation';
|
|
14
|
+
/** Longer header values are refused before they are looked at. */
|
|
15
|
+
export const INSTALLATION_HEADER_MAX_LENGTH = 128;
|
|
16
|
+
/** `app_` + a 26-character ID, one colon, a lowercase UUID. */
|
|
17
|
+
export const INSTALLATION_PATTERN = /^(app_[0-9A-Z]{26}):([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
|
|
18
|
+
/**
|
|
19
|
+
* Parse a `Clikgate-Installation` header value. Returns `null` for anything that isn't exactly
|
|
20
|
+
* `<app_id>:<installation_id>` (after trimming, at most 128 characters, lowercase UUID). Never throws.
|
|
21
|
+
*
|
|
22
|
+
* @example
|
|
23
|
+
* const installation = parseInstallationHeader(req.get('Clikgate-Installation'));
|
|
24
|
+
* // { appId: 'app_01J…', installationId: '3f2b…' } or null
|
|
25
|
+
*/
|
|
26
|
+
export function parseInstallationHeader(value) {
|
|
27
|
+
if (typeof value !== 'string' || value.length > INSTALLATION_HEADER_MAX_LENGTH)
|
|
28
|
+
return null;
|
|
29
|
+
const match = INSTALLATION_PATTERN.exec(value.replace(/^[ \t\r\n\f\v]+|[ \t\r\n\f\v]+$/g, ''));
|
|
30
|
+
return match ? { appId: match[1], installationId: match[2] } : null;
|
|
31
|
+
}
|
|
32
|
+
function headerValue(headers) {
|
|
33
|
+
if (!headers)
|
|
34
|
+
return undefined;
|
|
35
|
+
if (typeof headers.get === 'function') {
|
|
36
|
+
return headers.get(INSTALLATION_HEADER);
|
|
37
|
+
}
|
|
38
|
+
const record = headers;
|
|
39
|
+
const wanted = INSTALLATION_HEADER.toLowerCase();
|
|
40
|
+
for (const key of Object.keys(record)) {
|
|
41
|
+
if (key.toLowerCase() === wanted) {
|
|
42
|
+
const raw = record[key];
|
|
43
|
+
// Several headers with this name: refused, never guessed
|
|
44
|
+
return Array.isArray(raw) ? (raw.length === 1 ? raw[0] : undefined) : raw;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
return undefined;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* The installation from a request's `Clikgate-Installation` header, or `null` when it is missing or
|
|
51
|
+
* invalid. Never throws.
|
|
52
|
+
*
|
|
53
|
+
* @example
|
|
54
|
+
* const installation = installationFromRequest(req);
|
|
55
|
+
*/
|
|
56
|
+
export function installationFromRequest(request) {
|
|
57
|
+
try {
|
|
58
|
+
return parseInstallationHeader(headerValue(request?.headers));
|
|
59
|
+
}
|
|
60
|
+
catch {
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* @internal An installation from either the raw `Clikgate-Installation` header or a parsed {@link Installation}
|
|
66
|
+
* (`req.clikgate.installation`, `getInstallation(...)`). Both go through the same strict check; anything else is `null`.
|
|
67
|
+
*/
|
|
68
|
+
export function toInstallation(value) {
|
|
69
|
+
if (typeof value === 'string')
|
|
70
|
+
return parseInstallationHeader(value);
|
|
71
|
+
if (value && typeof value === 'object') {
|
|
72
|
+
const { appId, installationId } = value;
|
|
73
|
+
if (typeof appId === 'string' && typeof installationId === 'string')
|
|
74
|
+
return parseInstallationHeader(`${appId}:${installationId}`);
|
|
75
|
+
}
|
|
76
|
+
return null;
|
|
77
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { RequestOptions } from './http.js';
|
|
2
|
+
/**
|
|
3
|
+
* Known customers: people who were already your customers before you added Clikgate. Clikgate uses
|
|
4
|
+
* them so an existing customer is never counted as a referral or a new customer. It stores a keyed fingerprint of
|
|
5
|
+
* each ID, not the ID itself. Not available in private mode.
|
|
6
|
+
*/
|
|
7
|
+
/** One existing customer: your customer ID and, optionally, when they became a customer. */
|
|
8
|
+
export interface KnownCustomer {
|
|
9
|
+
customerId: string;
|
|
10
|
+
/** When they became a customer: `'YYYY-MM-DD'`, a `Date` or Unix seconds. Only the UTC day is sent. */
|
|
11
|
+
customerSince?: string | Date | number | null;
|
|
12
|
+
}
|
|
13
|
+
/** Why rows were refused. Counts only: the API never returns the refused IDs. */
|
|
14
|
+
export type KnownCustomerRefusal = 'looks_like_email' | 'looks_like_phone' | 'looks_like_national_id' | 'empty' | 'too_long' | 'bad_date' | 'date_out_of_range';
|
|
15
|
+
/** The answer of `knownCustomers.import()`, summed over every batch. */
|
|
16
|
+
export interface KnownCustomersImportResult {
|
|
17
|
+
accepted: number;
|
|
18
|
+
refused: number;
|
|
19
|
+
refused_by_reason: Partial<Record<KnownCustomerRefusal | string, number>>;
|
|
20
|
+
}
|
|
21
|
+
/** The API's batch size; `import()` splits larger lists. */
|
|
22
|
+
export declare const KNOWN_CUSTOMERS_BATCH = 10000;
|
|
23
|
+
/** `clikgate.knownCustomers`: import and remove existing customers (scope `people:write`). */
|
|
24
|
+
export declare class KnownCustomers {
|
|
25
|
+
private readonly core;
|
|
26
|
+
/**
|
|
27
|
+
* Import existing customers (`POST /v1/known-customers/import`), in batches of 10,000. Idempotent per customer ID.
|
|
28
|
+
* Use your own customer IDs, never emails or phone numbers. The result sums every batch; refused rows are counted
|
|
29
|
+
* by reason, never returned.
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* const result = await clikgate.knownCustomers.import([{ customerId: 'u_10482', customerSince: '2024-03-02' }]);
|
|
33
|
+
* console.log(result.accepted, result.refused_by_reason);
|
|
34
|
+
*/
|
|
35
|
+
import(customers: readonly KnownCustomer[], requestOptions?: RequestOptions): Promise<KnownCustomersImportResult>;
|
|
36
|
+
/**
|
|
37
|
+
* Remove one imported customer (`POST /v1/known-customers/remove`; the ID travels in the body, never in a URL).
|
|
38
|
+
*
|
|
39
|
+
* @example
|
|
40
|
+
* const { removed } = await clikgate.knownCustomers.remove('u_10482');
|
|
41
|
+
*/
|
|
42
|
+
remove(customerId: string, requestOptions?: RequestOptions): Promise<{
|
|
43
|
+
removed: boolean;
|
|
44
|
+
}>;
|
|
45
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import { ConflictError, localError } from './errors.js';
|
|
2
|
+
/** The API's batch size; `import()` splits larger lists. */
|
|
3
|
+
export const KNOWN_CUSTOMERS_BATCH = 10_000;
|
|
4
|
+
const DAY = /^\d{4}-\d{2}-\d{2}$/;
|
|
5
|
+
/** @internal The UTC day `YYYY-MM-DD` of a customerSince value. */
|
|
6
|
+
export function sinceDay(value) {
|
|
7
|
+
if (typeof value === 'string') {
|
|
8
|
+
if (!DAY.test(value))
|
|
9
|
+
throw localError('invalid_argument', "customerSince must be 'YYYY-MM-DD', a Date or Unix seconds.", 'customer_since');
|
|
10
|
+
return value;
|
|
11
|
+
}
|
|
12
|
+
const ms = typeof value === 'number' ? value * 1000 : value instanceof Date ? value.getTime() : Number.NaN;
|
|
13
|
+
if (!Number.isFinite(ms) || (typeof value === 'number' && !Number.isSafeInteger(value))) {
|
|
14
|
+
throw localError('invalid_argument', "customerSince must be 'YYYY-MM-DD', a Date or Unix seconds.", 'customer_since');
|
|
15
|
+
}
|
|
16
|
+
return new Date(ms).toISOString().slice(0, 10);
|
|
17
|
+
}
|
|
18
|
+
function privateModeConflict() {
|
|
19
|
+
return new ConflictError({
|
|
20
|
+
message: "Private mode is on: known customers can't be imported or removed.",
|
|
21
|
+
code: 'private_mode_conflict',
|
|
22
|
+
httpStatus: null,
|
|
23
|
+
});
|
|
24
|
+
}
|
|
25
|
+
/** `clikgate.knownCustomers`: import and remove existing customers (scope `people:write`). */
|
|
26
|
+
export class KnownCustomers {
|
|
27
|
+
core;
|
|
28
|
+
/** @internal */
|
|
29
|
+
constructor(core) {
|
|
30
|
+
this.core = core;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Import existing customers (`POST /v1/known-customers/import`), in batches of 10,000. Idempotent per customer ID.
|
|
34
|
+
* Use your own customer IDs, never emails or phone numbers. The result sums every batch; refused rows are counted
|
|
35
|
+
* by reason, never returned.
|
|
36
|
+
*
|
|
37
|
+
* @example
|
|
38
|
+
* const result = await clikgate.knownCustomers.import([{ customerId: 'u_10482', customerSince: '2024-03-02' }]);
|
|
39
|
+
* console.log(result.accepted, result.refused_by_reason);
|
|
40
|
+
*/
|
|
41
|
+
async import(customers, requestOptions = {}) {
|
|
42
|
+
if (!Array.isArray(customers))
|
|
43
|
+
throw localError('invalid_argument', 'customers must be an array.', 'customers');
|
|
44
|
+
const rows = customers.map((c, i) => {
|
|
45
|
+
if (!c || typeof c.customerId !== 'string')
|
|
46
|
+
throw localError('invalid_argument', `customers[${i}].customerId must be a string.`, 'customer_id');
|
|
47
|
+
const row = { customer_id: c.customerId };
|
|
48
|
+
if (c.customerSince != null)
|
|
49
|
+
row.customer_since = sinceDay(c.customerSince);
|
|
50
|
+
return row;
|
|
51
|
+
});
|
|
52
|
+
const total = { accepted: 0, refused: 0, refused_by_reason: {} };
|
|
53
|
+
if (rows.length === 0)
|
|
54
|
+
return total;
|
|
55
|
+
if ((await this.core.guardState()).guard)
|
|
56
|
+
throw privateModeConflict();
|
|
57
|
+
const several = rows.length > KNOWN_CUSTOMERS_BATCH;
|
|
58
|
+
for (let i = 0; i < rows.length; i += KNOWN_CUSTOMERS_BATCH) {
|
|
59
|
+
// One idempotency key per batch: a key you pass gets the batch number appended
|
|
60
|
+
const key = requestOptions.idempotencyKey;
|
|
61
|
+
const options = several && key ? { ...requestOptions, idempotencyKey: `${key}-${i / KNOWN_CUSTOMERS_BATCH}` } : requestOptions;
|
|
62
|
+
const { data } = await this.core.requester.request({
|
|
63
|
+
method: 'POST',
|
|
64
|
+
path: '/v1/known-customers/import',
|
|
65
|
+
body: { customers: rows.slice(i, i + KNOWN_CUSTOMERS_BATCH) },
|
|
66
|
+
...options,
|
|
67
|
+
});
|
|
68
|
+
total.accepted += data.accepted ?? 0;
|
|
69
|
+
total.refused += data.refused ?? 0;
|
|
70
|
+
for (const [reason, n] of Object.entries(data.refused_by_reason ?? {})) {
|
|
71
|
+
total.refused_by_reason[reason] = (total.refused_by_reason[reason] ?? 0) + (n ?? 0);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
return total;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Remove one imported customer (`POST /v1/known-customers/remove`; the ID travels in the body, never in a URL).
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* const { removed } = await clikgate.knownCustomers.remove('u_10482');
|
|
81
|
+
*/
|
|
82
|
+
async remove(customerId, requestOptions = {}) {
|
|
83
|
+
if (typeof customerId !== 'string' || customerId === '')
|
|
84
|
+
throw localError('invalid_customer_id', 'customerId must be a non-empty string.', 'customer_id');
|
|
85
|
+
if ((await this.core.guardState()).guard)
|
|
86
|
+
throw privateModeConflict();
|
|
87
|
+
const { data } = await this.core.requester.request({ method: 'POST', path: '/v1/known-customers/remove', body: { customer_id: customerId }, ...requestOptions });
|
|
88
|
+
return data;
|
|
89
|
+
}
|
|
90
|
+
}
|