@smplkit/sdk 3.0.3 → 3.0.4

package/README.md

@@ -16,34 +16,40 @@ npm install @smplkit/sdk
 
 ## Quick Start
 
+`SmplClient` requires `apiKey`, `environment`, and `service`. Each can come from the constructor, an environment variable, or `~/.smplkit`.
+
 ```typescript
 import { SmplClient } from "@smplkit/sdk";
 
-// Option 1: Explicit API key
-const client = new SmplClient({ apiKey: "sk_api_..." });
+const client = new SmplClient({
+  apiKey: "sk_api_...",
+  environment: "production",
+  service: "my-service",
+});
+
+// Block until cache is warm and the live-updates WebSocket is connected.
+// Optional but recommended at process start so the first reads hit cache.
+await client.waitUntilReady();
 
-// Option 2: Environment variable (SMPLKIT_API_KEY)
-// export SMPLKIT_API_KEY=sk_api_...
-const client2 = new SmplClient();
+// ... do work ...
 
-// Option 3: Configuration file (~/.smplkit)
-// [default]
-// api_key = sk_api_...
-const client3 = new SmplClient();
+client.close(); // releases the WebSocket and stops background timers
 ```
 
+If `SMPLKIT_API_KEY` / `SMPLKIT_ENVIRONMENT` / `SMPLKIT_SERVICE` are set (or a `~/.smplkit` profile supplies them), `new SmplClient()` works with no arguments.
+
 ## Configuration
 
-All settings are resolved from three sources, in order of precedence:
+Settings are resolved in order of precedence:
 
-1. **Constructor options** — highest priority, always wins.
-2. **Environment variables** — e.g. `SMPLKIT_API_KEY`, `SMPLKIT_ENVIRONMENT`.
+1. **Constructor options** — highest priority.
+2. **Environment variables** — `SMPLKIT_API_KEY`, `SMPLKIT_ENVIRONMENT`, `SMPLKIT_SERVICE`, `SMPLKIT_BASE_DOMAIN`, `SMPLKIT_SCHEME`, `SMPLKIT_DEBUG`, `SMPLKIT_DISABLE_TELEMETRY`, `SMPLKIT_PROFILE`.
 3. **Configuration file** (`~/.smplkit`) — INI-format with profile support.
-4. **Defaults** — built-in SDK defaults.
+4. **Built-in defaults**.
 
 ### Configuration File
 
-The `~/.smplkit` file supports a `[common]` section (applied to all profiles) and named profiles:
+`~/.smplkit` supports a `[common]` section (applied to every profile) plus named profiles:
 
 ```ini
 [common]
@@ -61,202 +67,291 @@ environment = development
 debug = true
 ```
 
-### Constructor Examples
-
 ```typescript
-// Use a named profile
 const client = new SmplClient({ profile: "local" });
-
-// Or configure explicitly
-const client = new SmplClient({
-  apiKey: "sk_api_...",
-  environment: "production",
-  service: "my-service",
-});
 ```
 
