@clikgate/node 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +126 -6
  3. package/SECURITY.md +2 -1
  4. package/dist/cjs/client.d.ts +54 -10
  5. package/dist/cjs/client.js +75 -16
  6. package/dist/cjs/currency.d.ts +7 -0
  7. package/dist/cjs/currency.js +75 -0
  8. package/dist/cjs/customer-id.d.ts +26 -0
  9. package/dist/cjs/customer-id.js +52 -0
  10. package/dist/cjs/enums.js +1 -1
  11. package/dist/cjs/errors.d.ts +1 -1
  12. package/dist/cjs/event-types.d.ts +108 -0
  13. package/dist/cjs/event-types.js +109 -0
  14. package/dist/cjs/express.d.ts +11 -2
  15. package/dist/cjs/express.js +3 -2
  16. package/dist/cjs/fastify.d.ts +4 -1
  17. package/dist/cjs/fastify.js +3 -2
  18. package/dist/cjs/generated/index.d.ts +2015 -83
  19. package/dist/cjs/generated/index.js +83 -3
  20. package/dist/cjs/identity.d.ts +12 -2
  21. package/dist/cjs/identity.js +37 -3
  22. package/dist/cjs/index.d.ts +11 -1
  23. package/dist/cjs/index.js +21 -1
  24. package/dist/cjs/installation.d.ts +47 -0
  25. package/dist/cjs/installation.js +83 -0
  26. package/dist/cjs/known-customers.d.ts +45 -0
  27. package/dist/cjs/known-customers.js +95 -0
  28. package/dist/cjs/lookups.d.ts +128 -0
  29. package/dist/cjs/lookups.js +149 -0
  30. package/dist/cjs/models.d.ts +342 -0
  31. package/dist/cjs/models.js +2 -0
  32. package/dist/cjs/next.d.ts +22 -0
  33. package/dist/cjs/next.js +20 -0
  34. package/dist/cjs/pager.d.ts +5 -0
  35. package/dist/cjs/pager.js +40 -0
  36. package/dist/cjs/referrals.d.ts +169 -0
  37. package/dist/cjs/referrals.js +208 -0
  38. package/dist/cjs/resources.d.ts +34 -5
  39. package/dist/cjs/resources.js +43 -42
  40. package/dist/cjs/types.d.ts +57 -10
  41. package/dist/cjs/version.d.ts +1 -1
  42. package/dist/cjs/version.js +1 -1
  43. package/dist/cjs/webhooks.d.ts +3 -2
  44. package/dist/cjs/webhooks.js +43 -2
  45. package/dist/esm/client.d.ts +54 -10
  46. package/dist/esm/client.js +75 -16
  47. package/dist/esm/currency.d.ts +7 -0
  48. package/dist/esm/currency.js +67 -0
  49. package/dist/esm/customer-id.d.ts +26 -0
  50. package/dist/esm/customer-id.js +47 -0
  51. package/dist/esm/enums.js +1 -1
  52. package/dist/esm/errors.d.ts +1 -1
  53. package/dist/esm/event-types.d.ts +108 -0
  54. package/dist/esm/event-types.js +106 -0
  55. package/dist/esm/express.d.ts +11 -2
  56. package/dist/esm/express.js +3 -2
  57. package/dist/esm/fastify.d.ts +4 -1
  58. package/dist/esm/fastify.js +3 -2
  59. package/dist/esm/generated/index.d.ts +2015 -83
  60. package/dist/esm/generated/index.js +80 -1
  61. package/dist/esm/identity.d.ts +12 -2
  62. package/dist/esm/identity.js +36 -3
  63. package/dist/esm/index.d.ts +11 -1
  64. package/dist/esm/index.js +6 -0
  65. package/dist/esm/installation.d.ts +47 -0
  66. package/dist/esm/installation.js +77 -0
  67. package/dist/esm/known-customers.d.ts +45 -0
  68. package/dist/esm/known-customers.js +90 -0
  69. package/dist/esm/lookups.d.ts +128 -0
  70. package/dist/esm/lookups.js +142 -0
  71. package/dist/esm/models.d.ts +342 -0
  72. package/dist/esm/models.js +1 -0
  73. package/dist/esm/next.d.ts +22 -0
  74. package/dist/esm/next.js +19 -0
  75. package/dist/esm/pager.d.ts +5 -0
  76. package/dist/esm/pager.js +36 -0
  77. package/dist/esm/referrals.d.ts +169 -0
  78. package/dist/esm/referrals.js +204 -0
  79. package/dist/esm/resources.d.ts +34 -5
  80. package/dist/esm/resources.js +43 -42
  81. package/dist/esm/types.d.ts +57 -10
  82. package/dist/esm/version.d.ts +1 -1
  83. package/dist/esm/version.js +1 -1
  84. package/dist/esm/webhooks.d.ts +3 -2
  85. package/dist/esm/webhooks.js +42 -2
  86. package/package.json +2 -2
