The OpenIAP client contract and multiplatform codegen toolkit.
npm install @hyodotdev/openiap-client-protocolimport {
ErrorCode,
type PurchaseError,
} from "@hyodotdev/openiap-client-protocol";
function isCanceled(error: PurchaseError): boolean {
return error.code === ErrorCode.UserCancelled;
}The root export provides TypeScript types and runtime enums. The /kit-api
export provides the portable IAPKit client helper, /purchase-flow the
backend-confirmed purchase pipeline with the result types an app backend
returns. Its legacy low-level confirmation helpers remain deprecated until
Client Protocol 2.0; use the framework SDK’s confirmWithIapkit or
confirmOnDeviceIOS, or supply another service’s confirmer. The extracted
confirmer implementation is internal, with no new public package entry point.
Generated native types are
available at /swift, /kotlin, /dart, /gdscript, and /csharp.
For a working purchase integration, choose a framework SDK.
The /purchase-flow-vectors fixture covers the shared lifecycle and built-in
adapters. Adapter cases describe that implementation, not requirements for
other verification services.
This package's npm version is the Client Protocol version. It is mirrored
into openiap-versions.json as clientProtocol, alongside the independent
openiap-apple and openiap-google native package versions.
Apple and Android providers share StoreProviderDescriptor, frozen IapStore
values, concrete storeId identity, purchase lifecycle and capability rules.
A new store uses store = unknown with its stable provider id. External
providers are selected with a community id; a provider that serves an existing
store reports that store's canonical storeId and legacy store value in its
purchases. Platform bindings preserve PurchaseIOS or PurchaseAndroid; request.apple and
request.google select the corresponding platform arguments.
Factories declare the native core and Client Protocol versions used to build the provider. An incompatible binding fails at connection. One optional registry entry can carry both platform bindings and their conformance reports. See the provider guide for native factories, package selection and independent verification.
The generator runs from a checkout of the OpenIAP repository; it is not included
in the npm package. Run the commands below from specs/client unless stated otherwise.
This package is the single source of truth for the OpenIAP client GraphQL schema. The SDL
files live in src/ and are split into common (type.graphql, api.graphql), error
taxonomy (error.graphql), and platform-specific (*-ios.graphql, *-android.graphql)
definitions.
This is a publishable specification artifact, not a deployed service. Runtime
service implementations remain in packages/ and libraries/; the portable
kit-api, purchase-flow, purchase-flow-core, and purchase-flow-confirmers
helpers are client
code, and the independent
server-side Commerce Protocol remains in specs/commerce-protocol.
The npm tarball ships the TypeScript runtime and declarations compiled into
dist/, so consumer compiler flags never re-check the authored sources.
Workspace consumers keep resolving the authored sources through the
openiap-source export condition (customConditions in their tsconfig), and
their bun runtimes pass --conditions=openiap-source for the same reason.
dist/ is a generated packaging artifact: build it with bun run build:package
and never edit or commit it.
The repository-owned generator is the only supported generation path for
TypeScript, Swift, Kotlin, Dart, GDScript, and C#. It understands OpenIAP's
code-generation SDL extensions (including nested union wrappers and comment
markers), validates their ownership, and keeps every published SDK copy in
sync. Update the schema files first, then run bun run generate.
TypeScript uses graphql-codegen followed by guarded AST post-processing. The
other five outputs use the strict parser, shared IR transformer, and language
plugins under codegen/. Both paths consume the same schema inventory,
marker/deprecation metadata, and typed custom-input contracts. Platform copies
are distributed through generated-sync-manifest.mjs; do not add a second
copy list or generator entrypoint.
# => Union is a closed wrapper contract: it may only annotate a non-root
object with one or more nullable result fields. Invalid owners, empty wrappers,
and required fields stop every language generator.
Generated outputs:
src/generated/types.ts— TypeScriptsrc/generated/Types.swift— Swiftsrc/generated/Types.kt— Kotlinsrc/generated/types.dart— Dartsrc/generated/types.gd— GDScriptsrc/generated/Types.cs— C# / .NET MAUI
Uses @graphql-codegen/cli.
- Install the repository-pinned Bun version.
- Install dependencies once from the monorepo root:
bun install --frozen-lockfile - Run the complete canonical pipeline:
bun run generate - Generated TypeScript output:
src/generated/types.ts
Configuration lives in codegen.ts. The script merges every SDL file and
emits a schema-first type layer that mirrors the documented shapes.
generate:ts remains an internal diagnostic stage of the complete command;
do not commit its partial output without the final native generation and
manifest sync stages.
- Treat the SDL files in
src/as the canonical schema. Commit schema updates before shipping generated code. - Do not feed the SDL directly to general-purpose GraphQL client generators.
ProductOrSubscriptionintentionally composes generated union wrappers, so the SDL is an OpenIAP code-generation DSL rather than a portable executable GraphQL service schema. - Regenerate with
bun run generatewhenever you change schema shape, generator code, or operations. Thegenerate:<language>commands are diagnostic plugin entry points; before committing, always finish with the complete command so every manifest target is synchronized. - If you introduce custom scalars, make sure to extend the respective generator config/plugin so they map to the desired native types.
- Commit every changed generated and synchronized artifact with its schema or generator change. The pre-commit and CI gates regenerate from scratch and reject unstaged or non-reproducible output drift.
Thank you to Meta, Amazon Developer, and Codemagic for supporting OpenIAP. View sponsorship options.
Claude for Open Source provides the Claude Ultra plan for the maintainer for 6 months.
Codemagic provides infrastructure support for OpenIAP.
We also recognize sponsors and backers through OpenCollective. The original react-native-iap collective now supports the broader OpenIAP ecosystem and is managed separately from the main sponsor program.
Become a sponsor | Become a backer
Supported the project before the OpenIAP sponsor program: Nami for 30 months and Courier for 1 month.

