@smplkit/sdk 1.3.5 → 1.3.7

package/dist/index.d.cts

@@ -727,9 +727,9 @@ interface SmplClientOptions {
      */
     environment?: string;
     /**
-     * Optional service name. When set, the SDK automatically registers
-     * the service as a context instance and includes it in flag
-     * evaluation context.
+     * Service name. The SDK automatically registers the service as a
+     * context instance and includes it in flag evaluation context.
+     * When omitted, resolved from the `SMPLKIT_SERVICE` environment variable.
      */
     service?: string;
     /**
@@ -759,7 +759,7 @@ declare class SmplClient {
     /** @internal */
     readonly _environment: string;
     /** @internal */
-    readonly _service: string | null;
+    readonly _service: string;
     private _connected;
     private readonly _timeout;
     private readonly _appHttp;
@@ -788,29 +788,39 @@ declare class SmplClient {
  * the base class for generic handling or specific subclasses for
  * fine-grained control.
  */
+/** A single error object from a JSON:API error response. */
+interface ApiErrorObject {
+    status?: string;
+    title?: string;
+    detail?: string;
+    source?: Record<string, unknown>;
+}
 /** Base exception for all smplkit SDK errors. */
 declare class SmplError extends Error {
     /** The HTTP status code, if the error originated from an HTTP response. */
     readonly statusCode?: number;
     /** The raw response body, if available. */
     readonly responseBody?: string;
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    /** Structured JSON:API error objects from the server response, if available. */
+    readonly errors: ReadonlyArray<ApiErrorObject>;
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
+    toString(): string;
 }
 /** Raised when a network request fails (e.g., DNS resolution, connection refused). */
 declare class SmplConnectionError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when an operation exceeds its timeout. */
 declare class SmplTimeoutError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when a requested resource does not exist (HTTP 404). */
 declare class SmplNotFoundError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when an operation conflicts with current state (HTTP 409). */
 declare class SmplConflictError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when a method requiring connect() is called before connecting. */
 declare class SmplNotConnectedError extends SmplError {
@@ -818,7 +828,7 @@ declare class SmplNotConnectedError extends SmplError {
 }
 /** Raised when the server rejects a request due to validation errors (HTTP 422). */
 declare class SmplValidationError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 
-export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };
+export { type ApiErrorObject, BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };

package/dist/index.d.ts

@@ -727,9 +727,9 @@ interface SmplClientOptions {
      */
     environment?: string;
     /**
-     * Optional service name. When set, the SDK automatically registers
-     * the service as a context instance and includes it in flag
-     * evaluation context.
+     * Service name. The SDK automatically registers the service as a
+     * context instance and includes it in flag evaluation context.
+     * When omitted, resolved from the `SMPLKIT_SERVICE` environment variable.
      */
     service?: string;
     /**
@@ -759,7 +759,7 @@ declare class SmplClient {
     /** @internal */
     readonly _environment: string;
     /** @internal */
-    readonly _service: string | null;
+    readonly _service: string;
     private _connected;
     private readonly _timeout;
     private readonly _appHttp;
@@ -788,29 +788,39 @@ declare class SmplClient {
  * the base class for generic handling or specific subclasses for
  * fine-grained control.
  */
+/** A single error object from a JSON:API error response. */
+interface ApiErrorObject {
+    status?: string;
+    title?: string;
+    detail?: string;
+    source?: Record<string, unknown>;
+}
 /** Base exception for all smplkit SDK errors. */
 declare class SmplError extends Error {
     /** The HTTP status code, if the error originated from an HTTP response. */
     readonly statusCode?: number;
     /** The raw response body, if available. */
     readonly responseBody?: string;
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    /** Structured JSON:API error objects from the server response, if available. */
+    readonly errors: ReadonlyArray<ApiErrorObject>;
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
+    toString(): string;
 }
 /** Raised when a network request fails (e.g., DNS resolution, connection refused). */
 declare class SmplConnectionError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when an operation exceeds its timeout. */
 declare class SmplTimeoutError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when a requested resource does not exist (HTTP 404). */
 declare class SmplNotFoundError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when an operation conflicts with current state (HTTP 409). */
 declare class SmplConflictError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 /** Raised when a method requiring connect() is called before connecting. */
 declare class SmplNotConnectedError extends SmplError {
@@ -818,7 +828,7 @@ declare class SmplNotConnectedError extends SmplError {
 }
 /** Raised when the server rejects a request due to validation errors (HTTP 422). */
 declare class SmplValidationError extends SmplError {
-    constructor(message: string, statusCode?: number, responseBody?: string);
+    constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 
-export { BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };
+export { type ApiErrorObject, BoolFlagHandle, Config, type ConfigChangeEvent, ConfigClient, Context, ContextType, type CreateConfigOptions, Flag, FlagChangeEvent, FlagStats, type FlagType, FlagsClient, type GetConfigOptions, JsonFlagHandle, NumberFlagHandle, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotConnectedError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlagHandle };

package/dist/index.js

@@ -10,38 +10,54 @@ var SmplError = class extends Error {
   statusCode;
   /** The raw response body, if available. */
   responseBody;
-  constructor(message, statusCode, responseBody) {
+  /** Structured JSON:API error objects from the server response, if available. */
+  errors;
+  constructor(message, statusCode, responseBody, errors) {
     super(message);
     this.name = "SmplError";
     this.statusCode = statusCode;
     this.responseBody = responseBody;
+    this.errors = errors ?? [];
     Object.setPrototypeOf(this, new.target.prototype);
   }
+  toString() {
+    if (this.errors.length === 0) {
+      return `${this.name}: ${this.message}`;
+    }
+    if (this.errors.length === 1) {
+      return `${this.name}: ${this.message}
+Error: ${JSON.stringify(this.errors[0])}`;
+    }
+    const lines = this.errors.map((e, i) => `  [${i}] ${JSON.stringify(e)}`);
+    return `${this.name}: ${this.message}
+Errors:
+${lines.join("\n")}`;
+  }
 };
 var SmplConnectionError = class extends SmplError {
-  constructor(message, statusCode, responseBody) {
-    super(message, statusCode, responseBody);
+  constructor(message, statusCode, responseBody, errors) {
+    super(message, statusCode, responseBody, errors);
     this.name = "SmplConnectionError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 var SmplTimeoutError = class extends SmplError {
-  constructor(message, statusCode, responseBody) {
-    super(message, statusCode, responseBody);
+  constructor(message, statusCode, responseBody, errors) {
+    super(message, statusCode, responseBody, errors);
     this.name = "SmplTimeoutError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 var SmplNotFoundError = class extends SmplError {
-  constructor(message, statusCode, responseBody) {
-    super(message, statusCode ?? 404, responseBody);
+  constructor(message, statusCode, responseBody, errors) {
+    super(message, statusCode ?? 404, responseBody, errors);
     this.name = "SmplNotFoundError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
 var SmplConflictError = class extends SmplError {
-  constructor(message, statusCode, responseBody) {
-    super(message, statusCode ?? 409, responseBody);
+  constructor(message, statusCode, responseBody, errors) {
+    super(message, statusCode ?? 409, responseBody, errors);
     this.name = "SmplConflictError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
@@ -54,12 +70,53 @@ var SmplNotConnectedError = class extends SmplError {
   }
 };
 var SmplValidationError = class extends SmplError {
-  constructor(message, statusCode, responseBody) {
-    super(message, statusCode ?? 422, responseBody);
+  constructor(message, statusCode, responseBody, errors) {
+    super(message, statusCode ?? 422, responseBody, errors);
     this.name = "SmplValidationError";
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+function parseJsonApiErrors(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && Array.isArray(parsed.errors)) {
+      return parsed.errors.map((e) => ({
+        ...e.status !== void 0 ? { status: String(e.status) } : {},
+        ...e.title !== void 0 ? { title: String(e.title) } : {},
+        ...e.detail !== void 0 ? { detail: String(e.detail) } : {},
+        ...e.source !== void 0 && typeof e.source === "object" && e.source !== null ? { source: e.source } : {}
+      }));
+    }
+  } catch {
+  }
+  return [];
+}
+function deriveMessage(errors, statusCode, body) {
+  if (errors.length === 0) {
+    return body ? `HTTP ${statusCode}: ${body}` : `HTTP ${statusCode}`;
+  }
+  const first = errors[0];
+  const base = first.detail ?? first.title ?? (first.status ? `HTTP ${first.status}` : `HTTP ${statusCode}`);
+  if (errors.length > 1) {
+    return `${base} (and ${errors.length - 1} more error${errors.length - 1 > 1 ? "s" : ""})`;
+  }
+  return base;
+}
+function throwForStatus(statusCode, body) {
+  const errors = parseJsonApiErrors(body);
+  const message = deriveMessage(errors, statusCode, body);
+  switch (statusCode) {
+    case 400:
+    case 422:
+      throw new SmplValidationError(message, statusCode, body, errors);
+    case 404:
+      throw new SmplNotFoundError(message, statusCode, body, errors);
+    case 409:
+      throw new SmplConflictError(message, statusCode, body, errors);
+    default:
+      throw new SmplError(message, statusCode, body, errors);
+  }
+}
 
 // src/config/resolve.ts
 function deepMerge(base, override) {
@@ -280,18 +337,9 @@ function resourceToConfig(resource, client) {
     updatedAt: attrs.updated_at ? new Date(attrs.updated_at) : null
   });
 }
-async function checkError(response, context) {
+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);
-  }
+  throwForStatus(response.status, body);
 }
 function wrapFetchError(err) {
   if (err instanceof SmplNotFoundError || err instanceof SmplConflictError || err instanceof SmplValidationError || err instanceof SmplError) {
@@ -794,18 +842,9 @@ var APP_BASE_URL = "https://app.smplkit.com";
 var CACHE_MAX_SIZE = 1e4;
 var CONTEXT_REGISTRATION_LRU_SIZE = 1e4;
 var CONTEXT_BATCH_FLUSH_SIZE = 100;
-async function checkError2(response, context) {
+async function checkError2(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);
-  }
+  throwForStatus(response.status, body);
 }
 function wrapFetchError2(err) {
   if (err instanceof SmplNotFoundError || err instanceof SmplConflictError || err instanceof SmplValidationError || err instanceof SmplError) {
@@ -1784,38 +1823,61 @@ var SharedWebSocket = class {
 import { readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-var NO_API_KEY_MESSAGE = "No API key provided. Set one of:\n  1. Pass apiKey to the constructor\n  2. Set the SMPLKIT_API_KEY environment variable\n  3. Create a ~/.smplkit file with:\n     [default]\n     api_key = your_key_here";
-function resolveApiKey(explicit) {
-  if (explicit) return explicit;
-  const envVal = process.env.SMPLKIT_API_KEY;
-  if (envVal) return envVal;
+function noApiKeyMessage(environment) {
+  return `No API key provided. Set one of:
+  1. Pass apiKey to the constructor
+  2. Set the SMPLKIT_API_KEY environment variable
+  3. Create a ~/.smplkit file with:
+     [${environment}]
+     api_key = your_key_here`;
+}
+function readApiKeyFromConfig(environment) {
   const configPath = join(homedir(), ".smplkit");
   try {
     const content = readFileSync(configPath, "utf-8");
-    let inDefaultSection = false;
+    let currentSection = null;
+    let envKey;
+    let defaultKey;
     for (const line of content.split("\n")) {
       const trimmed = line.trim();
       if (trimmed === "" || trimmed.startsWith("#")) continue;
       if (trimmed.startsWith("[")) {
-        inDefaultSection = trimmed.toLowerCase() === "[default]";
+        const sectionName = trimmed.slice(1, trimmed.indexOf("]")).toLowerCase();
+        currentSection = sectionName;
         continue;
       }
-      if (inDefaultSection && trimmed.startsWith("api_key")) {
+      if (currentSection && trimmed.startsWith("api_key")) {
         const eqIndex = trimmed.indexOf("=");
         if (eqIndex !== -1) {
           const value = trimmed.slice(eqIndex + 1).trim();
-          if (value) return value;
+          if (value) {
+            if (currentSection === environment.toLowerCase()) {
+              envKey = value;
+            } else if (currentSection === "default") {
+              defaultKey = value;
+            }
+          }
         }
       }
     }
+    return envKey ?? defaultKey;
   } catch {
+    return void 0;
   }
-  throw new SmplError(NO_API_KEY_MESSAGE);
+}
+function resolveApiKey(explicit, environment) {
+  if (explicit) return explicit;
+  const envVal = process.env.SMPLKIT_API_KEY;
+  if (envVal) return envVal;
+  const fileKey = readApiKeyFromConfig(environment);
+  if (fileKey) return fileKey;
+  throw new SmplError(noApiKeyMessage(environment));
 }
 
 // src/client.ts
 var APP_BASE_URL2 = "https://app.smplkit.com";
 var NO_ENVIRONMENT_MESSAGE = "No environment provided. Set one of:\n  1. Pass environment to the constructor\n  2. Set the SMPLKIT_ENVIRONMENT environment variable";
+var NO_SERVICE_MESSAGE = "No service provided. Set one of:\n  1. Pass service in options\n  2. Set the SMPLKIT_SERVICE environment variable";
 var SmplClient = class {
   /** Client for config management-plane operations. */
   config;
@@ -1831,14 +1893,18 @@ var SmplClient = class {
   _timeout;
   _appHttp;
   constructor(options = {}) {
-    const apiKey = resolveApiKey(options.apiKey);
-    this._apiKey = apiKey;
     const environment = options.environment || process.env.SMPLKIT_ENVIRONMENT;
     if (!environment) {
       throw new SmplError(NO_ENVIRONMENT_MESSAGE);
     }
     this._environment = environment;
-    this._service = options.service || process.env.SMPLKIT_SERVICE || null;
+    const service = options.service || process.env.SMPLKIT_SERVICE;
+    if (!service) {
+      throw new SmplError(NO_SERVICE_MESSAGE);
+    }
+    this._service = service;
+    const apiKey = resolveApiKey(options.apiKey, environment);
+    this._apiKey = apiKey;
     this._timeout = options.timeout ?? 3e4;
     const ms = this._timeout;
     this._appHttp = createClient3({
@@ -1878,9 +1944,7 @@ var SmplClient = class {
    */
   async connect() {
     if (this._connected) return;
-    if (this._service) {
-      await this._registerServiceContext();
-    }
+    await this._registerServiceContext();
     await this.flags._connectInternal(this._environment);
     await this.config._connectInternal(this._environment);
     this._connected = true;