@anvilco/types 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,35 @@
 # @anvilco/types
 
-TypeScript types generated from the [Anvil](https://www.useanvil.com) OpenAPI spec. Consumed internally by `@anvilco/browser` and `@anvilco/react`.
+TypeScript types generated from the [Anvil](https://www.useanvil.com) OpenAPI spec and GraphQL schema. Consumed internally by `@anvilco/browser` and `@anvilco/react`.
 
-Types are regenerated weekly from the production spec via `yarn workspace @anvilco/types generate:rest`.
+The one place for the Anvil SDK's TypeScript types:
+
+- **REST**: `paths`, `components` and `operations`, generated from the OpenAPI spec, plus the fill-PDF request types (`FillPdfPayload`, `FillPdfData`, `FillPdfOptions`).
+- **GraphQL**: the `GraphQL` namespace, generated from the schema.
+- **The SDK's own types**: `AnvilOptions`, `GraphQLResponse`, `RESTResponse`, `ResponseError`, `ResponseErrorField`, `RuntimeError` and `Abortable`.
+
+```ts
+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 query
+```
+
+Object 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`](../core/README.md). Its `graphql` documents are typed against this schema.
+
+The GraphQL schema these types are generated from also ships with the package, at `@anvilco/types/schema.graphql`, for build tooling. Importing `@anvilco/types` never loads it at runtime.
+
+## Regenerating
+
+Types are regenerated from production after every Anvil production deploy (`.github/workflows/sync-api-types.yml`), which opens a PR when they change. To regenerate by hand:
+
+- REST: `yarn workspace @anvilco/types generate:rest`
+- GraphQL: `ANVIL_API_KEY_PROD_BASE64=... yarn workspace @anvilco/types fetch:schema` refreshes `schema/anvil-schema.graphql` from production, then `yarn workspace @anvilco/types generate:graphql` rebuilds `src/graphql/generated/` from it. The second step needs no network access or key, which is what CI checks.