@poly-x/core 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,34 @@
+# @poly-x/core
+
+Framework-agnostic core of the [PolyX](../../README.md) SDK — the shared guts the
+`@poly-x/react`, `@poly-x/next`, and `@poly-x/sdk` packages build on. Most apps
+don't import this directly; reach for the framework package instead.
+
+## What's inside
+
+- **Key parsing & config** — `parsePolyXKey`, `resolveConfig`. Keys encode their
+  issuing deployment host, so one value identifies the app *and* locates its
+  PolyX. A secret key reaching the browser throws immediately.
+- **Error taxonomy** — a typed, branchable hierarchy (`PolyXError` →
+  `Unauthenticated`, `SessionExpired`, `SessionRevoked`, `Forbidden`,
+  `Validation`, `RateLimited`, `Upstream`, `ConfigError`). Key material and
+  tokens are redacted on serialization.
+- **Transport** — a `Transport` seam with a fetch implementation (timeout +
+  bounded transient retries) and a `MockTransport` for tests.
+- **Session engine** — the auth state machine (`resolving → authenticated ⇄
+  refreshing → signed-out`), single-flight refresh with reuse→revoke, cross-tab
+  sign-out, and server-authoritative proactive refresh, over swappable seams.
+- **Auth protocol client** — PKCE, authorize-URL building, the membership-outcome
+  parse, code exchange, refresh, logout.
+
+```ts
+import { createSessionEngine, AuthClient, resolveConfig } from "@poly-x/core";
+```
+
+## Install
+
+```bash
+npm install @poly-x/core
+```
+
+MIT licensed. See the [SDK docs](../../docs/) for the full design.