farvex 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# farvex
+
+## 0.1.0
+
+### Minor Changes
+
+- scaffold: initial publishable package with ESM + CJS dual format, subpath exports (`./core`, `./react`), tsup build, vitest + jsdom tests, oxlint + oxfmt, and changesets versioning.

package/README.md

@@ -0,0 +1,144 @@
+# farvex
+
+Web SDK for Callpad sessions — a thin, React-friendly wrapper over LiveKit and the Callpad Pulse realtime layer for managing WebRTC and SIP sessions.
+
+> Scaffold state. No SDK surface is exposed yet beyond placeholder exports that prove the build pipeline. The first published version will be `0.1.0`; the real SDK surface lands in the next iteration.
+
+## Install
+
+```sh
+npm i farvex
+# or
+pnpm add farvex
+# or
+bun add farvex
+```
+
+React and react-dom are optional peer dependencies (only needed when you import from `farvex/react`):
+
+```sh
+pnpm add react react-dom
+```
+
+## Subpath exports
+
+| Entry          | Use when                                                       |
+| -------------- | -------------------------------------------------------------- |
+| `farvex`       | Curated top-level exports (ships placeholder during scaffold). |
+| `farvex/core`  | Framework-agnostic client (browser-safe at module load).       |
+| `farvex/react` | React hooks and providers. Carries `"use client"` for Next.js. |
+
+```ts
+import { version } from "farvex";
+import { corePlaceholder } from "farvex/core";
+import { reactPlaceholder } from "farvex/react";
+```
+
+Both ESM and CJS builds ship. Types resolve correctly for bundlers, Node 16+ ESM, and Node 16+ CJS.
+
+## Next.js
+
+- Import from `farvex/react` directly inside client components — the build preserves the `"use client"` directive, so no transpile hack is needed.
+- Import from `farvex/core` from server components (no DOM access at module load).
+- No `next.config.js` `transpilePackages` changes required.
+
+## Vite
+
+- Works out of the box. Vite consumes the ESM output.
+- `react` and `react-dom` are `external` at build time; your app supplies them.
+
+## Local development
+
+From `websdk/`:
+
+```sh
+bun install
+bun run dev         # tsup watch mode; rebuilds dist/ on change
+bun run test        # vitest smoke tests
+bun run check       # lint + format + typecheck
+bun run build       # one-off production build
+```
+
+### Linking into a consumer app (goagentfe, customer app, etc.)
+
+We recommend [`yalc`](https://github.com/wclr/yalc) over `pnpm link` / `bun link` because it survives Vite and Next.js module caches.
+
+One-time setup:
+
+```sh
+# inside websdk/
+bun run dev                # keep running; watches src/ and rebuilds dist/
+npx yalc publish --push    # in another shell, first time
+```
+
+In the consumer app (e.g. `goagentfe`):
+
+```sh
+npx yalc add farvex
+pnpm install
+```
+
+Each change in `websdk/`:
+
+```sh
+# inside websdk/
+npx yalc push              # push built dist/ to subscribers
+```
+
+Before committing in the consumer app, undo the local link so `package.json` doesn't point at `file:.yalc/farvex`:
+
+```sh
+npx yalc remove --all
+pnpm install
+```
+
+## Release flow
+
+See `sdk-scaffold.md` at the repo root for the full plan. Short version (manual, no CI yet):
+
+```sh
+# while working on a change (from repo root or websdk/):
+bun run changeset
+
+# when ready to publish (from websdk/), on clean main:
+bun run version              # applies pending changesets, writes CHANGELOG.md
+git commit -am "chore: release farvex@x.y.z"
+bun run release              # builds, runs changeset publish
+git push --follow-tags
+```
+
+Before the first real publish:
+
+```sh
+npm login                    # as the publisher account
+npm view farvex              # must return 404
+bun run build
+bunx publint
+bun pm pack                  # inspect the tarball contents
+```
+
+Pre-1.0: every feature ships as a `minor` bump; breaking changes allowed without a major.
+
+## Package conventions
+
+- Side-effect free — `"sideEffects": false` in `package.json`. Tree-shakes cleanly.
+- No top-level access to `window`, `document`, `navigator`, `RTCPeerConnection`, or `localStorage`. Any such access happens inside methods or effects.
+- `typescript/no-explicit-any` is enforced by oxlint; we avoid `unknown` in exported types by convention.
+- `engines.node >= 18`.
+
+## Layout
+
+```
+websdk/
+  src/
+    index.ts              public entry (curated re-exports later)
+    core/index.ts         framework-agnostic client
+    react/index.ts        React hooks + providers
+  test/                   vitest + jsdom smoke tests
+  dist/                   build output (gitignored)
+  tsup.config.ts          build config (ESM + CJS + dts, use-client preserved)
+  tsconfig.json           strict TS, bundler resolution
+  vitest.config.ts        jsdom test env
+  .oxlintrc.json          lint rules (matches apps/main)
+  .oxfmtrc.json           format rules (matches apps/main)
+```

package/dist/core/index.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+// src/core/index.ts
+var corePlaceholder = "farvex/core";
+
+exports.corePlaceholder = corePlaceholder;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/index.ts"],"names":[],"mappings":";;;AAAO,IAAM,eAAA,GAAkB","file":"index.cjs","sourcesContent":["export const corePlaceholder = \"farvex/core\";\n"]}

