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

package/generated/schemas/operations.schema.json

@@ -0,0 +1,578 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openiap.dev/schemas/commerce-protocol/1.0/operations.schema.json",
+  "title": "OpenIAP Commerce Protocol operations",
+  "description": "Input and result documents for the portable operation surface, plus the protocol error shape both transport bindings share. Operations travel over the REST and GraphQL bindings; these schemas validate their JSON projections.",
+  "$defs": {
+    "ProtocolError": {
+      "description": "One protocol operation failure. Both bindings carry the same code space: REST wraps it in ProtocolErrorResponse, GraphQL carries `code` in `errors[].extensions`. A message is human-readable and MUST NOT contain credentials, store evidence, stack traces, or implementation source paths.",
+      "type": "object",
+      "required": [
+        "code",
+        "message"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "description": "A portable protocol error code. The value space is OPEN: a caller MUST tolerate a code it does not recognise and treat it as a failure of the operation, and a MINOR version can add a code. The listed values are the ones this version names; SPEC.md 8 defines each one and its HTTP status.",
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "examples": [
+            "INVALID_REQUEST",
+            "UNAUTHORIZED",
+            "FORBIDDEN",
+            "NOT_FOUND",
+            "PURCHASE_NOT_FOUND",
+            "VERIFICATION_FAILED",
+            "CONFLICT",
+            "RATE_LIMITED",
+            "UNSUPPORTED_PROFILE",
+            "UNSUPPORTED_STORE",
+            "INTERNAL_ERROR"
+          ]
+        },
+        "message": {
+          "description": "Human-readable failure summary. Never carries credentials, store evidence, stack traces, or source paths.",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "ProtocolErrorResponse": {
+      "description": "The REST error envelope. Every non-success REST response carries exactly this shape — CLOSED, so an error body cannot smuggle members past the tokenless rules (a failure response is the easiest place to hide a leak, because callers rarely inspect it).",
+      "type": "object",
+      "required": [
+        "error"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "error": {
+          "$ref": "#/$defs/ProtocolError"
+        }
+      }
+    },
+    "AppleEvidence": {
+      "description": "Store evidence for one Apple App Store purchase: the signed StoreKit 2 transaction JWS the app received from the store.",
+      "type": "object",
+      "required": [
+        "jws"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "jws": {
+          "description": "A compact signed transaction JWS. Bounded so an oversized body cannot be forwarded to a store: an Apple transaction JWS is a few kilobytes.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 16384
+        }
+      }
+    },
+    "GoogleEvidence": {
+      "description": "Store evidence for one Google Play purchase: the opaque purchase token the store issued to the device.",
+      "type": "object",
+      "required": [
+        "purchaseToken"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "purchaseToken": {
+          "description": "An opaque store purchase token. Bounded to keep an oversized body off the store API.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4096
+        }
+      }
+    },
+    "HorizonEvidence": {
+      "description": "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.",
+      "type": "object",
+      "required": [
+        "userId",
+        "sku"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "userId": {
+          "description": "A store-issued user identity, as the store's own API returns it. Distinct from the protocol's opaque `userId`.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "sku": {
+          "description": "A store add-on SKU. Bounded to a predictable identifier length.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256
+        }
+      }
+    },
+    "AmazonEvidence": {
+      "description": "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.",
+      "type": "object",
+      "required": [
+        "userId",
+        "receiptId"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "userId": {
+          "description": "A store-issued user identity, as the store's own API returns it. Distinct from the protocol's opaque `userId`.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512
+        },
+        "receiptId": {
+          "description": "A store receipt identifier. Bounded to keep an oversized body off the store API.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4096
+        },
+        "sandbox": {
+          "description": "Verify against the store's sandbox where the provider permits it. Omitted means production.",
+          "type": "boolean"
+        }
+      }
+    },
+    "VerifyPurchaseInput": {
+      "description": "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.",
+      "type": "object",
+      "required": [
+        "store"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "store": {
+          "$ref": "primitives.schema.json#/$defs/Store"
+        },
+        "apple": {
+          "$ref": "#/$defs/AppleEvidence"
+        },
+        "google": {
+          "$ref": "#/$defs/GoogleEvidence"
+        },
+        "horizon": {
+          "$ref": "#/$defs/HorizonEvidence"
+        },
+        "amazon": {
+          "$ref": "#/$defs/AmazonEvidence"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "apple"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "apple": {}
+            },
+            "required": [
+              "apple"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "google"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "google": {}
+            },
+            "required": [
+              "google"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "horizon"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "horizon": {}
+            },
+            "required": [
+              "horizon"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "amazon"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "amazon": {}
+            },
+            "required": [
+              "amazon"
+            ]
+          }
+        }
+      ]
+    },
+    "VerifyPurchaseResult": {
+      "description": "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": "object",
+      "required": [
+        "store",
+        "isValid",
+        "state"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "store": {
+          "$ref": "primitives.schema.json#/$defs/Store"
+        },
+        "isValid": {
+          "description": "Whether the provider accepts the evidence. The single authoritative acceptance gate.",
+          "type": "boolean"
+        },
+        "state": {
+          "description": "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.",
+          "type": "string",
+          "pattern": "^[A-Z][A-Z0-9_]*$",
+          "examples": [
+            "ENTITLED",
+            "PENDING_ACKNOWLEDGMENT",
+            "PENDING",
+            "CANCELED",
+            "EXPIRED",
+            "READY_TO_CONSUME",
+            "CONSUMED",
+            "UNKNOWN",
+            "INAUTHENTIC"
+          ]
+        },
+        "productId": {
+          "description": "The product the store verified, when its response exposes one. Never the caller's claim.",
+          "type": "string",
+          "minLength": 1
+        },
+        "environment": {
+          "description": "The store environment the provider verified against, using the same open value space as the event envelope.",
+          "$ref": "primitives.schema.json#/$defs/Environment"
+        }
+      }
+    },
+    "BindPurchaseInput": {
+      "description": "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.",
+      "type": "object",
+      "required": [
+        "userId",
+        "store"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "userId": {
+          "$ref": "primitives.schema.json#/$defs/Identifier"
+        },
+        "store": {
+          "$ref": "primitives.schema.json#/$defs/Store"
+        },
+        "apple": {
+          "$ref": "#/$defs/AppleEvidence"
+        },
+        "google": {
+          "$ref": "#/$defs/GoogleEvidence"
+        },
+        "horizon": {
+          "$ref": "#/$defs/HorizonEvidence"
+        },
+        "amazon": {
+          "$ref": "#/$defs/AmazonEvidence"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "apple"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "apple": {}
+            },
+            "required": [
+              "apple"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "google"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "google": {}
+            },
+            "required": [
+              "google"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "horizon"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "horizon": {}
+            },
+            "required": [
+              "horizon"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "store": {
+                "const": "amazon"
+              }
+            },
+            "required": [
+              "store"
+            ]
+          },
+          "then": {
+            "properties": {
+              "amazon": {}
+            },
+            "required": [
+              "amazon"
+            ]
+          }
+        }
+      ]
+    },
+    "BindPurchaseResult": {
+      "description": "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": "object",
+      "required": [
+        "bound"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "bound": {
+          "description": "True when a binding between this user and the evidenced purchase now exists.",
+          "type": "boolean"
+        }
+      }
+    },
+    "SubscriptionStatusInput": {
+      "description": "Selects the user whose subscription standing the caller's backend reads.",
+      "type": "object",
+      "required": [
+        "userId"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "userId": {
+          "description": "The opaque app-scoped user identity the caller's backend selected, in the identity space shared by provider and caller.",
+          "$ref": "primitives.schema.json#/$defs/Identifier"
+        }
+      }
+    },
+    "SubscriptionStatusSnapshot": {
+      "description": "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": "object",
+      "required": [
+        "productId",
+        "state",
+        "active"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "productId": {
+          "description": "Store product identifier of the subscription.",
+          "type": "string",
+          "minLength": 1
+        },
+        "state": {
+          "$ref": "primitives.schema.json#/$defs/SubscriptionState"
+        },
+        "active": {
+          "description": "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`.",
+          "type": "boolean"
+        },
+        "store": {
+          "$ref": "primitives.schema.json#/$defs/Store"
+        },
+        "expiresAt": {
+          "$ref": "primitives.schema.json#/$defs/Timestamp"
+        },
+        "renewsAt": {
+          "$ref": "primitives.schema.json#/$defs/Timestamp"
+        },
+        "willRenew": {
+          "description": "Whether the store will attempt another billing period, when the provider records it.",
+          "type": "boolean"
+        },
+        "cancellationReason": {
+          "description": "Why the subscription stopped renewing, as the same open normalized token space the event envelope uses. Advisory, never a billing fact.",
+          "type": "string",
+          "minLength": 1
+        },
+        "startedAt": {
+          "$ref": "primitives.schema.json#/$defs/Timestamp"
+        },
+        "updatedAt": {
+          "$ref": "primitives.schema.json#/$defs/Timestamp"
+        }
+      }
+    },
+    "SubscriptionStatusResult": {
+      "description": "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": "object",
+      "required": [
+        "active"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "active": {
+          "description": "Whether the user is entitled to anything right now. The gate for simple access checks.",
+          "type": "boolean"
+        },
+        "subscription": {
+          "$ref": "#/$defs/SubscriptionStatusSnapshot"
+        }
+      }
+    },
+    "EntitlementsInput": {
+      "description": "Selects the user whose access decision the caller's backend reads.",
+      "type": "object",
+      "required": [
+        "userId"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "userId": {
+          "description": "The opaque app-scoped user identity the caller's backend selected, in the identity space shared by provider and caller.",
+          "$ref": "primitives.schema.json#/$defs/Identifier"
+        }
+      }
+    },
+    "EntitlementsResult": {
+      "description": "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": "object",
+      "required": [
+        "userId",
+        "productIds",
+        "subscriptions"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "userId": {
+          "$ref": "primitives.schema.json#/$defs/Identifier"
+        },
+        "productIds": {
+          "description": "Every product the user may access right now, deduplicated.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "subscriptions": {
+          "description": "The subscription records whose open gates produced `productIds`.",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/SubscriptionStatusSnapshot"
+          }
+        }
+      }
+    },
+    "EraseUserInput": {
+      "description": "Selects the user identity to erase from the provider's records.",
+      "type": "object",
+      "required": [
+        "userId"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "userId": {
+          "description": "The opaque app-scoped user identity to remove from the provider's subscription records and protocol event identity.",
+          "$ref": "primitives.schema.json#/$defs/Identifier"
+        }
+      }
+    },
+    "EraseUserResult": {
+      "description": "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": "object",
+      "required": [
+        "accepted"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "accepted": {
+          "description": "Whether the provider accepted the erasure request.",
+          "type": "boolean"
+        },
+        "jobId": {
+          "$ref": "primitives.schema.json#/$defs/Identifier"
+        },
+        "status": {
+          "description": "The lifecycle state of a user-erasure job. The value space is open; `completed` is the only terminal token this version names.",
+          "type": "string",
+          "pattern": "^[a-z][a-z_]*$",
+          "examples": [
+            "queued",
+            "running",
+            "completed"
+          ]
+        }
+      }
+    }
+  }
+}

