@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/esm/types.d.ts
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
import type { GoalKind, GoalStatus, Provider } from './enums.js';
|
|
2
|
+
import type { LinkInfoResponse } from './generated/index.js';
|
|
3
|
+
import type { EventTypeValue } from './event-types.js';
|
|
4
|
+
import type { ConversionObject, DeviceChange, Install, PaymentReport, Referral, Referrer, WebhookGoalEvent } from './models.js';
|
|
2
5
|
/** Wire objects returned by the hand-written resources. Keys are as the API sends them (snake_case). */
|
|
3
6
|
/** Where a goal event was attributed. */
|
|
4
7
|
export interface GoalAttribution {
|
|
@@ -86,8 +89,8 @@ export interface LinkWarning {
|
|
|
86
89
|
message: string;
|
|
87
90
|
param?: string | null;
|
|
88
91
|
}
|
|
89
|
-
/** A link (`/v1/links`)
|
|
90
|
-
export interface Link {
|
|
92
|
+
/** A link (`/v1/links`): every field of the API's link, plus any newer field (kept as is). */
|
|
93
|
+
export interface Link extends Omit<LinkInfoResponse, 'object' | 'warnings' | 'metadata' | 'domain_badge' | 'locked'> {
|
|
91
94
|
object: 'link';
|
|
92
95
|
id: string;
|
|
93
96
|
short_url: string;
|
|
@@ -194,25 +197,69 @@ export interface ServerSdkConfig {
|
|
|
194
197
|
minimum_sdk_versions: Partial<Record<'node' | 'python' | 'php' | 'java' | 'dotnet', string>>;
|
|
195
198
|
[key: string]: unknown;
|
|
196
199
|
}
|
|
197
|
-
/**
|
|
198
|
-
export interface
|
|
200
|
+
/** Typed accessors of a verified webhook event (SPEC 29). Each gives `null` for an event of another family. */
|
|
201
|
+
export interface WebhookEventAccessors {
|
|
202
|
+
/** `referral.*`: the referral, with reward amounts. */
|
|
203
|
+
asReferral(): Referral | null;
|
|
204
|
+
/** `referrer.*`: the referrer. */
|
|
205
|
+
asReferrer(): Referrer | null;
|
|
206
|
+
/** `goal.completed` / `goal.reversed`: the goal event as webhooks show it. */
|
|
207
|
+
asGoalEvent(): WebhookGoalEvent | null;
|
|
208
|
+
/** `install.*`: the install. */
|
|
209
|
+
asInstall(): Install | null;
|
|
210
|
+
/** `payment.*`: the payment report. */
|
|
211
|
+
asPayment(): PaymentReport | null;
|
|
212
|
+
/** `conversion.*`: the conversion. */
|
|
213
|
+
asConversion(): ConversionObject | null;
|
|
214
|
+
/** `person.device_changed`: the device change. */
|
|
215
|
+
asDeviceChange(): DeviceChange | null;
|
|
216
|
+
/** The same event, typed as the union discriminated by `type`. */
|
|
217
|
+
typed(): TypedWebhookEvent;
|
|
218
|
+
}
|
|
219
|
+
/** A webhook event's `data`. */
|
|
220
|
+
export interface WebhookEventData<T> {
|
|
221
|
+
object: T;
|
|
222
|
+
previous_attributes?: Record<string, unknown> | null;
|
|
223
|
+
[key: string]: unknown;
|
|
224
|
+
}
|
|
225
|
+
/** A webhook event. `data` is the raw payload; the `as…()` accessors give typed objects. */
|
|
226
|
+
export interface WebhookEvent<T = Record<string, unknown>> extends WebhookEventAccessors {
|
|
199
227
|
id: string;
|
|
200
228
|
object: 'event';
|
|
201
|
-
/** e.g. `goal.completed`, `link.destination_changed
|
|
229
|
+
/** e.g. `referral.qualified`, `goal.completed`, `link.destination_changed`. Compare with `EventType`. */
|
|
202
230
|
type: string;
|
|
203
231
|
api_version: string;
|
|
204
232
|
created_at: string;
|
|
205
233
|
organization_id: string;
|
|
206
234
|
livemode: boolean;
|
|
207
|
-
data:
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
235
|
+
data: WebhookEventData<T>;
|
|
236
|
+
[key: string]: unknown;
|
|
237
|
+
}
|
|
238
|
+
/** One member of {@link TypedWebhookEvent}. */
|
|
239
|
+
export interface WebhookEventOf<Type extends string, T> extends WebhookEventAccessors {
|
|
240
|
+
id: string;
|
|
241
|
+
object: 'event';
|
|
242
|
+
type: Type;
|
|
243
|
+
api_version: string;
|
|
244
|
+
created_at: string;
|
|
245
|
+
organization_id: string;
|
|
246
|
+
livemode: boolean;
|
|
247
|
+
data: WebhookEventData<T>;
|
|
212
248
|
[key: string]: unknown;
|
|
213
249
|
}
|
|
250
|
+
type Family<P extends string> = Extract<EventTypeValue, `${P}.${string}`>;
|
|
251
|
+
type Typed = Family<'referral'> | Family<'referrer'> | Family<'goal'> | Family<'install'> | Family<'payment'> | Family<'conversion'> | 'person.device_changed';
|
|
252
|
+
/**
|
|
253
|
+
* Every webhook event this SDK release knows, discriminated by `type` (`event.typed()`):
|
|
254
|
+
*
|
|
255
|
+
* @example
|
|
256
|
+
* const e = event.typed();
|
|
257
|
+
* if (e.type === EventType.ReferralQualified) console.log(e.data.object.referrer.customer_user_id);
|
|
258
|
+
*/
|
|
259
|
+
export type TypedWebhookEvent = WebhookEventOf<Family<'referral'>, Referral> | WebhookEventOf<Family<'referrer'>, Referrer> | WebhookEventOf<Family<'goal'>, WebhookGoalEvent> | WebhookEventOf<Family<'install'>, Install> | WebhookEventOf<Family<'payment'>, PaymentReport> | WebhookEventOf<Family<'conversion'>, ConversionObject> | WebhookEventOf<'person.device_changed', DeviceChange> | WebhookEventOf<Exclude<EventTypeValue, Typed>, Record<string, unknown>>;
|
|
214
260
|
/** QR code bytes. */
|
|
215
261
|
export interface QrCode {
|
|
216
262
|
contentType: string;
|
|
217
263
|
data: Uint8Array;
|
|
218
264
|
}
|
|
265
|
+
export {};
|
package/dist/esm/version.d.ts
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The SDK version (kept equal to package.json by `npm run check:version`). */
|
|
2
|
-
export declare const VERSION = "2.
|
|
2
|
+
export declare const VERSION = "2.1.0";
|
package/dist/esm/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The SDK version (kept equal to package.json by `npm run check:version`). */
|
|
2
|
-
export const VERSION = '2.
|
|
2
|
+
export const VERSION = '2.1.0';
|
package/dist/esm/webhooks.d.ts
CHANGED
|
@@ -18,10 +18,11 @@ export declare const webhooks: {
|
|
|
18
18
|
*
|
|
19
19
|
* @example
|
|
20
20
|
* import express from 'express';
|
|
21
|
-
* import { webhooks } from '@clikgate/node';
|
|
21
|
+
* import { webhooks, EventType } from '@clikgate/node';
|
|
22
22
|
* app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
|
|
23
23
|
* const event = webhooks.verify(req.body, req.get('Clikgate-Signature'), process.env.CLIKGATE_WEBHOOK_SECRET!);
|
|
24
|
-
*
|
|
24
|
+
* const referral = event.asReferral(); // null for other event types
|
|
25
|
+
* if (referral && event.type === EventType.ReferralQualified) { … } // dedupe on event.id: delivery is at-least-once
|
|
25
26
|
* res.sendStatus(200);
|
|
26
27
|
* });
|
|
27
28
|
*/
|
package/dist/esm/webhooks.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { createHmac, timingSafeEqual } from 'node:crypto';
|
|
2
2
|
import { SignatureVerificationError, localError } from './errors.js';
|
|
3
|
+
import { toReferral, toReferrer } from './currency.js';
|
|
3
4
|
const fail = (code, message) => new SignatureVerificationError({ message, code });
|
|
4
5
|
function toBytes(raw) {
|
|
5
6
|
if (typeof raw === 'string')
|
|
@@ -66,6 +67,44 @@ function verifyWith(rawBody, signatureHeader, secrets, options) {
|
|
|
66
67
|
}
|
|
67
68
|
if (!event || typeof event !== 'object' || Array.isArray(event))
|
|
68
69
|
throw fail('invalid_payload', 'The body is not an event object.');
|
|
70
|
+
return withAccessors(event);
|
|
71
|
+
}
|
|
72
|
+
function objectOf(event, family) {
|
|
73
|
+
const type = event.type;
|
|
74
|
+
if (typeof type !== 'string' || !type.startsWith(`${family}.`))
|
|
75
|
+
return null;
|
|
76
|
+
const data = event.data;
|
|
77
|
+
if (!data || typeof data !== 'object' || Array.isArray(data))
|
|
78
|
+
return null;
|
|
79
|
+
const object = data.object;
|
|
80
|
+
return object && typeof object === 'object' && !Array.isArray(object) ? object : null;
|
|
81
|
+
}
|
|
82
|
+
/** @internal Add the typed accessors as non-enumerable methods (JSON.stringify(event) is unchanged). */
|
|
83
|
+
export function withAccessors(event) {
|
|
84
|
+
const accessors = {
|
|
85
|
+
asReferral: () => {
|
|
86
|
+
const o = objectOf(event, 'referral');
|
|
87
|
+
return o ? toReferral(o) : null;
|
|
88
|
+
},
|
|
89
|
+
asReferrer: () => {
|
|
90
|
+
const o = objectOf(event, 'referrer');
|
|
91
|
+
return o ? toReferrer(o) : null;
|
|
92
|
+
},
|
|
93
|
+
asGoalEvent: () => objectOf(event, 'goal'),
|
|
94
|
+
asInstall: () => objectOf(event, 'install'),
|
|
95
|
+
asPayment: () => objectOf(event, 'payment'),
|
|
96
|
+
asConversion: () => objectOf(event, 'conversion'),
|
|
97
|
+
asDeviceChange: () => {
|
|
98
|
+
if (event.type !== 'person.device_changed')
|
|
99
|
+
return null;
|
|
100
|
+
const data = event.data;
|
|
101
|
+
const object = data && typeof data === 'object' ? data.object : null;
|
|
102
|
+
return object && typeof object === 'object' && !Array.isArray(object) ? object : null;
|
|
103
|
+
},
|
|
104
|
+
typed: () => event,
|
|
105
|
+
};
|
|
106
|
+
for (const [name, fn] of Object.entries(accessors))
|
|
107
|
+
Object.defineProperty(event, name, { value: fn, enumerable: false, writable: true, configurable: true });
|
|
69
108
|
return event;
|
|
70
109
|
}
|
|
71
110
|
/**
|
|
@@ -78,10 +117,11 @@ export const webhooks = {
|
|
|
78
117
|
*
|
|
79
118
|
* @example
|
|
80
119
|
* import express from 'express';
|
|
81
|
-
* import { webhooks } from '@clikgate/node';
|
|
120
|
+
* import { webhooks, EventType } from '@clikgate/node';
|
|
82
121
|
* app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
|
|
83
122
|
* const event = webhooks.verify(req.body, req.get('Clikgate-Signature'), process.env.CLIKGATE_WEBHOOK_SECRET!);
|
|
84
|
-
*
|
|
123
|
+
* const referral = event.asReferral(); // null for other event types
|
|
124
|
+
* if (referral && event.type === EventType.ReferralQualified) { … } // dedupe on event.id: delivery is at-least-once
|
|
85
125
|
* res.sendStatus(200);
|
|
86
126
|
* });
|
|
87
127
|
*/
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clikgate/node",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "The official Clikgate server SDK for Node.js and TypeScript: send goals in three lines, keep the click ID, verify webhooks, with private mode built in.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"clikgate",
|
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
"directory": "server/node"
|
|
24
24
|
},
|
|
25
25
|
"license": "MIT",
|
|
26
|
-
"author": "Clikgate <
|
|
26
|
+
"author": "Clikgate <dev@clikgate.com> (https://clikgate.com)",
|
|
27
27
|
"type": "module",
|
|
28
28
|
"sideEffects": false,
|
|
29
29
|
"engines": {
|