Web
Install
npm install @heysada/rafiq
An assistant inside your web app: chats with your people and the AI, scoped Skills references and the
settings screen, as Web Components on a typed core. They work in React, Vue, Angular or a plain page.
Apache-2.0 (LICENSE). The design is ADR 027 §6–§7
(docs/decisions/027-rafiq-platform.md); the API is
services/rafiq (“Chats”, “The embedded API”, “Client calls” in its README).
The only runtime dependency is lit. Nothing on screen names a product: the assistant is called
by the client’s assistant_name, then the app’s design (brand.assistant_name, brand.name), then
the app’s own name.
Install
npm install @heysada/rafiq
Or one <script> tag, pinned to a version (it sets window.RafiqWeb and registers the elements,
with lit and the view renderer inside):
<script src="https://cdn.jsdelivr.net/npm/@heysada/[email protected]/dist/rafiq.iife.js"></script>
The package carries the view renderer inside it: there is nothing else to install
but lit, which npm brings.
Set it up
Copy the app’s key from the panel’s Install screen. That is all a guest’s chat needs:
import { init, openChat } from "@heysada/rafiq";
const rafiq = init({
baseUrl: "https://assistant.example.com", // the Install screen fills it in
appKey: "pk_…",
// Optional: the signed-in person. Your server signs a short HS256 token with the app's
// identity secret ({ sub, name?, exp } at most 24 hours on); null while nobody is signed in.
userToken: () => fetch("/api/rafiq-token").then((r) => (r.ok ? r.text() : null)),
// Your own API, which the app's own calls (the Actions screen) go to, with the page's cookies.
hostApiBase: "https://shop.example.com/api",
});
helpButton.addEventListener("click", () => openChat());
-
Guests and the signed-in. With
appKeyalone the SDK starts its own session (POST /v1/sessions/sdk) as a guest. Rafiq names the guest, and the page keeps itsguest_tokeninlocalStorage(storereplaces it), so the person stays the same guest.userTokenmakes the session the signed-in person’s. A guest’s run never changes anything through your server or MCP actions; your page’s own calls run with the page’s session. -
Where it works. A live app’s key works only on the origins listed on the Install screen.
-
Advanced:
session(a token, or a function) instead ofappKey: a session your server mints with the app’s secret (POST /v1/sessionswithsk_…). It is asked again, once, on a 401. -
The page’s own tools, in the WebMCP draft’s shape, so one object can be given to both:
rafiq.registerTool( { name: "add_to_cart", description: "Adds an item to the person's cart", inputSchema: { type: "object", properties: { sku: { type: "string" } }, required: ["sku"] }, execute: async ({ sku }) => cart.add(String(sku)), }, { signal: pageController.signal }, // aborting it takes the tool back );toolsininitis the same, by name ({ description, parameters, run }). -
Ratings. Each answer has a thumbs up and down, and a thumbs down asks, optionally, what went wrong.
ChatSession.rate(messageId, "up" | "down" | null, comment?)does the same from code. -
CSP: allow
connect-srctobaseUrl(andhostApiBase), andimg-src/media-srcto where files are served (baseUrl, or the API’s public URL). Nostyle-src 'unsafe-inline'is needed: the elements and the dialog frame style themselves with adopted (constructable) style sheets. -
With a
<script>tag:dist/rafiq.iife.jssetswindow.RafiqWeb(init,openChat, …) and registers the elements. A screen written in the page beforeinit()runs waits for it.
The screens
| Element | What it is |
|---|---|
<rafiq-chat> |
The person’s chats and the open one. Write to the AI or to the team (the audience toggle), attach files (10 MB each, ten a message), record a voice note (when the browser has MediaRecorder), @ to mention a member, the AI or one of the person’s things the app’s MCP servers list (a post, a campaign, a ticket: @ and words from its title, GET /v1/things?q=… across every kind as they type, picked with ↑/↓ and Enter or Tab, Esc to close; the picked one is marked in the text, the message carries them in things and the assistant reads them with its tools), reply, edit one’s own message (a message to the AI is asked again), answer again, stop the run, teach the assistant a message (with kb.write), see who is in the chat (the owner adds and removes people). Attributes: chat-id, no-list, show-replaced, locale; the suggestions property (strings) shows under a new chat’s greeting, a tap fills the composer. point({uri, title}) starts the next message pointing at a thing: the host page’s “Ask about this” link calls it with the item on screen. |
| ### Embedded Skills contract |
The Skills screen saves one aggregate through /v1/skills: Name, Content (description only),
Trigger words, Facts, Apply to, When and Status. GET returns the complete aggregate and its
revision; PUT requires that revision and returns 409 after a concurrent edit. Web callers use
listSkills, addSkill and updateSkill; KMP uses skills, addSkill and updateSkill.
The signed session supplies app/client scope. kb.read/kb.write still guard this capability.
SDK and taught-chat material remains quoted source data; an activation setting cannot promote
its trust, grant tools or publish private material to Skills Store.
Supported 0.1.x clients retain the /v1/knowledge title/facts/enabled boundary contract and its
public symbols. The adapter builds a complete Skill through the same ai-brain owner, preserving
source, private scope and all other fields on updates. It has no independent authoring table or
resolver. New owned screens use /v1/skills. Remove the boundary with the next major SDK
contract only after the supported-client adoption inventory confirms migration; changing the
UI label alone is not evidence that external clients have upgraded.