@klappay/types 1.1.1 → 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/README.md +4 -4
- package/dist/index.d.mts +178 -1041
- package/dist/index.d.ts +178 -1041
- package/dist/index.js +133 -449
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +131 -410
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -20,28 +20,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
|
|
|
20
20
|
// src/index.ts
|
|
21
21
|
var index_exports = {};
|
|
22
22
|
__export(index_exports, {
|
|
23
|
-
|
|
23
|
+
API_KEY_SCOPES: () => API_KEY_SCOPES,
|
|
24
24
|
AcceptedPaymentSchema: () => AcceptedPaymentSchema,
|
|
25
|
-
|
|
26
|
-
ApiKeySchema: () => ApiKeySchema,
|
|
27
|
-
AuthResponseSchema: () => AuthResponseSchema,
|
|
25
|
+
ApiKeyScopeSchema: () => ApiKeyScopeSchema,
|
|
28
26
|
CHARGE_ACCEPTED_PAYMENTS_MAX: () => CHARGE_ACCEPTED_PAYMENTS_MAX,
|
|
29
27
|
CHARGE_AMOUNT_MAX: () => CHARGE_AMOUNT_MAX,
|
|
30
28
|
CHARGE_EXPIRES_IN_MAX_SECONDS: () => CHARGE_EXPIRES_IN_MAX_SECONDS,
|
|
31
29
|
CHARGE_EXPIRES_IN_MIN_SECONDS: () => CHARGE_EXPIRES_IN_MIN_SECONDS,
|
|
32
30
|
CapabilitiesSchema: () => CapabilitiesSchema,
|
|
33
|
-
ChangeEmailSchema: () => ChangeEmailSchema,
|
|
34
|
-
ChangeNameSchema: () => ChangeNameSchema,
|
|
35
|
-
ChangePasswordSchema: () => ChangePasswordSchema,
|
|
36
|
-
ChargeModeSchema: () => ChargeModeSchema,
|
|
37
31
|
ChargeSchema: () => ChargeSchema,
|
|
38
32
|
ChargeStatusSchema: () => ChargeStatusSchema,
|
|
39
33
|
ChargeWebhookEventTypeSchema: () => ChargeWebhookEventTypeSchema,
|
|
40
34
|
ChargesDateFieldSchema: () => ChargesDateFieldSchema,
|
|
41
35
|
ChargesMetricFieldSchema: () => ChargesMetricFieldSchema,
|
|
42
36
|
ChargesQueryFieldSchema: () => ChargesQueryFieldSchema,
|
|
43
|
-
ConfirmEmailChangeSchema: () => ConfirmEmailChangeSchema,
|
|
44
|
-
CreateApiKeySchema: () => CreateApiKeySchema,
|
|
45
37
|
CreateChargeSchema: () => CreateChargeSchema,
|
|
46
38
|
CreateWebhookSchema: () => CreateWebhookSchema,
|
|
47
39
|
DistributionsDateFieldSchema: () => DistributionsDateFieldSchema,
|
|
@@ -51,64 +43,40 @@ __export(index_exports, {
|
|
|
51
43
|
EVM_NETWORKS: () => EVM_NETWORKS,
|
|
52
44
|
EnvironmentSchema: () => EnvironmentSchema,
|
|
53
45
|
ErrorPayloadSchema: () => ErrorPayloadSchema,
|
|
54
|
-
ForgotPasswordSchema: () => ForgotPasswordSchema,
|
|
55
46
|
GetChargeQrCodeQuerySchema: () => GetChargeQrCodeQuerySchema,
|
|
56
|
-
GetPublicChargeQrCodeQuerySchema: () => GetPublicChargeQrCodeQuerySchema,
|
|
57
|
-
GetPublicChargeQuerySchema: () => GetPublicChargeQuerySchema,
|
|
58
47
|
HealthSchema: () => HealthSchema,
|
|
59
|
-
InvitationSchema: () => InvitationSchema,
|
|
60
|
-
InviteUserSchema: () => InviteUserSchema,
|
|
61
|
-
ListApiKeysSchema: () => ListApiKeysSchema,
|
|
62
48
|
ListChargesSchema: () => ListChargesSchema,
|
|
63
|
-
ListOrganizationsSchema: () => ListOrganizationsSchema,
|
|
64
|
-
ListUsersSchema: () => ListUsersSchema,
|
|
65
49
|
ListWebhookDeliveriesSchema: () => ListWebhookDeliveriesSchema,
|
|
66
50
|
ListenPendingDistributionsQuerySchema: () => ListenPendingDistributionsQuerySchema,
|
|
67
|
-
LoginSchema: () => LoginSchema,
|
|
68
51
|
MAX_METRICS_QUERY_DATE_RANGE_DAYS: () => MAX_METRICS_QUERY_DATE_RANGE_DAYS,
|
|
69
52
|
METRICS_QUERY_DEFAULT_ROW_LIMIT: () => METRICS_QUERY_DEFAULT_ROW_LIMIT,
|
|
70
53
|
METRICS_QUERY_MAX_FILTERS: () => METRICS_QUERY_MAX_FILTERS,
|
|
71
54
|
METRICS_QUERY_MAX_GROUP_BY: () => METRICS_QUERY_MAX_GROUP_BY,
|
|
72
55
|
METRICS_QUERY_MAX_METRICS: () => METRICS_QUERY_MAX_METRICS,
|
|
73
56
|
METRICS_QUERY_MAX_ROW_LIMIT: () => METRICS_QUERY_MAX_ROW_LIMIT,
|
|
74
|
-
MessageResponseSchema: () => MessageResponseSchema,
|
|
75
57
|
MetricsAggregationSchema: () => MetricsAggregationSchema,
|
|
76
58
|
MetricsDateGranularitySchema: () => MetricsDateGranularitySchema,
|
|
77
59
|
MetricsFilterOperatorSchema: () => MetricsFilterOperatorSchema,
|
|
78
60
|
MetricsQueryResultRowSchema: () => MetricsQueryResultRowSchema,
|
|
79
61
|
MetricsQueryResultSchema: () => MetricsQueryResultSchema,
|
|
80
62
|
MetricsQuerySchema: () => MetricsQuerySchema,
|
|
81
|
-
MetricsQueryScopeSchema: () => MetricsQueryScopeSchema,
|
|
82
63
|
MetricsResourceSchema: () => MetricsResourceSchema,
|
|
83
64
|
NETWORK_EXPLORERS: () => NETWORK_EXPLORERS,
|
|
84
65
|
NETWORK_LABELS: () => NETWORK_LABELS,
|
|
85
66
|
NetworkSchema: () => NetworkSchema,
|
|
86
|
-
NonChargeTriggerableEventSchema: () => NonChargeTriggerableEventSchema,
|
|
87
|
-
NormalizedEmailSchema: () => NormalizedEmailSchema,
|
|
88
67
|
OPERATIONAL_NETWORKS: () => OPERATIONAL_NETWORKS,
|
|
89
|
-
OrganizationSchema: () => OrganizationSchema,
|
|
90
|
-
OrganizationWithRoleSchema: () => OrganizationWithRoleSchema,
|
|
91
68
|
PAGINATION_LIMIT_DEFAULT: () => PAGINATION_LIMIT_DEFAULT,
|
|
92
69
|
PAGINATION_LIMIT_MAX: () => PAGINATION_LIMIT_MAX,
|
|
93
70
|
PAGINATION_LIMIT_MIN: () => PAGINATION_LIMIT_MIN,
|
|
94
|
-
PaginatedApiKeysSchema: () => PaginatedApiKeysSchema,
|
|
95
71
|
PaginatedChargesSchema: () => PaginatedChargesSchema,
|
|
96
|
-
PaginatedOrganizationsSchema: () => PaginatedOrganizationsSchema,
|
|
97
72
|
PaginatedPendingDistributionsSchema: () => PaginatedPendingDistributionsSchema,
|
|
98
|
-
PaginatedUsersSchema: () => PaginatedUsersSchema,
|
|
99
73
|
PaginatedWebhookDeliveriesSchema: () => PaginatedWebhookDeliveriesSchema,
|
|
100
74
|
PaginationQuerySchema: () => PaginationQuerySchema,
|
|
101
75
|
PendingDistributionEventSchema: () => PendingDistributionEventSchema,
|
|
102
76
|
PendingDistributionRecipientSchema: () => PendingDistributionRecipientSchema,
|
|
103
77
|
PendingDistributionSchema: () => PendingDistributionSchema,
|
|
104
|
-
PublicChargeSchema: () => PublicChargeSchema,
|
|
105
|
-
ResetPasswordSchema: () => ResetPasswordSchema,
|
|
106
|
-
SandboxEventTriggerSchema: () => SandboxEventTriggerSchema,
|
|
107
78
|
SandboxTriggerSchema: () => SandboxTriggerSchema,
|
|
108
|
-
SecurityWebhookEventTypeSchema: () => SecurityWebhookEventTypeSchema,
|
|
109
|
-
SelfUserSchema: () => SelfUserSchema,
|
|
110
79
|
SettlementStatusSchema: () => SettlementStatusSchema,
|
|
111
|
-
SignupSchema: () => SignupSchema,
|
|
112
80
|
SplitDistributionStatusSchema: () => SplitDistributionStatusSchema,
|
|
113
81
|
TOKEN_ADDRESSES: () => TOKEN_ADDRESSES,
|
|
114
82
|
TOKEN_DECIMALS: () => TOKEN_DECIMALS,
|
|
@@ -120,11 +88,6 @@ __export(index_exports, {
|
|
|
120
88
|
TransactionsMetricFieldSchema: () => TransactionsMetricFieldSchema,
|
|
121
89
|
TransactionsQueryFieldSchema: () => TransactionsQueryFieldSchema,
|
|
122
90
|
TriggerableChargeEventSchema: () => TriggerableChargeEventSchema,
|
|
123
|
-
UpdateOrganizationSchema: () => UpdateOrganizationSchema,
|
|
124
|
-
UpdateUserRoleSchema: () => UpdateUserRoleSchema,
|
|
125
|
-
UserRoleSchema: () => UserRoleSchema,
|
|
126
|
-
UserSchema: () => UserSchema,
|
|
127
|
-
VerifyEmailSchema: () => VerifyEmailSchema,
|
|
128
91
|
WEBHOOK_EVENTS_WILDCARD: () => WEBHOOK_EVENTS_WILDCARD,
|
|
129
92
|
WEBHOOK_EVENT_CATEGORIES: () => WEBHOOK_EVENT_CATEGORIES,
|
|
130
93
|
WebhookCategorySchema: () => WebhookCategorySchema,
|
|
@@ -144,7 +107,7 @@ var import_zod = require("zod");
|
|
|
144
107
|
var ErrorPayloadSchema = import_zod.z.object({
|
|
145
108
|
error: import_zod.z.object({
|
|
146
109
|
code: import_zod.z.string().describe(
|
|
147
|
-
"A stable, machine-readable error identifier (e.g. `validation_error`, `
|
|
110
|
+
"A stable, machine-readable error identifier (e.g. `validation_error`, `charge_not_found`)."
|
|
148
111
|
),
|
|
149
112
|
message: import_zod.z.string().describe(
|
|
150
113
|
"Human-readable explanation, safe to log or show a developer \u2014 not meant for end users."
|
|
@@ -159,9 +122,27 @@ var EnvironmentSchema = import_zod2.z.enum(["live", "test"]).describe(
|
|
|
159
122
|
"`live` or `test`, matching the `klap_live_.../klap_test_...` prefix of the API key that created or is scoped to this resource. `live` settles on Base mainnet with real funds; `test` settles on Base Sepolia, a separate testnet \u2014 real on-chain activity, but never real money."
|
|
160
123
|
);
|
|
161
124
|
|
|
162
|
-
// src/
|
|
125
|
+
// src/api-key-scopes.ts
|
|
163
126
|
var import_zod3 = require("zod");
|
|
164
|
-
var
|
|
127
|
+
var ApiKeyScopeSchema = import_zod3.z.enum([
|
|
128
|
+
"charges:read",
|
|
129
|
+
"charges:write",
|
|
130
|
+
"webhooks:read",
|
|
131
|
+
"webhooks:write",
|
|
132
|
+
"webhooks:manage_secret",
|
|
133
|
+
"metrics:read",
|
|
134
|
+
"metrics:charges:read",
|
|
135
|
+
"metrics:transactions:read",
|
|
136
|
+
"metrics:distributions:read",
|
|
137
|
+
"sandbox:trigger"
|
|
138
|
+
]).describe(
|
|
139
|
+
"What an API key is allowed to do, independent of `tenantId`/`environment` (which scope *whose* data, not *what actions*). A key with none of these can still authenticate but every scoped route rejects it with `403 insufficient_scope`. `metrics:read` alone grants every metrics resource; `metrics:{resource}:read` grants only that one \u2014 a key can hold either or both."
|
|
140
|
+
);
|
|
141
|
+
var API_KEY_SCOPES = ApiKeyScopeSchema.options;
|
|
142
|
+
|
|
143
|
+
// src/networks.ts
|
|
144
|
+
var import_zod4 = require("zod");
|
|
145
|
+
var NetworkSchema = import_zod4.z.enum(["base", "optimism", "polygon", "ethereum", "arbitrum", "avalanche", "bnb"]).describe("The blockchain a charge/payment is on.");
|
|
165
146
|
var NETWORK_LABELS = {
|
|
166
147
|
base: "Base",
|
|
167
148
|
optimism: "Optimism",
|
|
@@ -200,29 +181,29 @@ var OPERATIONAL_NETWORKS = [
|
|
|
200
181
|
];
|
|
201
182
|
|
|
202
183
|
// src/pagination.ts
|
|
203
|
-
var
|
|
184
|
+
var import_zod5 = require("zod");
|
|
204
185
|
var PAGINATION_LIMIT_MIN = 1;
|
|
205
186
|
var PAGINATION_LIMIT_MAX = 100;
|
|
206
187
|
var PAGINATION_LIMIT_DEFAULT = 20;
|
|
207
|
-
var PaginationQuerySchema =
|
|
208
|
-
limit:
|
|
188
|
+
var PaginationQuerySchema = import_zod5.z.object({
|
|
189
|
+
limit: import_zod5.z.coerce.number().min(PAGINATION_LIMIT_MIN).max(PAGINATION_LIMIT_MAX).default(PAGINATION_LIMIT_DEFAULT).describe(
|
|
209
190
|
`Max items to return per page (${PAGINATION_LIMIT_MIN}\u2013${PAGINATION_LIMIT_MAX}, default ${PAGINATION_LIMIT_DEFAULT}).`
|
|
210
191
|
),
|
|
211
|
-
cursor:
|
|
192
|
+
cursor: import_zod5.z.string().max(500).optional().describe(
|
|
212
193
|
"Opaque \u2014 pass the previous response's `nextCursor` verbatim to fetch the next page. Never construct or parse this value yourself; its shape is not part of the public contract and may change."
|
|
213
194
|
)
|
|
214
195
|
});
|
|
215
196
|
function paginatedSchema(itemSchema) {
|
|
216
|
-
return
|
|
217
|
-
data:
|
|
218
|
-
nextCursor:
|
|
219
|
-
hasMore:
|
|
197
|
+
return import_zod5.z.object({
|
|
198
|
+
data: import_zod5.z.array(itemSchema),
|
|
199
|
+
nextCursor: import_zod5.z.string().nullable().describe("Pass as `cursor` to fetch the next page. `null` when there are no more results."),
|
|
200
|
+
hasMore: import_zod5.z.boolean()
|
|
220
201
|
});
|
|
221
202
|
}
|
|
222
203
|
|
|
223
204
|
// src/tokens.ts
|
|
224
|
-
var
|
|
225
|
-
var TokenSchema =
|
|
205
|
+
var import_zod6 = require("zod");
|
|
206
|
+
var TokenSchema = import_zod6.z.enum(["USDC", "USDT"]).describe(
|
|
226
207
|
`Which stablecoin the payer will send. Support depends on both \`network\` and \`environment\` \u2014 not every token/network/environment combination is deployed; today, both \`USDC\` and \`USDT\` are deployed on every operational network's \`live\` side except BNB Chain (\`${OPERATIONAL_NETWORKS.join(", ")}\`), but \`test\` coverage varies per network \u2014 Base, Optimism, and Ethereum each have a \`test\` environment (\`USDC\` only; none has an official Sepolia USDT), Arbitrum, Polygon, Avalanche, and BNB Chain have none yet (0xSplits hasn't deployed on Arbitrum Sepolia and has no Polygon, Avalanche Fuji, or BNB testnet support at all). An unconfigured combination is rejected with \`422 token_not_supported\`, not silently accepted. **BNB Chain's \`USDC\` address is Binance-Peg USDC, not an official Circle deployment** \u2014 Circle does not issue native USDC on BNB Chain at all; this is a Binance-custodied, 1:1-pegged BEP-20 token, a materially different trust model than every other \`TOKEN_ADDRESSES\` entry (all verified directly against their real issuer). Accepted at the payer's own risk \u2014 Klappay does not verify or guarantee Binance's collateral backing it. \`USDT\` on BNB Chain is Tether's own official issuance, same trust model as everywhere else. More tokens/networks are expected to be added over time \u2014 check \`TOKEN_ADDRESSES\` in \`@klappay/types\` (or a future \`GET /v1/networks\` capabilities endpoint) for the exact current matrix rather than assuming full coverage.`
|
|
227
208
|
);
|
|
228
209
|
var TOKEN_DECIMALS = 6;
|
|
@@ -257,30 +238,27 @@ var TOKEN_ADDRESSES = {
|
|
|
257
238
|
};
|
|
258
239
|
|
|
259
240
|
// src/charges.ts
|
|
260
|
-
var
|
|
261
|
-
var ChargeStatusSchema =
|
|
262
|
-
"Payment progress, from the payer side. `pending`: created, nothing received yet. `partially_paid`: some funds received, less than `amount`. `confirmed`: full amount received (or more \u2014 see `isOverpaid`). `expired`: `expiresAt` passed with zero funds received. `underpaid`: `expiresAt` passed while `partially_paid`.
|
|
241
|
+
var import_zod7 = require("zod");
|
|
242
|
+
var ChargeStatusSchema = import_zod7.z.enum(["pending", "partially_paid", "confirmed", "expired", "underpaid"]).describe(
|
|
243
|
+
"Payment progress, from the payer side. `pending`: created, nothing received yet. `partially_paid`: some funds received, less than `amount`. `confirmed`: full amount received (or more \u2014 see `isOverpaid`). `expired`: `expiresAt` passed with zero funds received. `underpaid`: `expiresAt` passed while `partially_paid`. Every status is reached automatically, on its own timeline \u2014 there is no merchant-initiated cancellation. This never reflects whether funds actually reached the merchant \u2014 see `settlementStatus` for that."
|
|
263
244
|
);
|
|
264
|
-
var SettlementStatusSchema =
|
|
245
|
+
var SettlementStatusSchema = import_zod7.z.enum(["pending", "completed", "failed"]).describe(
|
|
265
246
|
"Progress of the payout to the merchant's wallet, a separate step from `status` \u2014 `status: confirmed` only means the payment was detected on-chain, not that the merchant has been paid yet. `pending`: payment detected, payout not yet attempted. `completed`: the merchant's wallet has the funds. `failed`: the payout attempt failed and retries were exhausted (rare; contact support). `null` on the parent `Charge` means no payout has been attempted yet \u2014 nothing has been received, or the charge is still in progress."
|
|
266
247
|
);
|
|
267
|
-
var ChargeModeSchema = import_zod6.z.enum(["standard", "continuous"]).describe(
|
|
268
|
-
"`standard` (default): the usual lifecycle \u2014 accumulates transfers toward one resolution (`confirmed`/`expired`/`underpaid`), settles once. `continuous`: never resolves \u2014 `status` stays `pending` for the charge's entire life, and every credited transfer settles independently instead of accumulating toward one confirmation (see `charge.contribution_received`/`charge.contribution_settled`). Requires both `amount` and `expiresIn` to be omitted \u2014 there's no goal to accumulate toward and no deadline for something meant to run indefinitely (a link in a creator's bio, a permanent collection address). Not inferred from omitting those two fields \u2014 an explicit, deliberate choice, since silently changing a charge's entire settlement lifecycle based on which optional fields happened to be left out would be a footgun."
|
|
269
|
-
);
|
|
270
248
|
var CHARGE_EXPIRES_IN_MIN_SECONDS = 60;
|
|
271
|
-
var CHARGE_EXPIRES_IN_MAX_SECONDS =
|
|
249
|
+
var CHARGE_EXPIRES_IN_MAX_SECONDS = 3600;
|
|
272
250
|
var CHARGE_ACCEPTED_PAYMENTS_MAX = 14;
|
|
273
|
-
var AcceptedPaymentSchema =
|
|
251
|
+
var AcceptedPaymentSchema = import_zod7.z.object({
|
|
274
252
|
token: TokenSchema,
|
|
275
253
|
network: NetworkSchema
|
|
276
254
|
});
|
|
277
|
-
var AcceptedPaymentsSchema =
|
|
255
|
+
var AcceptedPaymentsSchema = import_zod7.z.array(AcceptedPaymentSchema).min(1, "At least one accepted payment is required.").max(CHARGE_ACCEPTED_PAYMENTS_MAX).superRefine((pairs, ctx) => {
|
|
278
256
|
const seen = /* @__PURE__ */ new Set();
|
|
279
257
|
pairs.forEach((pair, index) => {
|
|
280
258
|
const key = `${pair.token}:${pair.network}`;
|
|
281
259
|
if (seen.has(key)) {
|
|
282
260
|
ctx.addIssue({
|
|
283
|
-
code:
|
|
261
|
+
code: import_zod7.z.ZodIssueCode.custom,
|
|
284
262
|
message: `Duplicate accepted payment: ${pair.token} on ${pair.network}.`,
|
|
285
263
|
path: [index]
|
|
286
264
|
});
|
|
@@ -288,7 +266,7 @@ var AcceptedPaymentsSchema = import_zod6.z.array(AcceptedPaymentSchema).min(1, "
|
|
|
288
266
|
seen.add(key);
|
|
289
267
|
if (!OPERATIONAL_NETWORKS.includes(pair.network)) {
|
|
290
268
|
ctx.addIssue({
|
|
291
|
-
code:
|
|
269
|
+
code: import_zod7.z.ZodIssueCode.custom,
|
|
292
270
|
message: `Network "${pair.network}" isn't live yet \u2014 only ${OPERATIONAL_NETWORKS.join(", ")} today.`,
|
|
293
271
|
path: [index, "network"]
|
|
294
272
|
});
|
|
@@ -298,88 +276,70 @@ var AcceptedPaymentsSchema = import_zod6.z.array(AcceptedPaymentSchema).min(1, "
|
|
|
298
276
|
`Every \`(token, network)\` pair the payer is allowed to pay with \u2014 at least one, up to ${CHARGE_ACCEPTED_PAYMENTS_MAX}. This list is also the only restriction knob: the payer can use any combination of the pairs listed here, and every transfer on one of them is credited and sums toward the charge total (see \`paidWith\`) \u2014 e.g. a charge accepting USDC and USDT can be confirmed by $9 in USDC plus $1 in USDT, or by USDC arriving on two different accepted networks. To require payment in one specific token on one specific network, list only that single pair \u2014 a transfer on any pair not in this list is still recorded (for audit) but never credited. Each network must be live (see \`GET /v1/networks\` for the current matrix) \u2014 an unconfigured \`(token, network)\` combination for your environment is rejected with \`422 token_not_supported\`.`
|
|
299
277
|
);
|
|
300
278
|
var CHARGE_AMOUNT_MAX = 999999999999;
|
|
301
|
-
var CreateChargeSchema =
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
"Amount to charge, in `currency` units (e.g. `49.9` = $49.90) \u2014 up to 6 decimal places; anything more precise is silently truncated. Omit entirely for a charge that accepts any amount \u2014 the first credited transfer of any size confirms it, and `isOverpaid` never applies (there is no target to exceed)."
|
|
279
|
+
var CreateChargeSchema = import_zod7.z.object({
|
|
280
|
+
amount: import_zod7.z.number().positive().max(CHARGE_AMOUNT_MAX).describe(
|
|
281
|
+
"Amount to charge, in `currency` units (e.g. `49.9` = $49.90) \u2014 up to 6 decimal places; anything more precise is silently truncated. Required \u2014 every charge has a target amount, the first credited transfer that reaches it confirms the charge."
|
|
305
282
|
),
|
|
306
|
-
currency:
|
|
283
|
+
currency: import_zod7.z.literal("USD").default("USD").describe("Always `USD` today \u2014 the only supported currency."),
|
|
307
284
|
acceptedPayments: AcceptedPaymentsSchema,
|
|
308
|
-
expiresIn:
|
|
309
|
-
"Seconds, not minutes or milliseconds \u2014 how long the charge stays open, min 60, max
|
|
285
|
+
expiresIn: import_zod7.z.number().int().min(CHARGE_EXPIRES_IN_MIN_SECONDS).max(CHARGE_EXPIRES_IN_MAX_SECONDS).describe(
|
|
286
|
+
"Seconds, not minutes or milliseconds \u2014 how long the charge stays open before it expires. Required, min 60, max 3600 (60 minutes) \u2014 sized off the slowest chain Klappay supports today (Ethereum mainnet, where a safely-confirmed transfer takes up to ~15 minutes), leaving real margin for payer-side delay (gas spikes, wallet friction) on top of that. Cannot be extended or shortened after creation."
|
|
310
287
|
),
|
|
311
|
-
idempotencyKey:
|
|
312
|
-
"Scoped to your
|
|
288
|
+
idempotencyKey: import_zod7.z.string().min(1).max(255).optional().describe(
|
|
289
|
+
"Scoped to your tenant. Replaying the same key returns the original charge unchanged instead of creating a duplicate \u2014 safe to retry a request after a timeout without double-charging."
|
|
313
290
|
),
|
|
314
|
-
externalRef:
|
|
291
|
+
externalRef: import_zod7.z.string().min(1).max(255).optional().describe(
|
|
315
292
|
"An opaque correlation id from your own system (e.g. an order id) \u2014 echoed back on the charge and in every webhook payload. Not interpreted or validated by Klappay."
|
|
316
293
|
),
|
|
317
|
-
source:
|
|
294
|
+
source: import_zod7.z.string().min(1).max(64).optional().describe(
|
|
318
295
|
'Free-form label for what created this charge (e.g. `"checkout"`, `"invoice"`) \u2014 useful if you create charges from more than one flow and want to tell them apart later. Not a fixed enum; use whatever values make sense to you.'
|
|
319
296
|
),
|
|
320
|
-
metadata:
|
|
321
|
-
}).superRefine((input, ctx) => {
|
|
322
|
-
if (input.mode === "continuous" && (input.amount !== void 0 || input.expiresIn !== void 0)) {
|
|
323
|
-
ctx.addIssue({
|
|
324
|
-
code: import_zod6.z.ZodIssueCode.custom,
|
|
325
|
-
message: 'mode: "continuous" requires both amount and expiresIn to be omitted.',
|
|
326
|
-
path: ["mode"]
|
|
327
|
-
});
|
|
328
|
-
}
|
|
297
|
+
metadata: import_zod7.z.record(import_zod7.z.string(), import_zod7.z.unknown()).optional().describe("Arbitrary key/value data to attach to the charge, returned as-is on every read.")
|
|
329
298
|
});
|
|
330
|
-
var ChargeSchema =
|
|
331
|
-
id:
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
"
|
|
335
|
-
),
|
|
336
|
-
amountReceived: import_zod6.z.number().nullable().describe(
|
|
337
|
-
"Cumulative amount actually received on-chain so far, in `currency` units (up to 6 decimal places). `null` until the first transfer arrives. Can exceed `amount` \u2014 see `isOverpaid` \u2014 unless `amount` itself is `null`, in which case `isOverpaid` never applies."
|
|
299
|
+
var ChargeSchema = import_zod7.z.object({
|
|
300
|
+
id: import_zod7.z.string().describe("Klappay-generated id, e.g. `ch_...`. Use this to look up the charge later."),
|
|
301
|
+
amount: import_zod7.z.number().describe("The amount originally requested, in `currency` units (up to 6 decimal places)."),
|
|
302
|
+
amountReceived: import_zod7.z.number().nullable().describe(
|
|
303
|
+
"Cumulative amount actually received on-chain so far, in `currency` units (up to 6 decimal places). `null` until the first transfer arrives. Can exceed `amount` \u2014 see `isOverpaid`."
|
|
338
304
|
),
|
|
339
|
-
isOverpaid:
|
|
305
|
+
isOverpaid: import_zod7.z.boolean().describe(
|
|
340
306
|
"`true` if `amountReceived` ended up greater than `amount`. Klappay never refunds the difference automatically \u2014 see the docs for why."
|
|
341
307
|
),
|
|
342
|
-
currency:
|
|
343
|
-
acceptedPayments:
|
|
308
|
+
currency: import_zod7.z.string().describe("Always `USD` today \u2014 the only supported currency."),
|
|
309
|
+
acceptedPayments: import_zod7.z.array(AcceptedPaymentSchema).describe(
|
|
344
310
|
"Every `(token, network)` pair this charge was configured to accept, unchanged after creation."
|
|
345
311
|
),
|
|
346
|
-
paidWith:
|
|
312
|
+
paidWith: import_zod7.z.array(AcceptedPaymentSchema).describe(
|
|
347
313
|
"Every distinct `(token, network)` pair that has actually contributed a credited transfer so far \u2014 empty until the first one arrives. Can hold more than one entry: a charge accepting several pairs can be paid across a combination of them, and every entry here sums toward `amountReceived`."
|
|
348
314
|
),
|
|
349
|
-
address:
|
|
315
|
+
address: import_zod7.z.string().describe(
|
|
350
316
|
"The on-chain address the payer must send funds to \u2014 identical across every accepted network (0xSplits addresses are chain-agnostic). Unique per charge, predicted at creation time \u2014 funds sent here go directly to the merchant, Klappay never custodies them."
|
|
351
317
|
),
|
|
352
318
|
status: ChargeStatusSchema,
|
|
353
319
|
settlementStatus: SettlementStatusSchema.nullable(),
|
|
354
320
|
environment: EnvironmentSchema,
|
|
355
|
-
apiKeyId:
|
|
321
|
+
apiKeyId: import_zod7.z.string().nullable().describe(
|
|
356
322
|
"Which of your API keys created this charge. `null` for a charge created before this field existed."
|
|
357
323
|
),
|
|
358
|
-
txHash:
|
|
324
|
+
txHash: import_zod7.z.string().nullable().describe(
|
|
359
325
|
"Transaction hash of the most recent transfer detected for this charge. `null` until a payment is detected."
|
|
360
326
|
),
|
|
361
|
-
externalRef:
|
|
362
|
-
source:
|
|
363
|
-
metadata:
|
|
364
|
-
createdAt:
|
|
365
|
-
expiresAt:
|
|
366
|
-
"When this charge stops accepting payment, if still `pending`/`partially_paid` by then.
|
|
327
|
+
externalRef: import_zod7.z.string().nullable(),
|
|
328
|
+
source: import_zod7.z.string().nullable(),
|
|
329
|
+
metadata: import_zod7.z.record(import_zod7.z.string(), import_zod7.z.unknown()).nullable(),
|
|
330
|
+
createdAt: import_zod7.z.string().datetime(),
|
|
331
|
+
expiresAt: import_zod7.z.string().datetime().describe(
|
|
332
|
+
"When this charge stops accepting payment, if still `pending`/`partially_paid` by then."
|
|
367
333
|
),
|
|
368
|
-
confirmedAt:
|
|
369
|
-
settledAt:
|
|
334
|
+
confirmedAt: import_zod7.z.string().datetime().nullable().describe("When `status` first reached `confirmed`. `null` until then."),
|
|
335
|
+
settledAt: import_zod7.z.string().datetime().nullable().describe(
|
|
370
336
|
"When `settlementStatus` first reached `completed` \u2014 the merchant's wallet actually has the funds. `null` until then, including while `settlementStatus` is `pending`/`failed`."
|
|
371
337
|
),
|
|
372
|
-
lastActivityAt:
|
|
373
|
-
"When a transfer was last credited toward this charge, or `createdAt` if none has arrived yet.
|
|
374
|
-
),
|
|
375
|
-
pausedAt: import_zod6.z.string().datetime().nullable().describe(
|
|
376
|
-
"Only ever set for a charge with no `expiresAt`: `null` means Klappay is actively watching this address in real time (the normal case). A timestamp means no contribution arrived for longer than the inactivity window (90 days for a charge with a goal `amount`, 365 days for one without), so real-time watching was stopped \u2014 the charge itself is never closed, a transfer can still arrive and land, just detected on a much slower fallback poll instead of instantly. Clears automatically (and real-time watching resumes) the moment that happens."
|
|
377
|
-
),
|
|
378
|
-
canceledAt: import_zod6.z.string().datetime().nullable().describe(
|
|
379
|
-
"When `POST /v1/charges/{id}/cancel` was called. `null` unless `status` is `canceled`. Unlike `pausedAt`, this never clears automatically \u2014 real-time watching is stopped the same way, but a transfer landing afterward doesn't revert the charge to `pending`; it fires `charge.paid_after_cancel` instead, since resuming silently would contradict the merchant's explicit cancellation."
|
|
338
|
+
lastActivityAt: import_zod7.z.string().datetime().describe(
|
|
339
|
+
"When a transfer was last credited toward this charge, or `createdAt` if none has arrived yet."
|
|
380
340
|
)
|
|
381
341
|
});
|
|
382
|
-
var ListChargesSchema =
|
|
342
|
+
var ListChargesSchema = import_zod7.z.object({
|
|
383
343
|
status: ChargeStatusSchema.optional(),
|
|
384
344
|
token: TokenSchema.optional().describe(
|
|
385
345
|
"Filters on `paidWith.token` \u2014 the pair actually paid, not accepted."
|
|
@@ -388,55 +348,19 @@ var ListChargesSchema = import_zod6.z.object({
|
|
|
388
348
|
"Filters on `paidWith.network` \u2014 the pair actually paid, not accepted."
|
|
389
349
|
),
|
|
390
350
|
environment: EnvironmentSchema.optional(),
|
|
391
|
-
since:
|
|
351
|
+
since: import_zod7.z.string().datetime().optional().describe(
|
|
392
352
|
"Only return charges created at or after this timestamp (filters on `createdAt`, not on when the status last changed). If polling as a fallback for missed webhooks, use a window at least as wide as the longest `expiresIn` your charges use, or you can miss a long-lived charge that changed status outside a narrower window."
|
|
393
353
|
),
|
|
394
|
-
isOverpaid:
|
|
354
|
+
isOverpaid: import_zod7.z.enum(["true", "false"]).transform((v) => v === "true").optional()
|
|
395
355
|
}).extend(PaginationQuerySchema.shape);
|
|
396
356
|
var PaginatedChargesSchema = paginatedSchema(ChargeSchema);
|
|
397
|
-
var GetChargeQrCodeQuerySchema =
|
|
357
|
+
var GetChargeQrCodeQuerySchema = import_zod7.z.object({
|
|
398
358
|
token: TokenSchema.optional().describe(
|
|
399
359
|
"Which accepted `(token, network)` pair to encode in the QR \u2014 required if `acceptedPayments` has more than one pair, since there is no single unambiguous default to fall back to. Ignored (and unnecessary) when the charge accepts exactly one pair."
|
|
400
360
|
),
|
|
401
361
|
network: NetworkSchema.optional()
|
|
402
362
|
});
|
|
403
363
|
|
|
404
|
-
// src/public-charges.ts
|
|
405
|
-
var import_zod7 = require("zod");
|
|
406
|
-
var PublicChargeSchema = import_zod7.z.object({
|
|
407
|
-
id: import_zod7.z.string(),
|
|
408
|
-
mode: ChargeModeSchema,
|
|
409
|
-
status: ChargeStatusSchema,
|
|
410
|
-
settlementStatus: SettlementStatusSchema.nullable(),
|
|
411
|
-
amount: import_zod7.z.number().nullable(),
|
|
412
|
-
amountReceived: import_zod7.z.number().nullable(),
|
|
413
|
-
isOverpaid: import_zod7.z.boolean(),
|
|
414
|
-
currency: import_zod7.z.string(),
|
|
415
|
-
acceptedPayments: import_zod7.z.array(AcceptedPaymentSchema),
|
|
416
|
-
paidWith: import_zod7.z.array(AcceptedPaymentSchema),
|
|
417
|
-
address: import_zod7.z.string(),
|
|
418
|
-
environment: EnvironmentSchema,
|
|
419
|
-
txHash: import_zod7.z.string().nullable(),
|
|
420
|
-
metadata: import_zod7.z.record(import_zod7.z.unknown()).nullable().describe(
|
|
421
|
-
"Redacted \u2014 everything the merchant put in `Charge.metadata` is stripped except the reserved `klappay` key (for Klappay-internal product integrations, e.g. this endpoint's own checkout consumer), if present. `null` if there's no `klappay` key, even when the merchant's own metadata is otherwise non-empty."
|
|
422
|
-
),
|
|
423
|
-
createdAt: import_zod7.z.string().datetime(),
|
|
424
|
-
expiresAt: import_zod7.z.string().datetime().nullable(),
|
|
425
|
-
confirmedAt: import_zod7.z.string().datetime().nullable(),
|
|
426
|
-
settledAt: import_zod7.z.string().datetime().nullable(),
|
|
427
|
-
lastActivityAt: import_zod7.z.string().datetime(),
|
|
428
|
-
pausedAt: import_zod7.z.string().datetime().nullable(),
|
|
429
|
-
canceledAt: import_zod7.z.string().datetime().nullable()
|
|
430
|
-
});
|
|
431
|
-
var GetPublicChargeQuerySchema = import_zod7.z.object({
|
|
432
|
-
environment: EnvironmentSchema.describe(
|
|
433
|
-
"Which environment this charge is expected to be in. Required, not inferred \u2014 there's no API key here to derive it from, and stating it explicitly catches an integration bug (e.g. a `test` chargeId reaching a `live` checkout flow) instead of silently trusting whatever environment the id happens to belong to. A mismatch is indistinguishable from the charge not existing at all (`404`), same anti-enumeration posture as every other case below."
|
|
434
|
-
)
|
|
435
|
-
});
|
|
436
|
-
var GetPublicChargeQrCodeQuerySchema = GetPublicChargeQuerySchema.extend(
|
|
437
|
-
GetChargeQrCodeQuerySchema.shape
|
|
438
|
-
);
|
|
439
|
-
|
|
440
364
|
// src/distributions.ts
|
|
441
365
|
var import_zod8 = require("zod");
|
|
442
366
|
var SplitDistributionStatusSchema = import_zod8.z.enum(["pending", "processing", "completed", "failed"]).describe(
|
|
@@ -492,11 +416,11 @@ var MetricsAggregationSchema = import_zod9.z.enum(["count", "sum", "avg", "min",
|
|
|
492
416
|
var MetricsFilterOperatorSchema = import_zod9.z.enum(["eq", "neq", "in", "gt", "gte", "lt", "lte"]).describe(
|
|
493
417
|
"`in` expects an array value (max 50 entries); every other operator expects a single scalar."
|
|
494
418
|
);
|
|
495
|
-
var MetricsDateGranularitySchema = import_zod9.z.enum(["day", "week", "month"]).describe(
|
|
419
|
+
var MetricsDateGranularitySchema = import_zod9.z.enum(["day", "week", "month", "year"]).describe(
|
|
496
420
|
"Bucket width for a `date_bucket` `groupBy` entry \u2014 Postgres `date_trunc` semantics (UTC)."
|
|
497
421
|
);
|
|
498
422
|
var metricsQueryEnvironmentSchema = EnvironmentSchema.describe(
|
|
499
|
-
"Which environment's data to query \u2014 `live` or `test`.
|
|
423
|
+
"Which environment's data to query \u2014 `live` or `test`. Must match the environment of the API key used to authenticate \u2014 scopes the query to charges/transactions/distributions created under a `live` or `test` API key respectively."
|
|
500
424
|
);
|
|
501
425
|
var MAX_METRICS_QUERY_DATE_RANGE_DAYS = 366;
|
|
502
426
|
var METRICS_QUERY_MAX_ROW_LIMIT = 1e3;
|
|
@@ -529,14 +453,14 @@ var orderBySchema = import_zod9.z.object({
|
|
|
529
453
|
var limitSchema = import_zod9.z.number().int().min(1).max(METRICS_QUERY_MAX_ROW_LIMIT).default(METRICS_QUERY_DEFAULT_ROW_LIMIT).describe(
|
|
530
454
|
`Max rows to return, ${1}\u2013${METRICS_QUERY_MAX_ROW_LIMIT}, default ${METRICS_QUERY_DEFAULT_ROW_LIMIT}. If more rows matched, \`meta.truncated\` is \`true\` on the response \u2014 narrow the query instead of just raising this.`
|
|
531
455
|
);
|
|
532
|
-
var ChargesQueryFieldSchema = import_zod9.z.enum(["status", "
|
|
533
|
-
"A `Charge` field to filter or group by \u2014 see `ChargeStatusSchema
|
|
456
|
+
var ChargesQueryFieldSchema = import_zod9.z.enum(["status", "source", "apiKeyId", "currency", "isOverpaid", "externalRef"]).describe(
|
|
457
|
+
"A `Charge` field to filter or group by \u2014 see `ChargeStatusSchema` for `status`'s own possible values (charges.md). `source`/`externalRef` are free-form strings your own integration set at creation, not a fixed enum."
|
|
534
458
|
);
|
|
535
459
|
var ChargesMetricFieldSchema = import_zod9.z.enum(["amount", "amountReceived", "feePercent"]).describe(
|
|
536
460
|
"A `Charge` numeric field to aggregate. `amount`/`amountReceived` are decimal currency amounts (requested vs. actually received \u2014 see `charges.md`). `feePercent` is the platform fee frozen on the charge at creation, e.g. `1.5` means 1.5%."
|
|
537
461
|
);
|
|
538
|
-
var ChargesDateFieldSchema = import_zod9.z.enum(["createdAt", "confirmedAt", "lastActivityAt"]).describe(
|
|
539
|
-
"A `Charge` timestamp to filter/bucket by. `confirmedAt` is `null` until the charge reaches `confirmed` \u2014 a `dateRange`/`date_bucket` on it implicitly excludes every charge that never confirmed."
|
|
462
|
+
var ChargesDateFieldSchema = import_zod9.z.enum(["createdAt", "confirmedAt", "lastActivityAt", "expiresAt"]).describe(
|
|
463
|
+
"A `Charge` timestamp to filter/bucket by. `confirmedAt` is `null` until the charge reaches `confirmed` \u2014 a `dateRange`/`date_bucket` on it implicitly excludes every charge that never confirmed. `expiresAt` is always present (set at creation), useful for e.g. finding charges expiring soon or measuring how close to expiry charges typically resolve."
|
|
540
464
|
);
|
|
541
465
|
var ChargesFilterSchema = import_zod9.z.object({
|
|
542
466
|
field: ChargesQueryFieldSchema,
|
|
@@ -607,14 +531,14 @@ var TransactionsMetricsQuerySchema = import_zod9.z.object({
|
|
|
607
531
|
orderBy: orderBySchema.optional(),
|
|
608
532
|
limit: limitSchema
|
|
609
533
|
});
|
|
610
|
-
var DistributionsQueryFieldSchema = import_zod9.z.enum(["status", "network", "token"]).describe(
|
|
611
|
-
"A `SplitDistribution` field to filter or group by \u2014 see `SplitDistributionStatusSchema`/`NetworkSchema`/`TokenSchema` for their possible values."
|
|
534
|
+
var DistributionsQueryFieldSchema = import_zod9.z.enum(["status", "network", "token", "distributorAddress"]).describe(
|
|
535
|
+
"A `SplitDistribution` field to filter or group by \u2014 see `SplitDistributionStatusSchema`/`NetworkSchema`/`TokenSchema` for their possible values. `distributorAddress` is the public on-chain address that actually called `distribute()` for a `completed` distribution \u2014 Klappay's own operator address if settled by Klappay's own worker, a community keeper's address if settled externally (or `null` on the rare case that lookup failed), `null` for every non-`completed` status."
|
|
612
536
|
);
|
|
613
537
|
var DistributionsMetricFieldSchema = import_zod9.z.enum(["attempts"]).describe(
|
|
614
538
|
"How many times a payout was attempted for this settlement so far \u2014 incremented on every attempt, whether it succeeded or is being retried after failing. A high `attempts` alongside `status: 'failed'` means every automatic retry was exhausted."
|
|
615
539
|
);
|
|
616
|
-
var DistributionsDateFieldSchema = import_zod9.z.enum(["createdAt", "completedAt"]).describe(
|
|
617
|
-
"`createdAt`: when this settlement was queued. `completedAt`: when it actually paid out \u2014 `null` until `status` reaches `completed`, so a `dateRange`/`date_bucket` on it implicitly excludes every distribution still pending/processing/failed."
|
|
540
|
+
var DistributionsDateFieldSchema = import_zod9.z.enum(["createdAt", "processingStartedAt", "completedAt"]).describe(
|
|
541
|
+
"`createdAt`: when this settlement was queued. `processingStartedAt`: when a worker began its most recent attempt at the payout \u2014 `null` until the first attempt, then overwritten on every subsequent retry, so it reflects the *latest* attempt's start, not the first. `completedAt`: when it actually paid out \u2014 `null` until `status` reaches `completed`, so a `dateRange`/`date_bucket` on it implicitly excludes every distribution still pending/processing/failed."
|
|
618
542
|
);
|
|
619
543
|
var DistributionsFilterSchema = import_zod9.z.object({
|
|
620
544
|
field: DistributionsQueryFieldSchema,
|
|
@@ -711,15 +635,11 @@ var MetricsQueryResultRowSchema = import_zod9.z.record(
|
|
|
711
635
|
import_zod9.z.string(),
|
|
712
636
|
import_zod9.z.union([import_zod9.z.string(), import_zod9.z.number(), import_zod9.z.boolean(), import_zod9.z.null()])
|
|
713
637
|
);
|
|
714
|
-
var MetricsQueryScopeSchema = import_zod9.z.enum(["owner_admin", "member"]).describe(
|
|
715
|
-
"`member`: results were automatically restricted to data tied to API keys you personally created \u2014 rows with no resolvable creator were excluded, not counted, and not surfaced any other way. `owner_admin`: the full organization\u2019s data was queried, no restriction applied."
|
|
716
|
-
);
|
|
717
638
|
var MetricsQueryResultSchema = import_zod9.z.object({
|
|
718
639
|
data: import_zod9.z.array(MetricsQueryResultRowSchema),
|
|
719
640
|
meta: import_zod9.z.object({
|
|
720
641
|
resource: MetricsResourceSchema,
|
|
721
642
|
environment: EnvironmentSchema,
|
|
722
|
-
scope: MetricsQueryScopeSchema,
|
|
723
643
|
rowCount: import_zod9.z.number().int().describe("Number of rows in `data`."),
|
|
724
644
|
truncated: import_zod9.z.boolean().describe(
|
|
725
645
|
"`true` if more rows matched than `limit` allowed \u2014 `data` holds only the first `limit`."
|
|
@@ -737,86 +657,43 @@ var ChargeWebhookEventTypeSchema = import_zod10.z.enum([
|
|
|
737
657
|
"charge.underpaid",
|
|
738
658
|
"charge.settled",
|
|
739
659
|
"charge.settlement_failed",
|
|
740
|
-
"charge.overpaid"
|
|
741
|
-
"charge.paused",
|
|
742
|
-
"charge.reactivated",
|
|
743
|
-
"charge.contribution_received",
|
|
744
|
-
"charge.contribution_settled",
|
|
745
|
-
"charge.canceled",
|
|
746
|
-
"charge.paid_after_cancel"
|
|
747
|
-
]).describe(
|
|
748
|
-
'Note the distinction between `charge.confirmed` and `charge.settled`: `confirmed` means the payment was detected on-chain; `settled` means the merchant\'s wallet actually received the funds \u2014 a separate, later step. Subscribe to `confirmed` if you only need "will I get paid," or `settled` if you need "has the money actually arrived." `charge.overpaid` fires alongside `charge.confirmed`/`charge.partially_paid` whenever the cumulative amount received ends up above `amount` (see `Charge.isOverpaid`). Every event in this category carries the full `Charge` object as `data`, except `charge.paused`/`charge.reactivated`/`charge.contribution_received`/`charge.contribution_settled`/`charge.paid_after_cancel` (see below). `charge.paused` fires when a charge with no `expiresAt` has had no contribution for longer than its inactivity window (90 days for a charge with a goal `amount`, 365 days for one without) \u2014 Klappay stops watching its address in real time, but the charge itself is never closed; `charge.reactivated` fires the moment a transfer lands on a paused charge, detected by the same fallback poller used for missed webhooks (so with much higher latency than normal \u2014 pausing trades that away deliberately, see `docs/payments.md`). `charge.contribution_received`/`charge.contribution_settled` are exclusive to `mode: continuous` charges (see `Charge.mode`) \u2014 a continuous charge never fires `charge.confirmed`/`charge.settled` at all, since `status` never leaves `pending`; instead every individual transfer fires `contribution_received` on detection and `contribution_settled` once its payout completes, one pair-scoped event per contribution instead of one event for the whole charge. `charge.canceled` fires when a merchant explicitly cancels a `pending`/`partially_paid` charge via `POST /v1/charges/{id}/cancel` \u2014 unlike every other terminal status, this one is never reached automatically. `charge.paid_after_cancel` is an anomaly signal: a transfer still landed on a canceled charge\'s address (nothing on-chain can prevent that) \u2014 `status` stays `canceled`, it is never silently resumed, and this event is your cue to manually refund the payer or honor the charge anyway. `data` for `charge.paused`: `{ chargeId, lastActivityAt, pausedAt }`; for `charge.reactivated`: `{ chargeId, reactivatedAt }`; for `charge.contribution_received`: `{ chargeId, token, network, amount, txHash, payerAddress }`; for `charge.contribution_settled`: `{ chargeId, token, network, amount, txHash, distributorAddress }`; for `charge.paid_after_cancel`: `{ chargeId, token, network, amount, txHash, payerAddress }`.'
|
|
749
|
-
);
|
|
750
|
-
var AccountWebhookEventTypeSchema = import_zod10.z.enum([
|
|
751
|
-
"payout_address.changed",
|
|
752
|
-
"api_key.created",
|
|
753
|
-
"api_key.revoked",
|
|
754
|
-
"webhook.created",
|
|
755
|
-
"webhook.deleted",
|
|
756
|
-
"webhook.secret_rotated",
|
|
757
|
-
"fee_tier.updated",
|
|
758
|
-
"member.removed",
|
|
759
|
-
"member.role_changed",
|
|
760
|
-
"member.invited"
|
|
660
|
+
"charge.overpaid"
|
|
761
661
|
]).describe(
|
|
762
|
-
|
|
662
|
+
'Note the distinction between `charge.confirmed` and `charge.settled`: `confirmed` means the payment was detected on-chain; `settled` means the merchant\'s wallet actually received the funds \u2014 a separate, later step. Subscribe to `confirmed` if you only need "will I get paid," or `settled` if you need "has the money actually arrived." `charge.overpaid` fires alongside `charge.confirmed`/`charge.partially_paid` whenever the cumulative amount received ends up above `amount` (see `Charge.isOverpaid`). Every event in this category carries the full `Charge` object as `data`.'
|
|
763
663
|
);
|
|
764
664
|
var WebhookDeliveryEventTypeSchema = import_zod10.z.enum(["webhook.delivery_failed", "webhook.delivery_recovered", "webhook.endpoint_unhealthy"]).describe(
|
|
765
665
|
"Meta-events about the health of your own webhook endpoints \u2014 useful for monitoring without polling `GET /v1/webhooks/{id}/deliveries`. `webhook.endpoint_unhealthy` fires once when a webhook's failure rate over the trailing 24h crosses 20%, and `webhook.delivery_recovered` fires once when a delivery to that webhook next succeeds. `data` for every event in this category: `{ webhookId, url, failureRatio? }` (`failureRatio` only present on `webhook.endpoint_unhealthy`)."
|
|
766
666
|
);
|
|
767
|
-
var SecurityWebhookEventTypeSchema = import_zod10.z.enum([
|
|
768
|
-
"auth.login",
|
|
769
|
-
"auth.login_failed",
|
|
770
|
-
"auth.suspicious_activity",
|
|
771
|
-
"auth.email_verified",
|
|
772
|
-
"auth.password_reset_requested",
|
|
773
|
-
"auth.password_reset_completed",
|
|
774
|
-
"auth.password_changed",
|
|
775
|
-
"auth.email_change_requested",
|
|
776
|
-
"auth.email_changed"
|
|
777
|
-
]).describe(
|
|
778
|
-
"Account security signals. `auth.suspicious_activity` is a soft heuristic (login from an IP not seen on this account before), not a block \u2014 evaluate it, not enforce against it. `auth.password_reset_requested` only ever dispatches when the requested email actually matches an account (there is nowhere to notify otherwise) \u2014 `POST /v1/auth/forgot-password` itself always returns the same generic response either way, so this event never becomes a second channel for the same enumeration question the endpoint response deliberately avoids answering. `auth.password_changed` is the self-service counterpart to `auth.password_reset_completed` \u2014 fires from `POST /v1/auth/change-password` (requires the current password) instead of the unauthenticated forgot-password flow. `auth.email_change_requested`/`auth.email_changed` are the request/complete pair for `POST /v1/auth/change-email` \u2192 `POST /v1/auth/confirm-email-change` \u2014 the change only takes effect, and `email_changed` only fires, once the confirmation link sent to the *current* address is used. `data` per event: `auth.login`: `{ userId, ipAddress }`; `auth.login_failed`: `{ email, ipAddress }`; `auth.suspicious_activity`: `{ userId, ipAddress, previousIpAddress }`; `auth.email_verified`/`auth.password_reset_requested`/`auth.password_reset_completed`/`auth.password_changed`: `{ userId, email }`; `auth.email_change_requested`: `{ userId, email, newEmail }`; `auth.email_changed`: `{ userId, previousEmail, newEmail }`."
|
|
779
|
-
);
|
|
780
667
|
var WebhookEventTypeSchema = import_zod10.z.union([
|
|
781
668
|
ChargeWebhookEventTypeSchema,
|
|
782
|
-
|
|
783
|
-
WebhookDeliveryEventTypeSchema,
|
|
784
|
-
SecurityWebhookEventTypeSchema
|
|
669
|
+
WebhookDeliveryEventTypeSchema
|
|
785
670
|
]);
|
|
786
|
-
var WebhookCategorySchema = import_zod10.z.enum(["payments", "
|
|
671
|
+
var WebhookCategorySchema = import_zod10.z.enum(["payments", "webhooks"]).describe(
|
|
787
672
|
"Subscribe to every event in a category via `eventCategories` instead of listing events one by one \u2014 new events added to a category later arrive automatically, no subscription update needed."
|
|
788
673
|
);
|
|
789
674
|
function buildCategoryMap() {
|
|
790
675
|
const map = {};
|
|
791
676
|
for (const event of ChargeWebhookEventTypeSchema.options) map[event] = "payments";
|
|
792
|
-
for (const event of AccountWebhookEventTypeSchema.options) map[event] = "account";
|
|
793
677
|
for (const event of WebhookDeliveryEventTypeSchema.options) map[event] = "webhooks";
|
|
794
|
-
for (const event of
|
|
678
|
+
for (const event of WebhookEventTypeSchema.options.flatMap((schema) => schema.options)) {
|
|
679
|
+
if (!(event in map)) {
|
|
680
|
+
throw new Error(
|
|
681
|
+
`buildCategoryMap: "${event}" has no category \u2014 a new event sub-schema was unioned into WebhookEventTypeSchema without a matching loop added here.`
|
|
682
|
+
);
|
|
683
|
+
}
|
|
684
|
+
}
|
|
795
685
|
return map;
|
|
796
686
|
}
|
|
797
687
|
var EVENT_CATEGORY_MAP = buildCategoryMap();
|
|
798
688
|
var WEBHOOK_EVENT_CATEGORIES = {
|
|
799
689
|
payments: ChargeWebhookEventTypeSchema.options,
|
|
800
|
-
|
|
801
|
-
webhooks: WebhookDeliveryEventTypeSchema.options,
|
|
802
|
-
security: SecurityWebhookEventTypeSchema.options
|
|
690
|
+
webhooks: WebhookDeliveryEventTypeSchema.options
|
|
803
691
|
};
|
|
804
692
|
var TriggerableChargeEventSchema = ChargeWebhookEventTypeSchema.exclude([
|
|
805
|
-
"charge.created"
|
|
806
|
-
"charge.paused",
|
|
807
|
-
"charge.reactivated",
|
|
808
|
-
"charge.contribution_received",
|
|
809
|
-
"charge.contribution_settled",
|
|
810
|
-
"charge.canceled",
|
|
811
|
-
"charge.paid_after_cancel"
|
|
693
|
+
"charge.created"
|
|
812
694
|
]).describe(
|
|
813
|
-
"Every charge event that represents a payment-progress state transition a sandbox charge can be pushed into \u2014 everything except `charge.created` (a charge already exists by the time you have an id to trigger against)
|
|
695
|
+
"Every charge event that represents a payment-progress state transition a sandbox charge can be pushed into \u2014 everything except `charge.created` (a charge already exists by the time you have an id to trigger against)."
|
|
814
696
|
);
|
|
815
|
-
var NonChargeTriggerableEventSchema = import_zod10.z.union([
|
|
816
|
-
AccountWebhookEventTypeSchema,
|
|
817
|
-
WebhookDeliveryEventTypeSchema,
|
|
818
|
-
SecurityWebhookEventTypeSchema
|
|
819
|
-
]);
|
|
820
697
|
|
|
821
698
|
// src/webhooks.ts
|
|
822
699
|
var import_zod11 = require("zod");
|
|
@@ -841,7 +718,7 @@ var CreateWebhookSchema = import_zod11.z.object({
|
|
|
841
718
|
var WebhookSchema = import_zod11.z.object({
|
|
842
719
|
id: import_zod11.z.string(),
|
|
843
720
|
environment: EnvironmentSchema.nullable().describe(
|
|
844
|
-
"Which environment's API key created this webhook \u2014 `live` or `test`.
|
|
721
|
+
"Which environment's API key created this webhook \u2014 `live` or `test`. Every event is only ever delivered to a webhook whose `environment` matches the event's own (or to a webhook with `environment: null`, which receives every environment \u2014 the case for every webhook created before this field existed)."
|
|
845
722
|
),
|
|
846
723
|
url: import_zod11.z.string(),
|
|
847
724
|
events: import_zod11.z.array(WebhookEventTypeSchema),
|
|
@@ -863,7 +740,7 @@ var WebhookPayloadSchema = import_zod11.z.object({
|
|
|
863
740
|
event: WebhookEventTypeSchema,
|
|
864
741
|
createdAt: import_zod11.z.string().datetime(),
|
|
865
742
|
data: import_zod11.z.unknown().describe(
|
|
866
|
-
"Event-specific data. Charge events (`charge.*`) carry the full `Charge` object;
|
|
743
|
+
"Event-specific data. Charge events (`charge.*`) carry the full `Charge` object; webhook-delivery events carry a smaller, event-specific object \u2014 see `WebhookEventDataMap`/`TypedWebhookPayload` for the exact shape per event, or docs/webhooks.md."
|
|
867
744
|
)
|
|
868
745
|
});
|
|
869
746
|
var WebhookDeliveryStatusSchema = import_zod11.z.enum(["pending", "delivered", "failed"]);
|
|
@@ -885,178 +762,27 @@ var WebhookDeliverySchema = import_zod11.z.object({
|
|
|
885
762
|
var ListWebhookDeliveriesSchema = PaginationQuerySchema;
|
|
886
763
|
var PaginatedWebhookDeliveriesSchema = paginatedSchema(WebhookDeliverySchema);
|
|
887
764
|
|
|
888
|
-
// src/api-keys.ts
|
|
889
|
-
var import_zod12 = require("zod");
|
|
890
|
-
var CreateApiKeySchema = import_zod12.z.object({
|
|
891
|
-
name: import_zod12.z.string().min(1).max(64).describe(
|
|
892
|
-
'A label to help you tell keys apart (e.g. `"production backend"`). Not used for anything functional.'
|
|
893
|
-
),
|
|
894
|
-
environment: EnvironmentSchema.describe(
|
|
895
|
-
"`live` keys move real funds on Base mainnet; `test` keys settle on Base Sepolia (a real testnet, no real money) and additionally unlock `POST /v1/sandbox/*` for simulating events with zero on-chain activity at all."
|
|
896
|
-
)
|
|
897
|
-
});
|
|
898
|
-
var ApiKeySchema = import_zod12.z.object({
|
|
899
|
-
id: import_zod12.z.string(),
|
|
900
|
-
name: import_zod12.z.string(),
|
|
901
|
-
environment: EnvironmentSchema.describe(
|
|
902
|
-
"`live` keys authenticate real charges on Base mainnet; `test` keys authenticate the same charge lifecycle on Base Sepolia (a real testnet) and additionally unlock `/v1/sandbox/*` for synthetic event simulation."
|
|
903
|
-
),
|
|
904
|
-
key: import_zod12.z.string().optional().describe(
|
|
905
|
-
"The full secret key (`klap_live_...` / `klap_test_...`), used as the `Authorization: Bearer` value on `/v1/charges`, `/v1/webhooks`, and `/v1/sandbox` requests. Present only in the response to `POST /v1/api-keys` \u2014 never returned again afterward, so store it immediately."
|
|
906
|
-
),
|
|
907
|
-
hint: import_zod12.z.string().describe(
|
|
908
|
-
"A truncated, always-safe-to-display form of the key (e.g. `klap_live_...ab12`), returned everywhere the full key isn't."
|
|
909
|
-
),
|
|
910
|
-
createdAt: import_zod12.z.string().datetime(),
|
|
911
|
-
lastUsedAt: import_zod12.z.string().datetime().nullable().describe("Updated on every successful authenticated request. `null` if never used."),
|
|
912
|
-
createdByUserId: import_zod12.z.string().nullable().describe(
|
|
913
|
-
"Which member of the organization created this key. `null` for a key created before this field existed."
|
|
914
|
-
)
|
|
915
|
-
});
|
|
916
|
-
var ListApiKeysSchema = PaginationQuerySchema;
|
|
917
|
-
var PaginatedApiKeysSchema = paginatedSchema(ApiKeySchema);
|
|
918
|
-
|
|
919
|
-
// src/users.ts
|
|
920
|
-
var import_zod13 = require("zod");
|
|
921
|
-
var UserRoleSchema = import_zod13.z.enum(["owner", "admin", "member"]).describe(
|
|
922
|
-
"`owner`: full access, and the organization must always keep at least one. `admin`: can manage `member`s but not other `admin`s. `member`: no management permissions. You can only manage a member with a strictly lower role than your own, unless you're an `owner`."
|
|
923
|
-
);
|
|
924
|
-
var UpdateUserRoleSchema = import_zod13.z.object({
|
|
925
|
-
role: UserRoleSchema
|
|
926
|
-
});
|
|
927
|
-
var UserSchema = import_zod13.z.object({
|
|
928
|
-
id: import_zod13.z.string(),
|
|
929
|
-
email: import_zod13.z.string(),
|
|
930
|
-
name: import_zod13.z.string().nullable(),
|
|
931
|
-
role: UserRoleSchema.describe("Your role within the organization this user was fetched from."),
|
|
932
|
-
emailVerifiedAt: import_zod13.z.string().datetime().nullable().describe(
|
|
933
|
-
"When this address was confirmed via the emailed verification link. `null` until then. Required (non-null) for two specific actions: creating a `live` API key (`POST /v1/api-keys`) and changing `Organization.payoutAddress` (`PATCH /v1/organization`) \u2014 everything else works regardless of verification status."
|
|
934
|
-
),
|
|
935
|
-
createdAt: import_zod13.z.string().datetime()
|
|
936
|
-
});
|
|
937
|
-
var ListUsersSchema = PaginationQuerySchema;
|
|
938
|
-
var PaginatedUsersSchema = paginatedSchema(UserSchema);
|
|
939
|
-
|
|
940
|
-
// src/auth.ts
|
|
941
|
-
var import_zod14 = require("zod");
|
|
942
|
-
var NormalizedEmailSchema = import_zod14.z.string().trim().max(255).toLowerCase().email().transform((email) => email.normalize("NFC")).describe(
|
|
943
|
-
"Trimmed, lowercased, and NFC-normalized server-side before use \u2014 case/whitespace don't matter."
|
|
944
|
-
);
|
|
945
|
-
var SignupSchema = import_zod14.z.object({
|
|
946
|
-
email: NormalizedEmailSchema,
|
|
947
|
-
password: import_zod14.z.string().min(8).max(128).describe("8-128 characters. No other complexity rule.")
|
|
948
|
-
});
|
|
949
|
-
var LoginSchema = import_zod14.z.object({
|
|
950
|
-
email: NormalizedEmailSchema,
|
|
951
|
-
password: import_zod14.z.string().min(1).max(128)
|
|
952
|
-
});
|
|
953
|
-
var VerifyEmailSchema = import_zod14.z.object({
|
|
954
|
-
token: import_zod14.z.string().min(1).describe("The token from the verification email \u2014 passed as-is, not the account email.")
|
|
955
|
-
});
|
|
956
|
-
var ForgotPasswordSchema = import_zod14.z.object({
|
|
957
|
-
email: NormalizedEmailSchema
|
|
958
|
-
});
|
|
959
|
-
var ResetPasswordSchema = import_zod14.z.object({
|
|
960
|
-
token: import_zod14.z.string().min(1).describe("The token from the password reset email."),
|
|
961
|
-
newPassword: import_zod14.z.string().min(8).max(128)
|
|
962
|
-
});
|
|
963
|
-
var MessageResponseSchema = import_zod14.z.object({
|
|
964
|
-
message: import_zod14.z.string().describe("Human-readable confirmation, safe to show a user directly.")
|
|
965
|
-
});
|
|
966
|
-
var SelfUserSchema = UserSchema.omit({ createdAt: true, role: true });
|
|
967
|
-
var AuthResponseSchema = import_zod14.z.object({
|
|
968
|
-
token: import_zod14.z.string().describe(
|
|
969
|
-
"Session JWT, valid 7 days \u2014 use as `Authorization: Bearer <token>` on every `/v1/organizations/*` request (which nests API keys, members, and invitations \u2014 see `GET /v1/organizations`). This token identifies only you; it carries no organization or role \u2014 every `/v1/organizations/{id}/*` request is authorized fresh against your actual membership in that specific organization. This is a separate credential from an API key: it authenticates a human/dashboard session, not payment operations. Create an API key with it before you can create charges."
|
|
970
|
-
),
|
|
971
|
-
user: SelfUserSchema
|
|
972
|
-
});
|
|
973
|
-
var ChangeNameSchema = import_zod14.z.object({
|
|
974
|
-
name: import_zod14.z.string().min(1).max(255).describe("Your display name.")
|
|
975
|
-
});
|
|
976
|
-
var ChangePasswordSchema = import_zod14.z.object({
|
|
977
|
-
currentPassword: import_zod14.z.string().min(1).max(128),
|
|
978
|
-
newPassword: import_zod14.z.string().min(8).max(128)
|
|
979
|
-
});
|
|
980
|
-
var ChangeEmailSchema = import_zod14.z.object({
|
|
981
|
-
currentPassword: import_zod14.z.string().min(1).max(128),
|
|
982
|
-
newEmail: NormalizedEmailSchema
|
|
983
|
-
});
|
|
984
|
-
var ConfirmEmailChangeSchema = import_zod14.z.object({
|
|
985
|
-
token: import_zod14.z.string().min(1).describe("The token from the confirmation email sent to your current address.")
|
|
986
|
-
});
|
|
987
|
-
|
|
988
|
-
// src/organization.ts
|
|
989
|
-
var import_zod15 = require("zod");
|
|
990
|
-
var UpdateOrganizationSchema = import_zod15.z.object({
|
|
991
|
-
name: import_zod15.z.string().min(1).max(255).optional().describe("The organization's display name."),
|
|
992
|
-
payoutAddress: import_zod15.z.string().regex(/^0x[a-fA-F0-9]{40}$/, "must be a valid EVM address").optional().describe(
|
|
993
|
-
"The wallet that receives the merchant's share of every future charge. Changing this only affects charges created after the change \u2014 an already-created charge's payout split is frozen from creation and is never retroactively affected. Required before you can create any charge. Any casing is accepted \u2014 EIP-55 checksum casing is not required or verified."
|
|
994
|
-
)
|
|
995
|
-
});
|
|
996
|
-
var OrganizationSchema = import_zod15.z.object({
|
|
997
|
-
id: import_zod15.z.string(),
|
|
998
|
-
name: import_zod15.z.string(),
|
|
999
|
-
payoutAddress: import_zod15.z.string().nullable().describe("`null` until configured \u2014 `POST /v1/charges` fails until this is set."),
|
|
1000
|
-
currentFeePercent: import_zod15.z.number().describe(
|
|
1001
|
-
"Your current platform fee percentage \u2014 `1.5` means 1.5%, not a 0\u20131 fraction. Funds the infrastructure Klappay runs on your behalf (on-chain monitoring, settlement, webhook delivery, support) the same way any payment processor's fee does; this is not optional or removable. Dynamic, not fixed: it's based on your trailing monthly volume, with lower volume paying a higher percentage \u2014 higher-volume organizations, or ones with a specific negotiated arrangement, can be assigned a different rate at Klappay's discretion. Frozen onto each charge at creation, so a rate change never retroactively affects a charge already created; see `feeUpdatedAt` for when it last changed. Contact Klappay if you'd like your rate reviewed."
|
|
1002
|
-
),
|
|
1003
|
-
feeUpdatedAt: import_zod15.z.string().datetime().nullable().describe(
|
|
1004
|
-
"When `currentFeePercent` last changed. `null` if it has never changed since this organization signed up."
|
|
1005
|
-
),
|
|
1006
|
-
createdAt: import_zod15.z.string().datetime()
|
|
1007
|
-
});
|
|
1008
|
-
var OrganizationWithRoleSchema = OrganizationSchema.extend({
|
|
1009
|
-
role: UserRoleSchema.describe("Your own role within this specific organization.")
|
|
1010
|
-
});
|
|
1011
|
-
var PaginatedOrganizationsSchema = paginatedSchema(OrganizationWithRoleSchema);
|
|
1012
|
-
var ListOrganizationsSchema = PaginationQuerySchema;
|
|
1013
|
-
|
|
1014
|
-
// src/invitations.ts
|
|
1015
|
-
var import_zod16 = require("zod");
|
|
1016
|
-
var InviteUserSchema = import_zod16.z.object({
|
|
1017
|
-
email: NormalizedEmailSchema,
|
|
1018
|
-
role: UserRoleSchema.default("member").describe(
|
|
1019
|
-
"The role the invitee will hold once they accept \u2014 subject to the same management-hierarchy rule as `PATCH /v1/organizations/{id}/users/{userId}`: an `admin` inviter cannot invite an `admin` or `owner`."
|
|
1020
|
-
)
|
|
1021
|
-
});
|
|
1022
|
-
var AcceptInvitationSchema = import_zod16.z.object({
|
|
1023
|
-
token: import_zod16.z.string().min(1).describe("The token from the invitation email."),
|
|
1024
|
-
password: import_zod16.z.string().min(8).max(128).optional().describe(
|
|
1025
|
-
"Required only if the invited email has no existing Klappay account \u2014 a new account is created along with the membership. Ignored if the account already exists."
|
|
1026
|
-
)
|
|
1027
|
-
});
|
|
1028
|
-
var InvitationSchema = import_zod16.z.object({
|
|
1029
|
-
id: import_zod16.z.string(),
|
|
1030
|
-
organizationId: import_zod16.z.string(),
|
|
1031
|
-
email: import_zod16.z.string(),
|
|
1032
|
-
role: UserRoleSchema,
|
|
1033
|
-
invitedByUserId: import_zod16.z.string().describe("Which member of the organization sent this invitation."),
|
|
1034
|
-
expiresAt: import_zod16.z.string().datetime(),
|
|
1035
|
-
createdAt: import_zod16.z.string().datetime()
|
|
1036
|
-
});
|
|
1037
|
-
|
|
1038
765
|
// src/timeline.ts
|
|
1039
|
-
var
|
|
1040
|
-
var TransactionSourceSchema =
|
|
766
|
+
var import_zod12 = require("zod");
|
|
767
|
+
var TransactionSourceSchema = import_zod12.z.enum(["moralis_webhook", "reconciliation_job", "sandbox"]).describe(
|
|
1041
768
|
"How this transfer was detected: `moralis_webhook` (the normal path), `reconciliation_job` (a fallback poller caught it after the webhook was missed or delayed), or `sandbox` (simulated via `POST /v1/sandbox/charges/{id}/trigger`, no real on-chain transfer)."
|
|
1042
769
|
);
|
|
1043
|
-
var TimelineEventTypeSchema =
|
|
770
|
+
var TimelineEventTypeSchema = import_zod12.z.enum([
|
|
1044
771
|
"charge.created",
|
|
1045
772
|
"charge.expired",
|
|
1046
|
-
"charge.canceled",
|
|
1047
773
|
"transaction.detected",
|
|
1048
774
|
"split.distributed",
|
|
1049
775
|
"webhook.dispatched",
|
|
1050
776
|
"webhook.delivered",
|
|
1051
777
|
"webhook.failed"
|
|
1052
778
|
]).describe(
|
|
1053
|
-
"`charge.created`: the charge was created. `charge.expired`: `expiresAt` passed with no full payment. `
|
|
779
|
+
"`charge.created`: the charge was created. `charge.expired`: `expiresAt` passed with no full payment. `transaction.detected`: a raw on-chain transfer was seen (see the `event`-shaped fields below for details \u2014 a charge can have more than one, e.g. a partial payment followed by the rest). `split.distributed`: a payout to the merchant completed on-chain, for one contributing `(token, network)` pair \u2014 a charge settled across more than one pair emits one of these per pair (see the `token`/`network` fields below). `webhook.dispatched`/`webhook.delivered`/`webhook.failed`: one specific delivery *attempt* for one webhook subscription \u2014 `failed` here means this single attempt failed, not that all retries were exhausted (see `WebhookDeliveryStatusSchema` for the exhausted-all-retries state)."
|
|
1054
780
|
);
|
|
1055
|
-
var TimelineEventSchema =
|
|
781
|
+
var TimelineEventSchema = import_zod12.z.object({
|
|
1056
782
|
type: TimelineEventTypeSchema,
|
|
1057
|
-
at:
|
|
1058
|
-
txHash:
|
|
1059
|
-
amount:
|
|
783
|
+
at: import_zod12.z.string().datetime(),
|
|
784
|
+
txHash: import_zod12.z.string().optional().describe("Present for `transaction.detected` and `split.distributed` events only."),
|
|
785
|
+
amount: import_zod12.z.number().optional().describe(
|
|
1060
786
|
"Present for `transaction.detected` events only \u2014 the amount that specific transfer carried."
|
|
1061
787
|
),
|
|
1062
788
|
source: TransactionSourceSchema.optional().describe(
|
|
@@ -1068,81 +794,68 @@ var TimelineEventSchema = import_zod17.z.object({
|
|
|
1068
794
|
network: NetworkSchema.optional().describe(
|
|
1069
795
|
"Present for `transaction.detected` and `split.distributed` events \u2014 which network this specific transfer, or settlement, used."
|
|
1070
796
|
),
|
|
1071
|
-
causedTransition:
|
|
797
|
+
causedTransition: import_zod12.z.boolean().optional().describe(
|
|
1072
798
|
"Present for `transaction.detected` events only. `true` if this specific transfer changed the charge's status (e.g. PENDING\u2192CONFIRMED) \u2014 a charge paid in installments can have more than one such event."
|
|
1073
799
|
),
|
|
1074
800
|
event: WebhookEventTypeSchema.optional().describe(
|
|
1075
801
|
"Present for `webhook.*` events only \u2014 which event type this delivery was for."
|
|
1076
802
|
),
|
|
1077
|
-
responseCode:
|
|
803
|
+
responseCode: import_zod12.z.number().nullable().optional().describe(
|
|
1078
804
|
"Present for `webhook.*` events only \u2014 HTTP status your endpoint returned, or `null` if the request never connected."
|
|
1079
805
|
),
|
|
1080
|
-
attempts:
|
|
806
|
+
attempts: import_zod12.z.number().optional().describe(
|
|
1081
807
|
"Present for `webhook.*` events only \u2014 how many delivery attempts have been made so far."
|
|
1082
808
|
)
|
|
1083
809
|
});
|
|
1084
810
|
|
|
1085
811
|
// src/health.ts
|
|
1086
|
-
var
|
|
1087
|
-
var HealthSchema =
|
|
1088
|
-
status:
|
|
812
|
+
var import_zod13 = require("zod");
|
|
813
|
+
var HealthSchema = import_zod13.z.object({
|
|
814
|
+
status: import_zod13.z.enum(["ok", "error"]).describe(
|
|
1089
815
|
"`error` when the database connectivity check fails \u2014 the HTTP status code mirrors this (503 instead of 200), so a plain uptime check (not just a JSON-aware one) still catches a DB outage."
|
|
1090
816
|
),
|
|
1091
|
-
version:
|
|
1092
|
-
timestamp:
|
|
1093
|
-
db:
|
|
1094
|
-
pendingWebhooks:
|
|
1095
|
-
oldestPendingChargeAgeSeconds:
|
|
1096
|
-
lastMoralisEventAgeSeconds:
|
|
817
|
+
version: import_zod13.z.string(),
|
|
818
|
+
timestamp: import_zod13.z.string().datetime(),
|
|
819
|
+
db: import_zod13.z.enum(["ok", "error"]).describe("Result of a real database connectivity check, not just a process-alive check."),
|
|
820
|
+
pendingWebhooks: import_zod13.z.number().describe("Count of webhook deliveries still awaiting a successful attempt."),
|
|
821
|
+
oldestPendingChargeAgeSeconds: import_zod13.z.number().nullable().describe("Age of the oldest still-unpaid charge, in seconds. `null` if there are none."),
|
|
822
|
+
lastMoralisEventAgeSeconds: import_zod13.z.number().nullable().describe(
|
|
1097
823
|
"Seconds since the last on-chain payment notification was received \u2014 a cheap signal for whether payment detection is currently working. `null` if none have ever been received."
|
|
1098
824
|
)
|
|
1099
825
|
});
|
|
1100
826
|
|
|
1101
827
|
// src/sandbox.ts
|
|
1102
|
-
var
|
|
1103
|
-
var SandboxTriggerSchema =
|
|
828
|
+
var import_zod14 = require("zod");
|
|
829
|
+
var SandboxTriggerSchema = import_zod14.z.object({
|
|
1104
830
|
event: TriggerableChargeEventSchema,
|
|
1105
|
-
amount:
|
|
831
|
+
amount: import_zod14.z.number().positive().max(CHARGE_AMOUNT_MAX).optional().describe(
|
|
1106
832
|
"Used with `charge.partially_paid` (amount to simulate as received so far \u2014 must be less than the charge amount, defaults to half of it if omitted) and with `charge.overpaid` (amount received \u2014 must be greater than the charge amount, defaults to 1.5x it if omitted). Ignored for every other event."
|
|
1107
833
|
)
|
|
1108
834
|
});
|
|
1109
|
-
var SandboxEventTriggerSchema = import_zod19.z.object({
|
|
1110
|
-
event: NonChargeTriggerableEventSchema.describe(
|
|
1111
|
-
"Any account, security, or webhook-delivery event \u2014 simulates it with synthetic data against your own webhooks, no real state change or precondition required (unlike `POST /v1/sandbox/charges/{id}/trigger`, which acts on a real charge)."
|
|
1112
|
-
)
|
|
1113
|
-
});
|
|
1114
835
|
|
|
1115
836
|
// src/capabilities.ts
|
|
1116
|
-
var
|
|
1117
|
-
var CapabilitiesSchema =
|
|
1118
|
-
acceptedPayments:
|
|
837
|
+
var import_zod15 = require("zod");
|
|
838
|
+
var CapabilitiesSchema = import_zod15.z.object({
|
|
839
|
+
acceptedPayments: import_zod15.z.array(AcceptedPaymentSchema).describe(
|
|
1119
840
|
"Every `(token, network)` pair actually configured for your environment right now \u2014 read straight from the same lookup `POST /v1/charges` validates `acceptedPayments` against, so it can never list a pair that charge creation would then reject. Use this to build a picker UI instead of hardcoding the matrix client-side."
|
|
1120
841
|
)
|
|
1121
842
|
});
|
|
1122
843
|
// Annotate the CommonJS export names for ESM import in node:
|
|
1123
844
|
0 && (module.exports = {
|
|
1124
|
-
|
|
845
|
+
API_KEY_SCOPES,
|
|
1125
846
|
AcceptedPaymentSchema,
|
|
1126
|
-
|
|
1127
|
-
ApiKeySchema,
|
|
1128
|
-
AuthResponseSchema,
|
|
847
|
+
ApiKeyScopeSchema,
|
|
1129
848
|
CHARGE_ACCEPTED_PAYMENTS_MAX,
|
|
1130
849
|
CHARGE_AMOUNT_MAX,
|
|
1131
850
|
CHARGE_EXPIRES_IN_MAX_SECONDS,
|
|
1132
851
|
CHARGE_EXPIRES_IN_MIN_SECONDS,
|
|
1133
852
|
CapabilitiesSchema,
|
|
1134
|
-
ChangeEmailSchema,
|
|
1135
|
-
ChangeNameSchema,
|
|
1136
|
-
ChangePasswordSchema,
|
|
1137
|
-
ChargeModeSchema,
|
|
1138
853
|
ChargeSchema,
|
|
1139
854
|
ChargeStatusSchema,
|
|
1140
855
|
ChargeWebhookEventTypeSchema,
|
|
1141
856
|
ChargesDateFieldSchema,
|
|
1142
857
|
ChargesMetricFieldSchema,
|
|
1143
858
|
ChargesQueryFieldSchema,
|
|
1144
|
-
ConfirmEmailChangeSchema,
|
|
1145
|
-
CreateApiKeySchema,
|
|
1146
859
|
CreateChargeSchema,
|
|
1147
860
|
CreateWebhookSchema,
|
|
1148
861
|
DistributionsDateFieldSchema,
|
|
@@ -1152,64 +865,40 @@ var CapabilitiesSchema = import_zod20.z.object({
|
|
|
1152
865
|
EVM_NETWORKS,
|
|
1153
866
|
EnvironmentSchema,
|
|
1154
867
|
ErrorPayloadSchema,
|
|
1155
|
-
ForgotPasswordSchema,
|
|
1156
868
|
GetChargeQrCodeQuerySchema,
|
|
1157
|
-
GetPublicChargeQrCodeQuerySchema,
|
|
1158
|
-
GetPublicChargeQuerySchema,
|
|
1159
869
|
HealthSchema,
|
|
1160
|
-
InvitationSchema,
|
|
1161
|
-
InviteUserSchema,
|
|
1162
|
-
ListApiKeysSchema,
|
|
1163
870
|
ListChargesSchema,
|
|
1164
|
-
ListOrganizationsSchema,
|
|
1165
|
-
ListUsersSchema,
|
|
1166
871
|
ListWebhookDeliveriesSchema,
|
|
1167
872
|
ListenPendingDistributionsQuerySchema,
|
|
1168
|
-
LoginSchema,
|
|
1169
873
|
MAX_METRICS_QUERY_DATE_RANGE_DAYS,
|
|
1170
874
|
METRICS_QUERY_DEFAULT_ROW_LIMIT,
|
|
1171
875
|
METRICS_QUERY_MAX_FILTERS,
|
|
1172
876
|
METRICS_QUERY_MAX_GROUP_BY,
|
|
1173
877
|
METRICS_QUERY_MAX_METRICS,
|
|
1174
878
|
METRICS_QUERY_MAX_ROW_LIMIT,
|
|
1175
|
-
MessageResponseSchema,
|
|
1176
879
|
MetricsAggregationSchema,
|
|
1177
880
|
MetricsDateGranularitySchema,
|
|
1178
881
|
MetricsFilterOperatorSchema,
|
|
1179
882
|
MetricsQueryResultRowSchema,
|
|
1180
883
|
MetricsQueryResultSchema,
|
|
1181
884
|
MetricsQuerySchema,
|
|
1182
|
-
MetricsQueryScopeSchema,
|
|
1183
885
|
MetricsResourceSchema,
|
|
1184
886
|
NETWORK_EXPLORERS,
|
|
1185
887
|
NETWORK_LABELS,
|
|
1186
888
|
NetworkSchema,
|
|
1187
|
-
NonChargeTriggerableEventSchema,
|
|
1188
|
-
NormalizedEmailSchema,
|
|
1189
889
|
OPERATIONAL_NETWORKS,
|
|
1190
|
-
OrganizationSchema,
|
|
1191
|
-
OrganizationWithRoleSchema,
|
|
1192
890
|
PAGINATION_LIMIT_DEFAULT,
|
|
1193
891
|
PAGINATION_LIMIT_MAX,
|
|
1194
892
|
PAGINATION_LIMIT_MIN,
|
|
1195
|
-
PaginatedApiKeysSchema,
|
|
1196
893
|
PaginatedChargesSchema,
|
|
1197
|
-
PaginatedOrganizationsSchema,
|
|
1198
894
|
PaginatedPendingDistributionsSchema,
|
|
1199
|
-
PaginatedUsersSchema,
|
|
1200
895
|
PaginatedWebhookDeliveriesSchema,
|
|
1201
896
|
PaginationQuerySchema,
|
|
1202
897
|
PendingDistributionEventSchema,
|
|
1203
898
|
PendingDistributionRecipientSchema,
|
|
1204
899
|
PendingDistributionSchema,
|
|
1205
|
-
PublicChargeSchema,
|
|
1206
|
-
ResetPasswordSchema,
|
|
1207
|
-
SandboxEventTriggerSchema,
|
|
1208
900
|
SandboxTriggerSchema,
|
|
1209
|
-
SecurityWebhookEventTypeSchema,
|
|
1210
|
-
SelfUserSchema,
|
|
1211
901
|
SettlementStatusSchema,
|
|
1212
|
-
SignupSchema,
|
|
1213
902
|
SplitDistributionStatusSchema,
|
|
1214
903
|
TOKEN_ADDRESSES,
|
|
1215
904
|
TOKEN_DECIMALS,
|
|
@@ -1221,11 +910,6 @@ var CapabilitiesSchema = import_zod20.z.object({
|
|
|
1221
910
|
TransactionsMetricFieldSchema,
|
|
1222
911
|
TransactionsQueryFieldSchema,
|
|
1223
912
|
TriggerableChargeEventSchema,
|
|
1224
|
-
UpdateOrganizationSchema,
|
|
1225
|
-
UpdateUserRoleSchema,
|
|
1226
|
-
UserRoleSchema,
|
|
1227
|
-
UserSchema,
|
|
1228
|
-
VerifyEmailSchema,
|
|
1229
913
|
WEBHOOK_EVENTS_WILDCARD,
|
|
1230
914
|
WEBHOOK_EVENT_CATEGORIES,
|
|
1231
915
|
WebhookCategorySchema,
|