@smplkit/sdk 1.0.1 → 1.1.1

package/dist/index.js

@@ -1,3 +1,10 @@
+import {
+  ConfigRuntime
+} from "./chunk-PZD5PSQY.js";
+
+// src/config/client.ts
+import createClient from "openapi-fetch";
+
 // src/errors.ts
 var SmplError = class extends Error {
   /** The HTTP status code, if the error originated from an HTTP response. */
@@ -48,276 +55,439 @@ var SmplValidationError = class extends SmplError {
   }
 };
 
-// src/config/client.ts
-var CONFIGS_PATH = "/api/v1/configs";
-var ConfigClient = class {
-  /** @internal */
-  transport;
+// src/config/types.ts
+var Config = class {
+  /** UUID of the config. */
+  id;
+  /** Human-readable key (e.g. `"user_service"`). */
+  key;
+  /** Display name. */
+  name;
+  /** Optional description. */
+  description;
+  /** Parent config UUID, or null if this is a root config. */
+  parent;
+  /** Base key-value pairs. */
+  values;
+  /**
+   * Per-environment overrides.
+   * Stored as `{ env_name: { values: { key: value } } }` to match the
+   * server's format.
+   */
+  environments;
+  /** When the config was created, or null if unavailable. */
+  createdAt;
+  /** When the config was last updated, or null if unavailable. */
+  updatedAt;
+  /**
+   * Internal reference to the parent client.
+   * @internal
+   */
+  _client;
   /** @internal */
-  constructor(transport) {
-    this.transport = transport;
+  constructor(client, fields) {
+    this._client = client;
+    this.id = fields.id;
+    this.key = fields.key;
+    this.name = fields.name;
+    this.description = fields.description;
+    this.parent = fields.parent;
+    this.values = fields.values;
+    this.environments = fields.environments;
+    this.createdAt = fields.createdAt;
+    this.updatedAt = fields.updatedAt;
   }
   /**
-   * Fetch a single config by key or UUID.
+   * Update this config's attributes on the server.
    *
-   * Exactly one of `key` or `id` must be provided.
+   * Builds the request from current attribute values, overriding with any
+   * provided options. Updates local attributes in place on success.
    *
-   * @param options - Lookup options.
-   * @returns The matching config.
-   * @throws {SmplNotFoundError} If no matching config exists.
-   * @throws {Error} If neither or both of `key` and `id` are provided.
+   * @param options.name - New display name.
+   * @param options.description - New description (pass empty string to clear).
+   * @param options.values - New base values (replaces entirely).
+   * @param options.environments - New environments dict (replaces entirely).
    */
-  async get(options) {
-    const { key, id } = options;
-    if (key === void 0 === (id === void 0)) {
-      throw new Error("Exactly one of 'key' or 'id' must be provided.");
-    }
-    if (id !== void 0) {
-      return this.getById(id);
-    }
-    return this.getByKey(key);
+  async update(options) {
+    const updated = await this._client._updateConfig({
+      configId: this.id,
+      name: options.name ?? this.name,
+      key: this.key,
+      description: options.description !== void 0 ? options.description : this.description,
+      parent: this.parent,
+      values: options.values ?? this.values,
+      environments: options.environments ?? this.environments
+    });
+    this.name = updated.name;
+    this.description = updated.description;
+    this.values = updated.values;
+    this.environments = updated.environments;
+    this.updatedAt = updated.updatedAt;
   }
   /**
-   * List all configs for the account.
+   * Replace base or environment-specific values.
+   *
+   * When `environment` is provided, replaces that environment's `values`
+   * sub-dict (other environments are preserved). When omitted, replaces
+   * the base `values`.
    *
-   * @returns An array of config objects.
+   * @param values - The complete set of values to set.
+   * @param environment - Target environment, or omit for base values.
    */
-  async list() {
-    const response = await this.transport.get(CONFIGS_PATH);
-    const resources = response.data;
-    return resources.map((r) => this.resourceToModel(r));
+  async setValues(values, environment) {
+    let newValues;
+    let newEnvs;
+    if (environment === void 0) {
+      newValues = values;
+      newEnvs = this.environments;
+    } else {
+      newValues = this.values;
+      const existingEntry = typeof this.environments[environment] === "object" && this.environments[environment] !== null ? { ...this.environments[environment] } : {};
+      existingEntry.values = values;
+      newEnvs = { ...this.environments, [environment]: existingEntry };
+    }
+    const updated = await this._client._updateConfig({
+      configId: this.id,
+      name: this.name,
+      key: this.key,
+      description: this.description,
+      parent: this.parent,
+      values: newValues,
+      environments: newEnvs
+    });
+    this.values = updated.values;
+    this.environments = updated.environments;
+    this.updatedAt = updated.updatedAt;
   }
   /**
-   * Create a new config.
+   * Set a single key within base or environment-specific values.
    *
-   * @param options - Config creation options.
-   * @returns The created config.
-   * @throws {SmplValidationError} If the server rejects the request.
+   * Merges the key into existing values rather than replacing all values.
+   *
+   * @param key - The config key to set.
+   * @param value - The value to assign.
+   * @param environment - Target environment, or omit for base values.
    */
-  async create(options) {
-    const body = this.buildRequestBody(options);
-    const response = await this.transport.post(CONFIGS_PATH, body);
-    if (!response.data) {
-      throw new SmplValidationError("Failed to create config");
+  async setValue(key, value, environment) {
+    if (environment === void 0) {
+      const merged = { ...this.values, [key]: value };
+      await this.setValues(merged);
+    } else {
+      const envEntry = typeof this.environments[environment] === "object" && this.environments[environment] !== null ? this.environments[environment] : {};
+      const existing = {
+        ...typeof envEntry.values === "object" && envEntry.values !== null ? envEntry.values : {}
+      };
+      existing[key] = value;
+      await this.setValues(existing, environment);
     }
-    return this.resourceToModel(response.data);
   }
   /**
-   * Delete a config by UUID.
+   * Connect to this config for runtime value resolution.
    *
-   * @param configId - The UUID of the config to delete.
-   * @throws {SmplNotFoundError} If the config does not exist.
-   * @throws {SmplConflictError} If the config has children.
+   * Eagerly fetches this config and its full parent chain, resolves values
+   * for the given environment via deep merge, and returns a
+   * {@link ConfigRuntime} with a fully populated local cache.
+   *
+   * A background WebSocket connection is started for real-time updates.
+   * If the WebSocket fails to connect, the runtime operates in cache-only
+   * mode and reconnects automatically.
+   *
+   * Supports both `await` and `await using` (TypeScript 5.2+)::
+   *
+   * ```typescript
+   * // Simple await
+   * const runtime = await config.connect("production");
+   * try { ... } finally { await runtime.close(); }
+   *
+   * // await using (auto-close)
+   * await using runtime = await config.connect("production");
+   * ```
+   *
+   * @param environment - The environment to resolve for (e.g. `"production"`).
+   * @param options.timeout - Milliseconds to wait for the initial fetch.
    */
-  async delete(configId) {
-    await this.transport.delete(`${CONFIGS_PATH}/${configId}`);
-  }
-  /** Fetch a config by UUID. */
-  async getById(configId) {
-    const response = await this.transport.get(`${CONFIGS_PATH}/${configId}`);
-    if (!response.data) {
-      throw new SmplNotFoundError(`Config ${configId} not found`);
-    }
-    return this.resourceToModel(response.data);
-  }
-  /** Fetch a config by key using the list endpoint with a filter. */
-  async getByKey(key) {
-    const response = await this.transport.get(CONFIGS_PATH, { "filter[key]": key });
-    const resources = response.data;
-    if (!resources || resources.length === 0) {
-      throw new SmplNotFoundError(`Config with key '${key}' not found`);
-    }
-    return this.resourceToModel(resources[0]);
+  async connect(environment, options) {
+    const { ConfigRuntime: ConfigRuntime2 } = await import("./runtime-CCRTBKED.js");
+    const timeout = options?.timeout ?? 3e4;
+    const chain = await this._buildChain(timeout);
+    return new ConfigRuntime2({
+      configKey: this.key,
+      configId: this.id,
+      environment,
+      chain,
+      apiKey: this._client._apiKey,
+      baseUrl: this._client._baseUrl,
+      fetchChain: () => this._buildChain(timeout)
+    });
   }
   /**
-   * Convert a JSON:API resource to a Config domain model.
+   * Walk the parent chain and return config data objects, child-to-root.
    * @internal
    */
-  resourceToModel(resource) {
-    const attrs = resource.attributes;
-    return {
-      id: resource.id,
-      key: attrs.key ?? "",
-      name: attrs.name,
-      description: attrs.description ?? null,
-      parent: attrs.parent ?? null,
-      values: attrs.values ?? {},
-      environments: attrs.environments ?? {},
-      createdAt: attrs.created_at ? new Date(attrs.created_at) : null,
-      updatedAt: attrs.updated_at ? new Date(attrs.updated_at) : null
-    };
+  async _buildChain(_timeout) {
+    const chain = [{ id: this.id, values: this.values, environments: this.environments }];
+    let parentId = this.parent;
+    while (parentId !== null) {
+      const parentConfig = await this._client.get({ id: parentId });
+      chain.push({
+        id: parentConfig.id,
+        values: parentConfig.values,
+        environments: parentConfig.environments
+      });
+      parentId = parentConfig.parent;
+    }
+    return chain;
   }
-  /** Build a JSON:API request body for create operations. */
-  buildRequestBody(options) {
-    const attributes = {
-      name: options.name
-    };
-    if (options.key !== void 0) attributes.key = options.key;
-    if (options.description !== void 0) attributes.description = options.description;
-    if (options.parent !== void 0) attributes.parent = options.parent;
-    if (options.values !== void 0) attributes.values = options.values;
-    return {
-      data: {
-        type: "config",
-        attributes
-      }
-    };
+  toString() {
+    return `Config(id=${this.id}, key=${this.key}, name=${this.name})`;
   }
 };
 
-// src/auth.ts
-function buildAuthHeader(apiKey) {
-  return `Bearer ${apiKey}`;
+// src/config/client.ts
+var BASE_URL = "https://config.smplkit.com";
+function resourceToConfig(resource, client) {
+  const attrs = resource.attributes;
+  return new Config(client, {
+    id: resource.id ?? "",
+    key: attrs.key ?? "",
+    name: attrs.name,
+    description: attrs.description ?? null,
+    parent: attrs.parent ?? null,
+    values: attrs.values ?? {},
+    environments: attrs.environments ?? {},
+    createdAt: attrs.created_at ? new Date(attrs.created_at) : null,
+    updatedAt: attrs.updated_at ? new Date(attrs.updated_at) : null
+  });
 }
-
-// src/transport.ts
-var SDK_VERSION = "0.0.0";
-var DEFAULT_TIMEOUT_MS = 3e4;
-var Transport = class {
-  apiKey;
-  baseUrl;
-  timeout;
-  constructor(options) {
-    this.apiKey = options.apiKey;
-    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
-    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+async function checkError(response, context) {
+  const body = await response.text().catch(() => "");
+  switch (response.status) {
+    case 404:
+      throw new SmplNotFoundError(body || context, 404, body);
+    case 409:
+      throw new SmplConflictError(body || context, 409, body);
+    case 422:
+      throw new SmplValidationError(body || context, 422, body);
+    default:
+      throw new SmplError(`HTTP ${response.status}: ${body}`, response.status, body);
+  }
+}
+function wrapFetchError(err) {
+  if (err instanceof SmplNotFoundError || err instanceof SmplConflictError || err instanceof SmplValidationError || err instanceof SmplError) {
+    throw err;
+  }
+  if (err instanceof TypeError) {
+    throw new SmplConnectionError(`Network error: ${err.message}`);
+  }
+  throw new SmplConnectionError(
+    `Request failed: ${err instanceof Error ? err.message : String(err)}`
+  );
+}
+function buildRequestBody(options) {
+  const attrs = {
+    name: options.name
+  };
+  if (options.key !== void 0) attrs.key = options.key;
+  if (options.description !== void 0) attrs.description = options.description;
+  if (options.parent !== void 0) attrs.parent = options.parent;
+  if (options.values !== void 0)
+    attrs.values = options.values;
+  if (options.environments !== void 0)
+    attrs.environments = options.environments;
+  return {
+    data: {
+      id: options.id ?? null,
+      type: "config",
+      attributes: attrs
+    }
+  };
+}
+var ConfigClient = class {
+  /** @internal — used by Config instances for reconnecting and WebSocket auth. */
+  _apiKey;
+  /** @internal */
+  _baseUrl = BASE_URL;
+  /** @internal */
+  _http;
+  /** @internal */
+  constructor(apiKey, timeout) {
+    this._apiKey = apiKey;
+    const ms = timeout ?? 3e4;
+    this._http = createClient({
+      baseUrl: BASE_URL,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: "application/json"
+      },
+      // openapi-fetch custom fetch receives a pre-built Request object
+      fetch: async (request) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), ms);
+        try {
+          return await fetch(new Request(request, { signal: controller.signal }));
+        } catch (err) {
+          if (err instanceof DOMException && err.name === "AbortError") {
+            throw new SmplTimeoutError(`Request timed out after ${ms}ms`);
+          }
+          throw err;
+        } finally {
+          clearTimeout(timer);
+        }
+      }
+    });
   }
   /**
-   * Send a GET request.
+   * Fetch a single config by key or UUID.
+   *
+   * Exactly one of `key` or `id` must be provided.
    *
-   * @param path - URL path relative to `baseUrl` (e.g. `/api/v1/configs`).
-   * @param params - Optional query parameters.
-   * @returns Parsed JSON response body.
+   * @throws {SmplNotFoundError} If no matching config exists.
    */
-  async get(path, params) {
-    return this.request("GET", path, void 0, params);
+  async get(options) {
+    const { key, id } = options;
+    if (key === void 0 === (id === void 0)) {
+      throw new Error("Exactly one of 'key' or 'id' must be provided.");
+    }
+    return id !== void 0 ? this._getById(id) : this._getByKey(key);
   }
   /**
-   * Send a POST request with a JSON body.
-   *
-   * @param path - URL path relative to `baseUrl`.
-   * @param body - JSON-serializable request body.
-   * @returns Parsed JSON response body.
+   * List all configs for the account.
    */
-  async post(path, body) {
-    return this.request("POST", path, body);
+  async list() {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/configs", {});
+      if (result.error !== void 0) await checkError(result.response, "Failed to list configs");
+      data = result.data;
+    } catch (err) {
+      wrapFetchError(err);
+    }
+    if (!data) return [];
+    return data.data.map((r) => resourceToConfig(r, this));
   }
   /**
-   * Send a PUT request with a JSON body.
+   * Create a new config.
    *
-   * @param path - URL path relative to `baseUrl`.
-   * @param body - JSON-serializable request body.
-   * @returns Parsed JSON response body.
+   * @throws {SmplValidationError} If the server rejects the request.
    */
-  async put(path, body) {
-    return this.request("PUT", path, body);
+  async create(options) {
+    const body = buildRequestBody({
+      name: options.name,
+      key: options.key,
+      description: options.description,
+      parent: options.parent,
+      values: options.values
+    });
+    let data;
+    try {
+      const result = await this._http.POST("/api/v1/configs", { body });
+      if (result.error !== void 0) await checkError(result.response, "Failed to create config");
+      data = result.data;
+    } catch (err) {
+      wrapFetchError(err);
+    }
+    if (!data || !data.data) throw new SmplValidationError("Failed to create config");
+    return resourceToConfig(data.data, this);
   }
   /**
-   * Send a DELETE request.
+   * Delete a config by UUID.
    *
-   * @param path - URL path relative to `baseUrl`.
-   * @returns Parsed JSON response body (empty object for 204 responses).
+   * @throws {SmplNotFoundError} If the config does not exist.
+   * @throws {SmplConflictError} If the config has child configs.
    */
-  async delete(path) {
-    return this.request("DELETE", path);
+  async delete(configId) {
+    try {
+      const result = await this._http.DELETE("/api/v1/configs/{id}", {
+        params: { path: { id: configId } }
+      });
+      if (result.error !== void 0 && result.response.status !== 204)
+        await checkError(result.response, `Failed to delete config ${configId}`);
+    } catch (err) {
+      wrapFetchError(err);
+    }
   }
   /**
-   * Core request method. Handles headers, timeouts, and error mapping.
+   * Internal: PUT a full config update and return the updated model.
+   *
+   * Called by {@link Config} instance methods.
+   * @internal
    */
-  async request(method, path, body, params) {
-    let url = `${this.baseUrl}${path}`;
-    if (params) {
-      const searchParams = new URLSearchParams(params);
-      url += `?${searchParams.toString()}`;
-    }
-    const headers = {
-      Authorization: buildAuthHeader(this.apiKey),
-      "User-Agent": `smplkit-typescript-sdk/${SDK_VERSION}`,
-      Accept: "application/vnd.api+json"
-    };
-    if (body !== void 0) {
-      headers["Content-Type"] = "application/vnd.api+json";
-    }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    let response;
+  async _updateConfig(payload) {
+    const body = buildRequestBody({
+      id: payload.configId,
+      name: payload.name,
+      key: payload.key,
+      description: payload.description,
+      parent: payload.parent,
+      values: payload.values,
+      environments: payload.environments
+    });
+    let data;
     try {
-      response = await fetch(url, {
-        method,
-        headers,
-        body: body !== void 0 ? JSON.stringify(body) : void 0,
-        signal: controller.signal
+      const result = await this._http.PUT("/api/v1/configs/{id}", {
+        params: { path: { id: payload.configId } },
+        body
       });
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof DOMException && error.name === "AbortError") {
-        throw new SmplTimeoutError(`Request timed out after ${this.timeout}ms`);
-      }
-      if (error instanceof TypeError) {
-        throw new SmplConnectionError(`Network error: ${error.message}`);
-      }
-      throw new SmplConnectionError(
-        `Request failed: ${error instanceof Error ? error.message : String(error)}`
-      );
-    } finally {
-      clearTimeout(timeoutId);
-    }
-    if (response.status === 204) {
-      return {};
-    }
-    const responseText = await response.text();
-    if (!response.ok) {
-      this.throwForStatus(response.status, responseText);
+      if (result.error !== void 0)
+        await checkError(result.response, `Failed to update config ${payload.configId}`);
+      data = result.data;
+    } catch (err) {
+      wrapFetchError(err);
     }
+    if (!data || !data.data)
+      throw new SmplValidationError(`Failed to update config ${payload.configId}`);
+    return resourceToConfig(data.data, this);
+  }
+  // ---- Private helpers ----
+  async _getById(configId) {
+    let data;
     try {
-      return JSON.parse(responseText);
-    } catch {
-      throw new SmplError(`Invalid JSON response: ${responseText}`, response.status, responseText);
+      const result = await this._http.GET("/api/v1/configs/{id}", {
+        params: { path: { id: configId } }
+      });
+      if (result.error !== void 0)
+        await checkError(result.response, `Config ${configId} not found`);
+      data = result.data;
+    } catch (err) {
+      wrapFetchError(err);
     }
+    if (!data || !data.data) throw new SmplNotFoundError(`Config ${configId} not found`);
+    return resourceToConfig(data.data, this);
   }
-  /**
-   * Map HTTP error status codes to typed SDK exceptions.
-   *
-   * @throws {SmplNotFoundError} On 404.
-   * @throws {SmplConflictError} On 409.
-   * @throws {SmplValidationError} On 422.
-   * @throws {SmplError} On any other non-2xx status.
-   */
-  throwForStatus(status, body) {
-    switch (status) {
-      case 404:
-        throw new SmplNotFoundError(body, 404, body);
-      case 409:
-        throw new SmplConflictError(body, 409, body);
-      case 422:
-        throw new SmplValidationError(body, 422, body);
-      default:
-        throw new SmplError(`HTTP ${status}: ${body}`, status, body);
+  async _getByKey(key) {
+    let data;
+    try {
+      const result = await this._http.GET("/api/v1/configs", {
+        params: { query: { "filter[key]": key } }
+      });
+      if (result.error !== void 0)
+        await checkError(result.response, `Config with key '${key}' not found`);
+      data = result.data;
+    } catch (err) {
+      wrapFetchError(err);
+    }
+    if (!data || !data.data || data.data.length === 0) {
+      throw new SmplNotFoundError(`Config with key '${key}' not found`);
     }
+    return resourceToConfig(data.data[0], this);
   }
 };
 
 // src/client.ts
-var DEFAULT_BASE_URL = "https://config.smplkit.com";
 var SmplkitClient = class {
   /** Client for config management-plane operations. */
   config;
-  /** @internal */
-  transport;
   constructor(options) {
     if (!options.apiKey) {
       throw new Error("apiKey is required");
     }
-    this.transport = new Transport({
-      apiKey: options.apiKey,
-      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
-      timeout: options.timeout
-    });
-    this.config = new ConfigClient(this.transport);
+    this.config = new ConfigClient(options.apiKey, options.timeout);
   }
 };
 export {
+  Config,
   ConfigClient,
+  ConfigRuntime,
   SmplConflictError,
   SmplConnectionError,
   SmplError,