@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.
- package/CHANGELOG.md +126 -0
- package/LICENSE +21 -0
- package/README.md +300 -2
- package/SECURITY.md +34 -0
- package/dist/cjs/ads-hashing.d.ts +37 -0
- package/dist/cjs/ads-hashing.js +67 -0
- package/dist/cjs/click-ids.d.ts +184 -0
- package/dist/cjs/click-ids.js +535 -0
- package/dist/cjs/client.d.ts +175 -0
- package/dist/cjs/client.js +266 -0
- package/dist/cjs/config.d.ts +12 -0
- package/dist/cjs/config.js +87 -0
- package/dist/cjs/core.d.ts +15 -0
- package/dist/cjs/core.js +100 -0
- package/dist/cjs/enums.d.ts +48 -0
- package/dist/cjs/enums.js +47 -0
- package/dist/cjs/errors.d.ts +117 -0
- package/dist/cjs/errors.js +257 -0
- package/dist/cjs/express.d.ts +49 -0
- package/dist/cjs/express.js +44 -0
- package/dist/cjs/fastify.d.ts +47 -0
- package/dist/cjs/fastify.js +35 -0
- package/dist/cjs/generated/index.d.ts +17534 -0
- package/dist/cjs/generated/index.js +8816 -0
- package/dist/cjs/goals.d.ts +116 -0
- package/dist/cjs/goals.js +381 -0
- package/dist/cjs/guard.d.ts +17 -0
- package/dist/cjs/guard.js +40 -0
- package/dist/cjs/http.d.ts +16 -0
- package/dist/cjs/http.js +148 -0
- package/dist/cjs/identity.d.ts +32 -0
- package/dist/cjs/identity.js +99 -0
- package/dist/cjs/index.d.ts +32 -0
- package/dist/cjs/index.js +64 -0
- package/dist/cjs/logger.d.ts +9 -0
- package/dist/cjs/logger.js +8 -0
- package/dist/cjs/money.d.ts +16 -0
- package/dist/cjs/money.js +51 -0
- package/dist/cjs/next.d.ts +81 -0
- package/dist/cjs/next.js +103 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/payments.d.ts +174 -0
- package/dist/cjs/payments.js +485 -0
- package/dist/cjs/resources.d.ts +109 -0
- package/dist/cjs/resources.js +189 -0
- package/dist/cjs/shutdown.d.ts +2 -0
- package/dist/cjs/shutdown.js +51 -0
- package/dist/cjs/transport.d.ts +14 -0
- package/dist/cjs/transport.js +204 -0
- package/dist/cjs/types.d.ts +218 -0
- package/dist/cjs/types.js +2 -0
- package/dist/cjs/user-agent.d.ts +1 -0
- package/dist/cjs/user-agent.js +53 -0
- package/dist/cjs/version.d.ts +2 -0
- package/dist/cjs/version.js +5 -0
- package/dist/cjs/webhooks.d.ts +36 -0
- package/dist/cjs/webhooks.js +108 -0
- package/dist/esm/ads-hashing.d.ts +37 -0
- package/dist/esm/ads-hashing.js +62 -0
- package/dist/esm/click-ids.d.ts +184 -0
- package/dist/esm/click-ids.js +526 -0
- package/dist/esm/client.d.ts +175 -0
- package/dist/esm/client.js +262 -0
- package/dist/esm/config.d.ts +12 -0
- package/dist/esm/config.js +82 -0
- package/dist/esm/core.d.ts +15 -0
- package/dist/esm/core.js +96 -0
- package/dist/esm/enums.d.ts +48 -0
- package/dist/esm/enums.js +44 -0
- package/dist/esm/errors.d.ts +117 -0
- package/dist/esm/errors.js +234 -0
- package/dist/esm/express.d.ts +49 -0
- package/dist/esm/express.js +40 -0
- package/dist/esm/fastify.d.ts +47 -0
- package/dist/esm/fastify.js +32 -0
- package/dist/esm/generated/index.d.ts +17534 -0
- package/dist/esm/generated/index.js +8754 -0
- package/dist/esm/goals.d.ts +116 -0
- package/dist/esm/goals.js +371 -0
- package/dist/esm/guard.d.ts +17 -0
- package/dist/esm/guard.js +36 -0
- package/dist/esm/http.d.ts +16 -0
- package/dist/esm/http.js +138 -0
- package/dist/esm/identity.d.ts +32 -0
- package/dist/esm/identity.js +92 -0
- package/dist/esm/index.d.ts +32 -0
- package/dist/esm/index.js +21 -0
- package/dist/esm/logger.d.ts +9 -0
- package/dist/esm/logger.js +5 -0
- package/dist/esm/money.d.ts +16 -0
- package/dist/esm/money.js +48 -0
- package/dist/esm/next.d.ts +81 -0
- package/dist/esm/next.js +96 -0
- package/dist/esm/package.json +1 -0
- package/dist/esm/payments.d.ts +174 -0
- package/dist/esm/payments.js +476 -0
- package/dist/esm/resources.d.ts +109 -0
- package/dist/esm/resources.js +183 -0
- package/dist/esm/shutdown.d.ts +2 -0
- package/dist/esm/shutdown.js +47 -0
- package/dist/esm/transport.d.ts +14 -0
- package/dist/esm/transport.js +166 -0
- package/dist/esm/types.d.ts +218 -0
- package/dist/esm/types.js +1 -0
- package/dist/esm/user-agent.d.ts +1 -0
- package/dist/esm/user-agent.js +16 -0
- package/dist/esm/version.d.ts +2 -0
- package/dist/esm/version.js +2 -0
- package/dist/esm/webhooks.d.ts +36 -0
- package/dist/esm/webhooks.js +105 -0
- package/package.json +128 -4
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/** A goal's kind, set in the goal's settings (never in a goal call): `standard` or `payment`. */
|
|
2
|
+
export declare const GoalKind: {
|
|
3
|
+
readonly Standard: "standard";
|
|
4
|
+
readonly Payment: "payment";
|
|
5
|
+
};
|
|
6
|
+
/** A goal's kind, set in the goal's settings (never in a goal call): `standard` or `payment`. */
|
|
7
|
+
export type GoalKind = (typeof GoalKind)[keyof typeof GoalKind];
|
|
8
|
+
/** A goal call's outcome: `counted`, `waiting` (a Payment goal awaiting confirmation), `received` (not counted) or `refused`. */
|
|
9
|
+
export declare const GoalStatus: {
|
|
10
|
+
readonly Counted: "counted";
|
|
11
|
+
readonly Waiting: "waiting";
|
|
12
|
+
readonly Refused: "refused";
|
|
13
|
+
readonly Received: "received";
|
|
14
|
+
};
|
|
15
|
+
/** A goal call's outcome: `counted`, `waiting` (a Payment goal awaiting confirmation), `received` (not counted) or `refused`. */
|
|
16
|
+
export type GoalStatus = (typeof GoalStatus)[keyof typeof GoalStatus];
|
|
17
|
+
/** A payment provider: every gateway in `GET /v1/payment-gateways`, plus `shopify`, `woocommerce` and `custom`. */
|
|
18
|
+
export declare const Provider: {
|
|
19
|
+
readonly Paystack: "paystack";
|
|
20
|
+
readonly Flutterwave: "flutterwave";
|
|
21
|
+
readonly Monnify: "monnify";
|
|
22
|
+
readonly Squad: "squad";
|
|
23
|
+
readonly Opay: "opay";
|
|
24
|
+
readonly Interswitch: "interswitch";
|
|
25
|
+
readonly Remita: "remita";
|
|
26
|
+
readonly Korapay: "korapay";
|
|
27
|
+
readonly Paga: "paga";
|
|
28
|
+
readonly Moniepoint: "moniepoint";
|
|
29
|
+
readonly Hubtel: "hubtel";
|
|
30
|
+
readonly Mpesa: "mpesa";
|
|
31
|
+
readonly Pesapal: "pesapal";
|
|
32
|
+
readonly MtnMomo: "mtn_momo";
|
|
33
|
+
readonly AirtelMoney: "airtel_money";
|
|
34
|
+
readonly Yoco: "yoco";
|
|
35
|
+
readonly Payfast: "payfast";
|
|
36
|
+
readonly PeachPayments: "peach_payments";
|
|
37
|
+
readonly DpoPay: "dpo_pay";
|
|
38
|
+
readonly Stripe: "stripe";
|
|
39
|
+
readonly Paypal: "paypal";
|
|
40
|
+
readonly Adyen: "adyen";
|
|
41
|
+
readonly Square: "square";
|
|
42
|
+
readonly CheckoutCom: "checkout_com";
|
|
43
|
+
readonly Shopify: "shopify";
|
|
44
|
+
readonly Woocommerce: "woocommerce";
|
|
45
|
+
readonly Custom: "custom";
|
|
46
|
+
};
|
|
47
|
+
/** A payment provider: every gateway in `GET /v1/payment-gateways`, plus `shopify`, `woocommerce` and `custom`. */
|
|
48
|
+
export type Provider = (typeof Provider)[keyof typeof Provider];
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
// Generated by server/codegen/generate.mjs from openapi.json (GoalKind, GoalStatus, Provider). Do not edit by hand.
|
|
3
|
+
// Source sha256 d39834b71974ddd58b7ba177f00c450738a641f18add17189a2f707bf724c796.
|
|
4
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
5
|
+
exports.Provider = exports.GoalStatus = exports.GoalKind = void 0;
|
|
6
|
+
/** A goal's kind, set in the goal's settings (never in a goal call): `standard` or `payment`. */
|
|
7
|
+
exports.GoalKind = {
|
|
8
|
+
Standard: 'standard',
|
|
9
|
+
Payment: 'payment',
|
|
10
|
+
};
|
|
11
|
+
/** A goal call's outcome: `counted`, `waiting` (a Payment goal awaiting confirmation), `received` (not counted) or `refused`. */
|
|
12
|
+
exports.GoalStatus = {
|
|
13
|
+
Counted: 'counted',
|
|
14
|
+
Waiting: 'waiting',
|
|
15
|
+
Refused: 'refused',
|
|
16
|
+
Received: 'received',
|
|
17
|
+
};
|
|
18
|
+
/** A payment provider: every gateway in `GET /v1/payment-gateways`, plus `shopify`, `woocommerce` and `custom`. */
|
|
19
|
+
exports.Provider = {
|
|
20
|
+
Paystack: 'paystack',
|
|
21
|
+
Flutterwave: 'flutterwave',
|
|
22
|
+
Monnify: 'monnify',
|
|
23
|
+
Squad: 'squad',
|
|
24
|
+
Opay: 'opay',
|
|
25
|
+
Interswitch: 'interswitch',
|
|
26
|
+
Remita: 'remita',
|
|
27
|
+
Korapay: 'korapay',
|
|
28
|
+
Paga: 'paga',
|
|
29
|
+
Moniepoint: 'moniepoint',
|
|
30
|
+
Hubtel: 'hubtel',
|
|
31
|
+
Mpesa: 'mpesa',
|
|
32
|
+
Pesapal: 'pesapal',
|
|
33
|
+
MtnMomo: 'mtn_momo',
|
|
34
|
+
AirtelMoney: 'airtel_money',
|
|
35
|
+
Yoco: 'yoco',
|
|
36
|
+
Payfast: 'payfast',
|
|
37
|
+
PeachPayments: 'peach_payments',
|
|
38
|
+
DpoPay: 'dpo_pay',
|
|
39
|
+
Stripe: 'stripe',
|
|
40
|
+
Paypal: 'paypal',
|
|
41
|
+
Adyen: 'adyen',
|
|
42
|
+
Square: 'square',
|
|
43
|
+
CheckoutCom: 'checkout_com',
|
|
44
|
+
Shopify: 'shopify',
|
|
45
|
+
Woocommerce: 'woocommerce',
|
|
46
|
+
Custom: 'custom',
|
|
47
|
+
};
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Typed errors (SPEC section 5). Every error extends {@link ClikgateError}.
|
|
3
|
+
*
|
|
4
|
+
* @example
|
|
5
|
+
* import { Clikgate, RateLimitError, InvalidRequestError } from '@clikgate/node';
|
|
6
|
+
* try {
|
|
7
|
+
* await clikgate.goals.send('account_opened', { reference: 'APP-55231', value: '2000000' });
|
|
8
|
+
* } catch (err) {
|
|
9
|
+
* if (err instanceof RateLimitError) console.log('retry in', err.retryAfter, 's');
|
|
10
|
+
* else if (err instanceof InvalidRequestError) console.log(err.code, err.param);
|
|
11
|
+
* else throw err;
|
|
12
|
+
* }
|
|
13
|
+
*/
|
|
14
|
+
/** Error codes with documented meaning (SPEC section 5). Other codes can appear; `code` is a plain string. */
|
|
15
|
+
export type KnownErrorCode = 'invalid_goal_key' | 'invalid_reference' | 'invalid_value' | 'click_id_and_code' | 'batch_too_large' | 'batch_empty' | 'invalid_argument' | 'invalid_click_id' | 'queue_full' | 'client_closed' | 'missing_api_key' | 'invalid_api_key' | 'invalid_option' | 'network_error' | 'timeout' | 'unexpected_status' | 'rate_limit_exceeded' | 'private_mode_field_rejected' | 'link_locked' | 'idempotency_key_reused' | 'idempotency_request_in_progress' | 'goal_archived' | 'goal_not_found' | 'value_required' | 'value_not_allowed' | 'domain_mode_mismatch' | 'https_required' | 'destination_not_allowlisted' | 'test_destination_not_allowed' | 'test_link_limit_reached' | 'plan_limit_reached' | 'plan_upgrade_required' | 'plan_feature_unavailable' | 'feature_disabled' | 'invalid_provider' | 'unknown_provider' | 'code_not_supported' | 'payment_goal_needs_confirmation' | 'unknown_goal' | 'cli_scope' | 'missing_signature' | 'malformed_signature' | 'timestamp_outside_tolerance' | 'no_matching_signature' | 'invalid_payload' | 'server_only' | 'invalid_customer_id' | 'missing_identity_secret' | 'invalid_identity_secrets';
|
|
16
|
+
/** Fields every Clikgate error carries. */
|
|
17
|
+
export interface ClikgateErrorInit {
|
|
18
|
+
message: string;
|
|
19
|
+
code: string;
|
|
20
|
+
httpStatus?: number | null;
|
|
21
|
+
requestId?: string | null;
|
|
22
|
+
param?: string | null;
|
|
23
|
+
type?: string | null;
|
|
24
|
+
raw?: unknown;
|
|
25
|
+
}
|
|
26
|
+
/** Base class of every error the SDK throws. */
|
|
27
|
+
export declare class ClikgateError extends Error {
|
|
28
|
+
/** Stable machine-readable code, e.g. `invalid_value`, `link_locked`, `network_error`. */
|
|
29
|
+
readonly code: string;
|
|
30
|
+
/** HTTP status, or `null` for local, network and timeout errors. */
|
|
31
|
+
readonly httpStatus: number | null;
|
|
32
|
+
/** The request ID (`req_…`) to quote to Clikgate support, when the API answered. */
|
|
33
|
+
readonly requestId: string | null;
|
|
34
|
+
/** The request field the error is about, when there is one. */
|
|
35
|
+
readonly param: string | null;
|
|
36
|
+
/** The envelope `type` (`invalid_request`, `conflict`, …), or `null` for local errors. */
|
|
37
|
+
readonly type: string | null;
|
|
38
|
+
/** The raw `error` object from the API, including extra keys such as `required_plan`. */
|
|
39
|
+
readonly raw: unknown;
|
|
40
|
+
constructor(init: ClikgateErrorInit);
|
|
41
|
+
}
|
|
42
|
+
/** Invalid client options. Thrown by the constructor, never later. */
|
|
43
|
+
export declare class ConfigurationError extends ClikgateError {
|
|
44
|
+
}
|
|
45
|
+
/** 401: the API key is missing, invalid, expired or revoked. */
|
|
46
|
+
export declare class AuthenticationError extends ClikgateError {
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* 403: missing scope, role, feature or plan (`insufficient_scope`, `plan_limit_reached`, `plan_upgrade_required`,
|
|
50
|
+
* `feature_disabled`, `test_link_limit_reached`, `cli_scope`, …).
|
|
51
|
+
*/
|
|
52
|
+
export declare class PermissionError extends ClikgateError {
|
|
53
|
+
/** On `plan_limit_reached` / `plan_upgrade_required`: the lowest plan that allows it. */
|
|
54
|
+
get requiredPlan(): string | null;
|
|
55
|
+
/** On `test_link_limit_reached`: the number of active test links allowed. */
|
|
56
|
+
get limit(): number | null;
|
|
57
|
+
}
|
|
58
|
+
/** 400, 410, 422 and other 4xx (`invalid_value`, `domain_mode_mismatch`, `test_destination_not_allowed`, …); also local validation (`httpStatus` null). */
|
|
59
|
+
export declare class InvalidRequestError extends ClikgateError {
|
|
60
|
+
/** For batch calls: the index of the event that failed local validation. */
|
|
61
|
+
index: number | null;
|
|
62
|
+
/** On `test_destination_not_allowed`: the allowed destination kinds. */
|
|
63
|
+
get allowed(): string[] | null;
|
|
64
|
+
/** On `test_destination_not_allowed`: the docs page explaining test-link destinations. */
|
|
65
|
+
get docUrl(): string | null;
|
|
66
|
+
}
|
|
67
|
+
/** Private mode refused a field (locally, before sending, or by the API). Carries the field **name** only. */
|
|
68
|
+
export declare class PrivateModeFieldRejectedError extends InvalidRequestError {
|
|
69
|
+
/** The refused field name, e.g. `metadata`. Never its value. */
|
|
70
|
+
readonly field: string;
|
|
71
|
+
constructor(init: ClikgateErrorInit & {
|
|
72
|
+
field: string;
|
|
73
|
+
});
|
|
74
|
+
}
|
|
75
|
+
/** 404. */
|
|
76
|
+
export declare class NotFoundError extends ClikgateError {
|
|
77
|
+
}
|
|
78
|
+
/** 409. */
|
|
79
|
+
export declare class ConflictError extends ClikgateError {
|
|
80
|
+
}
|
|
81
|
+
/** 409 `link_locked`: the link is locked; destination, fallback and deep-link changes are refused. */
|
|
82
|
+
export declare class LinkLockedError extends ConflictError {
|
|
83
|
+
}
|
|
84
|
+
/** 409 `idempotency_*`: the key was used with a different request, or the first request is still running. */
|
|
85
|
+
export declare class IdempotencyError extends ClikgateError {
|
|
86
|
+
}
|
|
87
|
+
/** 429. */
|
|
88
|
+
export declare class RateLimitError extends ClikgateError {
|
|
89
|
+
/** Seconds from `Retry-After`, or `null`. */
|
|
90
|
+
readonly retryAfter: number | null;
|
|
91
|
+
constructor(init: ClikgateErrorInit & {
|
|
92
|
+
retryAfter?: number | null;
|
|
93
|
+
});
|
|
94
|
+
}
|
|
95
|
+
/** 5xx, or an unexpected status (redirects are never followed). */
|
|
96
|
+
export declare class ServerError extends ClikgateError {
|
|
97
|
+
/** Seconds from `Retry-After` on a 503, or `null`. */
|
|
98
|
+
readonly retryAfter: number | null;
|
|
99
|
+
constructor(init: ClikgateErrorInit & {
|
|
100
|
+
retryAfter?: number | null;
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
/** The connection failed (DNS, refused, reset, TLS). */
|
|
104
|
+
export declare class NetworkError extends ClikgateError {
|
|
105
|
+
}
|
|
106
|
+
/** The per-attempt timeout elapsed. */
|
|
107
|
+
export declare class TimeoutError extends ClikgateError {
|
|
108
|
+
}
|
|
109
|
+
/** A webhook signature didn't verify. `code`: `missing_signature`, `malformed_signature`, `timestamp_outside_tolerance`, `no_matching_signature` or `invalid_payload`. */
|
|
110
|
+
export declare class SignatureVerificationError extends ClikgateError {
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* `createIdentityToken()` ran in a browser or a React Native app. Identity tokens are signed with
|
|
114
|
+
* your identity secret, which must stay on your server. `code`: `server_only`.
|
|
115
|
+
*/
|
|
116
|
+
export declare class ClikgateServerOnlyError extends ClikgateError {
|
|
117
|
+
}
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Typed errors (SPEC section 5). Every error extends {@link ClikgateError}.
|
|
4
|
+
*
|
|
5
|
+
* @example
|
|
6
|
+
* import { Clikgate, RateLimitError, InvalidRequestError } from '@clikgate/node';
|
|
7
|
+
* try {
|
|
8
|
+
* await clikgate.goals.send('account_opened', { reference: 'APP-55231', value: '2000000' });
|
|
9
|
+
* } catch (err) {
|
|
10
|
+
* if (err instanceof RateLimitError) console.log('retry in', err.retryAfter, 's');
|
|
11
|
+
* else if (err instanceof InvalidRequestError) console.log(err.code, err.param);
|
|
12
|
+
* else throw err;
|
|
13
|
+
* }
|
|
14
|
+
*/
|
|
15
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
16
|
+
exports.ClikgateServerOnlyError = exports.SignatureVerificationError = exports.TimeoutError = exports.NetworkError = exports.ServerError = exports.RateLimitError = exports.IdempotencyError = exports.LinkLockedError = exports.ConflictError = exports.NotFoundError = exports.PrivateModeFieldRejectedError = exports.InvalidRequestError = exports.PermissionError = exports.AuthenticationError = exports.ConfigurationError = exports.ClikgateError = void 0;
|
|
17
|
+
exports.retryAfterMs = retryAfterMs;
|
|
18
|
+
exports.errorFromResponse = errorFromResponse;
|
|
19
|
+
exports.errorFromBatchItem = errorFromBatchItem;
|
|
20
|
+
exports.localError = localError;
|
|
21
|
+
/** Base class of every error the SDK throws. */
|
|
22
|
+
class ClikgateError extends Error {
|
|
23
|
+
/** Stable machine-readable code, e.g. `invalid_value`, `link_locked`, `network_error`. */
|
|
24
|
+
code;
|
|
25
|
+
/** HTTP status, or `null` for local, network and timeout errors. */
|
|
26
|
+
httpStatus;
|
|
27
|
+
/** The request ID (`req_…`) to quote to Clikgate support, when the API answered. */
|
|
28
|
+
requestId;
|
|
29
|
+
/** The request field the error is about, when there is one. */
|
|
30
|
+
param;
|
|
31
|
+
/** The envelope `type` (`invalid_request`, `conflict`, …), or `null` for local errors. */
|
|
32
|
+
type;
|
|
33
|
+
/** The raw `error` object from the API, including extra keys such as `required_plan`. */
|
|
34
|
+
raw;
|
|
35
|
+
constructor(init) {
|
|
36
|
+
super(init.message);
|
|
37
|
+
this.name = new.target.name;
|
|
38
|
+
this.code = init.code;
|
|
39
|
+
this.httpStatus = init.httpStatus ?? null;
|
|
40
|
+
this.requestId = init.requestId ?? null;
|
|
41
|
+
this.param = init.param ?? null;
|
|
42
|
+
this.type = init.type ?? null;
|
|
43
|
+
this.raw = init.raw ?? null;
|
|
44
|
+
Object.setPrototypeOf(this, new.target.prototype);
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
exports.ClikgateError = ClikgateError;
|
|
48
|
+
/** Invalid client options. Thrown by the constructor, never later. */
|
|
49
|
+
class ConfigurationError extends ClikgateError {
|
|
50
|
+
}
|
|
51
|
+
exports.ConfigurationError = ConfigurationError;
|
|
52
|
+
/** 401: the API key is missing, invalid, expired or revoked. */
|
|
53
|
+
class AuthenticationError extends ClikgateError {
|
|
54
|
+
}
|
|
55
|
+
exports.AuthenticationError = AuthenticationError;
|
|
56
|
+
const rawField = (raw, key) => (raw && typeof raw === 'object' ? raw[key] : undefined);
|
|
57
|
+
/**
|
|
58
|
+
* 403: missing scope, role, feature or plan (`insufficient_scope`, `plan_limit_reached`, `plan_upgrade_required`,
|
|
59
|
+
* `feature_disabled`, `test_link_limit_reached`, `cli_scope`, …).
|
|
60
|
+
*/
|
|
61
|
+
class PermissionError extends ClikgateError {
|
|
62
|
+
/** On `plan_limit_reached` / `plan_upgrade_required`: the lowest plan that allows it. */
|
|
63
|
+
get requiredPlan() {
|
|
64
|
+
const v = rawField(this.raw, 'required_plan');
|
|
65
|
+
return typeof v === 'string' ? v : null;
|
|
66
|
+
}
|
|
67
|
+
/** On `test_link_limit_reached`: the number of active test links allowed. */
|
|
68
|
+
get limit() {
|
|
69
|
+
const v = rawField(this.raw, 'limit');
|
|
70
|
+
return typeof v === 'number' ? v : null;
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
exports.PermissionError = PermissionError;
|
|
74
|
+
/** 400, 410, 422 and other 4xx (`invalid_value`, `domain_mode_mismatch`, `test_destination_not_allowed`, …); also local validation (`httpStatus` null). */
|
|
75
|
+
class InvalidRequestError extends ClikgateError {
|
|
76
|
+
/** For batch calls: the index of the event that failed local validation. */
|
|
77
|
+
index = null;
|
|
78
|
+
/** On `test_destination_not_allowed`: the allowed destination kinds. */
|
|
79
|
+
get allowed() {
|
|
80
|
+
const v = rawField(this.raw, 'allowed');
|
|
81
|
+
return Array.isArray(v) ? v.map(String) : null;
|
|
82
|
+
}
|
|
83
|
+
/** On `test_destination_not_allowed`: the docs page explaining test-link destinations. */
|
|
84
|
+
get docUrl() {
|
|
85
|
+
const v = rawField(this.raw, 'doc_url');
|
|
86
|
+
return typeof v === 'string' ? v : null;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
exports.InvalidRequestError = InvalidRequestError;
|
|
90
|
+
/** Private mode refused a field (locally, before sending, or by the API). Carries the field **name** only. */
|
|
91
|
+
class PrivateModeFieldRejectedError extends InvalidRequestError {
|
|
92
|
+
/** The refused field name, e.g. `metadata`. Never its value. */
|
|
93
|
+
field;
|
|
94
|
+
constructor(init) {
|
|
95
|
+
super(init);
|
|
96
|
+
this.field = init.field;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
exports.PrivateModeFieldRejectedError = PrivateModeFieldRejectedError;
|
|
100
|
+
/** 404. */
|
|
101
|
+
class NotFoundError extends ClikgateError {
|
|
102
|
+
}
|
|
103
|
+
exports.NotFoundError = NotFoundError;
|
|
104
|
+
/** 409. */
|
|
105
|
+
class ConflictError extends ClikgateError {
|
|
106
|
+
}
|
|
107
|
+
exports.ConflictError = ConflictError;
|
|
108
|
+
/** 409 `link_locked`: the link is locked; destination, fallback and deep-link changes are refused. */
|
|
109
|
+
class LinkLockedError extends ConflictError {
|
|
110
|
+
}
|
|
111
|
+
exports.LinkLockedError = LinkLockedError;
|
|
112
|
+
/** 409 `idempotency_*`: the key was used with a different request, or the first request is still running. */
|
|
113
|
+
class IdempotencyError extends ClikgateError {
|
|
114
|
+
}
|
|
115
|
+
exports.IdempotencyError = IdempotencyError;
|
|
116
|
+
/** 429. */
|
|
117
|
+
class RateLimitError extends ClikgateError {
|
|
118
|
+
/** Seconds from `Retry-After`, or `null`. */
|
|
119
|
+
retryAfter;
|
|
120
|
+
constructor(init) {
|
|
121
|
+
super(init);
|
|
122
|
+
this.retryAfter = init.retryAfter ?? null;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
exports.RateLimitError = RateLimitError;
|
|
126
|
+
/** 5xx, or an unexpected status (redirects are never followed). */
|
|
127
|
+
class ServerError extends ClikgateError {
|
|
128
|
+
/** Seconds from `Retry-After` on a 503, or `null`. */
|
|
129
|
+
retryAfter;
|
|
130
|
+
constructor(init) {
|
|
131
|
+
super(init);
|
|
132
|
+
this.retryAfter = init.retryAfter ?? null;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
exports.ServerError = ServerError;
|
|
136
|
+
/** The connection failed (DNS, refused, reset, TLS). */
|
|
137
|
+
class NetworkError extends ClikgateError {
|
|
138
|
+
}
|
|
139
|
+
exports.NetworkError = NetworkError;
|
|
140
|
+
/** The per-attempt timeout elapsed. */
|
|
141
|
+
class TimeoutError extends ClikgateError {
|
|
142
|
+
}
|
|
143
|
+
exports.TimeoutError = TimeoutError;
|
|
144
|
+
/** A webhook signature didn't verify. `code`: `missing_signature`, `malformed_signature`, `timestamp_outside_tolerance`, `no_matching_signature` or `invalid_payload`. */
|
|
145
|
+
class SignatureVerificationError extends ClikgateError {
|
|
146
|
+
}
|
|
147
|
+
exports.SignatureVerificationError = SignatureVerificationError;
|
|
148
|
+
/**
|
|
149
|
+
* `createIdentityToken()` ran in a browser or a React Native app. Identity tokens are signed with
|
|
150
|
+
* your identity secret, which must stay on your server. `code`: `server_only`.
|
|
151
|
+
*/
|
|
152
|
+
class ClikgateServerOnlyError extends ClikgateError {
|
|
153
|
+
}
|
|
154
|
+
exports.ClikgateServerOnlyError = ClikgateServerOnlyError;
|
|
155
|
+
const SNIPPET = 200;
|
|
156
|
+
// eslint-disable-next-line no-control-regex
|
|
157
|
+
const CONTROL = /[\u0000-\u001f\u007f]/g;
|
|
158
|
+
const stripControl = (t) => t.replace(CONTROL, ' ');
|
|
159
|
+
function retryAfterSeconds(headers, nowMs) {
|
|
160
|
+
const v = headers['retry-after'];
|
|
161
|
+
if (v === undefined)
|
|
162
|
+
return null;
|
|
163
|
+
const s = v.trim();
|
|
164
|
+
if (/^\d+$/.test(s))
|
|
165
|
+
return Number(s);
|
|
166
|
+
const t = Date.parse(s);
|
|
167
|
+
if (Number.isNaN(t))
|
|
168
|
+
return null;
|
|
169
|
+
return Math.max(0, Math.ceil((t - nowMs) / 1000));
|
|
170
|
+
}
|
|
171
|
+
/** @internal Parse `Retry-After` in milliseconds, or null when absent or unparseable. */
|
|
172
|
+
function retryAfterMs(headers, nowMs) {
|
|
173
|
+
const v = headers['retry-after'];
|
|
174
|
+
if (v === undefined)
|
|
175
|
+
return null;
|
|
176
|
+
const s = v.trim();
|
|
177
|
+
if (/^\d+$/.test(s))
|
|
178
|
+
return Number(s) * 1000;
|
|
179
|
+
const t = Date.parse(s);
|
|
180
|
+
if (Number.isNaN(t))
|
|
181
|
+
return null;
|
|
182
|
+
return Math.max(0, t - nowMs);
|
|
183
|
+
}
|
|
184
|
+
const str = (v) => (typeof v === 'string' ? v : null);
|
|
185
|
+
/** @internal Map an HTTP response to a typed error (SPEC 5, rules 3-13). */
|
|
186
|
+
function errorFromResponse(status, headers, body, nowMs) {
|
|
187
|
+
const text = new TextDecoder().decode(body);
|
|
188
|
+
let envelope = null;
|
|
189
|
+
let refusal = null;
|
|
190
|
+
try {
|
|
191
|
+
const parsed = JSON.parse(text);
|
|
192
|
+
if (parsed && typeof parsed === 'object' && 'error' in parsed) {
|
|
193
|
+
const e = parsed.error;
|
|
194
|
+
if (e && typeof e === 'object')
|
|
195
|
+
envelope = e;
|
|
196
|
+
}
|
|
197
|
+
else if (isRefusalBody(parsed)) {
|
|
198
|
+
refusal = parsed;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
catch {
|
|
202
|
+
envelope = null;
|
|
203
|
+
}
|
|
204
|
+
const requestId = str(envelope?.request_id) ?? headers['x-request-id'] ?? null;
|
|
205
|
+
const code = str(envelope?.code) ?? str(refusal?.reason) ?? (status >= 300 && status < 400 ? 'unexpected_status' : `http_${status}`);
|
|
206
|
+
const message = str(envelope?.message) ?? `HTTP ${status}${text ? `: ${stripControl(text.slice(0, SNIPPET))}` : ''}`;
|
|
207
|
+
const init = {
|
|
208
|
+
message,
|
|
209
|
+
code: status >= 300 && status < 400 ? 'unexpected_status' : code,
|
|
210
|
+
httpStatus: status,
|
|
211
|
+
requestId,
|
|
212
|
+
param: str(envelope?.param),
|
|
213
|
+
type: str(envelope?.type),
|
|
214
|
+
raw: envelope ?? refusal,
|
|
215
|
+
};
|
|
216
|
+
const retryAfter = retryAfterSeconds(headers, nowMs);
|
|
217
|
+
if (status === 429)
|
|
218
|
+
return new RateLimitError({ ...init, code: str(envelope?.code) ?? 'rate_limit_exceeded', retryAfter });
|
|
219
|
+
if (status >= 500)
|
|
220
|
+
return new ServerError({ ...init, retryAfter });
|
|
221
|
+
if (init.code === 'private_mode_field_rejected')
|
|
222
|
+
return new PrivateModeFieldRejectedError({ ...init, field: init.param ?? 'unknown' });
|
|
223
|
+
if (status === 401)
|
|
224
|
+
return new AuthenticationError(init);
|
|
225
|
+
if (status === 403)
|
|
226
|
+
return new PermissionError(init);
|
|
227
|
+
if (status === 404)
|
|
228
|
+
return new NotFoundError(init);
|
|
229
|
+
if (status === 409 && (init.type === 'idempotency' || init.code.startsWith('idempotency_')))
|
|
230
|
+
return new IdempotencyError(init);
|
|
231
|
+
if (status === 409 && init.code === 'link_locked')
|
|
232
|
+
return new LinkLockedError(init);
|
|
233
|
+
if (status === 409)
|
|
234
|
+
return new ConflictError(init);
|
|
235
|
+
if (status >= 400)
|
|
236
|
+
return new InvalidRequestError(init);
|
|
237
|
+
return new ServerError({ ...init, retryAfter: null });
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* A goal refusal answered as a result body instead of an error envelope (`422 {status: "refused", reason:
|
|
241
|
+
* "unknown_goal", ...}`): the reason is the error code.
|
|
242
|
+
*/
|
|
243
|
+
function isRefusalBody(v) {
|
|
244
|
+
if (!v || typeof v !== 'object' || Array.isArray(v))
|
|
245
|
+
return false;
|
|
246
|
+
const o = v;
|
|
247
|
+
return o.status === 'refused' && typeof o.reason === 'string' && o.reason !== '';
|
|
248
|
+
}
|
|
249
|
+
/** @internal Map a batch item's `{status, error}` to a typed error. */
|
|
250
|
+
function errorFromBatchItem(status, error) {
|
|
251
|
+
const body = new TextEncoder().encode(JSON.stringify({ error: error ?? {} }));
|
|
252
|
+
return errorFromResponse(status, {}, body, Date.now());
|
|
253
|
+
}
|
|
254
|
+
/** @internal A local validation error (no HTTP request was made). */
|
|
255
|
+
function localError(code, message, param = null) {
|
|
256
|
+
return new InvalidRequestError({ message, code, param, httpStatus: null });
|
|
257
|
+
}
|
|
@@ -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;
|