@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";
@@ -1,2 +1,2 @@
1
1
  /** The SDK version (kept equal to package.json by `npm run check:version`). */
2
- export const VERSION = '2.0.0';
2
+ export const 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,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
- * if (event.type === 'goal.completed') { … } // dedupe on event.id: delivery is at-least-once
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.0.0",
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 <sdk@clikgate.com> (https://clikgate.com)",
26
+ "author": "Clikgate <dev@clikgate.com> (https://clikgate.com)",
27
27
  "type": "module",
28
28
  "sideEffects": false,
29
29
  "engines": {