@nasebanal/cli 0.1.0 → 0.3.0

package/specs/account.yaml

@@ -1,10 +1,8 @@
 openapi: 3.0.3
 info:
   title: NASEBANAL Account API
-  description: >-
-    Centralized user and billing management API for NASEBANAL applications. Manages user profiles, per-service
-    subscriptions, Stripe billing, and Personal Access Tokens (PAT).
-  version: 1.4.0
+  description: Centralized user and billing management API for NASEBANAL applications. Manages user profiles, per-service subscriptions, Stripe billing, and Personal Access Tokens (PAT).
+  version: 1.5.1
   contact:
     name: NASEBANAL
     url: https://www.nasebanal.com
@@ -24,7 +22,7 @@ paths:
       description: Returns the health status of the API.
       security: []
       responses:
-        '200':
+        "200":
           description: API is healthy
           content:
             application/json:
@@ -44,34 +42,26 @@ paths:
       summary: Get current user profile
       description: Returns the authenticated user's profile information including subscription details.
       responses:
-        '200':
+        "200":
           description: User profile
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/UserResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                $ref: "#/components/schemas/UserResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
     delete:
       tags:
         - User
       summary: Delete account
-      description: >-
-        Permanently deletes the authenticated user's account and every service's data for it: Recorder records, tags and
-        media, Target goals, shares on both sides, organization memberships, and API tokens. An active personal
-        subscription is cancelled at Stripe as part of the same call.
+      description: |-
+        Permanently deletes the authenticated user's account and every service's data for it: Recorder records, tags and media, Target goals, shares on both sides, organization memberships, and API tokens. An active personal subscription is cancelled at Stripe as part of the same call.
 
+        Irreversible — there is no soft-delete or reactivation. Callers must confirm intent before invoking, and must send the user through logout afterwards: their access token stays cryptographically valid but no longer resolves to an account, so a subsequent authenticated request would provision a brand-new empty user.
 
-        Irreversible — there is no soft-delete or reactivation. Callers must confirm intent before invoking, and must
-        send the user through logout afterwards: their access token stays cryptographically valid but no longer resolves
-        to an account, so a subsequent authenticated request would provision a brand-new empty user.
-
-
-        Refused with `409` while the caller is the only administrator of an organization that still has other members;
-        the organization must be handed over or deleted first. `502` means nothing was deleted (a downstream service
-        could not be purged) and the request can safely be retried.
+        Refused with `409` while the caller is the only administrator of an organization that still has other members; the organization must be handed over or deleted first. `502` means nothing was deleted (a downstream service could not be purged) and the request can safely be retried.
       responses:
-        '200':
+        "200":
           description: Account deleted
           content:
             application/json:
@@ -83,7 +73,8 @@ paths:
                 properties:
                   success:
                     type: boolean
-                    enum: [true]
+                    enum:
+                      - true
                   data:
                     type: object
                     required:
@@ -92,7 +83,8 @@ paths:
                     properties:
                       deleted:
                         type: boolean
-                        enum: [true]
+                        enum:
+                          - true
                       user_id:
                         type: integer
                       organizations_deleted:
@@ -102,30 +94,27 @@ paths:
                         type: integer
                       auth0_identity_deleted:
                         type: boolean
-                        description: >-
-                          Whether the Auth0 identity was removed as well. False when the API has no Management API
-                          credentials configured — the account data is still fully deleted, but signing in again creates
-                          a new empty account.
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
+                        description: Whether the Auth0 identity was removed as well. False when the API has no Management API credentials configured — the account data is still fully deleted, but signing in again creates a new empty account.
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
           description: Service accounts cannot be deleted through this endpoint
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '409':
+                $ref: "#/components/schemas/Error"
+        "409":
           description: The caller is the last administrator of an organization that still has members
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-        '502':
+                $ref: "#/components/schemas/Error"
+        "502":
           description: A downstream service could not be purged — nothing was deleted
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
+                $ref: "#/components/schemas/Error"
   /api/v1/me/profile:
     put:
       tags:
@@ -137,16 +126,16 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/UpdateProfileInput'
+              $ref: "#/components/schemas/UpdateProfileInput"
       responses:
-        '200':
+        "200":
           description: Profile updated
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/UserResponse'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                $ref: "#/components/schemas/UserResponse"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/me/accept-terms:
     post:
       tags:
@@ -154,60 +143,28 @@ paths:
       summary: Accept terms of service
       description: Records the user's acceptance of the terms of service.
       responses:
