@hyodotdev/openiap-commerce-protocol 0.0.0-bootstrap.0 → 0.1.0

package/README.md

@@ -1,8 +1,230 @@
-# @hyodotdev/openiap-commerce-protocol
+# OpenIAP Commerce Protocol
 
-This package registers the official npm name for the OpenIAP Commerce Protocol.
+[![npm](https://img.shields.io/npm/v/@hyodotdev/openiap-commerce-protocol/latest)](https://www.npmjs.com/package/@hyodotdev/openiap-commerce-protocol)
 
-Version `0.0.0-bootstrap.0` contains package metadata only. It does not include
-a usable implementation. Functional releases will be published separately.
+A vendor-neutral specification for the **server side** of in-app purchases.
 
-[Project source](https://github.com/hyodotdev/openiap/tree/main/specs/commerce-protocol) · [Documentation](https://openiap.dev)
+OpenIAP normalizes the client-side purchase API across stores. This normalizes
+the server side: one commerce vocabulary, one portable operation surface with
+REST and GraphQL bindings, one event envelope, one webhook contract — so a
+backend or an analytics pipeline can verify purchases, read entitlements, and
+handle renewals, refunds, and entitlement changes from Apple, Google, Meta
+Horizon, and Amazon without parsing any store-native payload, and can replace
+the provider behind those calls without rewriting the integration.
+
+Nothing in this contract routes through infrastructure the OpenIAP project
+operates. Two parties exchange events directly, using a secret they share
+between themselves, and validate offline. The project distributes the contract;
+it does not sit in the path of anyone's commerce.
+
+**[Read the specification →](./SPEC.md)**
+
+## Choose your role
+
+A paywall specialist can supply the experience, a commerce service the purchase
+and access decisions, and an analytics platform the event processing. An
+integrated platform can supply several roles. Explore the [role map](https://openiap.dev/commerce-protocol#architecture)
+and [AI integration brief](https://openiap.dev/commerce-example/integration-brief.md)
+to connect your product to apps using OpenIAP. These product roles do not add
+protocol profiles or a universal paywall API.
+
+## Start implementing
+
+```sh
+npm install @hyodotdev/openiap-commerce-protocol
+```
+
+Or use `pnpm add`, `yarn add`, or `bun add` with the same package name.
+
+Give your AI the installed package's `SPEC.md`, `DESIGN.md`, and `generated/`
+artifacts. The package supplies the contract; your AI implements the backend.
+
+- **See what AI built:** the [recorded walkthrough](https://openiap.dev/commerce-protocol#build-walkthrough)
+  shows a real local HTTP + SQLite backend in six milestones, with captured
+  responses. The [IAPKit comparison](https://openiap.dev/commerce-protocol/implementation#iapkit) explains what was tested. Give the
+  [build brief](https://openiap.dev/commerce-example/build-brief.md)
+  to your AI to build the same flow in your own stack.
+- **Integrate your backend:** [Use a provider](https://openiap.dev/commerce-protocol/getting-started)
+  walks through discovery, verification, account binding, and entitlement reads.
+- **Build a provider:** [Build with AI](https://openiap.dev/commerce-protocol/implementation)
+  provides the brief, runnable example, and next implementation steps.
+  [DESIGN.md §5](./DESIGN.md#5-implementation-blueprint) contains the architecture
+  blueprint, storage keys, transaction boundaries, and recovery design.
+- **Try the contract locally:** from the repository root, run `bun install`,
+  then `cd specs/commerce-protocol && bun run quickstart`. The
+  [development walkthrough](https://github.com/hyodotdev/openiap/blob/main/specs/commerce-protocol/scripts/quickstart.mjs) uses the in-memory mock,
+  checks authorization and binding behavior, and runs REST/GraphQL conformance.
+  It uses fixture evidence, opens no HTTP server, and does not validate real
+  store purchases. Its Ajv and GraphQL dependencies come from this package's
+  development setup.
+
+[DESIGN.md](./DESIGN.md) explains why the boundaries sit where they do. It is
+background, not normative: where the two disagree, `SPEC.md` is right. It is
+also published as a PDF at
+<https://www.openiap.dev/commerce-protocol-rationale.pdf>.
+
+The contract sits between the stores and everything downstream of a backend:
+
+```mermaid
+flowchart TB
+  stores["Apple / Google / Meta / Amazon<br/>the stores"]
+  backend["A backend that implements this spec<br/>IAPKit, another provider, or the adopter's own — in any language<br/><br/>verify → normalize → lifecycle → entitle"]
+  app["shipped application<br/>verification role (§5)"]
+  server["the adopter's backend<br/>server role (§5)"]
+  consumers["any consumer<br/>data pipeline / CRM / analytics"]
+
+  stores -->|"store-native notifications and APIs"| backend
+  app -->|"verifyPurchase, providerCapabilities (§4.1, §4.6)<br/>over REST (§6) or GraphQL (§7)"| backend
+  server -->|"those, plus subscriptionStatus, entitlements, bindPurchase, eraseUser (§4.2–§4.5)<br/>server role only — never a shipped app"| backend
+  backend -->|"OpenIAP Commerce Protocol events (§9)"| consumers
+```
+
+## Reviewing a change
+
+Review only the authored surfaces, in this order:
+
+1. [`SPEC.md`](./SPEC.md) — behavior, operations, bindings, lifecycle,
+   transport, and compatibility.
+2. [`schema/`](./schema/) — the authored contract layers: wire structure, the
+   operation surface, and validation directives.
+   [`generated/commerce-protocol.graphql`](./generated/commerce-protocol.graphql)
+   is their generated single-file assembly (also exported at the package path
+   `@hyodotdev/openiap-commerce-protocol/commerce-protocol.graphql`).
+3. [`examples/`](./examples/) — representative documents and store mappings.
+4. [`vectors/signatures.json`](./vectors/signatures.json) — hand-authored
+   cryptographic truth cases.
+5. [`conformance/`](./conformance/) — the portable runner and its independent
+   mock provider.
+
+Ignore `generated/` during a human review. It is compiler output, kept only for
+validators and drift checks.
+
+## What ships here
+
+| Path                      | Contents                                                                    |
+| ------------------------- | --------------------------------------------------------------------------- |
+| `schema/`                 | Authored type, operation, and validation contract layers — edit these       |
+| `SPEC.md`                 | Normative meaning, operations, bindings, transport, and compatibility rules |
+| `DESIGN.md`               | Why the boundaries sit where they do — background, never normative          |
+| `generated/`              | Compiler output: schemas, binding manifests, OpenAPI, and vectors           |
+| `examples/`               | Canonical documents that must validate                                      |
+| `vectors/signatures.json` | Signature vectors every implementation must reproduce                       |
+| `conformance/`            | Portable conformance runner plus an IAPKit-free mock provider               |
+| `src/index.mjs`           | Runtime access to the generated schemas and their derived constants         |
+
+The `schema/` layers govern wire structure. Their custom directives retain
+patterns, bounds, maps, open objects, and conditional rules that standard SDL
+cannot express. `bun run build` compiles that source into the JSON Schemas a Go,
+Python, or other backend executes against incoming webhook bodies. `SPEC.md`
+governs meaning and transport.
+
+Do not add this SDL to `specs/client/schema-files.mjs`. `specs/client` owns the
+client purchase API and the SDK types compiled from it; this file independently
+owns the server-to-server commerce contract. Its Query and Mutation types are
+the portable server operation surface — compiled into the REST and GraphQL
+bindings, never into client SDK types — and it defines no Subscription root:
+the operation surface is bounded request/response by rule.
+
+## Receiving events
+
+An endpoint you register receives one JSON event per request. Verify the
+signature — `SPEC.md` §9.4.2 states the rule and `vectors/signatures.json` pins
+it — then handle the event; `SPEC.md` §9.5 walks a consumer end to end.
+
+Three rules that are easy to get wrong, all specified in detail in `SPEC.md`:
+
+- **Sign the bytes you received.** Re-serializing the JSON before verifying
+  changes key order and whitespace, and the signature will not match.
+- **Read `subscription.active`, not `state`.** A canceled subscription keeps
+  access until its paid period ends — `subscription.canceled` means auto-renew
+  was turned off, not that access was revoked.
+- **A missing amount means unknown.** It never means zero.
+
+## Calling a provider
+
+Start with the provider's capability descriptor. Every conforming provider
+supports discovery; its declared profiles determine which purchase, status,
+entitlement, binding, and erasure operations it supports. Check those profiles
+before calling an operation. REST and GraphQL bindings share one error-code
+space. `SPEC.md` §4–§8 define the surface and authorization rules.
+
+## Certifying a provider
+
+```js
+import Ajv from "ajv/dist/2020.js";
+import {
+  createRestAdapter,
+  createGraphqlAdapter,
+  runConformance,
+} from "@hyodotdev/openiap-commerce-protocol/conformance";
+
+const report = await runConformance({
+  adapters: [
+    createRestAdapter({ baseUrl, fetch, credentials }),
+    createGraphqlAdapter({ url: graphqlUrl, fetch, credentials }),
+  ],
+  Ajv,
+  // The same role-to-credential map the adapters use — required, so the
+  // runner can reject an error message that echoes a credential.
+  credentials,
+  // Required when your capability descriptor declares the events profile:
+  // your outbound webhook implementation, driven through SPEC.md §9's
+  // signing, verification, delivery, response, entitlement, and emission
+  // vectors.
+  eventsAdapter,
+});
+```
+
+The runner is offline, needs no hosted service, and imports no implementation;
+supply the Ajv 2020 class yourself, since the published runtime carries zero
+dependencies. It certifies the transport contract — never real store receipt
+validity (`SPEC.md` §11.3). A provider that declares the `events` profile must
+also pass an `eventsAdapter` covering the full `EventsAdapter` surface
+(`conformance/index.d.ts`); a signing-only adapter fails.
+
+## Validating
+
+```bash
+bun install
+bun run test
+```
+
+The suite recompiles every schema and binding artifact, validates every
+example, checks that each rejection case is actually rejected, reproduces
+every signature vector using an implementation written only from `SPEC.md`,
+and certifies an independent mock provider on both bindings.
+
+## Relationship to the rest of OpenIAP
+
+```
+       OpenIAP Commerce Protocol       ← this package: the server-side contract
+                     │
+      ┌──────────────┼──────────────┐
+      │              │              │
+   IAPKit      vendor backend   custom backend
+ (reference)
+      │              │              │
+      └──────────────┼──────────────┘
+                     ↓
+        normalized commerce events
+                     ↓
+      ┌──────────────┼──────────────┐
+      │              │              │
+    SaaS        analytics     enterprise
+```
+
+No box in that diagram is required to be operated by the OpenIAP project. An
+adopter may self-host IAPKit, use a hosted conforming provider, or implement the
+contract in the backend they already have — and a consumer supports _the
+specification_, so any of the three can feed it.
+
+## Status
+
+Implements protocol version 1.0. The event vocabulary,
+envelope, webhook contract, operation surface, REST and GraphQL bindings, and
+portable conformance runner are implemented and tested. `SPEC.md` §14 lists
+what is deliberately not in this version.
+
+## License
+
+MIT