@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,49 @@
1
+ /**
2
+ * Express / Connect middleware: keeps the click ID (SPEC section 17).
3
+ *
4
+ * @example
5
+ * import express from 'express';
6
+ * import { Clikgate } from '@clikgate/node';
7
+ * import { clikgateMiddleware } from '@clikgate/node/express';
8
+ *
9
+ * const clikgate = new Clikgate();
10
+ * const app = express();
11
+ * app.use(clikgateMiddleware(clikgate));
12
+ * app.post('/signup', (req, res) => {
13
+ * const clickId = req.clikgate.clickId; // save it with the application
14
+ * });
15
+ *
16
+ * @packageDocumentation
17
+ */
18
+ import type { IncomingMessage, ServerResponse } from 'node:http';
19
+ import { type PersistOptions } from './click-ids.js';
20
+ import type { Clikgate } from './client.js';
21
+ /** What the middleware puts on the request. */
22
+ export interface ClikgateRequestContext {
23
+ /** The click ID from the query, the `_cg_<param>` cookie or the `Clikgate-Click-Id` header; `null` when there is none. */
24
+ clickId: string | null;
25
+ }
26
+ declare global {
27
+ namespace Express {
28
+ interface Request {
29
+ /** Set by `clikgateMiddleware` from `@clikgate/node/express`. */
30
+ clikgate: ClikgateRequestContext;
31
+ }
32
+ }
33
+ }
34
+ /** Middleware options. */
35
+ export interface ClikgateMiddlewareOptions extends PersistOptions {
36
+ /** Write the cookie when the click ID arrives in the query string (default true; last click wins, like the web script). */
37
+ persist?: boolean;
38
+ }
39
+ type Next = (err?: unknown) => void;
40
+ /**
41
+ * Express/Connect middleware: sets `req.clikgate.clickId`, and stores a click ID that arrives in
42
+ * the query string in the first-party `_cg_<param>` cookie. Pass the client so the organisation's
43
+ * click-ID parameter is used; without it, `cgid`.
44
+ *
45
+ * @example
46
+ * app.use(clikgateMiddleware(clikgate, { days: 30 }));
47
+ */
48
+ export declare function clikgateMiddleware(client?: Clikgate | null, options?: ClikgateMiddlewareOptions): (req: IncomingMessage, res: ServerResponse, next: Next) => void;
49
+ export {};
@@ -0,0 +1,44 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.captureClickId = captureClickId;
4
+ exports.clikgateMiddleware = clikgateMiddleware;
5
+ const click_ids_js_1 = require("./click-ids.js");
6
+ /** @internal Shared by the add-ons: read, expose and (optionally) persist the click ID. */
7
+ function captureClickId(helpers, req, res, options) {
8
+ const clickId = helpers.fromRequest(req);
9
+ if (clickId && options.persist !== false) {
10
+ const url = new URL(req.originalUrl ?? req.url ?? '/', 'http://localhost');
11
+ if (url.searchParams.getAll(helpers.paramName).includes(clickId)) {
12
+ const { persist: _p, ...cookie } = options;
13
+ helpers.persist(res, clickId, cookie);
14
+ }
15
+ }
16
+ return clickId;
17
+ }
18
+ /**
19
+ * Express/Connect middleware: sets `req.clikgate.clickId`, and stores a click ID that arrives in
20
+ * the query string in the first-party `_cg_<param>` cookie. Pass the client so the organisation's
21
+ * click-ID parameter is used; without it, `cgid`.
22
+ *
23
+ * @example
24
+ * app.use(clikgateMiddleware(clikgate, { days: 30 }));
25
+ */
26
+ function clikgateMiddleware(client, options = {}) {
27
+ const helpers = client ? client.clickIds : click_ids_js_1.clickIds;
28
+ let warmed = false;
29
+ return (req, res, next) => {
30
+ try {
31
+ if (client && !warmed) {
32
+ warmed = true;
33
+ // learn the organisation's click_id_param in the background; never blocks a request
34
+ void client.config().catch(() => undefined);
35
+ }
36
+ const clickId = captureClickId(helpers, req, res, options);
37
+ req.clikgate = { clickId };
38
+ next();
39
+ }
40
+ catch (err) {
41
+ next(err);
42
+ }
43
+ };
44
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Fastify plugin: keeps the click ID (SPEC section 17). Works with Fastify 5 (Node 20+).
3
+ *
4
+ * @example
5
+ * import Fastify from 'fastify';
6
+ * import { Clikgate } from '@clikgate/node';
7
+ * import { clikgatePlugin } from '@clikgate/node/fastify';
8
+ *
9
+ * const clikgate = new Clikgate();
10
+ * const app = Fastify();
11
+ * await app.register(clikgatePlugin, { client: clikgate });
12
+ * app.post('/signup', async (request) => {
13
+ * const clickId = request.clikgate.clickId;
14
+ * });
15
+ *
16
+ * @packageDocumentation
17
+ */
18
+ import type { FastifyPluginAsync } from 'fastify';
19
+ import { type PersistOptions } from './click-ids.js';
20
+ import type { Clikgate } from './client.js';
21
+ /** What the plugin puts on the request. */
22
+ export interface ClikgateRequestContext {
23
+ /** The click ID, or `null`. */
24
+ clickId: string | null;
25
+ }
26
+ declare module 'fastify' {
27
+ interface FastifyRequest {
28
+ /** Set by `clikgatePlugin` from `@clikgate/node/fastify`. */
29
+ clikgate: ClikgateRequestContext;
30
+ }
31
+ }
32
+ /** Plugin options. */
33
+ export interface ClikgatePluginOptions extends PersistOptions {
34
+ /** The client (for the organisation's click-ID parameter). Optional: without it, `cgid`. */
35
+ client?: Clikgate;
36
+ /** Write the cookie when the click ID arrives in the query string (default true). */
37
+ persist?: boolean;
38
+ }
39
+ /**
40
+ * Fastify plugin: sets `request.clikgate.clickId` and keeps a click ID from the query string in the
41
+ * `_cg_<param>` cookie.
42
+ *
43
+ * @example
44
+ * await app.register(clikgatePlugin, { client: clikgate, days: 30 });
45
+ */
46
+ export declare const clikgatePlugin: FastifyPluginAsync<ClikgatePluginOptions>;
47
+ export default clikgatePlugin;
@@ -0,0 +1,35 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.clikgatePlugin = void 0;
4
+ const click_ids_js_1 = require("./click-ids.js");
5
+ const plugin = async (fastify, options) => {
6
+ const { client, persist, ...cookie } = options;
7
+ const helpers = client ? client.clickIds : click_ids_js_1.clickIds;
8
+ if (client)
9
+ void client.config().catch(() => undefined);
10
+ // v5: reference-type decorators must start as null and be set per request
11
+ fastify.decorateRequest('clikgate', null);
12
+ fastify.addHook('onRequest', async (request, reply) => {
13
+ const clickId = helpers.fromRequest({ url: request.url, headers: request.headers });
14
+ request.clikgate = { clickId };
15
+ if (clickId && persist !== false) {
16
+ const url = new URL(request.url, 'http://localhost');
17
+ if (url.searchParams.getAll(helpers.paramName).includes(clickId))
18
+ helpers.persist(reply, clickId, cookie);
19
+ }
20
+ });
21
+ };
22
+ // What fastify-plugin does, without the dependency: share decorators and hooks with the parent scope.
23
+ const meta = plugin;
24
+ meta[Symbol.for('skip-override')] = true;
25
+ meta[Symbol.for('fastify.display-name')] = '@clikgate/node/fastify';
26
+ meta[Symbol.for('plugin-meta')] = { name: '@clikgate/node/fastify', fastify: '>=5' };
27
+ /**
28
+ * Fastify plugin: sets `request.clikgate.clickId` and keeps a click ID from the query string in the
29
+ * `_cg_<param>` cookie.
30
+ *
31
+ * @example
32
+ * await app.register(clikgatePlugin, { client: clikgate, days: 30 });
33
+ */
34
+ exports.clikgatePlugin = plugin;
35
+ exports.default = exports.clikgatePlugin;