@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 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/security.ts
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
- describe16(`SecurityAdapter contract: ${name}`, () => {
2967
- it17(
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
- expect17(typeof result.valid).toBe("boolean");
2973
- expect17(Array.isArray(result.errors)).toBe(true);
3168
+ expect19(typeof result.valid).toBe("boolean");
3169
+ expect19(Array.isArray(result.errors)).toBe(true);
2974
3170
  },
2975
3171
  CASE_MS
2976
3172
  );
2977
- it17(
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
- expect17(result.errors.length).toBeGreaterThan(0);
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 describe17, it as it18, expect as expect18 } from "vitest";
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
- describe17("Projection idempotency contract", () => {
3012
- it18("processing the same event twice applies the mutation only once", async () => {
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
- expect18(await ctx.applicationCount()).toBe(1);
3213
+ expect20(await ctx.applicationCount()).toBe(1);
3018
3214
  });
3019
- it18("distinct events each apply their mutation", async () => {
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
- expect18(await ctx.applicationCount()).toBe(2);
3219
+ expect20(await ctx.applicationCount()).toBe(2);
3024
3220
  });
3025
- it18("after reprocessing a batch the count equals unique event count", async () => {
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
- expect18(await ctx.applicationCount()).toBe(3);
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,