@smplkit/sdk 3.0.6 → 3.0.8

package/dist/index.cjs

@@ -16623,6 +16623,7 @@ var index_exports = {};
 __export(index_exports, {
   AccountSettings: () => AccountSettings,
   AccountSettingsClient: () => AccountSettingsClient,
+  AuditClient: () => AuditClient,
   BooleanFlag: () => BooleanFlag,
   Color: () => Color,
   Config: () => Config,
@@ -16681,6 +16682,264 @@ module.exports = __toCommonJS(index_exports);
 // src/client.ts
 var import_openapi_fetch5 = __toESM(require("openapi-fetch"), 1);
 
+// src/audit/buffer.ts
+var MAX_BUFFER_SIZE = 1e3;
+var PERIODIC_FLUSH_INTERVAL_MS = 5e3;
+var HIGH_WATERMARK = 50;
+var MAX_ATTEMPTS_PER_ITEM = 5;
+var INITIAL_BACKOFF_MS = 250;
+var MAX_BACKOFF_MS = 8e3;
+var AuditEventBuffer = class {
+  _queue = [];
+  _post;
+  _maxSize;
+  _watermark;
+  _flushTimer;
+  _draining = false;
+  _closed = false;
+  _droppedCount = 0;
+  constructor(opts) {
+    this._post = opts.post;
+    this._maxSize = opts.maxSize ?? MAX_BUFFER_SIZE;
+    this._watermark = opts.watermark ?? HIGH_WATERMARK;
+    const interval = opts.flushIntervalMs ?? PERIODIC_FLUSH_INTERVAL_MS;
+    this._flushTimer = setInterval(() => {
+      void this._drainOnce();
+    }, interval);
+    if (typeof this._flushTimer.unref === "function") {
+      this._flushTimer.unref();
+    }
+  }
+  /** Enqueue a new event. May evict the oldest queued item if full. */
+  enqueue(body, idempotencyKey = null) {
+    if (this._closed) return;
+    if (this._queue.length >= this._maxSize) {
+      this._queue.shift();
+      this._droppedCount += 1;
+      console.warn(
+        `[smplkit.audit] buffer full (size=${this._maxSize}); dropped oldest event (total dropped=${this._droppedCount})`
+      );
+    }
+    this._queue.push({ body, idempotencyKey, attempts: 0, nextRetryAt: 0 });
+    if (this._queue.length >= this._watermark) {
+      void this._drainOnce();
+    }
+  }
+  /** Block (cooperatively) until the buffer is empty or `timeoutMs` elapses. */
+  async flush(timeoutMs = 5e3) {
+    const deadline = Date.now() + timeoutMs;
+    while (this._queue.length > 0) {
+      if (Date.now() >= deadline) {
+        console.warn(`[smplkit.audit] flush timed out after ${timeoutMs}ms`);
+        return;
+      }
+      void this._drainOnce();
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+  /** Stop the periodic timer, drain best-effort, and mark closed. */
+  async close(timeoutMs = 5e3) {
+    this._closed = true;
+    await this.flush(timeoutMs);
+    if (this._flushTimer !== null) {
+      clearInterval(this._flushTimer);
+      this._flushTimer = null;
+    }
+  }
+  async _drainOnce() {
+    if (this._draining) return;
+    this._draining = true;
+    try {
+      const now = Date.now();
+      while (this._queue.length > 0) {
+        const head = this._queue[0];
+        if (head.nextRetryAt > now) break;
+        this._queue.shift();
+        let outcome;
+        try {
+          outcome = await this._post(head);
+        } catch (err) {
+          outcome = { status: 0 };
+        }
+        const requeued = this._handleOutcome(head, outcome);
+        if (requeued !== null) {
+          this._queue.unshift(requeued);
+          break;
+        }
+      }
+    } finally {
+      this._draining = false;
+    }
+  }
+  _handleOutcome(item, outcome) {
+    if (outcome.status >= 200 && outcome.status < 300) return null;
+    if (outcome.status >= 400 && outcome.status < 500 && outcome.status !== 429) {
+      console.warn(`[smplkit.audit] permanent failure status=${outcome.status}; event dropped`);
+      return null;
+    }
+    item.attempts += 1;
+    if (item.attempts >= MAX_ATTEMPTS_PER_ITEM) {
+      console.warn(
+        `[smplkit.audit] gave up after ${item.attempts} attempts (last_status=${outcome.status})`
+      );
+      return null;
+    }
+    const backoff = Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** (item.attempts - 1));
+    const jitter = Math.random() * backoff * 0.25;
+    item.nextRetryAt = Date.now() + backoff + jitter;
+    return item;
+  }
+};
+
+// src/audit/client.ts
+var JSONAPI_HEADERS = {
+  "Content-Type": "application/vnd.api+json",
+  Accept: "application/vnd.api+json"
+};
+function _attributesFromInput(input) {
+  const attrs = {
+    action: input.action,
+    resource_type: input.resourceType,
+    resource_id: input.resourceId
+  };
+  if (input.occurredAt !== void 0) {
+    const ts = input.occurredAt instanceof Date ? input.occurredAt.toISOString() : input.occurredAt;
+    attrs.occurred_at = ts;
+  }
+  if (input.snapshot !== void 0) attrs.snapshot = input.snapshot;
+  if (input.data !== void 0) attrs.data = input.data;
+  return attrs;
+}
+function _eventFromResource(resource) {
+  const attrs = resource.attributes;
+  return {
+    id: resource.id,
+    action: String(attrs.action ?? ""),
+    resourceType: String(attrs.resource_type ?? ""),
+    resourceId: String(attrs.resource_id ?? ""),
+    occurredAt: String(attrs.occurred_at ?? ""),
+    createdAt: String(attrs.created_at ?? ""),
+    actorType: String(attrs.actor_type ?? ""),
+    actorId: attrs.actor_id ?? null,
+    actorLabel: String(attrs.actor_label ?? ""),
+    snapshot: attrs.snapshot ?? null,
+    data: attrs.data ?? {},
+    idempotencyKey: String(attrs.idempotency_key ?? "")
+  };
+}
+var EventsClient = class {
+  _apiKey;
+  _baseUrl;
+  _timeoutMs;
+  _buffer;
+  /** @internal */
+  _fetch = fetch;
+  constructor(opts) {
+    this._apiKey = opts.apiKey;
+    this._baseUrl = opts.baseUrl.replace(/\/$/, "");
+    this._timeoutMs = opts.timeoutMs ?? 1e4;
+    this._buffer = new AuditEventBuffer({
+      post: async (item) => {
+        try {
+          const headers = {
+            ...JSONAPI_HEADERS,
+            Authorization: `Bearer ${this._apiKey}`
+          };
+          if (item.idempotencyKey !== null) headers["Idempotency-Key"] = item.idempotencyKey;
+          const ctrl = new AbortController();
+          const t = setTimeout(() => ctrl.abort(), this._timeoutMs);
+          try {
+            const resp = await this._fetch(`${this._baseUrl}/api/v1/events`, {
+              method: "POST",
+              headers,
+              body: JSON.stringify(item.body),
+              signal: ctrl.signal
+            });
+            return { status: resp.status };
+          } finally {
+            clearTimeout(t);
+          }
+        } catch {
+          return { status: 0 };
+        }
+      }
+    });
+  }
+  /**
+   * Enqueue an audit event for asynchronous delivery.
+   * Returns immediately. The actual POST happens on the buffer worker.
+   *
+   * Customers may not emit `smpl.*` resource types — the server will
+   * reject those with a 403 (the buffer logs and drops permanent
+   * failures, so a misuse will silently disappear from the queue).
+   */
+  create(input) {
+    const body = {
+      data: { type: "event", attributes: _attributesFromInput(input) }
+    };
+    this._buffer.enqueue(body, input.idempotencyKey ?? null);
+  }
+  async list(params = {}) {
+    const qs = new URLSearchParams();
+    if (params.action !== void 0) qs.set("filter[action]", params.action);
+    if (params.resourceType !== void 0) qs.set("filter[resource_type]", params.resourceType);
+    if (params.resourceId !== void 0) qs.set("filter[resource_id]", params.resourceId);
+    if (params.actorType !== void 0) qs.set("filter[actor_type]", params.actorType);
+    if (params.actorId !== void 0) qs.set("filter[actor_id]", params.actorId);
+    if (params.occurredAtRange !== void 0) qs.set("filter[occurred_at]", params.occurredAtRange);
+    if (params.pageSize !== void 0) qs.set("page[size]", String(params.pageSize));
+    if (params.pageAfter !== void 0) qs.set("page[after]", params.pageAfter);
+    const resp = await this._fetch(`${this._baseUrl}/api/v1/events?${qs.toString()}`, {
+      headers: {
+        Authorization: `Bearer ${this._apiKey}`,
+        Accept: "application/vnd.api+json"
+      }
+    });
+    if (!resp.ok) {
+      throw new Error(`audit list failed: ${resp.status} ${resp.statusText}`);
+    }
+    const body = await resp.json();
+    const events = (body.data ?? []).map(_eventFromResource);
+    let nextCursor = null;
+    const nextLink = body.links?.next;
+    if (typeof nextLink === "string" && nextLink.includes("page[after]=")) {
+      nextCursor = nextLink.split("page[after]=")[1];
+    }
+    return { events, nextCursor };
+  }
+  async get(eventId) {
+    const resp = await this._fetch(`${this._baseUrl}/api/v1/events/${eventId}`, {
+      headers: {
+        Authorization: `Bearer ${this._apiKey}`,
+        Accept: "application/vnd.api+json"
+      }
+    });
+    if (!resp.ok) {
+      throw new Error(`audit get failed: ${resp.status} ${resp.statusText}`);
+    }
+    const body = await resp.json();
+    return _eventFromResource(body.data);
+  }
+  /** Block until the in-memory buffer is drained or `timeoutMs` elapses. */
+  async flush(timeoutMs = 5e3) {
+    await this._buffer.flush(timeoutMs);
+  }
+  /** @internal */
+  async _close() {
+    await this._buffer.close();
+  }
+};
+var AuditClient = class {
+  events;
+  constructor(opts) {
+    this.events = new EventsClient(opts);
+  }
+  /** @internal */
+  async _close() {
+    await this.events._close();
+  }
+};
+
 // src/config/client.ts
 var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
 
@@ -21957,6 +22216,8 @@ var SmplClient = class {
   flags;
   /** Client for logging management and runtime. */
   logging;
+  /** Client for the audit service — fire-and-forget event recording (ADR-047). */
+  audit;
   /**
    * Standalone management/CRUD entry point — mirrors Python's
    * `client.manage`. Construction is side-effect-free; safe to use even
@@ -21987,6 +22248,7 @@ var SmplClient = class {
     const configBaseUrl = serviceUrl(cfg.scheme, "config", cfg.baseDomain);
     const flagsBaseUrl = serviceUrl(cfg.scheme, "flags", cfg.baseDomain);
     const loggingBaseUrl = serviceUrl(cfg.scheme, "logging", cfg.baseDomain);
+    const auditBaseUrl = serviceUrl(cfg.scheme, "audit", cfg.baseDomain);
     this._appBaseUrl = appBaseUrl;
     const maskedKey = cfg.apiKey.length > 14 ? cfg.apiKey.slice(0, 10) + "..." + cfg.apiKey.slice(-4) : cfg.apiKey.slice(0, Math.min(4, cfg.apiKey.length)) + "...";
     debug(
@@ -22029,6 +22291,11 @@ var SmplClient = class {
       this._timeout,
       loggingBaseUrl
     );
+    this.audit = new AuditClient({
+      apiKey: cfg.apiKey,
+      baseUrl: auditBaseUrl,
+      timeoutMs: this._timeout
+    });
     this.config._getSharedWs = () => this._ensureWs();
     this.flags._parent = this;
     this.config._parent = this;
@@ -22108,6 +22375,7 @@ var SmplClient = class {
     }
     this.flags._close();
     this.logging._close();
+    void this.audit._close();
     if (this._wsManager !== null) {
       this._wsManager.stop();
       this._wsManager = null;
@@ -22342,6 +22610,7 @@ var PinoAdapter = class {
 0 && (module.exports = {
   AccountSettings,
   AccountSettingsClient,
+  AuditClient,
   BooleanFlag,
   Color,
   Config,