openapi: 3.0.3
info:
  title: Banno Plugin Framework
  description: |
    The Plugin Framework lets partners build custom cards that appear in
    a user's Banno Online and Mobile dashboard. Plugins are web
    applications (HTML + CSS + JavaScript) hosted on the partner's own
    infrastructure and registered as External Applications in Banno
    People.

    This OpenAPI documents the host-side surface a plugin uses against
    Banno (configuration metadata + bridge handshake). The browser-side
    runtime interactions happen over the @jack-henry/banno-plugin-framework-bridge
    `postMessage` channel rather than HTTP — see the bridge SDK README.
  version: v0
servers:
  - url: https://digital.garden.banno-uat.com
    description: Banno UAT
  - url: https://digital.banno.com
    description: Banno production
tags:
  - name: Plugin Configuration
    description: Plugin metadata published by the host.
  - name: Plugin Bridge
    description: Bridge handshake and lifecycle.
  - name: User Context
    description: Authenticated user/account context surfaced to a plugin.
paths:
  /plugins/api/v0/plugins/{pluginId}/manifest:
    get:
      summary: Get Plugin Manifest
      operationId: getPluginManifest
      tags: [Plugin Configuration]
      parameters:
        - name: pluginId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Manifest describing the plugin's cards, sizes, and entry points.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PluginManifest' }
  /plugins/api/v0/plugins/{pluginId}/bridge/token:
    post:
      summary: Exchange Bridge Token
      operationId: exchangeBridgeToken
      tags: [Plugin Bridge]
      description: |
        Exchanges the parent-window handshake nonce for a short-lived
        bridge token used by the @jack-henry/banno-plugin-framework-bridge
        library to call host-side functions.
      parameters:
        - name: pluginId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [nonce]
              properties:
                nonce: { type: string }
      responses:
        '200':
          description: Bridge token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  expiresIn: { type: integer, description: Seconds }
  /plugins/api/v0/context:
    get:
      summary: Get Plugin User Context
      operationId: getPluginUserContext
      tags: [User Context]
      description: |
        Returns the authenticated user/account context the host hands the
        plugin (institution ID, user ID, environment, locale). Subject to
        the plugin's authorized scopes in Banno People.
      responses:
        '200':
          description: Plugin context.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PluginContext' }
components:
  schemas:
    PluginManifest:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        version: { type: string }
        entryUrl: { type: string, format: uri }
        cards:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum: [CardFace, ExpandedView, FullScreen]
              size:
                type: string
                enum: [Small, Medium, Large]
              actionLabel: { type: string }
        permissions:
          type: array
          items:
            type: string
            description: Scopes requested by the plugin (e.g. user.profile.readonly).
    PluginContext:
      type: object
      properties:
        institutionId: { type: string, format: uuid }
        userId: { type: string, format: uuid }
        environment:
          type: string
          enum: [UAT, Production]
        locale: { type: string, example: en-US }
        bridgeVersion: { type: string }