@guidelytech/sdk-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,156 @@
-# Temporary Holding Version
+# @guidelytech/sdk-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-independent Guidely browser SDK: loads the published configuration for an environment,
+identifies users, tracks events, evaluates targeting/trigger/frequency rules and renders guides
+through `@guidelytech/guide-runtime`. Framework adapters (`@guidelytech/react`, `@guidelytech/nextjs`,
+`@guidelytech/svelte`, `@guidelytech/sveltekit`) and the script-tag build (`@guidelytech/embed`) wrap this
+package.
+
+```bash
+pnpm add @guidelytech/sdk-core
+```
+
+```ts
+import { createGuidely } from "@guidelytech/sdk-core";
+
+const guidely = createGuidely({
+  projectId: "pk_dev_demo_react",      // environment public key (not a secret)
+  apiUrl: "http://localhost:3000",     // defaults to https://api.guidely.app
+  environment: "development",
+});
+
+await guidely.ready();
+await guidely.identify("user_123", { role: "admin", plan: "pro" }, { id: "acme", traits: { seats: 12 } });
+guidely.track("contact_created", { source: "import" });
+guidely.on("guide:complete", (guide) => console.log("completed", guide.key));
+```
+
+The module is safe to import during SSR (nothing touches `window` at module scope).
+`createGuidely()` throws a friendly error when called on the server.
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `projectId` | — | Environment public key (`pk_dev_…`, `pk_stag_…`, `pk_prod_…`). Required. |
+| `environment` | inferred from key prefix | `development` \| `staging` \| `production`; exposed to targeting (`environment` field). |
+| `apiUrl` | `https://api.guidely.app` | Base URL of the Guidely API. Demos use `http://localhost:3000`. |
+| `debug` | `false` | Log trigger decisions and requests with `console.debug("[Guidely]", …)`. |
+| `analytics` | `true` | Send analytics events. Guides still render when `false`. |
+| `consent` | `"granted"` | `"pending"` buffers events (persisted) until `setConsent("granted")`; `"denied"` disables analytics. |
+| `storage` | `"local"` | `"local"` \| `"session"` \| `"memory"` for identity, cached config, state and queue. |
+| `pollIntervalMs` | `1000` | Idle re-check interval (min 250ms): re-arms `element_visible` triggers whose target appears without navigation and drains the guide queue. |
+| `configRefreshMs` | `300000` | Periodic config refresh (`If-None-Match` → 304 when unchanged). |
+| `maskSelectors` | `[]` | Elements whose text is never captured in authoring picks (merged with the project setting). |
+| `onError` | — | Receives every error the SDK swallows (network, rendering). |
+| `theme` | — | Overrides for the project theme (`primaryColor`, `backgroundColor`, `textColor`, `borderRadius`, `fontFamily`). |
+| `user` | — | `{ id, traits?, account? }` to identify immediately. |
+| `fetch` | global | Custom `fetch` (tests, polyfills). |
+| `disableAuthoring` | `false` | Ignore `?guidely_authoring=` in the URL. |
+
+## API
+
+All methods are safe to call at any time; failures are reported through `onError` / the `error`
+event, never thrown into the host application.
+
+| Method | Description |
+|---|---|
+| `init(): Promise<void>` / `ready(): Promise<void>` | Load config (cache first, then network), wire listeners, evaluate triggers. Idempotent. Resolves even when the API is unreachable (cached config is used; an `error` event is emitted). |
+| `identify(userId, traits?, account?)` | POST `/sdk/identify`; merges server state (audiences, guide history, checklist progress, submitted surveys). Local state wins when both exist. Re-evaluates triggers (`segment_enter`, targeting). |
+| `setAccount({ id, traits? })` | Sets the account for the current user and re-identifies. |
+| `updateTraits(traits)` | Merges traits and re-identifies. |
+| `reset()` | New anonymous id, cleared user and local state, new session; triggers re-evaluated. |
+| `track(name, properties?)` | Custom event. Drives `event` triggers, `advanceOn: "event"` steps and checklist tasks (`completion: "event"`). Keys matching `SENSITIVE_PROPERTY_PATTERN` are stripped. |
+| `page(url?)` | Records a `page_view` and re-evaluates triggers. Called automatically on SPA navigation (History API patch + `popstate` + `hashchange`); adapters call it explicitly too. |
+| `setConsent("granted" \| "denied" \| "pending")` | Runtime consent changes. |
+| `startGuide(idOrKey, { stepId? })` | Starts a guide regardless of targeting/frequency, replacing any active guide. Checklists open their panel. Returns `false` for unknown guides. |
+| `stopGuide()` | Removes the active guide silently (no dismiss event). |
+| `dismissGuide()` | Dismisses the active guide (records `guide_dismissed`). |
+| `getActiveGuide(): PublishedGuide \| null` | The exclusive guide currently showing. |
+| `getGuides(): readonly PublishedGuide[]` | Published guides for this environment. |
+| `isGuideCompleted(idOrKey)` | From merged local + server state. |
+| `getChecklistProgress(idOrKey)` | `{ completedTaskIds, completedAt, dismissedAt }`. |
+| `completeChecklistTask(idOrKey, taskId)` | Manual completion; syncs to `/sdk/checklists/:id/progress`. |
+| `openChecklist(idOrKey)` / `closeChecklist(idOrKey)` | Show/hide the checklist panel (re-renders a dismissed checklist). |
+| `openResourceCenter()` / `closeResourceCenter()` | Toggle the resource center panel. |
+| `refresh()` | Re-fetch config now. |
+| `on(event, cb): () => void` / `off(event, cb)` | Subscribe to events (below). |
+| `getContext()` | The `TargetingContext` used for rule evaluation (debugging). |
+| `getState()` | Debug snapshot: ready flag, ids, config version, active/queued guides, widgets, state, pending events. |
+| `destroy()` | Full cleanup: guides, widgets, listeners, timers, the `#guidely-root` host; flushes pending events via `sendBeacon`. A new client can be created afterwards. |
+| `GuidelyClient.init(options)` / `GuidelyClient.get()` | Singleton helpers used by the embed (`window.Guidely.init/get`). |
+
+### Events
+
+`ready(config)`, `config(config)`, `guide:start(guide)`, `guide:step({ guide, stepId, stepIndex })`,
+`guide:complete(guide)`, `guide:dismiss(guide)`, `guide:skip(guide)`,
+`checklist:task({ guide, task, progress })`, `checklist:complete(guide)`,
+`survey:submit({ guide, answers, responseId })`, `resource-center:open()`, `error(Error)`,
+`track(sdkEvent)`, `identify({ userId, anonymousId })`, `authoring({ active })`.
+
+## Behaviour
+
+* **Config**: `GET /api/v1/sdk/config?key=…` with `If-None-Match`; the last good response is cached
+  in storage (`guidely:config:<key>`) and used when offline. Refreshed every `configRefreshMs` and on `refresh()`.
+* **Events**: queued in memory + storage (max 200, oldest dropped), deduped by `eventId`, flushed in
+  batches of ≤50 every 2s, on navigation and on `visibilitychange`/`pagehide` (via `sendBeacon`,
+  falling back to `fetch`). Failed batches retry with exponential backoff (1s → 30s, 5 attempts)
+  and stay queued afterwards.
+* **Triggers**: `page_load`, `url_match`, `event`, `element_click` (delegated capture listener),
+  `element_visible` (IntersectionObserver), `delay`, `after_guide`, `segment_enter`, `manual`.
+  Filtered by `urlPatterns`, `trigger.urlPattern`, targeting rules (`rolloutSalt = guide.id`),
+  frequency (`once`, `once_per_session`, `every_time`, `interval`, `maxImpressions`,
+  `cooldownHours`, `reshowAfterDismiss`) and survey `startAt`/`endAt`.
+* **Exclusivity**: one flow/modal/tooltip/survey at a time, lowest `priority` first,
+  `mutuallyExclusiveWith` respected; banners, checklists, hotspot-only guides and the resource
+  center coexist. Remaining eligible guides queue and show after the active one ends (page-scoped
+  triggers are dropped if the page changed).
+* **Multi-page flows**: `step.url` steps wait for navigation; the active step is persisted in
+  `sessionStorage` (`guidely:active`) so full page loads resume the guide.
+* **Server sync** (fire-and-forget with retries): `POST /sdk/guide-state`,
+  `POST /sdk/checklists/:id/progress`, `POST /sdk/surveys/:id/responses`,
+  `GET /sdk/resource-center/search?q=`.
+
+## Authoring mode
+
+When the URL contains `?guidely_authoring=<token>` the SDK:
+
+1. Strips the parameter (`history.replaceState`) and stores `{ token }` in
+   `sessionStorage["guidely:authoring"]` so SPA navigations keep authoring active.
+2. Calls `GET /sdk/authoring/session?token=` and, when valid, starts the picker from
+   `@guidelytech/guide-runtime` (toolbar, hover outline, click-to-pick) and a 15s heartbeat
+   (`POST /sdk/authoring/session/heartbeat?token=`).
+3. Sends each pick as `window.opener.postMessage({ type: "guidely:pick", sessionId, pick }, dashboardOrigin)`
+   **and** `POST /sdk/authoring/session/picks?token=`.
+
+Messages accepted from `dashboardOrigin` (`event.origin` checked):
+
+| `type` | Payload | Effect |
+|---|---|---|
+| `guidely:preview-step` | `{ step, theme?, appearance? }` | Renders the draft step live (target fallback → modal). |
+| `guidely:preview-guide` | `{ guide: { id?, key?, name?, kind?, version?, config } }` | Runs the draft guide. |
+| `guidely:highlight` | `{ selectors }` | Outlines matches, replies `guidely:highlight-result { counts, resolved }`. |
+| `guidely:stop-preview` | — | Removes the preview. |
+| `guidely:ping` | — | Replies `guidely:pong { url }`. |
+| `guidely:exit` | — | Leaves authoring mode. |
+
+Messages posted to the opener: `guidely:authoring-ready { sessionId, url }`, `guidely:pick`,
+`guidely:highlight-result`, `guidely:preview-ended { reason }`, `guidely:pong`, `guidely:exit`.
+
+## Storage keys
+
+`guidely:anon`, `guidely:seen`, `guidely:config:<key>`, `guidely:etag:<key>`, `guidely:state:<key>`,
+`guidely:user:<key>`, `guidely:queue:<key>` (local/session storage per `storage` option);
+`guidely:session`, `guidely:active`, `guidely:authoring` (sessionStorage).
+
+## Bundle size
+
+`pnpm --filter @guidelytech/sdk-core size` builds a minified ESM bundle and prints gzip sizes:
+
+| Bundle | minified | min+gz |
+|---|---|---|
+| sdk-core + guide-runtime + floating-ui + `@guidelytech/shared/runtime` (everything an app ships) | 115 kB | **35.8 kB** |
+| script-tag build `guidely.js` (authoring schemas inlined) | 215 kB | 62 kB |
+
+The SDK imports only the zod-free `@guidelytech/shared/runtime` entry; the Zod schemas are loaded
+lazily and only when the page enters authoring mode. Budget: 45 kB min+gz for the npm runtime.