-        '200':
+        "200":
           description: Terms accepted
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
                       tos_accepted_at:
                         type: string
                         format: date-time
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-  /api/v1/me/subscription:
-    x-internal: true
-    get:
-      tags:
-        - Subscriptions
-      summary: Get subscription info (legacy)
-      description: Returns the authenticated user's legacy subscription information.
-      responses:
-        '200':
-          description: Subscription info
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: object
-                    properties:
-                      plan:
-                        type: string
-                        enum:
-                          - free
-                          - pro
-                          - family
-                          - enterprise
-                      subscription_id:
-                        type: string
-                      subscription_status:
-                        type: string
-                        enum:
-                          - active
-                          - canceled
-                          - past_due
-                          - trialing
-                      subscription_expires_at:
-                        type: string
-                        format: date-time
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/me/subscriptions:
     get:
       tags:
@@ -215,19 +172,26 @@ paths:
       summary: Get all per-service subscriptions
       description: Returns all per-service subscriptions for the authenticated user.
       responses:
-        '200':
+        "200":
           description: List of service subscriptions
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: array
                     items:
-                      $ref: '#/components/schemas/ServiceSubscription'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                      $ref: "#/components/schemas/ServiceSubscription"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/me/subscriptions/{serviceId}:
     get:
       tags:
@@ -241,114 +205,26 @@ paths:
           schema:
             type: string
       responses:
-        '200':
+        "200":
           description: Service subscription
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/ServiceSubscription'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
-  /api/v1/stripe/checkout:
-    x-internal: true
-    post:
-      tags:
-        - Stripe
-      summary: Create Stripe checkout session
-      description: Creates a new Stripe checkout session for subscription purchase.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - plan
-              properties:
-                plan:
-                  type: string
-                  enum: [pro, family]
-                  description: Target subscription plan.
-                serviceId:
-                  type: string
-                  description: Service the subscription applies to (defaults to "default").
-                currency:
-                  type: string
-                  enum: [jpy, usd]
-                  default: jpy
-                  description: >-
-                    Billing currency for the new subscription; selects the matching
-                    per-currency Stripe Price. Defaults to jpy when omitted. Stripe
-                    locks a customer to this currency on first payment, so it only
-                    applies to the initial checkout.
-                returnUrl:
-                  type: string
-                  description: >-
-                    Locale-aware URL Stripe returns the user to; the result query
-                    string (?upgrade=success&plan=…&serviceId=…) is appended by the API.
-      responses:
-        '200':
-          description: Checkout session created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: object
-                    properties:
-                      url:
-                        type: string
-                        description: Stripe checkout session URL
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-  /api/v1/stripe/change-plan:
-    x-internal: true
-    post:
-      tags:
-        - Stripe
-      summary: Change subscription plan
-      description: Changes the authenticated user's subscription plan.
-      responses:
-        '200':
-          description: Plan changed
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: object
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-  /api/v1/stripe/portal:
-    x-internal: true
-    post:
-      tags:
-        - Stripe
-      summary: Create customer portal session
-      description: Creates a Stripe customer portal session for subscription management.
-      responses:
-        '200':
-          description: Portal session created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  data:
-                    type: object
-                    properties:
-                      url:
-                        type: string
-                        description: Stripe customer portal URL
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+                    $ref: "#/components/schemas/ServiceSubscription"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/me/tokens:
     get:
       tags:
@@ -356,24 +232,31 @@ paths:
       summary: List API tokens
       description: Returns all Personal Access Tokens for the authenticated user.
       responses:
-        '200':
+        "200":
           description: List of API tokens
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
                       data:
                         type: array
                         items:
-                          $ref: '#/components/schemas/ApiToken'
+                          $ref: "#/components/schemas/ApiToken"
                       total:
                         type: integer
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
     post:
       tags:
         - API Tokens
@@ -384,26 +267,33 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateApiTokenInput'
+              $ref: "#/components/schemas/CreateApiTokenInput"
       responses:
-        '201':
+        "201":
           description: Token created
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     allOf:
-                      - $ref: '#/components/schemas/ApiToken'
+                      - $ref: "#/components/schemas/ApiToken"
                       - type: object
                         properties:
                           token:
                             type: string
                             description: The raw token (only returned on creation)
                             example: nbpat_a1b2c3d4e5f6g7h8i9j0...
