@appnotes/sdk

Embeddable AppNotes SDK for any SPA application.

import { initAppNotes } from "@appnotes/sdk";

const appNotes = initAppNotes({
  projectKey: "appnotes_pk_example",
  roomId: "account-42",
  roomName: "Codeception",
  toggleDomElement: "#appnotes-toggle",
  rootDomElement: document.body,
});

appNotes.open();

SaaS integrations default to https://api.appnotes.tech/api and wss://ws.appnotes.tech/v1. Self-hosted and development integrations should declare both transport endpoints:

const appNotes = initAppNotes({
  projectKey: "appnotes_pk_example",
  roomId: "account-42",
  endpoints: {
    apiUrl: "https://notes.example.com/api",
    realtimeUrl: "wss://notes.example.com/api/realtime",
  },
});

The legacy apiUrl option remains supported and derives a WebSocket URL by appending /realtime; explicit endpoints are preferred because they do not couple the two transports to one routing convention.

roomId is the stable room key used to isolate and filter notes. The optional roomName is a human-readable label shown in the drawer header and dashboard room filter. When the active account changes, update both values together:

appNotes.setRoom(nextAccount.id, nextAccount.name);

If roomName is omitted, AppNotes displays roomId as before.

The SDK mounts the button and drawer in separate Shadow DOM roots, tracks navigation through the History API, keeps the short-lived access token in memory, and automatically rotates it through a project-specific HttpOnly refresh cookie. The refresh credential is never returned to JavaScript and is never written to the host application's storage. Existing SDK credentials are removed from localStorage during the first initialization after upgrading; users must sign in again after the server-side session-scope migration.

SDK requests use credentials: "include". Production therefore requires HTTPS, an exact allowed origin for the project, and browser support for the API's SameSite=None; Secure third-party cookie. A host may explicitly provide the storage option to persist the access token, but the SDK still never places the refresh credential in that storage. Omitting storage is the recommended and default memory-only mode.

Members can edit, pin, archive, and restore their own notes, while owners and administrators can manage every note. Any writable member can change a note's open or resolved status. Pinned notes appear above the creation-date-ordered list. It subscribes to room changes over WebSocket and synchronizes the current REST representation whenever an event arrives or the connection is restored. It also synchronizes when the browser window regains focus. Per-user unread counters are shown on the launcher, tabs, and note cards; opening a note marks the fetched version as read. Notes created from the All tab apply to the whole room, while notes created from the This page tab remain bound to the current page. Writable members can attach up to ten images or files to their own notes and comments. Images are previewed inside the drawer, while every file is downloaded through the authenticated API; the SDK never exposes a server storage path. Each file is limited to 20 MiB. Supported formats are JPEG, PNG, GIF, WebP, PDF, UTF-8 text, CSV, Markdown, and log files. On screens wider than 640px, the drawer reserves its configured width on the document body so the host page reflows beside it. The host page's minimum width is preserved, allowing native horizontal scrolling when the remaining viewport is too narrow. On smaller screens, the drawer remains a full-screen panel. Its open or closed state is stored per project in localStorage and restored on the next page load.

The browser build exports the same API as window.AppNotes.init(options). SaaS serves the short-cache alias from https://js.appnotes.tech/appnotes.global.js and immutable releases from https://js.appnotes.tech/v<VERSION>/appnotes.global.js.

Host applications with Content Security Policy must allow https://js.appnotes.tech in script-src and both https://api.appnotes.tech and wss://ws.appnotes.tech in connect-src.