@smplkit/sdk 1.3.39 → 1.3.40

package/README.md

@@ -7,7 +7,7 @@ The official TypeScript SDK for [smplkit](https://www.smplkit.com) — simple ap
 ## Installation
 
 ```bash
-npm install smplkit-sdk
+npm install @smplkit/sdk
 ```
 
 ## Requirements
@@ -17,7 +17,7 @@ npm install smplkit-sdk
 ## Quick Start
 
 ```typescript
-import { SmplClient } from "smplkit-sdk";
+import { SmplClient } from "@smplkit/sdk";
 
 // Option 1: Explicit API key
 const client = new SmplClient({ apiKey: "sk_api_..." });
@@ -32,29 +32,6 @@ const client2 = new SmplClient();
 const client3 = new SmplClient();
 ```
 
-```typescript
-import { SmplClient } from "smplkit-sdk";
-
-const client = new SmplClient({ apiKey: "sk_api_..." });
-
-// Get a config by key
-const config = await client.config.getByKey("user_service");
-
-// List all configs
-const configs = await client.config.list();
-
-// Create a config
-const newConfig = await client.config.create({
-  name: "My Service",
-  key: "my_service",
-  description: "Configuration for my service",
-  values: { timeout: 30, retries: 3 },
-});
-
-// Delete a config
-await client.config.delete(newConfig.id);
-```
-
 ## Configuration
 
 The API key is resolved using the following priority:
@@ -79,15 +56,159 @@ const client = new SmplClient({
 });
 ```
 
+## Config
+
+### Runtime (resolve config 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"));
+});
+```
+
+### Management (CRUD)
+
+```typescript
+// Create a config
+const cfg = client.config.management.new("my-service", {
+  name: "My Service",
+  description: "Configuration for my service",
+});
+await cfg.save();
+
+// List configs
+const configs = await client.config.management.list();
+
+// Get a config by id
+const fetched = await client.config.management.get("my-service");
+
+// Delete a config
+await client.config.management.delete("my-service");
+```
+
+## Flags
+
+### Runtime (evaluate flags)
+
+```typescript
+import { SmplClient, Rule } from "@smplkit/sdk";
+
+const client = new SmplClient({ environment: "production", service: "my-service" });
+
+// Declare a flag
+const checkoutFlag = client.flags.booleanFlag("checkout-v2", { default: false });
+
+// Start the client (connects and fetches flags)
+await client.flags.initialize();
+
+// Evaluate with context
+const enabled = await checkoutFlag.get({ user: { plan: "enterprise" } });
+console.log("checkout-v2:", enabled);
+
+client.close();
+```
+
+### Management (CRUD)
+
+```typescript
+// Create flags
+const boolFlag = client.flags.management.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(),
+);
+
+// Configure environments
+boolFlag.setEnvironmentEnabled("production", true);
+boolFlag.setEnvironmentDefault("production", false);
+
+await boolFlag.save();
+
+// Other factory methods
+const strFlag = client.flags.management.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" },
+});
+
+// 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");
+```
+
+## Logging
+
+### Runtime (live log level management)
+
+```typescript
+const client = new SmplClient({ environment: "production", service: "my-service" });
+
+// Register an adapter for your logging library
+client.logging.registerAdapter(myAdapter);
+
+// Start the logging runtime (connects and fetches log levels)
+await client.logging.start();
+
+client.logging.onChange((loggers) => {
+  console.log("Log levels updated:", loggers.map((l) => `${l.id}=${l.level}`));
+});
+```
+
+### Management (CRUD)
+
+```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" });
+group.setLevel(LogLevel.WARN);
+await group.save();
+
+// Assign logger to group
+logger.group = group.id;
+await logger.save();
+
+// 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");
+
+const groups = await client.logging.management.listGroups();
+const fetchedGroup = await client.logging.management.getGroup(group.id);
+await client.logging.management.deleteGroup(group.id);
+```
+
 ## Error Handling
 
 All SDK errors extend `SmplError`:
 
 ```typescript
-import { SmplError, SmplNotFoundError } from "smplkit-sdk";
+import { SmplError, SmplNotFoundError } from "@smplkit/sdk";
 
 try {
-  const config = await client.config.getByKey("nonexistent");
+  const flag = await client.flags.management.get("nonexistent");
 } catch (err) {
   if (err instanceof SmplNotFoundError) {
     console.log("Not found:", err.message);

package/dist/index.cjs

@@ -16624,17 +16624,20 @@ __export(index_exports, {
   BooleanFlag: () => BooleanFlag,
   Config: () => Config,
   ConfigClient: () => ConfigClient,
+  ConfigManagement: () => ConfigManagement,
   Context: () => Context,
   Flag: () => Flag,
   FlagChangeEvent: () => FlagChangeEvent,
   FlagStats: () => FlagStats,
   FlagsClient: () => FlagsClient,
+  FlagsManagement: () => FlagsManagement,
   JsonFlag: () => JsonFlag,
   LiveConfigProxy: () => LiveConfigProxy,
   LogGroup: () => LogGroup,
   LogLevel: () => LogLevel,
   Logger: () => Logger,
   LoggingClient: () => LoggingClient,
+  LoggingManagement: () => LoggingManagement,
   NumberFlag: () => NumberFlag,
   PinoAdapter: () => PinoAdapter,
   Rule: () => Rule,
@@ -17043,6 +17046,27 @@ function buildRequestBody(options) {
     }
   };
 }
+var ConfigManagement = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** Create an unsaved config. Call `.save()` to persist. */
+  new(id, options) {
+    return this._client._mgNew(id, options);
+  }
+  /** Fetch a config by id. */
+  async get(id) {
+    return this._client._getById(id);
+  }
+  /** List all configs. */
+  async list() {
+    return this._client._mgList();
+  }
+  /** Delete a config by id. */
+  async delete(id) {
+    return this._client._mgDelete(id);
+  }
+};
 var ConfigClient = class {
   /** @internal */
   _apiKey;
@@ -17054,6 +17078,8 @@ var ConfigClient = class {
   _getSharedWs;
   /** @internal — set by SmplClient after construction. */
   _parent = null;
+  /** Management API — CRUD operations on Config models. */
+  management;
   _configCache = {};
   _initialized = false;
   _listeners = [];
@@ -17082,12 +17108,13 @@ var ConfigClient = class {
         }
       }
     });
+    this.management = new ConfigManagement(this);
   }
   // ------------------------------------------------------------------
-  // Management: factory method
+  // Management: internal implementations (delegated from ConfigManagement)
   // ------------------------------------------------------------------
-  /** Create an unsaved config. Call `.save()` to persist. */
-  new(id, options) {
+  /** @internal */
+  _mgNew(id, options) {
     return new Config(this, {
       id,
       name: options?.name ?? keyToDisplayName(id),
@@ -17099,15 +17126,8 @@ var ConfigClient = class {
       updatedAt: null
     });
   }
-  // ------------------------------------------------------------------
-  // Management: CRUD
-  // ------------------------------------------------------------------
-  /** Fetch a config by id. */
-  async get(id) {
-    return this._getById(id);
-  }
-  /** List all configs. */
-  async list() {
+  /** @internal */
+  async _mgList() {
     let data;
     try {
       const result = await this._http.GET("/api/v1/configs", {});
@@ -17119,8 +17139,8 @@ var ConfigClient = class {
     if (!data) return [];
     return data.data.map((r) => resourceToConfig(r, this));
   }
-  /** Delete a config by id. */
-  async delete(id) {
+  /** @internal */
+  async _mgDelete(id) {
     try {
       const result = await this._http.DELETE("/api/v1/configs/{id}", {
         params: { path: { id } }
@@ -17200,12 +17220,12 @@ var ConfigClient = class {
   // Runtime: resolve and subscribe
   // ------------------------------------------------------------------
   /**
-   * Resolve a config's values for the current environment.
+   * Get a config's resolved values for the current environment.
    *
    * Returns the resolved key-value pairs for the given config.
    * Optionally pass a model class to map the resolved values.
    */
-  async resolve(id, model) {
+  async get(id, model) {
     await this._ensureInitialized();
     const values = this._configCache[id];
     if (values === void 0) {
@@ -17273,13 +17293,13 @@ var ConfigClient = class {
    */
   async refresh() {
     if (!this._initialized) {
-      throw new SmplError("Config not initialized. Call resolve() or subscribe() first.");
+      throw new SmplError("Config not initialized. Call get() or subscribe() first.");
     }
     const environment = this._parent?._environment;
     if (!environment) {
       throw new SmplError("No environment set.");
     }
-    const configs = await this.list();
+    const configs = await this.management.list();
     const newCache = {};
     for (const cfg of configs) {
       const chain = await cfg._buildChain(configs);
@@ -17299,7 +17319,7 @@ var ConfigClient = class {
     if (!environment) {
       throw new SmplError("No environment set. Ensure SmplClient is configured.");
     }
-    const configs = await this.list();
+    const configs = await this.management.list();
     const cache = {};
     for (const cfg of configs) {
       const chain = await cfg._buildChain(configs);
@@ -17315,7 +17335,7 @@ var ConfigClient = class {
   /** @internal — called by SmplClient for backward compat. */
   async _connectInternal(environment) {
     if (this._initialized) return;
-    const configs = await this.list();
+    const configs = await this.management.list();
     const cache = {};
     for (const cfg of configs) {
       const chain = await cfg._buildChain(configs);
@@ -17694,6 +17714,39 @@ var ContextRegistrationBuffer = class {
     return this._pending.length;
   }
 };
+var FlagsManagement = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** Create an unsaved boolean flag. Call `.save()` to persist. */
+  newBooleanFlag(id, options) {
+    return this._client._mgNewBooleanFlag(id, options);
+  }
+  /** Create an unsaved string flag. Call `.save()` to persist. */
+  newStringFlag(id, options) {
+    return this._client._mgNewStringFlag(id, options);
+  }
+  /** Create an unsaved number flag. Call `.save()` to persist. */
+  newNumberFlag(id, options) {
+    return this._client._mgNewNumberFlag(id, options);
+  }
+  /** Create an unsaved JSON flag. Call `.save()` to persist. */
+  newJsonFlag(id, options) {
+    return this._client._mgNewJsonFlag(id, options);
+  }
+  /** Fetch a flag by id. */
+  async get(id) {
+    return this._client._mgGet(id);
+  }
+  /** List all flags. */
+  async list() {
+    return this._client._mgList();
+  }
+  /** Delete a flag by id. */
+  async delete(id) {
+    return this._client._mgDelete(id);
+  }
+};
 var FlagsClient = class {
   /** @internal */
   _apiKey;
@@ -17718,6 +17771,8 @@ var FlagsClient = class {
   _ensureWs;
   /** @internal — set by SmplClient after construction. */
   _parent = null;
+  /** Management API — CRUD operations on Flag models. */
+  management;
   /** @internal */
   constructor(apiKey, ensureWs, timeout) {
     this._apiKey = apiKey;
@@ -17753,12 +17808,13 @@ var FlagsClient = class {
       },
       fetch: fetchWithTimeout
     });
+    this.management = new FlagsManagement(this);
   }
   // ------------------------------------------------------------------
-  // Management: factory methods (return unsaved flags)
+  // Management: internal implementations (delegated from FlagsManagement)
   // ------------------------------------------------------------------
-  /** Create an unsaved boolean flag. Call `.save()` to persist. */
-  newBooleanFlag(id, options) {
+  /** @internal */
+  _mgNewBooleanFlag(id, options) {
     return new BooleanFlag(this, {
       id,
       name: options.name ?? keyToDisplayName(id),
@@ -17774,8 +17830,8 @@ var FlagsClient = class {
       updatedAt: null
     });
   }
-  /** Create an unsaved string flag. Call `.save()` to persist. */
-  newStringFlag(id, options) {
+  /** @internal */
+  _mgNewStringFlag(id, options) {
     return new StringFlag(this, {
       id,
       name: options.name ?? keyToDisplayName(id),
@@ -17788,8 +17844,8 @@ var FlagsClient = class {
       updatedAt: null
     });
   }
-  /** Create an unsaved number flag. Call `.save()` to persist. */
-  newNumberFlag(id, options) {
+  /** @internal */
+  _mgNewNumberFlag(id, options) {
     return new NumberFlag(this, {
       id,
       name: options.name ?? keyToDisplayName(id),
@@ -17802,8 +17858,8 @@ var FlagsClient = class {
       updatedAt: null
     });
   }
-  /** Create an unsaved JSON flag. Call `.save()` to persist. */
-  newJsonFlag(id, options) {
+  /** @internal */
+  _mgNewJsonFlag(id, options) {
     return new JsonFlag(this, {
       id,
       name: options.name ?? keyToDisplayName(id),
@@ -17816,11 +17872,8 @@ var FlagsClient = class {
       updatedAt: null
     });
   }
-  // ------------------------------------------------------------------
-  // Management: CRUD
-  // ------------------------------------------------------------------
-  /** Fetch a flag by id. */
-  async get(id) {
+  /** @internal */
+  async _mgGet(id) {
     let data;
     try {
       const result = await this._http.GET("/api/v1/flags/{id}", {
@@ -17837,8 +17890,8 @@ var FlagsClient = class {
     }
     return this._resourceToModel(data.data);
   }
-  /** List all flags. */
-  async list() {
+  /** @internal */
+  async _mgList() {
     let data;
     try {
       const result = await this._http.GET("/api/v1/flags", {});
@@ -17850,8 +17903,8 @@ var FlagsClient = class {
     if (!data) return [];
     return data.data.map((r) => this._resourceToModel(r));
   }
-  /** Delete a flag by id. */
-  async delete(id) {
+  /** @internal */
+  async _mgDelete(id) {
     try {
       const result = await this._http.DELETE("/api/v1/flags/{id}", {
         params: { path: { id } }
@@ -18498,6 +18551,43 @@ function wrapFetchError3(err) {
     `Request failed: ${err instanceof Error ? err.message : String(err)}`
   );
 }
+var LoggingManagement = class {
+  constructor(_client) {
+    this._client = _client;
+  }
+  /** Create an unsaved logger. Call `.save()` to persist. */
+  new(id, options) {
+    return this._client._mgNew(id, options);
+  }
+  /** Fetch a logger by id. */
+  async get(id) {
+    return this._client._mgGet(id);
+  }
+  /** List all loggers. */
+  async list() {
+    return this._client._mgList();
+  }
+  /** Delete a logger by id. */
+  async delete(id) {
+    return this._client._mgDelete(id);
+  }
+  /** Create an unsaved log group. Call `.save()` to persist. */
+  newGroup(id, options) {
+    return this._client._mgNewGroup(id, options);
+  }
+  /** Fetch a log group by id. */
+  async getGroup(id) {
+    return this._client._mgGetGroup(id);
+  }
+  /** List all log groups. */
+  async listGroups() {
+    return this._client._mgListGroups();
+  }
+  /** Delete a log group by id. */
+  async deleteGroup(id) {
+    return this._client._mgDeleteGroup(id);
+  }
+};
 var LoggingClient = class {
   /** @internal */
   _apiKey;
@@ -18507,6 +18597,8 @@ var LoggingClient = class {
   _http;
   /** @internal — set by SmplClient after construction. */
   _parent = null;
+  /** Management API — CRUD operations on Logger and LogGroup models. */
+  management;
   _ensureWs;
   _wsManager = null;
   _started = false;
@@ -18540,6 +18632,7 @@ var LoggingClient = class {
         }
       }
     });
+    this.management = new LoggingManagement(this);
   }
   // ------------------------------------------------------------------
   // Adapter registration
@@ -18558,10 +18651,10 @@ var LoggingClient = class {
     this._adapters.push(adapter);
   }
   // ------------------------------------------------------------------
-  // Management: Logger factory
+  // Management: internal implementations (delegated from LoggingManagement)
   // ------------------------------------------------------------------
-  /** Create an unsaved logger. Call `.save()` to persist. */
-  new(id, options) {
+  /** @internal */
+  _mgNew(id, options) {
     return new Logger(this, {
       id,
       name: options?.name ?? keyToDisplayName(id),
@@ -18574,11 +18667,8 @@ var LoggingClient = class {
       updatedAt: null
     });
   }
-  // ------------------------------------------------------------------
-  // Management: Logger CRUD
-  // ------------------------------------------------------------------
-  /** Fetch a logger by id. */
-  async get(id) {
+  /** @internal */
+  async _mgGet(id) {
     let data;
     try {
       const result = await this._http.GET("/api/v1/loggers/{id}", {
@@ -18595,8 +18685,8 @@ var LoggingClient = class {
     }
     return this._loggerToModel(data.data);
   }
-  /** List all loggers. */
-  async list() {
+  /** @internal */
+  async _mgList() {
     let data;
     try {
       const result = await this._http.GET("/api/v1/loggers", {});
@@ -18608,8 +18698,8 @@ var LoggingClient = class {
     if (!data) return [];
     return data.data.map((r) => this._loggerToModel(r));
   }
-  /** Delete a logger by id. */
-  async delete(id) {
+  /** @internal */
+  async _mgDelete(id) {
     try {
       const result = await this._http.DELETE("/api/v1/loggers/{id}", {
         params: { path: { id } }
@@ -18620,11 +18710,8 @@ var LoggingClient = class {
       wrapFetchError3(err);
     }
   }
-  // ------------------------------------------------------------------
-  // Management: LogGroup factory
-  // ------------------------------------------------------------------
-  /** Create an unsaved log group. Call `.save()` to persist. */
-  newGroup(id, options) {
+  /** @internal */
+  _mgNewGroup(id, options) {
     return new LogGroup(this, {
       id,
       name: options?.name ?? keyToDisplayName(id),
@@ -18635,20 +18722,17 @@ var LoggingClient = class {
       updatedAt: null
     });
   }
-  // ------------------------------------------------------------------
-  // Management: LogGroup CRUD
-  // ------------------------------------------------------------------
-  /** Fetch a log group by id. */
-  async getGroup(id) {
-    const groups = await this.listGroups();
+  /** @internal */
+  async _mgGetGroup(id) {
+    const groups = await this.management.listGroups();
     const match = groups.find((g) => g.id === id);
     if (!match) {
       throw new SmplNotFoundError(`LogGroup with id '${id}' not found`);
     }
     return match;
   }
-  /** List all log groups. */
-  async listGroups() {
+  /** @internal */
+  async _mgListGroups() {
     let data;
     try {
       const result = await this._http.GET("/api/v1/log_groups", {});
@@ -18661,9 +18745,9 @@ var LoggingClient = class {
     if (!data) return [];
     return data.data.map((r) => this._groupToModel(r));
   }
-  /** Delete a log group by id. */
-  async deleteGroup(id) {
-    const group = await this.getGroup(id);
+  /** @internal */
+  async _mgDeleteGroup(id) {
+    const group = await this.management.getGroup(id);
     try {
       const result = await this._http.DELETE("/api/v1/log_groups/{id}", {
         params: { path: { id: group.id } }
@@ -18805,14 +18889,20 @@ var LoggingClient = class {
     }
     for (const { name, level } of discovered) {
       try {
-        const logger = this.new(name, { managed: true });
+        const logger = this.management.new(name, { managed: true });
         logger.setLevel(level);
         await logger.save();
-      } catch {
+      } catch (err) {
+        console.warn(
+          `[smplkit] Failed to register logger "${name}": ${err instanceof Error ? err.message : String(err)}`
+        );
       }
     }
     try {
-      const [serverLoggers] = await Promise.all([this.list(), this.listGroups()]);
+      const [serverLoggers] = await Promise.all([
+        this.management.list(),
+        this.management.listGroups()
+      ]);
       this._applyLevels(serverLoggers);
     } catch {
     }
@@ -18911,7 +19001,7 @@ var LoggingClient = class {
   }
   /** Called by adapter hooks when a new logger is created in the framework. */
   _onAdapterNewLogger(_name, _level) {
-    const logger = this.new(_name, { managed: true });
+    const logger = this.management.new(_name, { managed: true });
     logger.setLevel(_level);
     logger.save().catch(() => {
     });
@@ -19728,17 +19818,20 @@ var PinoAdapter = class {
   BooleanFlag,
   Config,
   ConfigClient,
+  ConfigManagement,
   Context,
   Flag,
   FlagChangeEvent,
   FlagStats,
   FlagsClient,
+  FlagsManagement,
   JsonFlag,
   LiveConfigProxy,
   LogGroup,
   LogLevel,
   Logger,
   LoggingClient,
+  LoggingManagement,
   NumberFlag,
   PinoAdapter,
   Rule,