import { z } from "../../../contracts/zod.ts"; import type { CommandEffectDescriptor, InstalledContractContribution, InstalledHttpContract, } from "../../../contracts/external-contract-runtime.ts"; import { REFERENCE_FEATURE_ID } from "./reference-feature-contract.ts"; import { createReferenceResourceCommandSchema, referenceProblemSchema, referenceResourceDtoSchema, referenceResourceListQuerySchema, referenceResourceParamsSchema, type ReferenceProblem, zodValidator, } from "./reference-schemas.ts"; export type { ReferenceProblem } from "./reference-schemas.ts"; /** * §4.8. The single `TEMPLATE_FIXTURE` contribution. It keeps the reference * HTTP vertical executable as deterministic template data and is excluded from * `contractSet`. A product feature MUST instead pin an external package and * import it from its own `contracts/-contract-contribution.ts`. */ const PROBLEM_VALIDATOR = zodValidator( "ReferenceProblem", referenceProblemSchema, ); /** * Fixture-side classifier standing in for the package-provided pure bounded * classifier. A status the fixture does not describe stays `MAYBE_APPLIED`. */ const CREATE_EFFECT: CommandEffectDescriptor = Object.freeze({ successEffect: "APPLIED_CONFIRMED" as const, classifyProblem({ status, }: Readonly<{ status: number; problem: ReferenceProblem }>) { if (status === 400 || status === 409 || status === 422) { return "NOT_APPLIED"; } return "MAYBE_APPLIED"; }, /** * D-2. The reference backend rejects an unauthenticated, forbidden or * rate-limited create before touching state. */ classifyStatus: () => "NOT_APPLIED" as const, }); export const LIST_REFERENCE_RESOURCES_CONTRACT = Object.freeze({ contract: Object.freeze({ operationId: "LIST_REFERENCE_RESOURCES", method: "GET" as const, pathTemplate: "/api/reference-resources", inputValidator: zodValidator( "ReferenceResourceListQuery", referenceResourceListQuerySchema, ), outputValidator: zodValidator( "ReferenceResourceListPayload", z.array(referenceResourceDtoSchema).max(100), ), problemValidator: PROBLEM_VALIDATOR, acceptedStatuses: Object.freeze([200]), emptyBodyStatuses: Object.freeze([]), retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, commandRecovery: null, commandEffect: null, projectRequest(input: z.output) { const entries: (readonly [string, string])[] = []; if (input.cursor !== undefined) entries.push(["cursor", input.cursor]); entries.push(["limit", String(input.limit)]); for (const tag of input.tags ?? []) entries.push(["tags", tag]); return Object.freeze({ pathValues: Object.freeze({}), queryEntries: Object.freeze(entries), body: null, }); }, }), frontend: Object.freeze({ policyId: "REFERENCE_LIST_V1", requestByteLimit: 0, responseByteLimit: 262_144, totalDeadlineMs: 10_000, retryBudget: 2 as const, authProfileId: "REFERENCE_EXTERNAL_BEARER", diagnosticsOperation: "reference.list", traffic: Object.freeze({ maxPhysicalRequests: 3, maxRetries: 2, maxConcurrentRequests: 1, maxQueuedRequests: 0, }), }), }) satisfies InstalledHttpContract< z.output, readonly z.output[], ReferenceProblem >; export const GET_REFERENCE_RESOURCE_CONTRACT = Object.freeze({ contract: Object.freeze({ operationId: "GET_REFERENCE_RESOURCE", method: "GET" as const, pathTemplate: "/api/reference-resources/{resourceId}", inputValidator: zodValidator( "ReferenceResourceParams", referenceResourceParamsSchema, ), outputValidator: zodValidator( "ReferenceResourcePayload", referenceResourceDtoSchema, ), problemValidator: PROBLEM_VALIDATOR, acceptedStatuses: Object.freeze([200]), emptyBodyStatuses: Object.freeze([]), retrySemantics: "SAFE" as const, requestBody: "NONE" as const, responseBody: "REQUIRED_JSON" as const, commandRecovery: null, commandEffect: null, projectRequest(input: z.output) { return Object.freeze({ pathValues: Object.freeze({ resourceId: input.resourceId }), queryEntries: Object.freeze([]), body: null, }); }, }), frontend: Object.freeze({ policyId: "REFERENCE_DETAIL_V1", requestByteLimit: 0, responseByteLimit: 32_768, totalDeadlineMs: 10_000, retryBudget: 2 as const, authProfileId: "REFERENCE_EXTERNAL_BEARER", diagnosticsOperation: "reference.detail", traffic: Object.freeze({ maxPhysicalRequests: 3, maxRetries: 2, maxConcurrentRequests: 1, maxQueuedRequests: 0, }), }), }) satisfies InstalledHttpContract< z.output, z.output, ReferenceProblem >; export const CREATE_REFERENCE_RESOURCE_CONTRACT = Object.freeze({ contract: Object.freeze({ operationId: "CREATE_REFERENCE_RESOURCE", method: "POST" as const, pathTemplate: "/api/reference-resources", inputValidator: zodValidator( "CreateReferenceResourceCommand", createReferenceResourceCommandSchema, ), outputValidator: zodValidator( "ReferenceResourcePayload", referenceResourceDtoSchema, ), problemValidator: PROBLEM_VALIDATOR, acceptedStatuses: Object.freeze([200, 201]), emptyBodyStatuses: Object.freeze([]), retrySemantics: "KEYED" as const, requestBody: "JSON" as const, responseBody: "REQUIRED_JSON" as const, commandRecovery: Object.freeze({ mode: "IDEMPOTENCY_REPLAY" as const, operationIdentityField: "idempotencyKey", }), commandEffect: CREATE_EFFECT, projectRequest(input: z.output) { return Object.freeze({ pathValues: Object.freeze({}), queryEntries: Object.freeze([]), body: Object.freeze({ ...input }), }); }, }), frontend: Object.freeze({ policyId: "REFERENCE_CREATE_V1", requestByteLimit: 32_768, responseByteLimit: 32_768, totalDeadlineMs: 10_000, /** * §8.3. A KEYED command has no automatic retry after a dispatched attempt * lost its response; the fixture therefore declares a zero budget rather * than relying on a runtime special case. */ retryBudget: 0 as const, authProfileId: "REFERENCE_EXTERNAL_BEARER", diagnosticsOperation: "reference.create", traffic: Object.freeze({ maxPhysicalRequests: 1, maxRetries: 0, maxConcurrentRequests: 1, maxQueuedRequests: 0, }), }), }) satisfies InstalledHttpContract< z.output, z.output, ReferenceProblem >; export const REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION: InstalledContractContribution = Object.freeze({ contributionId: "reference-feature-http-v1", featureId: REFERENCE_FEATURE_ID, source: Object.freeze({ kind: "TEMPLATE_FIXTURE" as const, fixtureId: "REFERENCE_FEATURE_V1" as const, revision: 1 as const, }), http: Object.freeze([ LIST_REFERENCE_RESOURCES_CONTRACT, GET_REFERENCE_RESOURCE_CONTRACT, CREATE_REFERENCE_RESOURCE_CONTRACT, ]) as readonly InstalledHttpContract[], events: Object.freeze([]), });