@lib-acr/core 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Application Control Room
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @lib-acr/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared telemetry client used by every ACR SDK: batching, retry with exponential backoff and jitter, a bounded buffer, sampling, offline buffering, redaction and the ingestion protocol.
+
+## Install
+
+```bash
+npm install @lib-acr/core
+```
+
+## Quick start
+
+```ts
+import { AcrClient } from '@lib-acr/core';
+
+const acr = new AcrClient({
+  apiKey: process.env.ACR_API_KEY!,        // acr_live_… or acr_test_…
+  apiSecret: process.env.ACR_API_SECRET,   // server only
+  endpoint: 'https://acr.example.com/v1',
+});
+
+acr.trackEvent('checkout_started', { cartSize: 3 }, { userId: 'user_42' });
+acr.log('info', 'order created', { orderId: 'o-1' });
+acr.captureError(new Error('payment declined'), { handled: true });
+await acr.flush();          // or await acr.shutdown(2000) before the process exits
+```
+
+## Notes
+
+Options: `flushIntervalMs`, `maxBatchSize` (1–500), `maxBufferSize`, `maxRetries`, `retryBaseMs`, `requestTimeoutMs`, `sampleRate` (events and logs only), `minLogLevel` (`debug` by default; lower logs are dropped before buffering), `enabled`, `isOnline`, `onError`, `remoteControl` (default true), `configPollIntervalMs` (default 60 000). Invalid options throw at construction.
+
+- **Sampling** is per session: items with a session id are kept or skipped as a whole session
+  (`fnv1a32('sample:' + sessionId) % 10000 < sampleRate * 10000`); items without one are sampled individually.
+  Errors and heartbeats are never sampled.
+- **Enable state:** `setEnabled(false)` stops collection and the background flush timer; `setEnabled(true)` starts
+  the timer again.
+- **Offline:** when the device goes offline during a flush, every undelivered item of the batch goes back into the
+  buffer in order. `stats()` reports `queued`, `sent`, `rejected`, `dropped`, `bufferOverflow`, `requeued`,
+  `sampledOut` and `belowMinLevel`.
+- **Rate limits:** a 429 waits for the `Retry-After` header, or `retryAfterSeconds` from the JSON error body.
+- **Free-text redaction:** log messages, error messages and stack traces have e-mail addresses, `Bearer`/`Basic`
+  credentials, JWTs, `acr_secret_…` values and `token=`/`password=` pairs masked before buffering (`redactString`).
+- `sendAllNow()` starts one request per kind at once, without retries (used on page hide); `clearQueue()` discards
+  the buffer.
+
+## Remote control
+
+Unless `remoteControl: false` is set, the client polls `GET {endpoint}/sdk/config` with the same key headers as
+ingestion and `If-None-Match: "<revision>"` (a `304` keeps the current snapshot). It polls at start-up and every
+`configPollIntervalMs` (default 60 000, at least 15 000). The server can ask for a longer interval with
+`pollAfterSeconds`, and while the kill switch is on the client polls every 10 minutes. On failure it keeps the last
+good snapshot and retries with backoff; the first failure in a row is reported to `onError` as `CONTROL_FETCH_FAILED`.
+Timers are unref'd, and `shutdown()` stops polling.
+
+- **Kill switch:** `sdk.enabled: false` stops collection and flushing (buffered items wait) until it is true again.
+  It is separate from `setEnabled()`: enabling locally does not override it.
+- `sdk.sampleRate` and `sdk.logLevel` override `sampleRate` and `minLogLevel` while the snapshot sets them.
+
+```ts
+const state = acr.getControlState();      // { ready, revision, sdkEnabled, maintenance, announcement, release, flags, … }
+const off = acr.onControlChange((s) => render(s));
+await acr.refreshControl();               // poll now
+```
+
+`getControlState()` returns the same frozen object until something changes (new revision, `identify()`, an
+announcement window opening or closing), so it works directly with `useSyncExternalStore`. `maintenance.active` is
+false for subjects in `allowUserIds`. `release.updateAvailable` and `release.belowMinimum` compare `appVersion`
+(semver) with `latestVersion` and `minimumVersion`; versions that are not valid semver never prompt.
+
+Building blocks for other SDKs and frameworks: `parseSnapshot`, `planCommands`, `evaluateFlag`, `compareSemver`,
+`deriveControlState`, `maintenanceResponse` and `isMaintenanceExemptPath`.
+
+## Feature flags
+
+```ts
+acr.flag('new-checkout', false);                       // current subject: userId if identified, else anonymousId
+acr.flag('new-checkout', false, { userId: 'user_42' }); // servers: evaluate for the request's user
+acr.flags();                                            // every flag, evaluated for the current subject
+```
+
+Flags are evaluated locally from the snapshot; there is no request per flag. A missing or disabled flag returns the
+fallback. A subject in `allowUserIds` gets `value`. Otherwise `FNV-1a-32(flagKey + ":" + subject) % 100 < rollout`
+gets `value` and everyone else gets the flag's `default`. Without a subject (a server call with no user) only a
+100 % rollout serves `value`. When the served value has a different type from the fallback, the fallback is returned.
+The vectors in `packages/conformance/fixtures` pin the algorithm for every language.
+
+## Wire protocol
+
+Every SDK sends the same protocol: `POST {endpoint}/ingest/{events|logs|errors|heartbeat}` with the `X-ACR-Api-Key`
+header (and `X-ACR-Secret-Key` for server keys). The credential securely determines the app and its single
+environment; the body is `{ schemaVersion: 1, sdk, items[1..500] }`.
+Each item has a client `id`, which lets the server drop duplicates when a batch is retried.
+
+Retries use exponential backoff with jitter for network errors, 429 and 5xx responses. Other 4xx responses are not retried.
+Telemetry is buffered in a bounded in-memory queue. When it is full, the oldest items are dropped and counted in `stats()`.
+SDK code never throws into the host application.
+
+Metrics (`increment`, `gauge`, `histogram`) and traces are not yet available.

