@crvouga/mockingbird-service-fullscript 1.7.1 → 2.0.0

package/openapi.yaml

@@ -0,0 +1,776 @@
+openapi: 3.1.0
+info:
+  title: Fullscript API (Mockingbird subset)
+  description: 'Stateful mock subset of the Fullscript API for lab ordering: per-practitioner OAuth (authorize,
+    token with authorization_code and refresh_token grants, revoke), clinic, embeddable session grants,
+    lab orders, lab-order events, expiring result PDFs, and signed webhooks. Hand-authored from the EMR
+    consumer (fullscript-api-client.ts, fullscript-event-model.ts, fullscript-webhook-signature.ts).
+
+    '
+  version: '1'
+  x-mockingbird-upstream:
+    note: Wire shapes from the consumer app's EMR backend (its Fullscript services and routers);
+      the vendor's API reference is behind a partner login.
+servers:
+- url: https://api-us-snd.fullscript.io
+security:
+- bearerAuth: []
+paths:
+  /api/oauth/token:
+    post:
+      operationId: OAuthToken
+      description: Exchange an authorization code, or rotate a refresh token (the old refresh token stops
+        working).
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '200':
+          description: Token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthTokenResponse'
+        '400':
+          description: invalid_grant / unsupported_grant_type / invalid_request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthError'
+        '401':
+          description: invalid_client
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthError'
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TokenRequest'
+  /api/oauth/revoke:
+    post:
+      operationId: OAuthRevoke
+      description: 'Revoke an access or refresh token (RFC 7009: always 200).'
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: false
+      responses:
+        '200':
+          description: Revoked
+          content:
+            application/json:
+              schema:
+                type: object
+        '401':
+          description: invalid_client
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthError'
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+        '400':
+          description: invalid_request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthError'
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RevokeRequest'
+  /api/clinic:
+    get:
+      operationId: GetClinic
+      description: The token's clinic.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '200':
+          description: Clinic
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ClinicResponse'
+        '401': &id001
+          description: Missing, invalid, expired or revoked access token
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+  /api/clinic/embeddable/session_grants:
+    post:
+      operationId: CreateSessionGrant
+      description: A short-lived secret for the embedded Fullscript widget.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '201':
+          description: Grant
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SessionGrant'
+        '401': *id001
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+  /api/clinic/labs/orders:
+    get:
+      operationId: ListLabOrders
+      description: The clinic's lab orders (optionally one patient's), paged.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '200':
+          description: Page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LabOrdersPage'
+        '401': *id001
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+      parameters:
+      - name: patient_id
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+          - pat_seed_1
+          - pat_seed_2
+          - pat_missing
+      - name: page[number]
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 3
+      - name: page[size]
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+  /api/clinic/labs/orders/{orderId}:
+    get:
+      operationId: GetLabOrder
+      description: One lab order with tests, per-test results and the aggregated result.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '200':
+          description: Order
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LabOrderResponse'
+        '404':
+          description: Unknown order
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+        '401': *id001
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+      parameters:
+      - name: orderId
+        in: path
+        required: true
+        schema:
+          type: string
+          enum:
+          - lo_seed_1
+          - lo_seed_2
+          - lo_seed_3
+          - lo_missing
+  /api/events/lab_orders:
+    get:
+      operationId: ListLabOrderEvents
+      description: The clinic's lab_order.updated events, newest first by default.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '200':
+          description: Page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventsPage'
+        '401': *id001
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+      parameters:
+      - name: order_by
+        in: query
+        required: false
+        schema:
+          type: string
+          enum:
+          - DESC
+          - ASC
+      - name: page[number]
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 3
+      - name: page[size]
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 100
+  /api/events/{eventId}:
+    get:
+      operationId: GetEvent
+      description: One event with its data.
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: true
+          safe: true
+      responses:
+        '200':
+          description: Event
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventResponse'
+        '404':
+          description: Unknown event
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+        '401': *id001
+        '429':
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiErrors'
+      parameters:
+      - name: eventId
+        in: path
+        required: true
+        schema:
+          type: string
+          enum:
+          - evt_1
+          - evt_2
+          - evt_3
+          - evt_missing
+  /oauth/authorize:
+    get:
+      operationId: Authorize
+      description: 'The consent page: auto-approves as the requested (or default) practitioner and redirects
+        to redirect_uri with code and state.'
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: false
+          reason: Browser redirect flow; covered by acceptance tests.
+      parameters:
+      - name: client_id
+        in: query
+        required: true
+        schema:
+          type: string
+      - name: redirect_uri
+        in: query
+        required: true
+        schema:
+          type: string
+      - name: response_type
+        in: query
+        required: true
+        schema:
+          type: string
+          enum:
+          - code
+      - name: state
+        in: query
+        required: false
+        schema:
+          type: string
+      - name: scope
+        in: query
+        required: false
+        schema:
+          type: string
+      - name: practitioner_id
+        in: query
+        required: false
+        schema:
+          type: string
+      responses:
+        '302':
+          description: Redirect back with ?code=&state=
+        '400':
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OAuthError'
+  /results/{artifactId}:
+    get:
+      operationId: GetResultPdf
+      description: An expiring result PDF URL (what pdf_url points at).
+      security: []
+      x-mockingbird:
+        supported: true
+        parity:
+          enabled: false
+          reason: Binary PDF behind an expiring signed URL; covered by acceptance tests.
+      parameters:
+      - name: artifactId
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: expires
+        in: query
+        required: true
+        schema:
+          type: string
+      - name: signature
+        in: query
+        required: true
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '403':
+          description: Expired or bad signature
+        '404':
+          description: Unknown artifact
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    TokenRequest:
+      type: object
+      required:
+      - grant_type
+      - client_id
+      - client_secret
+      properties:
+        grant_type:
+          type: string
+          enum:
+          - authorization_code
+          - refresh_token
+        client_id:
+          type: string
+          minLength: 1
+          maxLength: 64
+          examples:
+          - parity-client
+        client_secret:
+          type: string
+          minLength: 1
+          maxLength: 64
+          examples:
+          - parity-secret
+        code:
+          type: string
+          maxLength: 64
+        refresh_token:
+          type: string
+          maxLength: 200
+        redirect_uri:
+          type: string
+          maxLength: 200
+          examples:
+          - https://emr.example.com/v1/fullscript/oauth/callback
+    RevokeRequest:
+      type: object
+      required:
+      - client_id
+      - client_secret
+      - token
+      properties:
+        client_id:
+          type: string
+          minLength: 1
+          maxLength: 64
+        client_secret:
+          type: string
+          minLength: 1
+          maxLength: 64
+        token:
+          type: string
+          minLength: 1
+          maxLength: 200
+    OAuthTokenResponse:
+      type: object
+      required:
+      - oauth
+      properties:
+        oauth:
+          type: object
+          required:
+          - access_token
+          - token_type
+          - expires_in
+          - refresh_token
+          - scope
+          - created_at
+          - resource_owner
+          properties:
+            access_token:
+              type: string
+              x-mockingbird-volatile:
+                kind: token
+            token_type:
+              type: string
+              enum:
+              - Bearer
+            expires_in:
+              type: integer
+            refresh_token:
+              type: string
+              x-mockingbird-volatile:
+                kind: token
+            scope:
+              type: string
+            created_at: &id002
+              type: string
+              x-mockingbird-volatile:
+                kind: timestamp
+            resource_owner:
+              type: object
+              required:
+              - id
+              - type
+              properties:
+                id:
+                  type: string
+                type:
+                  type: string
+                  enum:
+                  - Practitioner
+                  - Staff
+                clinic_id:
+                  type: string
+    OAuthError:
+      type: object
+      required:
+      - error
+      properties:
+        error:
+          type: string
+        error_description:
+          type: string
+    ApiErrors:
+      type: object
+      required:
+      - errors
+      properties:
+        errors:
+          type: array
+          items:
+            type: object
+            required:
+            - code
+            - message
+            properties:
+              code:
+                type: string
+              message:
+                type: string
+    ClinicResponse:
+      type: object
+      required:
+      - clinic
+      properties:
+        clinic:
+          type: object
+          required:
+          - id
+          - name
+          properties:
+            id:
+              type: string
+            name:
+              type: string
+            created_at: *id002
+    SessionGrant:
+      type: object
+      required:
+      - secret_token
+      - expires_at
+      properties:
+        secret_token:
+          type: string
+          x-mockingbird-volatile:
+            kind: token
+        expires_at: *id002
+    LabOrderSummary:
+      type: object
+      required:
+      - id
+      - state
+      - treatment_plan_id
+      - patient_id
+      - created_at
+      - updated_at
+      properties:
+        id:
+          type: string
+        state:
+          type: string
+          enum: &id003
+          - not_purchased
+          - purchased
+          - schedule_appointment
+          - upcoming_appointment
+          - processing
+          - partial_results
+          - results_ready
+          - interpretation_shared
+          - results_amended
+        treatment_plan_id:
+          type:
+          - string
+          - 'null'
+        patient_id:
+          type: string
+        name:
+          type: string
+        created_at: *id002
+        updated_at: *id002
+    LabOrdersPage:
+      type: object
+      required:
+      - orders
+      - meta
+      properties:
+        orders:
+          type: array
+          items:
+            $ref: '#/components/schemas/LabOrderSummary'
+        meta: &id005
+          type: object
+          required:
+          - current_page
+          - next_page
+          - prev_page
+          - total_pages
+          - total_count
+          properties:
+            current_page:
+              type: integer
+            next_page:
+              type:
+              - integer
+              - 'null'
+            prev_page:
+              type:
+              - integer
+              - 'null'
+            total_pages:
+              type: integer
+            total_count:
+              type: integer
+    LabOrderResponse:
+      type: object
+      required:
+      - order
+      properties:
+        order:
+          type: object
+          required:
+          - id
+          - state
+          - treatment_plan_id
+          - tests
+          - results
+          - latest_aggregated_result
+          properties:
+            id:
+              type: string
+            state:
+              type: string
+              enum: *id003
+            treatment_plan_id:
+              type:
+              - string
+              - 'null'
+            patient_id:
+              type: string
+            name:
+              type: string
+            collection_method:
+              type: string
+            created_at: *id002
+            updated_at: *id002
+            tests:
+              type: array
+              items:
+                type: object
+                required:
+                - id
+                - name
+                properties:
+                  id:
+                    type: string
+                  name:
+                    type: string
+                  lab_type:
+                    type: string
+            results:
+              type: array
+              items:
+                type: object
+                required:
+                - id
+                - name
+                - state
+                - pdf_url
+                properties:
+                  id:
+                    type: string
+                  name:
+                    type: string
+                  state:
+                    type: string
+                  pdf_url: &id004
+                    type: string
+                    x-mockingbird-volatile:
+                      kind: url
+            latest_aggregated_result:
+              type:
+              - object
+              - 'null'
+              properties:
+                id:
+                  type: string
+                artifact_id:
+                  type: string
+                pdf_url: *id004
+                status:
+                  type: string
+    EventSummary:
+      type: object
+      required:
+      - id
+      - type
+      - clinic_id
+      - created_at
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum:
+          - lab_order.updated
+        clinic_id:
+          type: string
+        created_at: *id002
+    EventsPage:
+      type: object
+      required:
+      - events
+      - meta
+      properties:
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/EventSummary'
+        meta: *id005
+    EventResponse:
+      type: object
+      required:
+      - event
+      properties:
+        event:
+          type: object
+          required:
+          - id
+          - type
+          - clinic_id
+          - created_at
+          - data
+          properties:
+            id:
+              type: string
+            type:
+              type: string
+            clinic_id:
+              type: string
+            created_at: *id002
+            data:
+              type: object