package/dist/core/index.d.cts

@@ -0,0 +1,3 @@
+declare const corePlaceholder = "farvex/core";
+
+export { corePlaceholder };

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+declare const corePlaceholder = "farvex/core";
+
+export { corePlaceholder };

package/dist/core/index.js

@@ -0,0 +1,6 @@
+// src/core/index.ts
+var corePlaceholder = "farvex/core";
+
+export { corePlaceholder };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/core/index.ts"],"names":[],"mappings":";AAAO,IAAM,eAAA,GAAkB","file":"index.js","sourcesContent":["export const corePlaceholder = \"farvex/core\";\n"]}

package/dist/index.cjs

@@ -0,0 +1,8 @@
+'use strict';
+
+// src/index.ts
+var version = "0.0.0";
+
+exports.version = version;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAAO,IAAM,OAAA,GAAU","file":"index.cjs","sourcesContent":["export const version = \"0.0.0\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,3 @@
+declare const version = "0.0.0";
+
+export { version };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare const version = "0.0.0";
+
+export { version };

package/dist/index.js

@@ -0,0 +1,6 @@
+// src/index.ts
+var version = "0.0.0";
+
+export { version };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAAO,IAAM,OAAA,GAAU","file":"index.js","sourcesContent":["export const version = \"0.0.0\";\n"]}

package/dist/react/index.cjs

@@ -0,0 +1,9 @@
+"use client";
+'use strict';
+
+// src/react/index.ts
+var reactPlaceholder = "farvex/react";
+
+exports.reactPlaceholder = reactPlaceholder;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/react/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;AAAO,IAAM,gBAAA,GAAmB","file":"index.cjs","sourcesContent":["export const reactPlaceholder = \"farvex/react\";\n"]}

package/dist/react/index.d.cts

@@ -0,0 +1,3 @@
+declare const reactPlaceholder = "farvex/react";
+
+export { reactPlaceholder };

package/dist/react/index.d.ts

@@ -0,0 +1,3 @@
+declare const reactPlaceholder = "farvex/react";
+
+export { reactPlaceholder };

package/dist/react/index.js

@@ -0,0 +1,7 @@
+"use client";
+// src/react/index.ts
+var reactPlaceholder = "farvex/react";
+
+export { reactPlaceholder };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";AAAO,IAAM,gBAAA,GAAmB","file":"index.js","sourcesContent":["export const reactPlaceholder = \"farvex/react\";\n"]}

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "farvex",
+  "version": "0.1.0",
+  "description": "Web SDK for Callpad sessions (LiveKit + Pulse)",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./core": {
+      "import": {
+        "types": "./dist/core/index.d.ts",
+        "default": "./dist/core/index.js"
+      },
+      "require": {
+        "types": "./dist/core/index.d.cts",
+        "default": "./dist/core/index.cjs"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": {
+        "types": "./dist/react/index.d.cts",
+        "default": "./dist/react/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.5.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "jsdom": "^25.0.0",
+    "oxfmt": "^0.38.0",
+    "oxlint": "^1.53.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "5.8.3",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "check": "bun run lint && bun run format:check && bun run typecheck",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "bun run build && changeset publish",
+    "prepublishOnly": "bun run check && bun run test && bun run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "callpad",
+    "sessions",
+    "livekit",
+    "webrtc",
+    "sip",
+    "realtime",
+    "react"
+  ]
+}