@smplkit/sdk 3.0.51 → 3.0.53

package/dist/index.d.ts

@@ -5,25 +5,61 @@ import createClient from 'openapi-fetch';
  *
  * ADR-047 §2.3.1.
  */
+/**
+ * A single audit event as returned by the audit service. ADR-047 §2.3.1.
+ */
 interface AuditEvent {
+    /** Server-assigned UUID for this event. */
     id: string;
+    /** Action slug — e.g. `"user.created"`, `"invoice.paid"`. */
     action: string;
+    /** Type of resource the action operated on — e.g. `"invoice"`. */
     resourceType: string;
+    /** Customer-facing id of the resource the action operated on. */
     resourceId: string;
+    /** ISO-8601-with-offset timestamp of when the action actually happened. */
     occurredAt: string;
+    /** ISO-8601-with-offset timestamp of when the audit service ingested the event. */
     createdAt: string;
+    /**
+     * Type of the actor that performed the action (`"user"`, `"api_key"`,
+     * `"system"`, …). Empty string when unknown.
+     */
     actorType: string;
+    /**
+     * UUID of the actor, when the actor is a tracked entity
+     * (user, api_key). `null` for system actors or anonymous events.
+     */
     actorId: string | null;
+    /**
+     * Display label for the actor — typically a name or email. Empty
+     * string when unknown.
+     */
     actorLabel: string;
+    /**
+     * Free-form per-event payload defined by the customer. Surfaced on
+     * the audit-event resource as a structured JSONB column.
+     */
     data: Record<string, unknown>;
+    /** Customer-supplied dedupe key. Empty when the customer didn't supply one. */
     idempotencyKey: string;
+    /**
+     * When `true`, the audit service records the event but skips SIEM
+     * forwarder delivery regardless of any matching forwarder filter.
+     */
     doNotForward: boolean;
 }
+/**
+ * Inputs for `client.audit.events.record(...)`.
+ */
 interface CreateEventInput {
+    /** Action slug — e.g. `"invoice.paid"`. */
     action: string;
+    /** Type of resource the action operated on. */
     resourceType: string;
+    /** Customer-facing id of the resource. */
     resourceId: string;
-    /** Defaults to server-side now() if omitted. */
+    /** Defaults to server-side `now()` if omitted. */
     occurredAt?: Date | string;
     /**
      * Free-form contextual JSON. To record a resource snapshot, nest it
@@ -34,34 +70,57 @@ interface CreateEventInput {
     /** Optional caller-supplied idempotency key. Server derives one from event content if absent. */
     idempotencyKey?: string;
     /**
-     * When true, the audit service records the event normally but does NOT POST
-     * it through any configured SIEM forwarder. A `skipped_do_not_forward`
-     * delivery row is recorded for each enabled forwarder so the skip is
-     * visible in the forwarder delivery log.
+     * When `true`, the audit service records the event normally but does
+     * NOT POST it through any configured SIEM forwarder. A
+     * `skipped_do_not_forward` delivery row is recorded for each enabled
+     * forwarder so the skip is visible in the forwarder delivery log.
      */
     doNotForward?: boolean;
 }
+/**
+ * Parameters accepted by `client.audit.events.list(...)`. Cursor
+ * paginated per ADR-014; pass {@link pageAfter} from the prior page's
+ * `nextCursor` to walk forward.
+ */
 interface ListEventsParams {
+    /** Filter to this action slug. */
     action?: string;
+    /** Filter to this resource_type slug. */
     resourceType?: string;
+    /** Filter to this resource id. */
     resourceId?: string;
+    /** Filter to this actor type. */
     actorType?: string;
+    /** Filter to this actor id. */
     actorId?: string;
-    /** Range notation per ADR-014, e.g. `[2026-01-01T00:00:00Z,*)`. */
+    /** Range notation per ADR-014, e.g. `"[2026-01-01T00:00:00Z,*)"`. */
     occurredAtRange?: string;
+    /** Items per page (1–1000). Defaults to 1000. */
     pageSize?: number;
+    /** Opaque cursor returned by the prior page's `nextCursor`. */
     pageAfter?: string;
 }
+/**
+ * Page of events returned by `client.audit.events.list(...)`.
+ */
 interface ListEventsPage {
+    /** Events on this page, newest first. */
     events: AuditEvent[];
-    /** Opaque cursor for the next page, or null if this is the last page. */
+    /** Opaque cursor for the next page, or `null` if this is the last page. */
     nextCursor: string | null;
 }
