@nasebanal/cli 0.1.0

package/specs/target.yaml

@@ -0,0 +1,1540 @@
+openapi: 3.0.3
+info:
+  title: NASEBANAL - Target API
+  description: >-
+    Target API for NASEBANAL. Provides hierarchical target management: users define goals and organize them in a tree
+    structure. Parent-child links are persisted via `targets.parent_target_id` (authoritative since migration 0017); a
+    legacy cell-based storage layer is kept in sync best-effort for backward compatibility. Targets can be shared with
+    other users (read/write, optionally including the subtree and linked Recorder data), and ownership of a personal
+    target subtree can be transferred to a recipient via an email-approved migration flow. Supports user authentication
+    via Auth0 JWT and Personal Access Tokens (PAT).
+  version: 1.4.1
+  contact:
+    name: NASEBANAL
+    url: https://www.nasebanal.com
+servers:
+  - url: http://localhost:8790
+    description: Local dev (wrangler dev)
+  - url: https://api.target.nasebanal.com
+    description: Production
+security:
+  - BearerAuth: []
+paths:
+  /api/v1/health:
+    get:
+      operationId: getHealth
+      tags:
+        - Health
+      summary: Health check
+      description: Returns the health status of the API.
+      security: []
+      responses:
+        '200':
+          description: API is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    properties:
+                      status:
+                        type: string
+                        example: ok
+                      timestamp:
+                        type: string
+                        format: date-time
+  /api/v1/me:
+    get:
+      operationId: getCurrentUser
+      tags:
+        - User
+      summary: Get current user profile
+      description: Returns the authenticated user's profile information (resolved from the Account API).
+      responses:
+        '200':
+          description: User profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/targets:
+    get:
+      operationId: listTargets
+      tags:
+        - Targets
+      summary: List targets
+      description: >-
+        Returns all targets belonging to the authenticated user in the active namespace (personal, or the active
+        organization), ordered by last updated. By default each target includes its storage cells so clients do not
+        need to issue a follow-up GET /targets/{id} per row. Pass `fields=summary` to omit `cells` and reduce payload
+        size for callers (e.g. a tree/chart view) that only need `progress` — fetch full detail on demand via
+        GET /targets/{id}.
+      parameters:
+        - name: fields
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - full
+              - summary
+            default: full
+          description: >-
+            `full` (default) returns every target's complete `cells` array — today's exact behavior, unchanged for
+            callers that omit this param. `summary` omits `cells`; `progress` is present in both modes.
+      responses:
+        '200':
+          description: List of targets with cells (or, with fields=summary, without cells)
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - data
+                      - total
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/TargetWithCells'
+                      total:
+                        type: integer
+              examples:
+                full:
+                  summary: Default (fields omitted or fields=full)
+                  value:
+                    success: true
+                    data:
+                      data:
+                        - id: tgt_a1b2c3d4
+                          user_id: 42
+                          created_by_user_id: 42
+                          organization_id: null
+                          parent_target_id: null
+                          title: Learn Japanese
+                          description: null
+                          memo: null
+                          recorder_tag: null
+                          recorder_goal_id: null
+                          progress: 40
+                          own_progress: 40
+                          created_at: '2026-05-14T12:00:00Z'
+                          updated_at: '2026-05-14T12:00:00Z'
+                          owner_email: user@example.com
+                          owner_name: Sample User
+                          created_by_email: user@example.com
+                          created_by_name: Sample User
+                          created_by_deleted: false
+                          cells:
+                            - id: 1
+                              target_id: tgt_a1b2c3d4
+                              position: 40
+                              text: Learn Japanese
+                              progress: 40
+                              created_by_user_id: 42
+                              created_at: '2026-05-14T12:00:00Z'
+                              updated_at: '2026-05-14T12:00:00Z'
+                      total: 1
+                summary:
+                  summary: fields=summary
+                  value:
+                    success: true
+                    data:
+                      data:
+                        - id: tgt_a1b2c3d4
+                          user_id: 42
+                          created_by_user_id: 42
+                          organization_id: null
+                          parent_target_id: null
+                          title: Learn Japanese
+                          description: null
+                          memo: null
+                          recorder_tag: null
+                          recorder_goal_id: null
+                          progress: 40
+                          own_progress: 40
+                          created_at: '2026-05-14T12:00:00Z'
+                          updated_at: '2026-05-14T12:00:00Z'
+                          owner_email: user@example.com
+                          owner_name: Sample User
+                          created_by_email: user@example.com
+                          created_by_name: Sample User
+                          created_by_deleted: false
+                      total: 1
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      operationId: createTarget
+      tags:
+        - Targets
+      summary: Create target
+      description: >-
+        Creates a new target. The storage cells are initialized with the target title pre-populated at position 40 (the
+        slot reserved for the target's own label). Optionally nests the new target under an existing parent.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTargetInput'
+      responses:
+        '201':
+          description: Target created with its storage cells
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TargetWithCellsResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/targets/{id}:
+    get:
+      operationId: getTarget
+      tags:
+        - Targets
+      summary: Get target
+      description: >-
+        Returns a single target with its storage cells. Accessible by the owner, by a user the target is shared with,
+        or by an admin of the organization that owns the target.
+      parameters:
+        - $ref: '#/components/parameters/TargetId'
+      responses:
+        '200':
+          description: Target with cells
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TargetWithCellsResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    put:
+      operationId: updateTarget
+      tags:
+        - Targets
+      summary: Update target
+      description: Updates a target's title, description, memo, and/or its Recorder tag binding.
+      parameters:
+        - $ref: '#/components/parameters/TargetId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTargetInput'
+      responses:
+        '200':
+          description: Target updated
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    $ref: '#/components/schemas/Target'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+    delete:
+      operationId: deleteTarget
+      tags:
+        - Targets
+      summary: Delete target
+      description: Deletes a target and all its cells.
+      parameters:
+        - $ref: '#/components/parameters/TargetId'
+      responses:
+        '200':
+          description: Target deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessFlagResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/targets/{id}/cells/{position}:
+    put:
+      operationId: updateTargetCell
+      tags:
+        - Target Cells
+      summary: Update target cell
+      description: Updates the text and/or progress of a specific storage cell on a target.
+      parameters:
+        - $ref: '#/components/parameters/TargetId'
+        - name: position
+          in: path
+          required: true
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 80
+          description: Cell position in the storage layout (0-80; position 40 is reserved for the target title)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTargetCellInput'
+      responses:
+        '200':
+          description: Cell updated
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    $ref: '#/components/schemas/TargetCell'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/targets/{id}/parent:
+    put:
+      operationId: setTargetParent
+      tags:
+        - Targets
+      summary: Set target parent
+      description: >-
+        Authoritative tree-move endpoint (migration 0017+). Sets or clears `parent_target_id` on the target. Pass
+        `null` to detach (move to root). The legacy sub-goal cells are updated best-effort to keep older clients in
+        sync. Parent and child must share the same organization namespace and the same owner; cycles are rejected.
+      parameters:
+        - $ref: '#/components/parameters/TargetId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SetTargetParentInput'
+      responses:
+        '200':
+          description: Parent updated; returns the updated target
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    $ref: '#/components/schemas/Target'
+        '400':
+          description: Invalid move (self-parent, namespace mismatch, or cycle)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shared-targets:
+    get:
+      operationId: listSharedTargets
+      tags:
+        - Sharing
+      summary: List targets shared with me
+      description: >-
+        Returns targets that other users have shared with the authenticated user and accepted (not paused, not hidden),
+        scoped to the active namespace via each share's `shared_with_org_id`. When `include_descendants` was set on the
+        share, the whole subtree is expanded. Each row carries the sharing owner and the effective permission.
+      responses:
+        '200':
+          description: Shared targets
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - data
+                      - total
+                    properties:
+                      data:
+                        type: array
+                        items:
+                          $ref: '#/components/schemas/SharedTarget'
+                      total:
+                        type: integer
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/shares:
+    get:
+      operationId: listMyShares
+      tags:
+        - Sharing
+      summary: List shares I created
+      description: >-
+        Returns shares the authenticated user owns (i.e. shares of their own targets), scoped to the active namespace.
+        Each row is enriched with the recipient email, the owner's plan, and the owner-side target chain.
+      responses:
+        '200':
+          description: Shares owned by the caller
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ShareListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+    post:
+      operationId: createShare
+      tags:
+        - Sharing
+      summary: Create a share invitation
+      description: >-
+        Shares a target the caller owns with another user by email. Sends an invitation email containing an accept
+        link; the share is `pending` until accepted. Optionally includes the subtree (`include_descendants`) and the
+        linked Recorder tag data (`include_data`, which cascades matching tag shares to the Recorder API).
+        `share_context: organization` routes the share into the caller's active organization view and requires the
+        recipient to be a member of that organization.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateShareInput'
+      responses:
+        '201':
+          description: Share created (pending acceptance)
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    $ref: '#/components/schemas/Share'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: Sharing not permitted (plan limit, or recipient not in organization)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: Target not found, or recipient email not registered
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          $ref: '#/components/responses/Conflict'
+  /api/v1/shares/with-me:
+    get:
+      operationId: listSharesWithMe
+      tags:
+        - Sharing
+      summary: List shares addressed to me
+      description: >-
+        Returns shares where the authenticated user is the recipient, scoped to the active namespace. Filter by status
+        with the `status` query parameter. Each row is enriched with the owner email and the owner-side target chain.
+      parameters:
+        - name: status
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [accepted, pending, rejected, all]
+            default: accepted
+          description: Which share statuses to return (default `accepted`).
+      responses:
+        '200':
+          description: Shares addressed to the caller
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ShareListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/shares/recipient-context-options:
+    get:
+      operationId: getRecipientContextOptions
+      tags:
+        - Sharing
+      summary: Resolve sharing-context options for a recipient
+      description: >-
+        Returns which sharing contexts the caller may offer for a given recipient email. Always includes `personal`;
+        additionally includes `organization` when the caller is acting under an organization context and the recipient
+        is a member of that same organization.
+      parameters:
+        - name: email
+          in: query
+          required: true
+          schema:
+            type: string
+            format: email
+          description: Recipient email to evaluate.
+      responses:
+        '200':
+          description: Available sharing contexts
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - options
+                    properties:
+                      options:
+                        type: array
+                        items:
+                          type: string
+                          enum: [personal, organization]
+                        example: [personal, organization]
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+  /api/v1/shares/accept:
+    post:
+      operationId: acceptShareByToken
+      tags:
+        - Sharing
+      summary: Accept a share invitation by token
+      description: Accepts a pending share invitation using the token from the invitation email.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TokenInput'
+      responses:
+        '200':
+          description: Share accepted (or already accepted)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ShareStatusResponse'
+        '400':
+          description: Invitation expired or already declined
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/migrate/accept:
+    post:
+      operationId: acceptMigrationByToken
+      tags:
+        - Sharing
+      summary: Accept an ownership transfer by token
+      description: >-
+        Accepts a pending ownership-transfer (data migration) using the token from the migration approval email. On
+        success the target (and, if the share included descendants, its subtree) is transferred to the caller, and a
+        reverse read-only share is created so the original owner keeps access.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TokenInput'
+      responses:
+        '200':
+          description: Ownership transferred
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MigrationStatusResponse'
+        '400':
+          description: Migration invitation no longer active or expired
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}:
+    delete:
+      operationId: deleteShare
+      tags:
+        - Sharing
+      summary: Delete a share
+      description: >-
+        Removes a share the caller owns. If the share was created with `include_data`, the matching Recorder tag shares
+        are revoked unless `cascade_tag_shares=false` is passed. A share with a pending ownership transfer cannot be
+        deleted until the migration is cancelled.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+        - name: cascade_tag_shares
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: ['true', 'false']
+            default: 'true'
+          description: Set to `false` to keep the linked Recorder tag shares when deleting.
+      responses:
+        '200':
+          description: Share deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SuccessFlagResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+  /api/v1/shares/{id}/accept:
+    post:
+      operationId: acceptShareById
+      tags:
+        - Sharing
+      summary: Accept a share invitation (in-app)
+      description: In-app counterpart to POST /shares/accept — accepts a pending share addressed to the caller by id.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      responses:
+        '200':
+          description: Share accepted (or already accepted)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ShareStatusResponse'
+        '400':
+          description: Invitation expired or already declined
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}/reject:
+    post:
+      operationId: rejectShare
+      tags:
+        - Sharing
+      summary: Reject a share invitation
+      description: Declines a pending share addressed to the caller. An already-accepted share cannot be rejected (delete it instead).
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      responses:
+        '200':
+          description: Share rejected (or already rejected)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ShareStatusResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}/pause:
+    patch:
+      operationId: toggleSharePaused
+      tags:
+        - Sharing
+      summary: Pause or resume a share
+      description: Owner-only. Pauses or resumes a share without deleting it; a paused share is hidden from the recipient's shared-targets list.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - is_paused
+              properties:
+                is_paused:
+                  type: boolean
+      responses:
+        '200':
+          description: Updated share row
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    $ref: '#/components/schemas/Share'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}/visibility:
+    patch:
+      operationId: toggleShareVisibility
+      tags:
+        - Sharing
+      summary: Hide or unhide a share
+      description: Recipient-only. Hides or unhides a share from the caller's own shared-targets list.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - is_hidden
+              properties:
+                is_hidden:
+                  type: boolean
+      responses:
+        '200':
+          description: Updated share row
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    $ref: '#/components/schemas/Share'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}/transfer:
+    post:
+      operationId: transferOwnership
+      tags:
+        - Sharing
+      summary: Start an ownership transfer
+      description: >-
+        Owner-only. Begins transferring ownership of the shared target (subtree if the share included descendants) to
+        the recipient by emailing them an approval link. The share must already be accepted. Organization-owned targets
+        cannot be transferred. The transfer only completes when the recipient accepts.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      responses:
+        '200':
+          description: Migration invitation issued
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - id
+                      - migration_status
+                    properties:
+                      id:
+                        type: integer
+                      migration_status:
+                        type: string
+                        enum: [pending]
+                      expires_at:
+                        type: string
+                        format: date-time
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+  /api/v1/shares/{id}/migrate/accept:
+    post:
+      operationId: acceptMigrationById
+      tags:
+        - Sharing
+      summary: Accept an ownership transfer (in-app)
+      description: In-app counterpart to POST /shares/migrate/accept — accepts a pending ownership transfer addressed to the caller by id.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      responses:
+        '200':
+          description: Ownership transferred
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MigrationStatusResponse'
+        '400':
+          description: Migration invitation no longer active or expired
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}/migrate/reject:
+    post:
+      operationId: rejectMigration
+      tags:
+        - Sharing
+      summary: Reject an ownership transfer
+      description: Recipient-only. Declines a pending ownership transfer; the underlying share keeps its existing permission.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      responses:
+        '200':
+          description: Migration rejected
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MigrationStatusResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+  /api/v1/shares/{id}/migrate/cancel:
+    post:
+      operationId: cancelMigration
+      tags:
+        - Sharing
+      summary: Cancel an ownership transfer
+      description: Owner-only. Cancels an outstanding ownership-transfer invitation before the recipient acts.
+      parameters:
+        - $ref: '#/components/parameters/ShareId'
+      responses:
+        '200':
+          description: Migration cancelled
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    type: boolean
+                    enum: [true]
+                  data:
+                    type: object
+                    required:
+                      - id
+                      - migration_status
+                    properties:
+                      id:
+                        type: integer
+                      migration_status:
+                        type: string
+                        nullable: true
+                        enum: [null]
+                        description: Always null after a cancel — the in-flight migration is cleared.
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT or PAT
+      description: Use either an Auth0 JWT token or a Personal Access Token (PAT) starting with `nbpat_`.
+  parameters:
+    TargetId:
+      name: id
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Target ID
+    ShareId:
+      name: id
+      in: path
+      required: true
+      schema:
+        type: integer
+      description: Share ID
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - auth0_sub
+        - email
+        - name
+        - language
+        - plan
+      properties:
+        id:
+          type: integer
+        auth0_sub:
+          type: string
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        language:
+          type: string
+          enum:
+            - ja
+            - en
+        plan:
+          type: string
+          enum:
+            - free
+            - pro
+            - family
+            - enterprise
+        subscription_status:
+          type: string
+          enum:
+            - active
+            - canceled
+            - past_due
+            - trialing
+            - null
+          nullable: true
+        subscription_expires_at:
+          type: string
+          format: date-time
+          nullable: true
+    UserResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/User'
+    Target:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Unique target ID
+        user_id:
+          type: integer
+          description: Owner user id
+        created_by_user_id:
+          type: integer
+          nullable: true
+          description: User who created the target. Distinct from ownership; preserved across ownership transfer.
+        organization_id:
+          type: integer
+          nullable: true
+          description: >-
+            Organization namespace. NULL = personal data. Non-null = created under an Enterprise org context; the org
+            admin can read it and the member-creator owns it day-to-day but cannot transfer or delete it.
+        parent_target_id:
+          type: string
+          nullable: true
+          description: >-
+            Direct parent reference (migration 0017+). Authoritative source of tree structure. NULL = root target.
+        title:
+          type: string
+          description: Goal title
+          maxLength: 200
+        description:
+          type: string
+          nullable: true
+        memo:
+          type: string
+          nullable: true
+        recorder_tag:
+          type: string
+          nullable: true
+          description: Optional tag linking to the Recorder app
+        recorder_goal_id:
+          type: integer
+          nullable: true
+          description: >-
+            Recorder Goal id pinned at the moment the tag was bound. Progress for this target is computed against this
+            specific goal so that later Goal period changes in Recorder do not silently re-route which goal is being
+            tracked.
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        owner_email:
+          type: string
+          format: email
+          description: Resolved owner email (present in response payloads).
+        owner_name:
+          type: string
+          description: >-
+            Display name the owner set in their profile. Absent when they set
+            none. Clients name the owner by this, falling back to a masked email.
+        created_by_email:
+          type: string
+          format: email
+          description: >-
+            Resolved creator email (present in response payloads). Absent when `created_by_deleted` is true — there is no
+            creator left to name, and the owner must NOT be substituted.
+        created_by_name:
+          type: string
+          description: >-
+            Display name the creator set in their profile. Absent when they set
+            none, or when `created_by_deleted` is true.
+        created_by_deleted:
+          type: boolean
+          description: >-
+            True when the author deleted their NASEBANAL account. The row itself survives because it belongs to this
+            target's owner; only the authorship is gone. Clients render a "deleted user" label (JA: 退会済ユーザー) rather
+            than falling back to `owner_email`, which would show the owner as the author of an edit they never made.
+    TargetCell:
+      type: object
+      properties:
+        id:
+          type: integer
+        target_id:
+          type: string
+        position:
+          type: integer
+          minimum: 0
+          maximum: 80
+          description: Cell position in the storage layout (0-80; position 40 is reserved for the target title)
+        text:
+          type: string
+          maxLength: 500
+          description: Cell content
+        progress:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: Progress percentage
+        created_by_user_id:
+          type: integer
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    TargetWithCells:
+      allOf:
+        - $ref: '#/components/schemas/Target'
+        - type: object
+          required:
+            - progress
+            - own_progress
+          properties:
+            cells:
+              type: array
+              items:
+                $ref: '#/components/schemas/TargetCell'
+              description: >-
+                All storage cells ordered by position. Present when the list was requested without `fields`, or with
+                `fields=full` (the default); omitted when requested with `fields=summary` — see `progress` and
+                `own_progress` instead.
+            progress:
+              type: integer
+              minimum: 0
+              maximum: 100
+              description: >-
+                A target's own roll-up progress, computed server-side: the average of its children's (recursively
+                rolled-up) progress when it has sub-goals, or its own storage cell (position 40, `own_progress`)
+                when it's a leaf. Always present, regardless of `fields`.
+            own_progress:
+              type: integer
+              minimum: 0
+              maximum: 100
+              description: >-
+                The target's own storage cell (position 40) value, unrolled — what the "clear" toggle sets directly
+                to 0 or 100, independent of any sub-goals. Distinct from `progress`: a target with sub-goals can
+                have `progress = 100` (every child rolled up to 100) while `own_progress` stays whatever it was
+                last explicitly set to, since a parent's own cell is never averaged into its own `progress`. Always
+                present, regardless of `fields` — use this, not `progress`, to tell whether a target itself has
+                been marked cleared.
+    TargetWithCellsResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          $ref: '#/components/schemas/TargetWithCells'
+    SharedTarget:
+      allOf:
+        - $ref: '#/components/schemas/TargetWithCells'
+        - type: object
+          properties:
+            shared_by_user_id:
+              type: integer
+              description: User id of the sharing owner
+            shared_by_email:
+              type: string
+              format: email
+            shared_by_name:
+              type: string
+              description: Display name the sharing owner set in their profile. Absent when they set none.
+            share_permission:
+              type: string
+              enum: [read, write]
+            share_root_target_id:
+              type: string
+              description: The root target id of the share that grants access to this row
+            share_show_embed:
+              type: integer
+              enum: [0, 1]
+              description: Whether the share permits embedding the linked Recorder graph
+    Share:
+      type: object
+      properties:
+        id:
+          type: integer
+        owner_user_id:
+          type: integer
+        shared_with_user_id:
+          type: integer
+        target_id:
+          type: string
+        permission:
+          type: string
+          enum: [read, write]
+        status:
+          type: string
+          enum: [pending, accepted, rejected]
+        expires_at:
+          type: string
+          format: date-time
+          nullable: true
+        migration_status:
+          type: string
+          enum: [pending, null]
+          nullable: true
+          description: Ownership-transfer state. NULL = no migration in flight.
+        migration_expires_at:
+          type: string
+          format: date-time
+          nullable: true
+        is_hidden:
+          type: integer
+          enum: [0, 1]
+        is_paused:
+          type: integer
+          enum: [0, 1]
+        show_embed:
+          type: integer
+          enum: [0, 1]
+        include_descendants:
+          type: integer
+          enum: [0, 1]
+        include_data:
+          type: integer
+          enum: [0, 1]
+        parent_share_id:
+          type: integer
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        target_title:
+          type: string
+          description: Enriched — title of the shared target.
+        target_chain:
+          type: string
+          description: Enriched — owner-side "Parent > Child" breadcrumb for the target.
+        owner_email:
+          type: string
+          format: email
+          description: Enriched — present when listing shares addressed to the caller.
+        owner_name:
+          type: string
+          description: >-
+            Display name the sharing owner set in their profile. Absent when they set none.
+        shared_with_email:
+          type: string
+          format: email
+          description: Enriched — present when listing shares the caller owns.
+        shared_with_name:
+          type: string
+          description: >-
+            Display name the recipient set in their profile. Set on shares the caller owns, and only once the share is
+            `accepted`, so an invitation does not reveal the profile of someone who has not accepted it.
+        owner_plan:
+          type: string
+          description: Enriched — the owner's plan, present when listing shares the caller owns.
+    ShareListResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          type: object
+          required:
+            - data
+            - total
+            - limit
+            - offset
+          properties:
+            data:
+              type: array
+              items:
+                $ref: '#/components/schemas/Share'
+            total:
+              type: integer
+            limit:
+              type: integer
+            offset:
+              type: integer
+    ShareStatusResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          type: object
+          required:
+            - id
+            - status
+          properties:
+            id:
+              type: integer
+            status:
+              type: string
+              enum: [pending, accepted, rejected]
+            already:
+              type: boolean
+              description: True when the share was already in the requested state.
+    MigrationStatusResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          type: object
+          required:
+            - id
+            - migration_status
+          properties:
+            id:
+              type: integer
+            migration_status:
+              type: string
+              enum: [accepted, rejected]
+    SuccessFlagResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          enum: [true]
+        data:
+          type: object
+          properties:
+            success:
+              type: boolean
+              enum: [true]
+    CreateTargetInput:
+      type: object
+      required:
+        - title
+      properties:
+        title:
+          type: string
+          minLength: 1
+          maxLength: 200
+          example: Become a professional athlete
+        description:
+          type: string
+        memo:
+          type: string
+        parent_id:
+          type: string
+          description: Optional parent target id to nest the new target under at creation time.
+    UpdateTargetInput:
+      type: object
+      properties:
+        title:
+          type: string
+          minLength: 1
+          maxLength: 200
+        description:
+          type: string
+          nullable: true
+        memo:
+          type: string
+          nullable: true
+        recorder_tag:
+          type: string
+          nullable: true
+          description: Tag to link with Recorder app
+        recorder_goal_id:
+          type: integer
+          nullable: true
+          description: >-
+            Pin a specific Recorder Goal to this target. Typically resolved by the client at bind time from the active
+            goal for the selected tag.
+    UpdateTargetCellInput:
+      type: object
+      properties:
+        text:
+          type: string
+          maxLength: 500
+          description: Cell content
+        progress:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: Progress percentage
+    SetTargetParentInput:
+      type: object
+      properties:
+        parent_target_id:
+          type: string
+          nullable: true
+          description: New parent target id, or null to detach to root.
+    CreateShareInput:
+      type: object
+      required:
+        - shared_with_email
+        - target_id
+      properties:
+        shared_with_email:
+          type: string
+          format: email
+          description: Email of the user to share with (must be a registered user).
+        target_id:
+          type: string
+        permission:
+          type: string
+          enum: [read, write]
+          default: read
+        include_descendants:
+          type: boolean
+          default: false
+          description: Share the whole subtree rooted at the target, not just the target itself.
+        include_data:
+          type: boolean
+          default: false
+          description: Also cascade-share the linked Recorder tag data so the recipient can view embedded graphs.
+        share_context:
+          type: string
+          enum: [personal, organization]
+          default: personal
+          description: >-
+            `organization` routes the share into the caller's active organization view; requires the recipient to be a
+            member of that organization.
+        extra_tag_names:
+          type: array
+          items:
+            type: string
+          description: Additional real Recorder tag names to include when cascading data shares.
+    TokenInput:
+      type: object
+      required:
+        - token
+      properties:
+        token:
+          type: string
+          description: The invitation token from the email link.
+    Error:
+      type: object
+      required:
+        - success
+        - error
+      properties:
+        success:
+          type: boolean
+          enum: [false]
+        error:
+          type: object
+          required:
+            - code
+            - message
+          properties:
+            code:
+              type: string
+            message:
+              type: string
+            details:
+              type: object
+              additionalProperties: true
+  responses:
+    Unauthorized:
+      description: Authentication required or invalid token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            success: false
+            error:
+              code: AUTH_ERROR
+              message: No authentication token provided
+    Forbidden:
+      description: The caller is not allowed to perform this action
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            success: false
+            error:
+              code: FORBIDDEN
+              message: Cannot transfer ownership of organization-owned target. Contact the organization admin.
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            success: false
+            error:
+              code: NOT_FOUND
+              message: Target not found
+    Conflict:
+      description: The request conflicts with the current state of the resource
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            success: false
+            error:
+              code: CONFLICT
+              message: 'Share already exists (status: pending)'
+    ValidationError:
+      description: Validation error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            success: false
+            error:
+              code: VALIDATION_ERROR
+              message: Title is required
+tags:
+  - name: Health
+    description: Health check endpoints
+  - name: User
+    description: User profile endpoints
+  - name: Targets
+    description: Target management
+  - name: Target Cells
+    description: Individual storage cell management on a target
+  - name: Sharing
+    description: Sharing targets with other users and transferring ownership