package/dist/cjs/backoff.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backoffMs = backoffMs;
+/** Exponential backoff with equal jitter: half fixed, half random. Capped at 30 s. */
+function backoffMs(attempt, baseMs) {
+    const exp = Math.min(30000, baseMs * 2 ** attempt);
+    return exp / 2 + Math.random() * (exp / 2);
+}
+//# sourceMappingURL=backoff.js.map

package/dist/cjs/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/backoff.ts"],"names":[],"mappings":";;AACA,8BAGC;AAJD,sFAAsF;AACtF,SAAgB,SAAS,CAAC,OAAe,EAAE,MAAc;IACvD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAM,EAAE,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;IACpD,OAAO,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC"}

package/dist/cjs/buffer.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BoundedBuffer = void 0;
+/**
+ * Bounded FIFO. When full, the oldest entries are dropped so the newest telemetry survives and memory stays flat.
+ * Dropped entries are counted, never thrown.
+ */
+class BoundedBuffer {
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+        this.items = [];
+        this.droppedCount = 0;
+    }
+    get size() {
+        return this.items.length;
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    /** Adds one entry, dropping the oldest when full. */
+    push(item) {
+        if (this.items.length >= this.maxSize) {
+            this.items.shift();
+            this.droppedCount += 1;
+        }
+        this.items.push(item);
+    }
+    /** Removes up to `max` entries from the front, in order. */
+    take(max) {
+        return this.items.splice(0, Math.max(0, max));
+    }
+    /** Puts entries back at the front (after a failed send). Keeps the bound by dropping the newest overflow. */
+    requeue(items) {
+        this.items = [...items, ...this.items];
+        if (this.items.length > this.maxSize) {
+            const overflow = this.items.length - this.maxSize;
+            this.items.splice(this.maxSize, overflow);
+            this.droppedCount += overflow;
+        }
+    }
+    /** Copy of the current entries, oldest first. The buffer is not changed. */
+    toArray() {
+        return [...this.items];
+    }
+    clear() {
+        this.items = [];
+    }
+}
+exports.BoundedBuffer = BoundedBuffer;
+//# sourceMappingURL=buffer.js.map

package/dist/cjs/buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer.js","sourceRoot":"","sources":["../../src/buffer.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,aAAa;IAIxB,YAA6B,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;QAHpC,UAAK,GAAQ,EAAE,CAAC;QAChB,iBAAY,GAAG,CAAC,CAAC;IAEsB,CAAC;IAEhD,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC,IAAO;QACV,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,4DAA4D;IAC5D,IAAI,CAAC,GAAW;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,6GAA6G;IAC7G,OAAO,CAAC,KAAU;QAChB,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC;YAClD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAC1C,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC;QAChC,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;CACF;AA9CD,sCA8CC"}