@fanfare-io/fanfare-sdk-contracts 0.18.0 → 0.19.0

package/README.md

@@ -19,13 +19,21 @@ npm install @fanfare-io/fanfare-sdk-contracts
 
 ## Response schema compatibility
 
-Choose the Valibot object mode based on the compatibility contract of the payload:
+Response schemas tolerate unknown keys and strip them. A field added to a server response is validated away rather than rejected, so a server-side addition cannot break an SDK that is already released and running in the field. Nothing downstream re-serializes a parsed response, so unknown keys are dropped rather than preserved wherever a schema does not say otherwise: callers read only the fields the types declare.
 
-- `v.strictObject` rejects unknown keys. Use it only for deliberately closed contracts, and document why additive server fields must be rejected.
-- `v.object` validates known fields and strips unknown keys. Use it when callers should remain compatible with additive fields but should not receive them.
-- `v.looseObject` validates known fields and preserves unknown keys. Use it when forward-compatible fields must survive validation.
+Request bodies stay strict, as do the contracts a service validates incoming payloads against. Rejecting a key the contract does not name is the point of a request contract, and those payloads are validated by the receiving service rather than by a released client.
 
-This choice is made per endpoint and may differ between a response root and its nested objects. SDK response parsing validates server payloads at runtime, so tightening a nested object can turn an otherwise additive server change into a client-visible validation failure. Treat such changes as coordinated contract changes rather than incidental schema cleanup.
+The Valibot object modes that express this:
+
+- `v.object` validates known fields and strips unknown keys. The default for every response schema.
+- `v.strictObject` rejects unknown keys. Reserved for request bodies, server-validated contracts, and the rare union whose members are told apart by strictness alone — each carrying a comment saying which.
+- `v.looseObject` validates known fields and preserves unknown keys. Use only where an unvalidated key genuinely has to survive validation.
+
+A contract used in both directions is defined once and exported twice: the field entries live in one object, and the package exports a strict schema for the request and a tolerant one for the response. `SelectionChoiceSchema` and `SelectionPinRequestSchema` are the pair. Defining them separately would let the two spellings drift; giving both directions one schema would force a single strictness onto two contracts that need opposite ones.
+
+Tolerance has a consequence worth stating plainly: phase exclusivity is no longer enforced by response parsing. A participating sequence that arrives carrying a `grant`, `checkout`, or `outcome` is parsed, not rejected — the out-of-phase key is simply stripped, and the parsed sequence is the phase it declared. Keeping those keys off the wire for the phases that do not own them is the server's contract to uphold; a client that tolerates additive fields cannot also police which ones belong.
+
+This choice applies to a response root and its nested objects alike: SDK response parsing validates server payloads at runtime, so tightening a nested object turns an otherwise additive server change into a client-visible validation failure. Treat such a change as a coordinated contract change rather than incidental schema cleanup.
 
 ## License
 

package/dist/auction.d.ts

@@ -1,6 +1,6 @@
 import { InferOutput } from 'valibot';
 import * as v from "valibot";
