Skip to content

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 appKey alone the SDK starts its own session (POST /v1/sessions/sdk) as a guest. Rafiq names the guest, and the page keeps its guest_token in localStorage (store replaces it), so the person stays the same guest. userToken makes 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 of appKey: a session your server mints with the app’s secret (POST /v1/sessions with sk_…). 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
    );

    tools in init is 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-src to baseUrl (and hostApiBase), and img-src/media-src to where files are served (baseUrl, or the API’s public URL). No style-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.js sets window.RafiqWeb (init, openChat, …) and registers the elements. A screen written in the page before init() 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.