fix(provider): accept Maestro's optional/nullable spec fields (#570 part 1)

[Kshot3000]

Summary

Part 1 of #570: Maestro responses that the provider schemas reject when a field the Maestro spec marks optional/nullable arrives null or missing.

The spec (maestro-org/maestro-api-specifications, per the issue) does not require these fields, but the schemas in Maestro.ts did — several via Schema.NullOr(...), which accepts null but not a missing key — so any of them arriving absent or null failed the whole call with a schema decode error:

• Protocol parameters: plutus_cost_models.plutus_v3 (the spec requires only plutus_v1 and plutus_v2)
• UTxOs: datum, reference_script, and a datum's bytes / json
• Paging and accounts: next_cursor on paginated responses, delegated_pool on accounts

Fix

All of the above are now Schema.optionalWith(X, { nullable: true }). The transforms needed almost no change — transformDatumOption, transformScriptRef, transformDelegation, and the pagination loop already handle null/undefined — except the cost models, where a missing/null plutus_v3 now maps via ?? [] to an empty PlutusV3 model.

For the three protocol parameters the issue flags separately — delegate_representative_deposit, governance_action_deposit, and min_fee_reference_scripts, all required by the public ProtocolParameters type — I chose the issue's "fail with a clear error" option over a default: a deposit or fee figure of 0 would be a silent wrong value, not a fallback. The schema accepts them as null/missing, and transformProtocolParameters then throws a clear error naming the field (required field "delegate_representative_deposit" arrived null or missing…). MaestroEffect.getProtocolParameters now converts that throw into a ProviderError via Effect.flatMap + Effect.try — a throw inside Effect.map would have surfaced as a defect, not the ProviderError the function promises.

Deliberately left out

Part 2 of #570 — the protocol-parameters path (/protocol-parameters vs the spec's /general/protocol-parameters). The issue itself says the old path "may still work" and needs a check with an API key before switching; I don't have a Maestro key to verify with, so I haven't touched the path.

Tests

Six new tests in Maestro.test.ts, each verified red on unmodified main first (schema ProviderError / decode failure) and green after:

• Missing plutus_v3 and null plutus_v3 both decode and map to an empty PlutusV3 model
• Each of the three required parameters arriving null/missing fails as a ProviderError (asserted Cause.Fail, not Die) whose cause chain carries the deliberate required field "…" wording — the test asserts that wording specifically because a bare ParseError also names the field
• A UTxO page with the datum/reference_script keys missing and no next_cursor key decodes (existing fixtures always send those keys, as null)
• A datum whose bytes/json keys are missing decodes to its datum hash
• An account with the delegated_pool key missing decodes to poolId: null

Maestro test file: 16/16. Full package suite: 1684 passed / 75 skipped / 0 failed (test files 101 passed / 1 skipped of 102 — main's baseline of 1678 plus the 6 new tests). tsc --noEmit and eslint clean on the touched files; prettier drift on the two touched files is byte-identical to unmodified main (both were already flagged there — I matched the surrounding style in my hunks rather than reformatting unrelated code). A patch changeset is included.

---

Independent builder — not affiliated with the Cardano Foundation, IOG or Intersect.

@Kshot9000 (https://x.com/kshot9000) · ADA donations: addr1q8hnl6vl5a6k3rw3n5g3jtte696zcl76kfatzv7gpswa9r0dj7fma6klq55y4ffm7tf0em09udnyhuk4ah92pl5x9jpqjae44v

cc @cardano-foundation @IntersectMBO