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

package/generated/bindings/operations.graphql

@@ -0,0 +1,366 @@
+# Executable GraphQL projection of the OpenIAP Commerce Protocol 1.0
+# operation surface. Generated from commerce-protocol.graphql — do not edit.
+# A conforming GraphQL binding defines everything this projection
+# defines, exactly as defined; a compatible MINOR may extend it
+# additively. Introspection, where enabled, must agree with the schema
+# served.
+
+"""
+The commerce platform that is authoritative for the purchase. This is a store, not a device platform: one device platform can host several stores. The value space is OPEN. The listed values are the stores this version names, but an implementation that observes commerce on another platform MUST be able to emit it, and a consumer MUST accept and preserve an unrecognised store opaquely rather than reject the event. Use a lowercase, stable, unambiguous token.
+"""
+scalar Store
+
+"""
+The store environment the purchase belongs to. The value space is open: receivers MUST accept and preserve an unrecognised value opaquely and MUST NOT reject an event because of it.
+"""
+scalar Environment
+
+"""
+An instant, as integer milliseconds since the Unix epoch, UTC. Every timestamp in this specification uses this encoding. The one exception is the transport signature timestamp, which is in seconds; see the webhook section of SPEC.md.
+"""
+scalar Timestamp
+
+"""
+An opaque, implementation-assigned identifier. Consumers MUST treat it as an opaque string and MUST NOT parse structure out of it.
+"""
+scalar Identifier
+
+"""
+The lifecycle state of a subscription. This is a state, not an event, and it does not by itself decide entitlement — see Entitlement in SPEC.md. These members are PascalCase while event types are lowercase-dotted; the inconsistency is inherited from the deployed 1.0 wire format and is recorded in CONVENTION.md rather than silently corrected, because changing it would break receivers already decoding it.
+"""
+enum SubscriptionState {
+  Active
+  InGracePeriod
+  InBillingRetry
+  Paused
+  Expired
+  Revoked
+  Refunded
+  Unknown
+}
+
+scalar StoreCapabilitiesMap
+
+"""
+What an implementation supports: the specification version it speaks, the event types it can emit, and what it can actually observe per store. This is the document a consumer, an operator, or a tool reads to determine compatibility without guessing and without reading prose. It contains no commerce data.
+"""
+type ProviderCapabilities {
+  """
+  OpenIAP Commerce Protocol version this declaration was written against, as MAJOR.MINOR.
+  """
+  specVersion: MajorMinor!
+  """
+  Free-form name and version of the backend making this declaration. Present so an operator can tell two backends apart; it carries no normative meaning.
+  """
+  implementation: Implementation
+  """
+  Event types this implementation can emit. A consumer uses it to know which lifecycle signals to expect; absence of a type here means this implementation never produces it, which is different from a type that simply has not occurred yet.
+  """
+  eventTypes: [NamespacedEventType!]!
+  """
+  Keyed by store, using the same open value space as the event envelope. An implementation declares only the stores it actually integrates.
+  """
+  stores: StoreCapabilitiesMap!
+  """
+  Operation profiles this implementation serves, keyed by profile name with the profile version as the value. This version names `verification`, `entitlements`, `events`, and `accountLifecycle`; the key space is open, so a consumer MUST ignore a profile it does not recognise. An implementation MUST declare only profiles it implements and passes conformance for, and MUST NOT declare a profile it partially implements. Absent on a descriptor from an events-only emitter that predates the operation surface.
+  """
+  profiles: ProfileVersionMap
+  """
+  Transport bindings this implementation serves for the declared profiles, keyed by binding name with the binding version as the value. This version names `rest` and `graphql`; the key space is open. Declaring a binding means every declared profile operation is reachable over it. An implementation MAY serve one binding only. Absent on a descriptor from an events-only emitter.
+  """
+  bindings: BindingVersionMap
+}
+
+scalar ProfileVersionMap
+
+scalar BindingVersionMap
+
+"""
+Free-form name and version of the backend making this declaration. Present so an operator can tell two backends apart; it carries no normative meaning.
+"""
+type Implementation {
+  """
+  Name of the backend making this declaration, for an operator reading a descriptor without knowing where it came from.
+  """
+  name: NonEmptyString
+  """
+  Version of that backend, when it publishes one. Not a specification version — that is `specVersion`.
+  """
+  version: NonEmptyString
+}
+
+"""
+The verification verdict for one piece of purchase evidence, as a normalized token. This is the purchase-validation axis SPEC.md 2.3 warns about — a CANCELED verification verdict and a canceled-but-still-entitled subscription are different facts. The value space is OPEN: a caller MUST tolerate a token it does not know and gate on `isValid` alone.
+"""
+scalar PurchaseVerificationState
+
+"""
+The lifecycle state of a user-erasure job. The value space is open; `completed` is the only terminal token this version names.
+"""
+scalar ErasureJobStatus
+
+"""
+A compact signed transaction JWS. Bounded so an oversized body cannot be forwarded to a store: an Apple transaction JWS is a few kilobytes.
+"""
+scalar AppleJws
+
+"""
+An opaque store purchase token. Bounded to keep an oversized body off the store API.
+"""
+scalar GooglePurchaseToken
+
+"""
+A store-issued user identity, as the store's own API returns it. Distinct from the protocol's opaque `userId`.
+"""
+scalar StoreUserIdentity
+
+"""
+A store add-on SKU. Bounded to a predictable identifier length.
+"""
+scalar StoreSku
+
+"""
+A store receipt identifier. Bounded to keep an oversized body off the store API.
+"""
+scalar StoreReceiptId
+
+"""
+Store evidence for one Apple App Store purchase: the signed StoreKit 2 transaction JWS the app received from the store.
+"""
+input AppleEvidence {
+  """
+  The compact signed transaction JWS, verbatim as the store handed it to the app.
+  """
+  jws: AppleJws!
+}
+
+"""
+Store evidence for one Google Play purchase: the opaque purchase token the store issued to the device.
+"""
+input GoogleEvidence {
+  """
+  The opaque purchase token, verbatim as the store issued it to the device.
+  """
+  purchaseToken: GooglePurchaseToken!
+}
+
+"""
+Store evidence for one Meta Horizon (Quest) entitlement. Horizon issues no server-verifiable receipt, so verification identifies the entitlement by user and SKU; the provider holds the store credentials.
+"""
+input HorizonEvidence {
+  """
+  The store's own user identity for the entitlement holder — not the protocol's opaque `userId`.
+  """
+  userId: StoreUserIdentity!
+  """
+  The add-on SKU as configured in the store's developer dashboard.
+  """
+  sku: StoreSku!
+}
+
+"""
+Store evidence for one Amazon Appstore purchase, as returned by the Amazon SDK. `sandbox` selects the RVS sandbox for App Tester receipts where the provider permits it.
+"""
+input AmazonEvidence {
+  """
+  The store's own user identity from the purchase response — not the protocol's opaque `userId`.
+  """
+  userId: StoreUserIdentity!
+  """
+  The receipt identifier from the purchase or purchase-updates response.
+  """
+  receiptId: StoreReceiptId!
+  """
+  Verify against the store's sandbox where the provider permits it. Omitted means production.
+  """
+  sandbox: Boolean
+}
+
+"""
+One purchase's store evidence, discriminated by `store`. The store space stays open: a provider that does not integrate the named store rejects the call with UNSUPPORTED_STORE rather than failing schema validation, so a future store is a MINOR evidence-member addition, not a breaking change. For each store this version names, the matching evidence member is required.
+"""
+input VerifyPurchaseInput {
+  store: Store!
+  apple: AppleEvidence
+  google: GoogleEvidence
+  horizon: HorizonEvidence
+  amazon: AmazonEvidence
+}
+
+"""
+The verification verdict. `isValid` is the authoritative acceptance gate: a caller MUST read it and MUST NOT re-derive acceptance from `state`. A verdict is a statement about the evidence at verification time, never an account mutation — verification binds no user.
+"""
+type VerifyPurchaseResult {
+  store: Store!
+  """
+  Whether the provider accepts the evidence. The single authoritative acceptance gate.
+  """
+  isValid: Boolean!
+  state: PurchaseVerificationState!
+  """
+  The product the store verified, when its response exposes one. Never the caller's claim.
+  """
+  productId: NonEmptyString
+  """
+  The store environment the provider verified against, using the same open value space as the event envelope.
+  """
+  environment: Environment
+}
+
+"""
+Connects verified store evidence to the adopter's own opaque user identity. Binding is a server-side account mutation: only the server role may call it, and possession of a purchase token is deliberately not proof of ownership — a provider MUST refuse to move an existing binding through this operation.
+"""
+input BindPurchaseInput {
+  userId: Identifier!
+  store: Store!
+  apple: AppleEvidence
+  google: GoogleEvidence
+  horizon: HorizonEvidence
+  amazon: AmazonEvidence
+}
+
+"""
+Whether a binding now exists between this user and the evidenced purchase. `bound: false` covers every non-binding outcome — unknown evidence, evidence bound to a different user, or a store the provider cannot bind — without distinguishing them, so the operation cannot be used to probe whether someone else's purchase exists. Re-binding the same user to the same evidence is idempotent and reports `bound: true`.
+"""
+type BindPurchaseResult {
+  """
+  True when a binding between this user and the evidenced purchase now exists.
+  """
+  bound: Boolean!
+}
+
+"""
+Selects the user whose subscription standing the caller's backend reads.
+"""
+input SubscriptionStatusInput {
+  """
+  The opaque app-scoped user identity the caller's backend selected, in the identity space shared by provider and caller.
+  """
+  userId: Identifier!
+}
+
+"""
+One subscription as the provider currently records it, shaped for a server-side read. It is tokenless by construction: this object is CLOSED, so the schema itself rejects any member beyond those listed — no purchase token, store transaction identity, signed receipt, or provider-internal record identifier can appear, and the response is safe to hold in a developer backend.
+"""
+type SubscriptionStatusSnapshot {
+  """
+  Store product identifier of the subscription.
+  """
+  productId: NonEmptyString!
+  state: SubscriptionState!
+  """
+  The entitlement gate for this subscription, evaluated with the predicate in SPEC.md 2.3 at the provider's read time. A caller gates access on this member, never on `state`.
+  """
+  active: Boolean!
+  store: Store
+  expiresAt: Timestamp
+  renewsAt: Timestamp
+  """
+  Whether the store will attempt another billing period, when the provider records it.
+  """
+  willRenew: Boolean
+  """
+  Why the subscription stopped renewing, as the same open normalized token space the event envelope uses. Advisory, never a billing fact.
+  """
+  cancellationReason: NonEmptyString
+  startedAt: Timestamp
+  updatedAt: Timestamp
+}
+
+"""
+The user's current subscription standing. `active` answers the gate for the user as a whole; `subscription` is the most relevant record — the current entitling subscription when one exists, otherwise the provider's most recent record as context. It is omitted when the provider has no record for this user. A provider that cannot enumerate the user's records completely MUST fail the operation instead of answering from a partial read.
+"""
+type SubscriptionStatusResult {
+  """
+  Whether the user is entitled to anything right now. The gate for simple access checks.
+  """
+  active: Boolean!
+  subscription: SubscriptionStatusSnapshot
+}
+
+"""
+Selects the user whose access decision the caller's backend reads.
+"""
+input EntitlementsInput {
+  """
+  The opaque app-scoped user identity the caller's backend selected, in the identity space shared by provider and caller.
+  """
+  userId: Identifier!
+}
+
+"""
+Every product the user may access right now, with the entitling subscription records. Unknown, expired, and ambiguous records contribute nothing: a product appears only when its gate is open at the provider's read time. A provider that cannot enumerate the user's records completely MUST fail the operation instead of answering from a partial read.
+"""
+type EntitlementsResult {
+  userId: Identifier!
+  """
+  Every product the user may access right now, deduplicated.
+  """
+  productIds: [NonEmptyString!]!
+  """
+  The subscription records whose open gates produced `productIds`.
+  """
+  subscriptions: [SubscriptionStatusSnapshot!]!
+}
+
+"""
+Selects the user identity to erase from the provider's records.
+"""
+input EraseUserInput {
+  """
+  The opaque app-scoped user identity to remove from the provider's subscription records and protocol event identity.
+  """
+  userId: Identifier!
+}
+
+"""
+Acknowledgement of an erasure request. Erasure removes the user identity from the provider's own records and event store; it is asynchronous where the provider processes it as a job, and re-requesting the same user is idempotent — it reports the current job rather than failing. A provider CANNOT unsend events: copies already delivered to the caller's own systems are the caller's responsibility to erase.
+"""
+type EraseUserResult {
+  """
+  Whether the provider accepted the erasure request.
+  """
+  accepted: Boolean!
+  jobId: Identifier
+  status: ErasureJobStatus
+}
+
+scalar MajorMinor
+
+scalar NonEmptyString
+
+scalar NamespacedEventType
+
+type Query {
+  """
+  What this provider implements: protocol version, profiles, bindings, and per-store capability. Public and free of commerce data, so a consumer or a conformance runner reads it without credentials and without any central registry.
+  """
+  providerCapabilities: ProviderCapabilities!
+
+  """
+  A developer backend reads one authenticated user's subscription standing. Server role only: a shipped app must not be able to walk arbitrary user identities, which is why the verification role is refused here.
+  """
+  subscriptionStatus(input: SubscriptionStatusInput!): SubscriptionStatusResult!
+
+  """
+  A developer backend reads one authenticated user's access decision. Server role only, and fail-close: anything the provider cannot classify as currently entitled is absent from the answer.
+  """
+  entitlements(input: EntitlementsInput!): EntitlementsResult!
+}
+
+type Mutation {
+  """
+  Verifies store evidence and returns the verdict. The verification role suffices: this operation binds no user, reads no account, and repeating it with the same evidence is safe. VERIFICATION_FAILED means the provider could not obtain a verdict — it never stands in for the store rejecting the evidence, which is a successful result with `isValid: false`.
+  """
+  verifyPurchase(input: VerifyPurchaseInput!): VerifyPurchaseResult!
+
+  """
+  Binds a verified purchase to the adopter's opaque user identity. Server role only; retrying is idempotent.
+  """
+  bindPurchase(input: BindPurchaseInput!): BindPurchaseResult!
+
+  """
+  Removes a user identity from the provider's subscription records and protocol event identity. Server role only; re-requesting the same user is idempotent and reports the current job.
+  """
+  eraseUser(input: EraseUserInput!): EraseUserResult!
+}