+/**
+ * A distinct `resource_type` slug seen for the account.
+ */
 interface ResourceType {
-    /** The resource_type slug. */
+    /** The resource_type slug, surfaced as the JSON:API resource id. */
     id: string;
+    /** ISO-8601 timestamp of the earliest sighting for the account. */
     createdAt: string;
 }
+/**
+ * Parameters accepted by `client.audit.resourceTypes.list(...)`.
+ */
 interface ListResourceTypesParams {
     /** 1-based page number to return. Defaults to 1. */
     pageNumber?: number;
@@ -70,15 +129,32 @@ interface ListResourceTypesParams {
     /** Include `total` and `totalPages` in {@link Pagination}. Defaults to false. */
     metaTotal?: boolean;
 }
+/**
+ * Page of resource types returned by
+ * `client.audit.resourceTypes.list(...)`.
+ */
 interface ListResourceTypesPage {
+    /** Resource types on this page, alphabetically sorted. */
     resourceTypes: ResourceType[];
+    /** Pagination metadata. */
     pagination: Pagination;
 }
+/**
+ * A distinct action slug seen for the account.
+ */
 interface Action {
-    /** The action slug. */
+    /** The action slug, surfaced as the JSON:API resource id. */
     id: string;
+    /**
+     * ISO-8601 timestamp of the earliest sighting for the account. When
+     * the list call was filtered by `resourceType`, this is the first
+     * sighting of that specific (action, resource_type) pair.
+     */
     createdAt: string;
 }
+/**
+ * Parameters accepted by `client.audit.actions.list(...)`.
+ */
 interface ListActionsParams {
     /** When set, returns only the actions seen with this resource_type. */
     filterResourceType?: string;
@@ -89,61 +165,204 @@ interface ListActionsParams {
     /** Include `total` and `totalPages` in {@link Pagination}. Defaults to false. */
     metaTotal?: boolean;
 }
+/**
+ * Page of actions returned by `client.audit.actions.list(...)`.
+ */
 interface ActionListPage {
+    /** Actions on this page, alphabetically sorted. */
     actions: Action[];
+    /** Pagination metadata. */
     pagination: Pagination;
 }
+/**
+ * A single name/value HTTP header on a forwarder destination.
+ */
 interface HttpHeader {
+    /** Header name (e.g. `"Authorization"`, `"DD-API-KEY"`). */
     name: string;
+    /**
+     * Header value, plaintext on writes. The audit service encrypts values
+     * at rest; reads return them as `"<redacted>"`.
+     */
     value: string;
 }
 /**
  * Supported SIEM forwarder destination types.
  *
- * ADR-047 §2.12. Mirrors the OpenAPI ``ForwarderType`` enum so callers
- * see autocomplete and the compiler rejects typos at build time. The
- * runtime values are a subset of the published constant
- * {@link FORWARDER_TYPES} for callers that need to iterate.
+ * ADR-047 §2.12. Mirrors the audit service's OpenAPI `ForwarderType`
+ * enum so callers get autocomplete and the compiler rejects typos at
+ * build time. The available types are real-time HTTP destinations
+ * sharing one outbound plumbing path. Object-storage archival (S3, GCS,
+ * etc.) has different operational shape (batching, IAM, lifecycle
+ * policies) and will get its own type if customer demand warrants.
+ */
+declare enum ForwarderType {
+    DATADOG = "DATADOG",
+    ELASTIC = "ELASTIC",
+    HONEYCOMB = "HONEYCOMB",
+    HTTP = "HTTP",
+    NEW_RELIC = "NEW_RELIC",
+    SPLUNK_HEC = "SPLUNK_HEC",
+    SUMO_LOGIC = "SUMO_LOGIC"
+}
+/**
+ * HTTP verb used by a forwarder's outbound delivery.
+ *
+ * Mirrors the audit service's OpenAPI `HttpConfigurationMethod` enum so
+ * callers get autocomplete and a typed value back from
+ * `forwarder.configuration.method`.
+ */
+declare enum HttpMethod {
+    DELETE = "DELETE",
+    GET = "GET",
+    PATCH = "PATCH",
+    POST = "POST",
+    PUT = "PUT"
+}
+/**
+ * Engine used to evaluate {@link Forwarder.transform}. Must be set
+ * whenever `transform` is set. Today only `JSONATA` is supported.
+ */
+declare enum TransformType {
+    JSONATA = "JSONATA"
+}
+/**
+ * Forwarder destination HTTP request shape.
+ *
+ * Today every destination type uses HTTP; future transports (FTP, SQS,
+ * ...) will join this as members of a discriminated union under
+ * {@link Forwarder.configuration}.
  */
-type ForwarderType = "HTTP" | "DATADOG" | "SPLUNK_HEC" | "SUMO_LOGIC" | "NEW_RELIC" | "HONEYCOMB" | "ELASTIC";
-interface ForwarderHttp {
-    method: string;
+declare class HttpConfiguration {
+    /** HTTP verb used for delivery. Defaults to {@link HttpMethod.POST}. */
+    method: HttpMethod;
+    /** Destination URL the audit service POSTs each event to. */
     url: string;
+    /**
+     * Headers attached to every outbound request. Values carry credentials
+     * and are encrypted at rest server-side; reads return them redacted.
+     */
     headers: HttpHeader[];
-    body: string | null;
     /**
-     * 3-character string: an exact HTTP code (e.g. `"200"`, `"204"`) or a
-     * class (`"2xx"`, `"3xx"`, `"4xx"`, `"5xx"`).
+     * Status the destination must return for delivery to count as success
+     * — either an exact code (`"200"`, `"204"`) or a status class
+     * (`"2xx"`, `"4xx"`). Defaults to `"2xx"`.
      */
     successStatus: string;
+    constructor(fields?: {
+        method?: HttpMethod;
+        url?: string;
+        headers?: HttpHeader[];
+        successStatus?: string;
+    });
 }
-interface Forwarder {
-    id: string;
+/**
+ * A SIEM streaming forwarder configured on the customer's account.
+ *
+ * Active-record style: mutate fields directly and call {@link save} to
+ * persist, or {@link delete} to remove. Header values in
+ * `configuration.headers` are always returned redacted on reads — the
+ * GET path on the audit API replaces every header value with
+ * `"<redacted>"`. Re-supply the real values before calling {@link save}
+ * (the SDK does not cache them client-side).
+ */
+declare class Forwarder {
+    /**
+     * Server-assigned UUID for this forwarder. `null` until {@link save}
+     * has run for the first time.
+     */
+    id: string | null;
+    /** Display name. Free-form. */
     name: string;
-    slug: string;
+    /** Destination type — see {@link ForwarderType}. */
     forwarderType: ForwarderType;
+    /** Destination request configuration. */
+    configuration: HttpConfiguration;
+    /**
+     * When `false`, the audit service skips delivery for this forwarder
+     * but still records `filtered_out` deliveries.
+     */
     enabled: boolean;
+    /** Optional free-text description. */
+    description: string | null;
+    /**
+     * Optional JSON Logic expression evaluated per event. When set, events
+     * that don't match are recorded as `filtered_out` deliveries instead
+     * of being POSTed to the destination.
+     */
     filter: Record<string, unknown> | null;
+    /**
+     * Optional template applied to each event before delivery. Shape
+     * depends on {@link transformType}; for `"JSONATA"`, a JSONata
+     * expression string. `null` delivers the event JSON as-is.
+     */
     transform: string | null;
-    /** Header values are returned redacted on reads. */
-    http: ForwarderHttp;
+    /**
+     * Engine used to evaluate {@link transform}. Currently only
+     * `"JSONATA"` is supported. Auto-filled by the SDK whenever
+     * {@link transform} is set on save.
+     */
+    transformType: TransformType | null;
+    /**
+     * When the audit service first persisted this forwarder. `null` for
+     * an unsaved instance.
+     */
     createdAt: string | null;
+    /** When this forwarder was last mutated. */
     updatedAt: string | null;
+    /** Soft-delete timestamp. `null` for live forwarders. */
     deletedAt: string | null;
+    /** Monotonic version counter; bumped on every server-side write. */
     version: number | null;
+    /** @internal */
+    _client: ForwarderModelClient | null;
+    constructor(client: ForwarderModelClient | null, fields: {
+        id?: string | null;
+        name: string;
+        forwarderType: ForwarderType;
+        configuration: HttpConfiguration;
+        enabled?: boolean;
+        description?: string | null;
+        filter?: Record<string, unknown> | null;
+        transform?: string | null;
+        transformType?: TransformType | null;
+        createdAt?: string | null;
+        updatedAt?: string | null;
+        deletedAt?: string | null;
+        version?: number | null;
+    });
+    /**
+     * Create or update this forwarder on the server.
+     *
+     * Upsert behavior is driven by {@link createdAt}: a forwarder with
+     * no `createdAt` is created (POST); otherwise it's full-replace
+     * updated (PUT). After the call, every field is refreshed from the
+     * server response (including newly-assigned `id`, `createdAt`,
+     * `updatedAt`, `version`).
+     */
+    save(): Promise<void>;
+    /** Soft-delete this forwarder on the server. */
+    delete(): Promise<void>;
+    /** @internal Copy every server-authoritative field from `other` onto self. */
+    _apply(other: Forwarder): void;
 }
-interface CreateForwarderInput {
-    name: string;
-    forwarderType: ForwarderType;
-    http: ForwarderHttp;
-    enabled?: boolean;
-    filter?: Record<string, unknown>;
-    transform?: string;
-}
-interface UpdateForwarderInput extends CreateForwarderInput {
+/**
+ * @internal Minimal interface that `Forwarder.save()` / `.delete()`
+ * call back into. Implemented by `ForwardersClient` in
+ * `src/management/audit.ts`.
+ */
+interface ForwarderModelClient {
+    _createForwarder(forwarder: Forwarder): Promise<Forwarder>;
+    _updateForwarder(forwarder: Forwarder): Promise<Forwarder>;
+    _deleteForwarder(id: string): Promise<void>;
 }
+/**
+ * Parameters accepted by `mgmt.audit.forwarders.list(...)`.
+ */
 interface ListForwardersParams {
+    /** Filter to a single forwarder type. */
     forwarderType?: ForwarderType;
+    /** Filter to forwarders matching this enabled state. */
     enabled?: boolean;
     /** 1-based page number to return. Defaults to 1. */
     pageNumber?: number;
@@ -152,8 +371,13 @@ interface ListForwardersParams {
     /** Include `total` and `totalPages` in {@link Pagination}. Defaults to false. */
     metaTotal?: boolean;
 }
+/**
+ * Page of forwarders returned by `mgmt.audit.forwarders.list(...)`.
+ */
 interface ListForwardersPage {
+    /** Forwarders on this page, in server-defined order. */
     forwarders: Forwarder[];
+    /** Pagination metadata (`page`, `size`, optional `total`/`totalPages`). */
     pagination: Pagination;
 }
 /**
@@ -1670,16 +1894,17 @@ interface components {
 /**
  * Shared types for the management namespace.
  */
-/** Whether an environment participates in the canonical ordering.
+/**
+ * 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,
+ * `AD_HOC` environments are transient targets (preview branches,
  * developer sandboxes) that are excluded from the standard ordering.
+ * `STANDARD` environments are the customer's deploy targets (production,
+ * staging, development, etc.) and appear in the environment_order list.
  */
 declare enum EnvironmentClassification {
-    STANDARD = "STANDARD",
-    AD_HOC = "AD_HOC"
+    AD_HOC = "AD_HOC",
+    STANDARD = "STANDARD"
 }
 /**
  * A color, expressed as a CSS hex string.
@@ -1839,14 +2064,14 @@ declare class AccountSettings {
  * can validate calls. Raw strings are still accepted for flexibility.
  */
 declare enum Op {
+    CONTAINS = "contains",
     EQ = "==",
-    NEQ = "!=",
-    LT = "<",
-    LTE = "<=",
     GT = ">",
     GTE = ">=",
     IN = "in",
-    CONTAINS = "contains"
+    LT = "<",
+    LTE = "<=",
+    NEQ = "!="
 }
 /** @internal */
 interface ContextClient {
@@ -1967,10 +2192,10 @@ declare class Rule {
  */
 /** Type of a {@link ConfigItem} value. */
 declare enum ItemType {
-    STRING = "STRING",
-    NUMBER = "NUMBER",
     BOOLEAN = "BOOLEAN",
-    JSON = "JSON"
+    JSON = "JSON",
+    NUMBER = "NUMBER",
+    STRING = "STRING"
 }
 /** @internal Config client surface used by the active-record `Config.save`/`delete`. */
 interface ConfigModelClient {
@@ -2621,15 +2846,21 @@ declare class ManagementFlagsClient {
 /**
  * Public types for the Logging SDK.
  */
-/** Log level values matching the smplkit platform. */
+/**
+ * Log severity levels used by the Smpl Logging service.
+ *
+ * Members are declared in alphabetical order. Severity ordering is not
+ * derived from declaration order — it lives in the framework adapter
+ * code that maps these to each framework's native numeric level.
+ */
 declare enum LogLevel {
-    TRACE = "TRACE",
     DEBUG = "DEBUG",
-    INFO = "INFO",
-    WARN = "WARN",
     ERROR = "ERROR",
     FATAL = "FATAL",
-    SILENT = "SILENT"
+    INFO = "INFO",
+    SILENT = "SILENT",
+    TRACE = "TRACE",
+    WARN = "WARN"
 }
 /**
  * Describes a logger effective-level change. Frozen — fields cannot be
@@ -2926,32 +3157,84 @@ declare class LogGroupsClient {
 /**
  * Smpl Audit management surface — `mgmt.audit.*`.
  *
- * Counterpart to the runtime `AuditClient`. The runtime client owns event
- * recording and read-side queries; this client owns SIEM forwarder CRUD:
+ * Counterpart to the runtime `AuditClient`. The runtime client owns
+ * event recording and read-side queries; this client owns SIEM
+ * forwarder CRUD via the active-record {@link Forwarder} model:
  *
- *   mgmt.audit.forwarders.{create,get,list,update,delete}
+ *   mgmt.audit.forwarders.{new,get,list,delete}
+ *   Forwarder.{save,delete}
  *
  * New audit-management capabilities should be added here, not in
  * `src/audit/client.ts`.
  */
 
 type AuditHttp = ReturnType<typeof createClient<paths>>;
-/** `mgmt.audit.forwarders.*` — CRUD for SIEM forwarders. */
-declare class ForwardersClient {
+/**
+ * `mgmt.audit.forwarders.*` — active-record CRUD for SIEM forwarders.
+ */
+declare class ForwardersClient implements ForwarderModelClient {
     private readonly _http;
     /** @internal */
     constructor(_http: AuditHttp);
-    create(input: CreateForwarderInput): Promise<Forwarder>;
-    list(params?: ListForwardersParams): Promise<ListForwardersPage>;
-    get(forwarderId: string): Promise<Forwarder>;
     /**
-     * Full-replace update. PUT semantics — every field is overwritten.
+     * Construct an unsaved {@link Forwarder}. Call {@link Forwarder.save}
+     * to persist.
+     *
+     * @param fields.name           Display name. Free-form.
+     * @param fields.forwarderType  Destination type — see {@link ForwarderType}.
+     * @param fields.configuration  Destination HTTP request configuration.
+     *                              Headers carry credentials and are
+     *                              encrypted at rest server-side; reads
+     *                              return them redacted.
+     * @param fields.enabled        Whether the forwarder is active. Defaults true.
+     * @param fields.description    Optional free-text description.
+     * @param fields.filter         Optional JSON Logic filter; events that
+     *                              don't match are recorded as
+     *                              `filtered_out` deliveries.
+     * @param fields.transform      Optional JSONata template applied to
+     *                              the event payload before POST. `null`
+     *                              delivers the event as-is.
+     */
+    new(fields: {
+        name: string;
+        forwarderType: ForwarderType;
+        configuration: HttpConfiguration;
+        enabled?: boolean;
+        description?: string | null;
+        filter?: Record<string, unknown> | null;
+        transform?: string | null;
+    }): Forwarder;
+    /**
+     * List forwarders for the authenticated account.
      *
-     * Header values must be re-supplied as plaintext; the GET path
-     * returns them in plaintext for exactly this round-trip.
+     * Offset paginated per ADR-014: pass {@link ListForwardersParams.pageNumber}
+     * (1-based) and {@link ListForwardersParams.pageSize} (default 1000,
+     * max 1000). Pass `metaTotal=true` to populate `total` and `totalPages`
+     * in the returned `pagination` (costs an extra `COUNT` query
+     * server-side).
      */
-    update(forwarderId: string, input: UpdateForwarderInput): Promise<Forwarder>;
+    list(params?: ListForwardersParams): Promise<ListForwardersPage>;
+    /**
+     * Fetch a single forwarder by id. The returned instance is bound to
+     * this client so {@link Forwarder.save} and {@link Forwarder.delete}
+     * round-trip back here.
+     */
+    get(forwarderId: string): Promise<Forwarder>;
+    /** Soft-delete a forwarder by id. */
     delete(forwarderId: string): Promise<void>;
+    /**
+     * @internal Called by `Forwarder.save()` on unsaved instances.
+     */
+    _createForwarder(forwarder: Forwarder): Promise<Forwarder>;
+    /**
+     * @internal Full-replace PUT. Called by `Forwarder.save()` on
+     * instances that already have a `createdAt`. Header values must be
+     * re-supplied as plaintext; the GET path redacts them, so a PUT body
+     * containing `"<redacted>"` would persist that literal.
+     */
+    _updateForwarder(forwarder: Forwarder): Promise<Forwarder>;
+    /** @internal Called by `Forwarder.delete()`. */
+    _deleteForwarder(id: string): Promise<void>;
 }
 /** `mgmt.audit.*` — management surface for the audit service. */
 declare class ManagementAuditClient {