-        '401':
-          $ref: '#/components/responses/Unauthorized'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/me/tokens/{id}:
     delete:
       tags:
@@ -417,23 +307,212 @@ paths:
           schema:
             type: integer
       responses:
-        '200':
+        "200":
           description: Token deleted
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
                       success:
                         type: boolean
                         example: true
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+  /api/v1/me/notifications:
+    get:
+      tags:
+        - Notifications
+      summary: List notifications
+      description: Returns the caller's in-app notifications, newest first, with the total unread count. Read rows are deleted 30 days after they were read and unread rows 90 days after their last update.
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum rows to return.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 30
+        - name: unread_only
+          in: query
+          required: false
+          description: Return only unread rows.
+          schema:
+            type: boolean
+            default: false
+      responses:
+        "200":
+          description: Notifications and the unread count
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
+                  data:
+                    $ref: "#/components/schemas/NotificationInbox"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v1/me/notifications/unread-count:
+    get:
+      tags:
+        - Notifications
+      summary: Unread notification count
+      description: Returns only the number of unread notifications. Cheap enough to poll for a badge; use the list endpoint to read the rows.
+      responses:
+        "200":
+          description: Unread count
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
+                  data:
+                    type: object
+                    properties:
+                      unread_count:
+                        type: integer
+                        minimum: 0
+                        example: 3
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v1/me/notifications/read:
+    post:
+      tags:
+        - Notifications
+      summary: Mark notifications as read
+      description: "Marks the given rows (`ids`, at most 100) or every unread row (`all: true`) as read. Ids that do not exist or belong to someone else are ignored."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/MarkNotificationsReadInput"
+      responses:
+        "200":
+          description: Marked as read
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
+                  data:
+                    type: object
+                    properties:
+                      updated:
+                        type: boolean
+                        example: true
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+  /api/v1/me/device-tokens:
+    post:
+      tags:
+        - Notifications
+      summary: Register a device for push
+      description: Sends this device's Expo push token to the signed-in account. Registering a token that belongs to another account moves it to the caller, so a shared phone follows whoever is signed in. At most a handful of devices are kept per user (the newest).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RegisterDeviceTokenInput"
+      responses:
+        "200":
+          description: Registered
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
+                  data:
+                    type: object
+                    properties:
+                      registered:
+                        type: boolean
+                        example: true
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    delete:
+      tags:
+        - Notifications
+      summary: Unregister a device
+      description: "Detaches a push token from the caller (on sign-out). Scoped to the caller: another account's token is left alone."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - token
+              properties:
+                token:
+                  type: string
+                  example: ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]
+      responses:
+        "200":
+          description: Unregistered
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
+                  data:
+                    type: object
+                    properties:
+                      unregistered:
+                        type: boolean
+                        example: true
+        "401":
+          $ref: "#/components/responses/Unauthorized"
   /api/v1/organizations/{orgId}/service-accounts:
     get:
       tags:
@@ -447,35 +526,40 @@ paths:
           schema:
             type: integer
       responses:
-        '200':
+        "200":
           description: List of service accounts
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
                       data:
                         type: array
                         items:
-                          $ref: '#/components/schemas/ServiceAccount'
+                          $ref: "#/components/schemas/ServiceAccount"
                       total:
                         type: integer
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     post:
       tags:
         - Service Accounts
       summary: Create a service account
-      description: >-
-        Creates a new service account in the organization. Requires the caller to be an Org Admin AND the organization
-        to hold an active Enterprise subscription.
+      description: Creates a new service account in the organization. Requires the caller to be an Org Admin AND the organization to hold an active Enterprise subscription.
       parameters:
         - name: orgId
           in: path
@@ -487,21 +571,28 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateServiceAccountInput'
+              $ref: "#/components/schemas/CreateServiceAccountInput"
       responses:
-        '201':
+        "201":
           description: Service account created
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/ServiceAccount'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
+                    $ref: "#/components/schemas/ServiceAccount"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
   /api/v1/organizations/{orgId}/service-accounts/{saId}:
     put:
       tags:
@@ -523,30 +614,35 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateServiceAccountInput'
+              $ref: "#/components/schemas/CreateServiceAccountInput"
       responses:
-        '200':
+        "200":
           description: Service account updated
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
-                    $ref: '#/components/schemas/ServiceAccount'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+                    $ref: "#/components/schemas/ServiceAccount"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     delete:
       tags:
         - Service Accounts
       summary: Delete a service account
