@anvilco/types
v1.1.0
Published
TypeScript types generated from the Anvil OpenAPI spec and GraphQL schema
Readme
@anvilco/types
TypeScript types generated from the Anvil OpenAPI spec and GraphQL schema. Consumed internally by @anvilco/browser and @anvilco/react.
The one place for the Anvil SDK's TypeScript types:
- REST:
paths,componentsandoperations, generated from the OpenAPI spec, plus the fill-PDF request types (FillPdfPayload,FillPdfData,FillPdfOptions). - Etch:
CreateEtchPacketArgs, the createEtchPacket mutation's arguments with the ones the GraphQL schema callsJSONtyped:signers(EtchSigner),signaturePageOptions(EtchSignaturePageOptions) andfinishPageOptions(EtchFinishPageOptions). The OpenAPI spec publishes their shapes. - GraphQL: the
GraphQLnamespace, generated from the schema. - The SDK's own types:
AnvilOptions,GraphQLResponse,RESTResponse,ResponseError,ResponseErrorField,RuntimeErrorandAbortable.
import type { GraphQL } from '@anvilco/types'
type Packet = GraphQL.Type<'EtchPacket'> // any type in the schema, by name
type WeldFile = GraphQL.Type<'WeldFile'> // input types too: nullable fields are optional
type Args = GraphQL.MutationArgs<'createEtchPacket'> // the arguments of any mutation
type PacketArgs = GraphQL.QueryArgs<'etchPacket'> // …or queryObject types describe the whole object as the schema defines it. A query returns only the fields it selects, so for data you fetched, use the type of your query's result instead.
Custom scalars are typed by GraphQL.Scalars: Date is an ISO 8601 string, JSON is unknown, and Upload is Blob | { data: string; mimetype: string; filename: string } | { url: string; filename?: string }.
GraphQL operations
To run queries and mutations, use @anvilco/core. Its graphql documents are typed against this schema.
The specs these types are generated from also ship with the package, for build tooling: the GraphQL schema at @anvilco/types/schema.graphql and the OpenAPI spec at @anvilco/types/openapi.json. The other Anvil API clients (python-anvil, dotnet-anvil) generate their types from them, so every client describes the same API. Importing @anvilco/types never loads them at runtime.
Versioning
The package mirrors the live API, so its version tracks what the API did, by semver:
- major: a type, field or argument was removed or renamed; an argument became required; an output field became nullable; an input field became required. Anything typed against the old shape may no longer compile.
- minor: additions: new types, fields, arguments, enum values and endpoints, and other changes that only widen what can be sent or received.
- patch: only descriptions changed.
The sync PR's changeset is chosen by diffing the specs (scripts/spec-bump.js: graphql-js's findBreakingChanges and findDangerousChanges for the schema, oasdiff for the OpenAPI spec), with the highest bump across both. A major sync PR lists each breaking change and is reviewed before it merges. @anvilco/core re-exports these types, so it takes the same bump.
Regenerating
Types are regenerated from production after every Anvil production deploy (.github/workflows/sync-api-types.yml), which opens a PR when they change, with a changeset at the bump the change warrants (see Versioning). To regenerate by hand:
- REST:
yarn workspace @anvilco/types generate:restrefreshesschema/openapi.jsonfrom production and rebuildssrc/rest.tsfrom it. - GraphQL:
ANVIL_API_KEY_PROD_BASE64=... yarn workspace @anvilco/types fetch:schemarefreshesschema/anvil-schema.graphqlfrom production, thenyarn workspace @anvilco/types generate:graphqlrebuildssrc/graphql/generated/from it. The second step needs no network access or key, which is what CI checks.
