"/beyond/scans/{scanRequestState}":
    parameters:
        - in: path
          name: scanRequestState
          required: true
          schema: { type: string }
          description: |
              Scan-request state filter. Optional in the underlying route
              (`/beyond/scans{/:scanRequestState}`) — when omitted, all
              states are returned.
    get:
        tags: [Beyond]
        operationId: getScanRequests
        summary: Caller's pending scans
        description: |
            Lists the scan requests on the caller's account, optionally
            filtered by state. Returns the public projection
            (`PublicScanRequest`), not the admin shape.
        responses:
            "200":
                description: Scan requests.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/PublicScanRequest.yaml" }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }

"/beyond/topology/{topologyToken}":
    parameters:
        - in: path
          name: topologyToken
          required: true
          schema: { type: string }
    get:
        tags: [Beyond]
        operationId: getTopologyTokenPresence
        summary: Topology-token presence check (auth optional)
        description: |
            Returns `200` plus a `redirectUrl` when the customer id behind
            this topology token exists on this server, `404` when it does
            not. Used by the iOS scanning app to confirm the right server
            and to deep-link the customer into the right next step.
        security:
            - apiKey: []
        responses:
            "200":
                description: Token recognised.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [redirectUrl]
                            properties:
                                redirectUrl:
                                    type: string
                                    format: uri
                                    description: Where the iOS scanning app should send the customer next.
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }
            "404":
                description: Token not on this server.

"/beyond/scan/{topologyToken}/process":
    parameters:
        - in: path
          name: topologyToken
          required: true
          schema: { type: string }
    get:
        tags: [Beyond]
        operationId: processTopologyScan
        summary: Process a scan by topology token
        description: |
            Triggers downstream processing for the scan associated with
            the supplied topology token. Long-running on the server side;
            returns once the job is queued. **Returns plain text `OK`** —
            not JSON.
        responses:
            "200":
                description: Processing started. Body is the literal string `OK`.
                content:
                    text/plain:
                        schema: { type: string, example: OK }
            "401":
                description: |
                    Caller does not own the scan referenced by the token.
                    *Note: handler returns 401 here even though 403 would
                    be more correct semantically.*
                content:
                    application/json:
                        schema: { $ref: "../public-api.yaml#/components/schemas/Error" }
            "404": { $ref: "../public-api.yaml#/components/responses/NotFound" }
            "422":
                description: "`ScanProcessorError` — invalid scan, preprocessing failed, etc."
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                code: { type: string }
                                message: { type: string }
                                scan:
                                    type: object
                                    additionalProperties: true

"/beyond/multipass":
    get:
        tags: [Beyond]
        operationId: getMultipassUrl
        summary: Shopify Multipass URL for the account
        description: |
            Returns a Shopify Multipass URL bound to the caller's account —
            used to deep-link the customer into their Shopify session
            (orders, returns) without a separate login.
        responses:
            "200":
                description: Multipass URL.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [url]
                            properties:
                                url: { type: string, format: uri }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }

"/beyond/orders":
    get:
        tags: [Beyond]
        operationId: getBigOrders
        summary: Caller's Beyond orders
        description: |
            Returns the `BigOrder`s associated with the caller's account
            (raw rows, not `getPublicData()` — historical inconsistency
            with `/beyond/order/{bigOrderId}`).
        responses:
            "200":
                description: Orders.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }

"/beyond/order/{bigOrderId}":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    get:
        tags: [Beyond]
        operationId: getBigOrder
        summary: One Beyond order
        description: |
            Returns a single `BigOrder` owned by the caller, via the
            customer-facing `getPublicData()` projection — the response
            is a *subset* of the full
            [`BigOrder`](../components/schemas/BigOrder.yaml)
            schema (admin-only fields like `currentLineItems`,
            `nextAction`, `priority`, `tags`, `history`,
            `creatorBigscreenAccountId`, `ownerBigscreenAccountId`,
            `shipmentHold`, `shippingServiceLevel` are stripped). The
            handler additionally attaches `ipdFromShopify`.
        responses:
            "200":
                description: Order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this order.
                content:
                    application/json:
                        schema: { $ref: "../public-api.yaml#/components/schemas/Error" }
            "404": { $ref: "../public-api.yaml#/components/responses/NotFound" }

"/beyond/order/{bigOrderId}/ipd":
    parameters:
        - in: path
          name: bigOrderId
          required: true
          schema: { type: string }
    put:
        tags: [Beyond]
        operationId: updateBigOrderFromCustomer
        summary: Set IPD on a Beyond order
        description: |
            Lets the customer set / update the IPD (interpupillary distance)
            on their Beyond order. Restricted to orders the caller owns.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [ipd]
                        properties:
                            ipd:
                                type: number
                                description: IPD in millimetres.
        responses:
            "200":
                description: Updated order.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/BigOrder.yaml" }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this order.
                content:
                    application/json:
                        schema: { $ref: "../public-api.yaml#/components/schemas/Error" }
            "404": { $ref: "../public-api.yaml#/components/responses/NotFound" }

"/beyond/scan/{scanRequestId}":
    parameters:
        - in: path
          name: scanRequestId
          required: true
          schema: { type: string }
    get:
        tags: [Beyond]
        operationId: getScanRequest
        summary: One scan request
        description: |
            Returns a single scan belonging to the caller, via the
            `PublicScanRequest` projection (admin / fabricator fields
            stripped). For the full admin shape see
            [`ScanRequest`](../components/schemas/ScanRequest.yaml).
        responses:
            "200":
                description: Scan request.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicScanRequest.yaml" }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this scan.
                content:
                    application/json:
                        schema: { $ref: "../public-api.yaml#/components/schemas/Error" }
            "404": { $ref: "../public-api.yaml#/components/responses/NotFound" }

"/beyond/scan/{scanRequestId}/rescan":
    parameters:
        - in: path
          name: scanRequestId
          required: true
          schema: { type: string }
    put:
        tags: [Beyond]
        operationId: handleRescan
        summary: Customer-initiated rescan
        description: |
            Lets a logged-in customer mark a scan for re-scan. Updates
            the underlying `ScanRequest` state so the iOS app knows to
            re-collect.
        responses:
            "200":
                description: Rescan flag set; `PublicScanRequest`.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/PublicScanRequest.yaml" }
            "401": { $ref: "../public-api.yaml#/components/responses/Unauthorized" }
            "403":
                description: Caller does not own this scan.
                content:
                    application/json:
                        schema: { $ref: "../public-api.yaml#/components/schemas/Error" }
            "404": { $ref: "../public-api.yaml#/components/responses/NotFound" }
