@nymbalhq/contract-tests 1.4.0 → 1.5.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/dist/index.d.ts +40 -2
- package/dist/index.js +213 -15
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -139,6 +139,44 @@ interface WebhookContractOptions {
|
|
|
139
139
|
*/
|
|
140
140
|
declare function runWebhookContract(name: string, build: Build<CommerceAdapter>, options: WebhookContractOptions): void;
|
|
141
141
|
|
|
142
|
+
/** One signed delivery as the provider sends it, and the address its bounce or complaint is for. */
|
|
143
|
+
interface EmailFeedbackSample {
|
|
144
|
+
request: WebhookRequest;
|
|
145
|
+
recipient: string;
|
|
146
|
+
}
|
|
147
|
+
interface EmailFeedbackContractOptions {
|
|
148
|
+
/** A delivery of a hard bounce (the provider's permanent failure). */
|
|
149
|
+
bounce: () => EmailFeedbackSample;
|
|
150
|
+
/** A delivery of a soft bounce (a transient failure). Given, the suite checks it is classified `soft`. */
|
|
151
|
+
softBounce?: () => EmailFeedbackSample;
|
|
152
|
+
/** A delivery of a spam complaint. Given, the suite checks it is a complaint. */
|
|
153
|
+
complaint?: () => EmailFeedbackSample;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Certifies an email adapter's bounces and complaints from `receiveWebhook`: a bounce received twice is one delivery
|
|
157
|
+
* with the same events, every delivery is one the kernel's route accepts for the email slot, and each bounce and
|
|
158
|
+
* complaint is classified as the provider reported it. Run it beside `runWebhookContract`.
|
|
159
|
+
*/
|
|
160
|
+
declare function runEmailFeedbackContract(name: string, build: Build<CommerceAdapter>, options: EmailFeedbackContractOptions): void;
|
|
161
|
+
|
|
162
|
+
/** One signed delivery as the provider sends it, and the tracking number its update is for. */
|
|
163
|
+
interface ShippingTrackingSample {
|
|
164
|
+
request: WebhookRequest;
|
|
165
|
+
trackingNumber: string;
|
|
166
|
+
}
|
|
167
|
+
interface ShippingTrackingContractOptions {
|
|
168
|
+
/** A delivery of a delivered update. */
|
|
169
|
+
delivered: () => ShippingTrackingSample;
|
|
170
|
+
/** A delivery of an in-transit update. Given, the suite checks it is classified `in_transit`. */
|
|
171
|
+
inTransit?: () => ShippingTrackingSample;
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* Certifies a shipping adapter's tracking updates from `receiveWebhook`: an update received twice is one delivery with
|
|
175
|
+
* the same events, every delivery is one the kernel's route accepts for the shipping slot, and each update is
|
|
176
|
+
* classified as the carrier reported it. Run it beside `runWebhookContract`.
|
|
177
|
+
*/
|
|
178
|
+
declare function runShippingTrackingContract(name: string, build: Build<CommerceAdapter>, options: ShippingTrackingContractOptions): void;
|
|
179
|
+
|
|
142
180
|
declare function runSecurityContract(name: string, build: Build<SecurityAdapter>, options?: ContractOptions<SecurityAdapter>): void;
|
|
143
181
|
|
|
144
182
|
interface ProjectionContractOptions {
|
|
@@ -161,5 +199,5 @@ type ContractSuite = (name: string, build: Build<unknown>, options?: Record<stri
|
|
|
161
199
|
/** Each kind's suite, one for every kind in CONTRACT_KINDS. Each is typed here, at the CLI's boundary. */
|
|
162
200
|
declare const contractSuites: Partial<Record<ContractKind, ContractSuite>>;
|
|
163
201
|
|
|
164
|
-
export { BOUND_MS, adapterContext, contractSuites, matchesQuery, runAnalyticsContract, runDocumentStoreContract, runEmailContract, runEventBusContract, runMediaStorageContract, runPaymentsContract, runProjectionContract, runReviewsContract, runSearchContract, runSecurityContract, runShippingContract, runTaxContract, runWebhookContract, searchTerms, toSearchDocument };
|
|
165
|
-
export type { Build, ContractKind, ContractOptions, ContractProduct, ContractSuite, DocumentStoreContractOptions, EventBusContractOptions, MediaStorageContractOptions, PaymentsContractOptions, ProjectionContractOptions, SearchContractOptions, WebhookContractOptions, WebhookRequest };
|
|
202
|
+
export { BOUND_MS, adapterContext, contractSuites, matchesQuery, runAnalyticsContract, runDocumentStoreContract, runEmailContract, runEmailFeedbackContract, runEventBusContract, runMediaStorageContract, runPaymentsContract, runProjectionContract, runReviewsContract, runSearchContract, runSecurityContract, runShippingContract, runShippingTrackingContract, runTaxContract, runWebhookContract, searchTerms, toSearchDocument };
|
|
203
|
+
export type { Build, ContractKind, ContractOptions, ContractProduct, ContractSuite, DocumentStoreContractOptions, EmailFeedbackContractOptions, EmailFeedbackSample, EventBusContractOptions, MediaStorageContractOptions, PaymentsContractOptions, ProjectionContractOptions, SearchContractOptions, ShippingTrackingContractOptions, ShippingTrackingSample, WebhookContractOptions, WebhookRequest };
|
package/dist/index.js
CHANGED
|
@@ -2948,8 +2948,204 @@ function runWebhookContract(name, build, options) {
|
|
|
2948
2948
|
});
|
|
2949
2949
|
}
|
|
2950
2950
|
|
|
2951
|
-
// src/
|
|
2951
|
+
// src/email-feedback.ts
|
|
2952
2952
|
import { describe as describe16, expect as expect17, it as it17 } from "vitest";
|
|
2953
|
+
import {
|
|
2954
|
+
emailFeedbackProblem,
|
|
2955
|
+
emailFeedbackType,
|
|
2956
|
+
webhookDeliveryProblem as webhookDeliveryProblem2
|
|
2957
|
+
} from "@nymbalhq/types";
|
|
2958
|
+
async function receive2(adapter, request) {
|
|
2959
|
+
expect17(typeof adapter.receiveWebhook, "the adapter has no receiveWebhook").toBe("function");
|
|
2960
|
+
return adapter.receiveWebhook(request.rawBody, request.headers);
|
|
2961
|
+
}
|
|
2962
|
+
function eventsFor(delivery, type, recipient) {
|
|
2963
|
+
return delivery.events.filter((e) => e.type === type && e.payload["recipient"] === recipient);
|
|
2964
|
+
}
|
|
2965
|
+
function runEmailFeedbackContract(name, build, options) {
|
|
2966
|
+
const samples = [options.bounce, options.softBounce, options.complaint].filter(
|
|
2967
|
+
(sample) => sample !== void 0
|
|
2968
|
+
);
|
|
2969
|
+
describe16(`email feedback contract: ${name}`, () => {
|
|
2970
|
+
it17(
|
|
2971
|
+
"replay: one bounce received twice gives one deliveryId and equal events",
|
|
2972
|
+
() => using(build, async (adapter) => {
|
|
2973
|
+
const first = await receive2(adapter, options.bounce().request);
|
|
2974
|
+
const second = await receive2(adapter, options.bounce().request);
|
|
2975
|
+
expect17(first.verified, "the signed bounce was not verified").toBe(true);
|
|
2976
|
+
expect17(typeof first.deliveryId === "string" && first.deliveryId !== "").toBe(true);
|
|
2977
|
+
expect17(second.deliveryId, "the same bounce got another deliveryId").toBe(first.deliveryId);
|
|
2978
|
+
expect17(second.events).toEqual(first.events);
|
|
2979
|
+
}),
|
|
2980
|
+
CASE_MS
|
|
2981
|
+
);
|
|
2982
|
+
it17(
|
|
2983
|
+
"shape: every event passes the kernel's rules for this slot",
|
|
2984
|
+
() => using(build, async (adapter) => {
|
|
2985
|
+
const feedback = [
|
|
2986
|
+
emailFeedbackType(adapter.providerName, "bounced"),
|
|
2987
|
+
emailFeedbackType(adapter.providerName, "complained")
|
|
2988
|
+
];
|
|
2989
|
+
for (const sample of samples) {
|
|
2990
|
+
const delivery = await receive2(adapter, sample().request);
|
|
2991
|
+
expect17(delivery.verified, "a signed delivery was not verified").toBe(true);
|
|
2992
|
+
expect17(
|
|
2993
|
+
delivery.events.filter((e) => feedback.includes(e.type)).length,
|
|
2994
|
+
"the delivery carried no bounce or complaint to check"
|
|
2995
|
+
).toBeGreaterThan(0);
|
|
2996
|
+
expect17(
|
|
2997
|
+
webhookDeliveryProblem2(adapter.providerName, adapter.producesEvents, delivery),
|
|
2998
|
+
"the kernel would refuse this delivery"
|
|
2999
|
+
).toBeNull();
|
|
3000
|
+
expect17(
|
|
3001
|
+
emailFeedbackProblem(adapter.providerName, delivery),
|
|
3002
|
+
"the kernel would refuse this delivery for the email slot"
|
|
3003
|
+
).toBeNull();
|
|
3004
|
+
}
|
|
3005
|
+
}),
|
|
3006
|
+
CASE_MS
|
|
3007
|
+
);
|
|
3008
|
+
it17(
|
|
3009
|
+
"classification: the hard bounce is hard for its recipient",
|
|
3010
|
+
() => using(build, async (adapter) => {
|
|
3011
|
+
const { request, recipient } = options.bounce();
|
|
3012
|
+
const delivery = await receive2(adapter, request);
|
|
3013
|
+
const bounces = eventsFor(
|
|
3014
|
+
delivery,
|
|
3015
|
+
emailFeedbackType(adapter.providerName, "bounced"),
|
|
3016
|
+
recipient
|
|
3017
|
+
);
|
|
3018
|
+
expect17(bounces.length, `no bounce for ${recipient}`).toBeGreaterThan(0);
|
|
3019
|
+
expect17(bounces.map((e) => e.payload["bounce"])).toEqual(bounces.map(() => "hard"));
|
|
3020
|
+
}),
|
|
3021
|
+
CASE_MS
|
|
3022
|
+
);
|
|
3023
|
+
const { softBounce, complaint } = options;
|
|
3024
|
+
if (softBounce !== void 0) {
|
|
3025
|
+
it17(
|
|
3026
|
+
"classification: the soft bounce is soft for its recipient",
|
|
3027
|
+
() => using(build, async (adapter) => {
|
|
3028
|
+
const { request, recipient } = softBounce();
|
|
3029
|
+
const delivery = await receive2(adapter, request);
|
|
3030
|
+
const bounces = eventsFor(
|
|
3031
|
+
delivery,
|
|
3032
|
+
emailFeedbackType(adapter.providerName, "bounced"),
|
|
3033
|
+
recipient
|
|
3034
|
+
);
|
|
3035
|
+
expect17(bounces.length, `no bounce for ${recipient}`).toBeGreaterThan(0);
|
|
3036
|
+
expect17(bounces.map((e) => e.payload["bounce"])).toEqual(bounces.map(() => "soft"));
|
|
3037
|
+
}),
|
|
3038
|
+
CASE_MS
|
|
3039
|
+
);
|
|
3040
|
+
}
|
|
3041
|
+
if (complaint !== void 0) {
|
|
3042
|
+
it17(
|
|
3043
|
+
"classification: the complaint is a complaint for its recipient",
|
|
3044
|
+
() => using(build, async (adapter) => {
|
|
3045
|
+
const { request, recipient } = complaint();
|
|
3046
|
+
const delivery = await receive2(adapter, request);
|
|
3047
|
+
const complaints = eventsFor(
|
|
3048
|
+
delivery,
|
|
3049
|
+
emailFeedbackType(adapter.providerName, "complained"),
|
|
3050
|
+
recipient
|
|
3051
|
+
);
|
|
3052
|
+
expect17(complaints.length, `no complaint for ${recipient}`).toBeGreaterThan(0);
|
|
3053
|
+
}),
|
|
3054
|
+
CASE_MS
|
|
3055
|
+
);
|
|
3056
|
+
}
|
|
3057
|
+
});
|
|
3058
|
+
}
|
|
3059
|
+
|
|
3060
|
+
// src/shipping-tracking.ts
|
|
3061
|
+
import { describe as describe17, expect as expect18, it as it18 } from "vitest";
|
|
3062
|
+
import {
|
|
3063
|
+
normaliseTrackingNumber,
|
|
3064
|
+
shippingTrackingProblem,
|
|
3065
|
+
shippingTrackingType,
|
|
3066
|
+
webhookDeliveryProblem as webhookDeliveryProblem3
|
|
3067
|
+
} from "@nymbalhq/types";
|
|
3068
|
+
async function receive3(adapter, request) {
|
|
3069
|
+
expect18(typeof adapter.receiveWebhook, "the adapter has no receiveWebhook").toBe("function");
|
|
3070
|
+
return adapter.receiveWebhook(request.rawBody, request.headers);
|
|
3071
|
+
}
|
|
3072
|
+
function eventsFor2(delivery, type, trackingNumber) {
|
|
3073
|
+
const key = normaliseTrackingNumber(trackingNumber);
|
|
3074
|
+
return delivery.events.filter((e) => {
|
|
3075
|
+
const n = e.payload["trackingNumber"];
|
|
3076
|
+
return e.type === type && typeof n === "string" && normaliseTrackingNumber(n) === key;
|
|
3077
|
+
});
|
|
3078
|
+
}
|
|
3079
|
+
function runShippingTrackingContract(name, build, options) {
|
|
3080
|
+
const samples = [options.delivered, options.inTransit].filter(
|
|
3081
|
+
(sample) => sample !== void 0
|
|
3082
|
+
);
|
|
3083
|
+
function classifies(sample, status) {
|
|
3084
|
+
return () => using(build, async (adapter) => {
|
|
3085
|
+
const { request, trackingNumber } = sample();
|
|
3086
|
+
const delivery = await receive3(adapter, request);
|
|
3087
|
+
const updates = eventsFor2(
|
|
3088
|
+
delivery,
|
|
3089
|
+
shippingTrackingType(adapter.providerName),
|
|
3090
|
+
trackingNumber
|
|
3091
|
+
);
|
|
3092
|
+
expect18(updates.length, `no tracking update for ${trackingNumber}`).toBeGreaterThan(0);
|
|
3093
|
+
expect18(updates.map((e) => e.payload["status"])).toEqual(updates.map(() => status));
|
|
3094
|
+
});
|
|
3095
|
+
}
|
|
3096
|
+
describe17(`shipping tracking contract: ${name}`, () => {
|
|
3097
|
+
it18(
|
|
3098
|
+
"replay: one tracking update received twice gives one deliveryId and equal events",
|
|
3099
|
+
() => using(build, async (adapter) => {
|
|
3100
|
+
const first = await receive3(adapter, options.delivered().request);
|
|
3101
|
+
const second = await receive3(adapter, options.delivered().request);
|
|
3102
|
+
expect18(first.verified, "the signed update was not verified").toBe(true);
|
|
3103
|
+
expect18(typeof first.deliveryId === "string" && first.deliveryId !== "").toBe(true);
|
|
3104
|
+
expect18(second.deliveryId, "the same update got another deliveryId").toBe(first.deliveryId);
|
|
3105
|
+
expect18(second.events).toEqual(first.events);
|
|
3106
|
+
}),
|
|
3107
|
+
CASE_MS
|
|
3108
|
+
);
|
|
3109
|
+
it18(
|
|
3110
|
+
"shape: every event passes the kernel's rules for this slot",
|
|
3111
|
+
() => using(build, async (adapter) => {
|
|
3112
|
+
const tracking = shippingTrackingType(adapter.providerName);
|
|
3113
|
+
for (const sample of samples) {
|
|
3114
|
+
const delivery = await receive3(adapter, sample().request);
|
|
3115
|
+
expect18(delivery.verified, "a signed delivery was not verified").toBe(true);
|
|
3116
|
+
expect18(
|
|
3117
|
+
delivery.events.filter((e) => e.type === tracking).length,
|
|
3118
|
+
"the delivery carried no tracking update to check"
|
|
3119
|
+
).toBeGreaterThan(0);
|
|
3120
|
+
expect18(
|
|
3121
|
+
webhookDeliveryProblem3(adapter.providerName, adapter.producesEvents, delivery),
|
|
3122
|
+
"the kernel would refuse this delivery"
|
|
3123
|
+
).toBeNull();
|
|
3124
|
+
expect18(
|
|
3125
|
+
shippingTrackingProblem(adapter.providerName, delivery),
|
|
3126
|
+
"the kernel would refuse this delivery for the shipping slot"
|
|
3127
|
+
).toBeNull();
|
|
3128
|
+
}
|
|
3129
|
+
}),
|
|
3130
|
+
CASE_MS
|
|
3131
|
+
);
|
|
3132
|
+
it18(
|
|
3133
|
+
"classification: the delivered update is delivered for its tracking number",
|
|
3134
|
+
classifies(options.delivered, "delivered"),
|
|
3135
|
+
CASE_MS
|
|
3136
|
+
);
|
|
3137
|
+
if (options.inTransit !== void 0) {
|
|
3138
|
+
it18(
|
|
3139
|
+
"classification: the in-transit update is in transit for its tracking number",
|
|
3140
|
+
classifies(options.inTransit, "in_transit"),
|
|
3141
|
+
CASE_MS
|
|
3142
|
+
);
|
|
3143
|
+
}
|
|
3144
|
+
});
|
|
3145
|
+
}
|
|
3146
|
+
|
|
3147
|
+
// src/security.ts
|
|
3148
|
+
import { describe as describe18, expect as expect19, it as it19 } from "vitest";
|
|
2953
3149
|
var testConfig = {
|
|
2954
3150
|
rateLimit: {
|
|
2955
3151
|
api: { requests: 100, window: "1m", action: "block" }
|
|
@@ -2963,24 +3159,24 @@ var testConfig = {
|
|
|
2963
3159
|
}
|
|
2964
3160
|
};
|
|
2965
3161
|
function runSecurityContract(name, build, options = {}) {
|
|
2966
|
-
|
|
2967
|
-
|
|
3162
|
+
describe18(`SecurityAdapter contract: ${name}`, () => {
|
|
3163
|
+
it19(
|
|
2968
3164
|
"validate accepts a valid config",
|
|
2969
3165
|
async () => {
|
|
2970
3166
|
const adapter = await build();
|
|
2971
3167
|
const result = await adapter.validate(testConfig);
|
|
2972
|
-
|
|
2973
|
-
|
|
3168
|
+
expect19(typeof result.valid).toBe("boolean");
|
|
3169
|
+
expect19(Array.isArray(result.errors)).toBe(true);
|
|
2974
3170
|
},
|
|
2975
3171
|
CASE_MS
|
|
2976
3172
|
);
|
|
2977
|
-
|
|
3173
|
+
it19(
|
|
2978
3174
|
"validate of empty config reports errors",
|
|
2979
3175
|
async () => {
|
|
2980
3176
|
const adapter = await build();
|
|
2981
3177
|
const result = await adapter.validate({});
|
|
2982
3178
|
if (!result.valid) {
|
|
2983
|
-
|
|
3179
|
+
expect19(result.errors.length).toBeGreaterThan(0);
|
|
2984
3180
|
}
|
|
2985
3181
|
},
|
|
2986
3182
|
CASE_MS
|
|
@@ -2995,7 +3191,7 @@ function runSecurityContract(name, build, options = {}) {
|
|
|
2995
3191
|
}
|
|
2996
3192
|
|
|
2997
3193
|
// src/projection.ts
|
|
2998
|
-
import { describe as
|
|
3194
|
+
import { describe as describe19, it as it20, expect as expect20 } from "vitest";
|
|
2999
3195
|
function makeEvent2(id) {
|
|
3000
3196
|
return {
|
|
3001
3197
|
id,
|
|
@@ -3008,26 +3204,26 @@ function makeEvent2(id) {
|
|
|
3008
3204
|
};
|
|
3009
3205
|
}
|
|
3010
3206
|
function runProjectionContract(opts) {
|
|
3011
|
-
|
|
3012
|
-
|
|
3207
|
+
describe19("Projection idempotency contract", () => {
|
|
3208
|
+
it20("processing the same event twice applies the mutation only once", async () => {
|
|
3013
3209
|
const ctx = await opts.build();
|
|
3014
3210
|
const event3 = makeEvent2("dedup-evt-001");
|
|
3015
3211
|
await ctx.handle(event3);
|
|
3016
3212
|
await ctx.handle(event3);
|
|
3017
|
-
|
|
3213
|
+
expect20(await ctx.applicationCount()).toBe(1);
|
|
3018
3214
|
});
|
|
3019
|
-
|
|
3215
|
+
it20("distinct events each apply their mutation", async () => {
|
|
3020
3216
|
const ctx = await opts.build();
|
|
3021
3217
|
await ctx.handle(makeEvent2("distinct-evt-001"));
|
|
3022
3218
|
await ctx.handle(makeEvent2("distinct-evt-002"));
|
|
3023
|
-
|
|
3219
|
+
expect20(await ctx.applicationCount()).toBe(2);
|
|
3024
3220
|
});
|
|
3025
|
-
|
|
3221
|
+
it20("after reprocessing a batch the count equals unique event count", async () => {
|
|
3026
3222
|
const ctx = await opts.build();
|
|
3027
3223
|
const events = [makeEvent2("batch-001"), makeEvent2("batch-002"), makeEvent2("batch-003")];
|
|
3028
3224
|
for (const e of events) await ctx.handle(e);
|
|
3029
3225
|
for (const e of events) await ctx.handle(e);
|
|
3030
|
-
|
|
3226
|
+
expect20(await ctx.applicationCount()).toBe(3);
|
|
3031
3227
|
});
|
|
3032
3228
|
});
|
|
3033
3229
|
}
|
|
@@ -3067,6 +3263,7 @@ export {
|
|
|
3067
3263
|
runAnalyticsContract,
|
|
3068
3264
|
runDocumentStoreContract,
|
|
3069
3265
|
runEmailContract,
|
|
3266
|
+
runEmailFeedbackContract,
|
|
3070
3267
|
runEventBusContract,
|
|
3071
3268
|
runMediaStorageContract,
|
|
3072
3269
|
runPaymentsContract,
|
|
@@ -3075,6 +3272,7 @@ export {
|
|
|
3075
3272
|
runSearchContract,
|
|
3076
3273
|
runSecurityContract,
|
|
3077
3274
|
runShippingContract,
|
|
3275
|
+
runShippingTrackingContract,
|
|
3078
3276
|
runTaxContract,
|
|
3079
3277
|
runWebhookContract,
|
|
3080
3278
|
searchTerms,
|