@smplkit/sdk 1.8.4 → 1.9.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import createClient from 'openapi-fetch';
+
 /**
  * Internal SDK telemetry engine.
  *
@@ -906,6 +908,14 @@ declare class FlagStats {
     readonly cacheMisses: number;
     constructor(cacheHits: number, cacheMisses: number);
 }
+/** @internal — exported so ManagementClient.contexts can share the same buffer. */
+declare class ContextRegistrationBuffer {
+    private _seen;
+    private _pending;
+    observe(contexts: Context[]): void;
+    drain(): Array<Record<string, any>>;
+    get pendingCount(): number;
+}
 /**
  * Management API for smplkit Flags — CRUD operations on Flag models.
  *
@@ -993,7 +1003,7 @@ declare class FlagsClient {
     /** Management API — CRUD operations on Flag models. */
     readonly management: FlagsManagement;
     /** @internal */
-    constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number, flagsBaseUrl?: string, appBaseUrl?: string);
+    constructor(apiKey: string, ensureWs: () => SharedWebSocket, timeout?: number, flagsBaseUrl?: string, appBaseUrl?: string, contextBuffer?: ContextRegistrationBuffer);
     /** @internal */
     _mgNewBooleanFlag(id: string, options: {
         default: boolean;
@@ -1080,14 +1090,6 @@ declare class FlagsClient {
      * - `onChange(id, callback)` — fires only for the specified flag id.
      */
     onChange(callbackOrId: string | ((event: FlagChangeEvent) => void), callback?: (event: FlagChangeEvent) => void): void;
-    /**
-     * Register context(s) with the server.
-     *
-     * Accepts a single Context or an array. Works before `initialize()` is called.
-     */
-    register(context: Context | Context[]): void;
-    /** Flush pending context registrations to the server. */
-    flushContexts(): Promise<void>;
     /**
      * Evaluate a flag with an explicit environment and context.
      */
@@ -1139,6 +1141,31 @@ interface LoggerChangeEvent {
     /** True when the logger or group was deleted. */
     deleted?: true;
 }
+/**
+ * Describes a logger to register via `client.logging.management.registerSources()`.
+ *
+ * Unlike auto-discovery (which reads the current process's logging framework),
+ * `registerSources` accepts explicit `service` and `environment` overrides —
+ * useful for sample-data seeding, cross-tenant migration, and test fixtures.
+ */
+declare class LoggerSource {
+    /** Logger name (e.g. `"sqlalchemy.engine"`). */
+    readonly name: string;
+    /** Service name this source belongs to. */
+    readonly service: string;
+    /** Environment name this source belongs to. */
+    readonly environment: string;
+    /** Effective log level for this source. */
+    readonly resolvedLevel: LogLevel;
+    /** Explicit (configured) log level, if different from `resolvedLevel`. */
+    readonly level: LogLevel | null;
+    constructor(name: string, options: {
+        service: string;
+        environment: string;
+        resolved_level: LogLevel;
+        level?: LogLevel | null;
+    });
+}
 
 /**
  * Logger and LogGroup active-record models for the Logging SDK.
@@ -1155,7 +1182,7 @@ declare class Logger {
     /** Human-readable display name. */
     name: string;
     /** Base log level, or null if inherited. */
-    level: string | null;
+    level: LogLevel | null;
     /** Id of the parent log group, or null. */
     group: string | null;
     /** Whether this logger is managed by the platform. */
@@ -1174,7 +1201,7 @@ declare class Logger {
     constructor(client: LoggingClient, fields: {
         id: string | null;
         name: string;
-        level: string | null;
+        level: LogLevel | null;
         group: string | null;
         managed: boolean;
         sources: Array<Record<string, any>>;
@@ -1215,7 +1242,7 @@ declare class LogGroup {
     /** Human-readable display name. */
     name: string;
     /** Base log level, or null if inherited. */
-    level: string | null;
+    level: LogLevel | null;
     /** Id of the parent log group, or null. */
     group: string | null;
     /** Per-environment level overrides. */
@@ -1231,7 +1258,7 @@ declare class LogGroup {
         id: string | null;
         key: string | null;
         name: string;
-        level: string | null;
+        level: LogLevel | null;
         group: string | null;
         environments: Record<string, any>;
         createdAt: string | null;
@@ -1321,6 +1348,14 @@ declare class LoggingManagement {
     listGroups(): Promise<LogGroup[]>;
     /** Delete a log group by id. */
     deleteGroup(id: string): Promise<void>;
+    /**
+     * Bulk-register explicit logger sources with the logging service.
+     *
+     * Unlike `start()`, which auto-discovers loggers from the current
+     * process, this method accepts explicit `service` and `environment`
+     * overrides — useful for sample-data seeding and test fixtures.
+     */
+    registerSources(sources: LoggerSource[]): Promise<void>;
 }
 /**
  * Client for the smplkit Logging API.
@@ -1383,6 +1418,8 @@ declare class LoggingClient {
     /** @internal */
     _mgListGroups(): Promise<LogGroup[]>;
     /** @internal */
+    _mgRegisterSources(sources: LoggerSource[]): Promise<void>;
+    /** @internal */
     _mgDeleteGroup(id: string): Promise<void>;
     /** @internal — PUT a logger (upsert: server creates if not found). */
     _saveLogger(logger: Logger): Promise<Logger>;
@@ -1426,6 +1463,285 @@ declare class LoggingClient {
     private _groupToModel;
 }
 
+/**
+ * Shared types for the management namespace.
+ */
+/** Whether an environment participates in the canonical ordering.
+ *
+ * STANDARD environments are the customer's deploy targets (production,
+ * staging, development, etc.) and appear in the environment_order list.
+ * AD_HOC environments are transient targets (preview branches,
+ * developer sandboxes) that are excluded from the standard ordering.
+ */
+declare enum EnvironmentClassification {
+    STANDARD = "STANDARD",
+    AD_HOC = "AD_HOC"
+}
+
+/**
+ * Active-record models for client.management.* resources.
+ */
+
+/**
+ * An environment resource managed by the smplkit platform.
+ *
+ * Mutate fields, then call `save()` to create or update.
+ */
+declare class Environment {
+    /** Unique slug identifier (e.g. `"production"`). */
+    id: string | null;
+    /** Human-readable display name. */
+    name: string;
+    /** Hex color code, or null. */
+    color: string | null;
+    /** Whether this is a STANDARD or AD_HOC environment. */
+    classification: EnvironmentClassification;
+    /** When the environment was created. */
+    createdAt: string | null;
+    /** When the environment was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    readonly _client: EnvironmentsClient | null;
+    /** @internal */
+    constructor(client: EnvironmentsClient | null, fields: {
+        id: string | null;
+        name: string;
+        color: string | null;
+        classification: EnvironmentClassification;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /** Persist this environment to the server (creates if new, updates if existing). */
+    save(): Promise<void>;
+    /** @internal */
+    _apply(other: Environment): void;
+    toString(): string;
+}
+/**
+ * A context-type resource managed by the smplkit platform.
+ *
+ * Mutate fields or use `addAttribute`/`removeAttribute`/`updateAttribute`,
+ * then call `save()` to persist.
+ */
+declare class ContextType {
+    /** Unique slug identifier (e.g. `"user"`). */
+    id: string | null;
+    /** Human-readable display name. */
+    name: string;
+    /** Known attribute keys with metadata objects. */
+    attributes: Record<string, Record<string, any>>;
+    /** When the context type was created. */
+    createdAt: string | null;
+    /** When the context type was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    readonly _client: ContextTypesClient | null;
+    /** @internal */
+    constructor(client: ContextTypesClient | null, fields: {
+        id: string | null;
+        name: string;
+        attributes: Record<string, Record<string, any>>;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /** Add a known-attribute slot. Local; call `save()` to persist. */
+    addAttribute(name: string, metadata?: Record<string, any>): void;
+    /** Remove a known-attribute slot. Local; call `save()` to persist. */
+    removeAttribute(name: string): void;
+    /** Replace a known-attribute slot's metadata. Local; call `save()` to persist. */
+    updateAttribute(name: string, metadata: Record<string, any>): void;
+    /** Persist this context type to the server (creates if new, updates if existing). */
+    save(): Promise<void>;
+    /** @internal */
+    _apply(other: ContextType): void;
+    toString(): string;
+}
+/**
+ * A context instance as returned by the management API.
+ *
+ * The write path is `client.management.contexts.register([...])`.
+ * This model is what comes back from `list`/`get`.
+ */
+declare class ContextEntity {
+    /** Context type key (e.g. `"user"`). */
+    type: string;
+    /** Entity key (e.g. `"user-123"`). */
+    key: string;
+    /** Human-readable display name, or null. */
+    name: string | null;
+    /** Observed attributes. */
+    attributes: Record<string, any>;
+    /** When the context was created. */
+    createdAt: string | null;
+    /** When the context was last updated. */
+    updatedAt: string | null;
+    /** @internal */
+    constructor(fields: {
+        type: string;
+        key: string;
+        name: string | null;
+        attributes: Record<string, any>;
+        createdAt: string | null;
+        updatedAt: string | null;
+    });
+    /** Composite `"type:key"` identifier. */
+    get id(): string;
+    toString(): string;
+}
+/**
+ * Active-record account-settings model.
+ *
+ * The wire format is opaque JSON. Documented keys are exposed as typed
+ * properties; unknown keys live in `raw`. Call `save()` to write back.
+ */
+declare class AccountSettings {
+    /** @internal */
+    private _data;
+    /** @internal */
+    readonly _client: AccountSettingsClient | null;
+    /** @internal */
+    constructor(client: AccountSettingsClient | null, data: Record<string, any>);
+    /** The full settings dict. Direct mutations are reflected in `save()`. */
+    get raw(): Record<string, any>;
+    set raw(value: Record<string, any>);
+    /** Canonical ordering of STANDARD environments. Empty array if unset. */
+    get environmentOrder(): string[];
+    set environmentOrder(value: string[]);
+    /** Persist the settings to the server. */
+    save(): Promise<void>;
+    /** @internal */
+    _apply(other: AccountSettings): void;
+    /** @internal — expose raw data for _save(). */
+    get _rawData(): Record<string, any>;
+    toString(): string;
+}
+
+type AppClient = ReturnType<typeof createClient<___generated_app_d_ts.paths>>;
+/**
+ * CRUD client for environments.
+ *
+ * Accessed via `client.management.environments`.
+ */
+declare class EnvironmentsClient {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: AppClient);
+    /**
+     * Return an unsaved `Environment`. Call `.save()` to persist.
+     */
+    new(id: string, options: {
+        name: string;
+        color?: string | null;
+        classification?: EnvironmentClassification;
+    }): Environment;
+    /** List all environments. */
+    list(): Promise<Environment[]>;
+    /** Fetch an environment by id. */
+    get(id: string): Promise<Environment>;
+    /** Delete an environment by id. */
+    delete(id: string): Promise<void>;
+    /** @internal — called by Environment.save() for new resources. */
+    _create(env: Environment): Promise<Environment>;
+    /** @internal — called by Environment.save() for existing resources. */
+    _update(env: Environment): Promise<Environment>;
+}
+/**
+ * CRUD client for context types.
+ *
+ * Accessed via `client.management.context_types`.
+ */
+declare class ContextTypesClient {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: AppClient);
+    /**
+     * Return an unsaved `ContextType`. Call `.save()` to persist.
+     */
+    new(id: string, options?: {
+        name?: string;
+        attributes?: Record<string, Record<string, any>>;
+    }): ContextType;
+    /** List all context types. */
+    list(): Promise<ContextType[]>;
+    /** Fetch a context type by id. */
+    get(id: string): Promise<ContextType>;
+    /** Delete a context type by id. */
+    delete(id: string): Promise<void>;
+    /** @internal — called by ContextType.save() for new resources. */
+    _create(ct: ContextType): Promise<ContextType>;
+    /** @internal — called by ContextType.save() for existing resources. */
+    _update(ct: ContextType): Promise<ContextType>;
+}
+/**
+ * Context registration + read/delete client.
+ *
+ * Accessed via `client.management.contexts`.
+ */
+declare class ContextsClient {
+    private readonly _http;
+    private readonly _buffer;
+    /** @internal */
+    constructor(_http: AppClient, _buffer: ContextRegistrationBuffer);
+    /**
+     * Buffer context(s) for registration; optionally flush immediately.
+     *
+     * When `flush` is false (default), contexts are queued for the SDK's
+     * background flush — right for high-frequency observation from a live
+     * request handler. When `flush` is true the call awaits the round-trip
+     * — right for IaC scripts.
+     */
+    register(items: Context | Context[], options?: {
+        flush?: boolean;
+    }): Promise<void>;
+    /** Send any pending context observations to the server. */
+    flush(): Promise<void>;
+    /** List all contexts of a given type. */
+    list(type: string): Promise<ContextEntity[]>;
+    /** Fetch a context by composite id (`"type:key"`) or by separate type and key. */
+    get(idOrType: string, key?: string): Promise<ContextEntity>;
+    /** Delete a context by composite id (`"type:key"`) or by separate type and key. */
+    delete(idOrType: string, key?: string): Promise<void>;
+}
+/**
+ * Account-settings get/save client.
+ *
+ * The settings endpoint is not JSON:API — body is a raw JSON object — so
+ * we use fetch directly rather than the typed openapi-fetch client.
+ *
+ * Accessed via `client.management.account_settings`.
+ */
+declare class AccountSettingsClient {
+    private readonly _appBaseUrl;
+    private readonly _headers;
+    /** @internal */
+    constructor(_appBaseUrl: string, apiKey: string);
+    /** Fetch the current account settings. */
+    get(): Promise<AccountSettings>;
+    /** @internal — called by AccountSettings.save(). */
+    _save(data: Record<string, any>): Promise<AccountSettings>;
+}
+/**
+ * Top-level management namespace.
+ *
+ * Accessed via `client.management`.
+ */
+declare class ManagementClient {
+    /** CRUD for environments. */
+    readonly environments: EnvironmentsClient;
+    /** Registration, list, get, and delete for context instances. */
+    readonly contexts: ContextsClient;
+    /** CRUD for context types (entity schemas). */
+    readonly context_types: ContextTypesClient;
+    /** Get/save for account-level settings. */
+    readonly account_settings: AccountSettingsClient;
+    /** @internal */
+    constructor(options: {
+        appBaseUrl: string;
+        apiKey: string;
+        buffer: ContextRegistrationBuffer;
+    });
+}
+
 /**
  * Top-level SDK client — SmplClient.
  *
@@ -1518,6 +1834,8 @@ declare class SmplClient {
     readonly flags: FlagsClient;
     /** Client for logging management and runtime. */
     readonly logging: LoggingClient;
+    /** Client for app-plane management (environments, contexts, context types, account settings). */
+    readonly management: ManagementClient;
     private _wsManager;
     private readonly _apiKey;
     /** @internal */
@@ -1636,4 +1954,4 @@ declare class SmplValidationError extends SmplError {
     constructor(message: string, statusCode?: number, responseBody?: string, errors?: ApiErrorObject[]);
 }
 
-export { type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, ConfigManagement, Context, Flag, FlagChangeEvent, FlagStats, FlagsClient, FlagsManagement, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, type LoggingAdapter, LoggingClient, LoggingManagement, NumberFlag, PinoAdapter, type PinoAdapterConfig, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag, WinstonAdapter, type WinstonAdapterConfig };
+export { AccountSettings, AccountSettingsClient, type ApiErrorObject, BooleanFlag, Config, type ConfigChangeEvent, ConfigClient, ConfigManagement, Context, ContextEntity, ContextType, ContextTypesClient, ContextsClient, Environment, EnvironmentClassification, EnvironmentsClient, Flag, FlagChangeEvent, FlagStats, FlagsClient, FlagsManagement, JsonFlag, LiveConfigProxy, LogGroup, LogLevel, Logger, type LoggerChangeEvent, LoggerSource, type LoggingAdapter, LoggingClient, LoggingManagement, ManagementClient, NumberFlag, PinoAdapter, type PinoAdapterConfig, Rule, SharedWebSocket, SmplClient, type SmplClientOptions, SmplConflictError, SmplConnectionError, SmplError, SmplNotFoundError, SmplTimeoutError, SmplValidationError, StringFlag, WinstonAdapter, type WinstonAdapterConfig };