@nymbalhq/contract-tests 1.4.0 → 1.6.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/LICENSE +21 -0
- package/README.md +6 -0
- package/dist/{chunk-KK53D2KL.js → chunk-ABEL44IM.js} +2 -1
- package/dist/{chunk-KK53D2KL.js.map → chunk-ABEL44IM.js.map} +1 -1
- package/dist/index.d.ts +106 -5
- package/dist/index.js +1776 -542
- package/dist/index.js.map +1 -1
- package/dist/kinds.d.ts +1 -1
- package/dist/kinds.js +1 -1
- package/package.json +2 -2
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 nymbal contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# @nymbalhq/contract-tests
|
|
2
|
+
|
|
3
|
+
The contract suites a Nymbal adapter is certified against, one per slot. `nymbal test:contracts --package
|
|
4
|
+
<package>` runs the suite for an adapter's slot.
|
|
5
|
+
|
|
6
|
+
See [Adapters](https://github.com/nymbalhq/nymbal/blob/main/apps/docs/src/content/docs/adapters.md).
|
|
@@ -7,6 +7,7 @@ var CONTRACT_KINDS = [
|
|
|
7
7
|
"analytics",
|
|
8
8
|
"shipping",
|
|
9
9
|
"tax",
|
|
10
|
+
"ai",
|
|
10
11
|
"documentStore",
|
|
11
12
|
"eventBus",
|
|
12
13
|
"media"
|
|
@@ -15,4 +16,4 @@ var CONTRACT_KINDS = [
|
|
|
15
16
|
export {
|
|
16
17
|
CONTRACT_KINDS
|
|
17
18
|
};
|
|
18
|
-
//# sourceMappingURL=chunk-
|
|
19
|
+
//# sourceMappingURL=chunk-ABEL44IM.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/kinds.ts"],"sourcesContent":["import type { Slot } from '@nymbalhq/types'\n\n// Its own entry (`@nymbalhq/contract-tests/kinds`), free of vitest: the CLI reads it in its own process, where\n// importing vitest outside a test run throws.\n\n/** The kinds `contractSuites` has a suite for. */\nexport const CONTRACT_KINDS = [\n 'payments',\n 'email',\n 'reviews',\n 'search',\n 'analytics',\n 'shipping',\n 'tax',\n 'documentStore',\n 'eventBus',\n 'media',\n] as const satisfies readonly Slot[]\n"],"mappings":";AAMO,IAAM,iBAAiB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}
|
|
1
|
+
{"version":3,"sources":["../src/kinds.ts"],"sourcesContent":["import type { Slot } from '@nymbalhq/types'\n\n// Its own entry (`@nymbalhq/contract-tests/kinds`), free of vitest: the CLI reads it in its own process, where\n// importing vitest outside a test run throws.\n\n/** The kinds `contractSuites` has a suite for. */\nexport const CONTRACT_KINDS = [\n 'payments',\n 'email',\n 'reviews',\n 'search',\n 'analytics',\n 'shipping',\n 'tax',\n 'ai',\n 'documentStore',\n 'eventBus',\n 'media',\n] as const satisfies readonly Slot[]\n"],"mappings":";AAMO,IAAM,iBAAiB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { Slot, AdapterContext, DocumentStoreAdapter, EventBusAdapter, MediaStorage, PaymentsAdapter, EmailAdapter, ReviewsAdapter, SearchAdapter, SearchDocument, AnalyticsAdapter, ShippingAdapter, TaxAdapter, WebhookHeaders, CommerceAdapter, SecurityAdapter, NymbalEvent } from '@nymbalhq/types';
|
|
1
|
+
import { Slot, AdapterContext, Logger, AiAdapter, DocumentStoreAdapter, EventBusAdapter, MediaStorage, PaymentsAdapter, EmailAdapter, ReviewsAdapter, Review, SearchAdapter, SearchDocument, AnalyticsAdapter, ShippingAdapter, Address, Parcel, TaxAdapter, WebhookHeaders, CommerceAdapter, SecurityAdapter, NymbalEvent } from '@nymbalhq/types';
|
|
2
2
|
export { CONTRACT_KINDS } from './kinds.js';
|
|
3
3
|
|
|
4
4
|
/** How long a health check, or a call on an unreachable dependency, may take to settle. */
|
|
@@ -21,6 +21,51 @@ interface ContractOptions<A = unknown> {
|
|
|
21
21
|
*/
|
|
22
22
|
declare function adapterContext(slot: Slot, config: Record<string, unknown>, env?: NodeJS.ProcessEnv): AdapterContext;
|
|
23
23
|
|
|
24
|
+
/** A capability a case is gated on. */
|
|
25
|
+
type AiCapability = 'tools' | 'stream';
|
|
26
|
+
/** How a stand-in answers every request of a failing build. */
|
|
27
|
+
type AiFailureMode = `status:${number}` | 'html:502' | 'no-text' | 'not-json' | 'hang' | 'unreachable' | 'stream-break' | 'stream-error' | 'stream-stall';
|
|
28
|
+
/** A failing build: the adapter, and how many requests its provider has received. */
|
|
29
|
+
interface AiFailingBuild {
|
|
30
|
+
adapter: AiAdapter;
|
|
31
|
+
requests: () => number;
|
|
32
|
+
close: () => Promise<void>;
|
|
33
|
+
/** The text deltas the provider sent on its last stream; the stream failure cases need it. */
|
|
34
|
+
sent?: () => string[];
|
|
35
|
+
/** How many requests the client closed before the provider finished answering; the abort case needs it. */
|
|
36
|
+
closed?: () => number;
|
|
37
|
+
}
|
|
38
|
+
interface AiContractOptions {
|
|
39
|
+
/**
|
|
40
|
+
* How many requests the provider behind `build` has received. Given, the suite adds the cases that count them:
|
|
41
|
+
* refused input makes none, and `complete()` makes one, as `chat()` does.
|
|
42
|
+
*/
|
|
43
|
+
requests?: () => number;
|
|
44
|
+
/**
|
|
45
|
+
* An adapter built with `key` as its configured key and `logger` as its logger, on a provider that answers every
|
|
46
|
+
* request as `mode`: `status:<n>` answers n with the provider's JSON error, its message echoing the key raw, as
|
|
47
|
+
* base64 and as base64url, and longer than 300 characters; `html:502` answers 502 with an HTML page; `no-text`
|
|
48
|
+
* answers 200 with no text; `not-json` answers 200 with a body that is not JSON; `hang` accepts the request and
|
|
49
|
+
* never answers, the adapter built with `timeoutMs: 300`; `unreachable` refuses the connection. Every mode but
|
|
50
|
+
* `unreachable` echoes the key in its body and in a response header; the error messages of `status:<n>` and
|
|
51
|
+
* `stream-error` echo the last user turn's text too. On a stream request only (anything else is answered as a
|
|
52
|
+
* model): `stream-break` sends the first two text deltas and destroys the connection; `stream-error` sends one
|
|
53
|
+
* delta and then the provider's mid-stream error; `stream-stall` sends one delta and then nothing, the adapter built
|
|
54
|
+
* with `timeoutMs: 300`. Given, the suite adds the failure cases.
|
|
55
|
+
*/
|
|
56
|
+
failing?: (mode: AiFailureMode, key: string, logger: Logger) => Promise<AiFailingBuild>;
|
|
57
|
+
/**
|
|
58
|
+
* The capabilities the adapter must list: a case gated on one fails when `capabilities()` lacks it, where it would
|
|
59
|
+
* be skipped. A provider package that ships tools and streaming names both, so dropping one cannot pass as a skip.
|
|
60
|
+
*/
|
|
61
|
+
requires?: readonly AiCapability[];
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Certifies an ai adapter's `chat()`: the eval set always, and with `options` the cases a stand-in makes possible.
|
|
65
|
+
* `build` makes a fresh adapter whose provider answers as a model.
|
|
66
|
+
*/
|
|
67
|
+
declare function runAiContract(name: string, build: Build<AiAdapter>, options?: AiContractOptions): void;
|
|
68
|
+
|
|
24
69
|
interface DocumentStoreContractOptions extends ContractOptions<DocumentStoreAdapter> {
|
|
25
70
|
/** A clock the store reads: the TTL cases advance it instead of waiting a one-second TTL out. */
|
|
26
71
|
clock?: {
|
|
@@ -81,7 +126,14 @@ declare function runPaymentsContract(name: string, build: Build<PaymentsAdapter>
|
|
|
81
126
|
|
|
82
127
|
declare function runEmailContract(name: string, build: Build<EmailAdapter>, options?: ContractOptions<EmailAdapter>): void;
|
|
83
128
|
|
|
84
|
-
|
|
129
|
+
interface ReviewsContractOptions extends ContractOptions<ReviewsAdapter> {
|
|
130
|
+
/**
|
|
131
|
+
* Puts `count` reviews of `productId` in the adapter's store, by whatever way reviews reach it, and returns them.
|
|
132
|
+
* Required when `submit` is not among the adapter's capabilities.
|
|
133
|
+
*/
|
|
134
|
+
seed?: (adapter: ReviewsAdapter, productId: string, count: number) => Promise<Review[]>;
|
|
135
|
+
}
|
|
136
|
+
declare function runReviewsContract(name: string, build: Build<ReviewsAdapter>, options?: ReviewsContractOptions): void;
|
|
85
137
|
|
|
86
138
|
interface SearchContractOptions extends ContractOptions<SearchAdapter> {
|
|
87
139
|
/** The adapter ranks by tiers (every term in the name, then every term in name, SKU or variant name), then score,
|
|
@@ -118,7 +170,18 @@ declare function matchesQuery(p: ContractProduct, query: string): boolean;
|
|
|
118
170
|
|
|
119
171
|
declare function runAnalyticsContract(name: string, build: Build<AnalyticsAdapter>, options?: ContractOptions<AnalyticsAdapter>): void;
|
|
120
172
|
|
|
121
|
-
|
|
173
|
+
interface ShippingContractOptions extends ContractOptions<ShippingAdapter> {
|
|
174
|
+
/** A tracking number the provider takes, fresh on each call (a provider may let each be registered once). */
|
|
175
|
+
trackingNumber?: () => string;
|
|
176
|
+
/** The carrier sent with it; none (the provider detects it) unless given. */
|
|
177
|
+
carrier?: string;
|
|
178
|
+
/** Where rates are asked from and to: two US addresses unless given. */
|
|
179
|
+
from?: Address;
|
|
180
|
+
to?: Address;
|
|
181
|
+
/** The parcel rated: 500 g unless given. */
|
|
182
|
+
parcel?: Parcel;
|
|
183
|
+
}
|
|
184
|
+
declare function runShippingContract(name: string, build: Build<ShippingAdapter>, options?: ShippingContractOptions): void;
|
|
122
185
|
|
|
123
186
|
declare function runTaxContract(name: string, build: Build<TaxAdapter>, options?: ContractOptions<TaxAdapter>): void;
|
|
124
187
|
|
|
@@ -139,6 +202,44 @@ interface WebhookContractOptions {
|
|
|
139
202
|
*/
|
|
140
203
|
declare function runWebhookContract(name: string, build: Build<CommerceAdapter>, options: WebhookContractOptions): void;
|
|
141
204
|
|
|
205
|
+
/** One signed delivery as the provider sends it, and the address its bounce or complaint is for. */
|
|
206
|
+
interface EmailFeedbackSample {
|
|
207
|
+
request: WebhookRequest;
|
|
208
|
+
recipient: string;
|
|
209
|
+
}
|
|
210
|
+
interface EmailFeedbackContractOptions {
|
|
211
|
+
/** A delivery of a hard bounce (the provider's permanent failure). */
|
|
212
|
+
bounce: () => EmailFeedbackSample;
|
|
213
|
+
/** A delivery of a soft bounce (a transient failure). Given, the suite checks it is classified `soft`. */
|
|
214
|
+
softBounce?: () => EmailFeedbackSample;
|
|
215
|
+
/** A delivery of a spam complaint. Given, the suite checks it is a complaint. */
|
|
216
|
+
complaint?: () => EmailFeedbackSample;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Certifies an email adapter's bounces and complaints from `receiveWebhook`: a bounce received twice is one delivery
|
|
220
|
+
* with the same events, every delivery is one the kernel's route accepts for the email slot, and each bounce and
|
|
221
|
+
* complaint is classified as the provider reported it. Run it beside `runWebhookContract`.
|
|
222
|
+
*/
|
|
223
|
+
declare function runEmailFeedbackContract(name: string, build: Build<CommerceAdapter>, options: EmailFeedbackContractOptions): void;
|
|
224
|
+
|
|
225
|
+
/** One signed delivery as the provider sends it, and the tracking number its update is for. */
|
|
226
|
+
interface ShippingTrackingSample {
|
|
227
|
+
request: WebhookRequest;
|
|
228
|
+
trackingNumber: string;
|
|
229
|
+
}
|
|
230
|
+
interface ShippingTrackingContractOptions {
|
|
231
|
+
/** A delivery of a delivered update. */
|
|
232
|
+
delivered: () => ShippingTrackingSample;
|
|
233
|
+
/** A delivery of an in-transit update. Given, the suite checks it is classified `in_transit`. */
|
|
234
|
+
inTransit?: () => ShippingTrackingSample;
|
|
235
|
+
}
|
|
236
|
+
/**
|
|
237
|
+
* Certifies a shipping adapter's tracking updates from `receiveWebhook`: an update received twice is one delivery with
|
|
238
|
+
* the same events, every delivery is one the kernel's route accepts for the shipping slot, and each update is
|
|
239
|
+
* classified as the carrier reported it. Run it beside `runWebhookContract`.
|
|
240
|
+
*/
|
|
241
|
+
declare function runShippingTrackingContract(name: string, build: Build<CommerceAdapter>, options: ShippingTrackingContractOptions): void;
|
|
242
|
+
|
|
142
243
|
declare function runSecurityContract(name: string, build: Build<SecurityAdapter>, options?: ContractOptions<SecurityAdapter>): void;
|
|
143
244
|
|
|
144
245
|
interface ProjectionContractOptions {
|
|
@@ -161,5 +262,5 @@ type ContractSuite = (name: string, build: Build<unknown>, options?: Record<stri
|
|
|
161
262
|
/** Each kind's suite, one for every kind in CONTRACT_KINDS. Each is typed here, at the CLI's boundary. */
|
|
162
263
|
declare const contractSuites: Partial<Record<ContractKind, ContractSuite>>;
|
|
163
264
|
|
|
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 };
|
|
265
|
+
export { BOUND_MS, adapterContext, contractSuites, matchesQuery, runAiContract, runAnalyticsContract, runDocumentStoreContract, runEmailContract, runEmailFeedbackContract, runEventBusContract, runMediaStorageContract, runPaymentsContract, runProjectionContract, runReviewsContract, runSearchContract, runSecurityContract, runShippingContract, runShippingTrackingContract, runTaxContract, runWebhookContract, searchTerms, toSearchDocument };
|
|
266
|
+
export type { AiCapability, AiContractOptions, AiFailingBuild, AiFailureMode, Build, ContractKind, ContractOptions, ContractProduct, ContractSuite, DocumentStoreContractOptions, EmailFeedbackContractOptions, EmailFeedbackSample, EventBusContractOptions, MediaStorageContractOptions, PaymentsContractOptions, ProjectionContractOptions, ReviewsContractOptions, SearchContractOptions, ShippingContractOptions, ShippingTrackingContractOptions, ShippingTrackingSample, WebhookContractOptions, WebhookRequest };
|