-export declare const AuctionLiveSchema: v.VariantSchema<"auctionType", [v.StrictObjectSchema<{
+export declare const AuctionLiveSchema: v.VariantSchema<"auctionType", [v.ObjectSchema<{
     readonly auctionType: v.LiteralSchema<"english", undefined>;
     readonly highestBid: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
     readonly minNextBid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
@@ -10,7 +10,7 @@ export declare const AuctionLiveSchema: v.VariantSchema<"auctionType", [v.Strict
     readonly autoExtended: v.BooleanSchema<undefined>;
     readonly reserveMet: v.BooleanSchema<undefined>;
     readonly ended: v.BooleanSchema<undefined>;
-}, undefined>, v.StrictObjectSchema<{
+}, undefined>, v.ObjectSchema<{
     readonly auctionType: v.LiteralSchema<"dutch", undefined>;
     readonly currentPrice: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
     readonly remainingQuantity: v.NumberSchema<undefined>;
@@ -23,10 +23,9 @@ export declare const AuctionLiveSchema: v.VariantSchema<"auctionType", [v.Strict
 export type AuctionLive = InferOutput<typeof AuctionLiveSchema>;
 /**
  * The auction configuration read. These fifteen fields are an authored projection of the auction
- * row: checkout and operator fields never leave the server on this endpoint, so a key outside this
- * set is a contract drift, not an addition to tolerate.
+ * row: checkout and operator fields never leave the server on this endpoint.
  */
-export declare const AuctionDetailsResponseSchema: v.StrictObjectSchema<{
+export declare const AuctionDetailsResponseSchema: v.ObjectSchema<{
     readonly id: v.StringSchema<undefined>;
     readonly timeZone: v.StringSchema<undefined>;
     readonly settleAt: v.StringSchema<undefined>;
@@ -44,7 +43,7 @@ export declare const AuctionDetailsResponseSchema: v.StrictObjectSchema<{
     readonly quantity: v.NullishSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>, undefined>;
 }, undefined>;
 export type AuctionDetailsResponse = InferOutput<typeof AuctionDetailsResponseSchema>;
-export declare const AuctionBidderStateResponseSchema: v.StrictObjectSchema<{
+export declare const AuctionBidderStateResponseSchema: v.ObjectSchema<{
     readonly status: v.PicklistSchema<["NOT_BID", "WINNING", "OUTBID", "WON", "LOST"], undefined>;
     readonly lastBidAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
     readonly winningBidAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
@@ -59,7 +58,7 @@ export declare const AuctionBidderStateResponseSchema: v.StrictObjectSchema<{
     readonly releaseClass: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     readonly outcome: v.OptionalSchema<v.PicklistSchema<["completed", "expired"], undefined>, undefined>;
     readonly degraded: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
-    readonly live: v.VariantSchema<"auctionType", [v.StrictObjectSchema<{
+    readonly live: v.VariantSchema<"auctionType", [v.ObjectSchema<{
         readonly auctionType: v.LiteralSchema<"english", undefined>;
         readonly highestBid: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
         readonly minNextBid: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
@@ -69,7 +68,7 @@ export declare const AuctionBidderStateResponseSchema: v.StrictObjectSchema<{
         readonly autoExtended: v.BooleanSchema<undefined>;
         readonly reserveMet: v.BooleanSchema<undefined>;
         readonly ended: v.BooleanSchema<undefined>;
-    }, undefined>, v.StrictObjectSchema<{
+    }, undefined>, v.ObjectSchema<{
         readonly auctionType: v.LiteralSchema<"dutch", undefined>;
         readonly currentPrice: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
         readonly remainingQuantity: v.NumberSchema<undefined>;

package/dist/auction.js

@@ -1,8 +1,8 @@
 import * as e from "valibot";
-const t = e.string(), n = e.pipe(t, e.regex(/^\d{1,12}(\.\d{1,8})?$/)), i = e.picklist(["NOT_BID", "WINNING", "OUTBID", "WON", "LOST"]), o = e.object({
+const t = e.string(), n = e.pipe(t, e.regex(/^\d{1,12}(\.\d{1,8})?$/)), o = e.picklist(["NOT_BID", "WINNING", "OUTBID", "WON", "LOST"]), i = e.object({
   productId: t,
   variantId: e.optional(t)
-}), l = e.strictObject({
+}), l = e.object({
   auctionType: e.literal("english"),
   highestBid: e.nullable(n),
   minNextBid: n,
@@ -12,7 +12,7 @@ const t = e.string(), n = e.pipe(t, e.regex(/^\d{1,12}(\.\d{1,8})?$/)), i = e.pi
   autoExtended: e.boolean(),
   reserveMet: e.boolean(),
   ended: e.boolean()
-}), s = e.strictObject({
+}), s = e.object({
   auctionType: e.literal("dutch"),
   currentPrice: n,
   remainingQuantity: e.number(),
@@ -21,7 +21,7 @@ const t = e.string(), n = e.pipe(t, e.regex(/^\d{1,12}(\.\d{1,8})?$/)), i = e.pi
   floorPrice: e.nullable(n),
   settleAt: t,
   ended: e.boolean()
-}), c = e.variant("auctionType", [l, s]), r = e.strictObject({
+}), c = e.variant("auctionType", [l, s]), r = e.object({
   id: t,
   timeZone: t,
   settleAt: t,
@@ -37,8 +37,8 @@ const t = e.string(), n = e.pipe(t, e.regex(/^\d{1,12}(\.\d{1,8})?$/)), i = e.pi
   autoExtendSeconds: e.nullish(e.number()),
   priceDropIntervalSeconds: e.nullish(e.pipe(e.number(), e.integer())),
   quantity: e.nullish(e.pipe(e.number(), e.integer()))
-}), u = e.strictObject({
-  status: i,
+}), u = e.object({
+  status: o,
   lastBidAmount: e.optional(n),
   winningBidAmount: e.optional(n),
   bidCount: e.optional(e.number()),
@@ -46,7 +46,7 @@ const t = e.string(), n = e.pipe(t, e.regex(/^\d{1,12}(\.\d{1,8})?$/)), i = e.pi
   // WON: the grant's continuation deadline, as the admission register holds it.
   expiresAt: e.optional(t),
   // WON: the product the win is bound to.
-  selection: e.optional(o),
+  selection: e.optional(i),
   // WON: the admission register's standing for this win, and the recorded cause when it is
   // `expired`. `outcome` is the terminal result derived from that standing — a WON bidder whose
   // admission was paid reads `completed`, one whose window closed reads `expired`.