-      description: >-
-        Deletes the service account and cascades to all of its API tokens. Returns the cascade count for audit
-        reference.
+      description: Deletes the service account and cascades to all of its API tokens. Returns the cascade count for audit reference.
       parameters:
         - name: orgId
           in: path
@@ -559,13 +655,20 @@ paths:
           schema:
             type: integer
       responses:
-        '200':
+        "200":
           description: Service account deleted
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
@@ -573,12 +676,12 @@ paths:
                         type: boolean
                       cascade_token_count:
                         type: integer
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/organizations/{orgId}/service-accounts/{saId}/tokens:
     get:
       tags:
@@ -596,35 +699,40 @@ paths:
           schema:
             type: integer
       responses:
-        '200':
+        "200":
           description: List of tokens
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
                       data:
                         type: array
                         items:
-                          $ref: '#/components/schemas/ApiToken'
+                          $ref: "#/components/schemas/ApiToken"
                       total:
                         type: integer
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
     post:
       tags:
         - Service Accounts
       summary: Issue a new token for a service account
-      description: >-
-        Creates a new API token under the service account. The raw `nbpat_...` token is returned exactly once; it is not
-        stored in plaintext and cannot be retrieved later.
+      description: Creates a new API token under the service account. The raw `nbpat_...` token is returned exactly once; it is not stored in plaintext and cannot be retrieved later.
       parameters:
         - name: orgId
           in: path
@@ -641,30 +749,37 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateApiTokenInput'
+              $ref: "#/components/schemas/CreateApiTokenInput"
       responses:
-        '201':
+        "201":
           description: Token issued
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     allOf:
-                      - $ref: '#/components/schemas/ApiToken'
+                      - $ref: "#/components/schemas/ApiToken"
                       - type: object
                         properties:
                           token:
                             type: string
                             description: The raw token value (returned once on creation)
                             example: nbpat_a1b2c3d4...
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
   /api/v1/organizations/{orgId}/service-accounts/{saId}/tokens/{tokenId}:
     delete:
       tags:
@@ -687,24 +802,31 @@ paths:
           schema:
             type: integer
       responses:
-        '200':
+        "200":
           description: Token revoked
           content:
             application/json:
               schema:
                 type: object
+                required:
+                  - success
+                  - data
                 properties:
+                  success:
+                    type: boolean
+                    enum:
+                      - true
                   data:
                     type: object
                     properties:
                       success:
                         type: boolean
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '403':
-          $ref: '#/components/responses/Forbidden'
-        '404':
-          $ref: '#/components/responses/NotFound'
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
 components:
   securitySchemes:
     BearerAuth:
@@ -730,9 +852,7 @@ components:
             - en
         timezone:
           type: string
-          description: >-
-            IANA time zone name (e.g. `Asia/Tokyo`), or `auto` to follow the
-            device the client runs on. Defaults to `auto`.
+          description: IANA time zone name (e.g. `Asia/Tokyo`), or `auto` to follow the device the client runs on. Defaults to `auto`.
           example: auto
         plan:
           type: string
@@ -757,7 +877,7 @@ components:
         subscriptions:
           type: array
           items:
-            $ref: '#/components/schemas/ServiceSubscription'
+            $ref: "#/components/schemas/ServiceSubscription"
         tos_accepted_at:
           type: string
           format: date-time
@@ -767,9 +887,16 @@ components:
           format: date-time
     UserResponse:
       type: object
+      required:
+        - success
+        - data
       properties:
+        success:
+          type: boolean
+          enum:
+            - true
         data:
-          $ref: '#/components/schemas/User'
+          $ref: "#/components/schemas/User"
     UpdateProfileInput:
       type: object
       properties:
@@ -858,12 +985,87 @@ components:
           type: string
           format: date-time
           description: Optional expiration date for the token.