-For the complete configuration reference, see the [Configuration Guide](https://docs.smplkit.com/getting-started/configuration).
+For the complete reference, see the [Configuration Guide](https://docs.smplkit.com/getting-started/configuration).
 
 ## Config
 
-### Runtime (resolve config values)
+### Runtime — resolve config values
+
+`client.config.get(key)` returns a `LiveConfigProxy`: a read-only, dict-like view that always reflects the latest server-pushed values.
 
 ```typescript
-// Resolve config values for a service
-const config = await client.config.get("my-service");
-console.log(config.getString("timeout"));
-console.log(config.getNumber("retries"));
-
-// Subscribe to live updates
-client.config.subscribe("my-service", (config) => {
-  console.log("Config updated:", config.getString("timeout"));
-});
+const cfg = await client.config.get("user-service");
+
+// Dict-style access — both forms work
+console.log(cfg.get("database.host"));
+console.log(cfg["max_retries"]);
+for (const key of Object.keys(cfg)) console.log(key, cfg[key]);
+
+// Per-config and per-item change listeners
+cfg.onChange((event) => console.log(`${event.itemKey}: ${event.oldValue} -> ${event.newValue}`));
+cfg.onChange("max_retries", (event) => console.log("retries changed:", event.newValue));
+
+// Or attach a global listener that fires for any config change
+client.config.onChange((event) => console.log(`${event.configId}.${event.itemKey} changed`));
+
+// Manual re-fetch (useful after suspecting drift)
+await client.config.refresh();
+```
+
+You can also pass a model class as the second argument; the proxy reconstructs the model from the latest values on every read so attribute access type-checks against your model:
+
+```typescript
+class UserServiceConfig {
+  database!: { host: string; port: number };
+  max_retries!: number;
+  constructor(data: any) {
+    Object.assign(this, data);
+  }
+}
+const typed = await client.config.get("user-service", UserServiceConfig);
+console.log(typed.database.host);
 ```
 
 ### Management (CRUD)
 
+CRUD lives under `client.manage.config.*`. You can also construct a standalone `SmplManagementClient` for setup scripts or admin tooling.
+
 ```typescript
-// Create a config
-const cfg = client.config.management.new("my-service", {
+// Author a config — `set*` mutations are local until `.save()` is called.
+const cfg = client.manage.config.new("my-service", {
   name: "My Service",
   description: "Configuration for my service",
 });
+cfg.setString("database.host", "localhost");
+cfg.setNumber("max_retries", 3);
+cfg.setBoolean("enable_signup", true);
+cfg.setJson("feature_matrix", { v2: true });
+
+// Per-environment override
+cfg.setNumber("max_retries", 5, { environment: "production" });
 await cfg.save();
 
-// List configs
-const configs = await client.config.management.list();
+// Read / list / delete
+const fetched = await client.manage.config.get("my-service");
+const all = await client.manage.config.list();
+await client.manage.config.delete("my-service");
+```
 
-// Get a config by id
-const fetched = await client.config.management.get("my-service");
+A config can have a `parent`; resolved values from the parent are inherited and overridden by the child. The hierarchy is at most two levels deep — the server rejects a parent that itself has a parent.
 
-// Delete a config
-await client.config.management.delete("my-service");
+```typescript
+const child = client.manage.config.new("user-service", {
+  name: "User Service",
+  parent: "my-service", // or pass a Config instance
+});
 ```
 
 ## Flags
 
-### Runtime (evaluate flags)
+### Runtime — evaluate flags
 
 ```typescript
-import { SmplClient, Rule } from "@smplkit/sdk";
+import { SmplClient, Context } from "@smplkit/sdk";
 
 const client = new SmplClient({ environment: "production", service: "my-service" });
+await client.waitUntilReady();
+
+// Declare typed flag handles. The default is returned when smplkit is
+// unreachable or the flag does not exist.
+const checkoutV2 = client.flags.booleanFlag("checkout-v2", false);
+const bannerColor = client.flags.stringFlag("banner-color", "red");
+const maxRetries = client.flags.numberFlag("max-retries", 3);
+
+// Evaluate with explicit per-call context
+const enabled = checkoutV2.get({
+  context: [
+    new Context("user", "alice@acme.com", { plan: "enterprise" }),
+    new Context("account", "1234", { region: "us" }),
+  ],
+});
 
-// Declare a flag
-const checkoutFlag = client.flags.booleanFlag("checkout-v2", { default: false });
+// Or register an ambient context provider that fires per evaluation
+client.flags.setContextProvider(() => [
+  new Context("user", currentUser.email, { plan: currentUser.plan }),
+]);
+const colour = bannerColor.get(); // uses the provider
+```
+
+`flag.get()` is synchronous — `initialize()` (or `waitUntilReady()`) populates the local store; subsequent reads hit cache and never block.
 
-// Start the client (connects and fetches flags)
-await client.flags.initialize();
+#### Listening for changes
+
+```typescript
+client.flags.onChange((event) => console.log(`${event.id} changed`));
+client.flags.onChange("banner-color", (event) => console.log("banner-color updated"));
 
-// Evaluate with context
-const enabled = await checkoutFlag.get({ user: { plan: "enterprise" } });
-console.log("checkout-v2:", enabled);
+// Manual re-fetch
+await client.flags.refresh();
 
-client.close();
+// Cache stats (cacheHits / cacheMisses)
+const stats = client.flags.stats();
 ```
 
 ### Management (CRUD)
 
 ```typescript
-// Create flags
-const boolFlag = client.flags.management.newBooleanFlag("checkout-v2", {
+import { Rule, Op } from "@smplkit/sdk";
+
+const flag = client.manage.flags.newBooleanFlag("checkout-v2", {
   default: false,
   description: "Controls rollout of the new checkout experience.",
 });
 
-// Add targeting rules
-boolFlag.addRule(
-  new Rule("Enable for enterprise users")
-    .environment("production")
-    .when("user.plan", "==", "enterprise")
-    .serve(true)
-    .build(),
+// Targeting rule — `environment` is required on the Rule constructor
+flag.addRule(
+  new Rule("Enable for enterprise users", { environment: "production" })
+    .when("user.plan", Op.EQ, "enterprise")
+    .when("account.region", Op.EQ, "us")
+    .serve(true),
 );
 
-// Configure environments
-boolFlag.setEnvironmentEnabled("production", true);
-boolFlag.setEnvironmentDefault("production", false);
+// Per-environment defaults and kill-switch
+flag.setDefault(false, { environment: "production" });
+flag.disableRules({ environment: "staging" }); // kill switch
+flag.enableRules({ environment: "production" });
 
-await boolFlag.save();
+await flag.save();
 
-// Other factory methods
-const strFlag = client.flags.management.newStringFlag("banner-color", {
+// Other typed factories
+const banner = client.manage.flags.newStringFlag("banner-color", {
   default: "red",
-  values: [{ name: "Red", value: "red" }, { name: "Blue", value: "blue" }],
-});
-const numFlag = client.flags.management.newNumberFlag("max-retries", { default: 3 });
-const jsonFlag = client.flags.management.newJsonFlag("ui-theme", {
-  default: { mode: "light" },
+  values: [
+    { name: "Red", value: "red" },
+    { name: "Blue", value: "blue" },
+  ],
 });
+const retries = client.manage.flags.newNumberFlag("max-retries", { default: 3 });
+const theme = client.manage.flags.newJsonFlag("ui-theme", { default: { mode: "light" } });
+
+// CRUD
+const all = await client.manage.flags.list();
+const fetched = await client.manage.flags.get("checkout-v2");
+await client.manage.flags.delete("checkout-v2");
+```
 
-// List / get / delete
-const flags = await client.flags.management.list();
-const flag = await client.flags.management.get("checkout-v2");
-await client.flags.management.delete("checkout-v2");
+### Contexts
+
+Bulk-register context entities so the platform knows about them (used in the targeting UI, dashboards, etc.):
+
+```typescript
+await client.manage.contexts.register([
+  new Context("user", "alice@acme.com", { plan: "enterprise" }),
+  new Context("account", "1234", { region: "us" }),
+]);
+await client.manage.contexts.flush(); // or pass `{ flush: true }` to register
 ```
 
 ## Logging
 
-### Runtime (live log level management)
+### Runtime — live log level management
+
+`install()` auto-discovers winston and pino loggers, hooks new-logger creation, applies server-managed levels, and subscribes to live updates over the shared WebSocket.
 
 ```typescript
+import { SmplClient, LogLevel } from "@smplkit/sdk";
+
 const client = new SmplClient({ environment: "production", service: "my-service" });
+await client.logging.install();
 
-// Register an adapter for your logging library
-client.logging.registerAdapter(myAdapter);
+client.logging.onChange((event) => {
+  console.log(`${event.id}: ${event.level} (source=${event.source})`);
+});
 
-// Start the logging runtime (connects and fetches log levels)
-await client.logging.start();
+// Force a manual re-sync (e.g. after suspecting drift)
+await client.logging.refresh();
+```
 
-client.logging.onChange((loggers) => {
-  console.log("Log levels updated:", loggers.map((l) => `${l.id}=${l.level}`));
-});
+**Adapter coverage.** Winston named loggers (`winston.loggers.*`) and the default winston logger are auto-discovered at install time. Pino has no global registry, so only loggers created through `pino()` / `logger.child()` after `install()` runs are tracked — pre-existing pino loggers must be recreated or explicitly registered via `client.manage.loggers.register([...])`. There is no console adapter; use a supported framework (winston or pino) to bring loggers under management.
+
+You can also register a custom adapter:
+
+```typescript
+client.logging.registerAdapter(myAdapter); // must implement LoggingAdapter
+await client.logging.install();
 ```
 
 ### Management (CRUD)
 
+Loggers and log groups have separate namespaces:
+
 ```typescript
-// Create a logger
-const logger = client.logging.management.new("sqlalchemy.engine", { managed: true });
-logger.setLevel(LogLevel.WARN);
-logger.setEnvironmentLevel("production", LogLevel.ERROR);
-await logger.save();
-
-// Create a log group
-const group = client.logging.management.newGroup("sql", { name: "SQL Loggers" });
+// Loggers
+const sql = client.manage.loggers.new("sqlalchemy.engine", { managed: true });
+sql.setLevel(LogLevel.WARN);
+sql.setLevel(LogLevel.ERROR, { environment: "production" });
+await sql.save();
+
+const all = await client.manage.loggers.list();
+const fetched = await client.manage.loggers.get("sqlalchemy.engine");
+await client.manage.loggers.delete("sqlalchemy.engine");
+
+// Log groups (a way to bulk-set levels across many loggers)
+const group = client.manage.logGroups.new("sql", { name: "SQL Loggers" });
 group.setLevel(LogLevel.WARN);
 await group.save();
 
-// Assign logger to group
-logger.group = group.id;
-await logger.save();
+await client.manage.logGroups.list();
+await client.manage.logGroups.get("sql");
+await client.manage.logGroups.delete("sql");
+```
+
+## Standalone management client
 
-// List / get / delete
-const loggers = await client.logging.management.list();
-const fetched = await client.logging.management.get("Sqlalchemy.Engine");
-await client.logging.management.delete("Sqlalchemy.Engine");
+For setup scripts, CI tooling, and admin utilities you don't need the runtime plane (no WebSocket, no metrics thread, no logger discovery). Construct `SmplManagementClient` directly:
 
-const groups = await client.logging.management.listGroups();
-const fetchedGroup = await client.logging.management.getGroup(group.id);
-await client.logging.management.deleteGroup(group.id);
+```typescript
+import { SmplManagementClient } from "@smplkit/sdk";
+
+const manage = new SmplManagementClient(); // resolves apiKey from env / ~/.smplkit
+await manage.environments.list();
+await manage.config.new("my-service", { name: "My Service" }).save();
+await manage.close(); // flushes any buffered context/flag/logger registrations
 ```
 
+The runtime `client.manage` and a standalone `SmplManagementClient` expose the same surface: `config`, `flags`, `loggers`, `logGroups`, `contexts`, `contextTypes`, `environments`, `accountSettings`.
+
 ## Error Handling
 
-All SDK errors extend `SmplError`:
+All SDK errors extend `SmplError` (also re-exported as `SmplkitError` for callers that prefer the longer prefix).
 
 ```typescript
 import { SmplError, SmplNotFoundError } from "@smplkit/sdk";
 
 try {
-  const flag = await client.flags.management.get("nonexistent");
+  await client.manage.flags.get("nonexistent");
 } catch (err) {
   if (err instanceof SmplNotFoundError) {
     console.log("Not found:", err.message);
   } else if (err instanceof SmplError) {
     console.log("SDK error:", err.statusCode, err.responseBody);
+    console.log("Structured details:", err.errors);
   }
 }
 ```
 
-| Error                  | Cause                        |
-|------------------------|------------------------------|
-| `SmplNotFoundError`    | HTTP 404 — resource not found |
-| `SmplConflictError`    | HTTP 409 — conflict           |
-| `SmplValidationError`  | HTTP 422 — validation error   |
-| `SmplTimeoutError`     | Request timed out             |
-| `SmplConnectionError`  | Network connectivity issue    |
-| `SmplError`            | Any other SDK error           |
+| Error                 | Cause                              |
+| --------------------- | ---------------------------------- |
+| `SmplNotFoundError`   | HTTP 404 — resource not found      |
+| `SmplConflictError`   | HTTP 409 — conflict                |
+| `SmplValidationError` | HTTP 422 — validation error        |
+| `SmplTimeoutError`    | Request timed out                  |
+| `SmplConnectionError` | Network connectivity issue         |
+| `SmplError`           | Base class for any other SDK error |
 
 ## Debug Logging
 
-Set `SMPLKIT_DEBUG=1` to enable verbose diagnostic output to stderr. This is useful for troubleshooting real-time level changes, WebSocket connectivity, and SDK initialization. Debug output bypasses the managed logging framework and writes directly to stderr.
+Set `SMPLKIT_DEBUG` to enable verbose diagnostic output to stderr — useful when troubleshooting WebSocket connectivity, level resolution, or initialization.
 
 ```bash
 SMPLKIT_DEBUG=1 node my-app.js
 ```
 
-Accepted values: `1`, `true`, `yes` (case-insensitive). Any other value (or unset) disables debug output.
+Accepted values: `1`, `true`, `yes` (case-insensitive). Any other value (or unset) disables debug output. You can also enable it programmatically via `new SmplClient({ debug: true })`.
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smplkit/sdk",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "type": "module",
   "description": "Official TypeScript SDK for the smplkit platform",
   "main": "./dist/index.cjs",