@anvilco/core
v1.1.0
Published
Shared core logic for Anvil JavaScript SDKs
Readme
@anvilco/core
Shared core logic for Anvil JavaScript SDKs. Internal use only — published to npm as a dependency of @anvilco/browser and @anvilco/react but not intended for direct consumer use. Consumed by @anvilco/browser, @anvilco/react, and future packages (e.g. a Node.js SDK).
The purpose of this package is to centralise logic that would otherwise be duplicated across SDK targets: HTTP transport, error handling, rate limiting, auth header construction, and API types derived from the OpenAPI spec.
What's in here
HTTP & transport
requestREST<T>— generic fetch wrapper with rate limiting, automatic 429 retry, error normalization, and AbortSignal support. ReturnsRESTResponse<T>.requestGraphQL/requestGraphQLUpload— same wrapper configured for GraphQL (POST to/graphql), as a JSON body or a multipart upload.requestGraphQLOperation— sends agraphql()document (result typed from it) or a plain string, as multipart when its variables hold aBloband as JSON otherwise.- Failures are returned, not thrown: every request resolves to
{ statusCode, data?, errors? }, whether the failure is an HTTP error, a GraphQL error or a network failure. The exception is aborting with asignal, which rejects with the signal's reason (anAbortErrorby default), asfetchdoes. wrapRequest— the underlying fetch executor; handles response parsing, content-type branching (JSON / blob / stream / arrayBuffer), and retry logic.
API functions
fillPdf— HTTP function forPOST /api/v1/fill/:castEid.pdf. TakesbaseUrl,authHeader,castEid, payload, and options (signal,versionNumber). Types are derived directly from the generated OpenAPI spec.
Auth
buildAuthHeader— builds aBearer <token>orBasic <base64(apiKey:)>header from anAnvilOptionsobject.
Rate limiting
createRateLimiter— token bucket rate limiter compatible with browser and Node environments. Used internally byrequestREST/requestGraphQL.
Error handling
isJsonError/normalizeJsonErrors/normalizeError— consistent error normalization across GraphQL error envelopes, REST error responses, and network-level errors.
GraphQL
graphql— writes a GraphQL document typed against the Anvil schema; its result and variables are inferred from the document. Built with gql.tada on@anvilco/types'GraphQL.Setup. Also exportsResultOf,VariablesOf,FragmentOfandreadFragment.- Documents in this repo are validated against the schema by
gql.tada checkin CI (yarn workspace @anvilco/browser check:graphql).
Constants & types
DEFAULT_BASE_URL—https://app.useanvil.comVERSION_LATEST/VERSION_LATEST_PUBLISHED— sentinel version numbers (-1,-2)DataType— union of supported response types (json,blob,stream,arrayBuffer)RESTResponse<T>,GraphQLResponse,ResponseError,RuntimeError— shared response and error shapes
Generated API types
Types are generated from the live Anvil OpenAPI spec and live in @anvilco/types. Core re-exports components, operations, and paths from that package — used to derive FillPdfPayload, FillPdfData, etc. To regenerate, run yarn generate:rest in the @anvilco/types package.
Versioning
Semver. The generated API types this package re-exports from @anvilco/types are part of its public API, so it takes the same bump as that package on every sync (see its versioning policy): a field the API removes is a major release of both. Its own changes follow the usual rules: major for a removed or changed export or behavior, minor for additions, patch for fixes.
Adding a new SDK target
When building a new package (e.g. @anvilco/node) that needs Anvil API access:
- Add
@anvilco/coreas a dependency - Import
requestREST,buildAuthHeader, and any generated types directly - API functions that are target-agnostic (like
fillPdf) live here and can be reused as-is - Target-specific concerns (auth flow, storage, framework bindings) live in the new package
Development
yarn build # compile to dist/
yarn test # run tests
yarn test:watch # run tests in watch mode
yarn typecheck # type check without building
yarn lint # lint src/