@usereq/widget 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# @usereq/widget
+
+Single-package repository for widget runtime/shared exports and embed bundle.
+
+## What this package contains
+
+- Core/shared TypeScript exports from root `src`.
+- Embed browser IIFE bundle generated at root `dist/widget.js`.
+
+This repo publishes **one npm package**: `@usereq/widget` (scoped; see `package.json`).
+
+## Repository layout
+
+- `src` (core, shared, runtime, custom-element, embed entry)
+- `dist` (built embed artifact; created by `bun run build`)
+- `tsconfig.json` (global TS config)
+- `.env.example` (optional local env template; not loaded automatically—copy to `.env` / `.env.production` as needed)
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) 1.2+ (matches `packageManager` in `package.json`)
+- npm CLI for publishing (`npm whoami`, `npm publish`)
+- npm account with publish permission to the `@usereq` scope (or change the package `name` before publishing elsewhere)
+
+## Environment variables
+
+These matter when you run **`bun run build`** (specifically the Vite embed step). Vite reads them from the repo root via `.env`, `.env.local`, `.env.production`, `.env.production.local`, and so on (see [Vite env files](https://vitejs.dev/guide/env-and-mode.html#env-files)). `vite build` uses mode **`production`**, so `.env.production` is the usual place for release API URLs.
+
+| Variable | When set | Effect |
+| --- | --- | --- |
+| `USEREQ_WIDGET_DEV_API_BASE` | Embed build | Highest-priority API origin (useful for dev-tag releases). If set, it overrides `USEREQ_WIDGET_API_BASE`. |
+| `USEREQ_WIDGET_API_BASE` | Embed build | Preferred API origin string inlined into `dist/widget.js` (no trailing slash normalization at build time; the runtime trims and strips trailing slashes). |
+| `NEXT_PUBLIC_API_URL` | Embed build | Used only if `USEREQ_WIDGET_API_BASE` is empty—handy if you already define this in a Next.js monorepo. |
+| *(neither set)* | Embed build | Falls back to `http://localhost:3000` in the Vite config. |
+
+**Runtime `globalThis` (advanced):** `getWidgetApiBase()` (see `src/runtime/api-origin.ts`) prefers the compile-time `__USEREQ_WIDGET_API_BASE__` value when it is non-empty after trimming. The Vite embed build always defines that symbol to a non-empty string (see defaults above), so **changing the API URL for the published `dist/widget.js` requires a rebuild with a different `USEREQ_WIDGET_API_BASE`**. The `globalThis.__USEREQ_WIDGET_API_BASE__` path mainly applies when consuming source from this package without inlining a base URL (for example your own bundler without that `define`). If nothing resolves, the function falls back to `http://localhost:4000`.
+
+Example for a production embed build:
+
+```bash
+USEREQ_WIDGET_API_BASE=https://api.example.com bun run build
+```
+
+Or create `.env.production` in the repo root (gitignored by default; copy from `.env.example`).
+
+## Install
+
+```bash
+bun install
+```
+
+## Development
+
+Typecheck:
+
+```bash
+bun run typecheck
+```
+
+Build core + embed:
+
+```bash
+bun run build
+```
+
+Build individual targets:
+
+```bash
+bun run build:core
+bun run build:embed
+```
+
+## Build outputs
+
+- Core/shared exports are served from root `src`.
+- Embed bundle is emitted at root `dist/widget.js` (plus css artifact if emitted).
+
+## Usage
+
+### Core/shared exports
+
+```ts
+import { registerWidgetElement } from "@usereq/widget/register";
+registerWidgetElement();
+```
+
+### Embed bundle from same package
+
+The package exports embed at subpath `@usereq/widget/embed` (maps to `dist/widget.js`).
+
+For CDN/script usage, use:
+
+- unpkg: `https://unpkg.com/@usereq/widget/dist/widget.js`
+- jsDelivr: `https://cdn.jsdelivr.net/npm/@usereq/widget/dist/widget.js`
+
+The embed entry automatically registers `<usereq-agent-widget>`.
+
+## Publish guide
+
+Publish once from this repo root. The package is **scoped** (`@usereq/widget`); `publishConfig.access` is already `public`.
+
+### 1) Login and verify permissions
+
+```bash
+npm whoami
+# If needed:
+npm login
+```
+
+Ensure you are logged in as a user or CI token that is allowed to publish under the `@usereq` scope on npm.
+
+### 2) Bump version
+
+Update `version` in root `package.json` only.
+
+To publish under a different scope or unscoped name, change the `name` field and update import paths / CDN URLs in your own docs accordingly.
+
+### 3) Set API base for production (recommended)
+
+Set `USEREQ_WIDGET_API_BASE` (or `.env.production`) so the published `dist/widget.js` targets your production API. Skipping this bakes in the default from Vite (`http://localhost:3000`).
+
+### 4) Clean build before publish
+
+```bash
+bun run typecheck
+bun run build
+```
+
+Confirm `dist/widget.js` exists (the `files` field includes `dist` and `src`).
+
+### 5) Sanity check contents (optional)
+
+```bash
+npm pack --dry-run
+```
+
+### 6) Publish
+
+```bash
+npm publish
+```
+
+`--access public` is optional here because `package.json` already sets `publishConfig.access` to `public`.
+
+### 7) Verify
+
+```bash
+npm view @usereq/widget version
+```
+
+### GitHub Actions
+
+- **CI** (`.github/workflows/ci.yml`): runs on pull requests and on pushes to `main` / `master` — `bun install --frozen-lockfile`, `bun run typecheck`, `bun run build`.
+- **Publish** (`.github/workflows/publish.yml`): runs when you push tags matching:
+  - `v*` (for example `v0.2.0`) → publishes to npm default `latest` tag.
+  - `dev-v*` (for example `dev-v0.2.0-dev.1`) → publishes to npm `dev` dist-tag.
+  Configure repository secrets:
+  - **`NPM_TOKEN`** (required): npm automation token able to publish `@usereq/widget`.
+  - **`USEREQ_WIDGET_API_BASE`** (optional): production API base for normal `v*` releases.
+  - **`USEREQ_WIDGET_DEV_API_BASE`** (optional): dev API base used by `dev-v*` releases.
+  - For `dev-v*` publishes, keep `package.json` `version` unique (for example prerelease versions like `0.2.0-dev.1`), because npm does not allow publishing the same version twice even with different dist-tags.
+
+## Notes
+
+- No workspace dependency is required for this repo itself; published consumers still install `@usereq/widget`’s npm `dependencies` (for example `@usereq/ui`) like any other package.
+- One package version controls both core/shared exports (`src` via `exports`) and the embed artifact (`dist/widget.js`).

package/dist/widget.css

@@ -0,0 +1,2 @@
+@keyframes sd-fadeIn{0%{opacity:0}to{opacity:1}}@keyframes sd-blurIn{0%{opacity:0;filter:blur(4px)}to{opacity:1;filter:blur()}}@keyframes sd-slideUp{0%{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}[data-sd-animate]{animation:var(--sd-animation,sd-fadeIn) var(--sd-duration,.15s) var(--sd-easing,ease) var(--sd-delay,0s) both}
+/*$vite$:1*/