@clikgate/node 0.0.0-stage → 2.0.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 (111) hide show
  1. package/CHANGELOG.md +126 -0
  2. package/LICENSE +21 -0
  3. package/README.md +300 -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 +175 -0
  10. package/dist/cjs/client.js +266 -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/enums.d.ts +48 -0
  16. package/dist/cjs/enums.js +47 -0
  17. package/dist/cjs/errors.d.ts +117 -0
  18. package/dist/cjs/errors.js +257 -0
  19. package/dist/cjs/express.d.ts +49 -0
  20. package/dist/cjs/express.js +44 -0
  21. package/dist/cjs/fastify.d.ts +47 -0
  22. package/dist/cjs/fastify.js +35 -0
  23. package/dist/cjs/generated/index.d.ts +17534 -0
  24. package/dist/cjs/generated/index.js +8816 -0
  25. package/dist/cjs/goals.d.ts +116 -0
  26. package/dist/cjs/goals.js +381 -0
  27. package/dist/cjs/guard.d.ts +17 -0
  28. package/dist/cjs/guard.js +40 -0
  29. package/dist/cjs/http.d.ts +16 -0
  30. package/dist/cjs/http.js +148 -0
  31. package/dist/cjs/identity.d.ts +32 -0
  32. package/dist/cjs/identity.js +99 -0
  33. package/dist/cjs/index.d.ts +32 -0
  34. package/dist/cjs/index.js +64 -0
  35. package/dist/cjs/logger.d.ts +9 -0
  36. package/dist/cjs/logger.js +8 -0
  37. package/dist/cjs/money.d.ts +16 -0
  38. package/dist/cjs/money.js +51 -0
  39. package/dist/cjs/next.d.ts +81 -0
  40. package/dist/cjs/next.js +103 -0
  41. package/dist/cjs/package.json +1 -0
  42. package/dist/cjs/payments.d.ts +174 -0
  43. package/dist/cjs/payments.js +485 -0
  44. package/dist/cjs/resources.d.ts +109 -0
  45. package/dist/cjs/resources.js +189 -0
  46. package/dist/cjs/shutdown.d.ts +2 -0
  47. package/dist/cjs/shutdown.js +51 -0
  48. package/dist/cjs/transport.d.ts +14 -0
  49. package/dist/cjs/transport.js +204 -0
  50. package/dist/cjs/types.d.ts +218 -0
  51. package/dist/cjs/types.js +2 -0
  52. package/dist/cjs/user-agent.d.ts +1 -0
  53. package/dist/cjs/user-agent.js +53 -0
  54. package/dist/cjs/version.d.ts +2 -0
  55. package/dist/cjs/version.js +5 -0
  56. package/dist/cjs/webhooks.d.ts +36 -0
  57. package/dist/cjs/webhooks.js +108 -0
  58. package/dist/esm/ads-hashing.d.ts +37 -0
  59. package/dist/esm/ads-hashing.js +62 -0
  60. package/dist/esm/click-ids.d.ts +184 -0
  61. package/dist/esm/click-ids.js +526 -0
  62. package/dist/esm/client.d.ts +175 -0
  63. package/dist/esm/client.js +262 -0
  64. package/dist/esm/config.d.ts +12 -0
  65. package/dist/esm/config.js +82 -0
  66. package/dist/esm/core.d.ts +15 -0
  67. package/dist/esm/core.js +96 -0
  68. package/dist/esm/enums.d.ts +48 -0
  69. package/dist/esm/enums.js +44 -0
  70. package/dist/esm/errors.d.ts +117 -0
  71. package/dist/esm/errors.js +234 -0
  72. package/dist/esm/express.d.ts +49 -0
  73. package/dist/esm/express.js +40 -0
  74. package/dist/esm/fastify.d.ts +47 -0
  75. package/dist/esm/fastify.js +32 -0
  76. package/dist/esm/generated/index.d.ts +17534 -0
  77. package/dist/esm/generated/index.js +8754 -0
  78. package/dist/esm/goals.d.ts +116 -0
  79. package/dist/esm/goals.js +371 -0
  80. package/dist/esm/guard.d.ts +17 -0
  81. package/dist/esm/guard.js +36 -0
  82. package/dist/esm/http.d.ts +16 -0
  83. package/dist/esm/http.js +138 -0
  84. package/dist/esm/identity.d.ts +32 -0
  85. package/dist/esm/identity.js +92 -0
  86. package/dist/esm/index.d.ts +32 -0
  87. package/dist/esm/index.js +21 -0
  88. package/dist/esm/logger.d.ts +9 -0
  89. package/dist/esm/logger.js +5 -0
  90. package/dist/esm/money.d.ts +16 -0
  91. package/dist/esm/money.js +48 -0
  92. package/dist/esm/next.d.ts +81 -0
  93. package/dist/esm/next.js +96 -0
  94. package/dist/esm/package.json +1 -0
  95. package/dist/esm/payments.d.ts +174 -0
  96. package/dist/esm/payments.js +476 -0
  97. package/dist/esm/resources.d.ts +109 -0
  98. package/dist/esm/resources.js +183 -0
  99. package/dist/esm/shutdown.d.ts +2 -0
  100. package/dist/esm/shutdown.js +47 -0
  101. package/dist/esm/transport.d.ts +14 -0
  102. package/dist/esm/transport.js +166 -0
  103. package/dist/esm/types.d.ts +218 -0
  104. package/dist/esm/types.js +1 -0
  105. package/dist/esm/user-agent.d.ts +1 -0
  106. package/dist/esm/user-agent.js +16 -0
  107. package/dist/esm/version.d.ts +2 -0
  108. package/dist/esm/version.js +2 -0
  109. package/dist/esm/webhooks.d.ts +36 -0
  110. package/dist/esm/webhooks.js +105 -0
  111. package/package.json +128 -4