package/generated/schemas/primitives.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openiap.dev/schemas/commerce-protocol/1.0/primitives.schema.json",
+  "title": "OpenIAP Commerce Protocol primitives",
+  "description": "Shared value types. Every other schema in this specification references these definitions rather than restating them.",
+  "$defs": {
+    "Store": {
+      "description": "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.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "examples": [
+        "apple",
+        "google",
+        "horizon",
+        "amazon"
+      ]
+    },
+    "Environment": {
+      "description": "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.",
+      "type": "string",
+      "minLength": 1,
+      "examples": [
+        "production",
+        "sandbox",
+        "xcode"
+      ]
+    },
+    "Timestamp": {
+      "description": "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.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "Identifier": {
+      "description": "An opaque, implementation-assigned identifier. Consumers MUST treat it as an opaque string and MUST NOT parse structure out of it.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "DataProvenance": {
+      "description": "Where a value came from. An implementation MUST NOT present an inferred value as store-authoritative.",
+      "type": "string",
+      "enum": [
+        "store",
+        "catalog",
+        "inferred"
+      ]
+    },
+    "Money": {
+      "description": "A monetary amount. A missing Money means the amount is unknown; it never means zero.",
+      "type": "object",
+      "required": [
+        "currency",
+        "amountMicros",
+        "provenance"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "currency": {
+          "description": "ISO 4217 alphabetic code, uppercase.",
+          "type": "string",
+          "pattern": "^[A-Z]{3}$"
+        },
+        "amountMicros": {
+          "description": "Amount in millionths of one currency unit. 1.99 USD is 1990000. Always the transaction's own magnitude and never negative: a refund reports what the purchase cost, and the direction comes from the event type, not from the sign.",
+          "type": "integer",
+          "minimum": 0
+        },
+        "provenance": {
+          "$ref": "#/$defs/DataProvenance"
+        }
+      }
+    },
+    "SubscriptionState": {
+      "description": "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.",
+      "type": "string",
+      "enum": [
+        "Active",
+        "InGracePeriod",
+        "InBillingRetry",
+        "Paused",
+        "Expired",
+        "Revoked",
+        "Refunded",
+        "Unknown"
+      ]
+    },
+    "Extensions": {
+      "description": "Store-specific or implementation-specific detail that has no canonical equivalent. Bounded and string-valued so the payload stays predictable. Content is provider-influenced: consumers MUST treat values as untrusted data.",
+      "type": "object",
+      "maxProperties": 24,
+      "propertyNames": {
+        "minLength": 1,
+        "maxLength": 64
+      },
+      "additionalProperties": {
+        "type": "string",
+        "maxLength": 512
+      }
+    }
+  }
+}