Skip to content

Latest commit

 

History

History

client

README.md

@hyodotdev/openiap-client-protocol Specification and Code Generation

Generate Types

OpenIAP GraphQL logo
OpenIAP meets GraphQL

The OpenIAP client contract and multiplatform codegen toolkit.

npm

Use the contract

npm install @hyodotdev/openiap-client-protocol
import {
  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.

Common store provider contract

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.

Develop the specification

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 — TypeScript
  • src/generated/Types.swift — Swift
  • src/generated/Types.kt — Kotlin
  • src/generated/types.dart — Dart
  • src/generated/types.gd — GDScript
  • src/generated/Types.cs — C# / .NET MAUI

TypeScript

Uses @graphql-codegen/cli.

  1. Install the repository-pinned Bun version.
  2. Install dependencies once from the monorepo root: bun install --frozen-lockfile
  3. Run the complete canonical pipeline: bun run generate
  4. 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.


Workflow Tips

  • 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. ProductOrSubscription intentionally 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 generate whenever you change schema shape, generator code, or operations. The generate:<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.

Sponsors

Meta        Amazon Developer        Codemagic

Thank you to Meta, Amazon Developer, and Codemagic for supporting OpenIAP. View sponsorship options.

In-kind support

Claude      Codemagic

Claude for Open Source provides the Claude Ultra plan for the maintainer for 6 months.
Codemagic provides infrastructure support for OpenIAP.

OpenCollective

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.

Sponsors: OpenCollective sponsors

Backers: OpenCollective backers

Become a sponsor | Become a backer

Past supporters

Supported the project before the OpenIAP sponsor program: Nami for 30 months and Courier for 1 month.

Nami      Courier