SDKs — Client Portals

Client Portals SDK

Licensable portal layer: gate, account, tickets, feedback, quicklinks, viewer, and custom content pages. The portal-shell.js runtime injects nav, footer, auth, and theme into any HTML page via a single script tag. The TypeScript package adds typed config, validation, and scaffold helpers.

SDK Portals JavaScript Cloudflare Pages

Overview

Client Portals is a standalone, licensable product. Each client gets a subdomain at <slug>.clientportals.vip — a private Cloudflare Pages site gated by a passphrase. The portal shell handles chrome (nav, footer, auth, theme) and exposes a feedback and ticketing API hosted at api.clientportals.vip.

The shell is deliberately a single vanilla JS file with no dependencies. Any HTML page becomes a portal page with one script tag.

Module catalog

gate.html
Passphrase login. Sets session auth key on success. No portal-shell script.
No shell
index.html
Portal home. Quicklinks, doc cards, hero image. Full nav with Account dropdown.
Content
account.html
Profile and team name fields. Saves to localStorage per tenant.
Chrome
tickets.html
Ticket submission form. Posts to feedback API ticketKey endpoint.
Chrome
feedback.html
General feedback form. Chrome page — toolbar always off.
Chrome
viewer.html
Full-screen document viewer. Toolbar active.
Content
Custom pages
Strategy docs, design pages, any inner section. Toolbar active when feedbackKey is set.
Content

Runtime script

Served from https://api.clientportals.vip/portal-shell.js. Drop one script tag into any portal page:

<script src="https://api.clientportals.vip/portal-shell.js"></script>

The script reads configuration from window.PORTAL_CONFIG (required) and inserts the nav and footer synchronously. Auth is enforced immediately on load before any page content renders.

The runtime file in the repo lives at services/feedback-api/portal-shell.js. After any change, sync and restart on ArcHelm:

cp ~/projects/the-grid/services/feedback-api/portal-shell.js \
  ~/portal-feedback-api/portal-shell.js
bash ~/restart-api.sh

PORTAL_CONFIG reference

Define window.PORTAL_CONFIG in a portal.config.js file loaded before the portal-shell script tag. Every chrome page (account, tickets, feedback) must also include portal.config.js or auth will fail.

// portal.config.js
window.PORTAL_CONFIG = {
  tenant:      'fortknox',
  clientName:  'Fort Knox',
  wordmark:    'Fort Knox',
  feedbackKey: 'fk-fortknox-fbk-8v1j6q',
  ticketKey:   'fk-fortknox-tkt-1n8p5r',
  themeKey:    'fk-theme',
  authKey:     'fk_fortknox_auth',
  clientId:    '178b6350-95c4-4697-b29e-52387b443328',
};
FieldTypeRequiredDescription
tenantstringrequiredSlug used by the feedback API. No hyphens — strip them (beyond-sleep becomes beyondsleep).
clientNamestringrequiredFull client display name shown in the Account dropdown.
feedbackKeystringrequiredx-api-key for /pins feedback endpoints. Issued per tenant in portal-feedback-api/.env.
themeKeystringrequiredlocalStorage key for theme preference. Must be unique per client. Convention: <tenant>-theme.
authKeystringrequiredsessionStorage key set by gate.html on login. Must be unique. Convention: <tenant>_auth.
wordmarkstringoptionalNav display name. Defaults to clientName.
ticketKeystringoptionalx-api-key for /tickets endpoints. Omit if tickets module is not active.
clientIdstring (UUID)optionalSurface client UUID. Required for review-share.js reviewer link generation.
heroImagestring (URL)optionalHero image on the portal index page. Defaults to the shared stock photo.
allowSignupbooleanoptionalRenders a "Request access" flow on gate.html. Defaults to false.

Toolbar rules

The feedback toolbar appears on inner (content) pages when feedbackKey is set. It is always suppressed on chrome pages.

Page typedata-toolbar attributeToolbar
gate.htmlNo portal-shell scriptNever
account, tickets, feedbackdata-toolbar="off"Never
index, viewer, custom contentOmit attributeWhen feedbackKey is set

Pages in subdirectories (strategy/, docs/) also need data-index and data-gate attributes on the portal-shell script tag, otherwise nav and auth redirect to the wrong paths.

TypeScript package

The @arcgrid/portal-shell package at packages/portal-shell/ provides typed config, a validation helper, and a programmatic scaffold wrapper.

import { createPortalConfig, PORTAL_PAGE_TYPES } from '@arcgrid/portal-shell'

const config = createPortalConfig({
  tenant:      'fortknox',
  clientName:  'Fort Knox',
  feedbackKey: 'fk-fortknox-fbk-8v1j6q',
  themeKey:    'fk-theme',
  authKey:     'fk_fortknox_auth',
})
// throws if required fields are missing or tenant contains hyphens

Key exports: PortalConfig interface, createPortalConfig(), scaffoldKeys(), PORTAL_PAGE_TYPES, TOOLBAR_RULES, CHROME_PAGES.

Scaffold a portal

Always scaffold from the template — never build from scratch.

bash scripts/new-portal.sh <slug> "Client Name" ["Eyebrow Text"]

This copies all template pages, generates a portal.config.js with fresh API keys, and creates a wrangler.toml. After scaffolding:

1
Set the gate passphrase
Edit clients/<slug>/portal/gate.html and replace CHANGEME.
2
Register API keys on ArcHelm
Add both generated keys to ~/portal-feedback-api/.env TENANT_KEYS, then run bash ~/restart-api.sh.
3
Create Cloudflare Pages project
Project name is always <slug>-portal.
4
Deploy from ArcHelm
npx wrangler pages deploy clients/<slug>/portal --project-name <slug>-portal --branch main
5
DNS
CNAME <slug>.clientportals.vip to <slug>-portal.pages.dev.

Deploy

Always deploy from ArcHelm, not from a local machine. Always verify the branch before deploying:

git branch --show-current
npx wrangler pages deploy clients/<slug>/portal \
  --project-name <slug>-portal \
  --branch main

After deploying, run the post-deploy checklist: gate passphrase, toolbar presence on content pages, toolbar absence on chrome pages, theme persistence, account page loads without redirect.

Run python3 scripts/audit-portal.py <slug> to catch THEME-KEY, CFG-ORDER, and CHROME-NO-CFG flags before and after any migration.