Hosted sites

Client portal kit

Put a working client portal and a staff pipeline on a hosted site with two lines of HTML and no JavaScript of your own. Clients see their requests, messages and documents and can start a new request. Staff move work through its stages and answer clients. Everything on screen comes from the Space's engagement types and forms, so a new kind of work needs no new code.

Set up

1. Turn on sign-inCreate a sign-in client for the Space at /dash/sites/oauth and add its auth block to config.json. See site config.
2. Turn on the add-onThe Space needs the engagements add-on. Without it the portal says it is not switched on.
3. Add a mount pointPut one element on a page. The kit loads itself, signs the person in and fills the element.

Publishing pages that use the kit

A page carries the runtime version from the moment it was published. After the kit changes, re-publish each page that mounts it (an edit to the page or a Rebuild is enough) so it loads the current version. Pages you have not re-published keep working on the version they were published with.

Mount points

<div data-bynli="portal" data-portal-heading="Your requests"></div>

<div data-bynli="portal-admin" data-portal-heading="Engagements"></div>

From a script, await Bynli.use('portal') loads the kit, and Bynli.Portal.mount(el) and Bynli.Portal.mountAdmin(el) fill an element you made yourself.

What a client gets

• A list of their requests with the stage each is at, or its status when the type has no stage for it.
• A request page with progress through the stages the client may see, the messages and updates in order, a message box while the request is open, the documents (download, add, and remove their own), and how to pay when something is due.
• A new request form built from the schema. With one type it shows that type's form fields. With several it asks which kind first. A type with no form, or a Space with no types, gets a short "what do you need" form.
• Booking when the Space has booking open: choose a booking type, pick a free time (shown in the practice's own time zone, which the page names), add a note and send it. Their bookings are listed with a pay link while one is waiting for payment, and a cancel button for the ones that can still be cancelled.
• The form's thank-you after sending, if the linked form has a confirmation message.

What staff get

• A pipeline board. By status, or by one type's stages, internal stages included. Cards stack on a phone.
• One engagement. The client's shared details, the full timeline with internal notes marked, and the documents.
• Charges and payment. On an engagement, edit its charges (description, quantity, price in dollars, and the kind, including discounts), send the client the pay link, open the payment page, and mark it paid when the Space collects the money itself. Settled engagements show their charges read-only.
• Stages and contact. Stage buttons for the engagement's type with the current one pressed, the request reference of the form that started it, and call and email buttons for the client.
• Bookings. A Bookings view next to the pipeline: approve or decline requests (with an optional reason sent to the client), cancel a booking, and retry a refund that did not go through.
• Moves. Change the status to one of the allowed next ones (with a reason, which is sent to the client when it asks them for something), move the stage, send a message to the client, or leave an internal note.

The schema call

{
  "schema": {
    "types": [
      {
        "key": "walks",
        "label": "Dog walk",
        "kind": "service",
        "stages": [
          {"key": "requested", "label": "Requested", "client_visible": true, "status_bucket": "submitted"},
          {"key": "walked", "label": "Walked", "client_visible": true, "status_bucket": "closed"}
        ],
        "bookingTypeId": "bkt_0123456789abcdef0123456789abcdef",
        "form": {
          "id": "frm_0123456789abcdef0123456789abcdef",
          "name": "Walk request",
          "message": "Thanks, we will be in touch.",
          "fields": [
            {"key": "field_12", "label": "Dog name", "type": "text", "required": true, "placeholder": null, "help": null, "options": []},
            {"key": "field_13", "label": "Size", "type": "dropdown", "required": true, "placeholder": null, "help": null, "options": ["Small", "Medium", "Large"]}
          ]
        }
      }
    ],
    "bookingTypes": [],
    "statuses": ["draft", "submitted", "awaiting_payment", "in_review", "info_needed", "filing", "filed", "issued", "closed", "cancelled"],
    "messageClosed": ["draft", "closed", "cancelled"],
    "kinds": ["formation", "service"],
    "limits": {"title": 160, "message": 4000, "answer": 2000}
  }
}

• Forms. form is null when the type has no form, or the form is paused or a registration form. Hidden fields are never listed. A section_header is a heading, not a question.
• Booking types. The Space's active booking types, only once it has opening hours. bookingTypeId is the booking type linked to the engagement type, or null.
• Before the update. A Space whose database has not got engagement types yet answers 200 with empty types, so the kit falls back to the short form.
• Add-on. Both calls answer 403 addon_required like the other engagement routes.

Starting a request from a type

POST /portal/engagements also takes a type. Send type (the type's key) and answers, an object keyed by the form's field_ keys. The request is created as a draft at the type's first stage with the type's default items, the answers become the first message (Label: value, one per line), and the client then sends it with POST /portal/engagements/{id}/submit.

{"type": "walks", "answers": {"field_12": "Rex", "field_13": "Large"}}

Styling and accessibility

• Neutral by default. The kit inherits the page's font and colours, and uses the browser's light or dark scheme for its own surfaces. Style the classes that start with bynli-portal- to match the site.
• Touch targets. Every button, field, select and choice is at least 44 pixels tall. Nothing makes the page scroll sideways at 390 pixels.
• Announced. Errors use an alert, confirmations a status message, the list of stages marks the current step, and the heading takes focus when the view changes. Required fields are marked for assistive technology.

Safety

• No markup from data. Titles, messages, names, file names and form labels are written as text, never as HTML. A request called <img onerror=...> shows exactly that.
• Links. A payment link appears only if it is an https:// address, and opens in a new tab with no access back to the page.
• The token stays in the sign-in kit. The portal sends it as a bearer header on each call and asks for no cookies.
• The server decides. The kit only shows what the API returns. A client cannot see another client's request, a stage marked staff-only, or an internal note, whatever the page does.