checkpoint before checking out feature/account-managed-gateway

docs/openapi.yaml

@@ -75,7 +75,7 @@ paths:
         default: { $ref: "#/components/responses/Error" }
   /v1/account:
     get:
-      summary: Return the minimal account profile
+      summary: Return the account profile
       responses:
         "200":
           description: Account profile
@@ -83,6 +83,20 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/AccountEnvelope" }
         default: { $ref: "#/components/responses/Error" }
+    patch:
+      summary: Update the current account nickname
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/UpdateAccountProfileRequest" }
+      responses:
+        "200":
+          description: Updated account profile
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/AccountEnvelope" }
+        default: { $ref: "#/components/responses/Error" }
     delete:
       summary: Reauthenticate with Apple, delete the account, and revoke authorization
       requestBody:
@@ -112,7 +126,7 @@ paths:
         default: { $ref: "#/components/responses/Error" }
   /v1/credits/balance:
     get:
-      summary: Return available integer credits
+      summary: Return available and consumed integer credits
       responses:
         "200":
           description: Credit account
@@ -146,6 +160,44 @@ paths:
                 type: array
                 items: { type: object, additionalProperties: true }
         default: { $ref: "#/components/responses/Error" }
+  /v1/storekit/products:
+    get:
+      summary: Return enabled consumable credit products
+      description: |
+        Current catalog: `500tks` grants 500 credits, `1500tks` grants 1,500
+        credits, and `3000tks` grants 3,000 credits. Localized prices are
+        supplied by StoreKit.
+      responses:
+        "200":
+          description: StoreKit credit product catalog
+          content:
+            application/json:
+              schema:
+                type: array
+                items: { $ref: "#/components/schemas/StoreKitProduct" }
+        default: { $ref: "#/components/responses/Error" }
+  /v1/storekit/transactions:
+    post:
+      summary: Verify an App Store transaction and idempotently grant credits
+      description: |
+        Submit the StoreKit 2 `VerificationResult.jwsRepresentation` before
+        finishing the consumable transaction. The purchase must include an
+        `appAccountToken` equal to the authenticated account UUID. Replaying
+        the same App Store transaction returns the original grant.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/StoreKitTransactionRequest" }
+      responses:
+        "200":
+          description: Verified purchase grant or idempotent replay
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/StoreKitPurchase" }
+        "409": { $ref: "#/components/responses/Error" }
+        "422": { $ref: "#/components/responses/Error" }
+        default: { $ref: "#/components/responses/Error" }
   /v1/referrals:
     get:
       summary: List invitees without exposing their Apple identity
@@ -162,7 +214,7 @@ paths:
         default: { $ref: "#/components/responses/Error" }
   /v1/referrals/me:
     get:
-      summary: Return the current referral code and binding
+      summary: Return the referral profile and idempotently provision its invite code
       responses:
         "200":
           description: Referral profile
@@ -1088,6 +1140,10 @@ components:
         nonce:
           type: string
           description: Raw nonce whose lowercase SHA-256 hex digest was sent to Apple.
+        displayName:
+          type: ["string", "null"]
+          maxLength: 128
+          description: Optional first-authorization Apple name used only to seed the nickname.
         deviceCheckToken:
           type: ["string", "null"]
           description: Ephemeral DeviceCheck token; never persisted in plaintext.
@@ -1143,12 +1199,24 @@ components:
       properties:
         id: { type: string, format: uuid }
         createdAtEpochSeconds: { type: integer, format: int64 }
+        displayName:
+          type: ["string", "null"]
+          maxLength: 64
     AccountEnvelope:
       type: object
       additionalProperties: false
       required: [data]
       properties:
         data: { $ref: "#/components/schemas/Account" }
+    UpdateAccountProfileRequest:
+      type: object
+      additionalProperties: false
+      required: [displayName]
+      properties:
+        displayName:
+          type: string
+          minLength: 1
+          maxLength: 64
     DeleteAccountRequest:
       type: object
       additionalProperties: false
@@ -1160,10 +1228,15 @@ components:
     CreditAccount:
       type: object
       additionalProperties: true
-      required: [userId, balance]
+      required: [userId, balance, lifetimeUsed]
       properties:
         userId: { type: string, format: uuid }
         balance: { type: integer, format: int64, minimum: 0 }
+        lifetimeUsed:
+          type: integer
+          format: int64
+          minimum: 0
+          description: Settled usage minus credits returned by refunds
     LedgerEntry:
       type: object
       additionalProperties: true
@@ -1172,6 +1245,35 @@ components:
         id: { type: string, format: uuid }
         amountDelta: { type: integer, format: int64 }
         balanceAfter: { type: integer, format: int64, minimum: 0 }
+    StoreKitProduct:
+      type: object
+      additionalProperties: false
+      required: [productId, credits]
+      properties:
+        productId:
+          type: string
+          enum: [500tks, 1500tks, 3000tks]
+        credits: { type: integer, format: int64, minimum: 1 }
+    StoreKitTransactionRequest:
+      type: object
+      additionalProperties: false
+      required: [signedTransaction]
+      properties:
+        signedTransaction:
+          type: string
+          minLength: 100
+          maxLength: 32768
+          description: StoreKit 2 VerificationResult.jwsRepresentation
+    StoreKitPurchase:
+      type: object
+      additionalProperties: false
+      required: [transactionId, productId, creditsGranted, balanceAfter, replayed]
+      properties:
+        transactionId: { type: string, pattern: "^[0-9]{1,64}$" }
+        productId: { type: string, minLength: 3, maxLength: 128 }
+        creditsGranted: { type: integer, format: int64, minimum: 1 }
+        balanceAfter: { type: integer, format: int64, minimum: 0 }
+        replayed: { type: boolean }
     AppleAppSiteAssociation:
       type: object
       additionalProperties: false