+    Notification:
+      type: object
+      description: One inbox row. Repeats of the same event on the same entity collapse into a single unread row (`count` says how many).
+      properties:
+        id:
+          type: integer
+        type:
+          type: string
+          description: Event kind, e.g. `share.invited`, `share.accepted`, `share.rejected`, `share.revoked`, `ownership.transfer_requested`, `target.updated`, `target.deleted`, `recorder.tag_updated`. New kinds may appear; clients should fall back to a generic sentence for one they do not know.
+          example: recorder.tag_updated
+        service_id:
+          type: string
+          description: Which API raised it (`target`, `recorder`, `account`); tells a client which app the reference belongs to.
+          example: recorder
+        ref_id:
+          type: string
+          nullable: true
+          description: "The entity to open: a target id, a tag id or a share id, depending on `type`."
+        params:
+          type: object
+          additionalProperties: true
+          description: "Display data, never rendered into a push: `actor_name`, `owner_name`, `recipient_name`, `target_title`, `tag_name`, and for `recorder.tag_updated` the latest `change` plus up to five `changes` (newest first), each with `action`, `record_id`, `value`, `unit`, `recorded_at`, `comment`, `media_type` (kind only, never a URL) and for goal edits `kind: goal`, `goal_value`, `direction`."
+        count:
+          type: integer
+          minimum: 1
+        read_at:
+          type: string
+          nullable: true
+          description: UTC, `YYYY-MM-DD HH:MM:SS`. Null while unread.
+        created_at:
+          type: string
+          description: UTC, `YYYY-MM-DD HH:MM:SS`.
+        updated_at:
+          type: string
+          description: UTC, `YYYY-MM-DD HH:MM:SS`. Moves forward when a repeat collapses into the row.
+    NotificationInbox:
+      type: object
+      properties:
+        notifications:
+          type: array
+          items:
+            $ref: "#/components/schemas/Notification"
+        unread_count:
+          type: integer
+          minimum: 0
+          description: Total unread rows, not just those in this page.
+    MarkNotificationsReadInput:
+      type: object
+      description: "Send either `all: true` or a non-empty `ids` array."
+      properties:
+        all:
+          type: boolean
+          enum:
+            - true
+        ids:
+          type: array
+          minItems: 1
+          maxItems: 100
+          items:
+            type: integer
+          example:
+            - 12
+            - 13
+    RegisterDeviceTokenInput:
+      type: object
+      required:
+        - token
+        - platform
+      properties:
+        token:
+          type: string
+          description: An Expo push token.
+          example: ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]
+        platform:
+          type: string
+          enum:
+            - ios
+            - android
     ServiceAccount:
       type: object
-      description: >-
-        A non-human users row scoped to a single organization. SAs hold API tokens via the existing api_tokens table
-        (user_id = SA.id). They never appear in member lists; verifyToken rejects any JWT bearing the synthetic
-        'service-account|' sub.
+      description: A non-human users row scoped to a single organization. SAs hold API tokens via the existing api_tokens table (user_id = SA.id). They never appear in member lists; verifyToken rejects any JWT bearing the synthetic 'service-account|' sub.
       properties:
         id:
           type: integer
@@ -908,22 +1110,10 @@ components:
         - success
         - error
       properties:
-        # The implementation has always answered with the same two-field
-        # envelope as a success response, `{ success, error }` — see
-        # errorResponse() in nb-account-api/src/utils/errors.ts. Only the
-        # success half of the envelope was ever described here, so every error
-        # response carried an undeclared `success` property. Specmatic reports
-        # it as R2003 "Unknown property", which is how this was found: the
-        # provider contract test covered only /health until the scope was
-        # widened to GET /api/v1/me -> 401.
-        #
-        # Pinned with `enum` for the same reason the success envelope pins it
-        # to [true] — a plain boolean lets a stub answer `success: true`
-        # alongside an error body, which is a state the implementation cannot
-        # produce.
         success:
           type: boolean
-          enum: [false]
+          enum:
+            - false
         error:
           type: object
           required:
@@ -934,10 +1124,6 @@ components:
               type: string
             message:
               type: string
-            # Optional, and omitted entirely when absent: AppError carries
-            # `details?: Record<string, unknown>` and JSON.stringify drops the
-            # key when it is undefined. Declared so a response that does carry
-            # it is not reported as another unknown property.
             details:
               type: object
               additionalProperties: true
@@ -947,7 +1133,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
@@ -958,7 +1144,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
@@ -969,7 +1155,7 @@ components:
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/Error'
+            $ref: "#/components/schemas/Error"
           example:
             success: false
             error:
@@ -982,9 +1168,9 @@ tags:
     description: User profile endpoints
   - name: Subscriptions
     description: Subscription management endpoints
-  - name: Stripe
-    description: Stripe billing and payment endpoints
   - name: API Tokens
     description: Personal Access Token management
   - name: Service Accounts
     description: Org-scoped service accounts for Enterprise organizations and their API tokens. Org Admin only.
+  - name: Notifications
+    description: In-app notification inbox and mobile push device registration