@@ -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`). Only the most used fields are typed; the rest are kept. */
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
- /** A webhook event. */
198
- export interface WebhookEvent<T = Record<string, unknown>> {
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`, `subscription.updated`. */
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
- object: T;
209
- previous_attributes?: Record<string, unknown> | null;
210
- [key: string]: unknown;
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 {};
@@ -1,2 +1,2 @@
1
1
  /** The SDK version (kept equal to package.json by `npm run check:version`). */
2
- export declare const VERSION = "2.0.0";
2
+ export declare const VERSION = "2.1.0";
@@ -2,4 +2,4 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  /** The SDK version (kept equal to package.json by `npm run check:version`). */
5
- exports.VERSION = '2.0.0';
5
+ exports.VERSION = '2.1.0';
@@ -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
- * if (event.type === 'goal.completed') { … } // dedupe on event.id: delivery is at-least-once
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
  */
@@ -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
- * if (event.type === 'goal.completed') { … } // dedupe on event.id: delivery is at-least-once
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
  */
@@ -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`, `appId` + `installationId`, `customerId`. */
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
- /** An app installation: the app's ID and the SDK's installation ID, together. */
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 customer ID. With a click or installation, links it to this customer. */
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 (`appId` +
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 reads
139
- * `getInstallationId()` and sends it in its sign-in request; your server calls this with
140
- * `{ appId, installationId, customerId, label? }` after sign-in and at every signed-in app open. When the app sends
141
- * no installation ID (tracking is off), skip the call. Clikgate accepts installations active in the last 7 days.
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
- * if (body.installationId) await clikgate.identifyUser({ appId: 'app_…', installationId: body.installationId, customerId: user.id });
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
  /**
@@ -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 → API keys.`, code: 'invalid_api_key', param: 'apiKey' });
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 (`appId` +
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 reads
190
- * `getInstallationId()` and sends it in its sign-in request; your server calls this with
191
- * `{ appId, installationId, customerId, label? }` after sign-in and at every signed-in app open. When the app sends
192
- * no installation ID (tracking is off), skip the call. Clikgate accepts installations active in the last 7 days.
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
- * if (body.installationId) await clikgate.identifyUser({ appId: 'app_…', installationId: body.installationId, customerId: user.id });
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
- if ((p.appId == null) !== (p.installationId == null)) {
201
- throw localError('invalid_request', 'Send appId and installationId together.', p.appId == null ? 'app_id' : 'installation_id');
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 (p.clickId == null && p.installationId == null && p.customerId == null) {
204
- throw localError('invalid_request', 'Send clickId, appId + installationId, or customerId.', 'click_id');
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 (p.appId != null)
210
- body.app_id = p.appId;
211
- if (p.installationId != null)
212
- body.installation_id = p.installationId;
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 d39834b71974ddd58b7ba177f00c450738a641f18add17189a2f707bf724c796.
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',