@clikgate/node 0.0.0-stage → 2.0.1

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 (119) hide show
  1. package/CHANGELOG.md +136 -0
  2. package/LICENSE +21 -0
  3. package/README.md +311 -2
  4. package/SECURITY.md +34 -0
  5. package/dist/cjs/ads-hashing.d.ts +37 -0
  6. package/dist/cjs/ads-hashing.js +67 -0
  7. package/dist/cjs/click-ids.d.ts +184 -0
  8. package/dist/cjs/click-ids.js +535 -0
  9. package/dist/cjs/client.d.ts +191 -0
  10. package/dist/cjs/client.js +291 -0
  11. package/dist/cjs/config.d.ts +12 -0
  12. package/dist/cjs/config.js +87 -0
  13. package/dist/cjs/core.d.ts +15 -0
  14. package/dist/cjs/core.js +100 -0
  15. package/dist/cjs/customer-id.d.ts +26 -0
  16. package/dist/cjs/customer-id.js +52 -0
  17. package/dist/cjs/enums.d.ts +48 -0
  18. package/dist/cjs/enums.js +47 -0
  19. package/dist/cjs/errors.d.ts +117 -0
  20. package/dist/cjs/errors.js +257 -0
  21. package/dist/cjs/express.d.ts +49 -0
  22. package/dist/cjs/express.js +44 -0
  23. package/dist/cjs/fastify.d.ts +47 -0
  24. package/dist/cjs/fastify.js +35 -0
  25. package/dist/cjs/generated/index.d.ts +17793 -0
  26. package/dist/cjs/generated/index.js +8896 -0
  27. package/dist/cjs/goals.d.ts +116 -0
  28. package/dist/cjs/goals.js +381 -0
  29. package/dist/cjs/guard.d.ts +17 -0
  30. package/dist/cjs/guard.js +40 -0
  31. package/dist/cjs/http.d.ts +16 -0
  32. package/dist/cjs/http.js +148 -0
  33. package/dist/cjs/identity.d.ts +42 -0
  34. package/dist/cjs/identity.js +133 -0
  35. package/dist/cjs/index.d.ts +34 -0
  36. package/dist/cjs/index.js +70 -0
  37. package/dist/cjs/known-customers.d.ts +45 -0
  38. package/dist/cjs/known-customers.js +95 -0
  39. package/dist/cjs/logger.d.ts +9 -0
  40. package/dist/cjs/logger.js +8 -0
  41. package/dist/cjs/money.d.ts +16 -0
  42. package/dist/cjs/money.js +51 -0
  43. package/dist/cjs/next.d.ts +81 -0
  44. package/dist/cjs/next.js +103 -0
  45. package/dist/cjs/package.json +1 -0
  46. package/dist/cjs/payments.d.ts +174 -0
  47. package/dist/cjs/payments.js +485 -0
  48. package/dist/cjs/resources.d.ts +109 -0
  49. package/dist/cjs/resources.js +189 -0
  50. package/dist/cjs/shutdown.d.ts +2 -0
  51. package/dist/cjs/shutdown.js +51 -0
  52. package/dist/cjs/transport.d.ts +14 -0
  53. package/dist/cjs/transport.js +204 -0
  54. package/dist/cjs/types.d.ts +218 -0
  55. package/dist/cjs/types.js +2 -0
  56. package/dist/cjs/user-agent.d.ts +1 -0
  57. package/dist/cjs/user-agent.js +53 -0
  58. package/dist/cjs/version.d.ts +2 -0
  59. package/dist/cjs/version.js +5 -0
  60. package/dist/cjs/webhooks.d.ts +36 -0
  61. package/dist/cjs/webhooks.js +108 -0
  62. package/dist/esm/ads-hashing.d.ts +37 -0
  63. package/dist/esm/ads-hashing.js +62 -0
  64. package/dist/esm/click-ids.d.ts +184 -0
  65. package/dist/esm/click-ids.js +526 -0
  66. package/dist/esm/client.d.ts +191 -0
  67. package/dist/esm/client.js +287 -0
  68. package/dist/esm/config.d.ts +12 -0
  69. package/dist/esm/config.js +82 -0
  70. package/dist/esm/core.d.ts +15 -0
  71. package/dist/esm/core.js +96 -0
  72. package/dist/esm/customer-id.d.ts +26 -0
  73. package/dist/esm/customer-id.js +47 -0
  74. package/dist/esm/enums.d.ts +48 -0
  75. package/dist/esm/enums.js +44 -0
  76. package/dist/esm/errors.d.ts +117 -0
  77. package/dist/esm/errors.js +234 -0
  78. package/dist/esm/express.d.ts +49 -0
  79. package/dist/esm/express.js +40 -0
  80. package/dist/esm/fastify.d.ts +47 -0
  81. package/dist/esm/fastify.js +32 -0
  82. package/dist/esm/generated/index.d.ts +17793 -0
  83. package/dist/esm/generated/index.js +8833 -0
  84. package/dist/esm/goals.d.ts +116 -0
  85. package/dist/esm/goals.js +371 -0
  86. package/dist/esm/guard.d.ts +17 -0
  87. package/dist/esm/guard.js +36 -0
  88. package/dist/esm/http.d.ts +16 -0
  89. package/dist/esm/http.js +138 -0
  90. package/dist/esm/identity.d.ts +42 -0
  91. package/dist/esm/identity.js +125 -0
  92. package/dist/esm/index.d.ts +34 -0
  93. package/dist/esm/index.js +23 -0
  94. package/dist/esm/known-customers.d.ts +45 -0
  95. package/dist/esm/known-customers.js +90 -0
  96. package/dist/esm/logger.d.ts +9 -0
  97. package/dist/esm/logger.js +5 -0
  98. package/dist/esm/money.d.ts +16 -0
  99. package/dist/esm/money.js +48 -0
  100. package/dist/esm/next.d.ts +81 -0
  101. package/dist/esm/next.js +96 -0
  102. package/dist/esm/package.json +1 -0
  103. package/dist/esm/payments.d.ts +174 -0
  104. package/dist/esm/payments.js +476 -0
  105. package/dist/esm/resources.d.ts +109 -0
  106. package/dist/esm/resources.js +183 -0
  107. package/dist/esm/shutdown.d.ts +2 -0
  108. package/dist/esm/shutdown.js +47 -0
  109. package/dist/esm/transport.d.ts +14 -0
  110. package/dist/esm/transport.js +166 -0
  111. package/dist/esm/types.d.ts +218 -0
  112. package/dist/esm/types.js +1 -0
  113. package/dist/esm/user-agent.d.ts +1 -0
  114. package/dist/esm/user-agent.js +16 -0
  115. package/dist/esm/version.d.ts +2 -0
  116. package/dist/esm/version.js +2 -0
  117. package/dist/esm/webhooks.d.ts +36 -0
  118. package/dist/esm/webhooks.js +105 -0
  119. package/package.json +128 -4
