@anvilco/core

Shared core logic for Anvil JavaScript SDKs. Internal use only — not published 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. Returns RESTResponse<T>.
• requestGraphQL — same wrapper configured for GraphQL (POST to /graphql, JSON body with query + variables).
• wrapRequest — the underlying fetch executor; handles response parsing, content-type branching (JSON / blob / stream / arrayBuffer), and retry logic.

API functions

• fillPdf — HTTP function for POST /api/v1/fill/:castEid.pdf. Takes baseUrl, authHeader, castEid, payload, and options (signal, versionNumber). Types are derived directly from the generated OpenAPI spec.

Auth

• buildAuthHeader — builds a Bearer <token> or Basic <base64(apiKey:)> header from an AnvilOptions object.

Rate limiting

• createRateLimiter — token bucket rate limiter compatible with browser and Node environments. Used internally by requestREST / requestGraphQL.

Error handling

• isJsonError / normalizeJsonErrors / normalizeError — consistent error normalization across GraphQL error envelopes, REST error responses, and network-level errors.

GraphQL

• graphql/ — query and mutation string factories for all Anvil GraphQL operations.

Constants & types

• DEFAULT_BASE_URL — https://app.useanvil.com
• VERSION_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.

Adding a new SDK target

When building a new package (e.g. @anvilco/node) that needs Anvil API access:

1. Add @anvilco/core as a dependency
2. Import requestREST, buildAuthHeader, and any generated types directly
3. API functions that are target-agnostic (like fillPdf) live here and can be reused as-is
4. 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/