@nymbalhq/contract-tests 0.0.0-stage → 1.2.0

package/dist/chunk-ABEL44IM.js

@@ -0,0 +1,19 @@
+// src/kinds.ts
+var CONTRACT_KINDS = [
+  "payments",
+  "email",
+  "reviews",
+  "search",
+  "analytics",
+  "shipping",
+  "tax",
+  "ai",
+  "documentStore",
+  "eventBus",
+  "media"
+];
+
+export {
+  CONTRACT_KINDS
+};
+//# sourceMappingURL=chunk-ABEL44IM.js.map

package/dist/chunk-ABEL44IM.js.map

@@ -0,0 +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

@@ -0,0 +1,149 @@
+import { Slot, AdapterContext, DocumentStoreAdapter, EventBusAdapter, MediaStorage, PaymentsAdapter, EmailAdapter, ReviewsAdapter, SearchAdapter, SearchDocument, AnalyticsAdapter, ShippingAdapter, TaxAdapter, AiAdapter, SecurityAdapter, NymbalEvent } from '@nymbalhq/types';
+export { CONTRACT_KINDS } from './kinds.js';
+
+/** How long a health check, or a call on an unreachable dependency, may take to settle. */
+declare const BOUND_MS = 6000;
+/** Makes the adapter under test: a fresh, initialized one each time it is called. */
+type Build<A> = () => A | Promise<A>;
+/** The options every suite takes. */
+interface ContractOptions<A = unknown> {
+    /**
+     * An adapter whose dependency cannot be reached. Given, the suite adds the downtime cases: `healthCheck()` reports
+     * `down`, and one representative operation rejects, each within 6 s. For a client that connects when it is built,
+     * build it while the dependency is up and then take the dependency away (close a proxy in front of it).
+     */
+    unreachable?: Build<A>;
+}
+
+/**
+ * The AdapterContext the kernel hands a package's `createAdapter`, with a silent logger: `config` is a commerce slot's
+ * `config` record or a primitive's connection block.
+ */
+declare function adapterContext(slot: Slot, config: Record<string, unknown>, env?: NodeJS.ProcessEnv): AdapterContext;
+
+interface DocumentStoreContractOptions extends ContractOptions<DocumentStoreAdapter> {
+    /** A clock the store reads: the TTL cases advance it instead of waiting a one-second TTL out. */
+    clock?: {
+        advance(ms: number): void | Promise<void>;
+    };
+    /** Two stores on one backend under different prefixes, for the prefix isolation cases. */
+    isolation?: () => Promise<[DocumentStoreAdapter, DocumentStoreAdapter]>;
+}
+type Make$1 = Build<DocumentStoreAdapter>;
+/**
+ * The document store contract every implementation runs: the reference order and filter of
+ * `compareDocumentValues` and `matchesSortKey`, cursors that survive a delete, TTL, conditional puts, batches,
+ * isolation between collections (and, given `isolation`, between prefixes), the same as a property against the
+ * reference model, an atomic `replaceCollection`, and health (and, given `unreachable`, downtime). `make` returns an
+ * empty store each time.
+ */
+declare function runDocumentStoreContract(name: string, make: Make$1, opts?: DocumentStoreContractOptions): void;
+
+interface EventBusContractOptions extends ContractOptions<EventBusAdapter> {
+    /** Another instance on the same streams as the bus `make` returned last: only a shared bus passes it. */
+    second?: () => Promise<EventBusAdapter>;
+    /** The bus's own knobs, set small by the caller: the claim and timeout cases assert the windows they bound. */
+    timing?: {
+        claimIdleMs: number;
+        ackTimeoutMs: number;
+    };
+}
+type Make = Build<EventBusAdapter>;
+/**
+ * The event bus contract every implementation runs. `publish` resolves only after every matching subscription's
+ * handler has finished (what a read straight after a command relies on); a throwing handler is logged and does not
+ * reject it; `replay` reaches `derived` subscriptions only; each subscription takes its events in order. With `second`,
+ * a named subscription is handled once across instances and an unnamed one on every instance. Then the delivery
+ * contract's cases, and health (and, given `unreachable`, downtime).
+ */
+declare function runEventBusContract(name: string, make: Make, opts?: EventBusContractOptions): void;
+
+interface MediaStorageContractOptions extends ContractOptions<MediaStorage> {
+    /** Reads back the bytes a URL `put` returned serves: the storage's public URL, or the file a local URL names. */
+    fetchUrl: (url: string) => Promise<Uint8Array>;
+}
+/**
+ * The media storage contract every implementation runs: `put` resolves with a URL, and the bytes read back from that
+ * URL (through `fetchUrl`, which knows where the storage serves from) are the bytes that were put; then health (and,
+ * given `unreachable`, downtime).
+ */
+declare function runMediaStorageContract(name: string, make: Build<MediaStorage>, options: MediaStorageContractOptions): void;
+
+interface PaymentsContractOptions extends ContractOptions<PaymentsAdapter> {
+    /** One webhook as the provider would deliver it, signed. Given, the suite parses it twice and compares. */
+    signedWebhook?: () => {
+        rawBody: string | Buffer;
+        signature: string;
+    };
+}
+declare function runPaymentsContract(name: string, build: Build<PaymentsAdapter>, options?: PaymentsContractOptions): void;
+
+declare function runEmailContract(name: string, build: Build<EmailAdapter>, options?: ContractOptions<EmailAdapter>): void;
+
+declare function runReviewsContract(name: string, build: Build<ReviewsAdapter>, options?: ContractOptions<ReviewsAdapter>): void;
+
+interface SearchContractOptions extends ContractOptions<SearchAdapter> {
+    /** The adapter ranks by tiers (every term in the name, then every term in name, SKU or variant name), then score,
+     *  then id. Native does; a vendor's need not, so the ranking case runs only when the runner says so. */
+    ranking?: boolean;
+    /** The adapter reports `facet` and counts `facet('categoryIds', {query, filters})` within the query's matches. */
+    facets?: boolean;
+    /** This adapter's cursor for an offset, valid or not (it encodes; only search validates), so the malformed-cursor
+     *  case can build a negative and a non-integer cursor. Without it only the undecodable and the stale cursor run. */
+    cursorAt?: (offset: number) => string;
+    /** fast-check runs per property (default 25). */
+    numRuns?: number;
+}
+declare function runSearchContract(name: string, build: Build<SearchAdapter>, options?: SearchContractOptions): void;
+
+/** The terms of a text, as search sees them. */
+declare function searchTerms(text: string): string[];
+/** A product as the search handler indexes it, before it is a SearchDocument. */
+interface ContractProduct {
+    id: string;
+    name: string;
+    description: string;
+    variants: Array<{
+        sku: string;
+        name: string;
+        priceMinor: number;
+    }>;
+    categoryIds: string[];
+}
+/** The document the search handler indexes for the product. */
+declare function toSearchDocument(p: ContractProduct): SearchDocument;
+/** Does the product match the query. */
+declare function matchesQuery(p: ContractProduct, query: string): boolean;
+
+declare function runAnalyticsContract(name: string, build: Build<AnalyticsAdapter>, options?: ContractOptions<AnalyticsAdapter>): void;
+
+declare function runShippingContract(name: string, build: Build<ShippingAdapter>, options?: ContractOptions<ShippingAdapter>): void;
+
+declare function runTaxContract(name: string, build: Build<TaxAdapter>, options?: ContractOptions<TaxAdapter>): void;
+
+declare function runAiContract(name: string, build: Build<AiAdapter>, options?: ContractOptions<AiAdapter>): void;
+
+declare function runSecurityContract(name: string, build: Build<SecurityAdapter>, options?: ContractOptions<SecurityAdapter>): void;
+
+interface ProjectionContractOptions {
+    /**
+     * Build a fresh projection handler context. Returns:
+     * - `handle(event)` — processes the event through the idempotency-guarded handler
+     * - `applicationCount()` — returns how many times the underlying handler actually ran
+     */
+    build: () => Promise<{
+        handle: (event: NymbalEvent) => Promise<void>;
+        applicationCount: () => Promise<number>;
+    }>;
+}
+declare function runProjectionContract(opts: ProjectionContractOptions): void;
+
+/** What a suite certifies: a commerce slot or an infrastructure primitive. */
+type ContractKind = Slot;
+/** A kind's suite, as `nymbal test:contracts` calls it: `build` makes a fresh adapter for each case. */
+type ContractSuite = (name: string, build: Build<unknown>, options?: Record<string, unknown>) => void;
+/** Each kind's suite, one for every kind in CONTRACT_KINDS. Each is typed here, at the CLI's boundary. */
+declare const contractSuites: Partial<Record<ContractKind, ContractSuite>>;
+
+export { BOUND_MS, adapterContext, contractSuites, matchesQuery, runAiContract, runAnalyticsContract, runDocumentStoreContract, runEmailContract, runEventBusContract, runMediaStorageContract, runPaymentsContract, runProjectionContract, runReviewsContract, runSearchContract, runSecurityContract, runShippingContract, runTaxContract, searchTerms, toSearchDocument };
+export type { Build, ContractKind, ContractOptions, ContractProduct, ContractSuite, DocumentStoreContractOptions, EventBusContractOptions, MediaStorageContractOptions, PaymentsContractOptions, ProjectionContractOptions, SearchContractOptions };