@@ -0,0 +1,36 @@
1
+ import type { WebhookEvent } from './types.js';
2
+ /** Options for webhook verification. */
3
+ export interface VerifyOptions {
4
+ /** Maximum age (and future skew) of the signature timestamp, in seconds. Default 300. `0` disables the check (tests only). */
5
+ tolerance?: number;
6
+ /** The current time in unix seconds (for tests). Default: now. */
7
+ now?: number;
8
+ }
9
+ /** The raw request body exactly as received. */
10
+ export type RawBody = string | Uint8Array | ArrayBuffer;
11
+ /**
12
+ * Webhook verification: `Clikgate-Signature: t=<unix>,v1=<hex>`,
13
+ * `hex = HMAC-SHA256(secret, "<t>." + raw body)`. No API key or client needed.
14
+ */
15
+ export declare const webhooks: {
16
+ /**
17
+ * Verify a delivery and return the parsed event. Throws {@link SignatureVerificationError}.
18
+ *
19
+ * @example
20
+ * import express from 'express';
21
+ * import { webhooks } from '@clikgate/node';
22
+ * app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
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
25
+ * res.sendStatus(200);
26
+ * });
27
+ */
28
+ verify<T = Record<string, unknown>>(rawBody: RawBody, signatureHeader: string | null | undefined, secret: string, options?: VerifyOptions): WebhookEvent<T>;
29
+ /**
30
+ * Like {@link webhooks.verify}, accepting any of several secrets (while you rotate your own).
31
+ *
32
+ * @example
33
+ * const event = webhooks.verifyAny(req.body, req.get('Clikgate-Signature'), [newSecret, oldSecret]);
34
+ */
35
+ verifyAny<T = Record<string, unknown>>(rawBody: RawBody, signatureHeader: string | null | undefined, secrets: string[], options?: VerifyOptions): WebhookEvent<T>;
36
+ };
@@ -0,0 +1,105 @@
1
+ import { createHmac, timingSafeEqual } from 'node:crypto';
2
+ import { SignatureVerificationError, localError } from './errors.js';
3
+ const fail = (code, message) => new SignatureVerificationError({ message, code });
4
+ function toBytes(raw) {
5
+ if (typeof raw === 'string')
6
+ return new TextEncoder().encode(raw);
7
+ if (raw instanceof Uint8Array)
8
+ return raw;
9
+ if (raw instanceof ArrayBuffer)
10
+ return new Uint8Array(raw);
11
+ throw fail('invalid_payload', 'Pass the raw request body (a string or Buffer), not parsed JSON: re-serialising changes the bytes Clikgate signed.');
12
+ }
13
+ function parseHeader(header) {
14
+ if (typeof header !== 'string' || header.trim() === '')
15
+ throw fail('missing_signature', 'The Clikgate-Signature header is missing.');
16
+ let t = null;
17
+ let bad = false;
18
+ const v1 = [];
19
+ for (const part of header.split(',')) {
20
+ const p = part.trim();
21
+ const eq = p.indexOf('=');
22
+ if (eq < 0)
23
+ continue;
24
+ const key = p.slice(0, eq).trim();
25
+ const value = p.slice(eq + 1).trim();
26
+ if (key === 't') {
27
+ if (/^\d+$/.test(value))
28
+ t = Number(value);
29
+ else
30
+ bad = true;
31
+ }
32
+ else if (key === 'v1')
33
+ v1.push(value);
34
+ }
35
+ if (bad || t === null || v1.length === 0)
36
+ throw fail('malformed_signature', 'The Clikgate-Signature header is malformed (expected t=<unix seconds>,v1=<hex>).');
37
+ return { t, v1 };
38
+ }
39
+ function safeEqualHex(a, b) {
40
+ const x = Buffer.from(a, 'utf8');
41
+ const y = Buffer.from(b, 'utf8');
42
+ if (x.length !== y.length)
43
+ return false;
44
+ return timingSafeEqual(x, y);
45
+ }
46
+ function verifyWith(rawBody, signatureHeader, secrets, options) {
47
+ const body = toBytes(rawBody);
48
+ const { t, v1 } = parseHeader(signatureHeader);
49
+ const tolerance = options.tolerance ?? 300;
50
+ const now = options.now ?? Math.floor(Date.now() / 1000);
51
+ if (tolerance > 0 && Math.abs(now - t) > tolerance) {
52
+ throw fail('timestamp_outside_tolerance', `The signature timestamp is more than ${tolerance} s from now; the request may be a replay, or this server's clock is wrong.`);
53
+ }
54
+ const matched = secrets.some((secret) => {
55
+ const expected = createHmac('sha256', secret).update(`${t}.`).update(body).digest('hex');
56
+ return v1.some((candidate) => safeEqualHex(expected, candidate));
57
+ });
58
+ if (!matched)
59
+ throw fail('no_matching_signature', 'No signature matches: check the endpoint secret, and that you pass the raw body.');
60
+ let event;
61
+ try {
62
+ event = JSON.parse(new TextDecoder().decode(body));
63
+ }
64
+ catch {
65
+ throw fail('invalid_payload', 'The body is not JSON.');
66
+ }
67
+ if (!event || typeof event !== 'object' || Array.isArray(event))
68
+ throw fail('invalid_payload', 'The body is not an event object.');
69
+ return event;
70
+ }
71
+ /**
72
+ * Webhook verification: `Clikgate-Signature: t=<unix>,v1=<hex>`,
73
+ * `hex = HMAC-SHA256(secret, "<t>." + raw body)`. No API key or client needed.
74
+ */
75
+ export const webhooks = {
76
+ /**
77
+ * Verify a delivery and return the parsed event. Throws {@link SignatureVerificationError}.
78
+ *
79
+ * @example
80
+ * import express from 'express';
81
+ * import { webhooks } from '@clikgate/node';
82
+ * app.post('/webhooks/clikgate', express.raw({ type: 'application/json' }), (req, res) => {
83
+ * 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
85
+ * res.sendStatus(200);
86
+ * });
87
+ */
88
+ verify(rawBody, signatureHeader, secret, options = {}) {
89
+ if (typeof secret !== 'string' || secret.length === 0)
90
+ throw localError('invalid_argument', 'secret must be the endpoint secret (whsec_…).', 'secret');
91
+ return verifyWith(rawBody, signatureHeader, [secret], options);
92
+ },
93
+ /**
94
+ * Like {@link webhooks.verify}, accepting any of several secrets (while you rotate your own).
95
+ *
96
+ * @example
97
+ * const event = webhooks.verifyAny(req.body, req.get('Clikgate-Signature'), [newSecret, oldSecret]);
98
+ */
99
+ verifyAny(rawBody, signatureHeader, secrets, options = {}) {
100
+ if (!Array.isArray(secrets) || secrets.length === 0 || secrets.some((s) => typeof s !== 'string' || s.length === 0)) {
101
+ throw localError('invalid_argument', 'secrets must be a non-empty list of endpoint secrets.', 'secrets');
102
+ }
103
+ return verifyWith(rawBody, signatureHeader, secrets, options);
104
+ },
105
+ };
package/package.json CHANGED
@@ -1,6 +1,130 @@
1
1
  {
2
2
  "name": "@clikgate/node",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "2.0.1",
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
+ "keywords": [
6
+ "clikgate",
7
+ "attribution",
8
+ "goals",
9
+ "conversions",
10
+ "deep-linking",
11
+ "webhooks",
12
+ "express",
13
+ "fastify",
14
+ "nextjs"
15
+ ],
16
+ "homepage": "https://clikgate.com/docs/sdks/node",
17
+ "bugs": {
18
+ "url": "https://github.com/clikgate/clikgate-sdks/issues"
19
+ },
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/clikgate/clikgate-sdks.git",
23
+ "directory": "server/node"
24
+ },
25
+ "license": "MIT",
26
+ "author": "Clikgate <sdk@clikgate.com> (https://clikgate.com)",
27
+ "type": "module",
28
+ "sideEffects": false,
29
+ "engines": {
30
+ "node": ">=18"
31
+ },
32
+ "main": "./dist/cjs/index.js",
33
+ "module": "./dist/esm/index.js",
34
+ "types": "./dist/cjs/index.d.ts",
35
+ "exports": {
36
+ ".": {
37
+ "import": {
38
+ "types": "./dist/esm/index.d.ts",
39
+ "default": "./dist/esm/index.js"
40
+ },
41
+ "require": {
42
+ "types": "./dist/cjs/index.d.ts",
43
+ "default": "./dist/cjs/index.js"
44
+ }
45
+ },
46
+ "./express": {
47
+ "import": {
48
+ "types": "./dist/esm/express.d.ts",
49
+ "default": "./dist/esm/express.js"
50
+ },
51
+ "require": {
52
+ "types": "./dist/cjs/express.d.ts",
53
+ "default": "./dist/cjs/express.js"
54
+ }
55
+ },
56
+ "./fastify": {
57
+ "import": {
58
+ "types": "./dist/esm/fastify.d.ts",
59
+ "default": "./dist/esm/fastify.js"
60
+ },
61
+ "require": {
62
+ "types": "./dist/cjs/fastify.d.ts",
63
+ "default": "./dist/cjs/fastify.js"
64
+ }
65
+ },
66
+ "./next": {
67
+ "import": {
68
+ "types": "./dist/esm/next.d.ts",
69
+ "default": "./dist/esm/next.js"
70
+ },
71
+ "require": {
72
+ "types": "./dist/cjs/next.d.ts",
73
+ "default": "./dist/cjs/next.js"
74
+ }
75
+ },
76
+ "./package.json": "./package.json"
77
+ },
78
+ "files": [
79
+ "dist",
80
+ "README.md",
81
+ "CHANGELOG.md",
82
+ "SECURITY.md",
83
+ "LICENSE"
84
+ ],
85
+ "scripts": {
86
+ "build": "node scripts/build.mjs",
87
+ "typecheck": "tsc -p tsconfig.json --noEmit",
88
+ "typecheck:examples": "tsc -p examples/express/tsconfig.json --noEmit && tsc -p examples/nextjs/tsconfig.json --noEmit",
89
+ "lint": "eslint .",
90
+ "test": "node scripts/run-tests.mjs",
91
+ "test:unit": "node scripts/run-tests.mjs --unit",
92
+ "test:conformance": "node scripts/run-tests.mjs --conformance",
93
+ "check:version": "node scripts/check-version.mjs",
94
+ "check:package": "node scripts/check-package.mjs",
95
+ "generate": "node ../codegen/generate.mjs --lang node",
96
+ "generate:check": "node ../codegen/generate.mjs --lang node --check",
97
+ "sbom": "npx --yes @cyclonedx/cyclonedx-npm@6.0.1 --omit dev --omit peer --omit optional --package-lock-only --spec-version 1.6 --output-reproducible --output-format JSON --output-file sbom.cdx.json",
98
+ "prepublishOnly": "npm run check:version && npm run build && npm run check:package"
99
+ },
100
+ "peerDependencies": {
101
+ "fastify": ">=5",
102
+ "next": ">=15"
103
+ },
104
+ "peerDependenciesMeta": {
105
+ "fastify": {
106
+ "optional": true
107
+ },
108
+ "next": {
109
+ "optional": true
110
+ }
111
+ },
112
+ "devDependencies": {
113
+ "@eslint/js": "10.0.1",
114
+ "@types/express": "5.0.6",
115
+ "@types/node": "18.19.130",
116
+ "@types/react": "19.3.0",
117
+ "eslint": "10.13.0",
118
+ "express": "5.3.0",
119
+ "fastify": "5.12.7",
120
+ "next": "16.4.3",
121
+ "react": "19.3.1",
122
+ "react-dom": "19.3.1",
123
+ "typescript": "6.0.3",
124
+ "typescript-eslint": "8.72.0"
125
+ },
126
+ "publishConfig": {
127
+ "access": "public",
128
+ "provenance": true
129
+ }
130
+ }