@@ -0,0 +1,184 @@
1
+ import type { IncomingMessage, ServerResponse } from 'node:http';
2
+ /** The click ID format: a prefixed ULID, `clk_` + 26 uppercase Crockford characters. */
3
+ export declare const CLICK_ID_PATTERN: RegExp;
4
+ /** The header a caller (e.g. your mobile app or BFF) can use to pass the click ID. */
5
+ export declare const CLICK_ID_HEADER = "clikgate-click-id";
6
+ /**
7
+ * Anything request-like: Node/Express/Connect/Fastify requests, Fetch `Request`, Next.js `NextRequest`,
8
+ * or a plain `{ url, headers }` object.
9
+ */
10
+ export type RequestLike = {
11
+ url?: string;
12
+ originalUrl?: string;
13
+ headers?: unknown;
14
+ nextUrl?: {
15
+ href: string;
16
+ };
17
+ } | {
18
+ url: string;
19
+ headers: {
20
+ get(name: string): string | null;
21
+ };
22
+ };
23
+ /** Anything response-like that can carry `Set-Cookie`: Node `ServerResponse`/Express `res`, Fastify `reply`, Fetch `Response`/`Headers`. */
24
+ export type ResponseLike = object;
25
+ /** Options for the click-ID cookie. */
26
+ export interface PersistOptions {
27
+ /** Lifetime in days (default 30). */
28
+ days?: number;
29
+ /** Add `Secure`. Default: true when the request was HTTPS (or unknown). */
30
+ secure?: boolean;
31
+ /** Cookie domain, e.g. `.example.com` to share across subdomains. */
32
+ domain?: string;
33
+ }
34
+ /**
35
+ * True when `id` is a Clikgate click ID (`clk_` + 26 characters).
36
+ *
37
+ * @example
38
+ * clickIds.isValid('clk_01JCK8Z9V7Q4M2N6P8R0S2T4W6'); // true
39
+ */
40
+ export declare function isValid(id: unknown): id is string;
41
+ /** Click-ID helpers bound to a `click_id_param` (SPEC section 13). */
42
+ export declare class ClickIds {
43
+ private readonly param;
44
+ /** The query parameter name in use (`cgid` unless configured). */
45
+ get paramName(): string;
46
+ /** The cookie name: `_cg_<param>`, the same first-party cookie the web script writes. */
47
+ get cookieName(): string;
48
+ /** {@inheritDoc isValid} */
49
+ isValid(id: unknown): id is string;
50
+ /**
51
+ * Read the click ID from a request: the query parameter, then the `_cg_<param>` cookie, then the
52
+ * `Clikgate-Click-Id` header. Only valid IDs are returned.
53
+ *
54
+ * @example
55
+ * app.post('/signup', (req, res) => {
56
+ * const clickId = clikgate.clickIds.fromRequest(req); // save it with the application
57
+ * });
58
+ */
59
+ fromRequest(req: RequestLike): string | null;
60
+ /** The click ID and where it was found (query, cookie or header). */
61
+ private locate;
62
+ /**
63
+ * The visitor context to send with a goal (SPEC 13.1): the click ID, how it was kept, and the browser engine and
64
+ * platform parsed from the `User-Agent` here in the SDK (the User-Agent itself is never sent). Spread it into the
65
+ * goal options.
66
+ *
67
+ * - `keptBy` is `server_cookie` when the ID came from the cookie and the `_cg_kept=s` marker is there (your server
68
+ * set it, see {@link keepRoute} and {@link persist}), `script_cookie` for the cookie without the marker, `form`
69
+ * for the `Clikgate-Click-Id` header, and `null` when it came from the URL or there is none.
70
+ *
71
+ * @example
72
+ * app.post('/signup', (req, res) => {
73
+ * clikgate.goal('account_opened', { reference: application.id, ...clikgate.clickIds.context(req) });
74
+ * });
75
+ */
76
+ context(req: RequestLike): ClickContext;
77
+ /**
78
+ * The `Set-Cookie` value that keeps the click ID: `SameSite=Lax`, `Secure` on HTTPS, not `HttpOnly`
79
+ * (the web script reads it).
80
+ *
81
+ * @example
82
+ * clikgate.clickIds.cookieHeader(clickId, { days: 30 });
83
+ * // '_cg_cgid=clk_…; Path=/; Max-Age=2592000; SameSite=Lax; Secure'
84
+ */
85
+ cookieHeader(id: string, options?: PersistOptions): string;
86
+ /**
87
+ * Add the click-ID cookie to a response, keeping any `Set-Cookie` headers already there.
88
+ *
89
+ * @example
90
+ * const clickId = clikgate.clickIds.fromRequest(req);
91
+ * if (clickId) clikgate.clickIds.persist(res, clickId);
92
+ */
93
+ persist(res: ResponseLike, id: string, options?: PersistOptions): void;
94
+ /**
95
+ * The `/cg/keep` handler (SPEC 13.1): the web script's `data-server-endpoint="/cg/keep"` posts the click ID from the
96
+ * page URL here, and your server sets the `_cg_<param>` cookie (plus the `_cg_kept=s` marker) for `days` days.
97
+ * Safari, and every browser on iPhone, keeps a click ID saved by a script for up to 7 days (sometimes less); a cookie
98
+ * your server sets lasts as long as you choose, up to the browser's limit. Serve it from the same host as your website.
99
+ *
100
+ * Returns a Fetch handler (`(Request) => Promise<Response>`, e.g. a Next.js App Router `POST`), with
101
+ * `.express` (Express/Connect) and `.node` (`node:http`) adapters, and `.handle` for any other framework.
102
+ * Only same-origin `POST`s with a valid, matching click ID are accepted; every answer is `no-store` with an
103
+ * empty body. `secure` defaults to true here.
104
+ *
105
+ * @throws InvalidRequestError `invalid_argument` when `days` is not 1-400.
106
+ * @example
107
+ * // app/cg/keep/route.ts
108
+ * export const POST = clikgate.clickIds.keepRoute();
109
+ * // Express
110
+ * app.all('/cg/keep', clikgate.clickIds.keepRoute({ days: 90 }).express);
111
+ */
112
+ keepRoute(options?: KeepRouteOptions): KeepRoute;
113
+ /**
114
+ * Find the click ID in a payment provider's payload: Paystack `metadata` (and `custom_fields`),
115
+ * Flutterwave `meta`, Shopify note or cart attributes, WooCommerce order meta, or your own webhook.
116
+ *
117
+ * @example
118
+ * app.post('/paystack/webhook', express.json(), (req, res) => {
119
+ * const clickId = clikgate.clickIds.fromPaymentMetadata(req.body);
120
+ * });
121
+ */
122
+ fromPaymentMetadata(payload: unknown): string | null;
123
+ }
124
+ /** How the click ID was kept (`kept_by`, SPEC 9.1). */
125
+ export type KeptBy = 'server_cookie' | 'script_cookie' | 'form' | 'payment_metadata' | 'unknown';
126
+ /** The browser engine family (`browser_engine`, SPEC 9.1). */
127
+ export type BrowserEngine = 'webkit_ios' | 'safari_mac' | 'chromium' | 'gecko' | 'other';
128
+ /** The visitor's platform (`platform`, SPEC 9.1). */
129
+ export type Platform = 'ios' | 'android' | 'macos' | 'windows' | 'linux' | 'other';
130
+ /** Every `kept_by` value. */
131
+ export declare const KEPT_BY: readonly KeptBy[];
132
+ /** Every `browser_engine` value. */
133
+ export declare const BROWSER_ENGINES: readonly BrowserEngine[];
134
+ /** Every `platform` value. */
135
+ export declare const PLATFORMS: readonly Platform[];
136
+ /** What `clickIds.context(req)` returns; its keys are goal options, so spread it into a goal. */
137
+ export interface ClickContext {
138
+ clickId: string | null;
139
+ keptBy: KeptBy | null;
140
+ browserEngine: BrowserEngine;
141
+ platform: Platform;
142
+ }
143
+ /** Options for `clickIds.keepRoute()`. */
144
+ export interface KeepRouteOptions {
145
+ /** Cookie lifetime in days, 1-400 (default 30). */
146
+ days?: number;
147
+ /** Add `Secure` (default true). */
148
+ secure?: boolean;
149
+ /** Cookie domain, e.g. `.example.com` to share across subdomains. */
150
+ domain?: string;
151
+ }
152
+ /** A framework-neutral `/cg/keep` request. `readBody` returns the raw body, or `null` when it is over 1024 bytes. */
153
+ export interface KeepInput {
154
+ method: string;
155
+ /** Header names in any case: a plain object, a Node `IncomingHttpHeaders` or a Fetch `Headers`. */
156
+ headers: unknown;
157
+ readBody: () => Promise<Uint8Array | null>;
158
+ /** The request URL, used for the host only when there is no `Host` header. Its query string is never read. */
159
+ url?: string;
160
+ }
161
+ /** A `/cg/keep` answer: the status and the headers to send (the body is always empty). */
162
+ export interface KeepResult {
163
+ status: 204 | 400 | 403 | 405;
164
+ headers: Array<[string, string]>;
165
+ }
166
+ type NodeReq = IncomingMessage & {
167
+ body?: unknown;
168
+ };
169
+ type NodeRes = ServerResponse;
170
+ /** The `/cg/keep` route: a Fetch handler plus framework adapters. */
171
+ export interface KeepRoute {
172
+ (request: Request): Promise<Response>;
173
+ /** Express / Connect: `app.all('/cg/keep', route.express)` (mount it before a body parser, or after one, both work). */
174
+ express: (req: NodeReq, res: NodeRes, next?: (err?: unknown) => void) => void;
175
+ /** Plain `node:http`: `if (req.url === '/cg/keep') return route.node(req, res)`. */
176
+ node: (req: NodeReq, res: NodeRes) => void;
177
+ /** The framework-neutral core, for any other framework. */
178
+ handle: (input: KeepInput) => Promise<KeepResult>;
179
+ }
180
+ /** The marker cookie that tells the web script (and `context()`) that your server kept the click ID. */
181
+ export declare const KEPT_COOKIE = "_cg_kept";
182
+ /** Click-ID helpers with the default parameter (`cgid`), usable without a client. */
183
+ export declare const clickIds: ClickIds;
184
+ export {};