kaafil-js 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaafil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# kaafil-js
+
+`kaafil-js` — the **headless** JavaScript/TypeScript SDK for the Kaafil v2 engine.
+
+One npm package: auth/session handling plus every data operation the engine exposes, and the offline engine behind them — local cache, a write-ahead outbox of pending mutations each carrying a fixed idempotency key and drained FIFO-per-trip, delta sync against the authoritative server clock, and conflict classification (transient / conflict / fatal) driven by the engine's error catalog.
+
+**Headless by design.** The SDK ships no UI components; the integrating CRM owns every pixel, under its own brand.
+
+Request/response types are **codegen'd from the engine's published `openapi.json`** with a CI drift-check. The offline machinery is hand-authored.
+
+## Examples
+
+Runnable, public reference examples live in
+**[`kaafil/kaafil-js-examples`](https://github.com/kaafil/kaafil-js-examples)** (MIT). Two halves, one per
+entry point:
+
+- **`server/simulate.ts`** — the CRM-backend half, under Node. The full lifecycle, every step narrated and
+  asserted with a meaningful exit code: trip ingest, manifest push, manager assignment, waiting for the
+  asynchronous journey build, the four-axis capability read, and the typed errors worth branching on.
+- **`browser/`** — the on-ground manager's half, vanilla TypeScript on Vite (no framework, so the SDK calls
+  are what you see). Opens a session from a server-minted token pair and proves the credential boundary.
+
+That repo is not a sample left to rot: its Node half runs inside the engine's own smoke gate against a live
+stack, so a change that breaks the published example fails the same gate that breaks this package.
+
+**One prerequisite the examples spell out, because missing it looks like a broken SDK:** a browser consumer's
+origin must be allowlisted on the engine (`CORS_ORIGIN`). A blocked request fails `fetch` with no status and
+no body — the browser withholds the response by design — so this SDK can only report it as a transport
+failure and cannot confirm the cause.
+
+## Contracts
+
+Every contract lives in **[`kaafil-product-docs`](https://github.com/kaafil/kaafil-product-docs)** (private) — start with `architecture/08-sdk.md` (SDK design, init, auth, method surface), then `architecture/06-offline-first.md` (cache + outbox + sync), `architecture/03-auth-and-tokens.md` (manager session tokens and share tokens — API keys are server-only and never reach a browser) and `architecture/10-conventions.md §7` (the master error catalog, including how the outbox classifies each code). This README never restates a contract; it points at one.
+
+## Working here
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) — branch and PR rules, conventional commits, and the memory-trail requirements.